Files
agent-lib/docs/proposals/client-labels.md
T

165 lines
6.3 KiB
Markdown
Raw Normal View History

# 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.
```json
{
"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: `foo` covers the skill `foo` and the command `foo` alike. 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); `version` is
required.
## Client side: `labels` in the client config
```json
{
"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 supplied `repo_url`. User-level and env
> configs cannot set or override `labels` while an admin value exists.
> Without an admin value, `labels` from 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
1. Build the inventory as today.
2. Read `agent-lib.labels.json` from 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` of labeled clients, not fatal and no toast (the curator-side `validate` is the
hard gate).
3. Drop items whose labels do not intersect the client labels before
hashing/planning (`internal/client/sync.go`, loop over
`inv.Deployable()`).
4. 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 (`--force` removes). 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:
```json
"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.