@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/chunk-O6USDERH.js

@@ -0,0 +1,165 @@
+import { resolveChildEnv } from './chunk-HKCKOAIO.js';
+import { TheokitAgentError, ConfigurationError } from './chunk-ALUN2B4W.js';
+import { execFile } from 'child_process';
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+
+// src/sandbox/shell-escape.ts
+function shellEscapePosix(arg) {
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+// src/sandbox/types.ts
+var SandboxSecurityError = class extends TheokitAgentError {
+  name = "SandboxSecurityError";
+  code = "sandbox_security";
+  constructor(message) {
+    super(message, { code: "sandbox_security", isRetryable: false });
+  }
+};
+var SandboxNotAvailableError = class extends TheokitAgentError {
+  name = "SandboxNotAvailableError";
+  code = "sandbox_not_available";
+  constructor(message) {
+    super(message, { code: "sandbox_not_available", isRetryable: false });
+  }
+};
+var SandboxBackend = class {
+  config;
+  constructor(config = {}) {
+    this.config = {
+      workDir: config.workDir ?? "/tmp",
+      timeoutMs: config.timeoutMs ?? 3e4,
+      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,
+      // #54 — preserve the env policy so backends can scrub secrets.
+      env: config.env ?? "inherit-scrubbed"
+    };
+  }
+  async readFile(path) {
+    const result = await this.execute(`cat ${this.shellEscape(path)}`);
+    if (result.exitCode !== 0) {
+      throw new Error(`readFile failed: ${result.stderr}`);
+    }
+    return result.stdout;
+  }
+  async writeFile(path, content) {
+    await this.uploadFile(path, content);
+  }
+  async glob(pattern, cwd) {
+    const dir = cwd ?? this.config.workDir ?? ".";
+    const result = await this.execute(
+      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`
+    );
+    this.assertCommandRan("glob", result);
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  async grep(pattern, path) {
+    const target = path ?? ".";
+    const result = await this.execute(
+      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`
+    );
+    if (result.exitCode !== 1) this.assertCommandRan("grep", result);
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  async listDir(path) {
+    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);
+    this.assertCommandRan("listDir", result);
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  /**
+   * Turns "the command did not run" into an error instead of an empty array.
+   *
+   * `glob`, `grep` and `listDir` used to `return []` on any non-zero exit, so a search that could not
+   * run reported the same thing as a search that found nothing — opposite facts, one normal and one
+   * meaning the agent is looking at a filesystem it cannot read. That is the failure mode a backend
+   * whose `execute` is not a POSIX shell hits, which this class's own docblock warns about in prose
+   * and could not enforce.
+   *
+   * A genuine no-match is still `[]`: `find` exits 0 with empty output, and `grep`'s exit 1 is
+   * checked by its caller before this is reached.
+   */
+  assertCommandRan(operation, result) {
+    if (result.exitCode === 0) return;
+    throw new ConfigurationError(
+      `${operation} failed (exit ${String(result.exitCode)}): ${result.stderr.trim() || "no stderr"}. The derived helpers shell out to POSIX \`cat\`/\`find\`/\`grep\`/\`ls\` \u2014 a backend whose execute() is not a POSIX shell must override them.`,
+      { code: "sandbox_derived_helper_failed" }
+    );
+  }
+  truncateOutput(output) {
+    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;
+    if (Buffer.byteLength(output) > max) {
+      return `${output.slice(0, max)}
+...(truncated)`;
+    }
+    return output;
+  }
+  shellEscape(arg) {
+    return shellEscapePosix(arg);
+  }
+};
+async function resolveSandbox(provider, ctx) {
+  return provider instanceof SandboxBackend ? provider : provider(ctx);
+}
+var LocalSandbox = class extends SandboxBackend {
+  constructor(config = {}) {
+    super(config);
+  }
+  async execute(command, opts) {
+    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 3e4;
+    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;
+    return new Promise((resolve) => {
+      const child = execFile(
+        "/bin/sh",
+        ["-c", command],
+        {
+          cwd: this.config.workDir,
+          timeout,
+          maxBuffer: max,
+          encoding: "utf-8",
+          // #54 — scrub secret-like host env vars from the child by default.
+          env: resolveChildEnv({ policy: this.config.env })
+        },
+        (error, stdout, stderr) => {
+          resolve(this.buildResult(error, stdout ?? "", stderr ?? ""));
+        }
+      );
+      child.on("error", () => {
+        resolve({ stdout: "", stderr: "spawn error", exitCode: 1, timedOut: false });
+      });
+    });
+  }
+  buildResult(error, stdout, stderr) {
+    const timedOut = error !== null && "killed" in error && error.killed;
+    const overflowed = error !== null && error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+    return {
+      stdout: this.markIfCut(this.truncateOutput(stdout), overflowed),
+      stderr: this.markIfCut(this.truncateOutput(stderr), overflowed),
+      exitCode: timedOut ? 124 : error ? 1 : 0,
+      timedOut
+    };
+  }
+  /**
+   * Append the `...(truncated)` marker `ExecuteResult` tells callers to branch on, when the child
+   * was killed for exceeding `maxOutputBytes` and this stream is the one sitting at the cap.
+   *
+   * `truncateOutput` has already run, so an output it marked is left alone rather than marked
+   * twice. Node does not say WHICH stream overflowed, so the stream at the cap is the one that
+   * lost data — the other, being shorter, is complete.
+   */
+  markIfCut(output, overflowed) {
+    if (!overflowed) return output;
+    if (output.endsWith("...(truncated)")) return output;
+    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;
+    return Buffer.byteLength(output) >= max ? `${output}
+...(truncated)` : output;
+  }
+  async uploadFile(path, content) {
+    const fullPath = path.startsWith("/") ? path : `${this.config.workDir}/${path}`;
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, content, "utf-8");
+  }
+};
+
+export { LocalSandbox, SandboxBackend, SandboxNotAvailableError, SandboxSecurityError, resolveSandbox, shellEscapePosix };
+//# sourceMappingURL=chunk-O6USDERH.js.map
+//# sourceMappingURL=chunk-O6USDERH.js.map

package/dist/chunk-O6USDERH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sandbox/shell-escape.ts","../src/sandbox/types.ts","../src/sandbox/local-sandbox.ts"],"names":["fsWriteFile"],"mappings":"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","file":"chunk-O6USDERH.js","sourcesContent":["/**\n * POSIX shell escaping for values interpolated into a `SandboxBackend.execute`\n * command string. `execute` runs via `/bin/sh -c`, so any untrusted value\n * (repo URL, ref, path) MUST be quoted to prevent command injection.\n *\n * @internal\n */\n\n/** Wrap `arg` in single quotes, escaping embedded single quotes (`'\\''`). */\nexport function shellEscapePosix(arg: string): string {\n  return `'${arg.replace(/'/g, \"'\\\\''\")}'`;\n}\n","/**\n * Sandbox backend protocol — pluggable execution environment for agent tools.\n *\n * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All\n * higher-level operations are derived on the base class. New backends\n * (Docker, Firecracker, E2B) only implement those 2 methods.\n *\n * @public\n */\n\nimport { ConfigurationError, TheokitAgentError } from \"../errors.js\";\nimport type { EnvPolicy } from \"../types/env-policy.js\";\nimport { shellEscapePosix } from \"./shell-escape.js\";\n\n/**\n * What a {@link SandboxBackend} returns for one command.\n *\n * `exitCode` is a coarse signal rather than the child's real exit status: the backends in this\n * package report `0` on success, `124` on timeout, and `1` for everything else — including a command\n * that exited with its own non-zero code. Read `timedOut` to tell a killed command from a failed one,\n * and `stderr` for the reason; branching on a specific exit code will not work here.\n *\n * `stdout` and `stderr` are truncated independently at `SandboxConfig.maxOutputBytes`, with a\n * trailing `...(truncated)` marker. Neither is safe to parse as a complete document without checking\n * for it.\n */\nexport interface ExecuteResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  timedOut: boolean;\n}\n\n/**\n * Construction-time settings shared by every {@link SandboxBackend}. All fields are optional and the\n * base constructor fills them in, so `{}` is a valid config: `workDir` `/tmp`, `timeoutMs` 30000,\n * `maxOutputBytes` 5 MiB, `env` `\"inherit-scrubbed\"`.\n *\n * `workDir` is the child process's cwd and the base a relative `uploadFile` path resolves against. It\n * is not a boundary — under `LocalSandbox` nothing stops a command, or an absolute path, from leaving\n * it. Only `LinuxSandbox` makes it enforceable.\n *\n * `timeoutMs` is the default for every call; `execute(command, { timeoutMs })` overrides it per\n * command. On expiry the child is killed and the result carries `timedOut: true` with `exitCode`\n * 124 — the partial output collected so far is still returned.\n */\nexport interface SandboxConfig {\n  workDir?: string;\n  timeoutMs?: number;\n  maxOutputBytes?: number;\n  /**\n   * #54 — env inherit/scrub policy for the executed command's child process.\n   * Defaults to `\"inherit-scrubbed\"` (drop secret-like vars: `*KEY*`, `*SECRET*`,\n   * `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Pass `\"all\"` to restore full inheritance\n   * or `\"core\"` for a minimal safe allowlist.\n   */\n  env?: EnvPolicy;\n}\n\n/**\n * A backend refused a command on policy grounds — the environment works, and it said no. Carries a\n * stable `code: \"sandbox_security\"` for callers that prefer not to match on the class.\n *\n * Nothing in this package throws it, which is worth knowing before you write a `catch` for it:\n * `LocalSandbox` and `LinuxSandbox` report a refusal through {@link ExecuteResult} (non-zero\n * `exitCode`, reason on `stderr`), and a write blocked under confinement surfaces as a plain `Error`\n * from `uploadFile`. This type exists so a custom backend that must reject a command BEFORE spawning\n * anything — a container or VM runner enforcing its own policy — can do so in the protocol's\n * vocabulary instead of inventing an error of its own.\n */\nexport class SandboxSecurityError extends TheokitAgentError {\n  override readonly name = \"SandboxSecurityError\";\n  override readonly code = \"sandbox_security\" as const;\n  constructor(message: string) {\n    // not retryable: a refused command is refused every time; retrying re-asks the same question\n    super(message, { code: \"sandbox_security\", isRetryable: false });\n  }\n}\n\n/**\n * A backend cannot be used at all: its runtime is missing or unusable. The distinction from\n * {@link SandboxSecurityError} is which side failed — there the sandbox worked and denied the\n * command, here there is no sandbox. Carries `code: \"sandbox_not_available\"`.\n *\n * Nothing in this package throws it either, and that is a position rather than an oversight:\n * `createSandboxBackend` treats a missing bubblewrap as a degradation, warns once, and hands back an\n * unconfined `LocalSandbox`. Throw this instead from a backend that must never silently run outside\n * its isolation.\n */\nexport class SandboxNotAvailableError extends TheokitAgentError {\n  override readonly name = \"SandboxNotAvailableError\";\n  override readonly code = \"sandbox_not_available\" as const;\n  constructor(message: string) {\n    // not retryable: a missing runtime does not appear on a second attempt\n    super(message, { code: \"sandbox_not_available\", isRetryable: false });\n  }\n}\n\n/**\n * The execution capability handed to an agent tool, and the extension point for new environments.\n *\n * A backend implements exactly two methods, `execute` and `uploadFile`. Everything else here —\n * `readFile`, `glob`, `grep`, `listDir` — is derived from `execute` by shelling out `cat`, `find`,\n * `grep` and `ls`, so a subclass that overrides `execute` alone inherits confined reads, searches and\n * listings for free. It does not inherit confined writes: `writeFile` delegates to `uploadFile`, and\n * that is the second override `LinuxSandbox` needs.\n *\n * Choosing one: `LocalSandbox` runs the command on the host with no isolation and suits code you\n * already trust; `LinuxSandbox` adds kernel confinement where bubblewrap is available;\n * `createSandboxBackend` probes and picks between them, and is the right entry point unless you have\n * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this\n * package does not ship — write it against these two methods.\n *\n * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a\n * backend whose `execute` is not a POSIX shell must override them as well.\n */\nexport abstract class SandboxBackend {\n  protected config: SandboxConfig;\n\n  constructor(config: SandboxConfig = {}) {\n    this.config = {\n      workDir: config.workDir ?? \"/tmp\",\n      timeoutMs: config.timeoutMs ?? 30_000,\n      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,\n      // #54 — preserve the env policy so backends can scrub secrets.\n      env: config.env ?? \"inherit-scrubbed\",\n    };\n  }\n\n  abstract execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult>;\n\n  abstract uploadFile(path: string, content: string | Buffer): Promise<void>;\n\n  async readFile(path: string): Promise<string> {\n    const result = await this.execute(`cat ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) {\n      throw new Error(`readFile failed: ${result.stderr}`);\n    }\n    return result.stdout;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.uploadFile(path, content);\n  }\n\n  async glob(pattern: string, cwd?: string): Promise<string[]> {\n    const dir = cwd ?? this.config.workDir ?? \".\";\n    const result = await this.execute(\n      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`,\n    );\n    this.assertCommandRan(\"glob\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async grep(pattern: string, path?: string): Promise<string[]> {\n    const target = path ?? \".\";\n    const result = await this.execute(\n      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`,\n    );\n    // `grep` exits 1 for NO MATCH and >= 2 for an error, so a 1 is an answer and is not asserted on.\n    if (result.exitCode !== 1) this.assertCommandRan(\"grep\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async listDir(path: string): Promise<string[]> {\n    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);\n    this.assertCommandRan(\"listDir\", result);\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  /**\n   * Turns \"the command did not run\" into an error instead of an empty array.\n   *\n   * `glob`, `grep` and `listDir` used to `return []` on any non-zero exit, so a search that could not\n   * run reported the same thing as a search that found nothing — opposite facts, one normal and one\n   * meaning the agent is looking at a filesystem it cannot read. That is the failure mode a backend\n   * whose `execute` is not a POSIX shell hits, which this class's own docblock warns about in prose\n   * and could not enforce.\n   *\n   * A genuine no-match is still `[]`: `find` exits 0 with empty output, and `grep`'s exit 1 is\n   * checked by its caller before this is reached.\n   */\n  private assertCommandRan(operation: string, result: ExecuteResult): void {\n    if (result.exitCode === 0) return;\n    throw new ConfigurationError(\n      `${operation} failed (exit ${String(result.exitCode)}): ${result.stderr.trim() || \"no stderr\"}. ` +\n        `The derived helpers shell out to POSIX \\`cat\\`/\\`find\\`/\\`grep\\`/\\`ls\\` — a backend whose ` +\n        `execute() is not a POSIX shell must override them.`,\n      { code: \"sandbox_derived_helper_failed\" },\n    );\n  }\n\n  protected truncateOutput(output: string): string {\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    if (Buffer.byteLength(output) > max) {\n      return `${output.slice(0, max)}\\n...(truncated)`;\n    }\n    return output;\n  }\n\n  private shellEscape(arg: string): string {\n    return shellEscapePosix(arg);\n  }\n}\n\n/**\n * A backend OR a per-request resolver of one — mirrors `FilesystemProvider` / `InteractiveProvider`.\n * A resolver runs at tool-execution time (request scope), so a multi-tenant / multi-role agent gets a\n * distinct sandbox per request without a shared mutable one. This is how a tool takes execution as an\n * INJECTED capability: the same tool runs on a local sandbox, a container/E2B backend (cluster/web), or\n * any future backend, with no direct `child_process` import.\n *\n * @public\n */\nexport type SandboxProvider<Ctx = unknown> =\n  | SandboxBackend\n  | ((ctx: Ctx) => SandboxBackend | Promise<SandboxBackend>);\n\n/** Resolve a {@link SandboxProvider} to a concrete backend for `ctx`. */\nexport async function resolveSandbox<Ctx>(\n  provider: SandboxProvider<Ctx>,\n  ctx: Ctx,\n): Promise<SandboxBackend> {\n  return provider instanceof SandboxBackend ? provider : provider(ctx);\n}\n","/**\n * LocalSandbox — subprocess-based execution. **This is NOT an isolation\n * boundary.** It runs the command via `/bin/sh -c` in the SAME OS as the host\n * with the host's filesystem and network fully reachable — it provides NO\n * process, filesystem, or network isolation. Its only safety affordances are:\n *   - a wall-clock timeout (kills a runaway command),\n *   - an output-size cap (bounds memory), and\n *   - env scrubbing (#54): secret-like parent env vars (`*KEY*`/`*SECRET*`/\n *     `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`) are dropped from the child by default\n *     (`SandboxConfig.env`), so a shell tool cannot exfiltrate host secrets via\n *     the environment.\n *\n * For real isolation (untrusted code), use a container/VM backend — NOT this.\n *\n * @public\n */\n\nimport { execFile } from \"node:child_process\";\nimport { writeFile as fsWriteFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { resolveChildEnv } from \"../internal/runtime/lifecycle/env-policy.js\";\nimport { type ExecuteResult, SandboxBackend, type SandboxConfig } from \"./types.js\";\n\n/**\n * Runs a command with `/bin/sh -c` on the host. NOT an isolation boundary — the\n * module note above states exactly what it does and does not protect.\n *\n *   const sandbox = new LocalSandbox({ workDir: \"/srv/repo\", timeoutMs: 10_000 });\n *   const { stdout, exitCode, timedOut } = await sandbox.execute(\"ls -1\");\n *\n * Needs a POSIX host with `/bin/sh`. Every helper inherited from\n * {@link SandboxBackend} — `readFile`, `glob`, `grep`, `listDir` — is built on\n * this `execute`, so they inherit that requirement too.\n *\n * How it fails: `execute` NEVER rejects. Every outcome, including a failure to\n * spawn, comes back as an {@link ExecuteResult}; read `timedOut` first\n * (`true` implies `exitCode` 124) and `stderr` for the reason. `uploadFile` DOES\n * reject, with the raw `node:fs` error, on a bad path or missing permission.\n *\n * Traps:\n *  - `exitCode` is not the child's exit code. It is 0, 124 (timed out) or 1 — a\n *    command that exits 3 is reported as 1, so branching on a specific code does\n *    not work here.\n *  - Output beyond `maxOutputBytes` (default 5 MiB) makes Node kill the child.\n *    The result is `exitCode: 1` and `timedOut: false`, with the cut stream\n *    carrying the `...(truncated)` marker described on `ExecuteResult` (#363).\n *    Since `exitCode` is 1 either way, that marker is what tells a lost-output\n *    result from a command that genuinely failed.\n *  - `uploadFile` resolves a relative path against `workDir` but does not contain\n *    it: an absolute path, or one containing `..`, writes wherever the process\n *    can. `workDir` is a starting directory, not a jail.\n *  - Secret-like parent env vars are dropped by default. Passing\n *    `env: \"all\"` in {@link SandboxConfig} puts the host's API keys back within\n *    reach of any command the agent runs.\n */\nexport class LocalSandbox extends SandboxBackend {\n  constructor(config: SandboxConfig = {}) {\n    super(config);\n  }\n\n  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {\n    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 30_000;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n\n    return new Promise<ExecuteResult>((resolve) => {\n      const child = execFile(\n        \"/bin/sh\",\n        [\"-c\", command],\n        {\n          cwd: this.config.workDir,\n          timeout,\n          maxBuffer: max,\n          encoding: \"utf-8\",\n          // #54 — scrub secret-like host env vars from the child by default.\n          env: resolveChildEnv({ policy: this.config.env }),\n        },\n        (error, stdout, stderr) => {\n          resolve(this.buildResult(error, stdout ?? \"\", stderr ?? \"\"));\n        },\n      );\n\n      // Safety: if child somehow doesn't callback\n      child.on(\"error\", () => {\n        resolve({ stdout: \"\", stderr: \"spawn error\", exitCode: 1, timedOut: false });\n      });\n    });\n  }\n\n  private buildResult(error: Error | null, stdout: string, stderr: string): ExecuteResult {\n    const timedOut = error !== null && \"killed\" in error && (error as { killed: boolean }).killed;\n    // #363 — the ONLY reliable signal that output was lost. Node caps the buffer AT `maxBuffer`, so\n    // for ASCII output the string comes back exactly at the cap and `truncateOutput`'s `> max` test\n    // never fires; a length comparison cannot tell a cut document from a complete one that happens\n    // to be that long. The child being killed for overflow can.\n    const overflowed =\n      error !== null && (error as { code?: unknown }).code === \"ERR_CHILD_PROCESS_STDIO_MAXBUFFER\";\n    return {\n      stdout: this.markIfCut(this.truncateOutput(stdout), overflowed),\n      stderr: this.markIfCut(this.truncateOutput(stderr), overflowed),\n      exitCode: timedOut ? 124 : error ? 1 : 0,\n      timedOut,\n    };\n  }\n\n  /**\n   * Append the `...(truncated)` marker `ExecuteResult` tells callers to branch on, when the child\n   * was killed for exceeding `maxOutputBytes` and this stream is the one sitting at the cap.\n   *\n   * `truncateOutput` has already run, so an output it marked is left alone rather than marked\n   * twice. Node does not say WHICH stream overflowed, so the stream at the cap is the one that\n   * lost data — the other, being shorter, is complete.\n   */\n  private markIfCut(output: string, overflowed: boolean): string {\n    if (!overflowed) return output;\n    if (output.endsWith(\"...(truncated)\")) return output;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    return Buffer.byteLength(output) >= max ? `${output}\\n...(truncated)` : output;\n  }\n\n  async uploadFile(path: string, content: string | Buffer): Promise<void> {\n    const fullPath = path.startsWith(\"/\") ? path : `${this.config.workDir}/${path}`;\n    await mkdir(dirname(fullPath), { recursive: true });\n    await fsWriteFile(fullPath, content, \"utf-8\");\n  }\n}\n"]}

