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

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

@@ -1,8 +1,11 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Work a service holds by its own limits, said to its caller and its operator (FAA-298): a held job's statusMessage in
 // the contract's pause grammar (`quota-exhausted[ until <until>]: waiting <reason> since <since>[: <message>]`; the
 // pinned interop-job schema is closed, so `waiting {reason, since, until, message}` rides statusMessage, never a field
 // of the job), one push per hold, and the operator's scoped lift. The twin of fabric_holds.py, held to the same
-// vectors (test/fixtures/holds/waiting-vectors.json). Part of the Node service kit (layer L3, after fabric-interop).
+// vectors (test/fixtures/holds/waiting-vectors.json). A record written since 0.83.0 carries `squash: 'ecmascript'`; one
+// without it is matched under both squashes, as 0.81.0's Python twin squashed names with str.split() (FAA-320,
+// test/fixtures/holds/legacy-squash-vectors.json). Part of the Node service kit (layer L3, after fabric-interop).
 // Node 20+, no dependency.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
@@ -40,6 +43,17 @@ const reasonOk = (reason, what) => {
 // (FAA-316): Python's str.split() also takes U+001C to U+001F and U+0085 and not U+FEFF.
 const SPACES = /[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+/g;
 const squash = (text) => String(text).replace(SPACES, ' ').replace(/^ | $/g, '');
+/** What a record written since 0.83.0 carries: its names were squashed with ECMAScript's whitespace (FAA-320). */
+export const SQUASH = 'ecmascript';
+// Python's str.isspace() class, the one 0.81.0's Python twin squashed a name with (`" ".join(text.split())`).
+const PY_SPACES = /[\t\n\v\f\r\u001c-\u001f \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/g;
+const legacySquash = (text) => String(text).replace(PY_SPACES, ' ').replace(/^ | $/g, '');
+// The stored forms `caller` matches in `record`: the ECMAScript squash, and for a record with no `squash` mark (written
+// before 0.83.0) also the squash 0.81.0's Python twin wrote (FAA-320). null matches only null.
+const names = (caller, record) => {
+  if (typeof caller !== 'string') return [caller];
+  return record.squash === SQUASH ? [squash(caller)] : [squash(caller), legacySquash(caller)];
+};
 
 /** A held job's statusMessage; the message is shortened, never refused, to fit 500 characters. */
 export function waitingMessage(reason, since, until = null, message = null) {
@@ -149,6 +163,7 @@ export class HoldBook {
 
   /** Hold `work` for `caller` by `reason`: {hold, statusMessage, push}; push only when this call opened the hold. */
   hold({ caller, work, reason, until = null, message = null, jobId = null, now = null }) {
+    const rawCaller = caller;
     caller = text(caller, 'caller');
     work = text(work, 'work');
     reasonOk(reason, 'hold');
@@ -158,10 +173,10 @@ export class HoldBook {
     }
     const data = this.load();
     HoldBook.expire(data, utcTime(at));
-    let hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    let hold = data.holds.find((h) => h.closed === null && h.reason === reason && names(rawCaller, h).includes(h.caller));
     const opened = hold === undefined;
     if (opened) {
-      hold = { id: newId(), reason, caller, work, since: at, until, jobs: [], closed: null };
+      hold = { id: newId(), reason, caller, work, since: at, until, jobs: [], closed: null, squash: SQUASH };
       data.holds.push(hold);
     }
     if (jobId !== null && !hold.jobs.includes(String(jobId))) hold.jobs.push(String(jobId));
@@ -176,7 +191,7 @@ export class HoldBook {
   release({ reason, caller, now = null }) {
     const at = this.now(now);
     const data = this.load();
-    const hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    const hold = data.holds.find((h) => h.closed === null && h.reason === reason && names(caller, h).includes(h.caller));
     if (!hold) return null;
     hold.closed = 'released';
     hold.closedAt = at;
@@ -211,12 +226,12 @@ export class HoldBook {
       throw new ServiceError('A raised limit needs its window\'s end (until): it falls back when the window ends.');
     }
     const record = { id: newId(), reason, caller: caller === null ? null : text(caller, 'caller'),
-      job: jobId === null ? null : String(jobId), from: at, until, [kind]: size, decision: { ...decision }, at };
+      job: jobId === null ? null : String(jobId), from: at, until, [kind]: size, decision: { ...decision }, at, squash: SQUASH };
     if (kind !== 'limit') record.left = size;
     const data = this.load();
     HoldBook.expire(data, utcTime(at));
     for (const hold of data.holds) {
-      if (hold.closed === null && hold.reason === reason && (record.caller === null || record.caller === hold.caller)
+      if (hold.closed === null && hold.reason === reason && (caller === null || names(caller, hold).includes(hold.caller))
         && (jobId === null || hold.jobs.includes(String(jobId)))) {
         hold.closed = 'lifted';
         hold.closedAt = at;
@@ -234,7 +249,7 @@ export class HoldBook {
 
   static matching(data, reason, caller, jobId, at, kind) {
     return data.lifts.filter((l) => l.reason === reason && kind in l && HoldBook.live(l, at)
-      && (l.caller === null || l.caller === caller) && (l.job === null || l.job === jobId));
+      && (l.caller === null || names(caller, l).includes(l.caller)) && (l.job === null || l.job === jobId));
   }
 
   /** Whether a lift lets work past the limit: {admitted: true, lift, left} spends one job or `costUsd`, else {admitted: false}. */

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // An outbound HTTP client for a service: one deadline across every attempt, bounded retries with jittered backoff,
 // `Retry-After` honoured up to a cap, a response size cap, and no secret in an error. The twin of fabric_http.py:
 // the same rules, the same cases (test/fixtures/kit-http-cases.json).
@@ -22,6 +23,7 @@
 import http from 'node:http';
 import net from 'node:net';
 import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED, UNKNOWN, method as tableMethod, owner as ownerOf, refusal, serverEnd } from './fabric-peer-owner.mjs';
+import { loopbackHost } from './fabric-socket-proof.mjs';
 
 export const RETRY_STATUSES = Object.freeze([408, 425, 429, 500, 502, 503, 504]);
 export const IDEMPOTENT_METHODS = Object.freeze(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
@@ -78,11 +80,8 @@ export function redactUrl(url) {
   return `${parts.protocol}//${parts.host}${parts.pathname}`;
 }
 
-function isLoopback(host) {
-  const h = host.replace(/^\[|\]$/g, '');
-  if (h === 'localhost' || h.endsWith('.localhost') || h === '::1') return true;
-  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
-}
+// Loopback as new URL leaves the host: the kit's one rule, shared with fabric-delegation (FAA-187 (15)).
+const isLoopback = loopbackHost;
 
 // Refuse what this client never sends: another scheme, no host, credentials in the URL, plain http off loopback.
 export function checkUrl(url, { insecure = false } = {}) {

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The Fabric hub's door, as a service agent reaches it (fabric-hub/0.1; Fabric ADR-0115 §1, ADR-0149 §4; FAA-12b).
 // The twin of fabric_hub.py, same rules and the same answers; Node built-ins only.
 //
@@ -79,7 +80,8 @@ export function fabricRoot(platform = process.platform, env = process.env) {
 /**
  * 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.
+ * 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;
@@ -192,7 +194,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));
@@ -224,6 +226,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-identifiers.mjs

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Identifier equality (contract DEC-0076): two identifiers are the same when their normal forms are equal. A port of the
 // contract's src/identifiers.ts (types removed), held to its fixtures/vectors/identifiers.json; the twin of
 // fabric_identifiers.py. Nothing here throws.

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // fabric-interop/0.1, the rule layer: the extension's names and limits, its errors, the trace context (C3.4), a usage
 // object's reading (C3.2) and the job limits and uncertain effects (DEC-0087). Every function answers by a rule and
 // touches no file; fabric-interop.mjs builds the tools, the envelope and the job store on it and re-exports every public
@@ -7,7 +8,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 +278,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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Reference kit for the fabric-interop/0.1 extension — Node.js 20+, no dependencies.
 // The Node twin of fabric_interop.py: the same rules and the same job file format, so a
 // job written by one kit is read by the other. The minimal MCP dispatcher is Python-only;
@@ -43,6 +44,8 @@ export {
   mandateSpend,
   keptStep,
   UNREADABLE_PROJECT,
+  UNREADABLE_AGENT,
+  identifiedAgent,
   actionRefusalToolResult,
   usageFindings,
   usageToward,
@@ -271,6 +274,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-jsvalue.mjs

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // JavaScript's view of JSON values, once for the whole Node kit (FAA-65, layer L0); the twin of fabric_jsvalue.py.
 // The contract's answers are computed by TypeScript; every reader in the kit takes these helpers from here:
 // isObject, isString, objects (an array's object items), indexed (with their index as written), show (the

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The call queue and the load report of DEC-0104 (contract src/agent-network.ts, FAC-SEM-131 to FAC-SEM-133), as the
 // contract's reference answers them: a node that hosts a job-backed agent queues its jobs per (agentRef, context) with
 // these and reports its load as service-load/1 under extensions/load/0.1. Part of the Node service kit (FAA-289, layer

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // 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.
 //
@@ -172,13 +173,26 @@ export class InstanceLock {
     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.timer !== null) clearInterval(this.timer);
-    if (this.fd !== null) fs.closeSync(this.fd);
-    if (this.server) this.server.close();
+    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
+      }
+    }
   }
 }
 

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // Logs and stopping (LC-01, LC-12): a rotating log, a capped stdout log, the stop signal and the drain.
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_logs.py. Node 20+, no dependency.
 import fs from 'node:fs';

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The operator's mandate, mandate/1 (DEC-0125, FAC-SEM-144): the operator's instruction for one task travels with the
 // task, narrowed at each hand-over. Part of the Node service kit (layer L2); the twin of fabric_mandate.py.
 //
@@ -193,6 +194,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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // OpenRouter chat completions for a service: its own key, a spend ceiling checked before every attempt, a usage receipt
 // for every answered call, and a fallback model of another vendor. The twin of fabric_openrouter.py: the same rules, the
 // same cases (test/fixtures/kit-openrouter-cases.json); the rules are written out in that file's docstring.
@@ -86,6 +87,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 +129,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;