@archmax-ai/harness 0.9.0 → 1.0.0

package/dist/workflow/automated.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Automated states — grader and code states — as the runtime runs them.
+ *
+ * Every model call of a session crosses `wrapModelCall`, the `jumpTo: "model"`
+ * routes that skip `beforeModel` included. So that is where an automated state
+ * is run: when the session's position is a grader or a code state, the call is
+ * **serviced in place of the agent's model** — {@link runAutomatedStep} runs the
+ * state and returns a marker message carrying its outcome — and `afterModel`
+ * strips the marker and commits the outcome ({@link automatedOutcomeOf}). A move
+ * jumps back to the model, where the next state's call is serviced the same way
+ * (an automated state, with no model call), made for real (an agent state), or
+ * spent on a park's handoff (a human state). One step per graph iteration: each
+ * committed as its own checkpointed step, and a runaway cycle bounded by the
+ * session's recursion limit like any runaway turn.
+ *
+ * The outcome rides in the marker, not in memory, so a process that dies
+ * between the model node and `afterModel` replays the commit from the marker.
+ */
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { AIMessage } from "@langchain/core/messages";
+import type { RunnableConfig } from "@langchain/core/runnables";
+import type { StructuredTool } from "@langchain/core/tools";
+import type { WorkflowEventEmitter } from "../core/events.js";
+import type { MountPrefixes } from "../core/mounts.js";
+import type { PricingTable, UsageSummary } from "../core/usage.js";
+import type { WorkflowMachine } from "../machine/machine.js";
+import { type VariableStore } from "../machine/variables.js";
+import type { ScriptExecutor } from "../sandbox/executor.js";
+import type { PtcToolGateway } from "../sandbox/ptc-gateway.js";
+import { type CodeScriptResolver } from "./code-state.js";
+import type { FileValueCheck } from "./signature-checks.js";
+import { type TrailStep } from "./state.js";
+/** An automated state's type. */
+export type AutomatedType = "grader" | "code";
+/**
+ * What one automated run settled as — exactly one of: it advanced (its decision
+ * stood and it finished cleanly), it raised, a terminal state completed, or it
+ * failed (an error, a timeout, a spent budget, or a non-terminal state that
+ * finished undecided).
+ */
+export type AutomatedResult = {
+    kind: "advanced";
+    to: string;
+    reason: string;
+    evidence?: string[];
+} | {
+    kind: "raised";
+    code: string;
+    reason: string;
+} | {
+    kind: "completed";
+} | {
+    kind: "failed";
+    reason: string;
+};
+/** A settled run, as the marker carries it to the commit: serializable, and the whole of what it commits. */
+export interface AutomatedOutcome {
+    state: string;
+    type: AutomatedType;
+    result: AutomatedResult;
+    /** The run's variable writes. */
+    variables?: VariableStore;
+    /** What the run's own model calls cost (a grader's). */
+    usage?: UsageSummary;
+    /** The sub-runs its calls dispatched, as trail steps. */
+    trail?: TrailStep[];
+}
+/** The outcome a marker message carries, when the message is one. */
+export declare function automatedOutcomeOf(message: unknown): AutomatedOutcome | undefined;
+export interface AutomatedStatesContext {
+    machine: WorkflowMachine;
+    emit: WorkflowEventEmitter;
+    mountPrefixes: MountPrefixes;
+    /** Governs every tool an automated state calls, against the live state. */
+    ptcGateway: PtcToolGateway;
+    /** Runs a code state's script, reading it from the authoring backend. */
+    codeExecutor: ScriptExecutor;
+    resolveScript: CodeScriptResolver;
+    /** The model a grader state runs on, and its id when the instance exposes one. */
+    graderModel(state: string): {
+        model: BaseChatModel;
+        id?: string;
+    };
+    pricing?: PricingTable;
+    /** The `file` type's runtime check for a session in a state; omitted, a `file` value is held to its shape alone. */
+    files?: (state: string, variables: VariableStore) => FileValueCheck;
+    /** The sub-runs the session's calls dispatched since the last drain, as trail steps. */
+    dispatchSteps(sessionId: string, state: string): TrailStep[];
+}
+export interface AutomatedStepRequest {
+    sessionId: string;
+    /** The checkpointed session. */
+    session: unknown;
+    /** Every tool the assembly registered, before any state narrows it. */
+    tools: StructuredTool[];
+    /** The turn's config, naming the calling state. */
+    config: RunnableConfig;
+    signal?: AbortSignal;
+}
+/**
+ * Run the automated state the session stands in — one step — and return the
+ * marker message standing in for the model call that was not made.
+ *
+ * The state is offered exactly its surface (`disclosedTools`): the registered
+ * tools it names, minus the agent's control declarations, plus its own controls
+ * bound to this run's recorder — every one wrapped by the gateway, whose live
+ * context is pointed at this state first. Narrative events are emitted once the
+ * run has settled, so nothing announces a move the run's error then discarded.
+ */
+export declare function runAutomatedStep(ctx: AutomatedStatesContext, request: AutomatedStepRequest): Promise<AIMessage>;
+/** The runtime note an automated move or raise leaves for the session to read. */
+export declare function automatedNoteText(outcome: AutomatedOutcome): string | undefined;

