@archmax-ai/harness 0.0.0

package/dist/lifecycle/runner.js

@@ -0,0 +1,372 @@
+import { runContextFromMessages } from "../core/messages.js";
+import { createSubagentBridgeDispatch } from "../sandbox/bridge.js";
+import { PROCESS_SESSION, } from "../sandbox/executor.js";
+import { resolvePtcTools } from "../sandbox/tools.js";
+import { afterHookLabel, hookKind, hookMaxIterations, iterationKey } from "./hook-shape.js";
+import { hookTranscript } from "./transcript.js";
+import { buildRubricTaskDescription, isRubricVerdict, resolveRubricResponseFormat, rubricId, } from "../rubrics/rubrics.js";
+import { createWorkflowEventEmitter, } from "../core/events.js";
+import { decide, reduceHookFact } from "../kernel/kernel.js";
+/**
+ * Interpret a lifecycle hook's return value into a decision, an error, or
+ * `null` (no opinion — proceed).
+ *
+ * **One contract for every hook kind**, the one `HookResult` declares: a verdict
+ * object decides, a bare `false` vetoes, returning nothing is `ok`, and any
+ * *other* object fails closed with its keys named. 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; reading it as `ok` would silently permit what the hook meant to
+ * block, with nothing said.
+ *
+ * A **script** hook's value arrives already reduced — the sandbox wrapper
+ * applies the same rules and throws on the last one — so what reaches here from
+ * a script is a verdict or an error outcome. The rules are restated because a
+ * custom `hookExecutors` kind hands its value through raw, and a consumer's
+ * executor is held to the same contract as a script: one governance vocabulary,
+ * whoever implements the kind.
+ */
+export function parseLifecycleDecision(outcome) {
+    if (!outcome.ok)
+        return { error: outcome.error?.message ?? "script error" };
+    const value = outcome.value;
+    if (isRubricVerdict(value)) {
+        return {
+            verdict: value.verdict,
+            reason: value.reason,
+            ...(value.rubric !== undefined ? { rubric: value.rubric } : {}),
+        };
+    }
+    if (value === false)
+        return { verdict: "veto", reason: "precondition not met" };
+    if (value !== null && typeof value === "object") {
+        return {
+            error: `hook returned ${describeNonVerdict(value)}, which is not a verdict — return ` +
+                `{ verdict: "ok" | "correct" | "veto", reason }, false, or nothing at all`,
+        };
+    }
+    return null;
+}
+/**
+ * Name a non-verdict object by its keys, never its values, so a diagnostic
+ * cannot leak what the hook was inspecting. Mirrors `__hookShape` in the
+ * sandbox prelude, which does the same for a script hook.
+ */
+function describeNonVerdict(value) {
+    if (Array.isArray(value))
+        return "an array";
+    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}`;
+}
+/** The built-in hook kinds, which consumer executors may not shadow. */
+export const BUILTIN_HOOK_KINDS = ["script", "rubric"];
+/** Short raw-output excerpt surfaced when a judge response cannot be parsed. */
+function snippet(value) {
+    let text;
+    try {
+        text = typeof value === "string" ? value : JSON.stringify(value);
+    }
+    catch {
+        text = String(value);
+    }
+    if (text === undefined || text === "undefined")
+        text = "(no output)";
+    return text.length > 200 ? `${text.slice(0, 200)}…` : text;
+}
+/**
+ * Runs deterministic `before`/`after` hooks (scripts or grading rubrics) at the
+ * machine's fixed points, in the same backend-backed interpreter as the model's
+ * own sandbox tool calls.
+ */
+export class LifecycleRunner {
+    machine;
+    executor;
+    rubrics;
+    ptcNames;
+    emit;
+    /** Hook kind → executor. Built-ins (`script`, `rubric`) plus registered custom kinds. */
+    hookExecutors;
+    /**
+     * Maps a hook's declared `script:` value to the path its source is read from.
+     * Injected so the runner stays ignorant of workspace layout: the harness binds
+     * it to the running workflow (workflow-relative, confined to `hooks/`). The
+     * identity default keeps a bare runner working.
+     */
+    resolveScript;
+    /** Deprecations already reported — each is said once per assembly. */
+    constructor(machine, executor, rubrics, ptcNames, hookExecutors, onEvent, opts = {}) {
+        this.machine = machine;
+        this.executor = executor;
+        this.rubrics = rubrics;
+        this.ptcNames = ptcNames;
+        this.emit = createWorkflowEventEmitter(onEvent);
+        this.resolveScript = opts.resolveScript ?? ((declared) => ({ ok: true, path: declared }));
+        // Built-ins first; consumer executors add kinds alongside them (built-ins
+        // are non-shadowable, enforced at assembly).
+        this.hookExecutors = new Map([
+            ["script", (hook, ctx, args) => this.runScript(String(hook.script), ctx, args)],
+        ]);
+        for (const [kind, exec] of Object.entries(hookExecutors ?? {})) {
+            this.hookExecutors.set(kind, exec);
+        }
+    }
+    resolvePtcTools(allTools) {
+        return resolvePtcTools(allTools, this.ptcNames);
+    }
+    /**
+     * The runtime's own dispatch for an inline grader, through the framework
+     * `task` tool. Reached only by {@link runRubric} — never wired into a script's
+     * sandbox, which has no name to dispatch by.
+     */
+    rubricDispatch(ctx, lifecycleArgs) {
+        if (!ctx.taskTool)
+            return undefined;
+        const base = createSubagentBridgeDispatch(ctx.taskTool, ctx.config, {
+            emit: this.emit,
+            ...(typeof lifecycleArgs.state === "string" ? { state: lifecycleArgs.state } : {}),
+        });
+        return async (input) => {
+            const rubric = this.rubrics.get(input.subagentType);
+            const description = input.description?.trim() ||
+                buildRubricTaskDescription({ ...lifecycleArgs, ...runContextFromMessages(ctx.messages) });
+            const responseSchema = input.responseSchema ?? (rubric ? resolveRubricResponseFormat(rubric) : undefined);
+            return base({
+                description,
+                subagentType: input.subagentType,
+                ...(responseSchema !== undefined
+                    ? { responseSchema: responseSchema }
+                    : {}),
+            });
+        };
+    }
+    async runScript(script, ctx, args) {
+        // A hook that cannot be placed is a hook that cannot be trusted: refusing
+        // here produces an error outcome, and an errored hook vetoes fail-closed —
+        // the same posture as a hook that throws.
+        const resolved = this.resolveScript(script);
+        if (!resolved.ok) {
+            return {
+                ok: false,
+                value: undefined,
+                logs: [],
+                error: { message: resolved.reason },
+                formatted: `error: ${resolved.reason}`,
+            };
+        }
+        return this.executor.runFile(resolved.path, {
+            sessionId: ctx.sessionId,
+            sessionNamespace: PROCESS_SESSION,
+            args,
+            tools: ctx.tools,
+            // No `task()` for a script hook: an inline rubric has no name a script
+            // could pass, so there is nothing to dispatch by. A script that wants a
+            // model verdict gets a `rubric` hook declared beside it in the same list.
+            lifecycle: true,
+        });
+    }
+    async runRubric(name, ctx, args) {
+        const dispatch = this.rubricDispatch(ctx, args);
+        if (!dispatch) {
+            const message = `rubric '${name}' could not be dispatched (no task tool)`;
+            return { ok: false, value: undefined, logs: [], error: { message }, formatted: `error: ${message}` };
+        }
+        const rubric = this.rubrics.get(name);
+        const responseSchema = rubric ? resolveRubricResponseFormat(rubric) : undefined;
+        try {
+            const value = await dispatch({
+                subagentType: name,
+                // The grader's payload keeps the compact `userRequest`/`history` view a
+                // rubric's `instructions` are written against.
+                description: buildRubricTaskDescription({ ...args, ...runContextFromMessages(ctx.messages) }),
+                ...(responseSchema !== undefined ? { responseSchema } : {}),
+            });
+            // Fail closed on unreadable grader output, exactly like a thrown error: a
+            // grader whose verdict cannot be read has approved nothing.
+            const verdict = value && typeof value === "object" && isRubricVerdict(value)
+                ? { ...value, rubric: name }
+                : {
+                    verdict: "veto",
+                    reason: `rubric '${name}' returned no parseable verdict: ${snippet(value)}`,
+                    rubric: name,
+                };
+            return { ok: true, value: verdict, logs: [], formatted: JSON.stringify(verdict) };
+        }
+        catch (err) {
+            const message = err.message ?? String(err);
+            return { ok: false, value: undefined, logs: [], error: { message }, formatted: `error: ${message}` };
+        }
+    }
+    /**
+     * Dispatch a single tagged hook through its kind's registered executor.
+     * An unknown kind (no registered executor) produces an error outcome that
+     * reduces to a fail-closed veto — the same path as any hook execution error.
+     */
+    async runHook(hook, ctx, args, at) {
+        const kind = hookKind(hook);
+        // `rubric` is serviced here rather than through the executor map, because
+        // dispatching an inline grader needs the hook's *position* — that is the id
+        // the runtime registered it under, and a `HookExecutor` sees only the hook.
+        // The kind is still non-shadowable: assembly checks `BUILTIN_HOOK_KINDS`.
+        if (kind === "rubric") {
+            return this.runRubric(rubricId(at.state, at.phase, at.index), ctx, args);
+        }
+        const executor = kind ? this.hookExecutors.get(kind) : undefined;
+        if (!executor) {
+            const message = kind
+                ? `no executor registered for hook kind '${kind}'`
+                : `malformed hook (expected a single-key tagged object)`;
+            return { ok: false, value: undefined, logs: [], error: { message }, formatted: `error: ${message}` };
+        }
+        return executor(hook, ctx, args);
+    }
+    applyDecision(state, label, decision, ctx, opts) {
+        this.emit({
+            type: "hook-verdict",
+            state,
+            phase: opts.phase,
+            label,
+            verdict: decision.verdict,
+            reason: decision.reason,
+        });
+        const budget = iterationKey(state, opts.phase, opts.index);
+        const used = ctx.iterations[budget] ?? 0;
+        // Iteration budget, uniform across hook kinds: the hook-level
+        // `max_iterations` sidecar wins (it describes *this* state's retry loop); a
+        // rubric hook falls back to the rubric's own `max_iterations`; otherwise 0
+        // (a `correct` hard-vetoes).
+        const rubric = decision.rubric ? this.rubrics.get(decision.rubric) : undefined;
+        const maxIterations = opts.maxIterations ?? rubric?.max_iterations ?? 0;
+        // The reduction rule lives in the decision kernel; the runner only executes
+        // hooks and applies the verdict (correction bookkeeping + events).
+        const verdict = reduceHookFact({ ...decision, maxIterations, iterationsUsed: used }, { phase: opts.phase, veto: opts.veto, to: opts.to });
+        if (verdict.decision === "block") {
+            if (verdict.correctionConsumed)
+                ctx.iterations[budget] = used + 1;
+            const reason = verdict.reason ?? decision.reason;
+            this.emit({ type: "hook-rejected", state, phase: opts.phase, reason });
+            // Exhausted iteration budget (after-phase correction flow only) cannot be
+            // fixed by retrying in place; a deliberate veto, an in-budget correction,
+            // or a before-phase rejection can. The kernel decides which this is, from
+            // the same reduction that wrote the reason.
+            return { reason, terminal: verdict.budgetExhausted === true };
+        }
+        // Only this hook's own budget is released: a passing hook ahead of a
+        // correcting one must not hand the latter a fresh budget every attempt.
+        delete ctx.iterations[budget];
+        return null;
+    }
+    async runPhase(state, phase, ctx, extraArgs, veto = false) {
+        const hooks = this.machine.lifecycleHooks()[state];
+        const list = phase === "before" ? hooks?.before : hooks?.after;
+        if (!list || list.length === 0)
+            return null;
+        // The hook input (`HookArgs` in the sandbox): the trigger reaches a hook as
+        // its bare id — a run's *input* lives in `variables` — and the transcript as
+        // plain messages.
+        const scriptArgs = {
+            state,
+            phase,
+            ...(ctx.trigger ? { trigger: ctx.trigger.id } : {}),
+            variables: ctx.variables ?? {},
+            messages: hookTranscript(ctx.messages),
+            ...extraArgs,
+        };
+        const to = typeof extraArgs?.to === "string" ? extraArgs.to : undefined;
+        // Run hooks in declaration order, short-circuiting on the first that fails.
+        // The index travels: an inline rubric has no name, so its position in this
+        // list is its identity — for dispatch and for its own retry budget.
+        for (const [index, hook] of list.entries()) {
+            const reject = await this.runSingleHook(state, phase, hook, ctx, scriptArgs, { veto, to, index });
+            if (reject)
+                return reject;
+        }
+        return null;
+    }
+    async runSingleHook(state, phase, hook, ctx, scriptArgs, opts) {
+        const label = afterHookLabel(hook, opts.index);
+        this.emit({ type: "hook-start", state, phase, label });
+        const outcome = await this.runHook(hook, ctx, scriptArgs, {
+            state,
+            phase,
+            index: opts.index,
+        });
+        for (const line of outcome.logs) {
+            if (line.trim()) {
+                this.emit({ type: "hook-output", state, line: line.trimEnd() });
+            }
+        }
+        const parsed = parseLifecycleDecision(outcome);
+        if (parsed && "error" in parsed) {
+            this.emit({ type: "hook-rejected", state, phase, reason: parsed.error });
+            // A hook that could not execute is a terminal failure: retrying the
+            // same turn re-runs the same broken hook.
+            return { reason: parsed.error, terminal: true };
+        }
+        if (!parsed) {
+            if (phase === "before") {
+                this.emit({ type: "hook-passed", state, phase });
+            }
+            return null;
+        }
+        const maxIterations = hookMaxIterations(hook);
+        return this.applyDecision(state, label, parsed, ctx, {
+            phase,
+            veto: opts.veto,
+            to: opts.to,
+            index: opts.index,
+            ...(maxIterations !== undefined ? { maxIterations } : {}),
+        });
+    }
+    async attemptTransition(from, to, ctx, reason, 
+    /**
+     * The tool call driving this attempt, when one is. Carried onto the `advance`
+     * event so a consumer can attribute the transition to the call that made it;
+     * a transition the runtime itself performs passes nothing.
+     */
+    options) {
+        // Work on a copy of the correction counts so the attempt never mutates the
+        // caller's context; the resulting counts are returned for the caller to
+        // commit to the checkpoint.
+        const corrections = { ...ctx.iterations };
+        const localCtx = { ...ctx, iterations: corrections };
+        // Edge validity is a pure, statically-decidable rule — route it through the
+        // decision kernel so runtime and `agent validate` agree. Hook reduction runs
+        // per-hook inside `runPhase` (also kernel-backed via `applyDecision`).
+        const edgeVerdict = decide(this.machine, { kind: "transition", from, to, hookFacts: [] }, [], undefined, ctx.variableStore ?? {});
+        if (edgeVerdict.decision === "block") {
+            return {
+                ok: false,
+                reason: edgeVerdict.reason ?? `cannot advance from '${from}' to '${to}'.`,
+                // An invalid edge is always recoverable: the agent picks a valid target.
+                terminal: false,
+                corrections,
+            };
+        }
+        const trimmedReason = reason?.trim();
+        const afterReject = await this.runPhase(from, "after", localCtx, { from, to, ...(trimmedReason ? { reason: trimmedReason } : {}) }, true);
+        if (afterReject) {
+            return { ok: false, reason: afterReject.reason, terminal: afterReject.terminal, corrections };
+        }
+        const beforeReject = await this.runPhase(to, "before", localCtx);
+        if (beforeReject) {
+            return { ok: false, reason: beforeReject.reason, terminal: beforeReject.terminal, corrections };
+        }
+        this.emit({
+            type: "advance",
+            from,
+            to,
+            ...(trimmedReason ? { reason: trimmedReason } : {}),
+            ...(options?.callId ? { callId: options.callId } : {}),
+        });
+        return { ok: true, from, to, corrections };
+    }
+    dispose(sessionId) {
+        this.executor.dispose(sessionId, PROCESS_SESSION);
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/lifecycle/runner.js.map

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

package/dist/lifecycle/transcript.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One transcript message as a hook reads it: plain data, no LangChain classes.
+ * `role` is `user`, `assistant`, `tool`, `system`, or `runtime` — the last for
+ * a note the runtime wrote (an arrival, a decision, an error route), which a
+ * model cannot read as a person speaking and a hook should not either.
+ */
+export interface HookMessage {
+    role: string;
+    text: string;
+    /** Assistant messages only: the tool calls the message made. */
+    toolCalls?: {
+        name: string;
+        args: unknown;
+    }[];
+    /** Tool results only: the tool that produced the text. */
+    tool?: string;
+    /** Runtime notes only: which kind of note this is. */
+    note?: string;
+}
+/** How much of the transcript a hook is handed: the most recent messages. */
+export declare const HOOK_TRANSCRIPT_LIMIT = 24;
+/**
+ * The recent transcript as a hook receives it in `messages`, newest last. A
+ * runtime note is carried in the transcript as a tool-call pair; only the half
+ * holding the text is kept, as one `runtime` entry.
+ */
+export declare function hookTranscript(messages: unknown[], limit?: number): HookMessage[];

package/dist/lifecycle/transcript.js

@@ -0,0 +1,43 @@
+import { contentToString, messageTypeOf, runtimeNoteKind } from "../core/messages.js";
+const ROLE_BY_TYPE = {
+    human: "user",
+    ai: "assistant",
+    system: "system",
+    tool: "tool",
+    function: "tool",
+};
+/** How much of the transcript a hook is handed: the most recent messages. */
+export const HOOK_TRANSCRIPT_LIMIT = 24;
+/**
+ * The recent transcript as a hook receives it in `messages`, newest last. A
+ * runtime note is carried in the transcript as a tool-call pair; only the half
+ * holding the text is kept, as one `runtime` entry.
+ */
+export function hookTranscript(messages, limit = HOOK_TRANSCRIPT_LIMIT) {
+    const out = [];
+    for (const raw of Array.isArray(messages) ? messages : []) {
+        const msg = raw;
+        const type = messageTypeOf(raw);
+        const text = contentToString(msg.content);
+        const note = runtimeNoteKind(raw);
+        if (note !== null) {
+            if (text.trim() === "")
+                continue;
+            out.push({ role: "runtime", text, note });
+            continue;
+        }
+        const entry = { role: ROLE_BY_TYPE[type] ?? (type || "unknown"), text };
+        const calls = msg.tool_calls;
+        if ((type === "ai" || type === "assistant") && Array.isArray(calls) && calls.length > 0) {
+            entry.toolCalls = calls.map((c) => {
+                const call = c;
+                return { name: String(call.name ?? ""), args: call.args ?? {} };
+            });
+        }
+        if (entry.role === "tool" && typeof msg.name === "string")
+            entry.tool = msg.name;
+        out.push(entry);
+    }
+    return out.slice(-limit);
+}
+//# sourceMappingURL=transcript.js.map

package/dist/lifecycle/transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/lifecycle/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAmBtF,MAAM,YAAY,GAA2B;IAC3C,KAAK,EAAE,MAAM;IACb,EAAE,EAAE,WAAW;IACf,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,MAAM;CACjB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmB,EAAE,KAAK,GAAG,qBAAqB;IAC/E,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAG,GAA8B,CAAC;QAC3C,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,SAAS;YACjC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1C,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAgB,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC;QACrF,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,WAAW,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxF,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBAChC,MAAM,IAAI,GAAG,CAA4B,CAAC;gBAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;YAClE,CAAC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACjF,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC"}

package/dist/machine/allow.d.ts

@@ -0,0 +1,65 @@
+import type { AllowEntry, MachineSpec } from "./types.js";
+import { type VariableReference, type VariableStore } from "./variables.js";
+/** Conventional path argument for file tools and `archmax_run`. */
+export declare const DEFAULT_PATH_ARG = "file_path";
+export interface NormalizedAllowEntry {
+    tool: string | undefined;
+    /** Per-argument glob matchers, or null to allow the tool with any arguments. */
+    argMatchers: Record<string, string[]> | null;
+}
+/**
+ * Whether a value matches any of the given globs. The value is canonicalized
+ * (`.`/`..`/`//` resolved) so a `./` or `.//` prefix cannot dodge a
+ * `forbid_paths` glob — the matcher sees the same path the backend resolves.
+ * Globs are leading-slash-normalized only, preserving their wildcards.
+ *
+ * `dot: true`: a workspace path is not a shell glob, and a governance glob that
+ * skipped dot-prefixed segments would read the same either way — `secrets/**`
+ * would miss `secrets/.env` on the deny side while `scratchpad/**` would refuse
+ * `scratchpad/.cache` on the allow side.
+ */
+export declare function valueMatches(value: unknown, globs: string[]): boolean;
+/**
+ * Normalize an `allow` entry into a tool name plus optional argument matchers.
+ * One shared derivation for the kernel, disclosure, and `validate`, so they
+ * cannot disagree about what an entry covers.
+ */
+export declare function normalizeAllowEntry(entry: AllowEntry): NormalizedAllowEntry;
+/**
+ * An unresolvable `${{…}}` reference in a guard. Not a mismatch: the harness
+ * could not evaluate the governance the author declared, so the caller turns
+ * this into a terminal run failure rather than a retryable block.
+ */
+export interface GuardResolutionFailure {
+    reference: string;
+    detail: string;
+}
+/**
+ * Whether a tool call's arguments satisfy a normalized allow entry's matchers.
+ *
+ * `${{…}}` references are resolved against the run's variables per call, never
+ * cached: a `set_variables` later in the same turn must take effect on the very
+ * next call. An unresolvable reference makes the entry match nothing and reports
+ * why through `onUnresolved` — never the literal `${{…}}` text or a permissive
+ * pattern. A dotted argument key (`args.file_path`) is read with the same
+ * own-property traversal `${{…}}` paths use, never the prototype chain.
+ */
+export declare function argsSatisfy(argMatchers: Record<string, string[]> | null, args: Record<string, unknown>, variables?: VariableStore, onUnresolved?: (failure: GuardResolutionFailure) => void): boolean;
+/**
+ * One `${{…}}` reference found in a tool-argument guard, with enough context to
+ * name it in a diagnostic: which state (null for an `allow_always` entry, which
+ * binds in every state), which tool, and which argument.
+ */
+export interface GuardVariableReference {
+    state: string | null;
+    tool: string | undefined;
+    arg: string;
+    glob: string;
+    reference: VariableReference;
+}
+/**
+ * Every `${{…}}` reference in the spec's tool-argument guards, with where it was
+ * found. Used at assembly to warn about a reference nothing guarantees, and by
+ * the spec lint for the same check minus the host's seeds.
+ */
+export declare function guardReferences(spec: MachineSpec): GuardVariableReference[];

