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

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.40.0 - 2026-10-21
+
+The kits as production modules (FAA-65). Every name a kit module made public at 0.39.1 is still there; a service that
+copies the kit now installs it with `fabric_kit.py install` (one file is no longer enough, see below).
+
+### Added
+
+- **A shared core, once per language** (layer L0 and L1): `fabric_jsvalue` / `fabric-jsvalue.mjs` (JavaScript's view
+  of JSON values: `show`, `js_to_number`, `same`, `json_equal`, `jcs` and the rest), `fabric_time` / `fabric-time.mjs`
+  (strict RFC 3339, UTC days, formatting, day windows, an injectable clock: the public dates API, on shared cases) and
+  `fabric_crypto` / `fabric-crypto.mjs` (Ed25519 and P-256 checks, small-order keys, base64url, sha256). They used to
+  live, twice, inside the estate and delegation readers; every reader now imports them.
+- **The kit is a manifest-listed set, installable as one.** `kit.json` lists every module in dependency order, with the
+  kit modules it imports, its sha256 and the sha256 of every release since 0.8.0. `fabric_kit.py install <dir>`
+  copies a module's closure (data files included); `status <dir>` says `current`, `older` (with its release) or
+  `modified`, and names a module a copy imports but lacks. SKILL.md said the kit was "one self-contained file"; it was
+  not, and a one-file copy of `fabric_service.py` failed in `usage_findings`.
+- **Connectors** (layer L4, both languages, shared cases): `fabric_http` (one deadline across attempts, bounded
+  retries with jittered backoff only when repeating is safe, `Retry-After` up to a cap, a response size cap, redirects
+  answered and never followed, plain http refused off loopback, redacted URLs in errors) and `fabric_openrouter` (the
+  agent's own key from a named environment variable, a spend ceiling checked before every attempt at the worst case
+  with calls in flight reserved, one usage receipt per answered call, empty, `length`, `error` and filtered answers
+  never returned as success, a fallback of another vendor required, 401/402/403 stop at once, attribution off by
+  default). References: `kit-modules.md`, `connectors.md`.
+- **A support-agent recipe** (`building-fabric-services/recipes/support-agent/`): answers a question from a knowledge
+  file through `fabric_openrouter`, accepts a reply only when code proves it (citations exist and were given, no em
+  dash or substitute, the question's script, a length limit), otherwise hands it to a person with the failed checks
+  named; idempotent per message id. `test/validate.py` lets a recipe import the kit modules `kit.json` lists.
+- **Layering held by tests**: a module imports only modules listed before it (a planted cycle is caught), none is over
+  1000 lines across every skill's scripts, the core is defined once, every module is in the module map, and the
+  0.39.1 public API of both facades is a snapshot test.
+
+### Changed
+
+- `fabric_service` / `fabric-service.mjs` and `fabric_board` / `fabric-board.mjs` are facades over modules split by
+  responsibility (base, platform, paths, protocols, lock, usage, backups, descriptor, auth, events, logs, supervisors;
+  board shapes, session, fixture). The probe's rules moved to `check_service_rules.py`. In working-with-fabric,
+  `fabric_session.py` is a facade over `fabric_session_{env,mcp,mail,hosts,cli}.py`; the hooks, the worker and
+  `install-host-hooks` still run the facade.
+- No import cycle is left: `fabric_estate` no longer imports `fabric_delegation`, in both languages.
+- A Node service that imported a module-private helper of `fabric-service.mjs` or `fabric-board.mjs` (not exported at
+  0.39.1, so outside the snapshot) imports it from the module that holds it now.
+- The probe runs the board responder's self-check in a clean Python (`-E -s`, its own working directory), so it reads
+  the kit it names and not a copy already imported.
+
+### Fixed
+
+- **Found by the release review (three blind readings) and fixed before release:** the OpenRouter ceiling counted
+  only the messages, so a large `tools` list could pass it (the worst case now bounds the messages and every param;
+  `models`, `route`, `plugins` and `web_search_options` are refused); an attempt that may have been billed without an
+  answer to read (a timeout, a 200 over the size cap or not JSON) left no receipt (it now records one with no tokens
+  and no cost, counted at the worst case); the Python transport could overrun its deadline on a slowly trickled body
+  (it reads in chunks against one deadline); the twins differed on a lone surrogate, NaN in a body, a transport bug and
+  `http://127.1` (both now behave the same, on shared cases); `fabric_service.py` could not be loaded by its path from
+  another folder (every kit module now puts its own folder on `sys.path`, tested from `/`); `fabric_kit.py status`
+  judged an older copy by the current release's imports and named only direct ones (it now reads each copy's own
+  imports and follows the closure); an unknown `--module` is a usage error (exit 2); the facade keeps `_number`,
+  `_DAY_MS` and `_utc_date_ms`; `install-host-hooks` requires the session helper's new modules; the recipe hands off a
+  message holding bytes a terminal could not decode instead of exiting, and its dash check also catches U+2012 and
+  U+2015.
+- **Found by the second review round and fixed:** a connection cut after a call may have been billed left no receipt
+  (every connection error now records an unmeasured one); `max_completion_tokens` and `n` could raise the output past
+  the bound (refused); an unmeasured call was counted at the current call's worst case (now at its own, while the
+  client runs); Node read a blank or hex price as a number (both twins now read a plain decimal or a number only);
+  Python's deadline started after the headers (it now covers them); `fabric_kit.py status` raised on a copy it could
+  not parse (it reports it `modified`) and now names a missing module's data files; `fabric_http` writes a JSON body
+  byte for byte as `JSON.stringify` (numbers and key order too, through the core's `json_stringify`); loopback edge
+  forms agree in both twins; the recipe's dash check covers U+2E3A, U+2E3B, U+FE58 and no-break spaces, and no longer
+  flags `1 - 2`.
+- **Found by the third review round and fixed:** an answer with no usage was counted at the next call's worst case
+  (now at its own); image, audio and file parts could be sent past the bound (only text content is sent); Python
+  raised outside `OpenRouterError` and kept no receipt on a 400-digit count or cost or JSON nested too deep (both read
+  as unmeasured now); Python's deadline could be held by trickled headers (a watchdog shuts the socket at the
+  deadline); `Response.json()` reads a byte order mark and refuses `NaN` as `JSON.parse` does; a `Retry-After` year
+  before 1000 is no date in either twin.
+- **A usage receipt's project id is checked the same way in both kits.** `fabric_service.py` defined its URI pattern
+  twice and the second won: Python accepted `project_id="urn:"` where Node refused it. Now one pattern per module, and
+  both kits refuse it (a test in each).
+
 ## 0.39.1 - 2026-10-21
 
 Fixes from two rounds of blind review of 0.39.0 (FAA-64).

