feat: client labels proposal
This commit is contained in:
1 parent
d6821c6d7c
commit
bb7e209e75
2 files changed
+160
No files matched your search
@@ -0,0 +1,159 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user