@synadia-ai/agent-fabric-claude-code 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,63 +0,0 @@
-import { AgentExtensionContext, ScratchPadSettings, AgentExtension } from '@synadia-ai/agent-fabric';
-export { SCRATCHPAD_OPTION, SP_VARS, ScratchPadHandOn } from '@synadia-ai/agent-fabric';
-
-/** The variable that names the file to `scripts/sp`, set by the package's hook. */
-declare const SP_ENV_FILE_VAR = "SP_ENV_FILE";
-/** The sp binary this package ships for this machine, or `SCRATCHPAD_BIN`. */
-declare function spBinary(env: Record<string, string | undefined>): string | undefined;
-/**
- * The file for the Claude Code process this server runs under:
- * `<stateDir>/agent-fabric/<pid>.env`, where the hook looks for it. The pid
- * is `CLAUDE_PID`, which Claude Code hands its hooks and its MCP servers
- * alike, else the parent's, as the plugin keys its own files.
- */
-declare function spEnvFilePath(stateDir: string, env: Record<string, string | undefined>, parentPid?: number): string;
-/**
- * The variables `scripts/sp` reads, kept as a plain object (the one the
- * shared pieces set and clear) and written to the file after each change.
- */
-declare class SpEnvFile {
-    readonly path: string;
-    /** What the shared pieces set and clear; `write()` puts it in the file. */
-    readonly vars: Record<string, string | undefined>;
-    constructor(path: string);
-    /**
-     * The file, whole, through a rename, so `scripts/sp` reads one state or
-     * the next. A value with a line break could not be read back, so it is
-     * left out. Throws what the file system throws.
-     */
-    write(): void;
-    /** Removes the file, when the server stops; `scripts/sp` then finds no configuration. */
-    remove(): void;
-}
-
-/** The extension's name, as the plugin's status output lists it. */
-declare const EXTENSION_NAME = "agent-fabric";
-/** The name the proxy files Claude Code's calls under, and the served records carry. */
-declare const SERVED_HARNESS = "claude";
-/** How long an answered turn waits for the `Stop` hook before `end` carries the reply's time. */
-declare const DEFAULT_STOP_WAIT_MS = 120000;
-/** The warning logged once at start when the plugin's identity is off. */
-declare const IDENTITY_OFF_WARNING: string;
-/** The line logged for a prompt that arrives while no session is known. */
-declare const NO_SESSION_LINE: string;
-/** `true` iff `value` is shaped like a session id Claude Code would send. */
-declare function isClaudeSessionId(value: unknown): value is string;
-/**
- * The factory: the module's default export. Called once by the plugin's
- * MCP server, before it connects, with what it knows then. Resolves
- * ScratchPad's settings (which may read the plugin's NATS context) and
- * builds the extension with them. Throws `NatsAgentError` for an edge
- * subject that can never be published to, or a `stopWaitMs` option that
- * is not a duration.
- *
- * `env` is where the variables are read from; a test passes its own.
- */
-declare function fabricExtension(ctx: AgentExtensionContext, env?: NodeJS.ProcessEnv): Promise<AgentExtension>;
-/**
- * The extension, built synchronously from settings already resolved:
- * without `scratchPad`, tracing, the `served` pair and the guard alone.
- */
-declare function createFabricExtension(ctx: AgentExtensionContext, env?: NodeJS.ProcessEnv, scratchPad?: ScratchPadSettings): AgentExtension;
-
-export { DEFAULT_STOP_WAIT_MS, EXTENSION_NAME, IDENTITY_OFF_WARNING, NO_SESSION_LINE, SERVED_HARNESS, SP_ENV_FILE_VAR, SpEnvFile, createFabricExtension, fabricExtension as default, fabricExtension, isClaudeSessionId, spBinary, spEnvFilePath };

package/dist/index.js

