@passioncode-ai/fabric-agent-adapter 0.39.0 → 0.40.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -3,7 +3,7 @@ name: building-fabric-services
 description: >-
   Use when handing out or opening a Fabric service dashboard, building a local agent service on a
   macOS machine, making an ONLINE agent or dashboard (https origin, the remote placement) a
-  Fabric service, or letting a service answer a Project's board requests — «сделай агенту дашборд»,
+  Fabric service, or letting a service answer a Project's board requests: «сделай агенту дашборд»,
   «локальный сервис агента», «подключи агента к Fabric Dashboards», «отвечать на запросы с доски проекта»,
   "make this agent a local service", "make an online dashboard a Fabric service", "add the
   well-known endpoint", «расходы агента на модели». Covers fabric-service/0.1:
@@ -18,7 +18,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.39.0"
+  version: "0.40.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "c55f2d5a11c9a0197e958e87212fca7ae1154769"
@@ -29,7 +29,7 @@ metadata:
 A **service** is an agent that keeps running on the operator's computer: it holds
 state, answers other agents, and shows a dashboard. This skill makes one that is
 always alive, comes back after a restart, never runs twice, keeps its state through a
-reinstall, and appears in Fabric Dashboards by itself — the `fabric-service/0.1`
+reinstall, and appears in Fabric Dashboards by itself: the `fabric-service/0.1`
 extension of the Fabric Agent Contract (DEC-0015).
 
 Every rule below exists because a real service on this estate broke it. Treat them as
@@ -41,15 +41,15 @@ re-deriving a rule.
 Use it to create a service, to bring an existing local server under the protocol, or
 to review one. Do not use it for:
 
-- a script, a cron job or a one-shot CLI — nothing stays running, so there is nothing
+- a script, a cron job or a one-shot CLI: nothing stays running, so there is nothing
   to supervise; a launchd `StartInterval` job needs no descriptor;
 - a hosted product with no agent behind it. An online agent or dashboard that should appear in
