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.
160 lines
6.1 KiB
Markdown
160 lines
6.1 KiB
Markdown
# 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.
|
|
|
|
```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 in sync log/status, not fatal
|
|
(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", "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.
|