@archmax-ai/harness 0.0.0

package/dist/rubrics/rubrics.js

@@ -0,0 +1,145 @@
+import { normalizeHooks } from "../lifecycle/hook-shape.js";
+import { ADVANCE_TOOL } from "../machine/tool-names.js";
+/**
+ * The structured output a rubric with an iteration budget must return. Applied
+ * automatically, so a grader's output is a contract rather than a prompt
+ * convention.
+ */
+export const RUBRIC_VERDICT_SCHEMA = {
+    type: "object",
+    properties: {
+        verdict: { type: "string", enum: ["ok", "correct", "veto"] },
+        reason: { type: "string" },
+    },
+    required: ["verdict", "reason"],
+};
+/**
+ * The id one inline rubric is registered and dispatched under. Positional
+ * because an inline rubric has no name: reordering a phase's hooks re-keys them,
+ * which is the same class of change as editing the spec at all (it moves the
+ * spec hash).
+ */
+export function rubricId(state, phase, index) {
+    return `${state}--${phase}--${index}`;
+}
+/** Whether a value is a usable verdict. Anything else has graded nothing. */
+export function isRubricVerdict(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return v.verdict === "ok" || v.verdict === "correct" || v.verdict === "veto";
+}
+/**
+ * The structured-output schema every dispatch requests: the verdict schema,
+ * unconditionally.
+ *
+ * Not conditional on `max_iterations`, as it was when a grader was a subagent
+ * that might also be a general-purpose helper. A rubric only ever grades, so a
+ * grader that needs no retries still has to answer in the verdict vocabulary —
+ * and without the schema its answer arrives as prose, parses to no verdict, and
+ * fails closed on a transition the author expected it to wave through.
+ */
+export function resolveRubricResponseFormat(_rubric) {
+    return RUBRIC_VERDICT_SCHEMA;
+}
+/** The compact task payload a grader is handed: the request, the transcript, and where it happened. */
+export function buildRubricTaskDescription(args) {
+    return JSON.stringify({
+        userRequest: args.userRequest ?? null,
+        history: args.history ?? [],
+        state: args.state ?? null,
+        phase: args.phase ?? null,
+    }, null, 2);
+}
+/**
+ * Map an `after`-hook verdict to an `archmax_advance` rejection outcome. One
+ * implementation for every hook kind: the retry flow (bounded iterations with
+ * remaining-attempt guidance) is identical whether the verdict came from a
+ * rubric or a script — only the label differs (`rubric` vs `hook`).
+ */
+export function rubricTransitionOutcome(verdict, opts) {
+    const label = verdict.rubric ? "rubric" : "hook";
+    if (verdict.verdict === "ok") {
+        return { reason: null, budgetExhausted: false, consumesIteration: false };
+    }
+    if (verdict.verdict === "veto") {
+        // A deliberate veto charges nothing: no retry was offered to bill for.
+        return {
+            reason: `${label} veto: ${verdict.reason}`,
+            budgetExhausted: false,
+            consumesIteration: false,
+        };
+    }
+    const max = Math.max(0, opts.maxIterations);
+    if (opts.iterationsUsed >= max) {
+        return {
+            reason: `${label} veto: reply still incomplete after ${max} attempt(s) — ${verdict.reason}`,
+            budgetExhausted: true,
+            consumesIteration: false,
+        };
+    }
+    const remaining = max - opts.iterationsUsed;
+    const target = opts.to ? `${ADVANCE_TOOL}({ to: "${opts.to}" })` : ADVANCE_TOOL;
+    return {
+        reason: `${label}: reply incomplete — ${verdict.reason}. ` +
+            `Update your answer and call ${target} again. (${remaining} attempt(s) remaining)`,
+        budgetExhausted: false,
+        consumesIteration: true,
+    };
+}
+/**
+ * The rejection reason alone, for callers that do not decide the retry budget.
+ */
+export function rubricTransitionReason(verdict, opts) {
+    return rubricTransitionOutcome(verdict, opts).reason;
+}
+/**
+ * The rubric registry for one machine: every inline rubric its states declare,
+ * keyed by {@link rubricId}. Walks the spec rather than reading a root block,
+ * because a grader lives on the hook that applies it.
+ *
+ * Scoped to this spec, so a delegated child is graded by its own standards; two
+ * states declaring the same criteria produce two entries, which is the accepted
+ * cost of a state being legible on its own.
+ */
+export function rubricsFromSpec(spec) {
+    const registry = new Map();
+    for (const [state, declared] of Object.entries(spec.states ?? {})) {
+        for (const phase of ["before", "after"]) {
+            normalizeHooks(declared?.[phase]).forEach((hook, index) => {
+                const declaration = hook.rubric;
+                if (declaration === undefined || typeof declaration !== "object")
+                    return;
+                const id = rubricId(state, phase, index);
+                registry.set(id, { ...declaration, id, state, phase, index });
+            });
+        }
+    }
+    return registry;
+}
+/**
+ * Project the registry into the Deep Agents subagent shape so the framework
+ * registers the `task` tool the runtime dispatches through. These are never
+ * disclosed to the agent: `task` is withheld in every state and grantable by
+ * nothing, so registering a grader here gives the graded agent no reach.
+ *
+ * `model` resolves the grader's own model when it declared one, else the
+ * assembly's `rubric`-role model.
+ */
+export function rubricsAsSubagents(registry, modelFor) {
+    return [...registry.values()].map((rubric) => {
+        const responseFormat = resolveRubricResponseFormat(rubric);
+        const model = modelFor?.(rubric);
+        return {
+            name: rubric.id,
+            // A grader is dispatched by the runtime under its positional id, never
+            // chosen from a menu by the agent, so the description exists only for the
+            // framework's own tool schema — which no state is ever shown.
+            description: `Grading rubric on '${rubric.state}' (${rubric.phase}).`,
+            systemPrompt: rubric.instructions,
+            ...(responseFormat !== undefined ? { responseFormat } : {}),
+            ...(model !== undefined ? { model } : {}),
+        };
+    });
+}
+//# sourceMappingURL=rubrics.js.map