package/dist/chunk-OBA6YK2R.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+// src/internal/runtime/lifecycle/goal-marker.ts
+var GOAL_CONTINUATION_MARKER = "[[theokit:goal-continuation]]";
+
+exports.GOAL_CONTINUATION_MARKER = GOAL_CONTINUATION_MARKER;
+//# sourceMappingURL=chunk-OBA6YK2R.cjs.map
+//# sourceMappingURL=chunk-OBA6YK2R.cjs.map

package/dist/chunk-OBA6YK2R.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/lifecycle/goal-marker.ts"],"names":[],"mappings":";;;AAYO,IAAM,wBAAA,GAA2B","file":"chunk-OBA6YK2R.cjs","sourcesContent":["/**\n * The goal-loop's continuation marker — in a LEAF module, on purpose.\n *\n * It lived in `goal-loop.ts` and was imported by `run-until.ts`, which `goal-loop` in turn\n * imports back. The cycle was broken at runtime (the return edge is `import type` + a dynamic\n * `await import()`), but the cycle detector counts the dynamic edge — and counting a dynamic import as a cycle\n * makes the gate impossible to satisfy without abandoning the canonical cycle-breaking technique.\n *\n * A constant shared by two modules that know each other is the textbook case for extraction into a\n * leaf: neither needs to import the other to know it. The cycle disappears under ANY detector, with no\n * tool policy and without changing a line of behavior.\n */\nexport const GOAL_CONTINUATION_MARKER = \"[[theokit:goal-continuation]]\";\n"]}

