@passioncode-ai/fabric-agent-adapter 0.82.0 → 0.84.1

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

@@ -51,13 +51,15 @@ record, which, not `decisions.jsonl` (one line per message id decided), counts t
 `on_handoff` again, so the repair step bounds its retries (one repair is the practices') and passes any further
 hand-off to the person's channel. A copy of `support_agent.py` made before 0.55.0 takes no `on_handoff` in
 `from_config` and hangs on such a call (`grep -c ReentryError support_agent.py` prints 0 for it; `fabric_kit.py
-status` covers the kit modules only): copy it again. The recipe also lacks three parts of such an agent: the Lookup
+status` covers the kit modules only): copy it again. The recipe also lacks two parts of such an agent: the Lookup
 (shared words, best three) is a relevance rule of its own, where the agent reads the knowledge service's per-item
-`answer` flag and puts small closed rule sets into the prompt whole; `from_config` accepts a same-vendor fallback,
-refused only per call as `model:config`; and the decision does not record which model answered, so fallback recoveries
-are not counted. The recipe hands off nothing for `policy`: the calling service routes the categories a person must
-handle (refunds, unbans, account recovery) before it calls the recipe, or a model's `HANDOFF` on them is counted as a
-false knowledge gap. Count its hand-offs by cause: a failed check is a refusal for the agent to repair, research and
+`answer` flag and puts small closed rule sets into the prompt whole; and the decision does not record which model
+answered, so fallback recoveries are not counted. A fallback of the writer's own vendor is refused when the agent is
+built (`RecipeError`), not per call. **A person's categories come first** (since 0.83.0): `policy` (a config key, or
+`policy=` on `SupportAgent`) maps each category a person must handle to the words that name it
+(`{"refund": ["refund", "money back"], "recovery": ["recover my account"]}`); a message holding one is a hand-off
+`policy:<category>` before any lookup or model call, so a refund is never a false knowledge gap. Count `policy:*`
+as `policy`, never `inability`. Count its hand-offs by cause: a failed check is a refusal for the agent to repair, research and
 hold, and only a hold on the material counts as `inability` (a hold after an outage or at the research time cap is
 `infrastructure`); `unsupported:amount` is a money reason, never researched, and so is `unsupported:number` unless the
 refused `draft` shows the number is not a price; `no-knowledge` and `model-unsure` are `inability`;
@@ -99,7 +101,8 @@ python3 <adapter>/plugins/fabric-agent-adapter/skills/building-fabric-services/s
   install <service>/support --lang py --module fabric_openrouter --module fabric_usage --module fabric_paths \
   --module fabric_connections
 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
+python3 <adapter>/.../fabric_kit.py status <service>/support      # the kit modules: current, older or modified
+# support_agent.py is not a kit module: compare it with the recipe's copy (diff) after each adapter release
 ```
 
 ## The knowledge file as a source
@@ -137,7 +140,8 @@ FAC-SEM-162 to 165 (rule `channel-agent.declaration`).
 
 | Key | Meaning |
 |---|---|
-| `knowledge` | the knowledge file: `{"entries": [{"id", "question", "answer", "tags"}]}`, ids unique |
+| `knowledge` | the knowledge file: `{"entries": [{"id", "question", "answer", "tags"}]}`, ids unique and citable (no colon, at most 64) |
+| `policy` | optional: `{category: [words]}`, the categories a person handles, routed before the lookup and the model |
 | `knowledgeMaxAgeSeconds` | optional: the knowledge file is then a source with an age and a last good version (above) |
 | `stateDir` | the decisions (`decisions.jsonl`), the handoff outbox (`handoffs.jsonl`) 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) |
@@ -169,15 +173,26 @@ Exit 1 on a broken config or knowledge file. A missing key is not a crash: the m
 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 `from_config` or `SupportAgent` to route
 handoffs to the operator's channel instead of the outbox file. A handoff carries the customer's text as `question` and