package/dist/rubrics/rubrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rubrics.js","sourceRoot":"","sources":["../../src/rubrics/rubrics.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAexD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE;QAC5D,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC3B;IACD,QAAQ,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC;CACvB,CAAC;AAcX;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,KAAyB,EAAE,KAAa;IAC9E,OAAO,GAAG,KAAK,KAAK,KAAK,KAAK,KAAK,EAAE,CAAC;AACxC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC;AAC/E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAA0B;IAE1B,OAAO,qBAA2D,CAAC;AACrE,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,0BAA0B,CAAC,IAA6B;IACtE,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI;QACrC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE;QAC3B,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;KAC1B,EACD,IAAI,EACJ,CAAC,CACF,CAAC;AACJ,CAAC;AAoBD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAA4B,EAC5B,IAAoE;IAEpE,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;IACjD,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;IAC5E,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC/B,uEAAuE;QACvE,OAAO;YACL,MAAM,EAAE,GAAG,KAAK,UAAU,OAAO,CAAC,MAAM,EAAE;YAC1C,eAAe,EAAE,KAAK;YACtB,iBAAiB,EAAE,KAAK;SACzB,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,cAAc,IAAI,GAAG,EAAE,CAAC;QAC/B,OAAO;YACL,MAAM,EAAE,GAAG,KAAK,uCAAuC,GAAG,iBAAiB,OAAO,CAAC,MAAM,EAAE;YAC3F,eAAe,EAAE,IAAI;YACrB,iBAAiB,EAAE,KAAK;SACzB,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,YAAY,WAAW,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC;IAChF,OAAO;QACL,MAAM,EACJ,GAAG,KAAK,wBAAwB,OAAO,CAAC,MAAM,IAAI;YAClD,+BAA+B,MAAM,YAAY,SAAS,wBAAwB;QACpF,eAAe,EAAE,KAAK;QACtB,iBAAiB,EAAE,IAAI;KACxB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA4B,EAC5B,IAAoE;IAEpE,OAAO,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,MAAM,CAAC;AACvD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiC;IAC/D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAClE,KAAK,MAAM,KAAK,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAU,EAAE,CAAC;YACjD,cAAc,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBACxD,MAAM,WAAW,GAAI,IAAuC,CAAC,MAAM,CAAC;gBACpE,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,WAAW,KAAK,QAAQ;oBAAE,OAAO;gBACzE,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;gBACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;YAChE,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAA6B,EAC7B,QAAwD;IAExD,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QAC3C,MAAM,cAAc,GAAG,2BAA2B,CAAC,MAAM,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,EAAE;YACf,uEAAuE;YACvE,0EAA0E;YAC1E,8DAA8D;YAC9D,WAAW,EAAE,sBAAsB,MAAM,CAAC,KAAK,MAAM,MAAM,CAAC,KAAK,IAAI;YACrE,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1B,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/runtime/contract.d.ts