package/dist/chunk-OQRGVTQF.js

@@ -0,0 +1,169 @@
+import { pluginBundleRoots, projectConfigRoots } from './chunk-WMWEI3NS.js';
+import { readWorkspaceDir, parseSimpleYaml } from './chunk-JNAA4G4H.js';
+import { ConfigurationError } from './chunk-ALUN2B4W.js';
+import { diag } from './chunk-CZJ6Q7CW.js';
+import { readdir, readFile } from 'fs/promises';
+import { join } from 'path';
+
+async function pluginBundleDirs(cwd, compatSources = []) {
+  const dirs = [];
+  for (const root of pluginBundleRoots(cwd, compatSources)) {
+    let entries;
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) dirs.push(join(root, entry.name));
+    }
+  }
+  return dirs;
+}
+
+// src/internal/runtime/skills/subagents-loader.ts
+async function loadSubagents(cwd, settingSourcesIncludeProject, inline, compatSources = []) {
+  const result = {};
+  if (settingSourcesIncludeProject) {
+    const projectAgents = await readProjectSubagents(cwd, compatSources);
+    for (const [name, definition] of Object.entries(projectAgents)) {
+      result[name] = definition;
+    }
+  }
+  if (inline !== void 0) {
+    for (const [name, definition] of Object.entries(inline)) {
+      result[name] = definition;
+    }
+  }
+  return result;
+}
+async function readProjectSubagents(cwd, compatSources) {
+  const subagents = {};
+  for (const configRoot of projectConfigRoots(cwd, compatSources, "subagents")) {
+    await readSubagentsFrom(join(configRoot, "agents"), subagents);
+  }
+  for (const bundle of await pluginBundleDirs(cwd, compatSources)) {
+    await readSubagentsFrom(join(bundle, "agents"), subagents);
+  }
+  return subagents;
+}
+async function readSubagentsFrom(root, subagents) {
+  const entries = await readWorkspaceDir(root, "subagents_read_error", "subagents directory");
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const path = join(root, entry.name);
+    const raw = await readFile(path, "utf8");
+    if (!hasFrontmatter(raw)) {
+      diag(`[theokit-sdk] ${entry.name} has no frontmatter \u2014 not an agent declaration, skipping`);
+      continue;
+    }
+    const definition = parseSubagentMarkdown(raw, entry.name);
+    if (subagents[definition.name] === void 0) {
+      subagents[definition.name] = { ...definition.definition, source: path };
+    }
+  }
+}
+var ACCEPTED_FIELDS = /* @__PURE__ */ new Set([
+  "name",
+  "description",
+  "model",
+  "tools",
+  "reasoning_effort",
+  "mcp",
+  "sandbox"
+]);
+var INERT_CLAUDE_CODE_FIELDS = /* @__PURE__ */ new Set([
+  /** The CLI's label colour for the agent. Presentation only. */
+  "color"
+]);
+function parseSubagentMarkdown(raw, filename) {
+  const { frontmatter, body } = splitFrontmatter(raw, filename);
+  const fields = parseFrontmatterFields(frontmatter);
+  rejectUnknownFields(fields, filename);
+  rejectMcp(fields, filename);
+  const definition = {
+    description: asString(fields.description) ?? "",
+    prompt: body
+  };
+  const model = resolveModel(fields, filename);
+  if (model !== void 0) definition.model = model;
+  const tools = toStringList(fields.tools);
+  if (tools.length > 0) definition.tools = tools;
+  const sandbox = resolveSandbox(fields, filename);
+  if (sandbox !== void 0) definition.sandbox = sandbox;
+  const name = asString(fields.name) ?? filename.replace(/\.md$/, "");
+  return { name, definition };
+}
+function rejectUnknownFields(fields, filename) {
+  for (const key of Object.keys(fields)) {
+    if (INERT_CLAUDE_CODE_FIELDS.has(key)) continue;
+    if (!ACCEPTED_FIELDS.has(key)) {
+      throw new ConfigurationError(
+        `Subagent ${filename}: unknown frontmatter field "${key}" (accepted: ${[...ACCEPTED_FIELDS].join(", ")})`,
+        { code: "subagent_unknown_field" }
+      );
+    }
+  }
+}
+function rejectMcp(fields, filename) {
+  if (fields.mcp !== void 0) {
+    throw new ConfigurationError(
+      `Subagent ${filename}: per-subagent "mcp" is not yet supported on the local delegation path; declare MCP servers in .theokit/mcp.json (or the parent) instead`,
+      { code: "subagent_mcp_unsupported_local" }
+    );
+  }
+}
+function resolveModel(fields, filename) {
+  const modelId = asString(fields.model);
+  const effort = asString(fields.reasoning_effort);
+  if (effort !== void 0 && (modelId === void 0 || modelId === "inherit")) {
+    throw new ConfigurationError(
+      `Subagent ${filename}: reasoning_effort requires a concrete model (effort is a model parameter; an absent model or "inherit" cannot carry it)`,
+      { code: "subagent_reasoning_effort_without_model" }
+    );
+  }
+  if (modelId === void 0) return void 0;
+  if (modelId === "inherit") return "inherit";
+  return effort !== void 0 ? { id: modelId, params: [{ id: "thinking", value: effort }] } : { id: modelId };
+}
+function resolveSandbox(fields, filename) {
+  if (fields.sandbox === void 0) return void 0;
+  if (typeof fields.sandbox !== "boolean") {
+    throw new ConfigurationError(
+      `Subagent ${filename}: sandbox must be a boolean (got "${String(fields.sandbox)}"); granular sandbox modes are not supported by the runtime`,
+      { code: "subagent_sandbox_not_boolean" }
+    );
+  }
+  return fields.sandbox;
+}
+function asString(v) {
+  if (typeof v !== "string") return void 0;
+  const m = /^(["'])(.*)\1$/.exec(v);
+  return m ? m[2] : v;
+}
+function toStringList(v) {
+  if (Array.isArray(v)) return v.map((t) => t.trim()).filter((t) => t.length > 0);
+  if (typeof v === "string") {
+    return v.split(/[\s,]+/).map((t) => t.trim()).filter((t) => t.length > 0);
+  }
+  return [];
+}
+function hasFrontmatter(raw) {
+  return /^---\s*\n/.test(raw);
+}
+function splitFrontmatter(raw, filename) {
+  const match = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/.exec(raw);
+  if (match === null) {
+    throw new ConfigurationError(`Subagent ${filename} is missing frontmatter`, {
+      code: "subagent_missing_frontmatter"
+    });
+  }
+  return { frontmatter: match[1] ?? "", body: (match[2] ?? "").trim() };
+}
+function parseFrontmatterFields(frontmatter) {
+  return parseSimpleYaml(frontmatter);
+}
+
+export { loadSubagents, pluginBundleDirs };
+//# sourceMappingURL=chunk-OQRGVTQF.js.map
+//# sourceMappingURL=chunk-OQRGVTQF.js.map

package/dist/chunk-OQRGVTQF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/plugin-loader/plugin-bundles.ts","../src/internal/runtime/skills/subagents-loader.ts"],"names":["join"],"mappings":"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","file":"chunk-OQRGVTQF.js","sourcesContent":["/**\n * Locating the plugin bundles a project carries.\n *\n * Shared by the skills and subagents loaders, which both need the same answer to \"which folders in\n * this project are plugins\" and would otherwise each grow their own copy of the directory walk.\n *\n * @internal\n */\n\nimport type { Dirent } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { pluginBundleRoots } from \"../../persistence/paths.js\";\nimport type { CompatSourceDeclaration } from \"../compat/foreign-config-sources.js\";\n\n/**\n * Every plugin folder under the project's plugin roots.\n *\n * Returns the FOLDERS, not their contents — what a bundle contributes (`skills/`, `agents/`) is the\n * caller's business, and a loader that also knew the layout would have to change whenever the other\n * one did.\n *\n * A missing root is not an error: most projects carry no plugins, and treating their absence as a\n * failure would make \"none installed\" indistinguishable from \"the directory could not be read\".\n */\nexport async function pluginBundleDirs(\n  cwd: string,\n  /** Declared foreign dialects (#524). Empty reads `.theokit/plugins` only. */\n  compatSources: readonly CompatSourceDeclaration[] = [],\n): Promise<string[]> {\n  const dirs: string[] = [];\n  for (const root of pluginBundleRoots(cwd, compatSources)) {\n    let entries: Dirent[];\n    try {\n      entries = await readdir(root, { withFileTypes: true });\n    } catch {\n      continue;\n    }\n    for (const entry of entries) {\n      if (entry.isDirectory()) dirs.push(join(root, entry.name));\n    }\n  }\n  return dirs;\n}\n","import { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { ConfigurationError } from \"../../../errors.js\";\nimport type { AgentDefinition } from \"../../../types/agent.js\";\nimport type { ModelSelection } from \"../../../types/agent-prims.js\";\nimport { diag } from \"../../diagnostics.js\";\nimport { projectConfigRoots } from \"../../persistence/paths.js\";\nimport type { CompatSourceDeclaration } from \"../compat/foreign-config-sources.js\";\nimport { readWorkspaceDir } from \"../config/workspace-dir.js\";\nimport { type FrontmatterValue, parseSimpleYaml } from \"../context/yaml-frontmatter.js\";\nimport { pluginBundleDirs } from \"../plugin-loader/plugin-bundles.js\";\n\n/**\n * Load file-based subagents from `.theokit/agents/*.md` and merge with\n * inline definitions. Inline overrides file-based on name conflict.\n *\n * Each markdown file has YAML frontmatter (description + optional model)\n * and a body that becomes the subagent prompt.\n *\n * @internal\n */\nexport async function loadSubagents(\n  cwd: string,\n  settingSourcesIncludeProject: boolean,\n  inline: Record<string, AgentDefinition> | undefined,\n  /** Declared foreign dialects (#524). Empty reads `.theokit/` only. */\n  compatSources: readonly CompatSourceDeclaration[] = [],\n): Promise<Record<string, AgentDefinition>> {\n  const result: Record<string, AgentDefinition> = {};\n  if (settingSourcesIncludeProject) {\n    const projectAgents = await readProjectSubagents(cwd, compatSources);\n    for (const [name, definition] of Object.entries(projectAgents)) {\n      result[name] = definition;\n    }\n  }\n  if (inline !== undefined) {\n    for (const [name, definition] of Object.entries(inline)) {\n      result[name] = definition;\n    }\n  }\n  return result;\n}\n\n/**\n * Read agent declarations from every project config root (`.theokit`, then `.claude`).\n *\n * FIRST occurrence of a name wins, which is what makes `projectConfigRoots`' order a contract rather\n * than a detail: a project declaring the same agent in both means the explicit namespace.\n */\nasync function readProjectSubagents(\n  cwd: string,\n  compatSources: readonly CompatSourceDeclaration[],\n): Promise<Record<string, AgentDefinition>> {\n  const subagents: Record<string, AgentDefinition> = {};\n  for (const configRoot of projectConfigRoots(cwd, compatSources, \"subagents\")) {\n    await readSubagentsFrom(join(configRoot, \"agents\"), subagents);\n  }\n  // A Claude Code plugin is a BUNDLE, and its `agents/` is what it exists to contribute. Read after\n  // the project's own, so a project can shadow an agent a plugin ships without editing the plugin.\n  for (const bundle of await pluginBundleDirs(cwd, compatSources)) {\n    await readSubagentsFrom(join(bundle, \"agents\"), subagents);\n  }\n  return subagents;\n}\n\nasync function readSubagentsFrom(\n  root: string,\n  subagents: Record<string, AgentDefinition>,\n): Promise<void> {\n  const entries = await readWorkspaceDir(root, \"subagents_read_error\", \"subagents directory\");\n  for (const entry of entries) {\n    if (!entry.isFile() || !entry.name.endsWith(\".md\")) continue;\n    const path = join(root, entry.name);\n    const raw = await readFile(path, \"utf8\");\n    // A markdown file with NO frontmatter is not an agent declaration — a directory of agents\n    // written for the Claude Code CLI conventionally carries documentation beside them, and\n    // `.claude/agents/README.md` exists in this repository. Throwing on it made ONE such file stop\n    // every agent in the directory from loading.\n    //\n    // Skipped with a warn rather than in silence, and ONLY for the no-frontmatter case: a file that\n    // HAS frontmatter and gets it wrong is a broken agent and still fails loudly, which is what\n    // keeps a typo'd `sandbox` from returning as a silent gate through this door.\n    if (!hasFrontmatter(raw)) {\n      diag(`[theokit-sdk] ${entry.name} has no frontmatter — not an agent declaration, skipping`);\n      continue;\n    }\n    const definition = parseSubagentMarkdown(raw, entry.name);\n    if (subagents[definition.name] === undefined) {\n      // `path` is computed above to read the file and was then dropped. Keeping it is the whole\n      // visibility fix (#524): without it a listing cannot say which root an agent came from.\n      subagents[definition.name] = { ...definition.definition, source: path };\n    }\n  }\n}\n\n// The frontmatter keys a disk subagent may declare. Any other key is a typed load\n// error rather than a silent drop — a dropped `sandbox` an operator wrote believing\n// it confines the child is exactly the silent-gate failure class this guards against.\nconst ACCEPTED_FIELDS = new Set([\n  \"name\",\n  \"description\",\n  \"model\",\n  \"tools\",\n  \"reasoning_effort\",\n  \"mcp\",\n  \"sandbox\",\n]);\n\n// Fields the Claude Code CLI writes that carry NO behaviour for this runtime. Accepted and ignored,\n// so an agent authored for the CLI loads here unchanged — measured 2026-08-26 across the 59 agent\n// files on one machine, where `color` appeared in 38 of them and made every one of those a\n// `subagent_unknown_field` load error.\n//\n// Named explicitly instead of loosening the check above, because that check's reason is sound: a\n// dropped `sandbox` an operator wrote believing it confines the child is a silent gate. A field that\n// COULD change behaviour must still fail loudly. This set is the difference between \"we know this\n// one and it does nothing\" and \"we have never heard of this\" — two facts a bare allow-everything\n// would collapse into one.\n//\n// Anything added here needs the same justification: inert for THIS runtime, not merely unfamiliar.\nconst INERT_CLAUDE_CODE_FIELDS = new Set([\n  /** The CLI's label colour for the agent. Presentation only. */\n  \"color\",\n]);\n\nfunction parseSubagentMarkdown(\n  raw: string,\n  filename: string,\n): { name: string; definition: AgentDefinition } {\n  const { frontmatter, body } = splitFrontmatter(raw, filename);\n  const fields = parseFrontmatterFields(frontmatter);\n  rejectUnknownFields(fields, filename);\n  rejectMcp(fields, filename);\n\n  const definition: AgentDefinition = {\n    description: asString(fields.description) ?? \"\",\n    prompt: body,\n  };\n  const model = resolveModel(fields, filename);\n  if (model !== undefined) definition.model = model;\n  const tools = toStringList(fields.tools);\n  if (tools.length > 0) definition.tools = tools;\n  const sandbox = resolveSandbox(fields, filename);\n  if (sandbox !== undefined) definition.sandbox = sandbox;\n\n  const name = asString(fields.name) ?? filename.replace(/\\.md$/, \"\");\n  return { name, definition };\n}\n\nfunction rejectUnknownFields(\n  fields: Record<string, FrontmatterValue | undefined>,\n  filename: string,\n): void {\n  for (const key of Object.keys(fields)) {\n    if (INERT_CLAUDE_CODE_FIELDS.has(key)) continue;\n    if (!ACCEPTED_FIELDS.has(key)) {\n      throw new ConfigurationError(\n        `Subagent ${filename}: unknown frontmatter field \"${key}\" (accepted: ${[...ACCEPTED_FIELDS].join(\", \")})`,\n        { code: \"subagent_unknown_field\" },\n      );\n    }\n  }\n}\n\n// mcp: a known field, but not yet honored on the LOCAL delegation path. The frontmatter YAML can only\n// express server NAMES (parseSimpleYaml has no nested-object support), while a child's `Agent.create`\n// needs `mcpServers` as a Record<name, config>; resolving names→config per-subagent in local delegation\n// is its own follow-up. Rather than silently drop it (the M26/M32 silent-gate class), it is a typed load\n// error that names the field and points at the alternative.\nfunction rejectMcp(fields: Record<string, FrontmatterValue | undefined>, filename: string): void {\n  if (fields.mcp !== undefined) {\n    throw new ConfigurationError(\n      `Subagent ${filename}: per-subagent \"mcp\" is not yet supported on the local delegation path; declare MCP servers in .theokit/mcp.json (or the parent) instead`,\n      { code: \"subagent_mcp_unsupported_local\" },\n    );\n  }\n}\n\n// model + reasoning_effort — effort rides inside `model.params[thinking]`, so it requires a concrete\n// model id to attach to (a child inheriting the parent's model cannot carry the parent's provider-\n// specific effort param safely).\nfunction resolveModel(\n  fields: Record<string, FrontmatterValue | undefined>,\n  filename: string,\n): ModelSelection | \"inherit\" | undefined {\n  const modelId = asString(fields.model);\n  const effort = asString(fields.reasoning_effort);\n  // reasoning_effort rides in model.params[thinking], so it needs a CONCRETE model id to attach to.\n  // Neither an absent model NOR `model: inherit` can carry it (the inherited id is unknown at load), so\n  // both are typed errors rather than a silently-dropped effort — the silent-gate class this guards.\n  if (effort !== undefined && (modelId === undefined || modelId === \"inherit\")) {\n    throw new ConfigurationError(\n      `Subagent ${filename}: reasoning_effort requires a concrete model (effort is a model parameter; an absent model or \"inherit\" cannot carry it)`,\n      { code: \"subagent_reasoning_effort_without_model\" },\n    );\n  }\n  if (modelId === undefined) return undefined;\n  if (modelId === \"inherit\") return \"inherit\";\n  return effort !== undefined\n    ? { id: modelId, params: [{ id: \"thinking\", value: effort }] }\n    : { id: modelId };\n}\n\n// sandbox: boolean only. A granular mode string (read-only/…) is unsupported by the SDK runtime and is\n// a typed error rather than a silent coercion to a boolean.\nfunction resolveSandbox(\n  fields: Record<string, FrontmatterValue | undefined>,\n  filename: string,\n): boolean | undefined {\n  if (fields.sandbox === undefined) return undefined;\n  if (typeof fields.sandbox !== \"boolean\") {\n    throw new ConfigurationError(\n      `Subagent ${filename}: sandbox must be a boolean (got \"${String(fields.sandbox)}\"); granular sandbox modes are not supported by the runtime`,\n      { code: \"subagent_sandbox_not_boolean\" },\n    );\n  }\n  return fields.sandbox;\n}\n\nfunction asString(v: FrontmatterValue | undefined): string | undefined {\n  if (typeof v !== \"string\") return undefined;\n  // parseSimpleYaml does not strip quotes (documented), and `model`/`reasoning_effort` are fields users\n  // habitually quote (`model: \"openai/gpt-4o\"`). Strip a single matching surrounding quote pair so a\n  // quoted id/effort does not slip past validation and fail only at the provider.\n  const m = /^([\"'])(.*)\\1$/.exec(v);\n  return m ? m[2] : v;\n}\n\n/** Accept a YAML list (`string[]`) or a comma/space-separated scalar; trim + drop empties. */\nfunction toStringList(v: FrontmatterValue | undefined): string[] {\n  if (Array.isArray(v)) return v.map((t) => t.trim()).filter((t) => t.length > 0);\n  if (typeof v === \"string\") {\n    return v\n      .split(/[\\s,]+/)\n      .map((t) => t.trim())\n      .filter((t) => t.length > 0);\n  }\n  return [];\n}\n\n/** Does this file open with a frontmatter block at all? Its ABSENCE means \"not an agent\". */\nfunction hasFrontmatter(raw: string): boolean {\n  return /^---\\s*\\n/.test(raw);\n}\n\nfunction splitFrontmatter(raw: string, filename: string): { frontmatter: string; body: string } {\n  const match = /^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n([\\s\\S]*)$/.exec(raw);\n  if (match === null) {\n    throw new ConfigurationError(`Subagent ${filename} is missing frontmatter`, {\n      code: \"subagent_missing_frontmatter\",\n    });\n  }\n  return { frontmatter: match[1] ?? \"\", body: (match[2] ?? \"\").trim() };\n}\n\nfunction parseFrontmatterFields(frontmatter: string): Record<string, FrontmatterValue | undefined> {\n  // Preserve the rich YAML value types (boolean/number/string[]): `sandbox: true` and\n  // `mcp: [a, b]` are meaningful here, so narrowing everything to string (as the\n  // pre-M33 loader did) would drop them. Per-field validation happens in parseSubagentMarkdown.\n  return parseSimpleYaml(frontmatter);\n}\n"]}

