@archmax-ai/harness 0.0.0

package/dist/sandbox/executor.js

@@ -0,0 +1,119 @@
+import { transformForEval } from "@langchain/quickjs";
+import { normalizeRelPath } from "../core/workspace.js";
+import { readPrelude } from "./prelude.js";
+import { prepareHookSource } from "./imports.js";
+import { DEFAULT_SANDBOX_VERSION } from "../runtime/contract.js";
+import { createQuickJsSandboxRuntime } from "./runtime.js";
+/**
+ * Sandboxed execution for the two sandbox tools (`archmax_eval`, `archmax_run`)
+ * and for lifecycle hooks.
+ *
+ * Script *sources* are read through the {@link Workspace} backend (not the
+ * local filesystem), so scripts work against whatever Deep Agents backend the
+ * runtime is configured with. Inline code and an authored file evaluate in the
+ * same REPL session for a scope and under the same PTC contract — the only
+ * difference is where the source came from.
+ */
+const DEFAULT_TIMEOUT_MS = 5_000;
+export const AGENT_SESSION = "agent";
+export const PROCESS_SESSION = "process";
+function errorOutcome(message) {
+    return { ok: false, value: undefined, logs: [], error: { message }, formatted: `error: ${message}` };
+}
+/** Lifecycle hooks get the hook contract; everything else the PTC contract. */
+function sandboxContext(params) {
+    return params.lifecycle ? "lifecycle-hook" : "ptc";
+}
+const argsAssignment = (args) => `globalThis.args = ${JSON.stringify(args ?? {})};`;
+/**
+ * The code a lifecycle hook runs as. The hook body is evaluated as its own
+ * async IIFE (`transformForEval`) so its completion value can be read — a
+ * bare-body hook may end in `veto("…")` — and a registered `export default`
+ * function is then called with the hook input: the arguments plus `tools`.
+ * Whatever came back is reduced to a verdict by the prelude.
+ */
+function buildHookCode(prepared, filePath, prelude, args) {
+    return [
+        prelude,
+        "globalThis.__hookDef = undefined;",
+        argsAssignment(args),
+        `globalThis.__scriptPath = ${JSON.stringify(normalizeRelPath(filePath))};`,
+        `globalThis.__hookBody = await ${transformForEval(prepared)};`,
+        "globalThis.__hookVerdict(",
+        "  typeof globalThis.__hookDef === \"function\"",
+        "    ? await globalThis.__hookDef(Object.assign({}, globalThis.args, {",
+        "        tools: typeof tools === \"undefined\" ? undefined : tools,",
+        "      }))",
+        "    : globalThis.__hookBody,",
+        ");",
+    ].join("\n");
+}
+export function createScriptExecutor(opts) {
+    const { workspace } = opts;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const sandboxVersion = opts.sandboxVersion ?? DEFAULT_SANDBOX_VERSION;
+    const runtime = opts.sandboxRuntime ?? createQuickJsSandboxRuntime();
+    const sessionKey = (sessionId, ns) => `${sessionId}:${ns}`;
+    async function evalCode(code, params) {
+        const session = runtime.session(sessionKey(params.sessionId, params.sessionNamespace), {
+            tools: params.tools ?? [],
+            quotas: {
+                memoryLimitBytes: opts.memoryLimitBytes,
+                maxPtcCalls: opts.maxPtcCalls,
+                maxResultChars: opts.maxResultChars,
+            },
+            captureConsole: true,
+            sessionId: params.sessionId,
+        });
+        return session.eval(code, timeoutMs);
+    }
+    async function runHook(source, filePath, params) {
+        // Typed `@archmax-ai/harness/*` imports are stripped (the prelude provides the
+        // globals) and `export default` becomes the hook registration; any other
+        // import — or a source that does not parse — fails closed here, host-side.
+        let code;
+        try {
+            const prelude = readPrelude("lifecycle-hook", sandboxVersion);
+            code = buildHookCode(prepareHookSource(source, { file: filePath }), filePath, prelude, params.args);
+        }
+        catch (err) {
+            return errorOutcome(err.message);
+        }
+        return evalCode(code, params);
+    }
+    return {
+        async runFile(filePath, params) {
+            const source = await workspace.readText(filePath);
+            if (source == null)
+                return errorOutcome(`cannot read script '${filePath}' from the agent workspace.`);
+            if (params.lifecycle)
+                return runHook(source, filePath, params);
+            const prelude = readPrelude(sandboxContext(params), sandboxVersion);
+            const code = [
+                prelude,
+                argsAssignment(params.args),
+                `globalThis.__scriptPath = ${JSON.stringify(normalizeRelPath(filePath))};`,
+                source,
+            ].join("\n");
+            return evalCode(code, params);
+        },
+        runCode(code, params) {
+            if (!params.prelude)
+                return evalCode(code, params);
+            // Same contract as an authored file: the PTC prelude runs first so inline
+            // code sees the same `SANDBOX_CONTRACT` marker and the same absence of
+            // the hook-only vocabulary.
+            return evalCode(`${readPrelude(sandboxContext(params), sandboxVersion)}\n${code}`, params);
+        },
+        dispose(sessionId, sessionNamespace) {
+            if (sessionNamespace) {
+                runtime.dispose(sessionKey(sessionId, sessionNamespace));
+                return;
+            }
+            for (const ns of [AGENT_SESSION, PROCESS_SESSION]) {
+                runtime.dispose(sessionKey(sessionId, ns));
+            }
+        },
+    };
+}
+//# sourceMappingURL=executor.js.map