-  Fabric IS in scope: it is the remote placement — read [Online services](#online-services--the-remote-placement);
-- the provider manifest and admission bundle — that is `adapting-projects-to-fabric`
+  Fabric IS in scope: it is the remote placement; read [Online services](#online-services-the-remote-placement);
+- the provider manifest and admission bundle: that is `adapting-projects-to-fabric`
   (a service that is also a provider does both);
 - the Fabric Dashboards app itself.
 
-## Step 0 — is it a service?
+## Step 0: is it a service?
 
 It is a service when at least one is true: other agents call it while the operator is
 away; it runs jobs longer than one request; it owns a store other tools read; the
@@ -65,7 +65,7 @@ Answer before writing code, and record the answers in the project README:
 | What it stores | the store, where it lives (Step 2, rule 5), and what survives uninstall |
 | What it tells the operator | the events worth a notification (Step 5) |
 
-## Step 1 — choose the surfaces
+## Step 1: choose the surfaces
 
 | Caller | Surface | Why |
 |---|---|---|
@@ -103,14 +103,14 @@ responder in its own process: [`scripts/fabric_hub.py`](scripts/fabric_hub.py) f
 every step and stops on `fenced`, `lease_expired` or `authority_changed` (Node: `fabric-hub.mjs`, `fabric-board.mjs`).
 The request body is data behind the service's own input gate. Read [the board reference](references/board.md).
 
-## Step 2 — the non-negotiables
+## Step 2: the non-negotiables
 
 1. **Loopback only.** Bind `127.0.0.1`. Refuse any `Host` other than
    `127.0.0.1:<port>`, `localhost:<port>`, `[::1]:<port>`; refuse a foreign `Origin` and
-   `Sec-Fetch-Site: cross-site` — on every path, the well-known one included.
+   `Sec-Fetch-Site: cross-site`, on every path, the well-known one included.
    *(A throwaway `python -m http.server` bound to every interface served a source tree to the local network.)*
 2. **One copy, locked before any side effect.** Take the exclusive lock on
-   `<data>/service.lock` first — before resuming jobs, starting a scheduler, migrating
+   `<data>/service.lock` first, before resuming jobs, starting a scheduler, migrating
    a store or even creating a token. Held → print one sentence naming the holder's pid
    and exit **75**. Binding the port is not a lock. Under launchd the kit backs off
    in-process first (up to 300 s), so a duplicate is a few starts an hour, not a
@@ -127,11 +127,11 @@ The request body is data behind the service's own input gate. Read [the board re
 5. **State outside code.** Data and config in `~/Library/Application Support/<id>/`,
    logs in `~/Library/Logs/<id>/`, cache in `~/Library/Caches/<id>/`; the service's own
    access token in a 0600 file it generates (principle 6). **Every provider credential the
-   service uses comes from Project Observatory, by name** — the plist starts the service
+   service uses comes from Project Observatory, by name**: the plist starts the service
    with `use_secret.py serve --consumer <label> <project> <NAME>[,<NAME>] -- <command>`, which
    reads the vault only and records the consumer so a rotation names it; never a copy of a
    key in a `.env`, a config file or the plist. Never inside the service's own code checkout or a release directory; a
-   repository that versions the data itself is a store and is fine — declare
+   repository that versions the data itself is a store and is fine; declare
    `source.repository` so the probe can tell them apart. *(Deleting a checkout left a
    plist launchd retried every 10 s, and the data went with it.)*
 6. **Tokens stay in files and headers.** Mode 0600, owner-checked, never a symlink;
@@ -139,25 +139,36 @@ The request body is data behind the service's own input gate. Read [the board re
    one-time login code, never the token.
 7. **`degraded` is always present.** An empty list asserts full health; `ready` with a
    non-empty list is a lie the kit corrects to `degraded`.
-8. **Atomic writes.** Temporary file, fsync, rename — for the store's side files, the
+8. **Atomic writes.** Temporary file, fsync, rename, for the store's side files, the
    descriptor and the token.
 
-## Step 3 — build it with the kit
-
-Copy the kit into the service (each is one self-contained file): Python
-[`scripts/fabric_service.py`](scripts/fabric_service.py), Node
-[`scripts/fabric-service.mjs`](scripts/fabric-service.mjs). Both share file formats, and
+## Step 3: build it with the kit
+
+Install the kit into the service with its manifest: `python3 scripts/fabric_kit.py install
+<service-dir> --module fabric_service --module fabric_interop` (Python: the service and its MCP
+surface, with every module they need; add `--module fabric_board` for a board responder, as
+the sample has) or `--lang node` with the same names in `-`;
+`fabric_kit.py status <service-dir>` says per file whether a copy is current, older or edited,
+and what is missing. The kit is layered modules behind the `fabric_service` /
+`fabric-service.mjs` facades, which keep every 0.39 import working; read
+[the kit modules reference](references/kit-modules.md) for the map, the dates API and
+installing more (`--module fabric_openrouter`). Both languages share file formats, and
 their locks exclude each other. The complete worked example is
-[`scripts/sample_service.py`](scripts/sample_service.py) — read it before writing a
+[`scripts/sample_service.py`](scripts/sample_service.py); read it before writing a
 handler.
 
+Calling out: [the connectors reference](references/connectors.md) (`fabric_http` with one
+deadline, safe retries and a size cap; `fabric_openrouter` with the agent's own key, a
+spend ceiling before every attempt, receipts and a fallback). A ready support agent on the
+kit: [`recipes/support-agent/`](recipes/support-agent/README.md).
+
 Startup order is the part that goes wrong; keep it exactly:
 
 ```python
 import fabric_service as fs
 
 dirs = fs.service_dirs("example-agent")
-lock = fs.hold_single_instance(dirs["data"])        # 1. lock — exits 75 if held (backs off first under launchd)
+lock = fs.hold_single_instance(dirs["data"])        # 1. lock: exits 75 if held (backs off first under launchd)
 token = fs.ensure_token(dirs["data"] / "service.token")  # 2. only now touch state
 log = fs.JsonlEventLog(dirs["data"] / "events.jsonl")    #    (or a view over your own log)
 codes = fs.LoginCodes(dirs["data"] / "auth")
@@ -172,12 +183,12 @@ On every request call `check_request(port, host, origin, sec_fetch_site)` and an
 
 | Route | Auth | Kit |
 |---|---|---|
-| `GET /.well-known/fabric-service` | none, guard still applies | `build_well_known(...)` — from memory, under 100 ms |
+| `GET /.well-known/fabric-service` | none, guard still applies | `build_well_known(...)`, from memory, under 100 ms |
 | `GET /fabric/v1/events?after=&limit=` | service token | `events_page(fetch, after, parse_limit(limit))` |
 | `POST /fabric/v1/login-code` | service token | `LoginCodes.issue()` |
 | `GET /fabric/v1/login?code=` | the code | `LoginCodes.redeem(code)` → `Set-Cookie: session_cookie_header(...)`, 302 to the dashboard |
 
-`SIGTERM` drains in-flight work, then exits — 10 s at most, inside `ExitTimeOut`
+`SIGTERM` drains in-flight work, then exits: 10 s at most, inside `ExitTimeOut`
 (`fs.Drain` / `new Drain()`: `with drain.work():` refuses new work once a stop began);
 interrupted work resumes on the next start. Log through `RotatingLog` (5 × 5 MB, 0600)
 and call `cap_stdout_log` once at start.
@@ -187,18 +198,18 @@ in Python; jobs live in `fabric_interop.JobStore(dirs["data"] / "jobs")`, create
 the lock like every other piece of state. Add `"mcp": {"path": "/mcp", "transport":
 "streamable-http", "capabilities": [...]}` to the well-known surfaces, and point the
 descriptor's `fabricManifest` at a manifest whose service key names this
-`<id>.<instance>` — `sample_service.py register` shows both.
+`<id>.<instance>`; `sample_service.py register` shows both.
 
-## Step 4 — install it
+## Step 4: install it
 
 The installer, not the service, owns the plist and the descriptor. Sequence:
 
-1. `write_descriptor(descriptor)` — refuses a port or `id.instance` another descriptor
-   claims. A preview or branch copy is a second **instance**, never a second id — and it is
+1. `write_descriptor(descriptor)`: refuses a port or `id.instance` another descriptor
+   claims. A preview or branch copy is a second **instance**, never a second id, and it is
    one more service the operator sees, probes and gets notified by. Verify a release with its
    own doctor or self-check before it replaces `default`; a temporary instance is uninstalled
    (`launchd_uninstall`, `remove_descriptor`) as soon as its check is done, not left running.
-2. `launchd_plist(...)` then `launchd_install(...)` — writes and lints the plist,
+2. `launchd_plist(...)` then `launchd_install(...)`: writes and lints the plist,
    `bootout` and waits for the unload, `bootstrap` with retries on the transient I/O
    error, then polls the well-known document until it answers with **this** identity.
    A label the operator disabled stays disabled: only a first install enables.
@@ -217,7 +228,7 @@ rewrites the plist and restarts. Read [the lifecycle reference](references/lifec
 for the plist fields, the release layout, log rotation, behaving under a host lifecycle broker
 and the Linux and Windows supervisors.
 
-## Step 5 — the dashboard and the events
+## Step 5: the dashboard and the events
 
 The dashboard is a same-origin page: no inline script, strict CSP, polling that pauses
 while the operator types or a dialog is open, one panel's failure never blanks the
@@ -235,10 +246,10 @@ and declare it with `extensions=fs.dashboard_extension()`. Read
 declaration and how to upgrade a dashboard built before the kit: an upgrade you may make yourself,
 which the plugin's session-start notice offers in a repository that owns the service.
 
-The events feed is a **view over the log you already keep** — a jobs table, a JSONL
-journal — not a second store. Each event is one sentence a person reads; set
+The events feed is a **view over the log you already keep** (a jobs table, a JSONL
+journal), not a second store. Each event is one sentence a person reads; set
 `notify: true` only when the operator must decide, or something failed or degrades their
-work — once per episode, with a `subject` and a `link` to the page that resolves it. A
+work, once per episode, with a `subject` and a `link` to the page that resolves it. A
 question's kind says so (`*.awaiting_*`, `*.approval_*`, `human_step.opened`). The service
 raises no banners of its own: the host is the one channel. Read
 [the events reference](references/events-and-notifications.md) for mapping an existing
@@ -253,9 +264,9 @@ A service whose store holds what the operator decided keeps **settings backups**
 directory, restores only on a fresh database and never overwrites. Read
 [the settings backups reference](references/settings-backups.md).
 
-## Step 6 — verify
+## Step 6: verify
 
-Run the probe against the live service — it reads the descriptor, then checks every
+Run the probe against the live service: it reads the descriptor, then checks every
 rule it can reach and says which it could not:
 
 ```bash
@@ -268,7 +279,7 @@ events auth and shape, single-use login, state outside code, instance lock, plis
 launchd pid equals answering pid, `dashboard.declared` (ED-9), and the `interop.*` rules:
 manifest link, capability list, tools equal to the manifest, job tools, unknown job, trace
 propagation, event trace pairs, and `board.responder` for a service that declares the project board) and exits 1 on
-any `FAIL`. A `NOT_RUN` is not a pass —
+any `FAIL`. A `NOT_RUN` is not a pass;
 name it in the report. A service with a dashboard also runs the layout probe,
 `node <skill-dir>/scripts/check_dashboard_layout.mjs --service <id>` (WebKit at 360, 480, 768
 and 1280 px; needs Playwright, else `NOT_RUN`).
@@ -277,7 +288,7 @@ Then prove the lock: start a second copy by hand against the same data directory
 must exit 75 while the first keeps serving. Prove recovery: `kill -9` the launchd pid;
 the well-known document must answer again with a new pid within about 15 seconds.
 
-## Packing and signing it — `fabric-package/1`
+## Packing and signing it: `fabric-package/1`
 
 To hand an agent to another machine or an organization, pack it as one folder (contract DEC-0050, DEC-0051). Write the
 author's `fabric.package.json` (the descriptive fields; for an agent `resultSignal` and `evals` with the receipt of the
@@ -313,11 +324,11 @@ first commit:
 org-index `scripts/check_format.py` reports 0 findings for it before it is called done. **An agent
 someone builds for themselves is not a PassionCode.ai repository:** its licence is its owner's
 choice, nothing about it is published or listed by the organization, and none of these files is
-required of it — though the verified MCP quick start is still how anyone learns to drive it.
+required of it, though the verified MCP quick start is still how anyone learns to drive it.
 
-## Online services — the remote placement
+## Online services: the remote placement
 
-An agent or a dashboard that runs online — on a platform, a server, a hosted app — becomes a
+An agent or a dashboard that runs online (on a platform, a server, a hosted app) becomes a
 Fabric service with the same four routes and one descriptor on the operator's computer
 (`placement: "remote"`, DEC-0019). Nothing about launchd, the lock or loopback applies; three
 things change and the kits implement each:
@@ -328,7 +339,7 @@ things change and the kits implement each:
 | Well-known | only for the token; otherwise `401` with an **empty** body | `wellKnownAllowed('remote', …)` / `well_known_allowed` |
 | Session | `__Host-fabric_session`, `Secure`; codes in memory, the key from a platform secret so sessions survive a deploy | `remoteSessionCookieHeader`, `new LoginCodes(null, 120, { store: new MemoryCodeStore(), key })` |
 
-1. **Serve the four routes** in the app that already exists — not beside it. The complete worked
+1. **Serve the four routes** in the app that already exists, not beside it. The complete worked
    example is [`scripts/sample-remote-service.mjs`](scripts/sample-remote-service.mjs): it runs
    with its own TLS or behind a platform router.
 2. **Secrets live on the platform:** the service token and the session key (32 bytes) are
@@ -336,7 +347,7 @@ things change and the kits implement each:
    remote service needs is issued and kept in Project Observatory, pushed to the platform, and
    the movement recorded with `vault.py moved --at <provider>`, so the platform's copy is
    known rather than invisible.
-3. **Register it on the operator's computer** — the installer side, run there:
+3. **Register it on the operator's computer**, the installer side, run there:
    `registerRemote({ id, name, origin, token })` / `register_remote(...)` writes the token file
    (0600) and the descriptor; pass the token from a file or stdin, never in argv. Public names
    only in public artifacts: a private service is registered by a local descriptor and nowhere
@@ -350,7 +361,7 @@ behaviour a host shows, rotation, a multi-process platform, and what a host will
 
 ## Migrating an existing service
 
-Read [the migration reference](references/migrating-a-service.md) — the order of
+Read [the migration reference](references/migrating-a-service.md): the order of
 changes that keeps the service answering throughout, and what each existing service on
 this estate needs.
 
@@ -367,14 +378,14 @@ this estate needs.
   against [the protocol reference](references/protocol.md); the probe is the judge.
 - **No contract checkout:** the protocol reference is pinned to the extension commit
   in this skill's metadata; do not reconstruct fields from memory.
-- **Fabric Dashboards not installed:** nothing changes — the service is complete
+- **Fabric Dashboards not installed:** nothing changes; the service is complete
   without a host; the descriptor waits for one.
 
 ## Gotchas
 
 - `lsof` shows `*:<port>` or `0.0.0.0` → the bind is wrong even if the Host check works.
 - A health probe that only checks HTTP 200 accepts any program on the port. Compare
-  `service.id` and `service.instance` — two services here once defaulted to ports
+  `service.id` and `service.instance`: two services here once defaulted to ports
   another service already held.
 - `launchctl bootstrap` right after `bootout` fails with I/O error 5 until the unload
   finishes; wait, then retry.
@@ -397,7 +408,7 @@ the probe table verbatim with every `NOT_RUN` explained; the lock and kill-9 res
 with pids; and the one next command. Never call a service conformant while the probe
 reports a `FAIL`.
 
-## Dashboard handoff — also for consumers
+## Dashboard handoff: also for consumers
 
 When handing a registered service dashboard to a person, or writing the generated
 agent's completion/notification instructions, read and apply

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/demo.html

@@ -65,7 +65,7 @@
           <tbody>
             <tr><td class="fd-mono">job-7f3a91</td><td>example.summarize</td><td><span class="fd-chip fd-s-info"><span class="fd-dot"></span>Running</span></td><td><time>2026-10-11 17:02</time></td><td class="fd-num">12 480</td><td class="fd-num">$0.031</td><td class="fd-mono">4bf92f3577b34da6a3ce929d0e0e4736</td></tr>
             <tr><td class="fd-mono">job-7f3a90</td><td>example.translate</td><td><span class="fd-chip fd-s-ok"><span class="fd-dot"></span>Done</span></td><td><time>2026-10-11 16:40</time></td><td class="fd-num">8 002</td><td class="fd-num">$0.019</td><td class="fd-mono">00f067aa0ba902b74bf92f3577b34da6</td></tr>
-            <tr><td class="fd-mono">job-7f3a8f</td><td>example.review</td><td><span class="fd-chip fd-s-warn"><span class="fd-dot"></span>Needs you</span></td><td><time>2026-10-11 15:12</time></td><td class="fd-num">2 210</td><td class="fd-num">—</td><td class="fd-mono">a3ce929d0e0e47364bf92f3577b34da6</td></tr>
+            <tr><td class="fd-mono">job-7f3a8f</td><td>example.review</td><td><span class="fd-chip fd-s-warn"><span class="fd-dot"></span>Needs you</span></td><td><time>2026-10-11 15:12</time></td><td class="fd-num">2 210</td><td class="fd-num">none</td><td class="fd-mono">a3ce929d0e0e47364bf92f3577b34da6</td></tr>
           </tbody>
         </table>
       </div>

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-button.js

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.0 · Fabric's button (Fabric Agent Contract DEC-0040, FB-1…FB-8, FL-1…FL-6)
+/* fabric-dashboard-kit@1.1.1 · Fabric's button (Fabric Agent Contract DEC-0040, FB-1…FB-8, FL-1…FL-6)
    Load it same-origin, after fabric-dashboard.css, with the service it opens Fabric on:
      <script src="fabric-button.js" defer data-service="example-agent.default" data-service-name="Example Agent"
              data-project="project-a" data-project-name="Project A"></script>
@@ -10,7 +10,7 @@
 (function (root) {
   'use strict';
 
-  var VERSION = '1.1.0';
+  var VERSION = '1.1.1';
   var COOKIE = 'fabric_button';
   var GET_FABRIC = 'https://passioncode.ai/fabric';
   var ABSENT_AFTER_MS = 1500;
@@ -212,7 +212,7 @@
       return a;
     });
     var note = el(doc, 'p', { 'class': 'fd-fabric-button-note', role: 'note' });
-    note.appendChild(doc.createTextNode('Fabric is not installed — get it at '));
+    note.appendChild(doc.createTextNode('Fabric is not installed. Get it at '));
     note.appendChild(el(doc, 'a', { href: GET_FABRIC, target: '_blank', rel: 'noopener', 'class': 'fd-fabric-button-get' }, 'passioncode.ai/fabric'));
     note.hidden = !absent;
     menu.appendChild(note);

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-dashboard.css

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.0 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
+/* fabric-dashboard-kit@1.1.1 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
    A Fabric service dashboard shown inside a host pane: usable from 360 CSS px up, navigation always
    reachable, wide content in its own scroll box, one vertical scroller, appearance from the host.
    Copy this file next to fabric-dashboard.js; do not edit it in place. Put the page's own rules in

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-dashboard.js

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.0 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
+/* fabric-dashboard-kit@1.1.1 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
    Load it same-origin with <script src="fabric-dashboard.js" defer></script>: no inline script, no
    eval, nothing from a CDN. It applies the host's appearance (ED-6, ED-8), folds navigation that
    does not fit into a More menu (ED-3), makes wide boxes keyboard-reachable (ED-4) and keeps
@@ -8,7 +8,7 @@
   'use strict';
 
   var KIT = 'fabric-dashboard-kit';
-  var VERSION = '1.1.0';
+  var VERSION = '1.1.1';
   /* fabric-dashboard-kit:theme-ids:begin */
   var THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 /* fabric-dashboard-kit:theme-ids:end */

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/kit.json

@@ -1,6 +1,6 @@
 {
   "name": "fabric-dashboard-kit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "profile": "fabric-dashboard/0.1",
   "decision": "DEC-0036",
   "declarationKey": "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1",
@@ -15,9 +15,9 @@
     "contrast"
   ],
   "files": {
-    "fabric-dashboard.css": "498571903fac6dfd2d6645283da2f703fa945f410f2fafa269a8c9c322735c3b",
-    "fabric-dashboard.js": "100f55d940d4ed60aa8511cee4c65219c93114eb7d7a66639b0e4e4d7aa05f22",
-    "fabric-button.js": "4f1e100936ae65af5539594681e66092ae1834a4952da547a67d0558c9fadbbe",
+    "fabric-dashboard.css": "a8847c8e2f386572318842ec1d1613fcb29e4aec060e033c060d8dba6b7c6f02",
+    "fabric-dashboard.js": "d0fc41144a6bd413383bd53bbfa6e01a29547c7ec9c01a3927d69fb36cd71a7d",
+    "fabric-button.js": "f5599fabfeadfb5c69d30f7ea500846521a166470078a736291c7753014bc25c",
     "themes.json": "511839f1a1a83eb37fadfd132791474497d5c28c5091700b9aa31ad076e359b5"
   },
   "history": {
@@ -29,6 +29,11 @@
       "fabric-dashboard.css": "498571903fac6dfd2d6645283da2f703fa945f410f2fafa269a8c9c322735c3b",
       "fabric-dashboard.js": "100f55d940d4ed60aa8511cee4c65219c93114eb7d7a66639b0e4e4d7aa05f22",
       "fabric-button.js": "4f1e100936ae65af5539594681e66092ae1834a4952da547a67d0558c9fadbbe"
+    },
+    "1.1.1": {
+      "fabric-dashboard.css": "a8847c8e2f386572318842ec1d1613fcb29e4aec060e033c060d8dba6b7c6f02",
+      "fabric-dashboard.js": "d0fc41144a6bd413383bd53bbfa6e01a29547c7ec9c01a3927d69fb36cd71a7d",
+      "fabric-button.js": "f5599fabfeadfb5c69d30f7ea500846521a166470078a736291c7753014bc25c"
     }
   }
 }

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/README.md

