1 Commits
Author SHA1 Message Date
Sascha König 39952ceb02 docs: propose client labels for per-client content selection
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.
2026-11-14 10:35:48 +01:00
2 changed files with 160 additions and 0 deletions

No files matched your search

+1
View File
@@ -1,3 +1,4 @@
{"_type":"issue","id":"agent_lib-fh4","title":"Client labels: deliver items only to clients with a matching label","description":"Design: docs/proposals/client-labels.md (proposed 14.11.2026).\n\nOptional repo file agent-lib.labels.json ({version:1, labels:{label:[item names]}}); unlabeled items go to everyone. Client config gains 'labels'; absent = no filtering, [] = only unlabeled. Admin default config's labels win over user/env config. Invalid labels file aborts sync before any disk change. Filter before planning (internal/client/sync.go loop over inv.Deployable()); deselected items reuse the upstream-deleted path with reason 'not selected for this client's labels'. status --json reports labels/source/filtered; validate checks the file (names resolve incl. MCP). Revises README non-goal 'client-side selection or profiles'.\n\nConsumer: az-agent-defaults (agent-lib.labels.json already prepared) + az-fleet agent_lib role.","acceptance_criteria":"Tests per proposal section 'Tests' green; README documents file format, config field, admin precedence; release tagged; second sync with labels is a byte-level no-op.","status":"open","priority":2,"issue_type":"feature","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-14T09:11:57Z","created_by":"m3ta-chiron","updated_at":"2026-11-14T09:11:57Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"agent-lib-u5t","title":"vendor rename: Vendor-Skills nachträglich umbenennen","description":"Kuratoren sollen vendored Items nachträglich (nicht nur bei vendor add) benutzerfreundlich umbenennen können. Neuer Befehl vendor rename \u003csource\u003e up=new / --reset; umbenannte Skills bekommen den name: im SKILL.md-Frontmatter angepasst (OpenCode verlangt name == Ordnername).","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"m3ta-chiron@agentmail.to","created_at":"2026-11-05T07:43:31Z","created_by":"m3ta-chiron","updated_at":"2026-11-05T07:45:14Z","started_at":"2026-11-05T07:43:50Z","closed_at":"2026-11-05T07:45:14Z","close_reason":"vendor rename implemented with SKILL.md name rewrite, tests + README","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"agent-lib-4wx.11","title":"Deliver end-to-end documentation and release gate","description":"Finish the MVP by documenting the full workflow and proving it through an offline end-to-end acceptance path. The slice should provide README content, quickstart, CLI reference, Home Manager examples, security/trust notes, troubleshooting, and a release gate that demonstrates init, Source add, inspect, snippet, Home Manager eval/render, target Manifests, and a green offline check.","acceptance_criteria":"- Documentation covers installation, quickstart, CLI reference, Home Manager configuration, Lockfile behavior, discovery conventions, security/trust model, troubleshooting, MVP scope, and non-goals\n- An offline end-to-end fixture workflow demonstrates initialization, Source discovery, selection, Pi and Opencode Rendered output, target Manifests, and no unmanaged overwrites\n- nix flake check is green without external network access and verifies the MVP acceptance criteria","notes":"E2E fixture check green. All steps verified: init creates lockfile, discover finds all items, lockfile has rev/narHash/HM-compatible schema, inspect/snippet/validate commands work, managed-file protection present. nix flake check passes.","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:50:02Z","created_by":"m3tam3re","updated_at":"2026-05-28T08:13:15Z","started_at":"2026-05-28T07:46:50Z","closed_at":"2026-05-28T08:13:15Z","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:50:01Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.1","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.10","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.2","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.4","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.6","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:50:02Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.11","depends_on_id":"agent-lib-4wx.9","type":"blocks","created_at":"2026-05-27T19:50:03Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":10,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"agent-lib-4wx.10","title":"Complete CLI operational workflows and snippets","description":"Complete the day-to-day CLI workflow around existing Sources, Profiles, and Targets. The slice should make update/review/switch workflows practical with added/removed Item reports, offline and fetch validation modes, minimal and full Nix snippets, JSON output, non-interactive defaults, and an optional interactive entry point without automatic Nix edits.","acceptance_criteria":"- source update and source update --all report added and removed Items without changing Home Manager selection\n- validate runs offline by default, validate --fetch performs explicit reachability checks, and list/inspect/validate support stable JSON output\n- snippet emits both minimal Profile include snippets and full example configuration, while the CLI remains non-interactive by default and never edits Nix files","status":"closed","priority":2,"issue_type":"feature","assignee":"m3ta-chiron","owner":"p@m3ta.dev","created_at":"2026-05-27T17:49:57Z","created_by":"m3tam3re","updated_at":"2026-05-28T07:46:28Z","started_at":"2026-05-28T07:39:36Z","closed_at":"2026-05-28T07:46:28Z","close_reason":"Closed","labels":["ready-for-agent"],"dependencies":[{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx","type":"parent-child","created_at":"2026-05-27T19:49:56Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.3","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.5","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.7","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"},{"issue_id":"agent-lib-4wx.10","depends_on_id":"agent-lib-4wx.8","type":"blocks","created_at":"2026-05-27T19:49:57Z","created_by":"m3tam3re","metadata":"{}"}],"dependency_count":4,"dependent_count":1,"comment_count":0}
+159
View File
@@ -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.