@@ -0,0 +1,73 @@
+import type { RuntimeMetadata } from "../machine/types.js";
+/**
+ * A workflow runtime contract: the authoring/runtime semantics a workspace
+ * expects. This is a coarse, stable axis (`"1"`, `"2"`, …) and is intentionally
+ * **not** the npm package version — patch/minor implementation releases must not
+ * force workflow authors to bump their `WORKFLOW.md`.
+ */
+export interface RuntimeContract {
+    engine: string;
+    version: string;
+}
+/**
+ * A {@link RuntimeContract} plus whether it was declared or defaulted, and the
+ * two surfaces the version implies.
+ *
+ * `sandbox` and `testFormat` are **derived, never declared**. They used to be
+ * three independent vocabularies — a `runtime.version` in the spec, a sandbox
+ * contract version, and a per-file `version` in `*.test.yaml` — describing one
+ * fact: which release of the authoring surface a workspace targets. Three
+ * vocabularies could disagree; one cannot.
+ */
+export interface ResolvedRuntimeContract extends RuntimeContract {
+    source: "declared" | "defaulted";
+    /** Sandbox script contract implied by this runtime version. */
+    sandbox: number;
+    /** Offline test-case format implied by this runtime version. */
+    testFormat: string;
+}
+/** The sandbox script contract applied when nothing resolves a runtime version. */
+export declare const DEFAULT_SANDBOX_VERSION: number;
+/**
+ * The execution contexts the runtime assembles a prelude for. The vocabulary
+ * survived the contract merge; the list of them did not, because nothing
+ * enumerated it — a context is always named, never iterated.
+ */
+export type SandboxContext = "lifecycle-hook" | "ptc";
+/** The runtime engine this package implements. */
+export declare const RUNTIME_ENGINE = "archmax-harness";
+/** Default contract version applied when metadata is omitted. */
+export declare const DEFAULT_RUNTIME_VERSION = "1";
+/** The contract resolved for workspaces that omit `runtime` metadata. */
+export declare const DEFAULT_RUNTIME_CONTRACT: RuntimeContract;
+/**
+ * The explicit set of runtime contracts the installed runtime supports.
+ * Version 2 identifies the v2 authoring contract (two-file `workflow.yaml` /
+ * `WORKFLOW.md` layout, declarative `tests:` block, typed sandbox imports,
+ * verdict-returning hook functions). Load behavior is
+ * layout-driven, not version-driven — the version is declarative metadata for
+ * support checking, validation, and docs. Version 1 remains supported.
+ */
+export declare const SUPPORTED_RUNTIME_CONTRACTS: readonly RuntimeContract[];
+/** Render a contract as `engine@version` for messages and artifacts. */
+export declare function formatRuntimeContract(contract: RuntimeContract): string;
+/**
+ * Resolve a workflow's runtime contract from optional declared metadata. Omitted
+ * metadata (or metadata with neither `engine` nor `version`) resolves to the
+ * default contract with `source: "defaulted"`.
+ */
+export declare function resolveRuntimeContract(metadata?: RuntimeMetadata | null): ResolvedRuntimeContract;
+/** Whether a contract is in the installed runtime's supported set. */
+export declare function isRuntimeContractSupported(contract: RuntimeContract): boolean;
+/**
+ * Diagnostic-friendly support check. Returns `null` when the contract is
+ * supported, otherwise an actionable message naming the requested contract and
+ * the supported set.
+ */
+export declare function unsupportedRuntimeContractMessage(contract: RuntimeContract): string | null;
+/** Thrown by assembly when a workflow declares an unsupported contract. */
+export declare class UnsupportedRuntimeContractError extends Error {
+    readonly requested: RuntimeContract;
+    readonly supported: readonly RuntimeContract[];
+    constructor(requested: RuntimeContract, supported?: readonly RuntimeContract[]);
+}

