@archmax-ai/harness 0.0.0

package/dist/workflow/state.d.ts

@@ -0,0 +1,347 @@
+import { z } from "zod";
+import { type UsageSummary } from "../core/usage.js";
+import type { VariableStore } from "../machine/variables.js";
+/**
+ * The checkpointed workflow channels, carried beside `messages` on the one
+ * compiled graph. The governance middleware is the only writer.
+ *
+ * **Every hook echoes the whole state.** A middleware hook returns
+ * `{ ...state, ...result }`, so a hook that touches one field rewrites every
+ * other with the value it read. Every accumulating reducer here is therefore
+ * idempotent on an echo — folding the value it already holds changes nothing —
+ * and that property is what the reducer tests pin.
+ */
+/** The pending-decision record for a session parked at a human state; the machine-authoritative source for presenting it. */
+export declare const pendingDecisionSchema: z.ZodObject<{
+    state: z.ZodString;
+    node: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    seq: z.ZodNumber;
+    transitions: z.ZodArray<z.ZodObject<{
+        to: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodEnum<{
+            approve: "approve";
+            reject: "reject";
+            refine: "refine";
+            none: "none";
+        }>>;
+    }, z.core.$strip>>;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type PendingDecision = z.infer<typeof pendingDecisionSchema>;
+/** The pending-input record for a session parked with `archmax_wait`; a delivery resumes the parked state itself. */
+export declare const pendingInputSchema: z.ZodObject<{
+    state: z.ZodString;
+    node: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    reason: z.ZodString;
+    parkedAt: z.ZodString;
+    resumeAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PendingInput = z.infer<typeof pendingInputSchema>;
+/**
+ * A delegation call whose sub-run parked. The head of the list is the decision
+ * the session currently shows; the run parks again while any remain.
+ */
+export declare const pendingDelegationSchema: z.ZodObject<{
+    state: z.ZodString;
+    node: z.ZodString;
+    workflow: z.ZodString;
+    toolCallId: z.ZodString;
+    identity: z.ZodString;
+    dispatchId: z.ZodString;
+    decision: z.ZodUnion<readonly [z.ZodObject<{
+        state: z.ZodString;
+        node: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        seq: z.ZodNumber;
+        transitions: z.ZodArray<z.ZodObject<{
+            to: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodEnum<{
+                approve: "approve";
+                reject: "reject";
+                refine: "refine";
+                none: "none";
+            }>>;
+        }, z.core.$strip>>;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodString;
+        node: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+        parkedAt: z.ZodString;
+        resumeAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>;
+/**
+ * Whether a delegated child's park is a decision rather than a wait. Told apart
+ * structurally, on the field only a decision carries, so a checkpoint written
+ * before the union widened still reads correctly.
+ */
+export declare function isDecisionPark(park: PendingDelegation["decision"] | null | undefined): park is PendingDecision;
+export type PendingDelegation = z.infer<typeof pendingDelegationSchema>;
+/** The state a park record names, across both spellings. */
+export declare function parkedStateOf(record: {
+    state?: string;
+    node?: string;
+} | null | undefined): string;
+/** Which channel a suspended run awaits: a person's `decision`, or external `input`. */
+export type ParkChannel = "decision" | "input";
+/**
+ * Where a park stands: `closing` — the record is committed and the run owes one
+ * tool-free message before it suspends; `suspend` — the next hook site suspends
+ * the session; `null` — no park in progress.
+ */
+export declare const parkPhaseSchema: z.ZodEnum<{
+    closing: "closing";
+    suspend: "suspend";
+}>;
+/** Model calls made in `state` since it was entered; `budget.maxTurns` is enforced against the visit. */
+export declare const stateTurnsSchema: z.ZodObject<{
+    state: z.ZodString;
+    count: z.ZodNumber;
+}, z.core.$strip>;
+export declare const TRAIL_STEP_KINDS: readonly ["trigger", "agent", "human", "sub-workflow", "reset", "on_error"];
+/** One committed traversal step: the state entered, the kind of edge, and the rationale when given. */
+export declare const trailStepSchema: z.ZodObject<{
+    to: z.ZodString;
+    kind: z.ZodEnum<{
+        human: "human";
+        trigger: "trigger";
+        agent: "agent";
+        "sub-workflow": "sub-workflow";
+        reset: "reset";
+        on_error: "on_error";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+    workflow: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+    }>>;
+    ts: z.ZodNumber;
+}, z.core.$strip>;
+export type TrailStep = z.infer<typeof trailStepSchema>;
+/** One run variable as checkpointed. Locking is monotonic. */
+export declare const variableEntrySchema: z.ZodObject<{
+    value: z.ZodUnknown;
+    locked: z.ZodBoolean;
+    reseed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** The run's usage as persisted — structurally identical to {@link UsageSummary} (guarded below). */
+export declare const usageSummarySchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodNumber;
+    cacheCreationTokens: z.ZodNumber;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** The workflow fields persisted in the checkpointer alongside `messages`. */
+declare const workflowStateFields: {
+    /** The machine's position. */
+    workflowState: z.ZodOptional<z.ZodString>;
+    /** Why the current turn was rejected; cleared on every transition and turn. */
+    rejected: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    iterations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    beforeDone: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    /** The trigger that started (or last resumed) this run. Its input lives in `variables`. */
+    trigger: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>>;
+    /** The state this run began in. Written once, so the reset tool has a fixed target. */
+    entryState: z.ZodOptional<z.ZodString>;
+    /** Hash of the machine spec the session last ran under. Introspection only, never a guard. */
+    specHash: z.ZodOptional<z.ZodString>;
+    /** Coarse lifecycle status; see {@link WORKFLOW_STATUSES}. */
+    status: z.ZodOptional<z.ZodString>;
+    /** The pending decision — the run's own, or a delegated child's. Cleared on decision. */
+    pendingDecision: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        state: z.ZodString;
+        node: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        seq: z.ZodNumber;
+        transitions: z.ZodArray<z.ZodObject<{
+            to: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodEnum<{
+                approve: "approve";
+                reject: "reject";
+                refine: "refine";
+                none: "none";
+            }>>;
+        }, z.core.$strip>>;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>>;
+    /** Monotonic count of human decisions this session has parked on. */
+    decisionCount: z.ZodOptional<z.ZodNumber>;
+    /** The pending input for a session parked with `archmax_wait`. Cleared on delivery. */
+    pendingInput: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        state: z.ZodString;
+        node: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+        parkedAt: z.ZodString;
+        resumeAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    /** Sub-runs waiting on a person, in presentation order. */
+    pendingDelegations: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        state: z.ZodString;
+        node: z.ZodString;
+        workflow: z.ZodString;
+        toolCallId: z.ZodString;
+        identity: z.ZodString;
+        dispatchId: z.ZodString;
+        decision: z.ZodUnion<readonly [z.ZodObject<{
+            state: z.ZodString;
+            node: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            seq: z.ZodNumber;
+            transitions: z.ZodArray<z.ZodObject<{
+                to: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                type: z.ZodOptional<z.ZodEnum<{
+                    approve: "approve";
+                    reject: "reject";
+                    refine: "refine";
+                    none: "none";
+                }>>;
+            }, z.core.$strip>>;
+            evidence: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            createdAt: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            state: z.ZodString;
+            node: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            reason: z.ZodString;
+            parkedAt: z.ZodString;
+            resumeAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>;
+    }, z.core.$strip>>>>;
+    parkPhase: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        closing: "closing";
+        suspend: "suspend";
+    }>>>;
+    /**
+     * This model call is a reply-only turn: no tools, one text reply. Set by both
+     * park moments (the closing turn and a reply to a parked session) so
+     * disclosure and governance read one condition. Cleared when spent.
+     */
+    replyOnly: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    /** Parks per state, keyed by slug — what `budget.maxParks` is enforced against. */
+    parkCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    stateTurns: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        state: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$strip>>>;
+    /** Ordered audit trail. Accumulates: a writer sends only the steps it adds. */
+    auditTrail: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        to: z.ZodString;
+        kind: z.ZodEnum<{
+            human: "human";
+            trigger: "trigger";
+            agent: "agent";
+            "sub-workflow": "sub-workflow";
+            reset: "reset";
+            on_error: "on_error";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+        workflow: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+        }>>;
+        ts: z.ZodNumber;
+    }, z.core.$strip>>>;
+    /**
+     * Cumulative token usage (and cost). A last-value channel: the one writer adds
+     * its delta to the total it reads, because an additive reducer cannot tell a
+     * hook echoing the total from a delta that happens to equal it.
+     */
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cacheReadTokens: z.ZodNumber;
+        cacheCreationTokens: z.ZodNumber;
+        costUsd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    /** The run's variables, keyed by name. The channel merges, so a writer sends only its delta. */
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        value: z.ZodUnknown;
+        locked: z.ZodBoolean;
+        reseed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+};
+export type WorkflowStateFields = z.infer<z.ZodObject<typeof workflowStateFields>>;
+/**
+ * Merge a variable delta into the store: a host seeding boundary (`reseed`)
+ * replaces anything, a locked entry is otherwise kept, any other write replaces.
+ * Only runtime-owned boundaries set the marker (never the variable tools), so no
+ * agent-reachable write breaks a lock. Folding a store onto itself changes nothing.
+ */
+export declare function mergeVariables(acc: VariableStore, update: VariableStore): VariableStore;
+/** Mark a delta as written at a host seeding boundary (a turn's opening, a delivery), so it replaces even a locked entry. */
+export declare function reseedAll(delta: VariableStore): VariableStore;
+/**
+ * The trail's fold: an update equal to the list held is a hook's echo (no-op);
+ * an update extending it replaces it; anything else (a tool seam sending only
+ * its own steps, two of them in one super-step) is appended.
+ */
+export declare function foldTrail(acc: TrailStep[] | undefined, update: TrailStep[] | undefined): TrailStep[];
+/**
+ * A `pendingDelegations` update: records to add (union by identity, so a hook's
+ * echo is a no-op), `null` to clear, or `{ remaining }` — the list after a
+ * decision resolved its head.
+ */
+export type PendingDelegationsUpdate = PendingDelegation[] | null | {
+    remaining: PendingDelegation[];
+};
+export declare function foldPendingDelegations(acc: PendingDelegation[] | null | undefined, update: PendingDelegationsUpdate | undefined): PendingDelegation[];
+/**
+ * The graph's and the middleware's `stateSchema`, with the accumulating
+ * channels' reducers applied. Without the wrap every field is last-value, and a
+ * tool committing a delta from inside a batch would replace the channel.
+ */
+export declare const workflowStateSchema: z.ZodObject<typeof workflowStateFields>;
+/** The checkpointed variable store; a checkpoint predating the field reads as empty. */
+export declare function readVariables(state: unknown): VariableStore;
+/** What a completed run returned, by declared name; `undefined` when nothing is declared. */
+export declare function readReturns(state: unknown, declared: string[] | undefined): Record<string, unknown> | undefined;
+/** Coarse session lifecycle values written to {@link WorkflowStateFields.status}. */
+export declare const WORKFLOW_STATUSES: {
+    readonly running: "running";
+    readonly completed: "completed";
+    readonly rejected: "rejected";
+    readonly awaitingDecision: "awaiting_decision";
+    readonly awaitingInput: "awaiting_input";
+};
+export type WorkflowStatus = (typeof WORKFLOW_STATUSES)[keyof typeof WORKFLOW_STATUSES];
+/** The statuses of a run that is over; a parked session is open. */
+export declare const FINISHED_STATUSES: ReadonlySet<string>;
+export type SessionClassification = "finished" | "open";
+export declare function isFinished(status: string | undefined): boolean;
+export declare function classifyStatus(status: string | undefined): SessionClassification;
+/** The checkpointed usage totals; a checkpoint predating the field reads as zeroed. */
+export declare function readRunUsage(state: unknown): UsageSummary;
+export declare function readAuditTrail(state: unknown): TrailStep[];
+export declare function readWorkflowState(state: unknown): WorkflowStateFields;
+export declare function currentWorkflowState(state: unknown, fallback: string): string;
+/** One reader for disclosure, the prompt section and the kernel, so a parked run cannot be disclosed one way and governed another. */
+export declare function isReplyOnly(state: unknown): boolean;
+/** What a hook or a serviced tool call commits: a channel delta, appended messages, and where the loop goes next. */
+export type WorkflowUpdate = Partial<Omit<WorkflowStateFields, "pendingDelegations">> & {
+    pendingDelegations?: PendingDelegationsUpdate;
+    messages?: unknown[];
+    jumpTo?: "model" | "end";
+};
+/** The park record a session currently holds, on either channel, or `null`. */
+export declare function pendingParkOf(state: unknown): {
+    channel: ParkChannel;
+    record: PendingDecision | PendingInput;
+} | null;
+export {};

package/dist/workflow/state.js

@@ -0,0 +1,322 @@
+import { withLangGraph } from "@langchain/langgraph/zod";
+import { z } from "zod";
+import { emptyUsage } from "../core/usage.js";
+/**
+ * The checkpointed workflow channels, carried beside `messages` on the one
+ * compiled graph. The governance middleware is the only writer.
+ *
+ * **Every hook echoes the whole state.** A middleware hook returns
+ * `{ ...state, ...result }`, so a hook that touches one field rewrites every
+ * other with the value it read. Every accumulating reducer here is therefore
+ * idempotent on an echo — folding the value it already holds changes nothing —
+ * and that property is what the reducer tests pin.
+ */
+// --- Park records ------------------------------------------------------------
+/** The pending-decision record for a session parked at a human state; the machine-authoritative source for presenting it. */
+export const pendingDecisionSchema = z.object({
+    /** Slug of the human state the session is parked at — the resume routes against this. */
+    state: z.string(),
+    /** @deprecated Older spelling of {@link state}; read from checkpoints written before the rename. */
+    node: z.string(),
+    /** The parked state's `title`, when declared. A label, never a routing target. */
+    title: z.string().optional(),
+    /** 1-based ordinal of this decision within the session. */
+    seq: z.number(),
+    /** The selectable outgoing transitions. */
+    transitions: z.array(z.object({
+        to: z.string(),
+        description: z.string().optional(),
+        type: z.enum(["approve", "reject", "refine", "none"]).optional(),
+    })),
+    /** Evidence artifacts surfaced to the person (agent-visible run paths). */
+    evidence: z.array(z.string()).optional(),
+    createdAt: z.string(),
+});
+/** The pending-input record for a session parked with `archmax_wait`; a delivery resumes the parked state itself. */
+export const pendingInputSchema = z.object({
+    /** Slug of the state the session is parked in — the state a delivery resumes. */
+    state: z.string(),
+    /** @deprecated Older spelling of {@link state}; read from checkpoints written before the rename. */
+    node: z.string(),
+    title: z.string().optional(),
+    /** Why the agent is waiting, in its own words. */
+    reason: z.string(),
+    parkedAt: z.string(),
+    /** When the run asked to be resumed (absolute). A hint for whoever schedules — the runtime holds no timer. */
+    resumeAt: z.string().optional(),
+});
+/**
+ * A delegation call whose sub-run parked. The head of the list is the decision
+ * the session currently shows; the run parks again while any remain.
+ */
+export const pendingDelegationSchema = z.object({
+    /** The state that made the call — where the run parks, and resumes. */
+    state: z.string(),
+    /** @deprecated Older spelling of {@link state}; read from checkpoints written before the rename. */
+    node: z.string(),
+    workflow: z.string(),
+    /** The tool call this sub-run answers. */
+    toolCallId: z.string(),
+    /** The sub-run's identity (`<state>:<workflow>:<ordinal>`); the child's session id derives from it. */
+    identity: z.string(),
+    dispatchId: z.string(),
+    /**
+     * The child's own park, presented to the person unchanged — a decision when it
+     * parked at a human state, an input park when it called `archmax_wait`. The
+     * parent parks on whichever channel the child asked for, so an `archmax_wait`
+     * child is delivered to rather than decided on.
+     */
+    decision: z.union([pendingDecisionSchema, pendingInputSchema]),
+});
+/**
+ * Whether a delegated child's park is a decision rather than a wait. Told apart
+ * structurally, on the field only a decision carries, so a checkpoint written
+ * before the union widened still reads correctly.
+ */
+export function isDecisionPark(park) {
+    return Array.isArray(park?.transitions);
+}
+/** The state a park record names, across both spellings. */
+export function parkedStateOf(record) {
+    return record?.state ?? record?.node ?? "";
+}
+/**
+ * Where a park stands: `closing` — the record is committed and the run owes one
+ * tool-free message before it suspends; `suspend` — the next hook site suspends
+ * the session; `null` — no park in progress.
+ */
+export const parkPhaseSchema = z.enum(["closing", "suspend"]);
+/** Model calls made in `state` since it was entered; `budget.maxTurns` is enforced against the visit. */
+export const stateTurnsSchema = z.object({ state: z.string(), count: z.number() });
+// --- Trail --------------------------------------------------------------------
+export const TRAIL_STEP_KINDS = ["trigger", "agent", "human", "sub-workflow", "reset", "on_error"];
+/** One committed traversal step: the state entered, the kind of edge, and the rationale when given. */
+export const trailStepSchema = z.object({
+    to: z.string(),
+    kind: z.enum(TRAIL_STEP_KINDS),
+    reason: z.string().optional(),
+    /** `sub-workflow` steps only: the child slug and whether it completed — the parent's whole record of the sub-run. */
+    workflow: z.string().optional(),
+    status: z.enum(["ok", "error"]).optional(),
+    /** Epoch milliseconds at commit. */
+    ts: z.number(),
+});
+/** One run variable as checkpointed. Locking is monotonic. */
+export const variableEntrySchema = z.object({
+    value: z.unknown(),
+    locked: z.boolean(),
+    /** Host-boundary marker; see {@link mergeVariables}. Never persisted as meaningful state. */
+    reseed: z.boolean().optional(),
+});
+/** The run's usage as persisted — structurally identical to {@link UsageSummary} (guarded below). */
+export const usageSummarySchema = z.object({
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    cacheReadTokens: z.number(),
+    cacheCreationTokens: z.number(),
+    costUsd: z.number().optional(),
+});
+const _trailStepPublicParity = true;
+void _trailStepPublicParity;
+const _usageParity = true;
+void _usageParity;
+// --- Fields -------------------------------------------------------------------
+/** The workflow fields persisted in the checkpointer alongside `messages`. */
+const workflowStateFields = {
+    /** The machine's position. */
+    workflowState: z.string().optional(),
+    /** Why the current turn was rejected; cleared on every transition and turn. */
+    rejected: z.string().nullable().optional(),
+    iterations: z.record(z.string(), z.number()).optional(),
+    beforeDone: z.record(z.string(), z.boolean()).optional(),
+    /** The trigger that started (or last resumed) this run. Its input lives in `variables`. */
+    trigger: z.object({ id: z.string() }).nullable().optional(),
+    /** The state this run began in. Written once, so the reset tool has a fixed target. */
+    entryState: z.string().optional(),
+    /** Hash of the machine spec the session last ran under. Introspection only, never a guard. */
+    specHash: z.string().optional(),
+    /** Coarse lifecycle status; see {@link WORKFLOW_STATUSES}. */
+    status: z.string().optional(),
+    /** The pending decision — the run's own, or a delegated child's. Cleared on decision. */
+    pendingDecision: pendingDecisionSchema.nullable().optional(),
+    /** Monotonic count of human decisions this session has parked on. */
+    decisionCount: z.number().optional(),
+    /** The pending input for a session parked with `archmax_wait`. Cleared on delivery. */
+    pendingInput: pendingInputSchema.nullable().optional(),
+    /** Sub-runs waiting on a person, in presentation order. */
+    pendingDelegations: z.array(pendingDelegationSchema).nullable().optional(),
+    parkPhase: parkPhaseSchema.nullable().optional(),
+    /**
+     * This model call is a reply-only turn: no tools, one text reply. Set by both
+     * park moments (the closing turn and a reply to a parked session) so
+     * disclosure and governance read one condition. Cleared when spent.
+     */
+    replyOnly: z.boolean().nullable().optional(),
+    /** Parks per state, keyed by slug — what `budget.maxParks` is enforced against. */
+    parkCounts: z.record(z.string(), z.number()).optional(),
+    stateTurns: stateTurnsSchema.nullable().optional(),
+    /** Ordered audit trail. Accumulates: a writer sends only the steps it adds. */
+    auditTrail: z.array(trailStepSchema).optional(),
+    /**
+     * Cumulative token usage (and cost). A last-value channel: the one writer adds
+     * its delta to the total it reads, because an additive reducer cannot tell a
+     * hook echoing the total from a delta that happens to equal it.
+     */
+    usage: usageSummarySchema.optional(),
+    /** The run's variables, keyed by name. The channel merges, so a writer sends only its delta. */
+    variables: z.record(z.string(), variableEntrySchema).optional(),
+};
+// --- Reducers -----------------------------------------------------------------
+/**
+ * Merge a variable delta into the store: a host seeding boundary (`reseed`)
+ * replaces anything, a locked entry is otherwise kept, any other write replaces.
+ * Only runtime-owned boundaries set the marker (never the variable tools), so no
+ * agent-reachable write breaks a lock. Folding a store onto itself changes nothing.
+ */
+export function mergeVariables(acc, update) {
+    const merged = { ...acc };
+    for (const [name, entry] of Object.entries(update)) {
+        const existing = merged[name];
+        if (existing !== undefined && entry.reseed !== true && existing.locked)
+            continue;
+        // The marker is an instruction to the merge, not part of the variable.
+        merged[name] = { value: entry.value, locked: entry.locked };
+    }
+    return merged;
+}
+/** Mark a delta as written at a host seeding boundary (a turn's opening, a delivery), so it replaces even a locked entry. */
+export function reseedAll(delta) {
+    const out = {};
+    for (const [name, entry] of Object.entries(delta))
+        out[name] = { ...entry, reseed: true };
+    return out;
+}
+/** Whether two steps are the same record; every field counts, so two children delegated on one millisecond stay two steps. */
+function sameStep(a, b) {
+    return (a === b ||
+        (a.to === b.to &&
+            a.kind === b.kind &&
+            a.ts === b.ts &&
+            a.reason === b.reason &&
+            a.workflow === b.workflow &&
+            a.status === b.status));
+}
+/**
+ * The trail's fold: an update equal to the list held is a hook's echo (no-op);
+ * an update extending it replaces it; anything else (a tool seam sending only
+ * its own steps, two of them in one super-step) is appended.
+ */
+export function foldTrail(acc, update) {
+    const current = acc ?? [];
+    if (!update || update.length === 0)
+        return current;
+    if (update.length === current.length && update.every((s, i) => sameStep(s, current[i]))) {
+        return current;
+    }
+    if (update.length > current.length && current.every((s, i) => sameStep(s, update[i]))) {
+        return [...update];
+    }
+    const fresh = update.filter((step) => !current.includes(step));
+    return fresh.length > 0 ? [...current, ...fresh] : current;
+}
+export function foldPendingDelegations(acc, update) {
+    const current = acc ?? [];
+    if (update === undefined)
+        return current;
+    if (update === null)
+        return [];
+    if (!Array.isArray(update))
+        return [...update.remaining];
+    if (update.length === 0)
+        return current;
+    const incoming = new Set(update.map((record) => record.identity));
+    return [...current.filter((record) => !incoming.has(record.identity)), ...update];
+}
+const pendingDelegationsUpdateSchema = z.union([
+    z.array(pendingDelegationSchema),
+    z.null(),
+    z.object({ remaining: z.array(pendingDelegationSchema) }),
+]);
+/** A field wrapped with its channel's fold; typed loosely, the object below is re-typed as a whole. */
+function reduced(field, updateSchema, fn, initial) {
+    return withLangGraph(field, {
+        reducer: { schema: updateSchema, fn },
+        default: initial,
+    });
+}
+/**
+ * The graph's and the middleware's `stateSchema`, with the accumulating
+ * channels' reducers applied. Without the wrap every field is last-value, and a
+ * tool committing a delta from inside a batch would replace the channel.
+ */
+export const workflowStateSchema = z.object({
+    ...workflowStateFields,
+    pendingDelegations: reduced(workflowStateFields.pendingDelegations, pendingDelegationsUpdateSchema, (acc, update) => foldPendingDelegations(acc, update), () => []),
+    variables: reduced(workflowStateFields.variables, workflowStateFields.variables, (acc, update) => update
+        ? mergeVariables(acc ?? {}, update)
+        : (acc ?? {}), () => ({})),
+    auditTrail: reduced(workflowStateFields.auditTrail, workflowStateFields.auditTrail, (acc, update) => foldTrail(acc, update), () => []),
+    // The wrap widens the reduced fields; what a hook reads and writes is the field's own shape.
+});
+// --- Readers ------------------------------------------------------------------
+/** The checkpointed variable store; a checkpoint predating the field reads as empty. */
+export function readVariables(state) {
+    return readWorkflowState(state).variables ?? {};
+}
+/** What a completed run returned, by declared name; `undefined` when nothing is declared. */
+export function readReturns(state, declared) {
+    if (!declared || declared.length === 0)
+        return undefined;
+    const variables = readVariables(state);
+    return Object.fromEntries(declared.map((name) => [name, variables[name]?.value]));
+}
+/** Coarse session lifecycle values written to {@link WorkflowStateFields.status}. */
+export const WORKFLOW_STATUSES = {
+    running: "running",
+    completed: "completed",
+    rejected: "rejected",
+    awaitingDecision: "awaiting_decision",
+    awaitingInput: "awaiting_input",
+};
+/** The statuses of a run that is over; a parked session is open. */
+export const FINISHED_STATUSES = new Set([
+    WORKFLOW_STATUSES.completed,
+    WORKFLOW_STATUSES.rejected,
+]);
+export function isFinished(status) {
+    return status !== undefined && FINISHED_STATUSES.has(status);
+}
+export function classifyStatus(status) {
+    return isFinished(status) ? "finished" : "open";
+}
+/** The checkpointed usage totals; a checkpoint predating the field reads as zeroed. */
+export function readRunUsage(state) {
+    const usage = readWorkflowState(state).usage;
+    return usage ? { ...emptyUsage(), ...usage } : emptyUsage();
+}
+export function readAuditTrail(state) {
+    const trail = readWorkflowState(state).auditTrail;
+    return Array.isArray(trail) ? trail : [];
+}
+export function readWorkflowState(state) {
+    if (!state || typeof state !== "object")
+        return {};
+    return state;
+}
+export function currentWorkflowState(state, fallback) {
+    return readWorkflowState(state).workflowState ?? fallback;
+}
+/** One reader for disclosure, the prompt section and the kernel, so a parked run cannot be disclosed one way and governed another. */
+export function isReplyOnly(state) {
+    return readWorkflowState(state).replyOnly === true;
+}
+/** The park record a session currently holds, on either channel, or `null`. */
+export function pendingParkOf(state) {
+    const fields = readWorkflowState(state);
+    if (fields.pendingDecision)
+        return { channel: "decision", record: fields.pendingDecision };
+    if (fields.pendingInput)
+        return { channel: "input", record: fields.pendingInput };
+    return null;
+}
+//# sourceMappingURL=state.js.map