@archmax-ai/harness 0.0.0

package/dist/workflow/tool-service.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The tools the runtime services itself inside `wrapToolCall`: the control
+ * tools (with checkpointed state in hand) and delegations (through the
+ * dispatcher, with the calling state known). Every serviced call is bracketed
+ * with the same `tool-called`/`tool-result` pair an ordinary call gets.
+ */
+import { ToolMessage } from "@langchain/core/messages";
+import { Command } from "@langchain/langgraph";
+import type { LifecycleContext, LifecycleRunner } from "../lifecycle/runner.js";
+import type { WorkflowMachine } from "../machine/machine.js";
+import type { WorkflowEventEmitter } from "../core/events.js";
+import type { MountPrefixes } from "../core/mounts.js";
+import type { WorkflowToolCallRequest } from "../core/deepagents.js";
+import { type PendingDecision, type TrailStep } from "./state.js";
+import { type SubWorkflowDispatcher } from "./sub-workflow.js";
+export interface ToolServiceContext {
+    machine: WorkflowMachine;
+    emit: WorkflowEventEmitter;
+    lifecycle: LifecycleRunner;
+    mountPrefixes: MountPrefixes;
+    subWorkflows?: SubWorkflowDispatcher;
+    lifecycleCtx(sessionId: string, state: unknown, messages: unknown[]): LifecycleContext;
+}
+/** The identities of one call being serviced. */
+export interface ServicedCall {
+    sessionId: string;
+    workflowState: string;
+    toolName: string;
+    /** The id the call is reported under: the provider's, else a generated fallback. */
+    callId: string;
+    /** The provider's tool-call id, echoed on the tool message. */
+    toolCallId: string;
+}
+/** A governance refusal: an error-status tool message the model self-corrects on, marked for the session view. */
+export declare function blockedMessage(toolName: string, toolCallId: string, content: string): ToolMessage;
+export declare function createToolService(ctx: ToolServiceContext): {
+    emitToolCalled: (state: string, toolName: string, callId: string, args: Record<string, unknown>) => void;
+    dispatchSteps: (sessionId: string, workflowState: string) => TrailStep[];
+    withDispatchSteps: (result: Command | ToolMessage, steps: TrailStep[]) => Command | ToolMessage;
+    reportMove: (sessionId: string, moved: {
+        from: string;
+        to: string;
+        park?: PendingDecision;
+    }) => void;
+    serviceDelegation: (request: WorkflowToolCallRequest, dispatcher: SubWorkflowDispatcher, call: ServicedCall, args: Record<string, unknown>) => Promise<Command | ToolMessage>;
+    serviceControlTool: (request: WorkflowToolCallRequest, call: ServicedCall, args: Record<string, unknown>) => Promise<Command | ToolMessage | undefined>;
+    releaseSession(sessionId: string): void;
+};

package/dist/workflow/tool-service.js

