@passioncode-ai/passioncode 0.2.17 → 0.2.19

package/payload/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/payload/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/payload/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/payload/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": ["пароль", "вход", "аккаунт"]}
+  ]
+}

package/payload/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/payload/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/payload/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/payload/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/payload/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/payload/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.