@passioncode-ai/fabric-agent-adapter 0.81.0 → 0.83.1

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service_channel_agent.py

@@ -18,7 +18,7 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from fabric_jsvalue import indexed_objects, js_keys  # noqa: E402
-from fabric_secrets import JS_SPACE, JWT_SHAPE, SECRET_VALUE, raw_values, secret_argument, secret_url, secret_value  # noqa: E402
+from fabric_secrets import JS_SPACE, SECRET_VALUE, has_jwt, raw_values, secret_argument, secret_url, secret_value  # noqa: E402
 from fabric_secrets import url_parts as _whatwg_url_parts  # noqa: E402 - public since FAA-250
 import check_service_channel_agent_schema as cas  # noqa: E402
 
@@ -208,9 +208,9 @@ def read_as_url(read: str) -> bool:
 
 
 def _url_reading(read: str) -> bool:
-    """secretUrl where read_as_url admits the head, secretArgument otherwise. The kit's secret_url also reads a URL the
-    WHATWG parser refuses (the safe direction for its own callers); the contract's `new URL` throws there and finds only
-    what secretArgument finds, so a refused URL is read by secret_argument alone here."""
+    """secretUrl where read_as_url admits the head, secretArgument otherwise. A URL the WHATWG parser refuses makes the
+    contract's `new URL` throw, which finds only what secretArgument finds, so such a URL is read by secret_argument
+    alone: url_parts answers None for it here, as the kit's secret_url reads it as an argument only since FAA-309."""
     if not read_as_url(read):
         return secret_argument(read)
     return secret_argument(read) or (url_parts(read) is not None and secret_url(read))
@@ -222,7 +222,7 @@ def shaped_read(read: str) -> bool:
 
 def _key_shaped(text: str) -> bool:
     read = head(text)
-    return bool(JWT_SHAPE.search(read) or SECRET_VALUE.search(read))
+    return bool(has_jwt(read) or SECRET_VALUE.search(read))
 
 
 def plain_name(name: str) -> bool:
@@ -397,6 +397,8 @@ def url_parts(text: str) -> Optional[Tuple[str, str]]:
             return None
         if at and hostport == "":
             return None
+        if host == "" and colon > bracket:
+            return None  # an empty host ended by `:`, with an empty port or a port: `new URL` throws
         if host == "" and special and lowered != "file":
             return None
         if host and not _host_ok(host, special):

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service_rules.py

@@ -135,20 +135,31 @@ import fabric_actions as fa  # noqa: E402 - beside this file (DEC-0121)
 import fabric_a2a as fa2  # noqa: E402 - beside this file (DEC-0122)
 
 
-def other_domain_copy(label: object, domain: str) -> Optional[str]:
-    """The other launchd domain when it also has job `label` loaded, a second copy (FAA-286 item 6), else None."""
-    other = ("gui/%d" % getattr(os, "getuid", lambda: 0)()) if domain == "system" else "system"
-    try:
-        out = subprocess.run(["launchctl", "print", "%s/%s" % (other, label)], capture_output=True, text=True, timeout=10)
-    except (OSError, subprocess.SubprocessError):
-        return None
-    return other if out.returncode == 0 else None
+def other_domain_copy(label: object, domain: str, user_name: object = None) -> Optional[str]:
+    """The other launchd domain when it also has job `label` loaded, a second copy (FAA-286 item 6), else None. For a
+    LaunchDaemon (`system`) that is a gui/<uid> domain: first the one of its plist's UserName (`user_name`), where a
+    leftover LaunchAgent of a dedicated account runs (FAA-317), then the probe's own."""
+    if domain == "system":
+        uids = [_sup._account_uid(user_name)] if isinstance(user_name, str) and user_name else []
+        uids.append(getattr(os, "getuid", lambda: 0)())
+        others = ["gui/%d" % uid for i, uid in enumerate(uids) if uid is not None and uid not in uids[:i]]
+    else:
+        others = ["system"]
+    for other in others:
+        try:
+            out = subprocess.run(["launchctl", "print", "%s/%s" % (other, label)], capture_output=True, text=True,
+                                 timeout=10)
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if out.returncode == 0:
+            return other
+    return None
 
 
 def in_launch_daemons(plist_path: Path) -> bool:
-    """Whether a plist sits in /Library/LaunchDaemons, where launchd loads it at boot as a LaunchDaemon (FAA-278)."""
-    folder = re.sub(r"^/{2,}", "/", str(Path(os.path.abspath(str(plist_path))).parent))
-    return folder.lower() == str(_sup.SYSTEM_DAEMONS).lower()  # the supervisors' own, which a test may point elsewhere
+    """Whether a plist sits in /Library/LaunchDaemons, where launchd loads it at boot as a LaunchDaemon (FAA-278): the
+    supervisors' own rule, imported (FAA-317), which a test may point elsewhere through their SYSTEM_DAEMONS."""
+    return _sup._in_daemons(plist_path)
 
 
 def plist_problems(plist: dict, label: object, token: object = None, *, system: bool = False,

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-a2a-server.mjs

@@ -0,0 +1,274 @@
+// The serving side and a bounded client of A2A 1.0 (FAA-10, DEC-0122): an Agent Card built from the service's
+// capabilities (agentCard, checked by agentCardFindings before it is served), the JSON-RPC binding (A2ABinding:
+// SendMessage, SendStreamingMessage, GetTask, CancelTask) mapped onto the interop job store (a task is a job, a choice
+// stop is TASK_STATE_INPUT_REQUIRED, the result envelope an artifact), and A2AClient (discover, call, get, cancel)
+// that reaches a peer only on an origin the operator allowed, its credential read from the environment use_secret.py
+// run fills. The interface never takes the descriptor's token (DEC-0122 item 3).
+// Part of the Node service kit (layer L4); the twin of fabric_a2a_server.py. Node 20+, no dependency.
+import crypto from 'node:crypto';
+import { A2A_PROTOCOL_VERSION, A2A_SURFACE_PATH, agentCardFindings } from './fabric-a2a.mjs';
+import { ServiceError } from './fabric-base.mjs';
+import { InteropError, UnknownJob } from './fabric-interop-rules.mjs';
+import { request as httpRequest } from './fabric-http.mjs';
+
+export const JSONRPC_BINDING = 'JSONRPC';
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+export const TASK_NOT_FOUND = -32001;
+export const TASK_NOT_CANCELABLE = -32002;
+export const UNSUPPORTED_OPERATION = -32004;
+export const CONTENT_TYPE_NOT_SUPPORTED = -32005;
+export const VERSION_NOT_SUPPORTED = -32009;
+export const TASK_STATES = Object.freeze({ working: 'TASK_STATE_WORKING', input_required: 'TASK_STATE_INPUT_REQUIRED', completed: 'TASK_STATE_COMPLETED', failed: 'TASK_STATE_FAILED', cancelled: 'TASK_STATE_CANCELED' });
+export const TERMINAL_STATES = Object.freeze(['TASK_STATE_COMPLETED', 'TASK_STATE_FAILED', 'TASK_STATE_CANCELED', 'TASK_STATE_REJECTED']);
+export const MAX_BODY = 1024 * 1024;
+const SKILL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const STOPS = [...TERMINAL_STATES, 'TASK_STATE_INPUT_REQUIRED'];
+const hex = (n) => crypto.randomBytes(n).toString('hex');
+
+/** A refused A2A call or card; the message never carries a credential. */
+export class A2AError extends ServiceError {}
+
+export function skillFromCapability(capability) {
+  const name = capability?.name;
+  if (typeof name !== 'string' || !SKILL_ID.test(name)) throw new A2AError("a skill's id is the capability's name: letters, digits, '.', '_' or '-', at most 64");
+  const skill = { id: name, name: capability.title || name, description: capability.description || name, tags: [...(capability.tags || [name.split('.')[0]])] };
+  for (const key of ['examples', 'inputModes', 'outputModes']) if (capability[key]?.length) skill[key] = [...capability[key]];
+  return skill;
+}
+
+export function agentCard({ name, description, version, url, capabilities, securitySchemes, streaming = false, extensions, remote = false, descriptorHeader = 'Authorization' }) {
+  const match = /^(https?:\/\/[^/?#]+)/.exec(url ?? '');
+  const card = {
+    name, description, version,
+    supportedInterfaces: [{ url, protocolBinding: JSONRPC_BINDING, protocolVersion: A2A_PROTOCOL_VERSION }],
+    capabilities: { streaming: Boolean(streaming), pushNotifications: false },
+    defaultInputModes: ['text/plain', 'application/json'], defaultOutputModes: ['text/plain', 'application/json'],
+    skills: capabilities.map(skillFromCapability),
+  };
+  if (extensions?.length) card.capabilities.extensions = extensions.map((e) => ({ ...e, required: false }));
+  if (securitySchemes) card.securitySchemes = securitySchemes;
+  const findings = agentCardFindings(card, { origin: match ? match[1] : undefined, remote, descriptorHeader });
+  if (findings.length) throw new A2AError(`the card is not served: ${findings.map((f) => f.message).join('; ')}`);
+  return card;
+}
+
+export const textOf = (message) => (Array.isArray(message?.parts) ? message.parts : []).filter((p) => typeof p?.text === 'string').map((p) => p.text).join('\n');
+export const dataOf = (message) => (Array.isArray(message?.parts) ? message.parts : []).filter((p) => p && typeof p === 'object' && 'data' in p).map((p) => p.data);
+
+export function agentMessage(text, { taskId, contextId, data } = {}) {
+  const parts = [{ text }];
+  if (data !== undefined) parts.push({ data });
+  const message = { role: 'ROLE_AGENT', parts, messageId: `msg-${hex(8)}` };
+  if (taskId) message.taskId = taskId;
+  if (contextId) message.contextId = contextId;
+  return message;
+}
+
+/** What a message handler gets: the message, its caller and start(skill), which makes the job that is the task. */
+export class TaskStart {
+  constructor(binding, message, caller, contextId) { Object.assign(this, { binding, message, caller, contextId, taskId: null }); }
+  start(skill) {
+    if (!this.binding.skills.has(skill)) throw new A2AError(`no skill ${skill} on this card`);
+    const handle = this.binding.jobs.create(`a2a.${skill}`, { a2a: { message: this.message, contextId: this.contextId, caller: this.caller } });
+    this.taskId = handle.job.id;
+    return this.taskId;
+  }
+}
+
+class NotCancelable extends Error {}
+class BadParams extends Error {}
+
+const result = (id, value) => ({ jsonrpc: '2.0', id, result: value });
+const error = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+const event = (id, value) => `data: ${JSON.stringify(result(id, value))}\n\n`;
+
+function textAnswer(requests, text) {
+  const keys = Object.keys(requests ?? {});
+  if (keys.length !== 1 || !text) return null;
+  const props = Object.keys(requests[keys[0]]?.params?.requestedSchema?.properties ?? {});
+  return props.length === 1 ? { [keys[0]]: { action: 'accept', content: { [props[0]]: text } } } : null;
+}
+
+/** The A2A Task an interop job reads as. */
+export function taskOf(job, contextId) {
+  const status = { state: TASK_STATES[job.status] ?? 'TASK_STATE_UNSPECIFIED', timestamp: job.updatedAt ?? '' };
+  if (job.status === 'input_required') {
+    const questions = Object.values(job.inputRequests ?? {}).map((r) => r?.params?.message).filter((q) => typeof q === 'string');
+    status.message = agentMessage(job.statusMessage || questions.join('; ') || 'an answer is needed', { taskId: job.id, contextId, data: { inputRequests: job.inputRequests } });
+  } else if (job.status === 'failed') {
+    status.message = agentMessage(String(job.error?.message || 'the task failed'), { taskId: job.id, contextId, data: { code: job.error?.code } });
+  } else if (job.statusMessage) {
+    status.message = agentMessage(job.statusMessage, { taskId: job.id, contextId });
+  }
+  const task = { id: job.id, contextId, status };
+  if (job.status === 'completed') task.artifacts = [{ artifactId: 'result', name: 'result', parts: [{ data: job.result }] }];
+  return task;
+}
+
+/** The JSON-RPC binding over the interop job store; see fabric_a2a_server.A2ABinding. */
+export class A2ABinding {
+  constructor(jobs, handler, { skills, authorize, clock = () => Date.now() / 1000 }) {
+    Object.assign(this, { jobs, handler, skills: new Set(skills), authorize, clock });
+  }
+
+  task(jobId, caller) {
+    const a2a = this.jobs.load(jobId).private?.input?.a2a;
+    if (!a2a || typeof a2a !== 'object' || (a2a.caller ?? null) !== (caller ?? null)) throw new UnknownJob(jobId);
+    return taskOf(this.jobs.get(jobId), a2a.contextId);
+  }
+
+  handle(body, headers = {}) {
+    const lowered = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+    const caller = this.authorize(lowered);
+    if (caller === null || caller === undefined) return [401, null];
+    if (body instanceof Uint8Array) {
+      if (body.length > MAX_BODY) return [413, null];
+      try { body = JSON.parse(Buffer.from(body).toString('utf8')); } catch { return [200, error(null, PARSE_ERROR, 'the body is not JSON')]; }
+    }
+    if (!body || typeof body !== 'object' || Array.isArray(body) || body.jsonrpc !== '2.0' || typeof body.method !== 'string') {
+      return [200, error(body && typeof body === 'object' && !Array.isArray(body) ? body.id : null, INVALID_REQUEST, 'not a JSON-RPC 2.0 request')];
+    }
+    const rid = body.id;
+    const version = lowered['a2a-version'];
+    if (version !== undefined && String(version).trim() !== A2A_PROTOCOL_VERSION) return [200, error(rid, VERSION_NOT_SUPPORTED, `this agent speaks A2A ${A2A_PROTOCOL_VERSION}`)];
+    const params = body.params;
+    if (!params || typeof params !== 'object' || Array.isArray(params)) return [200, error(rid, INVALID_PARAMS, 'params is an object')];
+    try {
+      if (body.method === 'SendStreamingMessage') return [200, error(rid, UNSUPPORTED_OPERATION, 'streaming is served by stream() as text/event-stream')];
+      if (body.method === 'SendMessage') return [200, result(rid, this.send(params, caller))];
+      if (body.method === 'GetTask') return [200, result(rid, this.task(String(params.id), caller))];
+      if (body.method === 'CancelTask') return [200, result(rid, this.cancel(String(params.id), caller))];
+    } catch (e) {
+      if (e instanceof UnknownJob) return [200, error(rid, TASK_NOT_FOUND, 'no such task')];
+      if (e instanceof NotCancelable) return [200, error(rid, TASK_NOT_CANCELABLE, 'the task has ended')];
+      if (e instanceof BadParams) return [200, error(rid, INVALID_PARAMS, e.message)];
+      if (e instanceof A2AError || e instanceof InteropError) return [200, error(rid, INTERNAL_ERROR, `the agent could not take the message: ${e.message}`)];
+      throw e;
+    }
+    return [200, error(rid, METHOD_NOT_FOUND, `no method ${body.method.slice(0, 64)} here`)];
+  }
+
+  send(params, caller) {
+    const message = params.message;
+    if (!message || typeof message !== 'object' || !Array.isArray(message.parts) || !message.parts.length) throw new BadParams('params.message is a message with parts');
+    if (typeof message.taskId === 'string' && message.taskId) return { task: this.continueTask(message.taskId, message, caller) };
+    const contextId = typeof message.contextId === 'string' ? message.contextId : `ctx-${hex(8)}`;
+    const start = new TaskStart(this, message, caller, contextId);
+    const reply = this.handler(start);
+    if (start.taskId !== null) return { task: this.task(start.taskId, caller) };
+    if (!reply || typeof reply !== 'object') throw new A2AError('the handler neither replied nor started a task');
+    return { message: { ...reply, contextId } };
+  }
+
+  continueTask(taskId, message, caller) {
+    const task = this.task(taskId, caller);
+    if (task.status.state !== 'TASK_STATE_INPUT_REQUIRED') throw new BadParams('the task waits for no answer');
+    const job = this.jobs.get(taskId);
+    let responses = dataOf(message).find((d) => d && typeof d === 'object' && d.inputResponses && typeof d.inputResponses === 'object' && !Array.isArray(d.inputResponses))?.inputResponses ?? null;
+    if (responses === null) responses = textAnswer(job.inputRequests ?? {}, textOf(message));
+    if (!responses || !Object.keys(this.jobs.answer(taskId, responses) ?? {}).length) throw new BadParams("the answer names none of the task's questions");
+    return this.task(taskId, caller);
+  }
+
+  cancel(taskId, caller) {
+    const task = this.task(taskId, caller);
+    if (TERMINAL_STATES.includes(task.status.state)) throw new NotCancelable();
+    this.jobs.cancel(taskId);
+    return this.task(taskId, caller);
+  }
+
+  async *stream(params, caller, { rid = null, pollS = 1, deadlineS = 300, sleep = (s) => new Promise((r) => setTimeout(r, s * 1000)) } = {}) {
+    const first = this.send(params, caller);
+    yield event(rid, first);
+    if (!first.task) return;
+    let task = first.task;
+    const end = this.clock() + deadlineS;
+    while (!STOPS.includes(task.status.state) && this.clock() < end) {
+      await sleep(pollS);
+      const now = this.task(task.id, caller);
+      if (now.status.state !== task.status.state || JSON.stringify(now.artifacts) !== JSON.stringify(task.artifacts)) {
+        yield event(rid, { statusUpdate: { taskId: now.id, contextId: now.contextId, status: now.status, final: STOPS.includes(now.status.state) } });
+      }
+      task = now;
+    }
+  }
+}
+
+/** scheme://host[:port] of a URL, lower-cased, a default port dropped. */
+export function originOf(url) {
+  const match = /^(https?):\/\/([^/?#]+)/i.exec(url ?? '');
+  if (!match || match[2].includes('@')) throw new A2AError("a peer's address is an http(s) origin with no userinfo");
+  const scheme = match[1].toLowerCase();
+  let host = match[2].toLowerCase();
+  const port = host.split(':').pop();
+  if (((scheme === 'https' && port === '443') || (scheme === 'http' && port === '80')) && host.includes(':') && !host.endsWith(']')) host = host.slice(0, host.lastIndexOf(':'));
+  return `${scheme}://${host}`;
+}
+
+/** A bounded A2A 1.0 client; see fabric_a2a_server.A2AClient. */
+export class A2AClient {
+  constructor(allowOrigins, { credentialEnv, header = 'Authorization', scheme = 'Bearer', deadlineS = 30, maxBytes = MAX_BODY, transport, insecure = false } = {}) {
+    this.allowed = new Set(allowOrigins.map(originOf));
+    if (!this.allowed.size) throw new A2AError("a client needs the operator's list of peer origins");
+    Object.assign(this, { credentialEnv, header, scheme, deadlineS, maxBytes, transport, insecure, ids: 0 });
+  }
+
+  check(url) { if (!this.allowed.has(originOf(url))) throw new A2AError(`${originOf(url)} is not on the operator's list of A2A peers`); }
+
+  headers() {
+    const headers = { 'A2A-Version': A2A_PROTOCOL_VERSION, Accept: 'application/json' };
+    if (this.credentialEnv) {
+      const value = process.env[this.credentialEnv];
+      if (!value) throw new A2AError(`${this.credentialEnv} is empty: run the caller under use_secret.py run, which places the key`);
+      headers[this.header] = this.scheme ? `${this.scheme} ${value}` : value;
+    }
+    return headers;
+  }
+
+  options(extra) { return { deadlineS: this.deadlineS, maxBytes: this.maxBytes, insecure: this.insecure, ...(this.transport ? { transport: this.transport } : {}), ...extra }; }
+
+  async discover(origin) {
+    const url = originOf(origin) + A2A_SURFACE_PATH;
+    this.check(url);
+    const response = await httpRequest('GET', url, this.options({ headers: { Accept: 'application/json' } }));
+    if (response.status !== 200) throw new A2AError(`the peer answered HTTP ${response.status} for its card`);
+    let card;
+    try { card = response.json(); } catch { throw new A2AError("the peer's card is not JSON"); }
+    if (!card || typeof card !== 'object' || Array.isArray(card)) throw new A2AError("the peer's card is not a JSON object");
+    for (const i of card.supportedInterfaces ?? []) {
+      if (i && i.protocolBinding === JSONRPC_BINDING && i.protocolVersion === A2A_PROTOCOL_VERSION && typeof i.url === 'string') {
+        this.check(i.url);
+        return { card, url: i.url };
+      }
+    }
+    throw new A2AError(`the peer's card names no A2A ${A2A_PROTOCOL_VERSION} JSON-RPC interface`);
+  }
+
+  async rpc(url, method, params) {
+    this.check(url);
+    this.ids += 1;
+    const response = await httpRequest('POST', url, this.options({ headers: this.headers(), body: { jsonrpc: '2.0', id: this.ids, method, params }, retries: 0 }));
+    if (response.status !== 200) throw new A2AError(`the peer answered HTTP ${response.status} to ${method}`);
+    let answer = null;
+    try { answer = response.json(); } catch { /* answered below */ }
+    if (!answer || typeof answer !== 'object' || Array.isArray(answer)) throw new A2AError(`the peer's answer to ${method} is not a JSON-RPC response`);
+    if ('error' in answer) throw new A2AError(`the peer refused ${method}: ${answer.error?.code} ${String(answer.error?.message).slice(0, 200)}`);
+    return answer.result;
+  }
+
+  call(url, text, { data, taskId, contextId } = {}) {
+    const parts = [{ text }];
+    if (data !== undefined) parts.push({ data });
+    const message = { role: 'ROLE_USER', parts, messageId: `msg-${hex(8)}` };
+    if (taskId) message.taskId = taskId;
+    if (contextId) message.contextId = contextId;
+    return this.rpc(url, 'SendMessage', { message });
+  }
+
+  get(url, taskId) { return this.rpc(url, 'GetTask', { id: taskId }); }
+  cancel(url, taskId) { return this.rpc(url, 'CancelTask', { id: taskId }); }
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-a2a.mjs

@@ -2,7 +2,7 @@
 // schema reads it (a2aSurfaceFindings, a2aView; a2aSurface builds one), and what a public card must not carry
 // (agentCardFindings): no member about the running process, no secret, no securitySchemes entry naming the descriptor's
 // token header, every Fabric extension required: false (or absent, which A2A reads as false), and interface URLs where the placement puts them. Serving a
-// card, the A2A binding and a client are not here (FAA-10).
+// card, the A2A binding and a client are in fabric-a2a-server.mjs (FAA-10).
 // Part of the Node service kit (layer L3); the twin of fabric_a2a.py. Node 20+, no dependency.
 import { ServiceError } from './fabric-base.mjs';
 import { isObject } from './fabric-jsvalue.mjs';

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-auth.mjs

@@ -7,7 +7,7 @@ import { PROTOCOL, ServiceError, nowIso } from './fabric-base.mjs';
 import { tokenMatches, windowsTokenProblem } from './fabric-platform.mjs';
 import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
 import { isPlainObject } from './fabric-usage.mjs';
-import { descriptorPath, namesRepository, sourceRefusal, validateDescriptor, writeDescriptor } from './fabric-descriptor.mjs';
+import { descriptorPath, namesRepository, sourceRefusal, validateDescriptor, warnNoSource, writeDescriptor } from './fabric-descriptor.mjs';
 
 export const SESSION_COOKIE = 'fabric_session';
 
@@ -286,9 +286,11 @@ export function registerRemote({ id, instance = 'default', name, summary, origin
   if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
   const refusal = sourceRefusal(d, dir); // before the token is written: a refused install leaves nothing (FAA-198)
   if (refusal) throw new ServiceError(refusal);
+  const warned = !namesRepository(d);
+  if (warned) warnNoSource(d); // before the token: a warning that throws leaves both files as they were (FAA-200 (1))
   ensurePrivateDir(path.dirname(tokenFile));
   atomicWrite(tokenFile, String(token).trim(), 0o600);
-  return writeDescriptor(d, dir);
+  return writeDescriptor(d, dir, { warned });
 }
 
 export function cookieValue(header, name = SESSION_COOKIE) {

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-board-fixture.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { Backoff, HubError, MCP_PROTOCOL_VERSION, normalProject, postMcp, toolAnswer } from './fabric-hub.mjs';
 import { COMMS_PROTOCOL, RESPOND_TOOLS } from './fabric-board-shapes.mjs';
 import { BoardSession, Responder } from './fabric-board-session.mjs';
+import { LEVELS } from './fabric-events.mjs'; // the levels the event log takes (FAA-187 (23))
 
 const FIXTURE_PROJECT = '3f2a6b1c-0d4e-4f5a-8b6c-7d8e9f0a1b2c';
 
@@ -28,7 +29,11 @@ function fixtureAnswers(variant) {
   };
 }
 
-/** One scripted conversation per path through this kit, with no Fabric; answers the problems found (empty: it passes). */
+/**
+ * One scripted conversation per path through this kit, with no Fabric; answers the problems found (empty: it passes).
+ * Its notices are recorded: one at a level the event log refuses, one without its subject, or a fenced attempt with no
+ * warning fails it (FAA-187 (23)).
+ */
 export async function selfCheck() {
   const os = await import('node:os');
   const problems = [];
@@ -45,6 +50,8 @@ export async function selfCheck() {
       const answers = fixtureAnswers(variant);
       const calls = [];
       const handled = [];
+      const notices = []; // recorded as JsonlEventLog.append takes them: (kind, level, text, {notify, subject, ...}) (FAA-187 (23))
+      const emit = (kind, level, text, options = {}) => { notices.push([kind, level, options?.subject]); };
       const post = async (origin, body, bearer, { method = 'POST' } = {}) => {
         if (method === 'DELETE') return { status: 200, headers: {}, body: null };
         if (body.method === 'initialize') return { status: 200, headers: { 'mcp-session-id': 'fixture-session' }, body: { jsonrpc: '2.0', id: body.id, result: { protocolVersion: MCP_PROTOCOL_VERSION } } };
@@ -58,9 +65,14 @@ export async function selfCheck() {
       const { HubClient } = await import('./fabric-hub.mjs');
       const responder = new Responder({ hub: new HubClient(root, { post }), projectId: FIXTURE_PROJECT, capabilities: ['fixture.render'], credentialFile: cred,
         checkpointFile: path.join(tmp, 'checkpoint.json'), handler: (request) => { handled.push(request.body); return { state: 'completed', summary: 'Rendered.' }; },
-        admit: () => null, now: () => 0, rand: () => 0.5, sessionFactory: (grant) => new BoardSession(grant, { post }) });
+        admit: () => null, now: () => 0, rand: () => 0.5, sessionFactory: (grant) => new BoardSession(grant, { post }), emit });
       await responder.step();
       const tools = calls.map(([t]) => t);
+      for (const [kind, level, subject] of notices) {
+        if (!LEVELS.includes(level)) problems.push(`${variant}: notice ${kind} at level '${level}', which the event log refuses`);
+        if (!(subject && typeof subject === 'object' && subject.type && subject.id)) problems.push(`${variant}: notice ${kind} without its subject`);
+      }
+      if (variant === 'fenced' && !notices.some(([, level]) => level === 'warning')) problems.push('fenced: no warning notice reached the service\'s emit');
       if (tools.some((t) => !RESPOND_TOOLS.has(t) && t !== 'fabric.board.join')) problems.push(`${variant}: a tool outside the respond scope was sent`);
       if (variant === 'whole') {
         if (tools.join(',') !== 'fabric.board.join,com.status,com.enroll,com.claim,com.get,com.accept,com.complete') problems.push(`whole: the calls were ${tools.join(', ')}`);

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-board-link.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { HubError, MCP_PROTOCOL_VERSION, postMcp, toolAnswer } from './fabric-hub.mjs';
 import { atomicWrite, ensurePrivateDir } from './fabric-service.mjs';
 import { BoardError, RESPOND_TOOLS, isObj, refusalProblems } from './fabric-board-shapes.mjs';
-import { UNREADABLE_PROJECT, mandateSpend } from './fabric-interop-rules.mjs'; // FAA-139
+import { UNREADABLE_AGENT, UNREADABLE_PROJECT, identifiedAgent, mandateSpend } from './fabric-interop-rules.mjs'; // FAA-139, FAA-135
 import { isAgentId, mandateCovers } from './fabric-mandate.mjs';
 import { formatRfc3339 } from './fabric-time.mjs';
 
@@ -26,9 +26,9 @@ export class BoardSession {
     return run;
   }
 
-  async #send(body, method = 'POST', timeout = null) {
+  async #send(body, method = 'POST', timeout = null, deadline = 0) {
     try {
-      return await this.post(this.grant.origin, body, this.grant.bearer(), { session: this.mcpSession, timeout: timeout > 0 ? timeout : this.timeout, method, protocolVersion: this.mcpSession ? this.protocolVersion : undefined });
+      return await this.post(this.grant.origin, body, this.grant.bearer(), { session: this.mcpSession, timeout: timeout > 0 ? timeout : this.timeout, method, protocolVersion: this.mcpSession ? this.protocolVersion : undefined, ...(deadline > 0 ? { deadline } : {}) });
     } catch (e) {
       // FAA-252: another OS account's process holds the port; nothing was sent
       if (e instanceof HubError && e.code === 'foreign-user') throw new BoardError('foreign-user', 'The hub\'s port is held by another OS account\'s process; nothing was sent.', true);
@@ -71,13 +71,13 @@ export class BoardSession {
     });
   }
 
-  /** Sends the DELETE (waiting `timeout` ms at most); true when Fabric answered it with a 2xx, so the slots are free now (FAA-163). A 404 (already gone) is false: a move made before it ended is read at the next com.status, so the slot records stay. */
+  /** Sends the DELETE (waiting `timeout` ms at most for the whole of it, FAA-187 (12)); true when Fabric answered it with a 2xx, so the slots are free now (FAA-163). A 404 (already gone) is false: a move made before it ended is read at the next com.status, so the slot records stay. */
   close(timeout = null) {
     return this.#serial(async () => {
       if (!this.mcpSession) return false;
       let status = 0;
       try {
-        const answer = await this.#send({}, 'DELETE', timeout);
+        const answer = await this.#send({}, 'DELETE', timeout, timeout > 0 ? timeout : 0); // the whole DELETE (FAA-187 (12))
         status = Number.isInteger(answer?.status) ? answer.status : 0; // an answer it cannot read is no release, as in Python
       } catch {
         // best effort: the lease lapses in 60 s anyway
@@ -92,7 +92,7 @@ export class BoardSession {
 export class Checkpoint {
   constructor(file) {
     this.file = file;
-    this.slots = {}; // the responder's own record of each slot it held: {project, generation, moved?} (FAA-155)
+    this.slots = Object.create(null); // the responder's own record of each slot it held: {project, generation, moved?} (FAA-155); no prototype, so a capability named `constructor` reads as any other (FAA-196 (24))
     this.entries = this.#load();
   }
   #load() {
@@ -111,7 +111,7 @@ export class Checkpoint {
     }
     if (!isObj(doc) || doc.version !== 1 || !isObj(doc.requests)) throw new BoardError('checkpoint', `The board checkpoint ${this.file} is not one this kit writes.`);
     // a record that is not an object is ignored, as a file without one is
-    this.slots = isObj(doc.slots) ? Object.fromEntries(Object.entries(doc.slots).filter(([, v]) => isObj(v))) : {};
+    this.slots = Object.assign(Object.create(null), isObj(doc.slots) ? Object.fromEntries(Object.entries(doc.slots).filter(([, v]) => isObj(v))) : {});
     return doc.requests;
   }
   #write(entries, slots = this.slots) {
@@ -137,7 +137,8 @@ export class Checkpoint {
   }
   /** Writes the record of a slot this responder held (null forgets it); nothing is written when it is unchanged. */
   slot(capability, record) {
-    const { [capability]: _old, ...slots } = this.slots;
+    const slots = Object.assign(Object.create(null), this.slots);
+    delete slots[capability];
     if (record !== null) slots[capability] = JSON.parse(JSON.stringify(record));
     if (JSON.stringify(sortDeep(slots)) === JSON.stringify(sortDeep(this.slots))) return;
     this.#write(this.entries, slots);
@@ -239,7 +240,7 @@ export function readMandate(request, mandateFrom, agentId) {
     try {
       value = JSON.parse(block);
     } catch {
-      if (block.includes('mandate/1')) return { mandate: null, unread: 'mandate-unreadable' };
+      if (/mandate(?:\/|\\\/|\\u002[fF])1/.test(block)) return { mandate: null, unread: 'mandate-unreadable' }; // the kind as written, its slash JSON-escaped too (FAA-196 (13))
       continue;
     }
     if (isObj(value) && value.kind === 'mandate/1') {
@@ -263,7 +264,7 @@ export function readMandate(request, mandateFrom, agentId) {
  * absent (an inherited, non-enumerable, getter or Proxy member included); the rest of the call is never touched. A
  * getter whose value changes is answered on its one read.
  */
-export function covers(mandate, call, agentId, wall, caller = null) {
+export function covers(mandate, call, agentId, wall, caller = null, callerAgent = null) {
   if (mandate == null || agentId == null) return null;
   if (call !== null && typeof call === 'object' && !Array.isArray(call)) {
     const read = {};
@@ -284,10 +285,52 @@ export function covers(mandate, call, agentId, wall, caller = null) {
   } catch { // finite but outside the dates a clock can name
     now = '';
   }
-  const answer = mandateCovers({ mandate, tier: 'T1', now, self: agentId, call });
+  const inputs = { mandate, tier: 'T1', now, self: agentId, call };
+  if (callerAgent !== null && callerAgent !== undefined) inputs.callerAgent = callerAgent; // FAA-135
+  const answer = mandateCovers(inputs);
   return answer.recordAs ? { ok: true, recordAs: { ...answer.recordAs, caller } } : answer;
 }
 
+/**
+ * A responder's `links` (FAA-187 (21)): the page on the service that resolves each notify kind, such as
+ * `{'board.slot.moved': '/#board'}`, passed to a notice that notifies as its `link`. A path on the service, as makeEvent
+ * takes one; null is none. A service that gives links has an emit that takes `link`.
+ */
+export function noticeLinks(links) {
+  if (links === null || links === undefined) return Object.create(null);
+  if (!isObj(links) || !Object.entries(links).every(([, v]) => typeof v === 'string' && v.startsWith('/') && !v.startsWith('//'))) {
+    throw new BoardError('invalid_arguments', 'links maps an event kind to a path on this service, such as /#board.');
+  }
+  return Object.assign(Object.create(null), links);
+}
+
+/**
+ * Why a message read back with com.get is not the request a claim took (the first path refuses it, a resume reads no
+ * mandate from it, FAA-196 (1)): `digest-mismatch` (another digest than the claim's), `not-addressed` (not this
+ * request, capability and Project), else null.
+ */
+export function readBackProblem(message, entry, project) {
+  if (!isObj(message) || message.digest !== entry.digest) return 'digest-mismatch';
+  const req = message.request;
+  if (!isObj(req) || req.id !== entry.request || req.capability !== entry.capability || req.target !== project) return 'not-addressed';
+  return null;
+}
+
+/**
+ * FAA-135: the agent id the service's identifyAgent(sender) names for a request's sender (the board's verified
+ * `{project, principal}`), read as identifiedAgent reads a hook's answer: null or undefined is none, an agent id is that
+ * id, anything else, or a hook that throws, is UNREADABLE_AGENT, which no chain holds. Asked only when a mandate
+ * travelled (`mandate` not null).
+ */
+export function senderAgent(identifyAgent, sender, mandate = true) {
+  if (identifyAgent == null || mandate == null) return null;
+  try {
+    return identifiedAgent(identifyAgent(sender));
+  } catch {
+    return UNREADABLE_AGENT; // the service's own hook: fail closed
+  }
+}
+
 /** The responder's opt-in, checked: answers `mandateFrom` as the responder keeps it (a Set or the string). */
 export function mandateOptions(agentId, mandateFrom) {
   if (agentId != null && !isAgentId(agentId)) throw new BoardError('invalid_arguments', 'agentId must be the service\'s registry agent id.');