@@ -0,0 +1,291 @@
+/**
+ * The tools the runtime services itself inside `wrapToolCall`: the control
+ * tools (with checkpointed state in hand) and delegations (through the
+ * dispatcher, with the calling state known). Every serviced call is bracketed
+ * with the same `tool-called`/`tool-result` pair an ordinary call gets.
+ */
+import { ToolMessage } from "@langchain/core/messages";
+import { Command } from "@langchain/langgraph";
+import { toolCallDetail, toolOutputPreview } from "../core/tool-telemetry.js";
+import { TITLE_VARIABLE } from "../machine/variables.js";
+import { workflowSlugFromToolName } from "../machine/tool-names.js";
+import { ADVANCE_TOOL, GET_VARIABLES_TOOL, handleAdvance, handleGetVariables, handleReset, handleSetVariables, handleWait, refusal, RESET_TOOL, SET_VARIABLES_TOOL, setVariablesCommand, WAIT_TOOL, } from "./control-tools.js";
+import { readVariables } from "./state.js";
+import { subWorkflowParkOf } from "./sub-workflow.js";
+import { delegationCallResult } from "./workflow-tools.js";
+import { buildRunnableConfig } from "./runtime-config.js";
+/**
+ * Which model step a serviced call belongs to: the id of the assistant message
+ * that made it. Every tool call in one assistant message shares it, and the
+ * next model call mints a new one — so it is exactly the scope within which a
+ * second transition is a duplicate rather than a further step.
+ *
+ * Without an id (a fake model in a test, a provider that omits one) the message
+ * count stands in: sibling calls still read one step-start snapshot, so they
+ * still agree, and a later step has appended at least the previous results.
+ */
+function stepIdOf(state) {
+    const messages = state?.messages;
+    if (!Array.isArray(messages))
+        return "0";
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        const calls = msg?.tool_calls;
+        if (!Array.isArray(calls) || calls.length === 0)
+            continue;
+        return typeof msg?.id === "string" && msg.id ? msg.id : `#${messages.length}`;
+    }
+    return `#${messages.length}`;
+}
+/**
+ * The refusal a second transition in one assistant message gets. Phrased as the
+ * mistake it is, so the model drops the extra call rather than retrying it: the
+ * first transition already landed and this step is over.
+ */
+function duplicateMoveRefusal(toolName, toolCallId, landedAt) {
+    return refusal(toolName, toolCallId, `${toolName} rejected: this message already moved the workflow, which is now in ` +
+        `state '${landedAt}'. One transition per message — decide where to go from ` +
+        `there on your next turn.`);
+}
+/** A governance refusal: an error-status tool message the model self-corrects on, marked for the session view. */
+export function blockedMessage(toolName, toolCallId, content) {
+    return new ToolMessage({
+        content,
+        tool_call_id: toolCallId,
+        name: toolName,
+        status: "error",
+        additional_kwargs: { governance_blocked: true },
+    });
+}
+/** The tool message a serviced handler settled with: bare, or carried in a `Command`'s update. */
+function settledMessage(result) {
+    if (result instanceof ToolMessage)
+        return result;
+    const update = result?.update;
+    return update?.messages?.find((m) => m instanceof ToolMessage);
+}
+export function createToolService(ctx) {
+    const { machine, emit, lifecycle, mountPrefixes, subWorkflows } = ctx;
+    function emitToolCalled(state, toolName, callId, args) {
+        const detail = toolCallDetail(args);
+        emit({ type: "tool-called", state, tool: toolName, callId, args, ...(detail ? { detail } : {}) });
+    }
+    /** Bracket a serviced call with its `tool-called`/`tool-result` pair: every announced call has to settle. */
+    async function withPairedEvents(call, args, handle, statusOf) {
+        const { workflowState, toolName, callId } = call;
+        emitToolCalled(workflowState, toolName, callId, args);
+        const startedAt = Date.now();
+        const settle = (status, preview) => emit({ type: "tool-result", state: workflowState, tool: toolName, callId, status, durationMs: Date.now() - startedAt, ...preview });
+        try {
+            const result = await handle();
+            const message = settledMessage(result.message);
+            settle(statusOf ? statusOf(result) : message?.status === "error" ? "error" : "ok", toolOutputPreview(message ?? result.message));
+            return result;
+        }
+        catch (err) {
+            settle("error", toolOutputPreview(err?.message ?? String(err)));
+            throw err;
+        }
+    }
+    /**
+     * The model step each session last moved in, keyed by session id. One step may
+     * commit one transition: sibling `archmax_advance` calls in a single assistant
+     * message each read the same step-start position, so each would pass edge
+     * validation, run the leaving state's `after` hook, and write a position to a
+     * last-value channel — double-running a governance hook and landing wherever
+     * the last writer said (issue #66).
+     */
+    const movedAtStep = new Map();
+    /**
+     * The sub-runs a call caused, drained from the dispatcher's ledger as trail
+     * steps. Drained after every call: a script's dispatches arrive during the
+     * `archmax_run` call that ran it.
+     */
+    function dispatchSteps(sessionId, workflowState) {
+        return (subWorkflows?.drainDispatches(sessionId) ?? []).map((d) => ({
+            to: workflowState,
+            kind: "sub-workflow",
+            workflow: d.workflow,
+            status: d.status,
+            ...(d.reason ? { reason: d.reason } : {}),
+            ts: Date.now(),
+        }));
+    }
+    function withDispatchSteps(result, steps) {
+        if (steps.length === 0)
+            return result;
+        if (result instanceof ToolMessage) {
+            return new Command({ update: { messages: [result], auditTrail: steps } });
+        }
+        const update = result.update ?? {};
+        return new Command({
+            update: { ...update, auditTrail: [...(update.auditTrail ?? []), ...steps] },
+        });
+    }
+    /** Report a move: the state left, the state entered, and the park it opened. */
+    function reportMove(sessionId, moved) {
+        emit({ type: "state-leave", state: moved.from, next: moved.to });
+        emit({ type: "state-enter", state: moved.to });
+        if (moved.park) {
+            emit({ type: "parked", node: moved.to, state: moved.to, sessionId, awaiting: "decision" });
+        }
+    }
+    /** Service a delegation through the dispatcher; refused as a blocked call when nothing may run. */
+    async function serviceDelegation(request, dispatcher, call, args) {
+        const { sessionId, workflowState, toolName, callId, toolCallId } = call;
+        const workflow = workflowSlugFromToolName(toolName);
+        const dispatchInput = {
+            workflow,
+            params: args,
+            variables: readVariables(request.state),
+            config: buildRunnableConfig(request.runtime ?? {}),
+            state: workflowState,
+            toolCallId: callId,
+        };
+        const refused = await dispatcher.refusal(dispatchInput);
+        if (refused) {
+            emit({ type: "tool-blocked", state: workflowState, tool: toolName, reason: refused.message, callId, args });
+            return blockedMessage(toolName, toolCallId, refused.message);
+        }
+        const outcome = await withPairedEvents(call, args, async () => {
+            try {
+                const output = delegationCallResult(await dispatcher.dispatch(dispatchInput));
+                return {
+                    message: new ToolMessage({
+                        content: typeof output === "string" ? output : JSON.stringify(output),
+                        tool_call_id: toolCallId,
+                        name: toolName,
+                    }),
+                };
+            }
+            catch (err) {
+                // The child stopped for a person. Recorded here, where checkpointed state
+                // is reachable, rather than propagated: the suspension would otherwise
+                // unwind the whole turn and replay every sibling call.
+                const parked = subWorkflowParkOf(err);
+                if (parked) {
+                    const decision = parked.decision;
+                    return {
+                        message: new Command({
+                            update: {
+                                pendingDelegations: [
+                                    {
+                                        state: workflowState,
+                                        node: workflowState,
+                                        workflow,
+                                        toolCallId,
+                                        identity: parked.identity,
+                                        dispatchId: parked.dispatchId,
+                                        decision,
+                                    },
+                                ],
+                                messages: [
+                                    new ToolMessage({
+                                        content: `The '${workflow}' sub-workflow stopped for a person at its ` +
+                                            `'${decision?.state ?? decision?.node}' step. This run is now waiting on ` +
+                                            `that decision and will continue here once it is made.`,
+                                        tool_call_id: toolCallId,
+                                        name: toolName,
+                                    }),
+                                ],
+                            },
+                        }),
+                    };
+                }
+                // A child that ran and did not finish is this state's failure: committed as
+                // `rejected`, so the run routes through `on_error` once the model has finished.
+                const message = err?.message ?? String(err);
+                return {
+                    message: new Command({
+                        update: { rejected: message, messages: [refusal(toolName, toolCallId, message)] },
+                    }),
+                };
+            }
+        });
+        return withDispatchSteps(outcome.message, dispatchSteps(sessionId, workflowState));
+    }
+    /** Service a control tool, or `undefined` when `toolName` is not one. */
+    async function serviceControlTool(request, call, args) {
+        const { sessionId, workflowState, toolName, callId, toolCallId } = call;
+        const state = request.state;
+        const step = stepIdOf(state);
+        // One transition per model step. Only a move that landed claims the step, so
+        // a refused attempt (invalid edge, hook veto) leaves a sibling free to try.
+        const claimed = movedAtStep.get(sessionId);
+        const alreadyMovedTo = claimed?.step === step ? claimed.to : undefined;
+        const claimStep = (moved) => {
+            if (!moved)
+                return;
+            movedAtStep.set(sessionId, { step, to: moved.to });
+            reportMove(sessionId, moved);
+        };
+        switch (toolName) {
+            case ADVANCE_TOOL: {
+                if (alreadyMovedTo)
+                    return duplicateMoveRefusal(toolName, toolCallId, alreadyMovedTo);
+                const outcome = await withPairedEvents(call, args, () => handleAdvance({ machine, lifecycle, mountPrefixes }, { toolCallId, callId, args, state, ctx: ctx.lifecycleCtx(sessionId, state, state?.messages ?? []) }), 
+                // A refused transition replies without erroring the message, so the outcome is read off the move.
+                (result) => (result.moved ? "ok" : "error"));
+                claimStep(outcome.moved);
+                return outcome.message;
+            }
+            case RESET_TOOL: {
+                if (alreadyMovedTo)
+                    return duplicateMoveRefusal(toolName, toolCallId, alreadyMovedTo);
+                const outcome = await withPairedEvents(call, args, () => handleReset(machine, { toolCallId, args, state }));
+                claimStep(outcome.moved);
+                return outcome.message;
+            }
+            case WAIT_TOOL: {
+                const outcome = await withPairedEvents(call, args, () => handleWait(machine, { toolCallId, args, state }));
+                if (outcome.park) {
+                    emit({
+                        type: "parked",
+                        node: workflowState,
+                        state: workflowState,
+                        sessionId,
+                        awaiting: "input",
+                        reason: outcome.park.reason,
+                        ...(outcome.park.resumeAt ? { resumeAt: outcome.park.resumeAt } : {}),
+                        callId,
+                    });
+                }
+                return outcome.message;
+            }
+            case GET_VARIABLES_TOOL: {
+                const outcome = await withPairedEvents(call, args, () => ({
+                    message: handleGetVariables({ toolCallId, args, state }),
+                }));
+                return outcome.message;
+            }
+            case SET_VARIABLES_TOOL: {
+                const outcome = await withPairedEvents(call, args, () => {
+                    const written = handleSetVariables({ toolCallId, args, state });
+                    // Only a write that landed is announced; a refusal is visible as the tool's error result.
+                    if (written.written) {
+                        emit({ type: "variables-set", state: workflowState, names: written.written, locked: written.locked === true, callId });
+                        const title = written.delta?.[TITLE_VARIABLE]?.value;
+                        if (typeof title === "string")
+                            emit({ type: "title-set", title, state: workflowState, callId });
+                    }
+                    return { message: setVariablesCommand(written) };
+                });
+                return outcome.message;
+            }
+            default:
+                return undefined;
+        }
+    }
+    return {
+        emitToolCalled,
+        dispatchSteps,
+        withDispatchSteps,
+        reportMove,
+        serviceDelegation,
+        serviceControlTool,
+        releaseSession(sessionId) {
+            movedAtStep.delete(sessionId);
+        },
+    };
+}
+//# sourceMappingURL=tool-service.js.map