package/dist/chunk-OR6XIWLB.js

@@ -0,0 +1,19 @@
+import { atomicWriteJson } from './chunk-3JHIFQ4I.js';
+import { diag } from './chunk-CZJ6Q7CW.js';
+import { join } from 'path';
+
+async function persistActiveMemoryTranscript(root, transcript) {
+  try {
+    const dir = join(root, "transcripts", "active-memory");
+    const file = join(dir, `${transcript.runId}.json`);
+    await atomicWriteJson(file, transcript);
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    diag(`[theokit-sdk] active-memory transcript persist failed: ${message}
+`);
+  }
+}
+
+export { persistActiveMemoryTranscript };
+//# sourceMappingURL=chunk-OR6XIWLB.js.map
+//# sourceMappingURL=chunk-OR6XIWLB.js.map

package/dist/chunk-OR6XIWLB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/memory/storage/transcript-store.ts"],"names":[],"mappings":";;;;AA2CA,eAAsB,6BAAA,CACpB,MACA,UAAA,EACe;AACf,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,IAAA,EAAM,aAAA,EAAe,eAAe,CAAA;AACrD,IAAA,MAAM,OAAO,IAAA,CAAK,GAAA,EAAK,CAAA,EAAG,UAAA,CAAW,KAAK,CAAA,KAAA,CAAO,CAAA;AAGjD,IAAA,MAAM,eAAA,CAAgB,MAAM,UAAU,CAAA;AAAA,EACxC,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,UAAU,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,OAAO,KAAK,CAAA;AACrE,IAAA,IAAA,CAAK,0DAA0D,OAAO;AAAA,CAAI,CAAA;AAAA,EAC5E;AACF","file":"chunk-OR6XIWLB.js","sourcesContent":["import { join } from \"node:path\";\nimport { diag } from \"../../diagnostics.js\";\nimport { atomicWriteJson } from \"../../persistence/atomic-write.js\";\nimport type { MemoryRoot } from \"./memory-root.js\";\n\n/**\n * Optional on-disk persistence for Active Memory recall transcripts (ADR D6).\n *\n * Writes one JSON file per run under\n * `.theokit/memory/transcripts/active-memory/<runId>.json` when the agent\n * passes `persistTranscripts: true`. Failures are swallowed with a stderr\n * warning so transcript IO never crashes the agent run.\n *\n * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`\n * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT\n * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes\n * this symbol from the published declarations and forces the satellite back onto a copy. Measured:\n * the first draft of this very note did exactly that. See #430 and #463.\n */\n\nexport interface ActiveMemoryTranscript {\n  runId: string;\n  startedAtMs: number;\n  userText: string;\n  queryMode: string;\n  status: string;\n  durationMs: number;\n  summary: string | undefined;\n  hits: ReadonlyArray<{\n    path: string;\n    startLine: number;\n    endLine: number;\n    score: number;\n    snippet: string;\n  }>;\n}\n\n/**\n * Write one active-memory recall transcript under `<memory root>/transcripts/active-memory`.\n *\n * Never throws. Transcript IO is observability, and observability must not break the run it merely\n * observes — a failure is reported through the diagnostics sink and swallowed.\n */\nexport async function persistActiveMemoryTranscript(\n  root: MemoryRoot,\n  transcript: ActiveMemoryTranscript,\n): Promise<void> {\n  try {\n    const dir = join(root, \"transcripts\", \"active-memory\");\n    const file = join(dir, `${transcript.runId}.json`);\n    // atomicWriteJson auto-creates the parent directory + writes atomically\n    // (no torn writes during crash).\n    await atomicWriteJson(file, transcript);\n  } catch (cause) {\n    const message = cause instanceof Error ? cause.message : String(cause);\n    diag(`[theokit-sdk] active-memory transcript persist failed: ${message}\\n`);\n  }\n}\n"]}