package/dist/sandbox/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/sandbox/executor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAuB,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAAE,2BAA2B,EAAuB,MAAM,cAAc,CAAC;AAEhF;;;;;;;;;GASG;AAEH,MAAM,kBAAkB,GAAG,KAAK,CAAC;AACjC,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AA4CzC,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;AACvG,CAAC;AAED,+EAA+E;AAC/E,SAAS,cAAc,CAAC,MAAuB;IAC7C,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC;AACrD,CAAC;AAED,MAAM,cAAc,GAAG,CAAC,IAAyC,EAAE,EAAE,CACnE,qBAAqB,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,CAAC;AAErD;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,QAAgB,EAAE,QAAgB,EAAE,OAAe,EAAE,IAA8B;IACxG,OAAO;QACL,OAAO;QACP,mCAAmC;QACnC,cAAc,CAAC,IAAI,CAAC;QACpB,6BAA6B,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,GAAG;QAC1E,iCAAiC,gBAAgB,CAAC,QAAQ,CAAC,GAAG;QAC9D,2BAA2B;QAC3B,gDAAgD;QAChD,uEAAuE;QACvE,oEAAoE;QACpE,WAAW;QACX,8BAA8B;QAC9B,IAAI;KACL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAA2B;IAC9D,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACvD,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,uBAAuB,CAAC;IACtE,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,IAAI,2BAA2B,EAAE,CAAC;IACrE,MAAM,UAAU,GAAG,CAAC,SAAiB,EAAE,EAAU,EAAE,EAAE,CAAC,GAAG,SAAS,IAAI,EAAE,EAAE,CAAC;IAE3E,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,MAAuB;QAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,gBAAgB,CAAC,EAAE;YACrF,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE;YACzB,MAAM,EAAE;gBACN,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;gBACvC,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,cAAc,EAAE,IAAI,CAAC,cAAc;aACpC;YACD,cAAc,EAAE,IAAI;YACpB,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,UAAU,OAAO,CAAC,MAAc,EAAE,QAAgB,EAAE,MAAuB;QAC9E,+EAA+E;QAC/E,yEAAyE;QACzE,2EAA2E;QAC3E,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,WAAW,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAAC;YAC9D,IAAI,GAAG,aAAa,CAAC,iBAAiB,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACtG,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,YAAY,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM;YAC5B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAClD,IAAI,MAAM,IAAI,IAAI;gBAAE,OAAO,YAAY,CAAC,uBAAuB,QAAQ,6BAA6B,CAAC,CAAC;YACtG,IAAI,MAAM,CAAC,SAAS;gBAAE,OAAO,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;YAE/D,MAAM,OAAO,GAAG,WAAW,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,CAAC;YACpE,MAAM,IAAI,GAAG;gBACX,OAAO;gBACP,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC;gBAC3B,6BAA6B,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,GAAG;gBAC1E,MAAM;aACP,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACb,OAAO,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,CAAC,IAAI,EAAE,MAAM;YAClB,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACnD,0EAA0E;YAC1E,uEAAuE;YACvE,4BAA4B;YAC5B,OAAO,QAAQ,CAAC,GAAG,WAAW,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,KAAK,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QAC7F,CAAC;QAED,OAAO,CAAC,SAAS,EAAE,gBAAgB;YACjC,IAAI,gBAAgB,EAAE,CAAC;gBACrB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;gBACzD,OAAO;YACT,CAAC;YACD,KAAK,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,eAAe,CAAC,EAAE,CAAC;gBAClD,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/sandbox/imports.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Source preparation for lifecycle hook scripts.
+ *
+ * `@langchain/quickjs`'s `transformForEval` (which `ReplSession.eval` applies to
+ * everything it runs) silently **drops** `import` and `export` statements and
+ * rejects nothing — so a hook's `export default async function hook(...)`
+ * would vanish and a foreign import would pass unnoticed. This module does the
+ * three things the transform will not:
+ *
+ * - **reject** any import that is not a `@archmax-ai/harness/*` type carrier (sandbox
+ *   scripts are self-contained — inline the logic or use `tools.*`);
+ * - **strip** the `@archmax-ai/harness/*` imports, preserving line count so sandbox
+ *   stack traces keep pointing at the right source lines;
+ * - **rewrite** `export default <expr>` to `globalThis.__hookDef = <expr>`, so
+ *   the hook function survives evaluation as a script and the executor can call
+ *   it with the hook input.
+ */
+/** Thrown (host-side) when a sandbox script imports a non-`@archmax-ai/harness/*` specifier. */
+export declare class ForbiddenSandboxImportError extends Error {
+    readonly specifier: string;
+    readonly file?: string | undefined;
+    constructor(specifier: string, file?: string | undefined);
+}
+/** All import specifiers in a source that are NOT `@archmax-ai/harness/*` (for validation). */
+export declare function findForeignImports(source: string): string[];
+/**
+ * Prepare a hook source for evaluation: strip `@archmax-ai/harness/*` imports, rewrite
+ * `export default` to the `__hookDef` registration, and throw
+ * {@link ForbiddenSandboxImportError} on any other import specifier.
+ */
+export declare function prepareHookSource(source: string, opts?: {
+    file?: string;
+}): string;