package/dist/runtime/contract.js

@@ -0,0 +1,96 @@
+/**
+ * What each supported runtime version implies for the surfaces that used to
+ * version themselves.
+ *
+ * Sandbox 2 = hooks are default-export functions returning `ok()` / `veto()` /
+ * `correct()`,
+ * plus typed `@archmax-ai/harness/*` import stripping. The test-case format has not
+ * changed across runtime versions, which is exactly why it did not need an axis
+ * of its own.
+ *
+ * This table is the single source of the supported set — adding a runtime
+ * version is one entry here.
+ */
+const CONTRACT_SURFACES = {
+    "1": { sandbox: 1, testFormat: "1" },
+    "2": { sandbox: 2, testFormat: "1" },
+};
+/** The sandbox script contract applied when nothing resolves a runtime version. */
+export const DEFAULT_SANDBOX_VERSION = CONTRACT_SURFACES["2"].sandbox;
+/** The runtime engine this package implements. */
+export const RUNTIME_ENGINE = "archmax-harness";
+/** Default contract version applied when metadata is omitted. */
+export const DEFAULT_RUNTIME_VERSION = "1";
+/** The contract resolved for workspaces that omit `runtime` metadata. */
+export const DEFAULT_RUNTIME_CONTRACT = {
+    engine: RUNTIME_ENGINE,
+    version: DEFAULT_RUNTIME_VERSION,
+};
+/**
+ * The explicit set of runtime contracts the installed runtime supports.
+ * Version 2 identifies the v2 authoring contract (two-file `workflow.yaml` /
+ * `WORKFLOW.md` layout, declarative `tests:` block, typed sandbox imports,
+ * verdict-returning hook functions). Load behavior is
+ * layout-driven, not version-driven — the version is declarative metadata for
+ * support checking, validation, and docs. Version 1 remains supported.
+ */
+export const SUPPORTED_RUNTIME_CONTRACTS = Object.keys(CONTRACT_SURFACES).map((version) => ({ engine: RUNTIME_ENGINE, version }));
+/** Render a contract as `engine@version` for messages and artifacts. */
+export function formatRuntimeContract(contract) {
+    return `${contract.engine}@${contract.version}`;
+}
+/**
+ * Resolve a workflow's runtime contract from optional declared metadata. Omitted
+ * metadata (or metadata with neither `engine` nor `version`) resolves to the
+ * default contract with `source: "defaulted"`.
+ */
+export function resolveRuntimeContract(metadata) {
+    if (!metadata || (metadata.engine === undefined && metadata.version === undefined)) {
+        return {
+            ...DEFAULT_RUNTIME_CONTRACT,
+            source: "defaulted",
+            ...surfacesFor(DEFAULT_RUNTIME_VERSION),
+        };
+    }
+    const declaredEngine = metadata.engine !== undefined ? String(metadata.engine) : RUNTIME_ENGINE;
+    const version = metadata.version !== undefined ? String(metadata.version) : DEFAULT_RUNTIME_VERSION;
+    return { engine: declaredEngine, version, source: "declared", ...surfacesFor(version) };
+}
+/**
+ * The surfaces a version implies, falling back to the default's for a version
+ * outside the table. Resolution stays total on purpose: an unsupported version
+ * is reported by {@link isRuntimeContractSupported} and thrown by assembly, so
+ * this function must not also throw — a diagnostic path that needs to *name* an
+ * unsupported contract has to be able to resolve it first.
+ */
+function surfacesFor(version) {
+    return CONTRACT_SURFACES[version] ?? CONTRACT_SURFACES[DEFAULT_RUNTIME_VERSION];
+}
+/** Whether a contract is in the installed runtime's supported set. */
+export function isRuntimeContractSupported(contract) {
+    return SUPPORTED_RUNTIME_CONTRACTS.some((supported) => supported.engine === contract.engine && supported.version === contract.version);
+}
+/**
+ * Diagnostic-friendly support check. Returns `null` when the contract is
+ * supported, otherwise an actionable message naming the requested contract and
+ * the supported set.
+ */
+export function unsupportedRuntimeContractMessage(contract) {
+    if (isRuntimeContractSupported(contract))
+        return null;
+    const supported = SUPPORTED_RUNTIME_CONTRACTS.map(formatRuntimeContract).join(", ");
+    return `Unsupported runtime contract '${formatRuntimeContract(contract)}'. Supported: ${supported}.`;
+}
+/** Thrown by assembly when a workflow declares an unsupported contract. */
+export class UnsupportedRuntimeContractError extends Error {
+    requested;
+    supported;
+    constructor(requested, supported = SUPPORTED_RUNTIME_CONTRACTS) {
+        super(`Unsupported runtime contract '${formatRuntimeContract(requested)}'. ` +
+            `Supported: ${supported.map(formatRuntimeContract).join(", ")}.`);
+        this.name = "UnsupportedRuntimeContractError";
+        this.requested = requested;
+        this.supported = supported;
+    }
+}
+//# sourceMappingURL=contract.js.map

