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

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

@@ -0,0 +1,266 @@
+// 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).
+// Node 20+, no dependency.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { ServiceError, nowIso } from './fabric-base.mjs';
+import { atomicWrite } from './fabric-paths.mjs';
+import { decisionShape } from './fabric-actions.mjs';
+import { QUOTA_EXHAUSTED, codePoints, pauseMessage, readJobPause, utcTime } from './fabric-interop-rules.mjs';
+import { secretValue } from './fabric-secrets.mjs';
+
+/** The limits a hold names: a daily quota, a per-caller share, a concurrency cap, a money cap. */
+export const HOLD_REASONS = Object.freeze(['daily-quota', 'caller-share', 'concurrency', 'money']);
+/** How the push names each reason to a person. */
+export const REASON_WORDS = Object.freeze({
+  'daily-quota': 'the daily quota', 'caller-share': 'its per-caller share',
+  concurrency: 'the concurrency cap', money: 'the money cap',
+});
+/** The push's kind: a decision for the operator (level notice, notify true). */
+export const HOLD_EVENT_KIND = 'limit.held';
+/** The record of a lift applied (level info, no notify). */
+export const LIFT_EVENT_KIND = 'limit.lifted';
+/** The decision action a lift carries (DEC-0121 AP-2 shape). */
+export const LIFT_ACTION = 'limit.lift';
+const MAX_STATUS_MESSAGE = 500;
+const WAITING = /^waiting (daily-quota|caller-share|concurrency|money) since ([0-9][0-9TZ:.-]*?)(?:: ([\s\S]+))?$/;
+const SIZES = ['jobs', 'usd', 'limit'];
+
+const instant = (value, name) => {
+  if (!Number.isFinite(utcTime(value))) throw new ServiceError(`${name} is a UTC instant (Z, at most 3 fraction digits).`);
+  return value;
+};
+const reasonOk = (reason, what) => {
+  if (!HOLD_REASONS.includes(reason)) throw new ServiceError(`A ${what}'s reason is one of ${HOLD_REASONS.join(', ')}.`);
+};
+const squash = (text) => String(text).split(/\s+/).filter(Boolean).join(' ');
+
+/** A held job's statusMessage; the message is shortened, never refused, to fit 500 characters. */
+export function waitingMessage(reason, since, until = null, message = null) {
+  reasonOk(reason, 'hold');
+  instant(since, 'since');
+  if (until !== null && until !== undefined) instant(until, 'until');
+  else until = null;
+  let text = `waiting ${reason} since ${since}`;
+  const head = QUOTA_EXHAUSTED.length + (until === null ? 0 : ' until '.length + until.length) + ': '.length;
+  if (message !== null && message !== undefined) {
+    const squashed = squash(message);
+    const room = MAX_STATUS_MESSAGE - head - codePoints(text) - ': '.length;
+    if (squashed && room > 0) {
+      text += ': ' + (codePoints(squashed) <= room ? squashed : [...squashed].slice(0, room - 3).join('').trimEnd() + '...');
+    }
+  }
+  return pauseMessage(until === null ? { text } : { resetsAt: until, text });
+}
+
+/** `{reason, since, until?, message?}` of a fabric.job.get answer whose job a limit holds, else null. */
+export function readWaiting(answer) {
+  const pause = readJobPause(answer);
+  if (!pause.paused) return null;
+  let rest = answer.job.statusMessage.slice(QUOTA_EXHAUSTED.length);
+  if ('resetsAt' in pause) rest = rest.slice(' until '.length + pause.resetsAt.length);
+  if (!rest.startsWith(': ')) return null;
+  const match = WAITING.exec(rest.slice(2));
+  if (!match || !Number.isFinite(utcTime(match[2]))) return null;
+  const waiting = { reason: match[1], since: match[2] };
+  if ('resetsAt' in pause) waiting.until = pause.resetsAt;
+  if (match[3] !== undefined) waiting.message = match[3];
+  return waiting;
+}
+
+/** Put one job of a fabric-interop JobStore on hold (JobStore.pause with the waiting text). */
+export function holdJob(jobs, jobId, reason, since, until = null, message = null) {
+  let text = waitingMessage(reason, since, until, message).slice(QUOTA_EXHAUSTED.length);
+  if (until !== null && until !== undefined) text = text.slice(' until '.length + until.length);
+  return jobs.pause(jobId, until === null || until === undefined ? { text: text.slice(2) } : { resetsAt: until, text: text.slice(2) });
+}
+
+/** The push's one sentence: who, what, why, when it frees by itself, and the question. */
+export function holdSentence(caller, work, reason, until) {
+  const frees = until !== null && until !== undefined ? `it frees by itself at ${until}`
+    : (['concurrency', 'caller-share'].includes(reason) ? 'it frees by itself when a running job ends' : 'it does not free by itself');
+  return `${work} for ${caller} is held by ${REASON_WORDS[reason]}; ${frees}. Raise the limit for it?`;
+}
+
+function text(value, name, high = 200) {
+  if (typeof value !== 'string' || !value.trim() || value.length > high) throw new ServiceError(`${name} is a text of 1 to ${high} characters.`);
+  if (secretValue(value)) throw new ServiceError(`${name} looks like a credential; a hold names callers and work, never a secret.`);
+  return squash(value);
+}
+
+const newId = () => crypto.randomUUID().replaceAll('-', '');
+
+/**
+ * The holds a service's limits put on work and the operator's lifts, in one file (0600, written atomically).
+ * `events`, when given, is a function `({kind, level, text, subject, notify}) => event` that writes the push and the
+ * lift record to the service's event log; without it they are returned for the service to write.
+ */
+export class HoldBook {
+  constructor(file, { events = null, clock = nowIso } = {}) {
+    this.file = file;
+    this.events = events;
+    this.clock = clock;
+  }
+
+  load() {
+    if (!fs.existsSync(this.file)) return { holds: [], lifts: [] };
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+    } catch {
+      throw new ServiceError('The hold book is not JSON; it is kept as it is.');
+    }
+    if (data === null || typeof data !== 'object' || !Array.isArray(data.holds) || !Array.isArray(data.lifts)) {
+      throw new ServiceError('The hold book is not {holds, lifts}; it is kept as it is.');
+    }
+    return data;
+  }
+
+  save(data) { atomicWrite(this.file, JSON.stringify(data, null, 1) + '\n', 0o600); }
+
+  now(now) { return instant(now ?? this.clock(), 'now'); }
+
+  emit(kind, level, sentence, subject, notify) {
+    const event = { kind, level, text: sentence, subject };
+    if (notify) event.notify = true;
+    return this.events ? this.events(event) : event;
+  }
+
+  static expire(data, at) {
+    for (const hold of data.holds) {
+      if (hold.closed === null && hold.until !== null && utcTime(hold.until) <= at) {
+        hold.closed = 'expired';
+        hold.closedAt = hold.until;
+      }
+    }
+  }
+
+  static live(lift, at) {
+    if (lift.from !== null && lift.from !== undefined && utcTime(lift.from) > at) return false;
+    if (lift.until !== null && lift.until !== undefined && utcTime(lift.until) <= at) return false;
+    return (lift.left ?? 1) > 0;
+  }
+
+  /** 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 }) {
+    caller = text(caller, 'caller');
+    work = text(work, 'work');
+    reasonOk(reason, 'hold');
+    const at = this.now(now);
+    if (until !== null && utcTime(instant(until, 'until')) <= utcTime(at)) {
+      throw new ServiceError(`until ${until} has passed: the limit no longer holds the work.`);
+    }
+    const data = this.load();
+    HoldBook.expire(data, utcTime(at));
+    let hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    const opened = hold === undefined;
+    if (opened) {
+      hold = { id: newId(), reason, caller, work, since: at, until, jobs: [], closed: null };
+      data.holds.push(hold);
+    }
+    if (jobId !== null && !hold.jobs.includes(String(jobId))) hold.jobs.push(String(jobId));
+    this.save(data);
+    const statusMessage = waitingMessage(reason, hold.since, hold.until, message);
+    const push = opened ? this.emit(HOLD_EVENT_KIND, 'notice', holdSentence(caller, work, reason, until),
+      { type: 'limit', id: `${reason}:${caller}`.slice(0, 200), label: REASON_WORDS[reason] }, true) : null;
+    return { hold: { ...hold }, statusMessage, push };
+  }
+
+  /** Close the open hold of (reason, caller): the limit freed the work. The next hold pushes again. */
+  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);
+    if (!hold) return null;
+    hold.closed = 'released';
+    hold.closedAt = at;
+    this.save(data);
+    return { ...hold };
+  }
+
+  openHolds(now = null) {
+    const data = this.load();
+    HoldBook.expire(data, utcTime(this.now(now)));
+    return data.holds.filter((h) => h.closed === null).map((h) => ({ ...h }));
+  }
+
+  /** Record the operator's answer as a scoped lift: exactly one of jobs, usd or limit (limit needs until). */
+  lift({ reason, decision, caller = null, jobId = null, jobs = null, usd = null, limit = null, until = null, now = null }) {
+    reasonOk(reason, 'lift');
+    if (!decisionShape(decision) || decision.action !== LIFT_ACTION) {
+      throw new ServiceError("A lift carries the operator's decision (decision.schema.json, action limit.lift, their "
+        + "words verbatim): operatorDecision({ action: 'limit.lift', instruction: words }).");
+    }
+    const sizes = { jobs, usd, limit };
+    const given = SIZES.filter((name) => sizes[name] !== null && sizes[name] !== undefined);
+    if (given.length !== 1) throw new ServiceError('A lift is one of jobs, usd or limit.');
+    const kind = given[0];
+    const size = sizes[kind];
+    if (typeof size !== 'number' || !Number.isFinite(size) || size <= 0 || (kind !== 'usd' && !Number.isInteger(size))) {
+      throw new ServiceError(`A lift's ${kind} is a positive ${kind === 'usd' ? 'number' : 'integer'}.`);
+    }
+    const at = this.now(now);
+    if (until !== null && utcTime(instant(until, 'until')) <= utcTime(at)) throw new ServiceError("A lift's window ends after now.");
+    if (kind === 'limit' && until === null) {
+      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 };
+    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)
+        && (jobId === null || hold.jobs.includes(String(jobId)))) {
+        hold.closed = 'lifted';
+        hold.closedAt = at;
+        hold.lift = record.id;
+      }
+    }
+    data.lifts.push(record);
+    this.save(data);
+    const scope = record.caller ? `for ${record.caller}` : 'for every caller';
+    const amount = { jobs: `${size} more job(s)`, usd: `USD ${size} more`, limit: `the limit at ${size}` }[kind];
+    this.emit(LIFT_EVENT_KIND, 'info', `The operator lifted ${REASON_WORDS[reason]} ${scope}: ${amount}${until ? ` until ${until}` : ''}.`,
+      { type: 'limit', id: `${reason}:${record.caller ?? '*'}`, label: REASON_WORDS[reason] }, false);
+    return { ...record };
+  }
+
+  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));
+  }
+
+  /** Whether a lift lets work past the limit: {admitted: true, lift, left} spends one job or `costUsd`, else {admitted: false}. */
+  admit({ reason, caller, jobId = null, costUsd = null, now = null }) {
+    const at = utcTime(this.now(now));
+    const data = this.load();
+    const kind = costUsd !== null ? 'usd' : 'jobs';
+    const found = HoldBook.matching(data, reason, caller, jobId === null ? null : String(jobId), at, kind)
+      .sort((a, b) => ((a.job === null) - (b.job === null)) || ((a.caller === null) - (b.caller === null)));
+    for (const lift of found) {
+      const need = kind === 'usd' ? costUsd : 1;
+      if (lift.left >= need) {
+        lift.left = kind === 'usd' ? Math.round((lift.left - need) * 1e6) / 1e6 : lift.left - 1;
+        this.save(data);
+        return { admitted: true, lift: lift.id, left: lift.left };
+      }
+    }
+    return { admitted: false };
+  }
+
+  /** The limit in force: `base`, or the highest live raised limit for (reason, caller). */
+  limit({ reason, base, caller = null, now = null }) {
+    const at = utcTime(this.now(now));
+    return Math.max(base, ...HoldBook.matching(this.load(), reason, caller, null, at, 'limit').map((l) => l.limit));
+  }
+
+  /** Every lift with `live`: whether it still applies now. */
+  lifts(now = null) {
+    const at = utcTime(this.now(now));
+    return this.load().lifts.map((l) => ({ ...l, live: HoldBook.live(l, at) }));
+  }
+}

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

