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

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/support_agent.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""A support agent on the service kit: it answers one inbound question from a knowledge file, or hands it to a person.
+
+    support_agent.py answer --config config.json --message-id m-1 --text "How do I reset my password?"
+
+For each message it:
+
+1. returns the decision it already made for that message id (idempotent: a repeat costs nothing and never sends a
+   second reply);
+2. finds the knowledge entries the question shares words with; none found is a handoff (`no-knowledge`);
+3. drafts a reply through fabric_openrouter (its own key, the spend ceiling, a usage receipt per call, a fallback of
+   another vendor); no answer, the ceiling or a refused key is a handoff (`model:<kind>`);
+4. accepts the draft only when code proves it: it cites at least one entry, every cited entry was given to it, it
+   carries no em dash (U+2014) and no dash substitute, it is written in the question's script, and it fits the length
+   limit. Anything else is a handoff, with the failed checks named;
+5. records the decision (0600, atomic) and, for a handoff, appends it to the outbox the operator's channel reads.
+
+What the agent does not do: send the reply anywhere (the service that calls it owns its channel), judge facts with a
+model, or answer outside the knowledge file. The model's text is data: a citation it invents fails the check.
+
+The kit modules (fabric_openrouter and its closure) sit beside this file in a service
+(`fabric_kit.py install <dir> --module fabric_openrouter`); in this repository they are read from ../../scripts.
+Standard library only. FAA-65 REQ-09.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import threading
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+if str(Path(__file__).resolve().parent) not in sys.path:  # the kit installed beside it, under `python3 -I` too
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+try:
+    import fabric_openrouter
+except ImportError:  # in the adapter's repository: the kit is two folders up
+    sys.path.append(str(Path(__file__).resolve().parents[2] / "scripts"))
+    import fabric_openrouter
+import fabric_paths
+import fabric_usage
+
+EM_DASH = "\u2014"
+_DASHES = re.compile(r"[\u2012\u2014\u2015\u2e3a\u2e3b\ufe58]|--|(?<=[^\W\d_])[ \u00a0][-\u2013]\s(?=[^\W\d_])")
+_CITATION = re.compile(r"\[KB:([A-Za-z0-9][A-Za-z0-9._-]{0,63})\]")
+_WORD = re.compile(r"\w+", re.UNICODE)
+_URL = re.compile(r"https?://\S+")
+_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}")
+SCRIPTS = (
+    ("latin", ((0x41, 0x5A), (0x61, 0x7A), (0xC0, 0x24F), (0x1E00, 0x1EFF))),
+    ("cyrillic", ((0x400, 0x52F),)),
+    ("greek", ((0x370, 0x3FF),)),
+    ("hebrew", ((0x590, 0x5FF),)),
+    ("arabic", ((0x600, 0x6FF), (0x750, 0x77F))),
+    ("devanagari", ((0x900, 0x97F),)),
+    ("thai", ((0xE00, 0xE7F),)),
+    ("cjk", ((0x3040, 0x30FF), (0x3400, 0x4DBF), (0x4E00, 0x9FFF), (0xAC00, 0xD7AF))),
+)
+STOPWORDS = frozenset("a an and are as at be by can do does for from how i in is it my of on or the to what when "
+                      "where which who why will with you your и в во на не что как я мой моя мне с по для из к "
+                      "у о а но ли же это".split())
+
+
+class RecipeError(Exception):
+    pass
+
+
+def script_of(text: str) -> Optional[str]:
+    """The script most of a text's letters are written in (citations and URLs left out), or None without letters."""
+    counts: Dict[str, int] = {}
+    for ch in _URL.sub(" ", _CITATION.sub(" ", text)):
+        code = ord(ch)
+        for name, ranges in SCRIPTS:
+            if any(lo <= code <= hi for lo, hi in ranges):
+                counts[name] = counts.get(name, 0) + 1
+                break
+    return max(counts, key=lambda k: (counts[k], k)) if counts else None
+
+
+def words(text: str) -> set:
+    return {w for w in (m.lower() for m in _WORD.findall(text)) if len(w) > 1 and w not in STOPWORDS}
+
+
+class Knowledge:
+    """Entries `{id, question, answer, tags?}` from a JSON file (`{"entries": [...]}`); ids are unique."""
+
+    def __init__(self, entries: List[Mapping[str, Any]]):
+        self.entries: Dict[str, Dict[str, Any]] = {}
+        for entry in entries:
+            if not isinstance(entry, dict) or not isinstance(entry.get("id"), str) or not _ID.fullmatch(entry["id"]):
+                raise RecipeError("every knowledge entry has an id of letters, digits, '.', '_', ':' or '-'")
+            if not isinstance(entry.get("answer"), str) or not entry["answer"].strip():
+                raise RecipeError("knowledge entry %s has no answer" % entry["id"])
+            if entry["id"] in self.entries:
+                raise RecipeError("knowledge entry %s appears twice" % entry["id"])
+            self.entries[entry["id"]] = dict(entry)
+
+    @classmethod
+    def load(cls, path: Path) -> "Knowledge":
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        return cls(data.get("entries", []) if isinstance(data, dict) else [])
+
+    def lookup(self, question: str, limit: int = 3) -> List[Dict[str, Any]]:
+        """The entries sharing the most words with the question (its words against each entry's question, tags and
+        answer), best first, ties by id; entries sharing none are left out."""
+        asked = words(question)
+        scored = []
+        for entry in self.entries.values():
+            text = " ".join([str(entry.get("question", "")), " ".join(map(str, entry.get("tags", []))),
+                             str(entry["answer"])])
+            score = len(asked & words(text))
+            if score:
+                scored.append((-score, entry["id"], entry))
+        return [entry for _, _, entry in sorted(scored)[:limit]]
+
+
+def check_reply(draft: str, question: str, given: List[str], *, max_chars: int) -> Dict[str, Any]:
+    """What code can prove about a draft: `{ok, problems, citations, reply}`; `reply` is the text without markers."""
+    problems = []
+    cited = list(dict.fromkeys(_CITATION.findall(draft)))
+    if not cited:
+        problems.append("no-citation")
+    unknown = [c for c in cited if c not in given]
+    if unknown:
+        problems.append("unknown-citation:" + ",".join(unknown))
+    if _DASHES.search(draft):
+        problems.append("dash")
+    reply = re.sub(r"[ \t]+", " ", _CITATION.sub("", draft)).replace(" .", ".").replace(" ,", ",").strip()
+    if not reply:
+        problems.append("empty")
+    elif len(reply) > max_chars:
+        problems.append("too-long")
+    wanted, written = script_of(question), script_of(reply)
+    if wanted and written and wanted != written:
+        problems.append("script:%s-not-%s" % (written, wanted))
+    return {"ok": not problems, "problems": problems, "citations": cited, "reply": reply}
+
+
+SYSTEM = (
+    "You are a support agent. Answer the customer's question using only the knowledge entries given below. "
+    "Cite every entry you rely on as [KB:<id>] right after the sentence it supports. If the entries do not answer "
+    "the question, reply exactly: HANDOFF. Write in the language of the question. Write plainly and briefly. "
+    "Never use an em dash or any dash between clauses: use a full stop, a comma, a colon or parentheses."
+)
+
+
+def build_messages(question: str, entries: List[Dict[str, Any]]) -> List[Dict[str, str]]:
+    kb = "\n\n".join("[KB:%s]\nQ: %s\nA: %s" % (e["id"], e.get("question", ""), e["answer"]) for e in entries)
+    return [{"role": "system", "content": SYSTEM + "\n\nKnowledge entries:\n\n" + kb},
+            {"role": "user", "content": question}]
+
+
+class SupportAgent:
+    def __init__(self, *, knowledge: Knowledge, client: Any, model: str, fallback: str, state_dir: Path,
+                 max_tokens: int = 600, max_chars: int = 1200, lookup_limit: int = 3,
+                 on_handoff: Optional[Callable[[Dict[str, Any]], None]] = None):
+        self.knowledge, self.client = knowledge, client
+        self.model, self.fallback = model, fallback
+        self.state_dir = Path(state_dir)
+        self.max_tokens, self.max_chars, self.lookup_limit = max_tokens, max_chars, lookup_limit
+        self.on_handoff = on_handoff or self._outbox
+        self._lock = threading.Lock()
+
+    @property
+    def decisions_file(self) -> Path:
+        return self.state_dir / "decisions.json"
+
+    def _decisions(self) -> Dict[str, Any]:
+        try:
+            return json.loads(self.decisions_file.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return {}
+
+    def _outbox(self, decision: Dict[str, Any]) -> None:
+        fabric_paths.ensure_private_dir(self.state_dir)
+        line = json.dumps(decision, ensure_ascii=False, separators=(",", ":")) + "\n"
+        fd = os.open(str(self.state_dir / "handoffs.jsonl"), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        try:
+            os.write(fd, line.encode("utf-8"))
+        finally:
+            os.close(fd)
+
+    def answer(self, message_id: str, text: str, *, task_run_id: Optional[str] = None) -> Dict[str, Any]:
+        """The decision for one message: `{messageId, action: reply|handoff, reply?, citations, reasons, costUsd}`."""
+        if not isinstance(message_id, str) or not _ID.fullmatch(message_id):
+            raise RecipeError("message id: letters, digits, '.', '_', ':' or '-', up to 128")
+        if not isinstance(text, str) or not text.strip():
+            raise RecipeError("the message has no text")
+        text = re.sub("[\ud800-\udfff]", "\ufffd", text)  # a lone surrogate (bytes a terminal could not decode) is kept, not fatal
+        with self._lock:  # one decision per message id, in this process; the service's instance lock covers others
+            done = self._decisions().get(message_id)
+            if done is not None:
+                return dict(done, repeated=True)
+            decision = self._decide(message_id, text, task_run_id)
+            if decision["action"] == "handoff":  # before the decision is saved: a crash repeats a handoff, never loses one
+                self.on_handoff(dict(decision, question=text))
+            decisions = self._decisions()
+            decisions[message_id] = decision
+            fabric_paths.ensure_private_dir(self.state_dir)
+            fabric_paths.atomic_write(self.decisions_file,
+                                      json.dumps(decisions, ensure_ascii=False, indent=1).encode("utf-8"))
+        return dict(decision, repeated=False)
+
+    def _decide(self, message_id: str, text: str, task_run_id: Optional[str]) -> Dict[str, Any]:
+        base = {"messageId": message_id, "citations": [], "costUsd": None}
+        entries = self.knowledge.lookup(text, self.lookup_limit)
+        if not entries:
+            return dict(base, action="handoff", reasons=["no-knowledge"])
+        try:
+            got = self.client.chat(build_messages(text, entries), model=self.model, fallback=self.fallback,
+                                   max_tokens=self.max_tokens, temperature=0, task_run_id=task_run_id)
+        except fabric_openrouter.OpenRouterError as err:
+            return dict(base, action="handoff", reasons=["model:" + err.kind])
+        base["costUsd"] = got["receipt"].get("costUsd")
+        if got["content"].strip() == "HANDOFF":
+            return dict(base, action="handoff", reasons=["model-unsure"])
+        checked = check_reply(got["content"], text, [e["id"] for e in entries], max_chars=self.max_chars)
+        if not checked["ok"]:
+            return dict(base, action="handoff", reasons=checked["problems"], citations=checked["citations"])
+        return dict(base, action="reply", reply=checked["reply"], citations=checked["citations"], reasons=[])
+
+
+def from_config(config_path: Path, **overrides: Any) -> SupportAgent:
+    """An agent from a config file (see config.example.json): paths are relative to the config's folder."""
+    config = json.loads(Path(config_path).read_text(encoding="utf-8"))
+    home = Path(config_path).resolve().parent
+    state = (home / config.get("stateDir", "state")).resolve()
+    prices = config.get("prices") or {}
+    if config.get("catalog"):
+        prices = dict(fabric_openrouter.prices_from_catalog(json.loads((home / config["catalog"]).read_text("utf-8"))),
+                      **prices)
+    client = fabric_openrouter.Client(ceiling_usd=float(config["ceilingUsd"]), window=config.get("window", "day"),
+                                      ledger=fabric_usage.JsonlUsageLedger(state / "usage.jsonl"), prices=prices,
+                                      key_env=config.get("keyEnv", "OPENROUTER_API_KEY"),
+                                      project_id=config.get("projectId"), **overrides)
+    return SupportAgent(knowledge=Knowledge.load(home / config["knowledge"]), client=client, model=config["model"],
+                        fallback=config["fallback"], state_dir=state, max_tokens=int(config.get("maxTokens", 600)),
+                        max_chars=int(config.get("maxChars", 1200)))
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    ask = sub.add_parser("answer", help="decide one message and print the decision as JSON")
+    ask.add_argument("--config", required=True, type=Path)
+    ask.add_argument("--message-id", required=True)
+    ask.add_argument("--text", help="the question; read from stdin when absent")
+    args = parser.parse_args(argv)
+    try:
+        agent = from_config(args.config)
+        text = args.text if args.text is not None else sys.stdin.read()
+        decision = agent.answer(args.message_id, text)
+    except (RecipeError, fabric_openrouter.OpenRouterError, OSError, ValueError, KeyError) as err:
+        print(json.dumps({"error": type(err).__name__, "message": str(err)}), file=sys.stderr)
+        return 1
+    print(json.dumps(decision, ensure_ascii=False, indent=1))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -63,12 +63,12 @@ One tick every 15 s ± 5 s (`step()` answers the wait):
 
 | Step | Board call | Checkpoint written first |
 |---|---|---|
-| hold the slot | `com.enroll` (again at about 20 s while idle: the holder's enroll renews its 60 s lease) | — |
+| hold the slot | `com.enroll` (again at about 20 s while idle: the holder's enroll renews its 60 s lease) | none |
 | take a request | `com.claim`, the same key while nothing is claimable | `claimed` |
-| read it | `com.get`: the digest must equal the claim's, and the request must name this Project and capability | — |
+| read it | `com.get`: the digest must equal the claim's, and the request must name this Project and capability | none |
 | accept | `com.accept` with the claim's exact fence (request, generation, attempt, digest, revision) | `accepting`, then `accepted` |
 | act | `com.effect_begin`, only when the handler calls `ctx.begin_effect()` | `effect-beginning`, then `in-progress` |
-| while working | `com.renew` at about 20 s; `com.progress` for `ctx.progress(note)` | — |
+| while working | `com.renew` at about 20 s; `com.progress` for `ctx.progress(note)` | none |
 | answer | `com.reply` (fenced) when the outcome carries `reply` | `replying` |
 | settle | `com.complete {state, observed, summary?, evidence?}` | `completing`, then the entry is dropped |
 
@@ -82,12 +82,12 @@ own monotonic clock and never reasons from `leaseExpiresAt`.
 `admit(request)` is required: it is the service's own input gate. It answers `None` to admit or one sentence saying
 why not; a refusal accepts the request and completes it `failed_known` with that sentence, so the requester learns it
 and the request does not bounce. A redacted body is refused the same way. The kit never hands a body to a model, a
-shell or a tool; what the handler does with an admitted body — and the checks it needs before a model, a tool or a
-spend sees it — is the service's own responsibility. A message never carries an approval.
+shell or a tool; what the handler does with an admitted body (and the checks it needs before a model, a tool or a
+spend sees it) is the service's own responsibility. A message never carries an approval.
 
 ## Effects, observation, evidence and the reply
 
-- Call `ctx.begin_effect(summary)` — and let it return — before the handler spends, writes outside the service or calls
+- Call `ctx.begin_effect(summary)`, and let it return, before the handler spends, writes outside the service or calls
   anything that acts. If it raises `Stopped`, act no further.
 - After an effect began, the outcome must be observed (`observed: true`): the kit never sends an unobserved result; the
   request stays unknown and is reconciled later.
@@ -130,7 +130,7 @@ contract's matrix, held to its vectors (`test/fixtures/contract/comms-hold-vecto
 | `com.enroll`, `com.claim`, `com.responder_replace` | the slot pauses: asked again after 15 s, then 30 s, doubling to 15 minutes; one `board.slot.held` event per capability, and `board.slot.released` when an enroll succeeds again |
 | `com.accept` (the hold came after the claim) | nothing was done: the entry is dropped, the claim lapses and the request waits on the board (`board.request.waiting`); the slot pauses |
 | `com.effect_begin` | the effect has not begun: the handler waits (same idempotency key, the pause doubling) while the tick keeps renewing the lease, then begins once the hold is lifted; `ctx.stopped` ends the wait |
-| accepted work at restart under a hold | kept as `lapsed`, then taken back with `com.responder_replace` and a transfer once the hold is lifted — never claimed back |
+| accepted work at restart under a hold | kept as `lapsed`, then taken back with `com.responder_replace` and a transfer once the hold is lifted, never claimed back |
 
 A hold is not an outage: no `board.down`, no notify. Work already accepted keeps running and completes.
 
@@ -143,7 +143,7 @@ whose responder was gone. Read it as the owner's attestation, not the responder'
 A board session (`fabric.board.join`) is served the respond scope only: `com.status`, `com.list`, `com.get`,
 `com.reply` (the fenced form), `com.enroll`, `com.claim`, `com.renew`, `com.accept`, `com.progress`,
 `com.effect_begin`, `com.complete`, `com.reconcile`, `com.responder_replace`. `BoardSession.call` refuses anything else
-locally (`not-in-scope`) — never `com.submit`, `com.cancel`, `com.read_ack` or `com.directory`.
+locally (`not-in-scope`): never `com.submit`, `com.cancel`, `com.read_ack` or `com.directory`.
 
 The idempotency epoch comes from `com.status`. A Fabric built before its board-session fix tells a board session none:
 the kit fails closed (`no-epoch`, `board.blocked`) instead of guessing one.
@@ -152,13 +152,13 @@ the kit fails closed (`no-epoch`, `board.blocked`) instead of guessing one.
 
 The directory belongs to a Project session (a coding agent's, or a launched one). Before looking a Project up in a
 `com.directory` page, `find_project(page, project_id, capability=None)` / `findProject` checks the page: closed shapes
-(no count, holder or generation) and FAC-SEM-107 — each Project once, each capability once per Project. Project ids and
+(no count, holder or generation) and FAC-SEM-107: each Project once, each capability once per Project. Project ids and
 capability names compare **exactly as written** (DEC-0077; they are not URIs, so not by normal form). A page that fails
 raises `directory-invalid` rather than answering; an unlisted Project may still be addressed by an id already held.
 
 ## Events, the probe and the live smoke
 
-Events go to `emit(kind, level, text, notify=…, data=…)` — `JsonlEventLog.append` fits — with `data {schema, value}`
+Events go to `emit(kind, level, text, notify=…, data=…)` (`JsonlEventLog.append` fits) with `data {schema, value}`
 checked by FAC-SEM-101 (no credential in data): `board.request.completed`, `board.request.refused`,
 `board.request.skipped`, `board.request.reconciled`, `board.request.held`, `board.attempt.lost`,
 `board.reconcile.needed`, `board.slot.contested`, `board.access.needed`, `board.blocked`, `board.down`, each
@@ -167,10 +167,10 @@ notifying episode said once.
 `check_service.py <id> [--board-kit <the service's fabric_board.py or fabric-board.mjs>]` rule **board.responder**:
 `NOT_RUN` when the well-known `protocols` names no `fabric-project-comms` revision; `FAIL` for a revision this kit does
 not read or a fixture conversation that goes wrong; `PASS` when the kit's `self_check()` / `selfCheck()` passes (the
-whole conversation, a fenced accept, a session without an epoch — no Fabric touched).
+whole conversation, a fenced accept, a session without an epoch; no Fabric touched).
 
 The live smoke runs only against a disposable Fabric (built app and its own stack), never an operator's estate: Fabric's
-COM-03 packet (`docs/evidence/plans/2026-10-04-project-communications.md`) has the exact commands — register
+COM-03 packet (`docs/evidence/plans/2026-10-04-project-communications.md`) has the exact commands: register
 `fabric-mcp` for Claude Code and Codex, the operator allows `session.enroll` and `board.respond`
 (`board:<example-agent project>/<capability>`), Claude submits a request, the responder enrolls, claims, accepts and
 completes, then is killed mid-claim and replaced. Without that Fabric, report it `NOT_RUN`.

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

@@ -0,0 +1,93 @@
+# Connectors: outbound HTTP and OpenRouter
+
+Two kit modules a service uses to reach the outside: `fabric_http` for any HTTP API, `fabric_openrouter` for models.
+Both have Node twins (`fabric-http.mjs`, `fabric-openrouter.mjs`) that run the same cases
+(`test/fixtures/kit-http-cases.json`, `test/fixtures/kit-openrouter-cases.json`). Install them with
+`fabric_kit.py install <dir> --module fabric_openrouter` ([kit modules](kit-modules.md)). The project board has its
+own connector ([board](board.md)). Standard library only; tests inject the transport and never open the network.
+
+## Contents
+
+- [fabric_http](#fabric_http)
+- [fabric_openrouter](#fabric_openrouter)
+- [Writing a connector for another API](#writing-a-connector-for-another-api)
+
+## fabric_http
+
+```python
+import fabric_http
+answer = fabric_http.request("GET", "https://api.example/v1/items", headers={"Authorization": "Bearer " + token},
+                             deadline_s=20, retries=2)
+answer.status, answer.headers["content-type"], answer.json()
+```
+
+```js
+import { request } from './fabric-http.mjs';
+const answer = await request('GET', 'https://api.example/v1/items', { headers, deadlineS: 20, retries: 2 });
+```
+
+| Rule | Default | Why |
+|---|---|---|
+| One deadline covers every attempt and every wait | `deadline_s` 30 | a caller's own deadline is one number, not one per retry |
+| Retried: 408, 425, 429, 500, 502, 503, 504 and connection errors | `retries` 2 (0 to 10) | transient failures |
+| Only when repeating is safe: `GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`, or an `Idempotency-Key` header; any other request only on 429 | | a second `POST` after a timeout may do the work twice |
+| Wait before retry n: `min(max_backoff_s, backoff_base_s * 2**n) * (0.5 + random())` | 0.5 s base, 8 s cap | jitter spreads retries of many clients |
+| `Retry-After` (seconds, or an IMF-fixdate) replaces the wait; over `max_retry_after_s` the answer stands | 30 s | the server knows when it recovers |
+| A wait that would pass the deadline is not taken: the last answer or error stands | | |
+| The body is read to one byte past `max_bytes`; over it is an error | 8 MiB | a runaway answer never fills memory |
+| Redirects are answered, never followed | | a redirect must not carry the `Authorization` header to another host |
+| Plain `http://` is refused unless the host is loopback or `insecure=True`; credentials in a URL are refused | | a token never crosses a network in clear, nor sits in a URL |
+| Header names must be tokens; a value with a line break or NUL is refused | | header injection |
+| A JSON body is written as `JSON.stringify` writes it: a lone surrogate escaped, NaN and Infinity refused | | both twins send the same bytes |
+| Whatever the transport throws is a connection error, in both languages; a timeout is a timeout | | |
+| The deadline is held across the whole response: a watchdog shuts the socket when it passes, so trickled headers or a trickled chunk cannot hold the caller | | |
+| `Response.json()` reads as `JSON.parse` does: a byte order mark skipped, `NaN` and `Infinity` refused | | |
+
+Every answer comes back as a `Response`, whatever its status; `HttpError` means no usable answer came, with `kind`
+`connection`, `timeout`, `too-large` or `refused`, the status when there was one, and the URL redacted to scheme,
+host, port and path (`redact_url`). An error never carries a request header or body.
+
+## fabric_openrouter
+
+```python
+import fabric_openrouter, fabric_usage
+client = fabric_openrouter.Client(ceiling_usd=2.0, window="day",
+                                  ledger=fabric_usage.JsonlUsageLedger(state / "usage.jsonl"),
+                                  prices=fabric_openrouter.prices_from_catalog(catalog))
+answer = client.chat(messages, model="deepseek/deepseek-v4.1-flash", fallback="qwen/qwen3.8-flash", max_tokens=800)
+answer["content"], answer["receipt"]["costUsd"], answer["attempts"]
+```
+
+```js
+const client = new Client({ ceilingUsd: 2, ledger: new JsonlUsageLedger(file), prices: pricesFromCatalog(catalog) });
+const answer = await client.chat(messages, { model, fallback, maxTokens: 800 });
+```
+
+| Rule | What happens |
+|---|---|
+| The key | read from the environment variable `key_env` names (`OPENROUTER_API_KEY`) at each call; sent only in `Authorization`; missing is `OpenRouterError` kind `config` before anything is sent |
+| The ceiling, before every attempt | the window's spend (ledger receipts in the UTC `day` or `month`) plus calls in flight plus this attempt's worst case must stay within `ceiling_usd`; otherwise kind `ceiling`, nothing sent. Retries and the fallback are checked the same way |
+| The worst case | the input at one token per two UTF-8 bytes of the messages and every param (tools, response_format) as compact JSON (`prompt_tokens_bound`), `max_tokens` of output, at the model's price, plus a per-request price. `models`, `route`, `plugins`, `web_search_options` and `n` are refused (they change what is billed), and so is `max_completion_tokens` (the client sets the output budget) |
+| A model without a price | never called (kind `unpriced`): its spend could not be bounded. Prices come from `GET https://openrouter.ai/api/v1/models` through `prices_from_catalog`; a price is a plain decimal string or a number, and anything else (blank, hex, a list) is no price |
+| A receipt without a cost in the window | an unmeasured attempt, or an answer that came with no usage, counted at the worst case of the attempt that wrote it while this client runs; one written before it started counts as `unmeasured_call_usd`, by default the current attempt's worst case |
+| Receipts | every status-200 answer records one, and so does an attempt that may have been billed without an answer to read (a timeout, a cut or refused connection, a 200 over the size cap or not JSON: no tokens, `costUsd: null`, `tokensMeasured: false`; over-counting a refused connection is the safe side): the served model, the provider's tokens (cache reads and writes kept apart), `costUsd` from `usage.cost`, else from the price list (`costBasis: price-list`), else `null` with `tokensMeasured: false`; `route: key`, the client's `project_id` and the call's `task_run_id`. A request the provider answered with a 4xx or 5xx records nothing: it was not billed |
+| What is an answer | `finish_reason` `stop` or `tool_calls` with content or tool calls; `error` is retried on the same model; `length` (the budget ran out, reasoning included), `content_filter` and empty content go to the fallback |
+| Retries | 408, 425, 429, 500, 502, 503, 504 and connection errors on the same model, `retries` times (default 1), `Retry-After` honoured, within one deadline (`deadline_s` 120) for the whole call |
+| Stop at once | 401, 402 and 403 (kinds `auth`, `payment`): a key, credit or permission problem is the same on every model |
+| The fallback | required, of another vendor (the part before `/` differs) |
+| Content | text only: a string, null, or parts that are all `{"type": "text"}`; an image, audio or file part is refused (`config`), because what it is billed cannot be bounded from its bytes |
+| What the ceiling does not cover | the `provider` routing param can send a call to a provider priced above the catalog; two `Client` objects sharing one ledger each hold only their own calls in flight, so give an agent one client per key |
+| Attribution | off unless an `attribution` setting is given (FAC-SEM-098, `fabric_usage.attribution_headers`) |
+| Request body | `model`, `messages`, `max_tokens`, `usage: {include: true}` and your params (temperature, reasoning, response_format, tools); `stream`, `model`, `messages`, `max_tokens` and `usage` as params are refused |
+
+`OpenRouterError.attempts` lists every attempt as `{model, status, outcome}` (`answered`, `retry`, `error`,
+`length`, `filtered`, `empty`, `refused`, `bad-answer`, `auth`, `payment`); nothing in it holds the key or the
+prompt. `totals(receipts)` gives calls, priced spend and unpriced calls for a dashboard line. Choosing the models
+themselves: creating-fabric-agents, `references/models-and-providers.md`.
+
+## Writing a connector for another API
+
+Build it on `fabric_http.request`: one module per API, the key read from a named environment variable at call time,
+the deadline and retries passed through, the provider's own answer mapped into your types, and a receipt through
+`fabric_usage.make_usage_receipt` for every billed call. Put it in your service, not in the kit, unless several
+services need it; a kit module also needs its Node twin and shared cases ([adding a module](kit-modules.md#adding-or-changing-a-module)).

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/dashboard-kit.md

@@ -1,4 +1,4 @@
-# The dashboard kit — `fabric-dashboard/0.1`
+# The dashboard kit: `fabric-dashboard/0.1`
 
 Fabric Dashboards shows a service's page in a pane beside its sidebar and the agent console, and the
 operator drags the console wider whenever they need it. The page never knows how much room it will
@@ -97,12 +97,12 @@ service. Load it after the stylesheet, with ids only:
   scroll. The mark and the word *Fabric*, the mark alone below 480 px; the accessible name is always *Open Fabric*;
   `--ink` on `--panel` with an `--edge` boundary, the pairs the themes are measured on.
 - **Links (FL-1…FL-6):** built with the kit's port of the contract's `buildFabricLink`; a value outside the grammar
-  — or one shaped like a credential — means no button, never a bad link. A press opens a view in Fabric and starts
+  (or one shaped like a credential) means no button, never a bad link. A press opens a view in Fabric and starts
   nothing (FB-8).
 - **The host (FB-6):** when the host's `fabric_button` cookie says `owner=host`, the page hides its own button.
 - **Fabric absent (FB-5):** when the cookie says `fabric=absent`, or `data-fabric="absent"`, or when the page is still
-  visible and focused 1.5 s after a link was followed, the menu says "Fabric is not installed — get it at
-  passioncode.ai/fabric". Nothing downloads, nothing retries. A local service's server decides `data-fabric` with
+  visible and focused 1.5 s after a link was followed, the menu says that Fabric is not installed and names
+  passioncode.ai/fabric to get it. Nothing downloads, nothing retries. A local service's server decides `data-fabric` with
   `fabric_button_presence()` / `fabricButtonPresence()`: `present` while Fabric's own descriptor
   (`services/fabric.default.json`, Fabric ADR-0139) is registered and, for an app's descriptor (`manager: "person"`,
   DEC-0069), its app is still installed; `absent` otherwise. A press only follows a link, so the button never reads

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/dashboard-links.md

@@ -1,4 +1,4 @@
-# Dashboard links — producer and consumer rule
+# Dashboard links: producer and consumer rule
 
 Read when an agent creates a dashboard, implements `<tool> dashboard`, or hands
 an existing Fabric service dashboard to a person. This also applies to generated

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

@@ -4,10 +4,10 @@ The dashboard is where the operator decides; it must stay truthful when parts of
 service are not.
 
 1. **Same origin, static assets.** HTML shell plus hashed `app.js`/`app.css` from a
-   whitelist; no inline script; a strict CSP. Nothing from a CDN — the page must work
+   whitelist; no inline script; a strict CSP. Nothing from a CDN: the page must work
    offline on a plane.
 2. **State first, then detail.** The top of every page answers "is it working, and
-   does it need me?" — the same `status`, `degraded` and attention tiles the
+   does it need me?": the same `status`, `degraded` and attention tiles the
    well-known document publishes, so the page and Fabric Dashboards never disagree.
 3. **Calm refresh.** Poll the page's own API every 5 s while visible, back off when
    hidden, and pause while a field is focused, a form has unsaved input or a dialog is
@@ -16,7 +16,7 @@ service are not.
 4. **Partial failure stays partial.** Load panels independently (`Promise.allSettled`);
    a failed panel shows its own one-sentence error and a retry, and the rest render.
 5. **Every error is a sentence and an action.** "Store listing push failed: App Store
-   Connect rejected the key. Settings → Keys" — never a status code, a stack trace or a
+   Connect rejected the key. Settings → Keys", never a status code, a stack trace or a
    blank area. Show when data was last fresh.
 6. **Server down is a state, not a crash.** When the API stops answering, keep the
    last data greyed with "Service not answering since 17:02", and recover by itself
@@ -30,4 +30,4 @@ service are not.
 9. **Links into the page are stable.** Event `link`s point at hash routes that survive
    a reload (`/dashboard#/approvals/77`) so a notification opens the exact item.
 10. **No second browser tab required.** With Fabric Dashboards installed, the page is
-    shown inside it; do not open windows or tabs on your own — use in-page dialogs.
+    shown inside it; do not open windows or tabs on your own; use in-page dialogs.

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

@@ -1,4 +1,4 @@
-# Delegation — checking who acts for whom (DEC-0039)
+# Delegation: checking who acts for whom (DEC-0039)
 
 A service that other agents of the estate call checks each call offline with the kit's verifier: the estate hub
 signs a delegation token naming the person (`sub`), the actor chain (`act`), this service (`aud`), the
@@ -22,7 +22,7 @@ contract's own verifier does.
 ## Declaring it
 
 In the well-known document: `surfaces.mcp.auth: "delegation"` (only delegation tokens) and
-`auth.delegation: {issuer, jwks}` — the `iss` you trust (`urn:fabric:estate:<id>`) and where the key set is read.
+`auth.delegation: {issuer, jwks}`: the `iss` you trust (`urn:fabric:estate:<id>`) and where the key set is read.
 The descriptor's token stays the host's: it is never a caller's credential on `/mcp` (DL-12). The probe checks
 the declaration (`auth.delegation-declared`) and that `/mcp` refuses the descriptor token.
 
@@ -34,7 +34,7 @@ keys = fd.JwksCache(well_known["auth"]["delegation"]["jwks"])          # https,
 gate = fd.delegation_gate(audience="example-agent", jwks=keys, issuer=well_known["auth"]["delegation"]["issuer"],  # required
                           effects={"example.write": "draft", "example.publish": "publish"})   # each tool's manifest effect
 server = fi.McpToolServer("example-agent", VERSION, authorize=gate)    # pass the request headers to handle()
-# in a handler: ctx.delegation["principal"], ["caller"], ["chain"] — record the chain with the work
+# in a handler: ctx.delegation["principal"], ["caller"], ["chain"]; record the chain with the work
 ```
 
 ```js
@@ -50,7 +50,7 @@ if (!verdict.ok) return refusalToolResult(verdict);
 DL-25 places each caller in a tier by its origin: **T0** a loopback caller under the owner's account that the
 service's own local floor (the descriptor token, the Host guard) has authenticated; **T1** an enrolled machine of
 the same owner; **T2** everyone else, and any call relayed onto loopback from off the machine (a tunnel, a proxy, the
-hub forwarding a T2 caller). DL-26: a T0 or T1 caller is never required to present a token — pass the tier,
+hub forwarding a T2 caller). DL-26: a T0 or T1 caller is never required to present a token; pass the tier,
 `gate(tool, headers, tier="T0")` or `server.handle(message, headers, tier="T0")`, and the call passes with no
 delegation. A token such a caller presents is still verified and refused when invalid. A T2 caller takes the whole
 profile. Money limits and human gates bind at every tier.
@@ -66,8 +66,10 @@ job records who started it.
 **A partner in the chain** (DEC-0090). A token a partner's agent presents for a customer organization carries the
 partner as the innermost actor: `{partner: "org:<id>"}`, exactly that member, under at least one agent. It counts
 toward the depth limit and ends the chain; outermost, with an `act` beneath, or as `personal` it is
-`malformed-chain`. A node with a `sub` beside `partner` is an agent, checked as one. `ctx.delegation["chain"]` lists a
-node with `partner` by its `org:` id. `chain_depth(act)` /
+`malformed-chain`. A node with a `sub` beside `partner` is checked as an agent, yet `ctx.delegation["chain"]` lists it
+by its `org:` id, as the contract's `chainOf` does; the schema refuses such a node, so a correct issuer never mints one
+(raised with the contract, FAA-64). Job ownership and idempotency keys follow `(principal, caller)` and do not include
+the partner (FAA-64). `chain_depth(act)` /
 `chainDepth(act)` answer the contract's depth, infinity for a chain that is not one. Minting a partner's token (its
 grant, FAC-SEM-124) is the issuer's, not the kit's.
 
@@ -76,19 +78,19 @@ grant, FAC-SEM-124) is the issuer's, not the kit's.
 An action with an external effect may need the operator's approval (DL-17, DL-18). The order is fixed: the token,
 then the grant check where there is one, then `verify_approval` / `verifyApproval`, which consumes the approval's
 `jti` last, then the action. Without an approval, answer `approval-required` with
-`action_digest(action)` / `actionDigest(action)` — the SHA-256 of the action's RFC 8785 form (`jcs`) — so the caller
+`action_digest(action)` / `actionDigest(action)` (the SHA-256 of the action's RFC 8785 form, `jcs`) so the caller
 can ask the hub. When the meter denies a grant check, answer `refusal_from_denial(denial)` /
 `refusalFromDenial(denial)`: the meter's code unchanged, its window and level in `error.data` (DL-21 step 6). Keep consumed ids in `FileJtiStore` (0600, survives a restart); `MemoryJtiStore` is for tests
 and `UNSAFE_NO_JTI_STORE` exists only by name. No store at all, or a store file that cannot be read, is
-`unknown-state` — never a pass.
+`unknown-state`, never a pass.
 
 ## What a refusal looks like
 
-DL-19: an MCP tool answers `refusal_tool_result(r)` / `refusalToolResult(r)` — `isError: true` and
+DL-19: an MCP tool answers `refusal_tool_result(r)` / `refusalToolResult(r)`: `isError: true` and
 `structuredContent: {error: {code, message, data: {detail}}}`; an HTTP route answers `refusal_http(r)` /
 `refusalHttp(r)` with the code's status (401 for `unauthenticated`, `token-expired`, `principal-unproven`, with
 `WWW-Authenticate: Bearer error="invalid_token"`; 503 for `issuer-unavailable` and `unknown-state`; 403 for the
-rest). A published key the service cannot use — of small order, for another use, or published twice — is the
+rest). A published key the service cannot use (of small order, for another use, or published twice) is the
 issuer's fault, `issuer-unavailable` (DEC-0045); a gate without a trusted issuer refuses everything as
 `no-trusted-issuer`. `detail` is a short machine word; the token, the approval and the keys never appear in a result or a log.
 
@@ -120,4 +122,4 @@ current verified revision as `estate=` / `{ estate }`, as a value or as a functi
 ## What the kit does not do
 
 It does not mint tokens, check attenuation against a parent (the issuer's rule, DL-5), check a grant or a spend
-window (the meter's, DL-21), or decide which actions need an approval — the service decides that.
+window (the meter's, DL-21), or decide which actions need an approval; the service decides that.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/estate-record.md

@@ -1,7 +1,8 @@
-# The estate record — what the operator's machines are, signed by their passkey (DEC-0055)
+# The estate record: what the operator's machines are, signed by their passkey (DEC-0055)
 
 Fabric Agent Contract DEC-0055, `docs/specification/estate-record.md`, schema `schemas/estate-record.schema.json`,
-rules `FAC-SEM-072…076`, with contexts (DEC-0082, `docs/specification/contexts.md`, `FAC-SEM-110`, `FAC-SEM-111`).
+rules `FAC-SEM-072…076`, with contexts (DEC-0082, `docs/specification/contexts.md`, `FAC-SEM-110`, `FAC-SEM-111`) and a
+partner's scoped publisher key (DEC-0090, `docs/specification/partner-channel.md`, `FAC-SEM-122`).
 One revision of one person's estate lists:
 - the passkeys that sign it;
 - the machines, with their device keys and a certificate of each machine's hub key;
@@ -78,13 +79,13 @@ gate = fd.delegation_gate(audience=..., jwks=keys, issuer=..., effects=..., esta
                           estate_revocations=lambda: delta_entries)
 ```
 
-- **The token's fault** — no such certification, another key under that `kid`, a `kid` on two machines, a revoked hub
-  key or machine — is `unauthenticated` (for an approval, `approval-invalid`) with detail `kid-not-certified`.
+- **The token's fault** (no such certification, another key under that `kid`, a `kid` on two machines, a revoked hub
+  key or machine) is `unauthenticated` (for an approval, `approval-invalid`) with detail `kid-not-certified`.
 - **The trust source's fault** is `issuer-unavailable`: `estate-unreadable` (a source that throws or answers nothing
   readable, a revision without a number or digest, a window of zero or over 30 days, dates read strictly, `machines` or
   `revocations` not arrays), `estate-outside-window`, `estate-rolled-back` (lower than the applied revision) and
   `estate-forked` (the applied number with another digest). A caller cannot cure these by minting again.
-- An unreadable clock — not a finite number of seconds a `Date` can hold — is refused `unknown-state` `no-clock`
+- An unreadable clock (not a finite number of seconds a `Date` can hold) is refused `unknown-state` `no-clock`
   before row 1, in every verifier.
 - Only an absent `estate` skips the check. In the Node kit `null` is an unreadable source; in Python, where `None` is
   the absent value, pass a function returning `None` for a source that has nothing.
@@ -117,6 +118,11 @@ of `[A-Za-z0-9][A-Za-z0-9_-]{0,127}`. Absent is `personal`; `null` is not absent
   names the keys that are a partner's (`kid`, `partner: org:<id>`, `contexts`); a placement under such a key is in one
   of the organization contexts listed, never `personal` or another organization. A key is scoped once, and only a key
   `publisherKeys` pins. A key no scope names keeps DEC-0051's meaning, trusted in any context.
+- **Update a copied kit before a revision carries `publisherScopes`.** A service runs the copy of the kit it was built
+  with; a copy older than 0.39.0 does not read `publisherScopes`, so it trusts a partner's key in every context and
+  finds no rule broken. A service that applies the estate record updates its copy first:
+  `fabric_kit.py install <dir> --module fabric_estate` (or `--lang node --module fabric-estate`). Since 0.40.0 the
+  estate reader imports the kit's core modules, so the one file alone no longer loads ([kit modules](kit-modules.md)).
 
 Every rule is total on hostile JSON, as the contract's are: an `instancePath` names an item by its index as written (a
 non-object before it does not shift it), and a value whose own `toString` member is data is shown as its JSON. Both kits