@@ -0,0 +1,64 @@
+# Recipe: a support agent
+
+A service answers one inbound question from its own knowledge file, or hands it to a person. Built only on the service
+kit: `fabric_openrouter` for the model, `fabric_usage` for receipts, `fabric_paths` for private, atomic state.
+Tests: `test/test_support_agent_recipe.py` (a fake model; no network, no key).
+
+## What it does with one message
+
+| Step | Rule | When it fails |
+|---|---|---|
+| Repeat | the decision already made for this message id is returned, with no model call | |
+| Lookup | entries sharing words with the question (its question, tags and answer), best three | handoff `no-knowledge` |
+| Draft | `fabric_openrouter.Client.chat`: own key, spend ceiling before every attempt, a usage receipt per call, a fallback of another vendor, temperature 0 | handoff `model:<kind>` (`ceiling`, `failed`, `auth`, `payment`, `config`, `unpriced`) |
+| Model unsure | the model may answer exactly `HANDOFF` | handoff `model-unsure` |
+| Checks, proven by code | at least one `[KB:<id>]` citation; every cited id was given to the model; no em dash (U+2014), `--` or a spaced hyphen or en dash between words; the reply's script is the question's; at most `maxChars` | handoff, each failed check named (`no-citation`, `unknown-citation:<ids>`, `dash`, `script:<got>-not-<wanted>`, `too-long`, `empty`) |
+| Record | the decision, 0600, written atomically; a handoff goes to the outbox first, so a crash repeats a handoff and never loses one | |
+
+A reply comes back without its citation markers, with `citations` beside it. The agent never sends the reply: the
+service that calls it owns its channel (mail, a chat, a store review) and its response time.
+
+## Install into a service
+
+```bash
+python3 <adapter>/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_kit.py \
+  install <service>/support --lang py --module fabric_openrouter --module fabric_usage --module fabric_paths
+cp <adapter>/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/support_agent.py <service>/support/
+python3 <adapter>/.../fabric_kit.py status <service>/support      # current, older or modified, per file
+```
+
+## Configure
+
+`config.example.json`, paths relative to the config's folder:
+
+| Key | Meaning |
+|---|---|
+| `knowledge` | the knowledge file: `{"entries": [{"id", "question", "answer", "tags"}]}`, ids unique |
+| `stateDir` | decisions, the handoff outbox and the usage ledger (`usage.jsonl`) |
+| `model`, `fallback` | two models of different vendors; a lane that reads what customers write runs on an open-vendor model (DEC-0083) |
+| `keyEnv` | the environment variable that holds the agent's own OpenRouter key; never a value in the file |
+| `ceilingUsd`, `window` | the spend ceiling per UTC `day` or `month` |
+| `prices` or `catalog` | USD per token per model. The example's prices are placeholders, not OpenRouter's: take them from `GET https://openrouter.ai/api/v1/models` (a saved catalog file named in `catalog` is read with `prices_from_catalog`). A model without a price is never called |
+| `maxTokens`, `maxChars` | the output budget per call and the reply's length limit |
+
+## Run
+
+```bash
+OPENROUTER_API_KEY=... python3 support_agent.py answer --config config.json --message-id m-1 --text "How do I reset my password?"
+```
+
+The key comes from the environment the service manager gives the agent, never typed on a command line. The decision
+prints as JSON: `{"messageId", "action": "reply"|"handoff", "reply"?, "citations", "reasons", "costUsd", "repeated"}`.
+Exit 1 on a broken config or knowledge file. A missing key is not a crash: the message is handed off with
+`model:config`.
+
+From a service's capability handler, build the agent once with `support_agent.from_config(path)` and call
+`agent.answer(message_id, text, task_run_id=...)`; pass `on_handoff=` to `SupportAgent` to route handoffs to the
+operator's channel instead of the outbox file.
+
+## Before you call it finished
+
+- Replace the example knowledge with the product's own, and run real past questions through it ([practices](../../../creating-fabric-agents/references/practices.md#judges-and-evals), *Judges
+  and evals*): count handoffs and read a sample of replies.
+- Show spend: `fabric_usage.usage_report` over the ledger, or `fabric_openrouter.totals`.
+- One decision per message id holds in one process; a service runs one instance per context under its instance lock.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/config.example.json