package/dist/workflow/tool-service.js.map

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

package/dist/workflow/turn-boundary.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The turn boundary: what happens once per invoke, before any model call.
+ *
+ * A turn boundary resets the turn's mechanics (rejected, iterations,
+ * beforeDone, parkCounts, park records and phase, replyOnly, the turn budget)
+ * and retains the conversation (position, entryState, variables, transcript,
+ * trail, files). Every ingress that begins a turn arrives here; a park
+ * resumption re-enters at its own suspension through a `Command` and never
+ * crosses this boundary — which is what makes "a disabled machine starts
+ * nothing, finishes what it started" a property of the graph's shape.
+ */
+import { type WorkflowEventEmitter, type WorkflowEventHandler } from "../core/events.js";
+import type { Workspace } from "../core/workspace.js";
+import type { WorkflowMachine } from "../machine/machine.js";
+import { type VariableStore } from "../machine/variables.js";
+import { type WorkflowUpdate } from "./state.js";
+export interface TurnBoundaryContext {
+    machine: WorkflowMachine;
+    emit: WorkflowEventEmitter;
+    /** The lifecycle event subscriber, for the spec snapshot's own diagnostics. */
+    onEvent?: WorkflowEventHandler;
+    /** Workspace backend for writing the spec snapshot into the session zone. */
+    workspace?: Workspace;
+    /** The `workflows/<slug>/` name, used only to name the machine in a refusal. */
+    workflowName?: string;
+    /** The assembly-time default trigger, used when an invocation supplies none. */
+    defaultTrigger?: {
+        id: string;
+    };
+    /** Host-seeded run variables, applied at each turn boundary (already locked). */
+    seededVariables?: VariableStore;
+}
+/**
+ * Open a turn: resolve where it begins, refuse it if the machine cannot serve
+ * it, and commit the opening. A refused turn carries `jumpTo: "end"` so no model runs.
+ */
+export declare function openTurn(ctx: TurnBoundaryContext, state: unknown, runtime: {
+    configurable?: Record<string, unknown>;
+} | undefined): Promise<WorkflowUpdate>;