package/dist/sandbox/imports.js

@@ -0,0 +1,67 @@
+/**
+ * Source preparation for lifecycle hook scripts.
+ *
+ * `@langchain/quickjs`'s `transformForEval` (which `ReplSession.eval` applies to
+ * everything it runs) silently **drops** `import` and `export` statements and
+ * rejects nothing — so a hook's `export default async function hook(...)`
+ * would vanish and a foreign import would pass unnoticed. This module does the
+ * three things the transform will not:
+ *
+ * - **reject** any import that is not a `@archmax-ai/harness/*` type carrier (sandbox
+ *   scripts are self-contained — inline the logic or use `tools.*`);
+ * - **strip** the `@archmax-ai/harness/*` imports, preserving line count so sandbox
+ *   stack traces keep pointing at the right source lines;
+ * - **rewrite** `export default <expr>` to `globalThis.__hookDef = <expr>`, so
+ *   the hook function survives evaluation as a script and the executor can call
+ *   it with the hook input.
+ */
+/** Import specifiers the sandbox accepts (and strips) in script sources. */
+const ALLOWED_SPECIFIER_PREFIX = "@archmax-ai/harness";
+/**
+ * Static import statements, single- or multi-line:
+ * `import { a, b } from "spec";`, `import x from 'spec'`, `import "spec";`.
+ */
+const IMPORT_RE = /(^|\n)[ \t]*import\s+(?:[^"'()]*?from\s+)?["']([^"']+)["'][ \t]*;?/g;
+/** `export default` at statement position. */
+const EXPORT_DEFAULT_RE = /(^|\n)([ \t]*)export[ \t]+default[ \t]+/g;
+/** Thrown (host-side) when a sandbox script imports a non-`@archmax-ai/harness/*` specifier. */
+export class ForbiddenSandboxImportError extends Error {
+    specifier;
+    file;
+    constructor(specifier, file) {
+        super(`sandbox scripts may import only from '@archmax-ai/harness/*' type-carrier entry points; ` +
+            `found 'import ... from "${specifier}"'${file ? ` in ${file}` : ""}. ` +
+            `Sandbox scripts are self-contained — inline the logic or use the tools bridge.`);
+        this.specifier = specifier;
+        this.file = file;
+        this.name = "ForbiddenSandboxImportError";
+    }
+}
+function specifierAllowed(specifier) {
+    return (specifier === ALLOWED_SPECIFIER_PREFIX ||
+        specifier.startsWith(`${ALLOWED_SPECIFIER_PREFIX}/`));
+}
+/** All import specifiers in a source that are NOT `@archmax-ai/harness/*` (for validation). */
+export function findForeignImports(source) {
+    const foreign = [];
+    for (const match of String(source).matchAll(IMPORT_RE)) {
+        const specifier = match[2];
+        if (!specifierAllowed(specifier))
+            foreign.push(specifier);
+    }
+    return foreign;
+}
+/**
+ * Prepare a hook source for evaluation: strip `@archmax-ai/harness/*` imports, rewrite
+ * `export default` to the `__hookDef` registration, and throw
+ * {@link ForbiddenSandboxImportError} on any other import specifier.
+ */
+export function prepareHookSource(source, opts = {}) {
+    const stripped = String(source).replace(IMPORT_RE, (whole, _lead, specifier) => {
+        if (!specifierAllowed(specifier))
+            throw new ForbiddenSandboxImportError(specifier, opts.file);
+        return "\n".repeat(whole.split("\n").length - 1);
+    });
+    return stripped.replace(EXPORT_DEFAULT_RE, "$1$2globalThis.__hookDef = ");
+}
+//# sourceMappingURL=imports.js.map

package/dist/sandbox/imports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.js","sourceRoot":"","sources":["../../src/sandbox/imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,4EAA4E;AAC5E,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAEvD;;;GAGG;AACH,MAAM,SAAS,GAAG,qEAAqE,CAAC;AAExF,8CAA8C;AAC9C,MAAM,iBAAiB,GAAG,0CAA0C,CAAC;AAErE,gGAAgG;AAChG,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAEzC;IACA;IAFX,YACW,SAAiB,EACjB,IAAa;QAEtB,KAAK,CACH,0FAA0F;YACxF,2BAA2B,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI;YACtE,gFAAgF,CACnF,CAAC;QAPO,cAAS,GAAT,SAAS,CAAQ;QACjB,SAAI,GAAJ,IAAI,CAAS;QAOtB,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED,SAAS,gBAAgB,CAAC,SAAiB;IACzC,OAAO,CACL,SAAS,KAAK,wBAAwB;QACtC,SAAS,CAAC,UAAU,CAAC,GAAG,wBAAwB,GAAG,CAAC,CACrD,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACvD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAGD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,OAA0B,EAAE;IAC5E,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAa,EAAE,SAAiB,EAAE,EAAE;QAC7F,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC;YAAE,MAAM,IAAI,2BAA2B,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9F,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,6BAA6B,CAAC,CAAC;AAC5E,CAAC"}

package/dist/sandbox/prelude.d.ts

@@ -0,0 +1,12 @@
+import { type SandboxContext } from "../runtime/contract.js";
+/**
+ * Assemble the QuickJS prelude for a sandbox context. The lifecycle-hook context
+ * is the verdict helpers (`ok`/`veto`/`correct`), `defineHook`, and the verdict
+ * reducer; the PTC context is the contract marker alone. Cached per
+ * `(context, version)`.
+ *
+ * There are exactly two preludes: no compatibility prelude exists for a
+ * superseded vocabulary, so a hook source using one throws in the sandbox and
+ * the phase vetoes fail-closed.
+ */
+export declare function readPrelude(context?: SandboxContext, version?: number): string;

package/dist/sandbox/prelude.js

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_SANDBOX_VERSION } from "../runtime/contract.js";
+const partsCache = new Map();
+const assembledCache = new Map();
+function partsDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), "assets", "parts");
+}
+function readPart(name) {
+    const cached = partsCache.get(name);
+    if (cached !== undefined)
+        return cached;
+    const content = readFileSync(join(partsDir(), `${name}.js`), "utf8");
+    partsCache.set(name, content);
+    return content;
+}
+/**
+ * The PTC context's whole prelude: the versioned contract marker and nothing
+ * else. The model's own code (`archmax_eval`, `archmax_run`) gets no hook
+ * vocabulary — `tools` and `args` are injected separately by the executor and
+ * the QuickJS session.
+ */
+const PTC_PRELUDE = `globalThis.SANDBOX_CONTRACT = { context: "ptc", version: globalThis.__SANDBOX_VERSION };`;
+/**
+ * Assemble the QuickJS prelude for a sandbox context. The lifecycle-hook context
+ * is the verdict helpers (`ok`/`veto`/`correct`), `defineHook`, and the verdict
+ * reducer; the PTC context is the contract marker alone. Cached per
+ * `(context, version)`.
+ *
+ * There are exactly two preludes: no compatibility prelude exists for a
+ * superseded vocabulary, so a hook source using one throws in the sandbox and
+ * the phase vetoes fail-closed.
+ */
+export function readPrelude(context = "lifecycle-hook", version = DEFAULT_SANDBOX_VERSION) {
+    const key = `${context}@${version}`;
+    const cached = assembledCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const header = `globalThis.__SANDBOX_VERSION = ${JSON.stringify(version)};`;
+    const parts = context === "ptc"
+        ? [PTC_PRELUDE]
+        : [
+            readPart("core"),
+            readPart("lifecycle-hook"),
+        ];
+    const assembled = [header, ...parts].join("\n");
+    assembledCache.set(key, assembled);
+    return assembled;
+}
+//# sourceMappingURL=prelude.js.map