@@ -16,9 +16,12 @@
 // The transport is injected in tests: async ({ method, url, headers, body, timeoutS, maxBytes }) =>
 // { status, headers, body: Uint8Array }, throwing on a connection error (a `TimeoutError` name is a timeout) or an
 // HttpError. Node 20 or newer, no dependencies. Part of the service kit (FAA-65, layer L4).
+//
+// Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 import http from 'node:http';
-import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+import net from 'node:net';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED, UNKNOWN, method as tableMethod, owner as ownerOf, refusal, serverEnd } from './fabric-peer-owner.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']);
@@ -27,7 +30,7 @@ const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 
 export class HttpError extends Error {
   constructor(message, { status = null, url = '', attempts = 0, retryAfterS = null, body = new Uint8Array(0),
-    kind = 'http' } = {}) {
+    kind = 'http', reason = null } = {}) {
     super(message);
     this.name = 'HttpError';
     this.status = status;
@@ -36,6 +39,8 @@ export class HttpError extends Error {
     this.retryAfterS = retryAfterS;
     this.body = body.slice(0, 2048);
     this.kind = kind; // http, connection, timeout, too-large, refused, foreign-user
+    // For foreign-user, why (FAA-272): table-restricted (never clears), the owner's kind, or the check's reason.
+    this.reason = reason;
   }
 }
 