package/README.md

@@ -54,9 +54,15 @@ that is always alive, runs as one copy, keeps its state through a reinstall and
 in Fabric Dashboards by itself: the `fabric-service/0.1` extension. It also makes an **online** agent
 or dashboard (an `https` origin on a platform) a Fabric service (the remote placement, DEC-0019): the same
 four routes behind the token, a `__Host-` session cookie, and one descriptor on the operator's computer;
-`scripts/sample-remote-service.mjs` is the complete example. It ships Python and
-Node reference kits (`scripts/fabric_service.py`, `scripts/fabric-service.mjs`), a
-complete `scripts/sample_service.py`, and `scripts/check_service.py`, a live probe. A service that answers
+`scripts/sample-remote-service.mjs` is the complete example. It ships the service kit in Python and
+Node: layered modules listed in `scripts/kit.json` behind the `fabric_service` / `fabric-service.mjs` facades,
+installed into a service with `scripts/fabric_kit.py install` and checked with `fabric_kit.py status`
+([kit modules](plugins/fabric-agent-adapter/skills/building-fabric-services/references/kit-modules.md), including
+the dates API); connectors for outbound HTTP and OpenRouter (`fabric_http`, `fabric_openrouter`: one deadline, safe
+retries, the agent's own key, a spend ceiling before every attempt, usage receipts, a fallback model;
+[connectors](plugins/fabric-agent-adapter/skills/building-fabric-services/references/connectors.md)); a ready
+[support-agent recipe](plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/README.md);
+a complete `scripts/sample_service.py`; and `scripts/check_service.py`, a live probe. A service that answers
 requests other Projects post to its Project on Fabric's project board uses the board responder
 (`scripts/fabric_hub.py` and `scripts/fabric_board.py`, Node `fabric-hub.mjs` and `fabric-board.mjs`): the
 `board.respond` grant, enroll, claim, accept the exact digest, complete, a checkpoint before every step, and restarts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.39.1"
+  version: "0.40.0"
   contract-version: "0.1.0"
   contract-commit: "c55f2d5a11c9a0197e958e87212fca7ae1154769"
 ---

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

@@ -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.1"
+  version: "0.40.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "c55f2d5a11c9a0197e958e87212fca7ae1154769"
@@ -144,13 +144,24 @@ The request body is data behind the service's own input gate. Read [the board re
 
 ## 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
+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
 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

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

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/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)).