package/dist/runtime/contract.js.map

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

package/dist/sandbox/assets/parts/core.js

@@ -0,0 +1,22 @@
+// QuickJS sandbox core: the verdict helpers a lifecycle hook answers with.
+//
+//   return ok();               // proceed
+//   return correct("why");     // the agent gets another attempt (after hooks)
+//   return veto("why");        // block, with the reason shown to the agent
+//
+// Returning nothing is `ok`; throwing is a veto (fail-closed). Nothing else is
+// installed here — the hook reads its inputs from the object it is called with.
+
+globalThis.__verdict = (verdict, reason, fallback) => ({
+  verdict,
+  reason: reason == null || String(reason).trim() === "" ? fallback : String(reason),
+});
+
+globalThis.ok = (reason) => globalThis.__verdict("ok", reason, "ok");
+globalThis.veto = (reason) => globalThis.__verdict("veto", reason, "vetoed by hook");
+globalThis.correct = (reason) => globalThis.__verdict("correct", reason, "correction requested");
+
+globalThis.__isVerdict = (value) =>
+  value != null &&
+  typeof value === "object" &&
+  (value.verdict === "ok" || value.verdict === "veto" || value.verdict === "correct");

package/dist/sandbox/assets/parts/lifecycle-hook.js

@@ -0,0 +1,47 @@
+// Lifecycle-hook context: the contract marker, the `defineHook` authoring
+// alias, and the reducer that turns whatever a hook produced into a verdict.
+// These globals are absent from the PTC context.
+
+globalThis.SANDBOX_CONTRACT = { context: "lifecycle-hook", version: globalThis.__SANDBOX_VERSION };
+
+// `export default defineHook(fn)` and `export default async function hook(...)`
+// both register the hook; the executor rewrites `export default` to an
+// assignment of `__hookDef`, so `defineHook` is an identity that also registers.
+globalThis.defineHook = (fn) => {
+  globalThis.__hookDef = fn;
+  return fn;
+};
+
+// How an object that is not a verdict is named back to its author: by its keys,
+// never its values, so a diagnostic cannot leak what the hook was inspecting.
+globalThis.__hookShape = (value) => {
+  if (Array.isArray(value)) return "an array";
+  try {
+    const keys = Object.keys(value);
+    if (keys.length === 0) return "an object with no keys";
+    const shown = keys.slice(0, 6).map((key) => `'${key}'`).join(", ");
+    return `an object with ${keys.length > 6 ? "keys including " : "keys "}${shown}`;
+  } catch {
+    return "an object";
+  }
+};
+
+// The verdict of a hook run. A verdict object is taken as is, a bare `false`
+// vetoes, and returning nothing is `ok`.
+//
+// Any *other* object fails closed. A hook's return value is its verdict and
+// nothing else, so an object that is not one is a verdict its author got wrong
+// — a misspelled `verdict`, a retired shape like `{ ok: false, reason }`. Read
+// as `ok` it would silently permit precisely what the hook meant to block, and
+// the author would have no way to notice: the run just proceeds.
+globalThis.__hookVerdict = (value) => {
+  if (globalThis.__isVerdict(value)) return value;
+  if (value === false) return globalThis.veto("precondition not met");
+  if (value !== null && typeof value === "object") {
+    throw new Error(
+      `hook returned ${globalThis.__hookShape(value)}, which is not a verdict — ` +
+        "return ok(), veto(reason), correct(reason), false, or nothing at all",
+    );
+  }
+  return globalThis.ok();
+};