@@ -154,6 +159,61 @@ function checkHeaders(headers) {
 
 const LOOPBACK_AGENT = new CheckedAgent();
 
+// Whether a connected socket reached this computer's loopback, by the address it connected to, not by the URL's
+// spelling: a name the hosts file maps to 127.0.0.1, `0.0.0.0` and `[::ffff:127.0.0.1]` arrive here (FAA-260).
+export function peerIsLoopback(address) {
+  const a = String(address ?? '').split('%', 1)[0].toLowerCase();
+  if (a === '::1' || a === '0.0.0.0' || a === '::') return true;
+  const v4 = /^(?:::ffff:)?(\d{1,3})\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.exec(a);
+  if (v4) return v4[1] === '127';
+  const hex = /^::ffff:([0-9a-f]{1,4}):[0-9a-f]{1,4}$/.exec(a);
+  return hex !== null && (parseInt(hex[1], 16) >> 8) === 127;
+}
+
+// An http.Agent for plain http to a host not spelled as loopback (`insecure`): when the connected socket's peer is a
+// loopback address, its server end is told as CheckedAgent tells it and refused before a byte is written unless it is
+// this OS account's process (DEC-0154 HA-2; 0.74.0 unit readings 7 and 8, FAA-260). Another peer is used as it is.
+export class PeerCheckedAgent extends http.Agent {
+  constructor({ ask = {}, ...options } = {}) {
+    super(options);
+    this.ask = ask;
+  }
+
+  createConnection(options, callback) {
+    let done = false;
+    const finish = (err, socket) => { if (!done) { done = true; callback(err, socket); } };
+    const port = Number(options.port);
+    const socket = net.connect({ host: options.host, port, noDelay: true, autoSelectFamily: true,
+      ...(options.lookup ? { lookup: options.lookup } : {}) });
+    socket.once('error', (err) => finish(err));
+    socket.once('connect', async () => {
+      if (!peerIsLoopback(socket.remoteAddress)) {
+        socket.removeAllListeners('error');
+        finish(null, socket);
+        return;
+      }
+      socket.pause();
+      let who;
+      try {
+        who = await serverEnd(socket, this.ask);
+      } catch (err) {
+        who = ownerOf(UNKNOWN, { method: tableMethod(), reason: `check: ${err?.name ?? 'Error'}` });
+      }
+      const refused = refusal(who, port, null);
+      if (refused) {
+        socket.destroy();
+        finish(new ListenerRefused(refused[0], `${refused[1]}; nothing was sent`, who));
+        return;
+      }
+      socket.removeAllListeners('error');
+      socket.resume();
+      finish(null, socket);
+    });
+  }
+}
+
+const PLAIN_AGENT = new PeerCheckedAgent();
+
 // Plain http to a loopback host (DEC-0154 HA-2): node:http over a connection checked before a byte is written, no
 // redirect followed, the body read to one byte past maxBytes. fetch cannot hand its socket to the check.
 export function checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes, agent = LOOPBACK_AGENT }) {
@@ -184,7 +244,9 @@ export function checkedLoopbackTransport({ method, url, headers, body, timeoutS,
     req.on('error', (err) => {
       clearTimeout(timer);
       if (err instanceof ListenerRefused) {
-        reject(new HttpError(`${method} ${redactUrl(url)}: foreign-user: ${err.message}`, { url: redactUrl(url), kind: 'foreign-user' }));
+        const why = String(err.owner?.reason ?? err.owner?.kind ?? err.code ?? 'unknown');
+        const reason = why.startsWith(TABLE_RESTRICTED) ? TABLE_RESTRICTED : why.split(':', 1)[0];
+        reject(new HttpError(`${method} ${redactUrl(url)}: foreign-user: ${err.message}`, { url: redactUrl(url), kind: 'foreign-user', reason }));
       } else reject(err);
     });
     if (body) req.write(body);
@@ -192,12 +254,15 @@ export function checkedLoopbackTransport({ method, url, headers, body, timeoutS,
   });
 }
 
-// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes; plain http to a
-// loopback host goes through checkedLoopbackTransport.
+// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes; plain http goes
+// through checkedLoopbackTransport, its connection checked when it reaches loopback (FAA-260).
 export async function fetchTransport({ method, url, headers, body, timeoutS, maxBytes }) {
   const target = new URL(url);
-  if (target.protocol === 'http:' && isLoopback(target.hostname)) {
-    return checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes });
+  if (target.protocol === 'http:') {
+    // plain http never goes through fetch: a URL spelled as loopback is checked on every connection, any other is
+    // checked when its connected peer is a loopback address (FAA-260)
+    return checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes,
+      ...(isLoopback(target.hostname) ? {} : { agent: PLAIN_AGENT }) });
   }
   const res = await fetch(url, { method, headers, body: body ?? undefined, redirect: 'manual',
     signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutS * 1000))) });

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