@@ -0,0 +1,15 @@
+{
+  "knowledge": "knowledge.example.json",
+  "stateDir": "state",
+  "model": "deepseek/deepseek-v4.1-flash",
+  "fallback": "qwen/qwen3.8-flash",
+  "keyEnv": "OPENROUTER_API_KEY",
+  "ceilingUsd": 1.0,
+  "window": "day",
+  "maxTokens": 600,
+  "maxChars": 1200,
+  "prices": {
+    "deepseek/deepseek-v4.1-flash": {"prompt": 0.0000002, "completion": 0.0000008},
+    "qwen/qwen3.8-flash": {"prompt": 0.0000001, "completion": 0.0000004}
+  }
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/knowledge.example.json

@@ -0,0 +1,13 @@
+{
+  "entries": [
+    {"id": "password-reset", "question": "How do I reset my password?",
+     "answer": "Open Settings, then Account, then Reset password. A link arrives by email within five minutes.",
+     "tags": ["password", "login", "account"]},
+    {"id": "refund-window", "question": "Can I get a refund?",
+     "answer": "Purchases can be refunded within 14 days through the store you bought from.",
+     "tags": ["refund", "money", "purchase"]},
+    {"id": "password-reset-ru", "question": "Как сбросить пароль?",
+     "answer": "Откройте Настройки, затем Аккаунт, затем Сбросить пароль. Ссылка придёт на почту в течение пяти минут.",
+     "tags": ["пароль", "вход", "аккаунт"]}
+  ]
+}