package/dist/sandbox/bridge.d.ts

@@ -0,0 +1,16 @@
+import type { RunnableConfig } from "@langchain/core/runnables";
+import type { StructuredTool } from "@langchain/core/tools";
+import { type SubagentBridgeOptions } from "@langchain/quickjs";
+import type { WorkflowEventEmitter } from "../core/events.js";
+/** Recover the textual payload from whatever envelope `task()` returns. */
+export declare function unwrapToolEnvelope(value: unknown): unknown;
+/**
+ * Bridge the QuickJS `task()` global to the Deep Agents `task` tool. When
+ * `telemetry` is supplied, each dispatch is bracketed with
+ * `rubric-start`/`rubric-result` lifecycle events (this path bypasses the
+ * outer agent's tool middleware, so it must emit its own bracketing).
+ */
+export declare function createSubagentBridgeDispatch(taskTool: StructuredTool, config: RunnableConfig, telemetry?: {
+    emit: WorkflowEventEmitter;
+    state?: string;
+}): SubagentBridgeOptions["dispatch"];

package/dist/sandbox/bridge.js

@@ -0,0 +1,95 @@
+import { BaseMessage } from "@langchain/core/messages";
+import { isCommand } from "@langchain/langgraph";
+import { SUBAGENT_RESPONSE_FORMAT_CONFIG_KEY } from "deepagents";
+import { validateResponseSchema } from "@langchain/quickjs";
+/** Recover the textual payload from whatever envelope `task()` returns. */
+export function unwrapToolEnvelope(value) {
+    if (typeof value === "string")
+        return value;
+    if (isCommand(value)) {
+        const messages = value.update?.messages;
+        if (Array.isArray(messages)) {
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const message = messages[i];
+                if (BaseMessage.isInstance(message) && message.content != null) {
+                    return unwrapToolEnvelope(message.content);
+                }
+            }
+        }
+        return value;
+    }
+    if (BaseMessage.isInstance(value))
+        return unwrapToolEnvelope(value.content);
+    if (Array.isArray(value)) {
+        for (let i = value.length - 1; i >= 0; i--) {
+            const entry = value[i];
+            if (BaseMessage.isInstance(entry))
+                return unwrapToolEnvelope(entry.content);
+            if (isCommand(entry)) {
+                const inner = unwrapToolEnvelope(entry);
+                if (inner !== entry)
+                    return inner;
+            }
+        }
+    }
+    return value;
+}
+/** Ids for bridge dispatches, which have no model-assigned tool-call id. */
+let bridgeDispatchSeq = 0;
+/**
+ * Bridge the QuickJS `task()` global to the Deep Agents `task` tool. When
+ * `telemetry` is supplied, each dispatch is bracketed with
+ * `rubric-start`/`rubric-result` lifecycle events (this path bypasses the
+ * outer agent's tool middleware, so it must emit its own bracketing).
+ */
+export function createSubagentBridgeDispatch(taskTool, config, telemetry) {
+    return async (input) => {
+        const hasSchema = input.responseSchema != null;
+        if (hasSchema)
+            validateResponseSchema(input.responseSchema);
+        const toolConfig = {
+            ...config,
+            configurable: {
+                ...config.configurable,
+                ...(hasSchema && { [SUBAGENT_RESPONSE_FORMAT_CONFIG_KEY]: input.responseSchema }),
+            },
+        };
+        const dispatchId = `bridge-${++bridgeDispatchSeq}`;
+        const state = telemetry?.state ?? "";
+        telemetry?.emit({
+            type: "rubric-start",
+            state,
+            name: input.subagentType,
+            dispatchId,
+        });
+        const startedAt = Date.now();
+        const settle = (status) => telemetry?.emit({
+            type: "rubric-result",
+            state,
+            name: input.subagentType,
+            dispatchId,
+            status,
+            durationMs: Date.now() - startedAt,
+        });
+        let raw;
+        try {
+            raw = await taskTool.invoke({ description: input.description, subagent_type: input.subagentType }, toolConfig);
+        }
+        catch (err) {
+            settle("error");
+            throw err;
+        }
+        settle("ok");
+        const content = unwrapToolEnvelope(raw);
+        if (hasSchema && typeof content === "string") {
+            try {
+                return JSON.parse(content);
+            }
+            catch {
+                return content;
+            }
+        }
+        return content;
+    };
+}
+//# sourceMappingURL=bridge.js.map