package/dist/sandbox/prelude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prelude.js","sourceRoot":"","sources":["../../src/sandbox/prelude.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,uBAAuB,EAAuB,MAAM,wBAAwB,CAAC;AAEtF,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;AAC7C,MAAM,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEjD,SAAS,QAAQ;IACf,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IACrE,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,WAAW,GACf,0FAA0F,CAAC;AAE7F;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,UAA0B,gBAAgB,EAC1C,UAAkB,uBAAuB;IAEzC,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,OAAO,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,MAAM,GAAG,kCAAkC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC;IAC5E,MAAM,KAAK,GACT,OAAO,KAAK,KAAK;QACf,CAAC,CAAC,CAAC,WAAW,CAAC;QACf,CAAC,CAAC;YACE,QAAQ,CAAC,MAAM,CAAC;YAChB,QAAQ,CAAC,gBAAgB,CAAC;SAC3B,CAAC;IACR,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACnC,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/sandbox/ptc-gateway.d.ts

@@ -0,0 +1,104 @@
+import type { RunnableConfig } from "@langchain/core/runnables";
+import type { StructuredTool } from "@langchain/core/tools";
+import type { WorkflowEventEmitter } from "../core/events.js";
+import { type GovernanceRule, type ToolCallOrigin } from "../kernel/kernel.js";
+import type { WorkflowMachine } from "../machine/machine.js";
+import type { VariableStore } from "../machine/variables.js";
+import { type MountPrefixes } from "../core/mounts.js";
+import { type SkillPrefixes } from "../core/skills.js";
+/**
+ * Governance and telemetry for programmatic tool calls (PTC) — the `tools.*`
+ * namespace sandbox scripts call.
+ *
+ * The sandbox bridge calls `invoke(input)` on a tool directly, bypassing the
+ * agent's tool node and `wrapToolCall`, so the gateway hands it *wrapped* tools:
+ * each runs the kernel `decide()` pipeline, emits the same tool events, honours
+ * declarative mocks and forwards the run's `RunnableConfig` before delegating to
+ * the real tool. One wrap covers both PTC consumers — `archmax_eval`/`archmax_run`
+ * code and lifecycle hooks.
+ *
+ * A script's call (`script` origin) is governed exactly as the model's own: the
+ * run's variables — refreshed per model call — resolve the state's `${{name}}`
+ * argument guards, so a guard admits from a script exactly what it admits from
+ * the model. Unlike `wrapToolCall`, no `${{…}}` substitution is applied to a
+ * script's arguments: a script passes computed values and reads the variables
+ * as `args.variables`, so such text is ordinary data and passes through
+ * verbatim — substituting would refuse or rewrite legitimate data.
+ */
+/**
+ * The live call context for one session's wrapped tools. A QuickJS session
+ * freezes its injected tool set at first eval but outlives many calls across
+ * several workflow states, so the wrapped tools close over this object and read
+ * it per call. Invariant: one context per session, mutated in place by
+ * {@link PtcToolGateway.refresh} at the start of every turn and never replaced,
+ * or the frozen tools would keep reading a stale one. The abort signal and tool
+ * mocks travel inside `config`, so there is exactly one thing to keep current.
+ */
+export interface PtcCallContext {
+    /** The workflow state a call made right now is governed against. */
+    state: string;
+    /** Runtime config forwarded to the underlying tool (session id, signal, store). */
+    config: RunnableConfig;
+    /**
+     * Whether the turn in force is reply-only (the run parked, nothing to produce
+     * but text). Enforced here as well as at the model's surface: a script from
+     * an earlier turn keeps its tools, and "a parked run may speak, never act"
+     * must hold on every path to a tool.
+     */
+    replyOnly?: boolean;
+    /**
+     * The run's variables at the turn's model call, as checkpointed: what the
+     * state's `${{name}}` guards resolve against. Absent means none are set — a
+     * guard that references one is then unevaluable and refuses the call.
+     */
+    variables?: VariableStore;
+}
+export interface PtcWrapOptions {
+    /** Which authority these tools run on; decides how the kernel governs them. */
+    origin: Extract<ToolCallOrigin, "script" | "lifecycle">;
+    /** The session whose live context these tools read on every call. */
+    sessionId: string;
+}
+export interface PtcToolGateway {
+    /**
+     * Wrap a resolved PTC tool surface. The returned tools are drop-in
+     * replacements — same `name`, `description`, and schema — so the sandbox
+     * bridge's own naming (it camel-cases `name`, and special-cases `read_file`)
+     * behaves exactly as it did with the raw tools.
+     */
+    wrap(tools: StructuredTool[], opts: PtcWrapOptions): StructuredTool[];
+    /**
+     * Point a session's live context at the current turn. Called once per model
+     * call, before any script can run, so tools wrapped in an earlier turn read
+     * the state committed for this one.
+     */
+    refresh(sessionId: string, next: PtcCallContext): void;
+    /** Drop a session's context (its wrapped tools go with the session). */
+    release(sessionId: string): void;
+}
+/**
+ * A PTC call the kernel refused. Thrown so the sandbox bridge rejects the
+ * script's promise: fail-closed (the underlying tool never runs) but catchable,
+ * so a script can handle the refusal instead of dying on it.
+ */
+export declare class PtcGovernanceError extends Error {
+    readonly tool: string;
+    readonly ruleId: string;
+    constructor(tool: string, ruleId: string, reason: string);
+}
+export interface PtcToolGatewayOptions {
+    machine: WorkflowMachine;
+    /** Consumer governance rules, applied to PTC calls exactly as to agent calls. */
+    policyRules?: GovernanceRule[];
+    /** The workspace's resolved mount keys, for the kernel's read-only rule. */
+    mountPrefixes?: MountPrefixes;
+    /**
+     * The workspace's resolved skill bundles, for the kernel's skill rule. A
+     * script's calls run on the model's authority, so the state's enabled set binds
+     * them; a hook's do not (the gateway passes `lifecycle` origin, which the rule
+     * exempts).
+     */
+    skills?: SkillPrefixes;
+    emit: WorkflowEventEmitter;
+}
+export declare function createPtcToolGateway(opts: PtcToolGatewayOptions): PtcToolGateway;