package/dist/machine/allow.js

@@ -0,0 +1,107 @@
+import picomatch from "picomatch";
+import { canonicalizeRelPath, normalizeRelPath } from "../core/workspace.js";
+import { hasVariableReference, parseReferences, resolveGlob, resolvePath, } from "./variables.js";
+/** Conventional path argument for file tools and `archmax_run`. */
+export const DEFAULT_PATH_ARG = "file_path";
+/**
+ * Whether a value matches any of the given globs. The value is canonicalized
+ * (`.`/`..`/`//` resolved) so a `./` or `.//` prefix cannot dodge a
+ * `forbid_paths` glob — the matcher sees the same path the backend resolves.
+ * Globs are leading-slash-normalized only, preserving their wildcards.
+ *
+ * `dot: true`: a workspace path is not a shell glob, and a governance glob that
+ * skipped dot-prefixed segments would read the same either way — `secrets/**`
+ * would miss `secrets/.env` on the deny side while `scratchpad/**` would refuse
+ * `scratchpad/.cache` on the allow side.
+ */
+export function valueMatches(value, globs) {
+    if (value == null || globs.length === 0)
+        return false;
+    return picomatch.isMatch(canonicalizeRelPath(String(value)).path, globs.map(normalizeRelPath), {
+        dot: true,
+    });
+}
+/**
+ * Normalize an `allow` entry into a tool name plus optional argument matchers.
+ * One shared derivation for the kernel, disclosure, and `validate`, so they
+ * cannot disagree about what an entry covers.
+ */
+export function normalizeAllowEntry(entry) {
+    if (typeof entry === "string")
+        return { tool: entry, argMatchers: null };
+    if (!entry || typeof entry !== "object")
+        return { tool: undefined, argMatchers: null };
+    const tool = entry.tool;
+    if (entry.args && typeof entry.args === "object") {
+        const argMatchers = {};
+        for (const [name, globs] of Object.entries(entry.args)) {
+            argMatchers[name] = Array.isArray(globs) ? globs : [globs];
+        }
+        return { tool, argMatchers };
+    }
+    if (entry.paths !== undefined) {
+        const globs = Array.isArray(entry.paths) ? entry.paths : [entry.paths];
+        return { tool, argMatchers: { [DEFAULT_PATH_ARG]: globs } };
+    }
+    return { tool, argMatchers: null };
+}
+/**
+ * Whether a tool call's arguments satisfy a normalized allow entry's matchers.
+ *
+ * `${{…}}` references are resolved against the run's variables per call, never
+ * cached: a `set_variables` later in the same turn must take effect on the very
+ * next call. An unresolvable reference makes the entry match nothing and reports
+ * why through `onUnresolved` — never the literal `${{…}}` text or a permissive
+ * pattern. A dotted argument key (`args.file_path`) is read with the same
+ * own-property traversal `${{…}}` paths use, never the prototype chain.
+ */
+export function argsSatisfy(argMatchers, args, variables, onUnresolved) {
+    if (!argMatchers)
+        return true;
+    return Object.entries(argMatchers).every(([name, globs]) => {
+        const resolved = [];
+        for (const glob of globs) {
+            if (!hasVariableReference(glob)) {
+                resolved.push(glob);
+                continue;
+            }
+            const result = resolveGlob(glob, variables ?? {});
+            if (!result.ok) {
+                onUnresolved?.({ reference: result.reference, detail: result.detail });
+                return false;
+            }
+            resolved.push(result.pattern);
+        }
+        return valueMatches(resolvePath(args, name.split(".")), resolved);
+    });
+}
+/**
+ * Every `${{…}}` reference in the spec's tool-argument guards, with where it was
+ * found. Used at assembly to warn about a reference nothing guarantees, and by
+ * the spec lint for the same check minus the host's seeds.
+ */
+export function guardReferences(spec) {
+    const found = [];
+    const collect = (entries, state) => {
+        for (const entry of entries ?? []) {
+            const { tool, argMatchers } = normalizeAllowEntry(entry);
+            if (!argMatchers)
+                continue;
+            for (const [arg, globs] of Object.entries(argMatchers)) {
+                for (const glob of globs) {
+                    for (const ref of parseReferences(glob)) {
+                        found.push({ state, tool, arg, glob, reference: ref });
+                    }
+                }
+            }
+        }
+    };
+    collect(spec.tools?.allow_always, null);
+    collect(spec.tools?.forbid_always, null);
+    for (const [slug, state] of Object.entries(spec.states)) {
+        collect(state.tools?.allow, slug);
+        collect(state.tools?.forbid, slug);
+    }
+    return found;
+}
+//# sourceMappingURL=allow.js.map

package/dist/machine/allow.js.map

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