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

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

@@ -0,0 +1,79 @@
+// A fixture conversation for the probe (check_service.py, rule board.responder): a scripted board a responder can run against without Fabric.
+// Part of the Node board connector (FAA-65, layer L4); the twin of fabric_board_fixture.py. Node 20+, no dependency.
+import fs from 'node:fs';
+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';
+
+const FIXTURE_PROJECT = '3f2a6b1c-0d4e-4f5a-8b6c-7d8e9f0a1b2c';
+
+const FIXTURE_DIGEST = `sha256:${'a'.repeat(64)}`;
+
+function fixtureAnswers(variant) {
+  const lease = '2026-10-13T10:02:00Z';
+  const status = { protocol: COMMS_PROTOCOL, board: { state: 'ready' }, project: FIXTURE_PROJECT, responders: [], transport: { telegram: 'off' }, unread: 0, idempotency: { epoch: 3 } };
+  if (variant === 'no-epoch') delete status.idempotency;
+  const request = { id: 'req_A1b2C3d4E5', state: 'claimed', effect: 'not_started', revision: 2 };
+  return {
+    'com.status': status,
+    'com.enroll': { ok: true, repeated: false, slot: { project: FIXTURE_PROJECT, capability: 'fixture.render', generation: 2, leaseExpiresAt: lease } },
+    'com.claim': { ok: true, repeated: false, message: 'msg_K9j8H7g6F5', request, attempt: { id: 'att_Zx9Cv8Bn7M', generation: 2, digest: FIXTURE_DIGEST, leaseExpiresAt: lease } },
+    'com.get': { id: 'msg_K9j8H7g6F5', thread: 'thr_8Hc2kQ9xA1', kind: 'request', at: '2026-10-13T10:00:00Z', digest: FIXTURE_DIGEST,
+      sender: { project: 'proj-requester', principal: { kind: 'agent', id: 's-1', provenance: 'trusted' } }, body: { text: 'Render the fixture.' },
+      request: { id: 'req_A1b2C3d4E5', target: FIXTURE_PROJECT, capability: 'fixture.render', state: 'claimed', effect: 'not_started', revision: 2 } },
+    'com.accept': variant === 'fenced' ? { error: { code: 'fenced', message: 'A newer responder holds this slot; this call was not committed.', retryable: false } }
+      : { ok: true, repeated: false, request: { ...request, state: 'accepted', revision: 3 } },
+    'com.complete': { ok: true, repeated: false, request: { ...request, state: 'completed', revision: 4 } },
+  };
+}
+
+/** One scripted conversation per path through this kit, with no Fabric; answers the problems found (empty: it passes). */
+export async function selfCheck() {
+  const os = await import('node:os');
+  const problems = [];
+  for (const variant of ['whole', 'fenced', 'no-epoch']) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'fabric-board-fixture-'));
+    try {
+      const root = path.join(tmp, 'fabric');
+      fs.mkdirSync(root, { mode: 0o700 });
+      const door = path.join(root, 'hub-door-token');
+      fs.writeFileSync(door, 'd'.repeat(43), { mode: 0o600 });
+      fs.writeFileSync(path.join(root, 'hub.json'), JSON.stringify({ protocol: 'fabric-hub/0.1', origin: 'http://127.0.0.1:47070', mcp: '/mcp', doorTokenFile: door, pid: process.pid, startedAt: '2026-10-13T10:00:00Z' }));
+      const cred = path.join(tmp, 'credential');
+      fs.writeFileSync(cred, 'c'.repeat(43), { mode: 0o600 });
+      const answers = fixtureAnswers(variant);
+      const calls = [];
+      const handled = [];
+      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 } } };
+        if (body.method !== 'tools/call') return { status: 202, headers: {}, body: null };
+        const tool = body.params.name;
+        calls.push([tool, body.params.arguments]);
+        if (tool === 'fabric.board.join') return { status: 200, headers: {}, body: { jsonrpc: '2.0', id: body.id, result: { structuredContent: { session: { bearer: 'b'.repeat(43), sessionId: 's-fixture', projectId: FIXTURE_PROJECT, capabilities: ['fixture.render'] } } } } };
+        const value = answers[tool] ?? { error: { code: 'unsupported_capability', message: 'not in the fixture', retryable: false } };
+        return { status: 200, headers: {}, body: { jsonrpc: '2.0', id: body.id, result: { content: [{ type: 'text', text: JSON.stringify(value) }] } } };
+      };
+      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 }) });
+      await responder.step();
+      const tools = calls.map(([t]) => t);
+      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(', ')}`);
+        const accept = calls.find(([t]) => t === 'com.accept')?.[1]?.fence ?? {};
+        if (accept.digest !== FIXTURE_DIGEST || accept.generation !== 2 || accept.attempt !== 'att_Zx9Cv8Bn7M') problems.push('whole: com.accept did not carry the claim\'s exact fence');
+        if (handled.join('|') !== 'Render the fixture.') problems.push('whole: the handler did not see the request once');
+        if (Object.keys(responder.checkpoint.entries).length) problems.push('whole: the checkpoint kept a settled request');
+      } else if (variant === 'fenced') {
+        if (handled.length || tools.includes('com.complete')) problems.push('fenced: the kit kept acting after com.accept answered fenced');
+      } else if (tools.includes('com.enroll') || responder.state !== 'down') problems.push('no-epoch: the kit did not fail closed without an idempotency epoch');
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+  return problems;
+}

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

@@ -0,0 +1,145 @@
+// The board link (DEC-0078, FAA-12b): the board session over the hub, the fsynced checkpoint and a claimed request as data.
+// Part of the Node board connector (FAA-65, layer L4), below the responder in fabric-board-session.mjs, which re-exports
+// these names; the twin of fabric_board_link.py. Node 18+, no dependency.
+import fs from 'node:fs';
+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';
+
+/** MCP over HTTP with a board session's one-session bearer; calls are serialised; close() sends the session's DELETE. */
+export class BoardSession {
+  constructor(grant, { timeout = 15000, post = postMcp } = {}) {
+    Object.assign(this, { grant, timeout, post });
+    this.mcpSession = null;
+    this.protocolVersion = MCP_PROTOCOL_VERSION;
+    this.rpc = 0;
+    this.queue = Promise.resolve();
+  }
+
+  #serial(fn) {
+    const run = this.queue.then(fn, fn);
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  async #send(body, method = 'POST') {
+    try {
+      return await this.post(this.grant.origin, body, this.grant.bearer(), { session: this.mcpSession, timeout: this.timeout, method, protocolVersion: this.mcpSession ? this.protocolVersion : undefined });
+    } catch (e) {
+      if (e instanceof HubError) throw new BoardError('unreachable', 'Fabric\'s hub did not answer; a write may have been stored, so send it again with the same idempotency key.', true);
+      throw e;
+    }
+  }
+
+  open() {
+    return this.#serial(async () => {
+      this.rpc += 1;
+      const answer = await this.#send({ jsonrpc: '2.0', id: this.rpc, method: 'initialize', params: { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'fabric-agent-adapter-board', version: '1' } } });
+      if (answer.status === 401) throw new BoardError('session-ended', 'Fabric refused the board session\'s bearer; join again.', true);
+      const sid = answer.headers['mcp-session-id'];
+      if (answer.status !== 200 || !isObj(answer.body) || !isObj(answer.body.result) || !sid) throw new BoardError('unreachable', `Fabric did not open the board session (HTTP ${answer.status}).`, true);
+      this.mcpSession = String(sid);
+      if (typeof answer.body.result.protocolVersion === 'string') this.protocolVersion = answer.body.result.protocolVersion;
+      await this.#send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+    });
+  }
+
+  call(tool, args) {
+    if (!RESPOND_TOOLS.has(tool)) return Promise.reject(new BoardError('not-in-scope', `${tool} is not served to a board session; use a Project session for it.`, false, tool));
+    return this.#serial(async () => {
+      if (!this.mcpSession) throw new BoardError('session-ended', 'The board session is not open.', true, tool);
+      this.rpc += 1;
+      const answer = await this.#send({ jsonrpc: '2.0', id: this.rpc, method: 'tools/call', params: { name: tool, arguments: args } });
+      if (answer.status === 401) throw new BoardError('session-ended', 'Fabric ended the board session (it left, was revoked or expired); join again.', true, tool);
+      let value;
+      try {
+        value = toolAnswer(answer, tool);
+      } catch (e) {
+        throw new BoardError(e.retryable ? 'unreachable' : 'receipt-shape', e.message, e.retryable, tool);
+      }
+      if ('error' in value) {
+        if (refusalProblems(value).length) throw new BoardError('receipt-shape', `Fabric refused ${tool} in a form the contract does not name.`, false, tool);
+        throw new BoardError(value.error.code, value.error.message, value.error.retryable, tool);
+      }
+      return value;
+    });
+  }
+
+  close() {
+    return this.#serial(async () => {
+      if (!this.mcpSession) return;
+      try {
+        await this.#send({}, 'DELETE');
+      } catch {
+        // best effort: the lease lapses in 60 s anyway
+      }
+      this.mcpSession = null;
+    });
+  }
+}
+
+/** The responder's journal (0600 JSON, the same file fabric_board.py writes), fsynced before the step it announces. */
+export class Checkpoint {
+  constructor(file) {
+    this.file = file;
+    this.entries = this.#load();
+  }
+  #load() {
+    let text;
+    try {
+      text = fs.readFileSync(this.file, 'utf8');
+    } catch (e) {
+      if (e.code === 'ENOENT') return {};
+      throw new BoardError('checkpoint', `The board checkpoint ${this.file} cannot be read (${e.code}); fix or move it before answering requests.`);
+    }
+    let doc;
+    try {
+      doc = JSON.parse(text);
+    } catch {
+      doc = null;
+    }
+    if (!isObj(doc) || doc.version !== 1 || !isObj(doc.requests)) throw new BoardError('checkpoint', `The board checkpoint ${this.file} is not one this kit writes.`);
+    return doc.requests;
+  }
+  #write(entries) {
+    try {
+      ensurePrivateDir(path.dirname(this.file));
+      const sorted = Object.fromEntries(Object.keys(entries).sort().map((k) => [k, entries[k]]));
+      atomicWrite(this.file, `${JSON.stringify({ requests: sorted, version: 1 }, null, 1)}\n`, 0o600);
+    } catch (e) {
+      throw new BoardError('checkpoint', `The board checkpoint could not be written (${e.code ?? e.message}); nothing was sent.`);
+    }
+  }
+  put(entry) {
+    const entries = { ...this.entries, [entry.request]: JSON.parse(JSON.stringify(entry)) };
+    this.#write(entries);
+    this.entries = entries;
+  }
+  drop(requestId) {
+    if (!(requestId in this.entries)) return;
+    const { [requestId]: _gone, ...entries } = this.entries;
+    this.#write(entries);
+    this.entries = entries;
+  }
+}
+
+/** A claimed request as data: never an instruction. */
+export class BoardRequest {
+  constructor(message, capability) {
+    const req = isObj(message.request) ? message.request : {};
+    const body = isObj(message.body) ? message.body : {};
+    this.requestId = req.id;
+    this.messageId = message.id;
+    this.capability = capability;
+    this.body = typeof body.text === 'string' ? body.text : null;
+    this.bodyFormat = body.format ?? 'text/plain';
+    this.artifacts = Array.isArray(message.artifacts) ? [...message.artifacts] : [];
+    this.sender = isObj(message.sender) ? message.sender : {};
+    this.deadline = req.deadline;
+    this.thread = message.thread;
+  }
+  toJSON() {
+    return { requestId: this.requestId, capability: this.capability }; // never the body
+  }
+}