- 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>
6.3 KiB
Proposal: client labels — deliver content to a subset of clients
Status: implemented on branch feat/client-labels (14.11.2026) — user docs in the README, section "Client labels"
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 on sync output and in
status, not fatal and no toast (the curator-sidevalidateis 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", "labels_file": true,
"not_selected": ["skills/officecli-financial-model"],
"unknown_names": []
}
The object is omitted when the client has no labels. source is admin
| user | env | flag. Human output prints one line:
labels: sales (admin) — 12 item(s) 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.