package/dist/workflow/automated.js

@@ -0,0 +1,163 @@
+import { AIMessage } from "@langchain/core/messages";
+import { v4 as uuidv4 } from "@langchain/core/utils/uuid";
+import { TRIGGER_VARIABLE } from "../machine/variables.js";
+import { createAutomatedControls, createStepRecorder } from "./automated-controls.js";
+import { runCodeState } from "./code-state.js";
+import { runGraderState } from "./grader-state.js";
+import { sessionHistory } from "./history.js";
+import { reportAdvance } from "./move-events.js";
+import { currentWorkflowState, readVariables, readWorkflowState } from "./state.js";
+/** Where the marker message carries its outcome. */
+const AUTOMATED_STEP_KEY = "archmax_automated_step";
+/** The outcome a marker message carries, when the message is one. */
+export function automatedOutcomeOf(message) {
+    const kwargs = message?.additional_kwargs;
+    const outcome = kwargs?.[AUTOMATED_STEP_KEY];
+    return outcome && typeof outcome === "object" ? outcome : undefined;
+}
+/** The variables as a script reads them: a flat `name → value` map. */
+function flatVariables(store) {
+    return Object.fromEntries(Object.entries(store).map(([name, entry]) => [name, entry.value]));
+}
+/** How a run settles, from its decision and whether it finished cleanly. */
+function settle(machine, state, type, decision, error) {
+    // A raise ends the session whatever the run did next; an error discards a move.
+    if (decision?.kind === "raise")
+        return { kind: "raised", code: decision.code, reason: decision.reason };
+    if (error !== undefined)
+        return { kind: "failed", reason: error };
+    if (decision?.kind === "advance") {
+        return {
+            kind: "advanced",
+            to: decision.to,
+            reason: decision.reason,
+            ...(decision.evidence.length > 0 ? { evidence: decision.evidence } : {}),
+        };
+    }
+    if (machine.isTerminal(state))
+        return { kind: "completed" };
+    return {
+        kind: "failed",
+        reason: `${type} state '${state}' finished without calling archmax_advance or archmax_raise`,
+    };
+}
+/**
+ * Run the automated state the session stands in — one step — and return the
+ * marker message standing in for the model call that was not made.
+ *
+ * The state is offered exactly its surface (`disclosedTools`): the registered
+ * tools it names, minus the agent's control declarations, plus its own controls
+ * bound to this run's recorder — every one wrapped by the gateway, whose live
+ * context is pointed at this state first. Narrative events are emitted once the
+ * run has settled, so nothing announces a move the run's error then discarded.
+ */
+export async function runAutomatedStep(ctx, request) {
+    const { machine, emit } = ctx;
+    const { sessionId, session, config } = request;
+    const state = currentWorkflowState(session, machine.entry);
+    const type = machine.isGraderState(state) ? "grader" : "code";
+    const declared = machine.spec.states[state];
+    const refresh = (variables) => ctx.ptcGateway.refresh(sessionId, { state, config, replyOnly: false, variables });
+    refresh(readVariables(session));
+    const recorder = createStepRecorder(state, session, refresh);
+    const history = sessionHistory(session);
+    const surface = machine.disclosedTools(state);
+    const controls = machine.controlTools(state);
+    const own = request.tools.filter((tool) => surface.has(tool.name) && !controls.has(tool.name));
+    const tools = ctx.ptcGateway.wrap([...own, ...createAutomatedControls(ctx, recorder, history)], { origin: type === "grader" ? "agent" : "script", sessionId });
+    const startedAt = Date.now();
+    let error;
+    let usage;
+    if (type === "code") {
+        emit({ type: "code-start", state, script: declared?.script ?? "" });
+        const trigger = readWorkflowState(session).trigger?.id;
+        const input = { state, ...(trigger ? { trigger } : {}), variables: flatVariables(recorder.store()) };
+        ({ error } = await runCodeState({
+            emit,
+            executor: ctx.codeExecutor,
+            resolveScript: ctx.resolveScript,
+            sessionId,
+            state,
+            script: declared?.script ?? "",
+            input,
+            tools,
+            surface: [...surface],
+            ...(request.signal ? { signal: request.signal } : {}),
+        }));
+    }
+    else {
+        emit({ type: "grader-start", state });
+        const { model, id } = ctx.graderModel(state);
+        ({ error, usage } = await runGraderState({
+            machine,
+            emit,
+            ...(ctx.pricing ? { pricing: ctx.pricing } : {}),
+            state,
+            model,
+            ...(id ? { modelId: id } : {}),
+            tools,
+            recorder,
+            ...(request.signal ? { signal: request.signal } : {}),
+        }));
+    }
+    const decision = recorder.decision;
+    const result = settle(machine, state, type, decision, error);
+    const failed = result.kind === "failed";
+    emit({
+        type: type === "code" ? "code-result" : "grader-result",
+        state,
+        status: failed ? "error" : "ok",
+        durationMs: Date.now() - startedAt,
+        ...(failed ? { reason: result.reason } : {}),
+    });
+    if (result.kind === "advanced") {
+        reportAdvance(emit, sessionId, {
+            from: state,
+            to: result.to,
+            reason: result.reason,
+            ...(decision?.callId ? { callId: decision.callId } : {}),
+            parks: machine.isHumanState(result.to),
+        });
+    }
+    else if (result.kind === "raised") {
+        emit({
+            type: "raised",
+            state,
+            sessionId,
+            code: result.code,
+            reason: result.reason,
+            ...(decision?.callId ? { callId: decision.callId } : {}),
+        });
+        // The session leaves the state it failed in as a completing one does; nothing is entered.
+        emit({ type: "state-leave", state, next: state });
+    }
+    // The built-in `trigger` is the turn's, set at its boundary: never a run's write.
+    const { [TRIGGER_VARIABLE]: _trigger, ...variables } = recorder.delta;
+    const trail = ctx.dispatchSteps(sessionId, state);
+    const outcome = {
+        state,
+        type,
+        result,
+        ...(Object.keys(variables).length > 0 ? { variables } : {}),
+        ...(usage ? { usage } : {}),
+        ...(trail.length > 0 ? { trail } : {}),
+    };
+    return new AIMessage({
+        content: "",
+        id: `automated_${uuidv4()}`,
+        additional_kwargs: { [AUTOMATED_STEP_KEY]: outcome },
+    });
+}
+/** The runtime note an automated move or raise leaves for the session to read. */
+export function automatedNoteText(outcome) {
+    const { state, type, result } = outcome;
+    const who = type === "grader" ? `The '${state}' grader` : `'${state}'`;
+    if (result.kind === "advanced") {
+        return `[${type}] ${who} moved the run to '${result.to}': ${result.reason}. You are now in '${result.to}'.`;
+    }
+    if (result.kind === "raised") {
+        return `[${type}] ${who} ended the session as failed ('${result.code}'): ${result.reason}`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=automated.js.map

package/dist/workflow/automated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automated.js","sourceRoot":"","sources":["../../src/workflow/automated.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAGrD,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAK1D,OAAO,EAAE,gBAAgB,EAAsB,MAAM,yBAAyB,CAAC;AAG/E,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAA0B,MAAM,yBAAyB,CAAC;AAC9G,OAAO,EAAE,YAAY,EAA2B,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAkB,MAAM,YAAY,CAAC;AA8BpG,oDAAoD;AACpD,MAAM,kBAAkB,GAAG,wBAAwB,CAAC;AAEpD,qEAAqE;AACrE,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,MAAM,GAAI,OAAuE,EAAE,iBAAiB,CAAC;IAC3G,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,kBAAkB,CAAC,CAAC;IAC7C,OAAO,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAE,OAA4B,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5F,CAAC;AA+BD,uEAAuE;AACvE,SAAS,aAAa,CAAC,KAAoB;IACzC,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED,4EAA4E;AAC5E,SAAS,MAAM,CACb,OAAwB,EACxB,KAAa,EACb,IAAmB,EACnB,QAAuC,EACvC,KAAyB;IAEzB,gFAAgF;IAChF,IAAI,QAAQ,EAAE,IAAI,KAAK,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IACxG,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAClE,IAAI,QAAQ,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC5D,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,GAAG,IAAI,WAAW,KAAK,6DAA6D;KAC7F,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAA2B,EAAE,OAA6B;IAC/F,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC;IAC9B,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC/C,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAkB,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7E,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAG,CAAC,SAAwB,EAAE,EAAE,CAC3C,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IACpF,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAExC,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/F,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAC/B,CAAC,GAAG,GAAG,EAAE,GAAG,uBAAuB,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,EAC5D,EAAE,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,CAC9D,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,KAAyB,CAAC;IAC9B,IAAI,KAA+B,CAAC;IACpC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC;QACpE,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;QACrG,CAAC,EAAE,KAAK,EAAE,GAAG,MAAM,YAAY,CAAC;YAC9B,IAAI;YACJ,QAAQ,EAAE,GAAG,CAAC,YAAY;YAC1B,aAAa,EAAE,GAAG,CAAC,aAAa;YAChC,SAAS;YACT,KAAK;YACL,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE;YAC9B,KAAK;YACL,KAAK;YACL,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC;YACrB,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD,CAAC,CAAC,CAAC;IACN,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;QACtC,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC;YACvC,OAAO;YACP,IAAI;YACJ,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,KAAK;YACL,KAAK;YACL,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9B,KAAK;YACL,QAAQ;YACR,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD,CAAC,CAAC,CAAC;IACN,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC;IACxC,IAAI,CAAC;QACH,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe;QACvD,KAAK;QACL,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;QAC/B,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;QAClC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7C,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE;YAC7B,IAAI,EAAE,KAAK;YACX,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;SACvC,CAAC,CAAC;IACL,CAAC;SAAM,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,IAAI,EAAE,QAAQ;YACd,KAAK;YACL,SAAS;YACT,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC,CAAC;QACH,0FAA0F;QAC1F,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,kFAAkF;IAClF,MAAM,EAAE,CAAC,gBAAgB,CAAC,EAAE,QAAQ,EAAE,GAAG,SAAS,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC;IACtE,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,OAAO,GAAqB;QAChC,KAAK;QACL,IAAI;QACJ,MAAM;QACN,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvC,CAAC;IACF,OAAO,IAAI,SAAS,CAAC;QACnB,OAAO,EAAE,EAAE;QACX,EAAE,EAAE,aAAa,MAAM,EAAE,EAAE;QAC3B,iBAAiB,EAAE,EAAE,CAAC,kBAAkB,CAAC,EAAE,OAAO,EAAE;KACrD,CAAC,CAAC;AACL,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,OAAyB;IACzD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC;IACvE,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,IAAI,IAAI,KAAK,GAAG,sBAAsB,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,qBAAqB,MAAM,CAAC,EAAE,IAAI,CAAC;IAC9G,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,IAAI,KAAK,GAAG,kCAAkC,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC;IAC7F,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/workflow/code-state.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A code state's run: its `script`, read from the authoring backend, evaluated
+ * in the sandbox with its state's input and its state's tools — nothing else.
+ *
+ * The run decides nothing here: the script moves the session through
+ * `tools.archmax_advance` or ends it through `tools.archmax_raise`, which the
+ * step recorder holds, and the orchestrator (`automated.ts`) reads the outcome
+ * from that record and from whether the script finished cleanly.
+ */
+import type { StructuredTool } from "@langchain/core/tools";
+import type { WorkflowEventEmitter } from "../core/events.js";
+import type { ScriptExecutor } from "../sandbox/executor.js";
+/** Resolves a code state's declared `script` to its authoring-backend path, or refuses it with a reason. */
+export type CodeScriptResolver = (declared: string) => {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface CodeStateRun {
+    emit: WorkflowEventEmitter;
+    /** The executor reading sources from the authoring backend. */
+    executor: ScriptExecutor;
+    resolveScript: CodeScriptResolver;
+    sessionId: string;
+    state: string;
+    /** The state's declared `script`. */
+    script: string;
+    /** The script's input: `{ state, trigger?, variables }`. */
+    input: Record<string, unknown>;
+    /** The code state's tools, governed. */
+    tools: StructuredTool[];
+    /** The names those tools are listed and reached by. */
+    surface: readonly string[];
+    signal?: AbortSignal;
+}
+/**
+ * Run a code state's script. Settles with the error that stopped it, if one did
+ * — a script that cannot be placed or read, a foreign import, a throw, a
+ * timeout, a cancelled turn — and with nothing when it ran to its end. Each
+ * console line is reported as it was logged.
+ */
+export declare function runCodeState(run: CodeStateRun): Promise<{
+    error?: string;
+}>;

package/dist/workflow/code-state.js

@@ -0,0 +1,26 @@
+/**
+ * Run a code state's script. Settles with the error that stopped it, if one did
+ * — a script that cannot be placed or read, a foreign import, a throw, a
+ * timeout, a cancelled turn — and with nothing when it ran to its end. Each
+ * console line is reported as it was logged.
+ */
+export async function runCodeState(run) {
+    const resolved = run.resolveScript(run.script);
+    if (!resolved.ok)
+        return { error: resolved.reason };
+    const outcome = await run.executor.runCodeState(resolved.path, {
+        sessionId: run.sessionId,
+        args: run.input,
+        tools: run.tools,
+        surface: run.surface,
+        ...(run.signal ? { signal: run.signal } : {}),
+    });
+    for (const line of outcome.logs) {
+        if (line.trim())
+            run.emit({ type: "code-output", state: run.state, line: line.trimEnd() });
+    }
+    if (outcome.ok)
+        return {};
+    return { error: outcome.error?.message ?? "the script failed" };
+}
+//# sourceMappingURL=code-state.js.map

package/dist/workflow/code-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-state.js","sourceRoot":"","sources":["../../src/workflow/code-state.ts"],"names":[],"mappings":"AAkCA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAiB;IAClD,MAAM,QAAQ,GAAG,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IACpD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE;QAC7D,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,IAAI,EAAE,GAAG,CAAC,KAAK;QACf,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC,CAAC;IACH,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,EAAE;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IAC1B,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,IAAI,mBAAmB,EAAE,CAAC;AAClE,CAAC"}

package/dist/workflow/control-tools.d.ts

@@ -1,23 +1,25 @@
 /**
  * The control tools: `archmax_advance`, `archmax_wait`, `archmax_reset`,
- * `archmax_raise`, `archmax_get_variables`, `archmax_set_variables`.
+ * `archmax_raise`, `archmax_get_variables`, `archmax_set_variables` — and
+ * `archmax_get_history`, which only a grader state is offered.
  *
  * Each is a declaration whose body never runs in a wired assembly: governance
- * intercepts the call in `wrapToolCall`, where checkpointed state is in hand, and
- * services it with the handler here. A handler returns the tool message the
- * model reads and, when the call changed the run, the `Command` committing it.
+ * intercepts the session's agent's call in `wrapToolCall`, where checkpointed
+ * state is in hand, and services it with the handler here. A handler returns the
+ * tool message the model reads and, when the call changed the run, the `Command`
+ * committing it. An automated state's controls (`automated-controls.ts`) reuse
+ * the same schemas, handlers and {@link transitionUpdate}.
  */
 import { ToolMessage } from "@langchain/core/messages";
 import type { StructuredTool } from "@langchain/core/tools";
 import { Command } from "@langchain/langgraph";
 import { z } from "zod";
 import { type MountPrefixes } from "../core/zones.js";
-import type { LifecycleContext, LifecycleRunner } from "../lifecycle/runner.js";
 import type { WorkflowMachine } from "../machine/machine.js";
 import { ADVANCE_TOOL, GET_VARIABLES_TOOL, RAISE_TOOL, RESET_TOOL, SET_VARIABLES_TOOL, WAIT_TOOL } from "../machine/tool-names.js";
 import { type UnresolvedGlob, type VariableStore } from "../machine/variables.js";
 import { type FileValueCheck } from "./signature-checks.js";
-import { type PendingDecision, type PendingInput, type RaiseRecord, type WorkflowStateFields } from "./state.js";
+import { type MoveKind, type PendingDecision, type PendingInput, type RaiseRecord, type WorkflowStateFields, type WorkflowUpdate } from "./state.js";
 export { ADVANCE_TOOL, GET_VARIABLES_TOOL, RAISE_TOOL, RESET_TOOL, SET_VARIABLES_TOOL, WAIT_TOOL };
 /** The one refusal shape: an error-status tool message, so the model self-corrects and a view classifies it. */
 export declare function refusal(name: string, toolCallId: string, text: string): ToolMessage;
@@ -71,36 +73,66 @@ export declare const setVariablesSchema: z.ZodObject<{
 export declare function createControlTools(opts?: {
     child?: boolean;
 }): StructuredTool[];
+/** One move along a declared edge, as a trail step and a park will record it. */
+export interface Move {
+    to: string;
+    /** Who moved the session: its agent, a grader state or a code state. */
+    kind: MoveKind;
+    reason: string;
+    /** Attached evidence paths, already validated; only into a human state. */
+    evidence?: readonly string[];
+}
+/**
+ * The update a move commits — the target position, the trail step, a cleared
+ * rejection marker and a fresh turn budget — plus, into a human state, the park
+ * record opened in its closing phase. The one derivation every mover shares: the
+ * session's agent through {@link handleAdvance}, and an automated state's run.
+ * Messages are the caller's (a tool reply, a runtime note).
+ */
+export declare function transitionUpdate(machine: WorkflowMachine, state: unknown, move: Move): {
+    update: WorkflowUpdate;
+    park?: PendingDecision;
+};
+/**
+ * Why `from` may not be left for `to` right now, or `undefined` when it may: the
+ * kernel's transition verdict — the state's `requires` against `variables`, then
+ * the declared edge. Every refusal is recoverable: the mover sets what is owed,
+ * or picks a valid target.
+ */
+export declare function transitionRefusal(machine: WorkflowMachine, from: string, to: string, variables: VariableStore): string | undefined;
+/**
+ * Evidence an advance attaches, validated for the target: accepted only into a
+ * human state, and only paths the session itself could read.
+ */
+export declare function advanceEvidence(machine: WorkflowMachine, to: string, attached: readonly string[], mounts?: MountPrefixes): EvidenceValidation;
 export interface AdvanceRequest {
     /** Tool call id, echoed on the resulting ToolMessage. */
     toolCallId: string;
-    /** The id this call is reported under on the event stream (the provider's, else the generated fallback). */
-    callId?: string;
     args: Record<string, unknown>;
     /** Checkpointed agent state at the time of the call. */
     state: unknown;
-    /** Lifecycle context; its `iterations` are seeded from state and committed back. */
-    ctx: LifecycleContext;
 }
 export interface AdvanceOutcome {
     message: Command | ToolMessage;
     moved?: {
         from: string;
         to: string;
+        reason: string;
         /** The decision record committed when `to` is a human state. */
         park?: PendingDecision;
     };
 }
 /**
- * Attempt a transition and commit the outcome: `workflowState` and the `agent`
- * trail step on success, `iterations` always, and — into a human state —
- * the pending-decision record with the park opened in its closing phase.
+ * Service the session's agent's `archmax_advance`: validate the arguments, the
+ * evidence and the transition, then commit {@link transitionUpdate} with the
+ * reply the agent reads. A refusal leaves the session exactly where it was — no
+ * trail step — and replies without erroring the message, so the agent corrects
+ * the call rather than reading a failed run.
  */
 export declare function handleAdvance(opts: {
     machine: WorkflowMachine;
-    lifecycle: LifecycleRunner;
     mountPrefixes?: MountPrefixes;
-}, request: AdvanceRequest): Promise<AdvanceOutcome>;
+}, request: AdvanceRequest): AdvanceOutcome;
 /** The accepted `until` forms, quoted verbatim in every rejection. */
 export declare const WAIT_UNTIL_FORMS: string;
 export type WaitUntilResult = {
@@ -150,9 +182,9 @@ export interface ResetOutcome {
     };
 }
 /**
- * Service a reset: move back to the entry state and clear what gates progress
- * (correction budgets, `beforeDone`). Evidence — messages, files, variables, the
- * trail — is left alone: a reset moves the machine, not the history.
+ * Service a reset: move back to the entry state. Evidence — messages, files,
+ * variables, the trail — is left alone: a reset moves the machine, not the
+ * history.
  */
 export declare function handleReset(machine: WorkflowMachine, request: ResetRequest): ResetOutcome;
 export interface RaiseRequest {
@@ -170,9 +202,9 @@ export interface RaiseOutcome {
  * Service a raise: end the session as a failure in the state it was called in.
  * Commits the record and `status: failed`, and drops a pending rejection — the
  * agent's own account of the failure is what the session ends with. The turn
- * ends at the next model hook; nothing routes and no hook runs. Refused, with the
- * session left in place, for invalid arguments or a message making other calls:
- * those run concurrently, so a raise beside them could not mean one thing.
+ * ends at the next model hook; nothing routes and nothing further runs. Refused,
+ * with the session left in place, for invalid arguments or a message making other
+ * calls: those run concurrently, so a raise beside them could not mean one thing.
  */
 export declare function handleRaise(machine: WorkflowMachine, request: RaiseRequest): RaiseOutcome;
 export interface VariableToolRequest {
@@ -209,8 +241,7 @@ fileRefusal?: string): SetVariablesOutcome;
 export declare function fileReturnsRefusal(machine: WorkflowMachine, state: unknown, args: Record<string, unknown>, check: FileValueCheck): Promise<string | undefined>;
 /** Wrap an `archmax_set_variables` outcome as the update that commits its delta. */
 export declare function setVariablesCommand(outcome: SetVariablesOutcome): Command | ToolMessage;
-/** The variables a state still owes before it may be left — its `requires` minus what is set. */
-export declare function unmetRequirements(required: string[], store: VariableStore): string[];
+export { unmetRequirements } from "../kernel/kernel.js";
 /**
  * The wording for a `${{…}}` reference in the agent's own tool arguments that
  * could not be resolved: a correctable refusal carrying the two fixes it might