-its time as `at`.
-
-## Retention: the outbox keeps what customers wrote
-
-Every handoff row in `handoffs.jsonl` holds the customer's own message, which can carry an email address, a phone
-number or a card number. It stays until it is pruned. Choose a retention the product's privacy policy states, at most
-30 days for an agent that answers people (the standard's A1). A1 also asks for the text redacted: the outbox keeps it
-as written, and `prune` takes any `--keep-days`, so such an agent passes an `on_handoff` that redacts what it stores,
-which replaces the outbox, and keeps 30 days or fewer. A refused `draft`, which can echo what the customer wrote,
+its time as `at`. The handler catches `ReentryError` before `RecipeError` (it is a subclass) and answers it as the
+service's own fault, never the caller's: a retry of the same message id would pay for its draft again. From inside
+`on_handoff` on the same thread, `agent.prune(...)` completes (the agent's lock is reentrant, held by a test), while
+`agent.answer(...)` is refused with `ReentryError` before any input check, so even a bad id or an empty text there is a
+`ReentryError`.
+
+A Node agent (the communication template's) runs the same checks with `support-agent.mjs`: `checkReply(draft, question,
+given, {maxChars, sources})`, the twin of `check_reply`, answers every case in
+`test/fixtures/support-check-reply-cases.json` as Python does. Knowledge ids are what a citation can name: letters,
+digits, `.`, `_` and `-`, at most 64; an entry whose id has a colon or is longer is refused at load (map it).
+
+## Retention: the outbox keeps what customers wrote, redacted
+
+Every handoff row in `handoffs.jsonl` holds the customer's message as `question`, redacted since 0.83.0: `redact()`
+replaces an email address, a card number, a phone number or other long digit run, and a long key-shaped run with a
+marker (`[email]`, `[card]`, `[number]`, `[secret]`) before the row is written (the standard's A4 and A9). The rest
+stays until it is pruned. Choose a retention the product's privacy policy states, at most 30 days for an agent that
+answers people (the standard's A1). An agent that passes its own `on_handoff` replaces the outbox and keeps its own
+store: it redacts what it stores (`support_agent.redact` is there to call) and prunes that store itself, since `prune`
+covers only `handoffs.jsonl` and `decisions.jsonl`. A refused `draft`, which can echo what the customer wrote,
 reaches the returned decision and an `on_handoff` the agent passes, never a file: neither `decisions.jsonl` nor the
 default outbox stores it. A capability handler returns the decision without it: a kit job's result is written to
 the job's file (`fabric_interop`'s job store), so pass `draft` only to the repair step. Prune on a schedule:

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

@@ -12,5 +12,9 @@
   "prices": {
     "deepseek/deepseek-v4.1-flash": {"prompt": 0.0000002, "completion": 0.0000008},
     "qwen/qwen3.8-flash": {"prompt": 0.0000001, "completion": 0.0000004}
+  },
+  "policy": {
+    "refund": ["refund", "money back", "chargeback"],
+    "recovery": ["recover my account", "account was stolen"]
   }
 }

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

@@ -0,0 +1,115 @@
+// The code checks of the support-agent recipe for a Node agent (FAA-264 item 10): checkReply, the gate the
+// communication template runs on every final text, and what it reads (unsupported, scriptOf). The twin of
+// support_agent.py's check_reply; both answer the cases in test/fixtures/support-check-reply-cases.json the same way.
+// Python's Unicode classes are written out (\w as [\p{L}\p{N}_], \d as \p{Nd}, \b as lookarounds), since a JavaScript
+// \w, \d and \b are ASCII. Node 20+, no dependency.
+const W = '\\p{L}\\p{N}_';
+const LETTER = '\\p{L}\\p{Nl}\\p{No}'; // Python's [^\W\d_]: a word character that is no decimal digit and no underscore
+const DASHES = new RegExp(`[\\u2012\\u2014\\u2015\\u2e3a\\u2e3b\\ufe58]|--|(?<=[${LETTER}])[ \\u00a0][-\\u2013]\\s(?=[${LETTER}])`, 'u');
+const CITATION = /\[KB:([A-Za-z0-9][A-Za-z0-9._-]{0,63})\]/g;
+const URL_RUN = /https?:\/\/\S+/gu;
+const CCTLD = ('ac ad ae af ag ai al am ao aq ar as at au aw ax az ba bb bd be bf bg bh bi bj bm bn bo br bs bt bw by bz ca '
+  + 'cc cd cf cg ch ci ck cl cm cn co cr cu cv cw cx cy cz de dj dk dm do dz ec ee eg er es et eu fi fj fk fm fo '
+  + 'fr ga gd ge gf gg gh gi gl gm gn gp gq gr gs gt gu gw gy hk hm hn hr ht hu id ie il im in io iq ir is it je '
+  + 'jm jo jp ke kg kh ki km kn kp kr kw ky kz la lb lc li lk lr ls lt lu lv ly ma mc md me mg mh mk ml mm mn mo '
+  + 'mp mq mr ms mt mu mv mw mx my mz na nc ne nf ng ni nl no np nr nu nz om pa pe pf pg ph pk pl pm pn pr ps pt '
+  + 'pw py qa re ro rs ru rw sa sb sc sd se sg sh si sk sl sm sn so sr ss st su sv sx sy sz tc td tf tg th tj tk '
+  + 'tl tm tn to tr tt tv tw tz ua ug uk us uy uz va vc ve vg vi vn vu wf ws ye yt za zm zw');
+const GTLD = ('com net org info biz edu gov mil int app dev xyz online site shop store tech cloud email link live news blog '
+  + 'page help support pro club top vip one world today space website mobi name travel agency company services '
+  + 'solutions digital network media studio design money finance bank pay refund claim click download win '
+  + 'рф рус укр бел срб');
+const TLDS = [...new Set(`${CCTLD} ${GTLD}`.split(' '))].sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0)).join('|');
+const STOP = '[^\\s<>()"\'\\[\\]]';
+const LINK = new RegExp(`(?:(?<![${W}])https?://|(?<![${W}@.-])www\\.)${STOP}+`
+  + `|(?<![${W}@.\\-/])(?:[\\p{L}\\p{N}](?:[${W}-]{0,61}[\\p{L}\\p{N}])?\\.)+(?:${TLDS})(?![${W}-])(?::\\p{Nd}{1,5})?(?:[/?#]${STOP}*)?`, 'giu');
+const EMAIL = new RegExp(`[${W}.+-]+@[${W}-]+(?:\\.[${W}-]+)+`, 'gu');
+const PHONE = new RegExp(`(?<![${W}+])\\+?\\p{Nd}(?:[ ().-]{0,2}\\p{Nd}){6,}`, 'gu');
+const CURRENCY = { $: 'usd', '€': 'eur', '£': 'gbp', '¥': 'jpy', '₽': 'rub', '₹': 'inr', dollar: 'usd', dollars: 'usd', euro: 'eur', euros: 'eur', pound: 'gbp', pounds: 'gbp' };
+const CODES = 'usd|eur|gbp|jpy|rub|inr|chf|cad|aud|cny|uah|pln|try';
+const UNIT = `[$\\u20ac\\u00a3\\u00a5\\u20bd\\u20b9]|(?<![${W}])(?:${CODES}|dollars?|euros?|pounds?)(?![${W}])|руб[${W}]*`;
+const NUM = '\\p{Nd}+(?:[.,]\\p{Nd}+)*';
+const AMOUNT = new RegExp(`(${UNIT})\\s?(${NUM})|(${NUM})\\s?(${UNIT})`, 'giu');
+const NUMBER = new RegExp(NUM, 'gu');
+const TRAILING = ".,;:!?'\")]";
+export const SCRIPTS = Object.freeze([
+  ['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]]],
+]);
+
+/** The script most of a text's letters are written in (citations and URLs left out), or null without letters. */
+export function scriptOf(text) {
+  const counts = new Map();
+  for (const ch of text.replace(CITATION, ' ').replace(URL_RUN, ' ')) {
+    const code = ch.codePointAt(0);
+    const hit = SCRIPTS.find(([, ranges]) => ranges.some(([lo, hi]) => lo <= code && code <= hi));
+    if (hit) counts.set(hit[0], (counts.get(hit[0]) ?? 0) + 1);
+  }
+  let best = null;
+  for (const [name, n] of counts) if (best === null || n > counts.get(best) || (n === counts.get(best) && name > best)) best = name;
+  return best;
+}
+
+const currency = (unit) => {
+  const lowered = unit.toLowerCase();
+  return lowered.startsWith('руб') ? 'rub' : (CURRENCY[lowered] ?? lowered);
+};
+
+function linkKey(link) {
+  let key = link.replace(/^https?:\/\//i, '');
+  while (key && (TRAILING + '/').includes(key[key.length - 1])) key = key.slice(0, -1);
+  const cut = key.search(/[/?#]/);
+  return cut < 0 ? key.toLowerCase() : key.slice(0, cut).toLowerCase() + key.slice(cut);
+}
+
+const rstrip = (text, chars) => { let end = text.length; while (end && chars.includes(text[end - 1])) end -= 1; return text.slice(0, end); };
+
+function claims(text) {
+  const amounts = new Set();
+  for (const m of text.matchAll(AMOUNT)) amounts.add(JSON.stringify([currency(m[1] ?? m[4]), m[2] ?? m[3]]));
+  return {
+    url: new Set([...text.matchAll(LINK)].map((m) => linkKey(m[0]))),
+    email: new Set([...text.matchAll(EMAIL)].map((m) => rstrip(m[0], TRAILING).toLowerCase())),
+    phone: new Set([...text.matchAll(PHONE)].map((m) => m[0].replace(/\P{Nd}/gu, ''))),
+    amount: amounts,
+    number: new Set([...text.matchAll(NUMBER)].map((m) => m[0])),
+  };
+}
+
+/** unsupported:<kind> for each kind of claim in the reply that the source text does not carry. */
+export function unsupported(reply, source) {
+  const said = claims(reply);
+  const known = claims(source);
+  const problems = [];
+  for (const kind of ['url', 'email', 'phone', 'amount', 'number']) {
+    const missing = kind === 'phone'
+      ? [...said[kind]].filter((c) => ![...known[kind]].some((k) => k.endsWith(c)))
+      : [...said[kind]].filter((c) => !known[kind].has(c));
+    if (missing.length) problems.push(`unsupported:${kind}`);
+  }
+  return problems;
+}
+
+/** What code can prove about a draft: {ok, problems, citations, reply}; the twin of support_agent.check_reply. */
+export function checkReply(draft, question, given, { maxChars, sources = {} } = {}) {
+  const problems = [];
+  const cited = [...new Set([...draft.matchAll(CITATION)].map((m) => m[1]))];
+  if (!cited.length) problems.push('no-citation');
+  const unknown = cited.filter((c) => !given.includes(c));
+  if (unknown.length) problems.push(`unknown-citation:${unknown.join(',')}`);
+  if (DASHES.test(draft)) problems.push('dash');
+  const reply = draft.replace(CITATION, '').replace(/[ \t]+/g, ' ').replaceAll(' .', '.').replaceAll(' ,', ',').trim();
+  if (!reply) problems.push('empty');
+  else if ([...reply].length > maxChars) problems.push('too-long');
+  problems.push(...unsupported(reply, cited.filter((c) => given.includes(c)).map((c) => (Object.hasOwn(sources, c) ? sources[c] : '')).join('\n')));
+  const wanted = scriptOf(question);
+  const written = scriptOf(reply);
+  if (wanted && written && wanted !== written) problems.push(`script:${written}-not-${wanted}`);
+  return { ok: problems.length === 0, problems, citations: cited, reply };
+}

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

@@ -58,7 +58,8 @@ _DASHES = re.compile(r"[\u2012\u2014\u2015\u2e3a\u2e3b\ufe58]|--|(?<=[^\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}")
+_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}")  # a message id
+_ENTRY_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}")  # a knowledge id: exactly what _CITATION can name
 # What a reply may carry only when the entries it cites carry it (D6): a link, an address, a phone number, an amount,
 # a number. The customer's message never counts: an instruction hidden in it is exactly what this refuses.
 # A bare host is a link only when its last label is a top-level domain people write in prose: every two-letter
@@ -154,8 +155,10 @@ class Knowledge:
     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, dict) or not isinstance(entry.get("id"), str) or not _ENTRY_ID.fullmatch(entry["id"]):
+                # the citation's own grammar (FAA-264): an id with a colon or over 64 characters could never be cited
+                raise RecipeError("every knowledge entry has an id a citation can name: letters, digits, '.', '_' or "
+                                  "'-', up to 64 (map one that has a colon)")
             if not isinstance(entry.get("answer"), str) or not entry["answer"].strip():
                 raise RecipeError("knowledge entry %s has no answer" % entry["id"])
             if "question" in entry and not isinstance(entry["question"], str):
@@ -452,10 +455,52 @@ def prune(state_dir: Path, keep_days: int, *, now: Optional[datetime] = None) ->
     return removed
 
 
+def check_policy(policy: Mapping[str, Any]) -> Dict[str, List[str]]:
+    """Categories only a person handles (refunds, account recovery, legal), each a list of words or phrases; a message
+    that holds one is routed to a person before the lookup and the model, so a refund is never a knowledge gap."""
+    checked: Dict[str, List[str]] = {}
+    for category, phrases in dict(policy).items():
+        if not isinstance(category, str) or not _ENTRY_ID.fullmatch(category):
+            raise RecipeError("a policy category is a short id (letters, digits, '.', '_' or '-')")
+        if not isinstance(phrases, list) or not phrases or not all(isinstance(p, str) and p.strip() for p in phrases):
+            raise RecipeError("policy %s lists the words that route a message to a person" % category)
+        checked[category] = [p.strip().lower() for p in phrases]
+    return checked
+
+
+def policy_route(policy: Mapping[str, List[str]], text: str) -> Optional[str]:
+    """The first category whose phrase the message holds (whole words, any case), or None."""
+    lowered = " %s " % " ".join(_WORD.findall(text.lower()))
+    for category, phrases in policy.items():
+        if any(" %s " % " ".join(_WORD.findall(p)) in lowered for p in phrases):
+            return category
+    return None
+
+
+_REDACT = (
+    (re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+"), "[email]"),
+    (re.compile(r"(?<!\w)(?:\d[ -]?){13,19}(?!\w)"), "[card]"),
+    (re.compile(r"(?<![\w+])\+?\d[\d ()-]{6,}\d(?!\w)"), "[number]"),
+    (re.compile(r"[A-Za-z0-9+/=_-]{32,}"), "[secret]"),
+)
+
+
+def redact(text: str) -> str:
+    """The customer's text as the outbox keeps it: an address, a card or phone number, and a long key-shaped run
+    replaced by a marker, so a person reading the queue never reads a code or a key the customer pasted."""
+    for pattern, marker in _REDACT:
+        text = pattern.sub(marker, text)
+    return text
+
+
 class SupportAgent:
     def __init__(self, *, knowledge: Union[Knowledge, "KnowledgeSource"], 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):
+                 on_handoff: Optional[Callable[[Dict[str, Any]], None]] = None,
+                 policy: Optional[Mapping[str, Any]] = None):
+        if fabric_openrouter.vendor(model) and fabric_openrouter.vendor(model) == fabric_openrouter.vendor(fallback):
+            raise RecipeError("the fallback is a model of another vendor than %s (refused at load, FAA-116)" % model)
+        self.policy = check_policy(policy or {})
         self.knowledge, self.client = knowledge, client
         self.model, self.fallback = model, fallback
         self.state_dir = Path(state_dir)
@@ -492,6 +537,8 @@ class SupportAgent:
         # The outbox keeps the customer's own text until it is pruned: see `prune` and the README's retention note.
         fabric_paths.ensure_private_dir(self.state_dir)
         kept = {k: v for k, v in decision.items() if k != "draft"}  # a person reads the question and the reasons
+        if isinstance(kept.get("question"), str):
+            kept["question"] = redact(kept["question"])  # what a person reads carries no code, key, card or address
         line = json.dumps(kept, ensure_ascii=False, separators=(",", ":")) + "\n"
         _append_line(self.state_dir / "handoffs.jsonl", line.encode("utf-8"))
 
@@ -509,6 +556,9 @@ class SupportAgent:
         rewrites the draft once with the refusal's reasons: a pass is a reply with `repaired: true`, and a repair that
         does not end in a reply (a second refusal, a model `HANDOFF`, no knowledge on the retry; not a `model:*`
         outage) a hand-off with `fallback: true` (the channel-agent standard's 4.4 and 13.2, FAA-197)."""
+        if getattr(self._local, "in_handoff", False):  # first, so a bad input from on_handoff is a ReentryError too
+            raise ReentryError("answer() was called from on_handoff: queue the hand-off and call answer() again after "
+                              "this call returns")
         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():
@@ -518,9 +568,6 @@ class SupportAgent:
                               "decision or the on_handoff copy (a repeat returns no draft, and a fallback had its repair)")
         if repair is not None and repair.get("messageId") == message_id:
             raise RecipeError("repair= runs under a new message id: the refused one returns its stored decision")
-        if getattr(self._local, "in_handoff", False):
-            raise ReentryError("answer() was called from on_handoff: queue the hand-off and call answer() again after "
-                              "this call returns")
         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._log.get(message_id)
@@ -540,6 +587,9 @@ class SupportAgent:
     def _decide(self, message_id: str, text: str, task_run_id: Optional[str],
                 repair: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
         base = {"messageId": message_id, "citations": [], "costUsd": None}
+        routed = policy_route(self.policy, text)
+        if routed is not None:  # a person's category goes to a person before any lookup or model call (FAA-116)
+            return dict(base, action="handoff", reasons=["policy:" + routed])
         knowledge = self.knowledge.current() if isinstance(self.knowledge, KnowledgeSource) else self.knowledge
         entries = knowledge.lookup(text, self.lookup_limit)
         if not entries:
@@ -571,9 +621,10 @@ class SupportAgent:
 def from_config(config_path: Path, *, on_handoff: Optional[Callable[[Dict[str, Any]], None]] = None,
                 **overrides: Any) -> SupportAgent:
     """An agent from a config file (see config.example.json): paths are relative to the config's folder. `on_handoff`
-    takes each hand-off in place of the outbox. Other keywords go to the model client (`transport`, `deadline_s`,
-    `retries`), except those the config already sets (`ceiling_usd`, `window`, `ledger`, `prices`, `key_env`,
-    `project_id`)."""
+    takes each hand-off in place of the outbox. Other keywords go to the model client as they are: the eleven the
+    config does not set (`base_url`, `attribution`, `unmeasured_call_usd`, `deadline_s`, `retries`, `environ`,
+    `transport`, `sleep`, `clock`, `now`, `rand`); the six it always sets (`ceiling_usd`, `window`, `ledger`, `prices`,
+    `key_env`, `project_id`) are not keywords here. `policy` in the config routes a person's categories first."""
     config = json.loads(Path(config_path).read_text(encoding="utf-8"))
     home = Path(config_path).resolve().parent
     state = (home / config.get("stateDir", "state")).resolve()
@@ -593,7 +644,8 @@ def from_config(config_path: Path, *, on_handoff: Optional[Callable[[Dict[str, A
         knowledge = Knowledge.load(home / config["knowledge"])
     return SupportAgent(knowledge=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)), on_handoff=on_handoff)
+                        max_chars=int(config.get("maxChars", 1200)), on_handoff=on_handoff,
+                        policy=config.get("policy"))
 
 
 def main(argv: Optional[List[str]] = None) -> int:

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

@@ -0,0 +1,98 @@
+# A2A: serving a card and the binding, calling a peer
+
+A service that other agents reach over the open A2A protocol (version 1.0, the contract's A2A peer profile) serves a
+public Agent Card, answers A2A's JSON-RPC binding, and may call other A2A agents. The kit's module is
+`fabric_a2a_server.py` with its Node twin `fabric-a2a-server.mjs` (FAA-10); `fabric_a2a.py` reads the card and the
+well-known member (DEC-0122), and `check_service_a2a.py` holds the probe's A2A rules.
+
+## The card
+
+```python
+from fabric_a2a import a2a_surface
+from fabric_a2a_server import agent_card
+
+card = agent_card(name="Example Agent", description="Drafts notes.", version="0.2.0",
+                  url="http://127.0.0.1:47000/a2a/v1", capabilities=[{"name": "notes.draft", "description": "Drafts a note."}],
+                  security_schemes={"own": {"apiKeySecurityScheme": {"location": "header", "name": "X-Example-Key"}}})
+# serve card at GET /.well-known/agent-card.json, without the service token; declare it:
+well_known["surfaces"]["a2a"] = a2a_surface()
+```
+
+- Each capability is one `AgentSkill`; its id is the capability's name, the id the provider manifest's A2A profile
+  lists in `skillIds`.
+- One interface: the JSON-RPC binding at `url`, `protocolVersion` 1.0. On a local placement the URL is on the service's
+  loopback origin; on a remote one it is https.
+- `agent_card` runs `agent_card_findings` before it returns, so a card that names a member about the running process,
+  holds a value shaped like a credential, names the descriptor's token header as its scheme, or marks a Fabric
+  extension required is never served.
+- **The interface never takes the descriptor's token** (DEC-0122 item 3). It has its own scheme (an API key of its own,
+  OAuth, or none on a loopback interface trusted under HA-3), and the service's `authorize` turns the request's headers
+  into a caller.
+
+## The binding
+
+```python
+from fabric_a2a_server import A2ABinding, agent_message, text_of
+
+def handler(start):                      # a new message
+    if text_of(start.message) == "ping":
+        return agent_message("pong")     # a reply with no task
+    start.start("notes.draft")           # or a task: a job in the interop job store
+    run_in_background(start.task_id)     # the service moves the job: working, request_input, complete, fail
+
+binding = A2ABinding(jobs, handler, skills=["notes.draft"], authorize=lambda headers: keys.get(headers.get("x-example-key")))
+status, body = binding.handle(request_body_bytes, request_headers)   # POST /a2a/v1
+```
+
+| A2A 1.0 | The kit |
+|---|---|
+| `SendMessage` | the handler replies (`{message}`) or starts a job (`{task}`); a message with `taskId` answers an input-required task |
+| `SendStreamingMessage` | `binding.stream(params, caller, rid=...)`: server-sent events, the task first, then a `statusUpdate` at each change, ending at a terminal or input-required state |
+| `GetTask` | the job as a Task |
+| `CancelTask` | `JobStore.cancel`; an ended task answers -32002 |
+| task id | the job id; only the caller that started it reads, answers or cancels it (any other gets -32001) |
+| `TASK_STATE_WORKING`, `_INPUT_REQUIRED`, `_COMPLETED`, `_FAILED`, `_CANCELED` | job `working`, `input_required`, `completed`, `failed`, `cancelled` |
+| an input-required question | the job's elicitation requests in the status message's data part; the answer is a data part `{inputResponses}` as `fabric.job.get` takes it, or plain text for a question of one field |
+| the result | the job's result envelope as the artifact `result`, one data part |
+| a failure | the status message names the job's error message and its code in a data part |
+
+JSON-RPC codes follow A2A 1.0 section 5.4: -32001 task not found, -32002 not cancelable, -32004 unsupported, -32009 an
+`A2A-Version` header that is not 1.0; -32700, -32600, -32601 and -32602 are JSON-RPC's own. A caller `authorize`
+refuses gets HTTP 401; a body over 1 MiB gets 413.
+
+## Calling a peer
+
+```python
+from fabric_a2a_server import A2AClient
+
+client = A2AClient(["https://peer.example"], credential_env="EXAMPLE_PEER_KEY")
+peer = client.discover("https://peer.example")          # {card, url}
+answer = client.call(peer["url"], "Draft a note about Monday.")
+client.get(peer["url"], answer["task"]["id"]); client.cancel(peer["url"], answer["task"]["id"])
+```
+
+- **Only the operator's origins.** The client reaches an origin in its list, and the interface the card names must be
+  on one too.
+- **The key from the environment.** `credential_env` names a variable that `use_secret.py run --vault-only <project>
+  <NAME> -- <command>` fills; the client never reads a key file beside the agent, and an error never carries the key.
+- **Bounded.** Each call has a deadline (30 s) and a size cap (1 MiB) through `fabric_http`, follows no redirect and
+  never retries a `SendMessage`. A plain `http://` URL is refused unless it is loopback (and then its listener must be
+  this account's) or the client is built with `insecure=True`.
+
+## The probe
+
+`check_service_a2a.py <origin> [--remote] [--key-env NAME] [--probe-text TEXT]` reads `surfaces.a2a`, the card,
+the interface and the binding's refusals (`a2a.surface`, `a2a.card`, `a2a.interface`, `a2a.task-not-found`, `a2a.cancel-not-found`,
+`a2a.method-not-found`); `a2a.task-states` runs only with a message the service names as safe to send, since any
+message may start real work. An interface that answers 401 without `--key-env` makes the binding rows NOT_RUN.
+
+It is a command of its own, not a part of `check_service.py`: that probe's `a2a.card` reads the public card with no
+Authorization header and never calls the card's interfaces (D5), while this one calls the interface with the
+interface's own key. Run both for a service that serves A2A.
+
+## Not here yet
+
+- The interop test against a live Hermes A2A endpoint (`a2a_discover`, `a2a_call`): it waits for a Hermes A2A endpoint
+  reachable on this machine (FAA-10).
+- The sample service serving both MCP and A2A.
+- The REST and gRPC bindings, push notifications and `ListTasks`.

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

@@ -48,6 +48,16 @@ repository-relative path at a commit, an eval report). A decision without a numb
 | building-fabric-services | at each release | contribute the release's measured wins as success cases and its new technical decisions |
 | working-with-fabric | the retro after work | a lesson with a measured effect is also a success case: contribute it beside the lesson it records |
 
+## A template and the communication prompt
+
+For an agent that talks with people on a channel, the database's template and creating-fabric-agents' communication
+agent prompt (`references/communication-agent-template.md`) are read together, never as two templates (the database's
+own rule). Where they disagree, the template wins, in every part and not only the first-release ones: it is the merged
+practice of the agents of its kind. A part the prompt carries and the template lacks (a first-release part, a check, a
+pipeline step) is built too, unless the template rules it out, and goes back to the database as feedback on that
+template (`agents-db.contribute`); the completion report names each such part. Without a template for the kind, the
+prompt is the recipe.
+
 ## Recording the template
 
 An agent built from a template declares it: `provenance.template` with its id and version, so a later template

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

@@ -121,7 +121,7 @@ body (contract project-comms.md, DEC-0125 MD-3). The kit cannot tell his persona
   any other id as written. The mandate is a block fenced ` ```json `, the opening and the closing fence each at the start
   of its own line, with no indent (lowercase; an indented fence, as inside a list item, is not read either; ` ````json `, ` ```JSON ` and `~~~` are not read), whose value has `kind: "mandate/1"`; any other JSON
   block, a decision block included, is not read, with no warning. A fence quoted inside another fenced block is still
-  read: quote an example in prose, not in a fence. Two `mandate/1` blocks, whoever their chains end in, or one whose text holds `mandate/1` and is
+  read: quote an example in prose, not in a fence. Two `mandate/1` blocks, whoever their chains end in, or one whose text holds `mandate/1` (its slash plain or JSON-escaped, `\/` or `\u002f`, FAA-196 (13)) and is
   not JSON (`NaN` included), read as none (a broken block without `mandate/1` is skipped, and a mandate beside it
   is still read), and the responder emits `board.request.mandate_unread` (a warning) with the
   request id and its `reason`, `mandate-blocks` or `mandate-unreadable`: the block holds his words, which reach no event, log or
@@ -131,6 +131,10 @@ body (contract project-comms.md, DEC-0125 MD-3). The kit cannot tell his persona
   than 4300 digits on every Python (the kit refuses it there, as `int_max_str_digits` does from 3.11 and
   the 3.8.14, 3.9.14 and 3.10.7 security releases; a limit configured
   lower, `PYTHONINTMAXSTRDIGITS` on a Python that has one, refuses an integer longer than it).
+- A request transferred to a new session runs again from a fresh `com.get`. Its mandate is read only when the message
+  read back carries the digest the claim took and names this request, capability and Project, as the first claim
+  checks; otherwise it is worked without one, and `board.request.mandate_unread` names `digest-mismatch` or
+  `not-addressed` (FAA-196 (1)).
 - The handler gets `ctx.mandate` (the one block without `source`, or None) and `ctx.mandate_covers(call)` (Node
   `ctx.mandateCovers(call)`, `call` being `{capability, action?, effect, spendUsd?, project?}`: pass `project` when the work
   acts in one, since a call naming none is not limited by the mandate's `projects`; both are read failing closed, as
@@ -145,7 +149,12 @@ body (contract project-comms.md, DEC-0125 MD-3). The kit cannot tell his persona
   spend; all five are read up front, whatever the scope limits, so a member that raises raises to the handler (in
   Python a `KeyError` reads as not named), and a Python mapping's default, a `defaultdict`'s
   included, is read as named, the `defaultdict` gaining the key): `mandate_covers` with `tier: "T1"`, `self` the service's `agent_id`, no `callerAgent` (the
-  board names a Project's principal, not an agent id the chain can bind, so the chain's end alone binds it) and the
+  board names a Project's principal, not an agent id the chain can bind, so the chain's end alone binds it), unless the
+  service passes `identify_agent=` (Node `identifyAgent`, FAA-135): a function of the request's sender (`{project,
+  principal}`, as the board verified it) answering the agent id the service authenticates for it, or None; asked only
+  when a mandate travelled, its agent id must be the one before `agent_id` in the chain, and an id the registry
+  refuses, an answer that is not a string or a hook that raises fails closed (`mandate-not-for-this-call`), as
+  [interop](interop.md) reads `identify_agent`; and the
   responder's wall clock (`wall=`: seconds, `time.time` by default; Node milliseconds, `Date.now`; one that returns a value
   that is not a finite number answers `{"fault": "now-unreadable"}`; a clock that raises passes its error to the handler). It answers `{"ok": True, "recordAs": {by, via: "mandate", task,
   chain, caller}}` (`caller` the sender Project, as MD-3 records it; a sender that names no Project is never read), a
@@ -180,7 +189,7 @@ body (contract project-comms.md, DEC-0125 MD-3). The kit cannot tell his persona
 | `authority_changed`, `not_authorized` | stop claiming; one `board.access.needed` event (notify) saying what to ask for (except `not_authorized` on the move-back claim of a moved slot, read as another session's slot, [below](#when-the-operator-moves-a-slot-to-another-session-faa-155)) |
 | `fenced` on enroll or claim | another live holder: wait for it to lapse; never replace it on its own initiative. When this responder recorded holding the slot, it first reads `com.status`: a newer generation means the slot [moved](#when-the-operator-moves-a-slot-to-another-session-faa-155), and it is not taken again even after that holder lapses |
 | lost after an effect began | keep the entry as `unknown`; `observe(entry)` is asked to settle it with `com.reconcile` |
-| Fabric down, hub missing | bounded backoff (2 s doubling to 5 minutes, jittered), one `board.down` event, no spinning |
+| Fabric down, hub missing | bounded backoff (2 s doubling to 5 minutes, jittered), one `board.down` event, no spinning; a board that flaps is said down once until it stays up `DOWN_QUIET_SECONDS` (300 s, FAA-187 (22)) |
 | one call without an answer while the lease holds | `board.down`, but the session and the running work stay; the call goes again, with the same key, before the lease lapses |
 | `revision_conflict` on `com.renew` or `com.progress` | they store nothing: the revision is read again (`com.get`) and the call sent once more; a second one loses the attempt |
 | `idempotency_conflict` | a key sent with other content is a defect, not an outage: `board.blocked` (notify) naming it, and the session is left |
@@ -311,10 +320,10 @@ held and not transferred). The responder keeps that move instead of undoing it:
   Fabric release through v0.3.19 (2026-11-11) offers the operator's move (the control is CT-174's in Fabric, its agent twin CT-181 in the contract, then CT-125),
   so today every move is another session taking the slot and take-back is the route back; the check below is ready
   for the move. While
-  a slot is moved the responder reads `com.status` once a renewal (20 s) and, when the slot's generation is past the
+  a slot is moved the responder reads `com.status` once a renewal (20 s; one read a tick for every moved slot, FAA-194 (5)) and, when the slot's generation is past the
   recorded move, sends one `com.claim` under a fresh key, as PR-2's "Learning the slot is its own" says (FAA-165,
   0.60.0); the move itself drops the claim key of that capability, whose receipt the move made dead. A claim that
-  lands is the slot held again: the record loses `moved`, the request it handed out is worked (with none, its own
+  lands is the slot held again (`board.slot.returned`, info, says so; FAA-194 (8)): the record loses `moved`, the request it handed out is worked (with none, its own
   enroll renews the lease at once), accepted work left `lapsed` comes back with a transfer, and a later move is said
   again. `lease_expired` (the move reached this session and its lease lapsed first) enrolls again. `held` asks again
   at the next renewal. `idempotency_window_expired` or `capacity_exceeded` asks again at the next renewal under a
@@ -323,7 +332,7 @@ held and not transferred). The responder keeps that move instead of undoing it:
   recorded as `moved` at that generation, so it is not asked about twice. A claim whose answer was lost (`unreachable`) is asked again under the same key at the next renewal, so a claim that
   landed is not stranded; until then it counts as at most a lease from that key's first send (a fresh key starts
   its own, and it counts only while more than the 10 s margin of that lease is left, then no more, as a lapsed slot), so a second lost answer keeps
-  the session (finding 38). A replayed receipt from a generation older than `com.status` shows (a move away and back meanwhile) is
+  the session (as any call without an answer does while a lease holds: the failure table above; FAA-194 (34)). A replayed receipt from a generation older than `com.status` shows (a move away and back meanwhile) is
   dead: its key is dropped and a fresh key asks at the next renewal. A take-back drops the capability's claim key too, so a request a move-back claim handed out while the take-back raced
   it waits for its attempt's lease (60 s) before it is claimed again (a take-back that lands before the move-back check makes its claim key
   leaves that key to the claim loop, which works the request at once). Nothing is asked while the responder stops. It is never an enroll or a replace on a slot another session holds, and it waits
@@ -332,7 +341,9 @@ held and not transferred). The responder keeps that move instead of undoing it:
 - Otherwise only the operator brings the slot back: `take_back(capability)` (`takeBack`) forgets the record, and wins over a move
   being read at the same time: the move is written under the responder's lock (Node: on the fence queue, after any fenced
   call in flight) and only while the record is unchanged (FAA-158). Never edit the
-  checkpoint's `slots` record by hand to undo a move. In the same board
+  checkpoint's `slots` record by hand to undo a move. Once the slot is held again after a take-back (an enroll or a
+  replace lands, in the same process), the kit says `board.slot.returned` (info, once per take-back; FAA-325), as it
+  does for a move back. In the same board
   session the next tick enrolls once the other session lets the slot go (a live holder is waited for) and takes the work
   left `lapsed` back with a transfer. A restart or reconnect before that, with accepted work waiting for the slot, takes it
   back at once by `com.responder_replace`, as a restart did before 0.53.0: the operator asked for the slot back, so the
@@ -345,7 +356,8 @@ held and not transferred). The responder keeps that move instead of undoing it:
   (`interop.well-known-capabilities`): an agent whose MCP client sets `_meta` calls it over `/mcp` with the operator's
   decision in `_meta.decision` (a call without one is `operator-decision-required`); Claude Code and Codex send
   arguments only, so until CT-125 they hand the operator the page as Fabric Dashboards' `open_link`. Either door records
-  the take-back as a `board.slot.returned` event (info, the capability as its subject) whose sentence says the route in
+  the take-back as a `board.slot.taken_back` event (info, the capability as its subject; the slot is still away, so never
+  `board.slot.returned`, which is the kit's and means held again, FAA-325) whose sentence says the route in
   words and whose `data` holds `by`, `via` and the `caller` (none when the feed refuses the caller), never the decision's words; a repeat after a lost answer is answered `{capability, moved: false}`. A service built on the kit declares it as an operator action, a button with its tool ([Every button has a
   tool](../SKILL.md), `fabric-actions/0.1`) with gate `relayed` (the operator's decision), never `none`, so a call
   without the operator's relayed decision is refused; on a server that reads mandates (`agent_id`) it also names its effect class, for example
@@ -385,7 +397,9 @@ checked by FAC-SEM-101 (no credential in data): `board.request.completed`, `boar
 `board.reconcile.needed`, `board.slot.contested`, `board.slot.moved`, `board.slot.refused`, `board.access.needed`, `board.blocked`,
 `board.down`, each notifying episode said once, and `board.outcome.invalid` (warning) when a handler's outcome fails
 its checks and is not sent, and `board.request.mandate_unread` (warning) when a request's mandate is not read (above). The operator's hold (below) adds `board.held`, `board.slot.held`,
-`board.slot.released` and `board.request.waiting`. The reference service adds `board.slot.returned` at a take-back.
+`board.slot.released` and `board.request.waiting`. A slot held again after a move back or a take-back is
+`board.slot.returned` (info). The reference service adds `board.slot.taken_back` at a take-back, when the operator asks
+for the slot (FAA-325).
 
 `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
@@ -405,11 +419,13 @@ Python (`fabric_hub`): `fabric_root(platform, env)`, `locate_hub(root=None, aliv
 `request_board_access(agent_id, project_id, capabilities, reason)`, `poll_access(request_id, poll_secret,
 credential_file)`, `join_board(project_id, credential_file) -> BoardGrant`, `call_door(tool, args)`,
 `call_binding(tool, args, credential_file)`; `pid_alive(pid)` answers True, False, or None for another OS account's
-process (not verified); `Backoff(first=2, cap=300, jitter=0.2, floor=1)`; `HubError(code,
+process (not verified); on Windows it asks OpenProcess for the access Node's `process.kill(pid, 0)` asks (libuv's
+terminate, query and synchronize), so an elevated process of the same user reads None in both kits, as another
+account's does, where limited query access alone would have read it as running (FAA-323); `Backoff(first=2, cap=300, jitter=0.2, floor=1)`; `HubError(code,
 message, retryable, data)`.
 
 Python (`fabric_board`): `Responder(*, hub, project_id, capabilities, credential_file, checkpoint_file, handler,
-admit, observe=None, emit=None, service, now, rand, spawn, session_factory, agent_id=None, mandate_from=None, wall=time.time)`
+admit, observe=None, emit=None, service, now, rand, spawn, session_factory, agent_id=None, mandate_from=None, wall=time.time, identify_agent=None, links=None)`
 with `step()`, `run(stop, drain)`, `shutdown(drain)`, `take_back(capability)`; `WorkContext.progress(note)`,
 `.begin_effect(summary)`, `.stopped`, `.mandate`, `.mandate_covers(call)`; `PERSONAL_BOARD`; `BoardSession(grant)`;
 `Checkpoint(path)`; `comms_canonical(value)`, `comms_digest(operation, value)`, `receipt_problems(value, op)`,
@@ -420,4 +436,4 @@ effect_began)`, `self_check()`; `BoardError`, `Stopped`.
 Node: the same names in camelCase (`locateHub(root, {alive, estate, now})`, `new HubClient(root, {alive, timeout,
 estate, post})`, `new Responder({...})` with async `step()`, `run({signal, drain})`, `shutdown(drain)`,
 `takeBack(capability)`; `await ctx.progress(note)`, `await ctx.beginEffect(summary)`, `ctx.mandate`, `ctx.mandateCovers(call)`;
-the options `agentId`, `mandateFrom` and `wall` (milliseconds); `selfCheck()`). Both kits read and write the same checkpoint file.
+the options `agentId`, `mandateFrom`, `wall` (milliseconds), `identifyAgent` and `links`; `selfCheck()`). Both kits read and write the same checkpoint file. `links` maps a notify kind to the page on the service that resolves it (`{"board.slot.moved": "/#board"}`, a path, as `make_event` takes one): a notice that notifies carries it as `link`, so the banner opens that page; give it only with an emit that takes `link` (`JsonlEventLog.append` does; FAA-187 (21)). A Node emit receives `{notify, subject, link?, data?}` as one object: spread it before its own `subject` or `link` if it sets its own, or the responder's wins (FAA-187 (27)).

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

@@ -37,7 +37,7 @@ const answer = await request('GET', 'https://api.example/v1/items', { headers, d
 | 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 |
-| Plain `http://` to a loopback host goes on a connection whose server end is this OS account's process, told from the socket table before a byte is sent and never through a proxy from the environment (`fabric_peer_owner`); another account's listener, root's, or one whose owner cannot be told is kind `foreign-user`, nothing sent, never retried (on a restricted macOS table its reason says `table-restricted`: protocol.md, FAA-272). The Node twin sends such a request through `node:http` on a checked connection, not `fetch` | | DEC-0154 HA-2: loopback is one per computer, not one per OS account |
+| Plain `http://` to a loopback host goes on a connection whose server end is this OS account's process, told from the socket table before a byte is sent and never through a proxy from the environment (`fabric_peer_owner`); another account's listener, root's, or one whose owner cannot be told is kind `foreign-user`, nothing sent, never retried (on a restricted macOS table its reason says `table-restricted`, which no retry clears, unless this account's own processes hold the accepted socket, DEC-0155 RT-2: protocol.md, FAA-272, FAA-292). The Node twin sends such a request through `node:http` on a checked connection, not `fetch` | | DEC-0154 HA-2: loopback is one per computer, not one per OS account |
 | 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 | | |
