Add docs/proposals/client-labels.md: an optional agent-lib.labels.json in the work repository, a "labels" field in the client config (admin-pinned), filtering before planning with deselected items following the upstream-deletion rules, plus status and validate support. Tracked as beads issue agent_lib-fh4.
6.1 KiB
Proposal: client labels — deliver content to a subset of clients
Status: proposed (14.11.2026)
Problem
A work repository serves every client the same content. Organisations with teams want relevant content per team: finance needs finance skills, sales needs sales agents, and nobody benefits from all of it. A long skill list also hurts routing quality of small models.
Today the only way to split is one repository or one branch per team. Both force shared content to be maintained N times (merges, drift) and cannot serve a client that belongs to two teams — a client pulls exactly one ref.
Decision in one sentence
Content items may carry labels in the work repository; clients carry
labels in their config; sync delivers an item when it is unlabeled or
shares at least one label with the client.
agent-lib stays generic: it knows "label" and "item", never "department", "role" or any organisation's vocabulary. What a label means and who gets it is decided outside agent-lib (curator: which item has which label; fleet tooling: which client has which label).
This revises the v2 non-goal "client-side selection or profiles": labels are a selection, but no profiles — there is no per-label content, overrides or inheritance, only a filter over the one shared inventory.
Repository side: agent-lib.labels.json
Optional file in the work repository root, next to agent-lib.lock.json.
JSON keeps the binary free of a YAML dependency (frontmatter is hand-parsed
today) and matches the lockfile and client config.
{
"version": 1,
"labels": {
"sales": ["crm-agent", "quote-writer"],
"finance": ["officecli-financial-model", "invoice-check"],
"dev": ["grilling", "to-spec"]
}
}
Rules:
- Unlabeled = everyone. Only items that should be restricted appear in the file. Adding an item to the repository without touching the file delivers it to all clients — same as today.
- An item may appear under several labels (OR).
- Entries are deployed item names (after vendor renames), matched across
types:
foocovers the skillfooand the commandfooalike. Type- qualified entries are not needed until a real collision appears. - Label form
^[a-z0-9][a-z0-9-]*$; lists must be non-empty. - Names may also refer to MCP fragments. The binary never deploys MCP, but fleet tooling can read the same file to scope MCP servers — one source of truth for "who gets what".
- Unknown top-level keys are an error (typo protection);
versionis required.
Client side: labels in the client config
{
"repo_url": "https://git.example.com/company/agent-content.git",
"ref": "main",
"labels": ["sales", "leadership"]
}
labels |
Effect |
|---|---|
| field absent | no filtering — every item, as today (backward compatible) |
[] |
only unlabeled items |
["a","b"] |
unlabeled items plus items labeled a or b |
Client labels that no item uses are fine (no warning): a client may be labeled ahead of content.
Admin-pinned labels
Today the first config found wins as a whole, and the user-level config precedes the admin default. For labels that would let a user widen their own selection. Rule:
If the admin default config exists and contains
labels, that value applies — whichever config suppliedrepo_url. User-level and env configs cannot set or overridelabelswhile an admin value exists. Without an admin value,labelsfrom the chosen config applies (personal machines keep full control).
--labels a,b as a flag is deliberately not offered for sync; for testing
use --config with a file that has no admin counterpart, i.e. on a machine
without an admin default.
Labels are a relevance filter, not access control: the whole repository revision is still fetched into the local cache. Confidential content needs a separately authenticated repository.
Sync behaviour
- Build the inventory as today.
- Read
agent-lib.labels.jsonfrom the same revision.- Absent → no filtering.
- Invalid (parse error, bad label form, empty list, unknown key, unknown version) → sync aborts before any change with a clear error. Never fall back to "deliver everything".
- A name that matches no item → warning in sync log/status, not fatal
(the curator-side
validateis the hard gate).
- Drop items whose labels do not intersect the client labels before
hashing/planning (
internal/client/sync.go, loop overinv.Deployable()). - Planning is unchanged. A previously deployed item that is no longer
selected is handled exactly like an upstream deletion: unmodified →
remove; locally modified → skip + warn (
--forceremoves). The plan reason and toast text say "not selected for this client's labels" instead of "upstream deleted" so users understand why.
Status
status --json gains:
"labels": { "client": ["sales"], "source": "admin", "filtered": 12 }
source is admin | user | env | flag | none. Human output
prints one line: labels: sales (admin) — 12 items not selected.
Curator side
agent-lib validate checks agent-lib.labels.json when present:
schema/version, label form, non-empty lists, every name resolves to an
inventory item (own or external, any type including MCP). Errors are
fatal, so a broken file never reaches clients through CI.
No new curator command is required; the file is edited by hand. A later
agent-lib labels list (item → labels table) is a nice-to-have.
Tests
- planner/sync: absent field,
[], single/multi label, item under two labels, label removed from client → remove unmodified / keep modified,--force. - config: admin labels beat user labels; user labels apply without admin value; absent everywhere → no filtering.
- labels file: absent, invalid variants (abort, no disk change), unknown name (warning).
- validate: each error class.
- e2e: second run is a byte-level no-op with labels active.
Rollout
Additive and backward compatible: old clients ignore the file, new
clients without labels ignore the file. Fleet tooling adds the field
after pinning the release that understands it.