package/dist/sandbox/ptc-gateway.js

@@ -0,0 +1,167 @@
+import { findMock, mockPayload, readMocks } from "../core/tool-mocks.js";
+import { isWorkflowToolName } from "../machine/tool-names.js";
+import { SubWorkflowError, subWorkflowParkOf } from "../workflow/sub-workflow.js";
+import { toolCallDetail, toolOutputPreview } from "../core/tool-telemetry.js";
+import { decide } from "../kernel/kernel.js";
+import { NO_MOUNTS } from "../core/mounts.js";
+import { NO_SKILLS } from "../core/skills.js";
+import { REDACTED_TOOLS, redactDisabledSkills } from "../core/skill-redact.js";
+/**
+ * A PTC call the kernel refused. Thrown so the sandbox bridge rejects the
+ * script's promise: fail-closed (the underlying tool never runs) but catchable,
+ * so a script can handle the refusal instead of dying on it.
+ */
+export class PtcGovernanceError extends Error {
+    tool;
+    ruleId;
+    constructor(tool, ruleId, reason) {
+        super(reason);
+        this.tool = tool;
+        this.ruleId = ruleId;
+        this.name = "PtcGovernanceError";
+    }
+}
+/**
+ * Filter a listing a script asked for to the state's enabled skills — the PTC
+ * half of the invisibility rule the governance middleware applies to the model's
+ * own calls, since `tools.ls` inside `archmax_eval` reaches the same tool by
+ * another door. `lifecycle` origin is exempt, as it is from the rule itself: a
+ * hook runs on harness authority.
+ */
+function redactPtcListing(result, enabled, skills, tool, origin) {
+    if (origin === "lifecycle" || skills.length === 0 || !REDACTED_TOOLS.has(tool))
+        return result;
+    if (typeof result !== "string")
+        return result;
+    return redactDisabledSkills(result, enabled, skills);
+}
+/** Normalize whatever the sandbox passed as tool input to a governable args object. */
+function toArgs(input) {
+    return input != null && typeof input === "object" && !Array.isArray(input)
+        ? input
+        : {};
+}
+export function createPtcToolGateway(opts) {
+    const { machine, policyRules = [], mountPrefixes = NO_MOUNTS, skills = NO_SKILLS, emit } = opts;
+    const contexts = new Map();
+    let callSeq = 0;
+    const skillSlugs = skills.map((skill) => skill.slug);
+    const redactSkills = (result, state, tool, origin) => redactPtcListing(result, machine.enabledSkills(state, skillSlugs), skills, tool, origin);
+    /** The session's stable context ref, created on first use. */
+    function contextFor(sessionId) {
+        let context = contexts.get(sessionId);
+        if (!context) {
+            context = { state: machine.entry, config: {} };
+            contexts.set(sessionId, context);
+        }
+        return context;
+    }
+    function governedInvoke(inner, origin, context) {
+        return async (input, config) => {
+            const tool = inner.name;
+            const args = toArgs(input);
+            // Read per call, not per wrap: the session's tool set is frozen but the
+            // workflow state behind it moves with every `archmax_advance`.
+            const { state, config: contextConfig, replyOnly, variables = {} } = context;
+            const callId = `ptc:${++callSeq}`;
+            const verdict = decide(machine, { kind: "tool-call", state, tool, args, origin, ...(replyOnly ? { replyOnly } : {}) }, policyRules, mountPrefixes, variables, skills);
+            if (verdict.decision === "block") {
+                const reason = verdict.reason ?? `'${tool}' is not allowed in state '${state}'.`;
+                // Gated on `warn` for parity with the agent path, where a non-warn
+                // block (the inline-`eval` refusal) is deliberately silent.
+                if (verdict.warn) {
+                    emit({ type: "tool-blocked", state, tool, reason, callId, args, origin });
+                }
+                throw new PtcGovernanceError(tool, verdict.ruleId, reason);
+            }
+            const detail = toolCallDetail(args);
+            emit({
+                type: "tool-called",
+                state,
+                tool,
+                callId,
+                args,
+                origin,
+                ...(detail ? { detail } : {}),
+            });
+            const startedAt = Date.now();
+            const settle = (status, value) => {
+                emit({
+                    type: "tool-result",
+                    state,
+                    tool,
+                    callId,
+                    status,
+                    durationMs: Date.now() - startedAt,
+                    origin,
+                    ...toolOutputPreview(value),
+                });
+            };
+            try {
+                // Mocks are checked after governance, mirroring the agent path where the
+                // mock middleware sits inside the workflow middleware: a call the state
+                // forbids is refused whether or not a test mocked it.
+                // Delegation mocks belong to the dispatcher (see the mock middleware):
+                // serving one here would skip the dispatch and its record of itself.
+                const mock = isWorkflowToolName(tool)
+                    ? undefined
+                    : findMock(readMocks(contextConfig.configurable), tool, args);
+                const result = mock
+                    ? mockPayload(mock)
+                    : // The bridge passes no config of its own; the turn's gives the tool
+                        // the session id, signal and store an agent call would have had, and
+                        // `toolCallId` lets a delegation's telemetry trace back to this call.
+                        await inner.invoke(args, { ...(config ?? contextConfig), toolCallId: callId });
+                const served = redactSkills(result, state, tool, origin);
+                settle("ok", served);
+                return served;
+            }
+            catch (err) {
+                // A delegated sub-run stopped for a person. A script cannot park — a
+                // QuickJS frame is not durable — so this fails closed as an error rather
+                // than letting a raw suspension escape: a script's park must never
+                // unwind the turn that ran it.
+                const parked = subWorkflowParkOf(err);
+                if (parked) {
+                    const failure = new SubWorkflowError("parked", parked.workflow, `Sub-workflow '${parked.workflow}' stopped for a person, and a script cannot wait ` +
+                        `for one: the sandbox has no way to resume. Call it from the state's agent, or ` +
+                        `move the decision to a human node in the calling workflow.`);
+                    settle("error", failure.message);
+                    throw failure;
+                }
+                settle("error", err?.message ?? String(err));
+                throw err;
+            }
+        };
+    }
+    return {
+        wrap(tools, { origin, sessionId }) {
+            const context = contextFor(sessionId);
+            return tools.map((inner) => {
+                const invoke = governedInvoke(inner, origin, context);
+                // A Proxy rather than a rebuilt tool: `name`, `description` and schema
+                // stay the originals. Non-intercepted members are bound to the target so
+                // the real tool's internals never see the proxy as `this`.
+                return new Proxy(inner, {
+                    get(target, prop) {
+                        if (prop === "invoke")
+                            return invoke;
+                        const value = Reflect.get(target, prop, target);
+                        return typeof value === "function" ? value.bind(target) : value;
+                    },
+                });
+            });
+        },
+        refresh(sessionId, next) {
+            const context = contextFor(sessionId);
+            context.state = next.state;
+            context.config = next.config;
+            context.replyOnly = next.replyOnly;
+            context.variables = next.variables;
+        },
+        release(sessionId) {
+            contexts.delete(sessionId);
+        },
+    };
+}
+//# sourceMappingURL=ptc-gateway.js.map