@@ -27,7 +27,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { atomicWrite, ensurePrivateDir, readToken } from './fabric-service.mjs';
 import { hubKeyCertified } from './fabric-estate.mjs';
-import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
 
 // DEC-0154 HA-2: every connection to the door is checked before a byte goes out; kept alive, so a busy session reads the
 // socket table once per connection, not once per call. A free socket is closed after 2 s idle, before a server's own
@@ -53,6 +53,20 @@ 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.
+ */
+export function listenerRefusal(e) {
+  const kind = e?.owner?.kind ?? null;
+  const why = String(e?.owner?.reason ?? kind ?? e?.code ?? 'unknown');
+  const reason = why.startsWith(TABLE_RESTRICTED) ? TABLE_RESTRICTED : why.split(':', 1)[0];
+  const shown = kind && e?.owner?.reason ? `${kind}: ${e.owner.reason}` : String(kind ?? why);
+  return new HubError('foreign-user', `The hub's port is not held by this OS account's process (${shown}); nothing was sent.`, reason !== TABLE_RESTRICTED, { reason });
+}
+
 /** Fabric's registry root, where hub.json lives (Fabric agentRegistry.ts#registryDirs). */
 export function fabricRoot(platform = process.platform, env = process.env) {
   const home = env.HOME || env.USERPROFILE || os.homedir();
@@ -202,7 +216,7 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
     });
     req.on('timeout', () => req.destroy(new Error('timeout')));
     req.on('error', (e) => reject(e instanceof ListenerRefused
-      ? new HubError('foreign-user', `The hub's port is not held by this OS account's process (${e.owner?.kind ?? e.code}); nothing was sent.`, true)
+      ? listenerRefusal(e)
       : new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));
     if (payload) req.write(payload);
     req.end();