@@ -1,248 +0,0 @@
-import { SP_VARS, spBinary as spBinary$1, resolveScratchPad, resolveEdgeSubject, fabricTracing, loopGuard, exportScratchPad, ServedPromptEnv, ScratchPadHandOn, bindActiveTrace, activeTrace, servedPublisher, READS_REFERENCES_KEY, spPort as spPort$1 } from '@synadia-ai/agent-fabric';
-export { SCRATCHPAD_OPTION, SP_VARS, ScratchPadHandOn } from '@synadia-ai/agent-fabric';
-import { NatsAgentError } from '@synadia-ai/agents';
-import { mkdirSync, writeFileSync, renameSync, rmSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-// src/extension.ts
-var SKILL_DIR = fileURLToPath(new URL("../skills/scratchpad", import.meta.url));
-var SP_ENV_FILE_VAR = "SP_ENV_FILE";
-function spBinary(env) {
-  return spBinary$1(env, SKILL_DIR);
-}
-function spPort(settings, creator, env) {
-  return spPort$1(settings, creator, env, SKILL_DIR);
-}
-function spEnvFilePath(stateDir, env, parentPid = process.ppid) {
-  const pid = env["CLAUDE_PID"];
-  return join(
-    stateDir,
-    "agent-fabric",
-    `${pid !== void 0 && /^\d+$/.test(pid) ? pid : String(parentPid)}.env`
-  );
-}
-var NAMES = new Set(Object.values(SP_VARS));
-var SpEnvFile = class {
-  constructor(path) {
-    this.path = path;
-  }
-  path;
-  /** What the shared pieces set and clear; `write()` puts it in the file. */
-  vars = {};
-  /**
-   * The file, whole, through a rename, so `scripts/sp` reads one state or
-   * the next. A value with a line break could not be read back, so it is
-   * left out. Throws what the file system throws.
-   */
-  write() {
-    let text = "";
-    for (const [name, value] of Object.entries(this.vars)) {
-      if (!NAMES.has(name) || value === void 0 || /[\r\n]/.test(value)) continue;
-      text += `${name}=${value}
-`;
-    }
-    mkdirSync(dirname(this.path), { recursive: true, mode: 448 });
-    const staging = `${this.path}.${process.pid}.tmp`;
-    writeFileSync(staging, text, { mode: 384 });
-    renameSync(staging, this.path);
-  }
-  /** Removes the file, when the server stops; `scripts/sp` then finds no configuration. */
-  remove() {
-    rmSync(this.path, { force: true });
-  }
-};
-
-// src/extension.ts
-var EXTENSION_NAME = "agent-fabric";
-var SERVED_HARNESS = "claude";
-var DEFAULT_STOP_WAIT_MS = 12e4;
-var IDENTITY_OFF_WARNING = `${EXTENSION_NAME}: senderIdentity is off; trace records are signed, so none will be published and each counts as dropped on the heartbeat. Set senderIdentity to signed.`;
-var NO_SESSION_LINE = `${EXTENSION_NAME}: no Claude Code session id known for this prompt, so no served pair; its model calls stand as a harness thread of their own. Are the plugin's hooks registered?`;
-var SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
-function isClaudeSessionId(value) {
-  return typeof value === "string" && SESSION_ID_RE.test(value);
-}
-function stopWaitFrom(options) {
-  const value = options["stopWaitMs"];
-  if (value === void 0) return DEFAULT_STOP_WAIT_MS;
-  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-    throw new NatsAgentError(`${EXTENSION_NAME}: options.stopWaitMs must be a number of ms \u2265 0`);
-  }
-  return value;
-}
-async function fabricExtension(ctx, env = process.env) {
-  return createFabricExtension(ctx, env, await resolveScratchPad(ctx, env));
-}
-function createFabricExtension(ctx, env = process.env, scratchPad) {
-  const edgeSubject = resolveEdgeSubject(ctx.options, env);
-  const stopWaitMs = stopWaitFrom(ctx.options);
-  const tracing = fabricTracing({ edgeSubject });
-  const guard = loopGuard();
-  const log = ctx.logger;
-  let publisher;
-  let currentSession;
-  const served = /* @__PURE__ */ new Map();
-  const awaitingStop = [];
-  const release = (waiting) => {
-    const at = awaitingStop.indexOf(waiting);
-    if (at >= 0) awaitingStop.splice(at, 1);
-    clearTimeout(waiting.timer);
-  };
-  let warnedIdentityOff = false;
-  let spEnv;
-  if (scratchPad !== void 0) {
-    if (ctx.settings.stateDir !== void 0) {
-      spEnv = new SpEnvFile(spEnvFilePath(ctx.settings.stateDir, env));
-    } else {
-      log.warn(
-        `${EXTENSION_NAME}: the plugin names no state directory, so the skill's scripts/sp gets no ScratchPad settings`
-      );
-    }
-  }
-  const writeSpEnv = () => {
-    if (spEnv === void 0) return;
-    try {
-      spEnv.write();
-    } catch (err) {
-      log.warn(`${EXTENSION_NAME}: ScratchPad's settings for scripts/sp: ${String(err)}`);
-    }
-  };
-  if (scratchPad !== void 0 && spEnv !== void 0) {
-    exportScratchPad(scratchPad, spEnv.vars);
-    writeSpEnv();
-  }
-  const promptEnv = spEnv !== void 0 ? new ServedPromptEnv(spEnv.vars) : void 0;
-  const handOn = scratchPad !== void 0 ? new ScratchPadHandOn() : void 0;
-  return {
-    name: EXTENSION_NAME,
-    // The service: tracing first, so the guard runs inside the scope tracing
-    // bound and a malformed pair is refused with 400 before the guard
-    // looks; the plugin appends its own (the tools' scope) after these.
-    // The ScratchPad extension's, last, remembers the references each
-    // served prompt brings, which Claude Code may hand on.
-    requestInterceptors: [
-      tracing.requestInterceptor,
-      guard.requestInterceptor,
-      ...handOn !== void 0 ? [handOn.requestInterceptor] : []
-    ],
-    // The client Claude Code's agent tools prompt through: the edge and the
-    // pair, then the waiting mark. Both read the ambient scope, so the
-    // order between them does not matter.
-    promptInterceptors: [tracing.promptInterceptor, guard.promptInterceptor],
-    heartbeatExtras: tracing.heartbeatExtras,
-    ...handOn !== void 0 ? {
-      // References in Claude Code's `prompt_agent`: granted to a
-      // receiver that reads them, removed with a note for any other.
-      toolExtensions: [handOn],
-      // So a caller's `prompt_agent` hands references to Claude Code.
-      metadata: { [READS_REFERENCES_KEY]: "true" }
-    } : {},
-    started({ agents, service }) {
-      if (ctx.settings.senderIdentity !== "signed" && !warnedIdentityOff) {
-        warnedIdentityOff = true;
-        log.warn(IDENTITY_OFF_WARNING);
-      }
-      if (edgeSubject !== null) {
-        publisher = servedPublisher({ agents, subject: edgeSubject, logger: log });
-      }
-      log.info(
-        `${EXTENSION_NAME}: tracing ${service.subject.prompt}` + (edgeSubject === null ? " (propagate-only: lineage forwarded, no edge or served record published)" : `, edge and served records on ${edgeSubject}`)
-      );
-      if (scratchPad !== void 0 && handOn !== void 0) {
-        if (spEnv !== void 0) {
-          spEnv.vars[SP_VARS.creator] = service.subject.prompt;
-          writeSpEnv();
-        }
-        const port = spPort(scratchPad, service.subject.prompt, env);
-        if (port !== void 0) handOn.start({ scratchPad: port, agents, service, logger: log });
-        else
-          log.warn(
-            `${EXTENSION_NAME}: no sp for this platform (set SCRATCHPAD_BIN); references in prompt_agent are not handed on, and grant requests not answered`
-          );
-        log.info(
-          `${EXTENSION_NAME}: ScratchPad volume ${scratchPad.volume}` + (scratchPad.dir !== void 0 ? `, workspace ${scratchPad.dir}` : ", no workspace") + (spEnv !== void 0 ? `, for the skill's scripts/sp through ${spEnv.path}` : "")
-        );
-      }
-    },
-    async stopping() {
-      for (const waiting of [...awaitingStop]) {
-        release(waiting);
-        waiting.turn.settle("ok", waiting.repliedAtMs);
-      }
-      for (const [id, entry] of served) {
-        served.delete(id);
-        entry.turn?.settle("error", void 0, "shutdown");
-      }
-      spEnv?.remove();
-      await publisher?.flush();
-    },
-    events: {
-      sessionStarted(sessionId) {
-        if (isClaudeSessionId(sessionId)) currentSession = sessionId;
-      },
-      promptAccepted(request) {
-        const scope = activeTrace();
-        if (promptEnv !== void 0) {
-          promptEnv.enter(request, scope);
-          writeSpEnv();
-        }
-        if (scope === void 0) return;
-        const named = request.sessionId ?? currentSession;
-        const sessionId = isClaudeSessionId(named) ? named : void 0;
-        let turn;
-        if (sessionId === void 0) {
-          log.warn(NO_SESSION_LINE);
-        } else {
-          turn = publisher?.beginTurn(scope, SERVED_HARNESS);
-          turn?.bind(sessionId);
-        }
-        served.set(request.id, { request, scope, sessionId, turn });
-      },
-      promptEnded(request, outcome, atMs, reason) {
-        const entry = served.get(request.id);
-        served.delete(request.id);
-        if (promptEnv !== void 0) {
-          promptEnv.leave(request);
-          const open = [...served.values()].at(-1);
-          if (open !== void 0) promptEnv.enter(open.request, open.scope);
-          writeSpEnv();
-        }
-        if (entry === void 0) return;
-        const { turn, sessionId } = entry;
-        if (turn === void 0 || sessionId === void 0) return;
-        if (outcome !== "ok" || reason === "final_text") {
-          turn.settle(outcome, atMs, reason);
-          return;
-        }
-        const waiting = {
-          sessionId,
-          turn,
-          repliedAtMs: atMs,
-          timer: setTimeout(() => {
-            release(waiting);
-            turn.settle("ok", atMs);
-          }, stopWaitMs)
-        };
-        waiting.timer.unref?.();
-        awaitingStop.push(waiting);
-      },
-      turnStopped(sessionId, atMs) {
-        for (const waiting of [...awaitingStop]) {
-          if (sessionId !== void 0 && waiting.sessionId !== sessionId) continue;
-          if (waiting.repliedAtMs >= atMs) continue;
-          release(waiting);
-          waiting.turn.settle("ok", atMs);
-        }
-      },
-      aroundToolCall(request, _toolName, run) {
-        const scope = request === void 0 ? void 0 : served.get(request.id)?.scope;
-        return scope === void 0 ? run() : bindActiveTrace(scope, () => guard.aroundToolCall(scope, run));
-      }
-    }
-  };
-}
-
-export { DEFAULT_STOP_WAIT_MS, EXTENSION_NAME, IDENTITY_OFF_WARNING, NO_SESSION_LINE, SERVED_HARNESS, SP_ENV_FILE_VAR, SpEnvFile, createFabricExtension, fabricExtension as default, fabricExtension, isClaudeSessionId, spBinary, spEnvFilePath };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/scratchpad.ts","../src/extension.ts"],"names":["sharedSpBinary","sharedSpPort","SP_VARS"],"mappings":"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","file":"index.js","sourcesContent":["// ScratchPad for Claude Code's model (`docs/plugins.md` §9): the pieces every\n// add-on shares, from the fabric package (`plugin-scratchpad.ts` there), with\n// this package's copy of the skill (`skills/scratchpad`, installed by\n// `npm run build:sp` from `plugins/scratchpad-skill`), and the one piece\n// Claude Code needs of its own: the file the variables go to.\n//\n// This module runs in the NATS channel plugin's MCP server, a child of\n// Claude Code and a sibling of the Bash tool's processes, so nothing it sets\n// in its own environment reaches `scripts/sp` (§9.4). So it keeps the\n// variables in a file, `<state dir>/agent-fabric/<CLAUDE_PID>.env`, rewritten\n// whole on every change, and this package's own Claude Code hook\n// (`hooks/session-start.sh`, at SessionStart) names that file to the Bash\n// tool as `SP_ENV_FILE`, which `scripts/sp` reads on every call. So the\n// served prompt's trace and caller reach each call, per turn, with nothing\n// from the operator but loading this package as a plugin, which the skill\n// needs anyway.\n\nimport { mkdirSync, renameSync, rmSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport {\n  spBinary as sharedSpBinary,\n  spPort as sharedSpPort,\n  SP_VARS,\n  type ScratchPad,\n  type ScratchPadSettings,\n} from \"@synadia-ai/agent-fabric\";\n\nexport {\n  exportScratchPad,\n  resolveScratchPad,\n  SCRATCHPAD_OPTION,\n  ScratchPadHandOn,\n  ServedPromptEnv,\n  SP_VARS,\n  type ScratchPadSettings,\n} from \"@synadia-ai/agent-fabric\";\n\n/** This package's skill directory: `src/` in the tests, `dist/` when installed, one level below it. */\nexport const SKILL_DIR = fileURLToPath(new URL(\"../skills/scratchpad\", import.meta.url));\n\n/** The variable that names the file to `scripts/sp`, set by the package's hook. */\nexport const SP_ENV_FILE_VAR = \"SP_ENV_FILE\";\n\n/** The sp binary this package ships for this machine, or `SCRATCHPAD_BIN`. */\nexport function spBinary(env: Record<string, string | undefined>): string | undefined {\n  return sharedSpBinary(env, SKILL_DIR);\n}\n\n/** The ScratchPad port over this package's sp, for the extension's grants. */\nexport function spPort(\n  settings: ScratchPadSettings,\n  creator: string,\n  env: Record<string, string | undefined>,\n): ScratchPad | undefined {\n  return sharedSpPort(settings, creator, env, SKILL_DIR);\n}\n\n/**\n * The file for the Claude Code process this server runs under:\n * `<stateDir>/agent-fabric/<pid>.env`, where the hook looks for it. The pid\n * is `CLAUDE_PID`, which Claude Code hands its hooks and its MCP servers\n * alike, else the parent's, as the plugin keys its own files.\n */\nexport function spEnvFilePath(\n  stateDir: string,\n  env: Record<string, string | undefined>,\n  parentPid: number = process.ppid,\n): string {\n  const pid = env[\"CLAUDE_PID\"];\n  return join(\n    stateDir,\n    \"agent-fabric\",\n    `${pid !== undefined && /^\\d+$/.test(pid) ? pid : String(parentPid)}.env`,\n  );\n}\n\n// The names `scripts/sp` takes from the file; nothing else is written.\nconst NAMES: ReadonlySet<string> = new Set(Object.values(SP_VARS));\n\n/**\n * The variables `scripts/sp` reads, kept as a plain object (the one the\n * shared pieces set and clear) and written to the file after each change.\n */\nexport class SpEnvFile {\n  /** What the shared pieces set and clear; `write()` puts it in the file. */\n  readonly vars: Record<string, string | undefined> = {};\n\n  constructor(readonly path: string) {}\n\n  /**\n   * The file, whole, through a rename, so `scripts/sp` reads one state or\n   * the next. A value with a line break could not be read back, so it is\n   * left out. Throws what the file system throws.\n   */\n  write(): void {\n    let text = \"\";\n    for (const [name, value] of Object.entries(this.vars)) {\n      if (!NAMES.has(name) || value === undefined || /[\\r\\n]/.test(value)) continue;\n      text += `${name}=${value}\\n`;\n    }\n    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });\n    const staging = `${this.path}.${process.pid}.tmp`;\n    writeFileSync(staging, text, { mode: 0o600 });\n    renameSync(staging, this.path);\n  }\n\n  /** Removes the file, when the server stops; `scripts/sp` then finds no configuration. */\n  remove(): void {\n    rmSync(this.path, { force: true });\n  }\n}\n","// The fabric add-on for the Claude Code channel plugin: the factory the\n// plugin's MCP server calls once at start, and the extension it returns\n// (`docs/plugins.md` §2.3, §2.4, §3.1, §3.4).\n//\n// What it does, in one screen. The fabric package's `fabricTracing()` gives\n// the three hooks the SDK takes; the plugin puts the request interceptor and\n// the heartbeat extras on its `AgentService` and the prompt interceptor on\n// the `Agents` client its agent tools prompt through. That alone makes the\n// session what an SDK-built agent is on the wire: the envelope's pair\n// adopted or a root minted per served prompt, an `edge` record before every\n// prompt Claude Code's model sends, the record counts on the heartbeat.\n//\n// The harness piece is the join of Claude Code's own model calls. Claude\n// Code sends `X-Claude-Code-Session-ID` on every model request and the\n// proxy files the calls under the session id; the plugin, an MCP server\n// inside the session, cannot touch those headers. So per served prompt the\n// add-on publishes the binding as the signed `served` pair on the edge\n// subject: `start` stamped with the arrival, naming the served thread and\n// the session the prompt was delivered to, and `end` with the outcome.\n//\n// The turn does not end with the reply. After `reply` completes the\n// request with `done`, Claude Code makes at least one more model call to\n// write its closing text. So an `ok` turn stays pending until the plugin's\n// `Stop` hook reports the turn's end (`turnStopped`) at a time after the\n// reply, and `end` carries that time; with no `Stop` within the bound\n// (`stopWaitMs`, 120 s by default) it carries the reply's. A failed or\n// expired request ends at once. So does a request the plugin answered\n// with the turn's final text (reason `final_text`): the model wrote no\n// reply, and the plugin sends that text at the turn's `Stop`, which has\n// already come. The plugin's reason for an end the model did not make\n// itself goes on `end` as the record's `reason`; the add-on's own end of\n// an open request at `stopping` carries `shutdown`.\n//\n// The served request's scope is kept by the plugin's request id from\n// `promptAccepted` to `promptEnded` and bound around every agent-tool\n// call. The plugin already re-enters the handler's async context (a\n// snapshot taken after the interceptors ran) before `aroundToolCall`, so\n// the binding is a no-op rebind the add-on makes anyway. The `409` loop\n// guard is the fabric package's two interceptors, after tracing's, and its\n// `aroundToolCall` inside the add-on's, which lifts the mark once the\n// request's calls have settled.\n//\n// ScratchPad (§9.13): when a volume is configured, the add-on keeps the\n// variables the package's skill (`skills/scratchpad`, loaded with the\n// package as a Claude Code plugin) reads through `scripts/sp` in a file the\n// package's SessionStart hook names to the Bash tool: the connection, the\n// workspace and the volume at start, the served prompt's trace and caller\n// from its arrival to its end (`scratchpad.ts`). It registers Claude Code as\n// reading references, hands the references Claude Code's model puts into\n// `prompt_agent` to the fabric package's ScratchPad extension, and answers\n// grant requests for what Claude Code published, by an SDK-built agent's\n// rule.\n\nimport {\n  activeTrace,\n  bindActiveTrace,\n  fabricTracing,\n  loopGuard,\n  resolveEdgeSubject,\n  servedPublisher,\n  type AgentExtension,\n  type AgentExtensionContext,\n  type EndReason,\n  type Outcome,\n  type ServedPublisher,\n  type ServedRequest,\n  type ServedTurn,\n  type TraceScope,\n  READS_REFERENCES_KEY,\n} from \"@synadia-ai/agent-fabric\";\nimport { NatsAgentError } from \"@synadia-ai/agents\";\nimport {\n  exportScratchPad,\n  resolveScratchPad,\n  ScratchPadHandOn,\n  ServedPromptEnv,\n  SP_VARS,\n  SpEnvFile,\n  spEnvFilePath,\n  spPort,\n  type ScratchPadSettings,\n} from \"./scratchpad.js\";\n\n/** The extension's name, as the plugin's status output lists it. */\nexport const EXTENSION_NAME = \"agent-fabric\";\n\n/** The name the proxy files Claude Code's calls under, and the served records carry. */\nexport const SERVED_HARNESS = \"claude\";\n\n/** How long an answered turn waits for the `Stop` hook before `end` carries the reply's time. */\nexport const DEFAULT_STOP_WAIT_MS = 120_000;\n\n/** The warning logged once at start when the plugin's identity is off. */\nexport const IDENTITY_OFF_WARNING =\n  `${EXTENSION_NAME}: senderIdentity is off; trace records are signed, so none will be ` +\n  \"published and each counts as dropped on the heartbeat. Set senderIdentity to signed.\";\n\n/** The line logged for a prompt that arrives while no session is known. */\nexport const NO_SESSION_LINE =\n  `${EXTENSION_NAME}: no Claude Code session id known for this prompt, so no served pair; ` +\n  \"its model calls stand as a harness thread of their own. Are the plugin's hooks registered?\";\n\n// Claude Code's session ids are UUIDs; the rule is the one the pre-split\n// plugin checked before it published a pair (`isClaudeSessionId`,\n// `agents/claude-code/src/session-id.ts` at `fbd16ab`): header-safe, so\n// nothing a header value could never hold reaches the record.\nconst SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;\n\n/** `true` iff `value` is shaped like a session id Claude Code would send. */\nexport function isClaudeSessionId(value: unknown): value is string {\n  return typeof value === \"string\" && SESSION_ID_RE.test(value);\n}\n\n/** One served prompt, from `promptAccepted` to `promptEnded`. */\ninterface Served {\n  readonly request: ServedRequest;\n  /** The scope tracing bound around the prompt's handler. */\n  readonly scope: TraceScope;\n  /** The session the pair names; absent when none was known. */\n  readonly sessionId: string | undefined;\n  /** The pair; absent when the add-on publishes no records or knew no session. */\n  readonly turn: ServedTurn | undefined;\n}\n\n/** An answered prompt whose turn waits for the `Stop` hook. */\ninterface AwaitingStop {\n  readonly sessionId: string;\n  readonly turn: ServedTurn;\n  /** When `reply` completed the request: `promptEnded`'s time. */\n  readonly repliedAtMs: number;\n  readonly timer: ReturnType<typeof setTimeout>;\n}\n\nfunction stopWaitFrom(options: Readonly<Record<string, unknown>>): number {\n  const value = options[\"stopWaitMs\"];\n  if (value === undefined) return DEFAULT_STOP_WAIT_MS;\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < 0) {\n    throw new NatsAgentError(`${EXTENSION_NAME}: options.stopWaitMs must be a number of ms ≥ 0`);\n  }\n  return value;\n}\n\n/**\n * The factory: the module's default export. Called once by the plugin's\n * MCP server, before it connects, with what it knows then. Resolves\n * ScratchPad's settings (which may read the plugin's NATS context) and\n * builds the extension with them. Throws `NatsAgentError` for an edge\n * subject that can never be published to, or a `stopWaitMs` option that\n * is not a duration.\n *\n * `env` is where the variables are read from; a test passes its own.\n */\nexport async function fabricExtension(\n  ctx: AgentExtensionContext,\n  env: NodeJS.ProcessEnv = process.env,\n): Promise<AgentExtension> {\n  return createFabricExtension(ctx, env, await resolveScratchPad(ctx, env));\n}\n\n/**\n * The extension, built synchronously from settings already resolved:\n * without `scratchPad`, tracing, the `served` pair and the guard alone.\n */\nexport function createFabricExtension(\n  ctx: AgentExtensionContext,\n  env: NodeJS.ProcessEnv = process.env,\n  scratchPad?: ScratchPadSettings,\n): AgentExtension {\n  const edgeSubject = resolveEdgeSubject(ctx.options, env);\n  const stopWaitMs = stopWaitFrom(ctx.options);\n  const tracing = fabricTracing({ edgeSubject });\n  const guard = loopGuard();\n  const log = ctx.logger;\n\n  // Made at `started`, from the plugin's client, which signs as the\n  // plugin's identity. A prompt accepted before then gets no pair. With\n  // the edge subject `null` (propagate-only) there is never one.\n  let publisher: ServedPublisher | undefined;\n  // The session Claude Code is in now, as the `SessionStart` hook last\n  // reported it; the fallback when the plugin names none on a request.\n  let currentSession: string | undefined;\n  const served = new Map<string, Served>();\n  // Answered turns in the order they were answered.\n  const awaitingStop: AwaitingStop[] = [];\n\n  const release = (waiting: AwaitingStop): void => {\n    const at = awaitingStop.indexOf(waiting);\n    if (at >= 0) awaitingStop.splice(at, 1);\n    clearTimeout(waiting.timer);\n  };\n\n  let warnedIdentityOff = false;\n\n  // ScratchPad's variables, in the file the package's hook names to the\n  // Bash tool. Without the plugin's state directory there is no file to\n  // name, and the skill's scripts/sp finds no configuration.\n  let spEnv: SpEnvFile | undefined;\n  if (scratchPad !== undefined) {\n    if (ctx.settings.stateDir !== undefined) {\n      spEnv = new SpEnvFile(spEnvFilePath(ctx.settings.stateDir, env));\n    } else {\n      log.warn(\n        `${EXTENSION_NAME}: the plugin names no state directory, so the skill's ` +\n          \"scripts/sp gets no ScratchPad settings\",\n      );\n    }\n  }\n  const writeSpEnv = (): void => {\n    if (spEnv === undefined) return;\n    try {\n      spEnv.write();\n    } catch (err) {\n      log.warn(`${EXTENSION_NAME}: ScratchPad's settings for scripts/sp: ${String(err)}`);\n    }\n  };\n  if (scratchPad !== undefined && spEnv !== undefined) {\n    exportScratchPad(scratchPad, spEnv.vars);\n    writeSpEnv();\n  }\n  const promptEnv = spEnv !== undefined ? new ServedPromptEnv(spEnv.vars) : undefined;\n  const handOn = scratchPad !== undefined ? new ScratchPadHandOn() : undefined;\n\n  return {\n    name: EXTENSION_NAME,\n    // The service: tracing first, so the guard runs inside the scope tracing\n    // bound and a malformed pair is refused with 400 before the guard\n    // looks; the plugin appends its own (the tools' scope) after these.\n    // The ScratchPad extension's, last, remembers the references each\n    // served prompt brings, which Claude Code may hand on.\n    requestInterceptors: [\n      tracing.requestInterceptor,\n      guard.requestInterceptor,\n      ...(handOn !== undefined ? [handOn.requestInterceptor] : []),\n    ],\n    // The client Claude Code's agent tools prompt through: the edge and the\n    // pair, then the waiting mark. Both read the ambient scope, so the\n    // order between them does not matter.\n    promptInterceptors: [tracing.promptInterceptor, guard.promptInterceptor],\n    heartbeatExtras: tracing.heartbeatExtras,\n    ...(handOn !== undefined\n      ? {\n          // References in Claude Code's `prompt_agent`: granted to a\n          // receiver that reads them, removed with a note for any other.\n          toolExtensions: [handOn],\n          // So a caller's `prompt_agent` hands references to Claude Code.\n          metadata: { [READS_REFERENCES_KEY]: \"true\" },\n        }\n      : {}),\n\n    started({ agents, service }) {\n      if (ctx.settings.senderIdentity !== \"signed\" && !warnedIdentityOff) {\n        warnedIdentityOff = true;\n        log.warn(IDENTITY_OFF_WARNING);\n      }\n      if (edgeSubject !== null) {\n        publisher = servedPublisher({ agents, subject: edgeSubject, logger: log });\n      }\n      log.info(\n        `${EXTENSION_NAME}: tracing ${service.subject.prompt}` +\n          (edgeSubject === null\n            ? \" (propagate-only: lineage forwarded, no edge or served record published)\"\n            : `, edge and served records on ${edgeSubject}`),\n      );\n      if (scratchPad !== undefined && handOn !== undefined) {\n        if (spEnv !== undefined) {\n          spEnv.vars[SP_VARS.creator] = service.subject.prompt;\n          writeSpEnv();\n        }\n        const port = spPort(scratchPad, service.subject.prompt, env);\n        if (port !== undefined) handOn.start({ scratchPad: port, agents, service, logger: log });\n        else\n          log.warn(\n            `${EXTENSION_NAME}: no sp for this platform (set SCRATCHPAD_BIN); ` +\n              \"references in prompt_agent are not handed on, and grant requests not answered\",\n          );\n        log.info(\n          `${EXTENSION_NAME}: ScratchPad volume ${scratchPad.volume}` +\n            (scratchPad.dir !== undefined ? `, workspace ${scratchPad.dir}` : \", no workspace\") +\n            (spEnv !== undefined ? `, for the skill's scripts/sp through ${spEnv.path}` : \"\"),\n        );\n      }\n    },\n\n    async stopping() {\n      // The plugin calls this before it fails the requests still open, and\n      // no `Stop` will come any more: every turn ends here, an answered one\n      // at its reply, an open one now.\n      for (const waiting of [...awaitingStop]) {\n        release(waiting);\n        waiting.turn.settle(\"ok\", waiting.repliedAtMs);\n      }\n      for (const [id, entry] of served) {\n        served.delete(id);\n        entry.turn?.settle(\"error\", undefined, \"shutdown\");\n      }\n      // No served prompt any more, and no server to serve one.\n      spEnv?.remove();\n      await publisher?.flush();\n    },\n\n    events: {\n      sessionStarted(sessionId) {\n        if (isClaudeSessionId(sessionId)) currentSession = sessionId;\n      },\n\n      promptAccepted(request) {\n        // In the handler's async context, inside the scope tracing bound.\n        const scope = activeTrace();\n        // From here to its end this prompt is the one Claude Code works on,\n        // and the one `scripts/sp` works for.\n        if (promptEnv !== undefined) {\n          promptEnv.enter(request, scope);\n          writeSpEnv();\n        }\n        if (scope === undefined) return;\n        const named = request.sessionId ?? currentSession;\n        const sessionId = isClaudeSessionId(named) ? named : undefined;\n        let turn: ServedTurn | undefined;\n        if (sessionId === undefined) {\n          log.warn(NO_SESSION_LINE);\n        } else {\n          // `beginTurn` stamps the arrival now; `bind` publishes `start`.\n          // The session is bound at arrival, so a `/clear` during the turn\n          // does not move the binding.\n          turn = publisher?.beginTurn(scope, SERVED_HARNESS);\n          turn?.bind(sessionId);\n        }\n        served.set(request.id, { request, scope, sessionId, turn });\n      },\n\n      promptEnded(request, outcome: Outcome, atMs, reason?: EndReason) {\n        const entry = served.get(request.id);\n        served.delete(request.id);\n        if (promptEnv !== undefined) {\n          // Claude Code may hold a second prompt in the same turn: the\n          // variables go back to the latest one still open.\n          promptEnv.leave(request);\n          const open = [...served.values()].at(-1);\n          if (open !== undefined) promptEnv.enter(open.request, open.scope);\n          writeSpEnv();\n        }\n        if (entry === undefined) return;\n        const { turn, sessionId } = entry;\n        if (turn === undefined || sessionId === undefined) return;\n        // A failure ends at once, and so does an answer the plugin sent from\n        // the turn's final text: it comes at the turn's `Stop`, so the turn\n        // is already over.\n        if (outcome !== \"ok\" || reason === \"final_text\") {\n          turn.settle(outcome, atMs, reason);\n          return;\n        }\n        // Answered, but Claude Code is still writing its closing text.\n        const waiting: AwaitingStop = {\n          sessionId,\n          turn,\n          repliedAtMs: atMs,\n          timer: setTimeout(() => {\n            release(waiting);\n            turn.settle(\"ok\", atMs);\n          }, stopWaitMs),\n        };\n        waiting.timer.unref?.();\n        awaitingStop.push(waiting);\n      },\n\n      turnStopped(sessionId, atMs) {\n        // One `Stop` ends one turn of Claude Code's, and every prompt\n        // answered in it before the stop: the oldest first, so two\n        // prompts answered in one turn share its end, and a prompt\n        // answered after this stop waits for the next.\n        for (const waiting of [...awaitingStop]) {\n          if (sessionId !== undefined && waiting.sessionId !== sessionId) continue;\n          if (waiting.repliedAtMs >= atMs) continue;\n          release(waiting);\n          waiting.turn.settle(\"ok\", atMs);\n        }\n      },\n\n      aroundToolCall(request: ServedRequest | undefined, _toolName, run) {\n        const scope = request === undefined ? undefined : served.get(request.id)?.scope;\n        return scope === undefined\n          ? run()\n          : bindActiveTrace(scope, () => guard.aroundToolCall(scope, run));\n      },\n    },\n  };\n}\n"]}