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

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

@@ -56,8 +56,9 @@ export class HubError extends Error {
 /**
  * The HubError for a hub port the peer-owner check refused (DEC-0154 HA-2): code `foreign-user`, the pinned contract's
  * state name, with the owner's reason in the sentence and in `data.reason` (FAA-272): `table-restricted` when this
- * runtime's socket table hides other processes' sockets, which never clears, so it is not retryable; otherwise the
- * owner's kind or the check's reason (`another-account`, `no-row`), retryable as before.
+ * runtime's socket table hides other processes' sockets, or, on macOS, holds no row for this connection (DEC-0155
+ * RT-1, FAA-312), which never clears, so it is not retryable; otherwise the owner's kind or the check's reason
+ * (`another-account`, or `no-row`, which only Linux and Windows give), retryable.
  */
 export function listenerRefusal(e) {
   const kind = e?.owner?.kind ?? null;
@@ -75,14 +76,19 @@ export function fabricRoot(platform = process.platform, env = process.env) {
   return path.join(env.XDG_DATA_HOME || path.join(home, '.local/share'), 'passioncode-fabric');
 }
 
-/** Whether a process with this id runs as this user (Fabric hub.ts#pidAlive): EPERM is another user's process. */
+/**
+ * true: a process of this OS account runs under pid; false: none does. null (falsy): a process of another account does
+ * (EPERM), as when the id hub.json names was reused: not verified, never called running (FAA-304, the session hooks'
+ * answer since FAA-254). Never signals it. On Windows libuv opens the process for terminate, query and synchronize, so
+ * an elevated process of the same user answers EPERM too; the Python twin asks OpenProcess for the same access (FAA-323).
+ */
 export function pidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
-    return false;
+  } catch (e) {
+    return e?.code === 'EPERM' ? null : false;
   }
 }
 
@@ -108,7 +114,8 @@ function readSmall(file) {
 
 /**
  * hub.json read the way an agent must, every call. Answers {origin, mcpUrl, doorTokenFile, pid, startedAt, features} or
- * throws HubError (not-running, retryable; not-a-hub). Reads no token. `estate` is {record, applied}: with it, a hubKey
+ * throws HubError (not-running, retryable; not-a-hub, retryable when hub.json names another OS account's process, not
+ * verified, FAA-304). Reads no token. `estate` is {record, applied}: with it, a hubKey
  * the document names is checked by hubKeyCertified (DEC-0060); fabric-hub/0.1 names none.
  */
 export function locateHub(root = fabricRoot(), { alive = pidAlive, estate, now } = {}) {
@@ -142,7 +149,10 @@ export function locateHub(root = fabricRoot(), { alive = pidAlive, estate, now }
     sameRoot = false;
   }
   if (!sameRoot) throw notHub('names a door token outside the registry root');
-  if (!alive(doc.pid)) throw new HubError('not-running', `Fabric is not running: hub.json names process ${doc.pid}, which is not running.`, true);
+  const live = alive(doc.pid);
+  // FAA-304: another account's process under that id, so not this account's Fabric (as FAA-254)
+  if (live === null) throw new HubError('not-a-hub', `Fabric's hub.json names process ${doc.pid}, which runs under another OS account: not verified.`, true);
+  if (!live) throw new HubError('not-running', `Fabric is not running: hub.json names process ${doc.pid}, which is not running.`, true);
   const features = Array.isArray(doc.features) ? doc.features.filter((f) => typeof f === 'string') : [];
   if (estate && doc.hubKey && typeof doc.hubKey === 'object') {
     const verdict = hubKeyCertified(estate.record, doc.hubKey.kid, doc.hubKey.x, now ?? Date.now() / 1000, estate.applied ?? undefined);
@@ -183,7 +193,7 @@ export function readCredential(file) {
  * is HubError hub-unavailable (retryable); a listener that is not this OS account's process is HubError foreign-user
  * (retryable) before the bearer is sent (DEC-0154 HA-2): the connection is checked from the socket table first.
  */
-export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion, agent = HUB_AGENT } = {}) {
+export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion, agent = HUB_AGENT, deadline = 0 } = {}) {
   const m = LOOPBACK_ORIGIN.exec(origin);
   if (!m) return Promise.reject(new HubError('not-a-hub', 'Only the hub\'s loopback origin is used.'));
   const payload = method === 'DELETE' ? null : Buffer.from(JSON.stringify(body));
@@ -215,6 +225,9 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
       res.on('error', () => reject(new HubError('hub-unavailable', 'Fabric\'s hub did not answer (the answer broke off).', true)));
     });
     req.on('timeout', () => req.destroy(new Error('timeout')));
