Files
agent-lib/README.md
T
m3ta-chironandClaude Opus 5.5 59735c3b24 feat(client): deliver items only to clients with a matching label
- Add internal/labels: parse and validate the optional work-repo file
  agent-lib.labels.json (version 1; unlabeled items go to every client;
  names match across types)
- Add "labels" to the client config: absent = no filtering, [] = unlabeled
  items only; labels from the admin default config are pinned and cannot be
  overridden by user, env or flag configs; a broken admin config aborts
- Filter in prepare() before planning; deselected items follow the
  upstream-deletion rules (unmodified removed, modified kept + warn,
  --force removes) with reason "not selected for this client's labels"
- Abort sync before any change when the labels file does not validate;
  names that match no item only warn on the client
- Report the active selection in sync output and status (--json: labels
  object with client, source, labels_file, not_selected, unknown_names)
- validate checks the labels file, including that every name resolves to
  an own, vendored or MCP item
- Document in README ("Client labels"), fleet handoff and the proposal;
  revise the "client-side selection" non-goal
- Tests: labels parser, config precedence, planner deselection, e2e for
  filter/remove/keep-modified/abort/unknown names, validate

Refs: agent_lib-fh4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 10:36:07 +01:00

414 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# agent-lib
One Go binary, two roles: **curator** and **client**.
- **Curator side** — `agent-lib vendor …` pulls external git repositories into a
plain work repository under `external/<source>/<type>/`, pinned by revision,
with per-source selection and collision-safe naming. Publication is nothing
more than `git commit && git push`.
- **Client side** — `agent-lib sync` pulls the work repository and deploys its
content into the OpenCode runtime paths. Local modifications win over
company updates, self-created items are never touched, and Windows toast
notifications tell employees when their edits blocked an update.
No Nix, no Python, no git subprocess at runtime — a single static binary for
windows/amd64, linux/amd64, linux/arm64, darwin/amd64 and darwin/arm64.
## Installation
Download the binary for your platform from the
[GitHub releases](https://github.com/m3tam3re/agent-lib/releases), verify the
checksum, and put it on your `PATH`:
```sh
curl -fsSLO https://github.com/m3tam3re/agent-lib/releases/latest/download/agent-lib_linux_amd64.tar.gz
tar xzf agent-lib_linux_amd64.tar.gz
sha256sum -c checksums.txt --ignore-missing
install -m 0755 agent-lib /usr/local/bin/
agent-lib version
```
Fleet-managed machines receive the binary via a pinned rollout — see
[docs/fleet-handoff.md](docs/fleet-handoff.md). There is no self-update.
From source: `go build .` (version is baked in via ldflags; `make build` uses
the git description).
## Curator guide
The work repository layout:
```
skills/<id>/SKILL.md own skills (folder artifacts)
commands/<id>.md own OpenCode commands
agents/<id>.md own OpenCode agents
mcp/<id>.yaml own MCP fragments (never deployed by the binary)
external/<source>/<type>/ vendored content, mirrors the same four types
agent-lib.lock.json lockfile v2 — pins every source
agent-lib.labels.json optional — restricts items to labeled clients
```
This layout is **exactly** what OpenCode natively consumes — agent-lib is
deliberately on the opencode standard, no conversion layer:
| Type | Canonical form |
|---|---|
| skills | `<id>/SKILL.md` folder (any depth, category nesting ok) |
| commands | flat `commands/<id>.md` |
| agents | flat `agents/<id>.md` |
| mcp | flat `mcp/<id>.yaml` (inventoried, never deployed) |
**Migrating from folder-style agent repos** (e.g. `agents/<id>/AGENT.md`
layouts): flatten `agents/<id>/AGENT.md` → `agents/<id>.md`, and move
documentation and manifests (`SCHEMA.md`, `agents.json`, `README.md`) out of
the typed directories. No folder support for agents/commands is planned —
adapting the source repo to the standard beats shipping a renderer.
### Vendoring a source
```sh
agent-lib vendor add superpowers https://github.com/obra/superpowers/tree/main/skills
```
Pasted GitHub/GitLab web-tree URLs are normalized automatically. A URL
pointing directly at a type directory (e.g. `…/tree/main/skills`) selects
that directory as the skills root. `--ref <branch-or-tag>` pins a ref; the
resolved revision is pinned in the lockfile. Discovery understands the four
standard directories (`skills/`, `commands/`, `agents/`, `mcp/`); skills are
folders containing `SKILL.md` — found at **any depth**, so category-nested
layouts (`skills/engineering/tdd/SKILL.md`) work too, with the folder's base
name as the skill id — commands and agents are flat `.md` files, MCP
fragments are `.yaml`. A flat `.md` under `commands/` or `agents/` whose
frontmatter contains none of the definition keys (`name`, `description`,
`mode`, `agent`, `model`, `argument-hint`, `temperature`, `permission`) is
treated as dropped documentation: skipped with a recorded warning, never an
inventory entry. Everything is read-only scanned — upstream code is never
executed.
### Selection rules
- Default: vendor **everything** (`mode: all`).
- `--include a,b,c` switches the source to **include mode**: only those ids
arrive, and new upstream items do **not** arrive automatically.
- `--exclude a,b,c` keeps **all mode** minus those ids — for taking the
majority of a source while dropping a few items.
- `--types skills,commands` (**allow-list**) and `--exclude-types agents,mcp`
(**deny-list**) filter whole content types. The filter is stored as
`exclude_types` in the lockfile and **survives updates**: new upstream items
of an excluded type never enter the work repository. `--types` covering all
four types normalizes to no filter; excluding all four fails at the
zero-selection guard.
- Hard errors, enforced by `vendor add`, `vendor update`, `vendor select`
and `validate`:
- `all` combined with an include list → error
- an exclude list without `all` → error (not supported in v2 selections)
- an include or exclude entry that no longer exists upstream → error naming the item
- `--include` combined with `--exclude` → error
- `--types` combined with `--exclude-types` → error
- unknown type names → error listing `skills, commands, agents, mcp`
- an include entry belonging to a type the type filter excludes → error
(`vendor select` changes selections later — see
[Changing your selection later](#changing-your-selection-later) below.)
### Changing your selection later
`vendor select` manages the selection after the initial add — without ever
advancing the pinned revision (that is `vendor update`'s job):
```sh
agent-lib vendor select superpowers --add tdd,brainstorm # include mode: grow
agent-lib vendor select superpowers --remove review,debug # include mode: shrink
agent-lib vendor select superpowers --remove review # all mode: move to exclude
agent-lib vendor select superpowers --types skills # replace the type filter
agent-lib vendor select superpowers --mode all # reset: take everything again
```
- **include mode**: `--add` appends ids (validated against the pinned
upstream — typos abort with the list of available ids), `--remove` drops
ids and deletes their folders from `external/`.
- **all mode**: `--remove` moves ids onto the exclude list (lockfile v2
supports exclude in all mode) and deletes their folders; `--add` is a hard
error — everything is already selected.
- `--types` / `--exclude-types` **replace** the content-type filter
(same semantics as on `vendor add`); when neither flag is passed, the
stored filter stays as-is.
- `--mode all` clears include/exclude **and the type filter** and
re-materializes the full pinned upstream, reporting what appeared.
Every select re-runs the collision checks and honors the lockfile rename map
— you can hand-add a rename for a not-yet-selected item, then `--add` it
under its deployed name. Failed selects mutate nothing.
### Collisions and renames
Every item deploys into a flat per-type namespace. If a vendored id collides
with one of your own items (or with another source's item), the operation
aborts with a hard error naming both parties — before anything is written.
Resolve it with an explicit, reviewable rename:
```sh
agent-lib vendor add superpowers "$URL" --rename review=superpowers-review
```
The on-disk folder always carries exactly the deployed name. Renaming onto
another collision is an error.
### Friendlier names for your users
Renames are not only for collisions — use them to give vendored items names
your colleagues recognize. `vendor rename` changes them at any time, without
moving the pinned revision or the selection:
```sh
agent-lib vendor rename superpowers brainstorming=ideen-sammeln tdd=test-first
agent-lib vendor rename superpowers --reset tdd # back to the upstream id
agent-lib vendor rename superpowers # list current renames
```
- The rename map lives in the lockfile and survives `vendor update` and
`vendor select`.
- A renamed skill gets the `name:` in its `SKILL.md` frontmatter rewritten to
the new folder name (OpenCode requires both to match and shows that name).
Commands and agents are renamed via their file name only.
- Skill names must be 1–64 lowercase letters, digits and single hyphens
(`code-review`, not `Code Review`). No name of any type may contain path
separators or start with a dot.
- Renaming an id that is not selected yet is allowed; it applies once the
item is added via `vendor select --add`.
- On the next `agent-lib sync`, clients receive the item under the new name;
the old name is removed from their machine like any upstream deletion
(locally modified copies stay, as usual).
### The maintenance loop
```sh
agent-lib vendor diff superpowers # read-only preview: new/changed/deleted vs selection
agent-lib vendor update superpowers # fetch latest of the pinned ref, rewrite, report
agent-lib vendor update --all # every source, reported per source
agent-lib vendor remove superpowers # delete external area + lockfile entry
```
In `all` mode new upstream items arrive automatically (and appear in the
update report); in include mode they deliberately do not — `vendor diff`
surfaces them as `available upstream, not selected`. Every update re-runs the
collision checks and honors the rename map.
### Auditing
```sh
agent-lib validate # offline: rules + tree/lockfile consistency
agent-lib vendor list # sources with pin, mode, item counts
agent-lib vendor inspect <name> # full inventory with metadata + warnings
```
All three accept `--json`. The lockfile is deterministic JSON (sorted keys,
fixed indentation) — identical reruns produce identical bytes, so git diffs
stay clean.
## Client guide
Employees run two commands:
```sh
agent-lib sync # pull the work repository and deploy
agent-lib status # report local state; exit 1 when updates are blocked
```
Both accept `--repo <url>` / `--ref <ref>` for config-free personal use —
see [Configuration](#configuration) below.
Deployment mapping (OpenCode target):
| Type | Destination |
|---|---|
| skills | `~/.agents/skills/<id>/` (whole artifact folders) |
| commands | `~/.config/opencode/commands/<id>.md` |
| agents | `~/.config/opencode/agents/<id>.md` |
| mcp | **never deployed** — stays under fleet-controller merge |
### Sync semantics (three-state)
Sync plans before it mutates. For every item the planner compares the
repository, the local manifest and the on-disk content:
- new item → **deploy**
- managed & unmodified, upstream changed → **update**
- managed & locally modified → **skip + warn** — your version stays
- on disk but never deployed by us → **leave + warn** — self-created items are safe by construction
- upstream deleted & unmodified → **remove**
- upstream deleted & modified → **skip + warn** — your version stays
With `--force` the two skip cases turn into **update** and **remove** —
the repository version wins over local modifications. Unmanaged items
(leave + warn) are never touched, even with `--force`; neither are paths
occupied by items agent-lib never deployed.
Sync is idempotent (a second run is a byte-level no-op) and fails cleanly:
an unreachable repository never leaves a half-deployed machine. The default
branch is resolved from the remote's advertised `HEAD`, so a sync without
`--ref` always tracks the server's current default branch — even after the
cache has been re-fetched many times.
### Configuration
The repository to pull comes from the first source that provides one:
1. `--repo <url>` flag (works with **no config file at all**)
2. `--config <path>` flag
3. `AGENT_LIB_CONFIG` env
4. user-level config (personal machines)
5. admin-protected platform default (fleet rollout)
| Source | Linux / macOS | Windows |
|---|---|---|
| user-level config | `$XDG_CONFIG_HOME/agent-lib/config.json` (default `~/.config/agent-lib/config.json`) | `%AppData%\agent-lib\config.json` |
| admin default | `/etc/agent-lib/config.json` | `%ProgramData%\agent-lib\config.json` |
`--repo` overrides a `repo_url` from any discovered config; `--ref` narrows it
to a branch or tag. When no config exists anywhere, the error lists every
searched location, a minimal working example, and the `--repo` shortcut.
```json
{
"repo_url": "https://git.example.com/company/agent-content.git",
"ref": "main",
"token": "<read-only deploy token>",
"token_user": "oauth2"
}
```
The token is used for basic auth only. It never appears in the lockfile, the
manifest, logs or error messages. On `--repo` runs (or when the discovered
config carries no token) `AGENT_LIB_GIT_TOKEN` / `AGENT_LIB_GIT_USER` supply
credentials instead — env never overrides a configured token.
**Personal quickstart (no fleet, no config):**
```sh
agent-lib sync --repo https://github.com/you/your-agent-content.git
```
The work repository must be a committed git repository (sync pulls it
read-only via go-git; local uncommitted state is ignored).
### Client labels
Not every client needs every item. Restrict items to clients that carry a
matching label with an optional `agent-lib.labels.json` at the work
repository root:
```json
{
"version": 1,
"labels": {
"sales": ["crm-agent", "quote-writer"],
"finance": ["officecli-financial-model", "crm-agent"]
}
}
```
- **Unlabeled items go to every client.** Only restricted items appear in
the file; a new item needs no entry to reach everyone.
- Entries are deployed item names (after renames) and match across types —
one entry covers a skill and a command of the same name. MCP fragment
names are allowed too (fleet tooling can scope MCP from the same file;
the binary never deploys MCP).
- An item under several labels reaches clients with any of them.
- Labels match `^[a-z0-9][a-z0-9-]*$`; lists must be non-empty; unknown
keys and unknown versions are errors.
Clients opt in through `labels` in their config:
| `labels` | Delivered |
|---|---|
| absent | everything — no filtering (default, backward compatible) |
| `[]` | unlabeled items only |
| `["sales", "lead"]` | unlabeled items plus items labeled `sales` or `lead` |
**Admin-pinned:** when the admin default config exists and sets `labels`,
that value applies no matter which config supplied `repo_url` — a user-level
config, `AGENT_LIB_CONFIG` or `--config` can neither widen nor drop it. An
admin config that exists but cannot be parsed aborts the run.
Sync filters before planning. An item that is no longer selected follows
the upstream-deletion rules: unmodified copies are removed, locally modified
copies are kept with a warning (`--force` removes them); the reason reads
"not selected for this client's labels". A labels file that does not
validate **aborts the sync before any change** — it never falls back to
delivering everything. Names that match no item only warn on the client;
`agent-lib validate` treats them as errors on the curator side.
`sync` and `status` print the active selection
(`labels: sales (admin) — 12 item(s) not selected`); `status --json` adds a
`labels` object with `client`, `source`, `labels_file`, `not_selected` and
`unknown_names`.
Labels are a relevance filter, **not access control**: every client still
fetches the whole revision into its cache. Keep confidential material in a
separately authenticated repository.
### Notifications
On Windows, a toast fires when (and only when) a sync kept local
modifications or discovered unmanaged items — never for routine syncs. The
same warnings are appended to the sync log
(`~/.local/state/agent-lib/sync.log` on Linux, `%LocalAppData%\agent-lib`
on Windows) and surfaced by `status`. Linux/macOS notification is a no-op.
`status --json` is machine-readable: deployed revision, repository revision,
pending changes, skipped and unrecognized items, and a `problematic_drift`
flag that drives the non-zero exit code — suitable for headless drift checks.
## Security / trust model
- External sources are **untrusted**. Discovery and vendoring never execute
upstream code; only file contents are read.
- The shared read-only token limits blast radius; rotation is a single fleet
run (see the handoff doc).
- MCP fragments from vendored sources are **never activated** by the binary;
merging and vault substitution remain an explicit fleet-controller decision.
- Binary updates happen exclusively via pinned fleet rollouts — there is no
self-update path to abuse.
## Troubleshooting
| Symptom | Cause / fix |
|---|---|
| `error: … no client config found. Searched (in order): …` | No config anywhere. Create one where the error suggests, or skip it: `agent-lib sync --repo <url>`. |
| `error: … include entry "x" not found upstream` | Typo, or the item was renamed/removed upstream. Fix the lockfile include list, or re-add with a corrected `--include`. |
| `error: … collides with own skills "x"` | Deployed-name collision. Add `--rename <upstream>=<deployed>` (add) or fix the rename map (update). |
| `validate` reports tree/lockfile divergence | Someone edited `external/` by hand. Re-run `vendor update <source>` to restore the pinned state. |
| Skill didn't update, `skipped (local modifications kept): 1` | Working as designed — you edited the deployed item. Run `agent-lib sync --force` to overwrite local modifications with the repository version, or delete the local copy and re-sync. |
| `status` exits 1 | Local modifications block repository updates (or occupy names the repo needs). See `status` output for the item list. |
| Sync fails with clone/fetch error | Work repository unreachable, or token expired. Previous local state remains intact; fix config/network and re-run. |
| No toast on Windows | Toasts need an interactive user session — the scheduled task must run as the logged-in user, not SYSTEM. |
| Terminal window flashes on scheduled sync (Windows) | The task runs the console program `agent-lib.exe`. Point it at `agent-libw.exe sync` from the same zip: same commands, no window, no output. |
## Development
```sh
make build # build with version ldflags
make test # unit + black-box e2e (fully offline, local fixture git repos)
make lint # go vet + gofmt check
./scripts/e2e-acceptance.sh # full spec walk: 60+ assertions, offline
```
Release: `goreleaser release` on a tagged commit builds all five targets with
checksums and publishes to GitHub releases. Verify with
`goreleaser release --snapshot --clean` or a tagged `--skip=publish` dry run.
## Scope and non-goals (v2)
In scope: vendoring with selection/renames into any git work repository;
OpenCode-only deployment with three-state protection; toast notifications;
goreleaser/GitHub release pipeline.
Client-side selection is limited to label filtering (see Client labels) —
no per-client profiles, overrides or inheritance.
Not in scope: additional targets (Pi,
Hermes, Crush, Amp), MCP merge/vault (fleet-controller concern), binary
self-update, git submodule sources, migration tooling from the Python-era
lockfile.