package/dist/workflow/turn-boundary.js

@@ -0,0 +1,128 @@
+/**
+ * The turn boundary: what happens once per invoke, before any model call.
+ *
+ * A turn boundary resets the turn's mechanics (rejected, iterations,
+ * beforeDone, parkCounts, park records and phase, replyOnly, the turn budget)
+ * and retains the conversation (position, entryState, variables, transcript,
+ * trail, files). Every ingress that begins a turn arrives here; a park
+ * resumption re-enters at its own suspension through a `Command` and never
+ * crosses this boundary — which is what makes "a disabled machine starts
+ * nothing, finishes what it started" a property of the graph's shape.
+ */
+import { SESSION_ORIGIN } from "../core/events.js";
+import { MANUAL_TRIGGER } from "../machine/triggers.js";
+import { buildSeededVariables, TITLE_VARIABLE, TRIGGER_VARIABLE, } from "../machine/variables.js";
+import { decisionRecordFor } from "./parks.js";
+import { writeSpecSnapshotIfAbsent } from "./snapshot.js";
+import { readVariables, readWorkflowState, reseedAll, WORKFLOW_STATUSES, } from "./state.js";
+import { sessionScopeFrom, seedVariablesFrom } from "../sessions/scope.js";
+/**
+ * Open a turn: resolve where it begins, refuse it if the machine cannot serve
+ * it, and commit the opening. A refused turn carries `jumpTo: "end"` so no model runs.
+ */
+export async function openTurn(ctx, state, runtime) {
+    const { machine, emit } = ctx;
+    const fields = readWorkflowState(state);
+    // The trigger is per invoke, falling back to the assembly's default; its id maps
+    // to a declared start state, or the machine's entry when unmatched.
+    const trigger = fields.trigger ?? ctx.defaultTrigger ?? { id: MANUAL_TRIGGER };
+    const startState = machine.startStateForTrigger(trigger.id) ?? machine.entry;
+    // A session's first turn enters the state its trigger declares; every later turn
+    // continues where the conversation is. A retained position the current
+    // definition no longer declares reopens at the trigger's entry.
+    const retained = fields.workflowState;
+    const reopening = retained == null || !Object.hasOwn(machine.spec.states, retained);
+    const position = reopening ? startState : retained;
+    const entryState = fields.entryState ?? position;
+    // A refused turn commits `rejected` with a reason rather than throwing, before
+    // any event narrates a turn beginning: nothing is entered, no hook runs.
+    const refuse = (reason, extra = {}) => {
+        emit({ type: "warning", scope: "workflow", message: reason });
+        return {
+            workflowState: position,
+            entryState,
+            specHash: machine.specHash,
+            status: WORKFLOW_STATUSES.rejected,
+            rejected: reason,
+            trigger,
+            ...extra,
+            jumpTo: "end",
+        };
+    };
+    if (machine.disabled) {
+        const named = ctx.workflowName ? `workflow '${ctx.workflowName}'` : "this workflow";
+        return refuse(`Refusing to start: ${named} is disabled.`);
+    }
+    // A reset means "opened at an entry state": a first turn, or a reopening on a dropped position.
+    if (reopening)
+        emit({ type: "workflow-reset", entry: position });
+    // Every turn announces where it begins; the trail records the same arrival below.
+    emit({ type: "advance", from: SESSION_ORIGIN, to: position });
+    // A definition may change between turns; the snapshot must exist for the recorded hash to mean anything.
+    if (fields.specHash !== machine.specHash && ctx.workspace) {
+        await writeSpecSnapshotIfAbsent(ctx.workspace, machine.specHash, machine.spec, ctx.onEvent);
+    }
+    // This turn's opening variables: the host's seeds, this invocation's seeds (a
+    // sub-run's params), and the built-in `trigger`, locked. Marked `reseed`: a turn
+    // boundary is a host seeding boundary exactly as a delivery is.
+    const openingVariables = reseedAll({
+        ...(ctx.seededVariables ?? {}),
+        ...buildSeededVariables(seedVariablesFrom(runtime?.configurable), "supplied to a sub-workflow"),
+        [TRIGGER_VARIABLE]: { value: trigger.id, locked: true },
+    });
+    // A seeded `title` is an opening label: it loses to a title the session already
+    // holds, so the agent's refinement survives the next turn.
+    if (openingVariables[TITLE_VARIABLE] !== undefined &&
+        readVariables(state)[TITLE_VARIABLE] !== undefined) {
+        delete openingVariables[TITLE_VARIABLE];
+    }
+    const seededTitle = openingVariables[TITLE_VARIABLE]?.value;
+    if (typeof seededTitle === "string")
+        emit({ type: "title-set", title: seededTitle });
+    // The entry half of the trigger's signature: a run that cannot satisfy its own contract reaches no model.
+    const missingInputs = (machine.requiresForTrigger(trigger.id) ?? []).filter((name) => openingVariables[name] === undefined);
+    if (missingInputs.length > 0) {
+        return refuse(`Refusing to start: trigger '${trigger.id}' requires ` +
+            `${missingInputs.map((n) => `'${n}'`).join(", ")}, which this firing does not supply.`, { variables: openingVariables });
+    }
+    emit({ type: "state-enter", state: position });
+    // A turn opened on a session parked at a human state presents the decision
+    // again on a fresh record: the run owes the person a closing message, then
+    // suspends where it stood.
+    let reparked = {};
+    if (machine.isHumanState(position)) {
+        const seq = (fields.decisionCount ?? 0) + 1;
+        emit({ type: "parked", node: position, state: position, sessionId: sessionScopeFrom(runtime).sessionId, awaiting: "decision" });
+        reparked = {
+            pendingDecision: decisionRecordFor(machine, position, seq),
+            decisionCount: seq,
+            status: WORKFLOW_STATUSES.awaitingDecision,
+            parkPhase: "closing",
+        };
+    }
+    return {
+        workflowState: position,
+        rejected: null,
+        iterations: {},
+        beforeDone: {},
+        parkCounts: {},
+        // A new turn is not a resumed park: every park channel is cleared, and a
+        // delegated child suspended on its own human state is abandoned by the turn
+        // that supersedes it — an orphaned child beats a caller wedged on an interrupt.
+        pendingInput: null,
+        pendingDecision: null,
+        pendingDelegations: null,
+        parkPhase: null,
+        replyOnly: null,
+        stateTurns: null,
+        // Where this session began: recorded once, so the reset tool has a fixed target.
+        entryState,
+        specHash: machine.specHash,
+        status: WORKFLOW_STATUSES.running,
+        trigger,
+        variables: openingVariables,
+        auditTrail: [{ to: position, kind: "trigger", reason: trigger.id, ts: Date.now() }],
+        ...reparked,
+    };
+}
+//# sourceMappingURL=turn-boundary.js.map