+    // `deadline` (ms) bounds the whole request, where `timeout` bounds each socket read (FAA-187 (12))
+    const timer = deadline > 0 ? setTimeout(() => req.destroy(new Error('deadline')), deadline) : null;
+    if (timer) req.on('close', () => clearTimeout(timer));
     req.on('error', (e) => reject(e instanceof ListenerRefused
       ? listenerRefusal(e)
       : new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));

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

@@ -7,7 +7,7 @@ import crypto from 'node:crypto';
 import { ServiceError } from './fabric-base.mjs';
 import { jcs, refusalFromAction, refusalToolResult } from './fabric-delegation.mjs';
 import { actionDecision, decisionShape, jobCapability } from './fabric-actions.mjs'; // DEC-0121
-import { EFFECT_CLASSES, OPERATOR_SOURCE_PROTOCOL, mandateCovers, mandateProblem, withoutSource } from './fabric-mandate.mjs'; // DEC-0125, DEC-0126
+import { EFFECT_CLASSES, OPERATOR_SOURCE_PROTOCOL, isAgentId, mandateCovers, mandateProblem, withoutSource } from './fabric-mandate.mjs'; // DEC-0125, DEC-0126
 import { isString } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
 import { isObject } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
 
@@ -277,6 +277,25 @@ export function jobStep({ mandate, tier, now, self, capability, key, effect, cal
 /** The project of a call whose project could not be read: never in a mandate's projects (FAA-139). */
 export const UNREADABLE_PROJECT = '\u0000unreadable';
 
+/**
+ * The caller's agent id when a service's own hook answered something no chain can hold (an id the registry refuses, not
+ * a string, or the hook threw): passed as callerAgent it matches no agent, so every mandate reads
+ * mandate-not-for-this-call (fail closed, FAA-135). Never an agent id (isAgentId refuses it).
+ */
+export const UNREADABLE_AGENT = '\u0000unreadable-agent';
+
+/**
+ * FAA-135: the caller's agent id as a service's own hook named it from a per-agent credential (contract delegation.md,
+ * `surfaces.mcp.auth: own`), read as the mandate chain binds it: pass the answer as actionGate's and jobStep's
+ * `callerAgent`. null or undefined (no per-agent credential) is null, and the chain's end alone binds the mandate, as
+ * before; an agent id the registry accepts is that id; anything else is UNREADABLE_AGENT. A hook that throws: pass
+ * UNREADABLE_AGENT. The Python twin's McpToolServer(identify_agent=) reads it so; never a name the call carries.
+ */
+export function identifiedAgent(value) {
+  if (value === null || value === undefined) return null;
+  return isAgentId(value) ? value : UNREADABLE_AGENT;
+}
+
 /** A spend estimate as a mandate reads it (FAA-139): a finite number stays, anything else is none (a ceiling refuses it). */
 export function mandateSpend(value) {
   return typeof value === 'number' && Number.isFinite(value) ? value : undefined;

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

@@ -43,6 +43,8 @@ export {
   mandateSpend,
   keptStep,
   UNREADABLE_PROJECT,
+  UNREADABLE_AGENT,
+  identifiedAgent,
   actionRefusalToolResult,
   usageFindings,
   usageToward,
@@ -271,6 +273,9 @@ export class JobStore {
   requestInput(jobId, inputRequests, statusMessage, { steps } = {}) {
     const entries = Object.entries(inputRequests ?? {});
     if (!entries.length || Array.isArray(inputRequests) || typeof inputRequests !== 'object') throw new InteropError('input_required needs a JSON object of at least one input request.'); // a JSON object of requests, first (unit 38, 40)
+    if (steps !== null && steps !== undefined && (typeof steps !== 'object' || Array.isArray(steps))) { // FAA-196 (26)
+      throw new InteropError('steps maps an input request\'s key to its approval step: a JSON object, or none.');
+    }
     const kept = Object.create(null); // the value checked is the value kept (seam 34); a key __proto__ stays a key (35)
     for (const [key, step] of Object.entries(steps ?? {})) {
       kept[key] = Object.hasOwn(inputRequests, key) && step !== null && step !== undefined ? keptStep(step) : {};

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

@@ -1,5 +1,15 @@
 // One copy of a service, locked before any side effect (LC-01, DEC-0057): the instance lock and the supervisor marker.
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_lock.py. Node 20+ (22+ for the Linux lock), no dependency.
+//
+// A lock that moves under its holder (FAA-303). Linux and Windows hold a name keyed by the lock's path (an abstract
+// unix socket, a named pipe), so a folder swapped under a running copy cannot let a second copy in. macOS has no such
+// name: O_EXLOCK (and the Python twin's flock) lock an inode, so after a data import swaps the data folder a second
+// copy locks the new file and starts. There the holder watches its lock instead (InstanceLock#watch, started by
+// holdSingleInstance): every LOCK_WATCH_SECONDS it compares the inode it locked with the file at the path, and once
+// the path names another file it stops with 75 and one sentence naming the path, before writing anything more into a
+// folder that is no longer the one it read. Two copies then overlap for at most one interval. A path-keyed name on
+// macOS was weighed and left: it needs a file in a folder outside the data folder that the system never cleans and
+// every copy can write, which Node alone cannot promise.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import net from 'node:net';
@@ -15,6 +25,12 @@ export const LOCK_BACKOFF_FIRST_SECONDS = 0.5;
 
 export const LOCK_BACKOFF_MAX_SECONDS = 30;
 
+/**
+ * How often a holder that has no path-keyed name (macOS) compares the inode it locked with the file at the lock's path
+ * (FAA-303): one stat and one fstat; two copies overlap for at most this long after a folder swap.
+ */
+export const LOCK_WATCH_SECONDS = 2;
+
 const O_EXLOCK = 0x20; // BSD/macOS: open(2) takes flock(LOCK_EX); absent from fs.constants
 
 export class AlreadyRunning extends ServiceError {
@@ -34,6 +50,7 @@ export class InstanceLock {
     this.path = path.join(dataDir, 'service.lock');
     this.fd = null;
     this.server = null;
+    this.timer = null;
   }
 
   async acquire() {
@@ -124,11 +141,75 @@ export class InstanceLock {
     return true;
   }
 
+  /**
+   * Re-check, every `intervalSeconds` on an unref'd timer, that the file this copy locked is still the file at the path
+   * (FAA-303); the first time the path names another file (a swapped folder's lock, or the one a second copy made),
+   * call `onLost(lock)` once and stop watching. The default stops the process with 75 and one sentence
+   * (stopLostHolder). A path that is gone or cannot be read now is read as nothing there yet and tried again next time:
+   * a second copy has to make a file there to start, and the watch then sees that file. `release` ends the watch. Only
+   * a lock held as a file is watched (macOS): elsewhere the descriptor is null and the path-keyed name keeps a second
+   * copy out, so this is a no-op, as for a lock not held.
+   */
+  watch({ onLost, intervalSeconds = LOCK_WATCH_SECONDS } = {}) {
+    if (this.fd === null || this.timer !== null) return this;
+    const fd = this.fd;
+    const react = onLost ?? stopLostHolder;
+    this.timer = setInterval(() => {
+      let here;
+      let held;
+      try {
+        here = fs.statSync(this.path);
+        held = fs.fstatSync(fd);
+      } catch {
+        return;
+      }
+      if (here.dev === held.dev && here.ino === held.ino) return;
+      clearInterval(this.timer);
+      this.timer = null;
+      react(this);
+    }, intervalSeconds * 1000);
+    this.timer.unref();
+    return this;
+  }
+
+  /**
+   * Let the lock go. Never throws, so a release in a `finally` never replaces the caller's own outcome (FAA-196 (11)):
+   * the descriptor and the name's server are forgotten before they are closed, so a retry never closes a descriptor
+   * reused since, and a close that fails still closes the server.
+   */
   release() {
-    if (this.fd !== null) fs.closeSync(this.fd);
-    if (this.server) this.server.close();
+    if (this.timer !== null) clearInterval(this.timer);
+    const { fd, server } = this;
+    this.timer = null;
     this.fd = null;
     this.server = null;
+    try {
+      if (fd !== null) fs.closeSync(fd);
+    } catch { // the descriptor is gone either way; the kernel frees the lock with it
+    } finally {
+      try {
+        server?.close();
+      } catch { // nothing to add to the caller's own outcome
+      }
+    }
+  }
+}
+
+/** The one sentence a holder whose lock moved under it stops with (FAA-303). */
+export function lostLockMessage(lockPath) {
+  return `${lockPath} is no longer the file this copy locked (the data folder moved or was swapped?): stopping, so a copy started on the folder now at that path runs alone.`;
+}
+
+/**
+ * InstanceLock#watch's default: write lostLockMessage and end the process with 75 at once. Not a graceful stop: a
+ * shutdown would write this copy's state into the folder now at the path, which is not the one it read; the kit's
+ * journals make an abrupt stop recoverable (LC-03).
+ */
+export function stopLostHolder(lock) {
+  try {
+    fs.writeSync(2, `${lostLockMessage(lock.path)}\n`);
+  } finally {
+    process.exit(EXIT_ALREADY_RUNNING);
   }
 }
 
@@ -253,10 +334,12 @@ const sleepSeconds = (s) => new Promise((resolve) => setTimeout(resolve, s * 100
  * supervisor that restarts on exit (launchd's KeepAlive) an immediate exit is a respawn every ThrottleInterval,
  * forever; so a supervised copy first backs off in-process (0.5 s doubling to 30 s,
  * LOCK_WAIT_SUPERVISED_SECONDS in all), takes over if the holder leaves, and exits 75 only when
- * the wait runs out. `waitSeconds` overrides the choice (0 = never wait).
+ * the wait runs out. `waitSeconds` overrides the choice (0 = never wait). Where the lock is held as a file (macOS)
+ * the held lock is watched (InstanceLock#watch, FAA-303): a folder swapped under the running copy stops it with 75;
+ * `onLost` replaces that reaction.
  */
 export async function holdSingleInstance(dataDir, {
-  waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code), env, argv,
+  waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code), env, argv, onLost,
 } = {}) {
   // DEC-0057: markers that disagree exit 75 at once, before the lock, naming them.
   const marker = supervisorMarker({ ...(env === undefined ? {} : { env }), ...(argv === undefined ? {} : { argv }) });
@@ -270,7 +353,7 @@ export async function holdSingleInstance(dataDir, {
   let announced = false;
   for (;;) {
     try {
-      return await new InstanceLock(dataDir).acquire();
+      return (await new InstanceLock(dataDir).acquire()).watch({ onLost });
     } catch (error) {
       if (!(error instanceof AlreadyRunning)) throw error;
       const remaining = deadline - clock();

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

@@ -193,6 +193,11 @@ const invalid = (detail) => ({ ok: false, code: MANDATE_INVALID, data: { detail
  * being where the operator said the words when the mandate carries it (DEC-0126 OA-6). `callerAgent` is
  * passed only when the callee authenticated the caller's agent id; without one the chain's end alone binds it. A missing
  * or non-object `call` is read as a call that names nothing (the reference would throw).
+ *
+ * A call is a plain object of its own data properties (FAA-196 (19)): its members are read as own members only, where
+ * the contract's reference reads plain properties, so an inherited or getter `project`, `action` or `spendUsd` is none
+ * here and may be covered where the reference refuses it. Build the call as an object literal of the values the work
+ * names, as the kit's own readers do (the board's `covers`, actionGate, jobStep).
  */
 export function mandateCovers(input) {
   const field = (key) => member(input, key);

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

@@ -86,6 +86,26 @@ function checkAttribution(projectId, taskRunId) {
   }
 }
 
+// Why a base URL is not sent the same by both twins, read from the URL as sent (its ends trimmed), or null: a backslash
+// anywhere (new URL reads it as a slash), and after a `//` authority a path holding anything but URL path characters
+// and %XX escapes (Python refused a space or a character outside ASCII where new URL percent-encoded it, and new URL
+// removes a tab or a line break) or a dot segment, escaped or not (new URL collapses it). The Python twin's
+// base_url_problem is the same rule (FAA-187 (18), kit-openrouter-cases.json).
+export function baseUrlProblem(base) {
+  const text = String(base).replace(/^[\x00-\x20]+|[\x00-\x20]+$/g, '');
+  if (text.includes('\\')) return 'the base URL holds a backslash';
+  if (/[\t\n\r]/.test(text)) return 'the base URL holds a tab or a line break'; // new URL removes them and sends the rest
+  const rest = text.slice(text.indexOf(':') + 1);
+  if (text.indexOf(':') < 0 || !rest.startsWith('//')) return null; // no authority as written: checkUrl reads it
+  const after = rest.slice(2);
+  const path = after.includes('/') ? after.slice(after.indexOf('/')) : '';
+  if (!/^(?:\/(?:[A-Za-z0-9._~!$&'()*+,;=:@-]|%[0-9A-Fa-f]{2})*)*$/.test(path)) {
+    return 'the base URL\'s path holds a character outside URL path characters and %XX escapes';
+  }
+  if (path.split('/').slice(1).some((seg) => ['.', '..'].includes(seg.replace(/%2e/gi, '.')))) return 'the base URL\'s path holds a dot segment';
+  return null;
+}
+
 export class Client {
   constructor({ ceilingUsd, ledger, prices, keyEnv = 'OPENROUTER_API_KEY', window = 'day', baseUrl = BASE_URL,
     attribution = null, projectId, unmeasuredCallUsd = null, deadlineS = 120, retries = 1, env = process.env,
@@ -108,13 +128,14 @@ export class Client {
     if (/[?#]/.test(baseUrl)) {
       throw new OpenRouterError('the base URL holds no query or fragment', { kind: 'config' });
     }
+    const problem = baseUrlProblem(baseUrl);
+    if (problem) throw new OpenRouterError(`${problem} (both kits would not send it alike)`, { kind: 'config' });
     http.checkUrl(baseUrl);
     checkAttribution(projectId, undefined);
     Object.assign(this, { ceilingUsd, ledger, keyEnv, window, attribution, projectId, unmeasuredCallUsd, deadlineS, retries });
     this.prices = Object.fromEntries(Object.entries(prices ?? {}).map(([k, v]) => [k, { ...v }]));
-    // The base URL as checkUrl read it: `new URL` removes tabs and line breaks anywhere and trims C0 controls and
-    // spaces from its ends, so `.../v1/ ` and `.../v1\n/` are composed as `.../v1/chat/completions`, as `new URL`
-    // composed them in 0.55.0 (0.56.0 product r20, unit r22, seam r22; the Python twin refuses what urllib cannot send).
+    // The base URL as checkUrl read it: its ends trimmed of C0 controls and spaces, so `.../v1/ ` is composed as
+    // `.../v1/chat/completions` (0.56.0 product r20); a tab or line break inside is refused above since FAA-187 (18).
     this.baseUrl = baseUrl.replace(/[\t\n\r]/g, '').replace(/^[\x00-\x20]+|[\x00-\x20]+$/g, '').replace(/\/+$/, '');
     this.env = env;
     this.transport = transport;