package/dist/sandbox/bridge.js.map

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

package/dist/sandbox/executor.d.ts

@@ -0,0 +1,46 @@
+import type { StructuredTool } from "@langchain/core/tools";
+import type { Workspace } from "../core/workspace.js";
+import { type SandboxRuntime } from "./runtime.js";
+export declare const AGENT_SESSION = "agent";
+export declare const PROCESS_SESSION = "process";
+export interface ScriptRunParams {
+    sessionId: string;
+    sessionNamespace: string;
+    args?: Record<string, unknown>;
+    tools?: StructuredTool[];
+    /** Run as a lifecycle hook: the hook prelude, the hook input, a verdict back. */
+    lifecycle?: boolean;
+    /**
+     * `runCode` only: prepend the context's prelude, so inline code runs under
+     * the same contract as an authored file. The agent's `archmax_eval` sets it;
+     * bespoke callers that assemble their own preamble leave it off.
+     */
+    prelude?: boolean;
+}
+export interface ScriptOutcome {
+    ok: boolean;
+    value: unknown;
+    logs: string[];
+    error?: {
+        name?: string;
+        message?: string;
+    };
+    formatted: string;
+}
+export interface ScriptExecutor {
+    runFile(filePath: string, params: ScriptRunParams): Promise<ScriptOutcome>;
+    runCode(code: string, params: ScriptRunParams): Promise<ScriptOutcome>;
+    dispose(sessionId: string, sessionNamespace?: string): void;
+}
+export interface ScriptExecutorOptions {
+    workspace: Workspace;
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+    maxPtcCalls?: number | null;
+    maxResultChars?: number;
+    /** Sandbox contract version injected into each prelude (default: current). */
+    sandboxVersion?: number;
+    /** Script-execution backend; defaults to the bundled QuickJS runtime. */
+    sandboxRuntime?: SandboxRuntime;
+}
+export declare function createScriptExecutor(opts: ScriptExecutorOptions): ScriptExecutor;