package/dist/workflow/turn-boundary.js.map

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

package/dist/workflow/turn-runner.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The turn runner: how one invocation on a session is driven. Every way a
+ * session is entered goes through here, so all of them bind the session's run
+ * zone and event context, stream the model's text as `agent-text-delta` events,
+ * and settle to the same state the graph's `invoke` would.
+ */
+import type { RunnableConfig } from "@langchain/core/runnables";
+import type { WorkflowEventEmitter } from "../core/events.js";
+import type { CompiledAgentGraph } from "../core/deepagents.js";
+/** Drives one turn on a session: the graph's `invoke`/`stream`/`streamEvents`, session-bound. */
+export interface TurnRunner {
+    invoke(input: unknown, config?: RunnableConfig): Promise<Record<string, unknown>>;
+    stream(input: unknown, config?: RunnableConfig): AsyncIterable<unknown>;
+    streamEvents(input: unknown, config: RunnableConfig, options?: unknown): AsyncIterable<unknown>;
+}
+/** What binds a call to a session: the session zone's view and the event context, refusing a bad id. */
+export type SessionBinder = <T>(sessionId: string, fn: () => Promise<T>) => Promise<T>;
+export interface TurnRunnerOptions {
+    graph: CompiledAgentGraph;
+    emit: WorkflowEventEmitter;
+    /** Bind `fn` to `sessionId` (session zone and event context); refuses an id that escapes its zone or shadows a reserved name. */
+    bindSession: SessionBinder;
+    /** The state deltas are attributed to before the graph reports one. */
+    entryState: string;
+}
+export declare function sessionIdOfConfig(config: RunnableConfig | undefined): string;
+export declare function createTurnRunner(opts: TurnRunnerOptions): TurnRunner;
+/**
+ * The runner a **plain** (ungoverned) agent drives its graph through: the graph's
+ * own `invoke`/`stream`/`streamEvents`, each bound to the session named by
+ * `configurable.thread_id`. No machine means no state to attribute text deltas
+ * to and no park to settle, so nothing here reshapes the graph's results; what
+ * the binding buys is that the agent's `scratchpad/…` and offload paths land
+ * under `<sessionId>/` in the session store exactly as a governed session's do,
+ * and that a reserved or escaping id is refused before anything is written.
+ */
+export declare function createPlainTurnRunner(opts: {
+    graph: CompiledAgentGraph;
+    bindSession: SessionBinder;
+}): TurnRunner;