@@ -85,7 +85,7 @@ const answer = await client.chat(messages, { model, fallback, maxTokens: 800 });
 | 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 |
-| The base URL | `base_url` (`baseUrl`), by default `https://openrouter.ai/api/v1`: checked by `check_url` when the client is built; ASCII whitespace and trailing `/` at its ends are trimmed (Node also trims every C0 control at the ends and removes a tab or line break anywhere, as `new URL` reads them); a base that is not a string is refused as `check_url` refuses it (`HttpError` kind `refused`, both twins); a query or a fragment is refused (kind `config`, both twins, before `check_url`). Python also refuses a space, a control or a non-ASCII character in the path (`check_url`'s `HttpError` kind `refused`); Node sends it percent-encoded, as `new URL` writes it (FAA-187 (18)) |
+| The base URL | `base_url` (`baseUrl`), by default `https://openrouter.ai/api/v1`: checked by `check_url` when the client is built; ASCII whitespace and trailing `/` at its ends are trimmed (Node also trims every C0 control at the ends); a base that is not a string is refused as `check_url` refuses it (`HttpError` kind `refused`, both twins); a query or a fragment is refused (kind `config`, both twins, before `check_url`). One rule reads the base as both twins send it, before `check_url` (`base_url_problem`, `baseUrlProblem`, FAA-187 (18)): a backslash anywhere, a path holding anything but URL path characters and `%XX` escapes (a space, a control, a tab or line break inside, a character outside ASCII) or a dot segment, escaped or not, is kind `config` in both, where Python refused some and Node sent them percent-encoded or rewritten. A host outside ASCII is kept as urllib dials it, in IDNA, so attribution reads the host the call reaches in both twins (FAA-187 (19)) |
 | 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 |