package/dist/sandbox/ptc-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ptc-gateway.js","sourceRoot":"","sources":["../../src/sandbox/ptc-gateway.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/runtime.d.ts

@@ -0,0 +1,59 @@
+import type { StructuredTool } from "@langchain/core/tools";
+import { type SubagentBridgeOptions } from "@langchain/quickjs";
+/**
+ * The pluggable script-execution backend and its bundled QuickJS default.
+ *
+ * Namespaced sessions with an `eval` operation and disposal: QuickJS is what
+ * ships ({@link createQuickJsSandboxRuntime}); a consumer may supply another
+ * implementation to run scripts in a worker or remotely alongside a remote Deep
+ * Agents backend. The executor talks only to this interface.
+ */
+/** Resource quotas applied to a sandbox session, uniformly across implementations. */
+export interface SandboxQuotas {
+    memoryLimitBytes?: number;
+    maxPtcCalls?: number | null;
+    maxResultChars?: number;
+}
+/** Options for creating (or reusing) a namespaced sandbox session. */
+export interface SandboxSessionOptions {
+    /** Privileged tools scripts may call (PTC). */
+    tools?: StructuredTool[];
+    /** Quotas bounding this session's execution. */
+    quotas?: SandboxQuotas;
+    /** Capture `console.*` output into the eval result's `logs`. */
+    captureConsole?: boolean;
+    /** Session id surfaced to scripts (the run/session id). */
+    sessionId?: string;
+    /** Subagent bridge dispatch for `task()` calls, and its concurrency cap. */
+    subagentDispatch?: SubagentBridgeOptions["dispatch"];
+    subagentMaxConcurrency?: number;
+}
+/** The normalized result of one sandbox `eval` — the shape the executor surfaces. */
+export interface SandboxEvalResult {
+    ok: boolean;
+    value: unknown;
+    logs: string[];
+    error?: {
+        name?: string;
+        message?: string;
+    };
+    /** Human-readable rendering of the result (value or error), for tool replies. */
+    formatted: string;
+}
+/** A namespaced sandbox session that evaluates code with a per-call timeout. */
+export interface SandboxSession {
+    eval(code: string, timeoutMs?: number): Promise<SandboxEvalResult>;
+}
+export interface SandboxRuntime {
+    /** Get or create the session for a namespace, applying the given options. */
+    session(namespace: string, options: SandboxSessionOptions): SandboxSession;
+    /** Release the session for a namespace (idempotent). */
+    dispose(namespace: string): void;
+}
+/**
+ * The bundled default: `@langchain/quickjs`'s `ReplSession` behind the
+ * interface. Sessions are keyed by namespace and reused across evals (the
+ * runtime namespaces per session + session kind), and `formatReplResult`
+ * renders the outcome so the executor stays engine-agnostic.
+ */
+export declare function createQuickJsSandboxRuntime(): SandboxRuntime;