@archmax-ai/harness 0.0.0

package/dist/sandbox/runtime.js

@@ -0,0 +1,51 @@
+import { formatReplResult, ReplSession } from "@langchain/quickjs";
+const DEFAULT_SUBAGENT_CONCURRENCY = 32;
+/** Fallback per-eval timeout when a caller omits one (mirrors the executor default). */
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * The bundled default: `@langchain/quickjs`'s `ReplSession` behind the
+ * interface. Sessions are keyed by namespace and reused across evals (the
+ * runtime namespaces per session + session kind), and `formatReplResult`
+ * renders the outcome so the executor stays engine-agnostic.
+ */
+export function createQuickJsSandboxRuntime() {
+    return {
+        session(namespace, options) {
+            const bridge = options.subagentDispatch != null
+                ? {
+                    dispatch: options.subagentDispatch,
+                    maxConcurrency: options.subagentMaxConcurrency ?? DEFAULT_SUBAGENT_CONCURRENCY,
+                }
+                : undefined;
+            const session = ReplSession.getOrCreate(namespace, {
+                tools: options.tools ?? [],
+                memoryLimitBytes: options.quotas?.memoryLimitBytes,
+                maxPtcCalls: options.quotas?.maxPtcCalls,
+                maxResultChars: options.quotas?.maxResultChars,
+                captureConsole: options.captureConsole ?? true,
+                sessionId: options.sessionId,
+                subagentBridge: bridge,
+            });
+            // Refresh the bridge dispatch each acquisition so a reused session picks up
+            // the current request's `task()` wiring.
+            if (bridge)
+                session.updateBridgeDispatch(bridge.dispatch);
+            return {
+                async eval(code, timeoutMs) {
+                    const result = await session.eval(code, timeoutMs ?? DEFAULT_TIMEOUT_MS);
+                    return {
+                        ok: result.ok,
+                        value: result.value,
+                        logs: result.logs,
+                        error: result.error,
+                        formatted: formatReplResult(result),
+                    };
+                },
+            };
+        },
+        dispose(namespace) {
+            ReplSession.deleteSession(namespace);
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/sandbox/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/sandbox/runtime.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAA8B,MAAM,oBAAoB,CAAC;AAuD/F,MAAM,4BAA4B,GAAG,EAAE,CAAC;AACxC,wFAAwF;AACxF,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,OAAO,CAAC,SAAiB,EAAE,OAA8B;YACvD,MAAM,MAAM,GACV,OAAO,CAAC,gBAAgB,IAAI,IAAI;gBAC9B,CAAC,CAAC;oBACE,QAAQ,EAAE,OAAO,CAAC,gBAAgB;oBAClC,cAAc,EAAE,OAAO,CAAC,sBAAsB,IAAI,4BAA4B;iBAC/E;gBACH,CAAC,CAAC,SAAS,CAAC;YAEhB,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC,SAAS,EAAE;gBACjD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;gBAC1B,gBAAgB,EAAE,OAAO,CAAC,MAAM,EAAE,gBAAgB;gBAClD,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE,WAAW;gBACxC,cAAc,EAAE,OAAO,CAAC,MAAM,EAAE,cAAc;gBAC9C,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,IAAI;gBAC9C,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,cAAc,EAAE,MAAM;aACvB,CAAC,CAAC;YACH,4EAA4E;YAC5E,yCAAyC;YACzC,IAAI,MAAM;gBAAE,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAE1D,OAAO;gBACL,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,SAAkB;oBACzC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,IAAI,kBAAkB,CAAC,CAAC;oBACzE,OAAO;wBACL,EAAE,EAAE,MAAM,CAAC,EAAE;wBACb,KAAK,EAAE,MAAM,CAAC,KAAK;wBACnB,IAAI,EAAE,MAAM,CAAC,IAAI;wBACjB,KAAK,EAAE,MAAM,CAAC,KAAK;wBACnB,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC;qBACpC,CAAC;gBACJ,CAAC;aACF,CAAC;QACJ,CAAC;QAED,OAAO,CAAC,SAAiB;YACvB,WAAW,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/sandbox/tools.d.ts

@@ -0,0 +1,34 @@
+import type { StructuredTool } from "@langchain/core/tools";
+import type { AgentMiddleware } from "langchain";
+import type { PtcToolGateway } from "./ptc-gateway.js";
+import { type ScriptExecutor } from "./executor.js";
+/**
+ * The two sandbox tools — `archmax_eval` (inline code) and `archmax_run` (an
+ * authored script file) — plus the middleware that scopes their PTC tools,
+ * snapshots the session's variables for `archmax_run`, and tears down REPL
+ * sessions per scope. Both evaluate in the *same* REPL session for a run scope,
+ * so a helper defined by one is in scope for the other.
+ */
+export interface Interpreter {
+    middleware: AgentMiddleware;
+    tools: StructuredTool[];
+    executor: ScriptExecutor;
+    /**
+     * Release the resources held for a session: the cached PTC tool sets and the
+     * agent REPL sessions of the session's own run scope **and of every sub-run
+     * scope nested beneath it**. Idempotent; safe after aborted runs.
+     */
+    dispose(sessionId: string): void;
+}
+/** Pick PTC tools from the agent's full tool set. Empty `names` = all except {@link PTC_EXCLUDED_TOOLS}. */
+export declare function resolvePtcTools(allTools: unknown[], names: string[]): StructuredTool[];
+export declare function createInterpreter(opts: {
+    executor: ScriptExecutor;
+    ptcNames: string[];
+    /**
+     * Governs and instruments the `tools.*` calls scripts make. Optional so a
+     * test can assemble a bare interpreter; the runtime always supplies one, and
+     * without it a script's tool calls run ungoverned.
+     */
+    ptcGateway?: PtcToolGateway;
+}): Interpreter;

package/dist/sandbox/tools.js

@@ -0,0 +1,147 @@
+import { createMiddleware, tool } from "langchain";
+import { z } from "zod";
+import { asModelCallResult, } from "../core/deepagents.js";
+import { EVAL_TOOL, RUN_TOOL } from "../machine/tool-names.js";
+import { PTC_EXCLUDED_TOOLS } from "../kernel/kernel.js";
+import { AGENT_SESSION } from "./executor.js";
+import { DEFAULT_SESSION_ID, releaseScopes, sessionScopeFrom } from "../sessions/scope.js";
+import { readVariables } from "../workflow/state.js";
+/** Pick PTC tools from the agent's full tool set. Empty `names` = all except {@link PTC_EXCLUDED_TOOLS}. */
+export function resolvePtcTools(allTools, names) {
+    const tools = allTools;
+    if (names.length === 0) {
+        return tools.filter((t) => !PTC_EXCLUDED_TOOLS.has(t.name));
+    }
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    // Governance-owned exclusions hold even for an explicit allow-list: scripts
+    // may never call the runtime's controls (both sandbox entry points among them)
+    // through PTC.
+    return names
+        .map((n) => byName.get(n))
+        .filter((t) => t !== undefined && !PTC_EXCLUDED_TOOLS.has(t.name));
+}
+/** The session's variables as the flat `name → value` map a script reads. */
+function flatVariables(state) {
+    return Object.fromEntries(Object.entries(readVariables(state)).map(([name, entry]) => [name, entry.value]));
+}
+export function createInterpreter(opts) {
+    const { executor, ptcNames, ptcGateway } = opts;
+    // Keyed by **run scope**, not session: two sub-runs of one session execute
+    // concurrently and must not share a REPL or each other's PTC tool set. At the
+    // top level the scope key is the session id.
+    const ptcToolsByScope = new Map();
+    // The variables in force for the `archmax_run` call being serviced, captured at
+    // the tool call so the script reads the store the call was made against.
+    const variablesByScope = new Map();
+    /** The PTC surface a call in this scope may use, wrapped by the gateway. */
+    const scopeTools = (scope) => ptcToolsByScope.get(scope) ?? [];
+    const evalCode = tool(async (input, runtimeConfig) => {
+        const scope = sessionScopeFrom(runtimeConfig, DEFAULT_SESSION_ID).sessionId;
+        const outcome = await executor.runCode(input.code, {
+            sessionId: scope,
+            sessionNamespace: AGENT_SESSION,
+            tools: scopeTools(scope),
+            prelude: true,
+        });
+        return outcome.formatted;
+    }, {
+        name: EVAL_TOOL,
+        description: "Evaluate JavaScript in a sandboxed REPL with persistent state across calls, " +
+            "console capture, and `tools.*` for tool calls. " +
+            "Prefer it over many small tool calls when work is loops, filtering, or arithmetic. " +
+            "Every `tools.*` call is governed by the workflow graph exactly as a direct call is.",
+        schema: z.object({
+            code: z
+                .string()
+                .describe("JavaScript to evaluate. The last expression is returned."),
+        }),
+    });
+    const runScript = tool(async (input, runtimeConfig) => {
+        const scope = sessionScopeFrom(runtimeConfig, DEFAULT_SESSION_ID).sessionId;
+        const outcome = await executor.runFile(input.file_path, {
+            sessionId: scope,
+            sessionNamespace: AGENT_SESSION,
+            // The script's `args`: what the model passed, plus the session's
+            // variables by name — a script reads the run's input without the model
+            // having to retype it.
+            args: { ...(input.args ?? {}), variables: variablesByScope.get(scope) ?? {} },
+            tools: scopeTools(scope),
+        });
+        return outcome.formatted;
+    }, {
+        name: RUN_TOOL,
+        description: "Run an authored workspace JavaScript file in the same sandboxed REPL as " +
+            `\`${EVAL_TOOL}\`, with \`tools.*\` for tool calls. The script reads its input as the ` +
+            "global `args`: the arguments you pass plus `args.variables`, the session's variables " +
+            "by name. Which files may run is enforced by the workflow graph.",
+        schema: z.object({
+            file_path: z
+                .string()
+                .describe("Workspace-relative path, e.g. skills/orders/scripts/check.js."),
+            args: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Exposed to the script as global `args`, beside `args.variables`."),
+        }),
+    });
+    function releaseScope(scope) {
+        ptcToolsByScope.delete(scope);
+        variablesByScope.delete(scope);
+        ptcGateway?.release(scope);
+        executor.dispose(scope, AGENT_SESSION);
+    }
+    function dispose(sessionId) {
+        // A session's scopes are its own plus every sub-run's, so disposal sweeps by
+        // prefix. The executor is told about each one: a REPL leaked per dispatch
+        // would outlive the run that opened it.
+        const released = releaseScopes(ptcToolsByScope, sessionId);
+        releaseScopes(variablesByScope, sessionId);
+        if (!released.includes(sessionId))
+            released.push(sessionId);
+        for (const scope of released)
+            releaseScope(scope);
+    }
+    const middleware = createMiddleware({
+        name: "ScriptInterpreter",
+        // A middleware's hooks see the agent state parsed through *its own* schema,
+        // so without declaring `variables` here the snapshot below would read an
+        // empty store. Declared read-only in shape: the workflow middleware owns
+        // the channel and its reducer (the first declaration of a key wins).
+        stateSchema: z.object({
+            variables: z
+                .record(z.string(), z.object({ value: z.unknown(), locked: z.boolean() }).passthrough())
+                .optional(),
+        }),
+        wrapModelCall: async (request, handler) => {
+            const scope = sessionScopeFrom(request.runtime, DEFAULT_SESSION_ID).sessionId;
+            // Selection stays pure (which tools a script may see); the gateway adds
+            // enforcement (what each call may do), which it decides per call against
+            // the scope's live context rather than at this capture point.
+            const selected = resolvePtcTools(request.tools ?? [], ptcNames);
+            ptcToolsByScope.set(scope, ptcGateway ? ptcGateway.wrap(selected, { origin: "script", sessionId: scope }) : selected);
+            // Narrowed like the workflow middleware: whichever is innermost is named
+            // when the model handler returns something outside the contract.
+            return asModelCallResult(await handler(request), "the script interpreter");
+        },
+        wrapToolCall: async (request, handler) => {
+            if (request.toolCall.name === RUN_TOOL) {
+                const scope = sessionScopeFrom(request.runtime, DEFAULT_SESSION_ID).sessionId;
+                variablesByScope.set(scope, flatVariables(request.state));
+            }
+            return handler(request);
+        },
+        afterAgent: async (state, runtime) => {
+            // Released at the scope this agent ran in, not the session: a sub-run
+            // finishing must not tear down its parent's REPL, which is still mid-run.
+            releaseScope(sessionScopeFrom(runtime, DEFAULT_SESSION_ID).sessionId);
+            return state;
+        },
+    });
+    return {
+        middleware,
+        tools: [evalCode, runScript],
+        executor,
+        dispose,
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/sandbox/tools.js.map

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

package/dist/sessions/operations.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The session operations an assembled agent carries — `sessions.list/get/
+ * delete/seed` over the configured session store, and the artifact emitter —
+ * governed or not. Assembly wires them; nothing here knows how the agent was composed.
+ */
+import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+import { type CompiledAgentGraph } from "../core/deepagents.js";
+import type { WorkflowEventEmitter } from "../core/events.js";
+import { type SessionStore } from "../core/session-store.js";
+import { type UsageTracker } from "../core/usage.js";
+import { Workspace } from "../core/workspace.js";
+import { type MountPrefixes } from "../core/zones.js";
+import type { WorkflowMachine } from "../machine/machine.js";
+import type { MachineSpec } from "../machine/types.js";
+import type { ResolvedRuntimeContract } from "../runtime/contract.js";
+import { describeMachineTopology, type Trajectory } from "../workflow/session-artifacts.js";
+import { type TrailStep } from "../workflow/state.js";
+import { type SessionSummary } from "./summary.js";
+export { describeMachineTopology };
+/**
+ * Session handles over the configured session store — the supported
+ * alternative to manipulating a store's `<sessionId>/…` folders directly.
+ */
+export interface SessionOperations {
+    /**
+     * Enumerate durable sessions, projected from each session's latest checkpoint.
+     * Empty when the checkpointer or store cannot enumerate sessions (an ephemeral
+     * `MemorySaver`, a backend store without listing capability).
+     */
+    list(): Promise<SessionSummary[]>;
+    /** A single session's summary, or `null` when no such session exists. */
+    get(sessionId: string): Promise<SessionSummary | null>;
+    /**
+     * How many messages the session's transcript holds, from its latest checkpoint;
+     * `0` for a session that has not run. A **cursor**: read it before a turn and
+     * hand it to `messagesSince(messages, cursor)` afterwards to slice exactly what
+     * that turn appended — seeds, notes and all — without counting them yourself.
+     */
+    messageCount(sessionId: string): Promise<number>;
+    /**
+     * Remove all of a session's state — checkpoints, artifacts, scratchpad — through
+     * the session store, and evict it from the live checkpointer. Returns whether
+     * anything was removed. Throws `SessionStoreCapabilityError` when the store
+     * cannot delete.
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Seed input files into a session's workspace through the store. Keys are
+     * workspace-relative paths classified against the assembly's mounts: only
+     * agent-visible session paths (root-level files like `trigger.json`, plus
+     * `scratchpad/…`) are seedable, and one bad path seeds nothing. Strings are
+     * written verbatim, other values as pretty-printed JSON; existing files are overwritten.
+     */
+    seed(sessionId: string, files: Record<string, unknown>): Promise<void>;
+}
+/** Persist a session's graph snapshot, trajectory, trail, variables and metadata. */
+export type EmitRunArtifacts = (sessionId: string, trajectory: Trajectory, opts?: {
+    trail?: TrailStep[];
+}) => Promise<string | null>;
+export declare function createSessionOperations(deps: {
+    checkpointer: BaseCheckpointSaver;
+    sessionStore: SessionStore;
+    /** The agent's workspace — its root, outside a bound session, is the raw store root. */
+    workspace: Workspace;
+    mountPrefixes: MountPrefixes;
+    dispose: (sessionId: string) => void;
+}): SessionOperations;
+export declare function createArtifactEmitter(deps: {
+    graph: CompiledAgentGraph;
+    /** The governing machine, or `null` for a plain assembly. */
+    machine: WorkflowMachine | null;
+    workspace: Workspace;
+    workflowName: string;
+    runtimeContract: ResolvedRuntimeContract;
+    usage: UsageTracker;
+    emit: WorkflowEventEmitter;
+}): EmitRunArtifacts;
+/** Resolve a persisted machine spec by its `specHash`, or `null`. */
+export declare function createSpecSnapshotReader(workspace: Workspace): (hash: string) => Promise<MachineSpec | null>;

package/dist/sessions/operations.js

@@ -0,0 +1,121 @@
+import { asDecisionGraph } from "../core/deepagents.js";
+import { SessionStoreIdError, sessionIdRejection } from "../core/session-store.js";
+import { hasUsage } from "../core/usage.js";
+import { canonicalizeRelPath, Workspace } from "../core/workspace.js";
+import { classifyWorkspacePath } from "../core/zones.js";
+import { PACKAGE_VERSION } from "../env.js";
+import { BackendCheckpointSaver } from "../workflow/checkpointer.js";
+import { describeMachineTopology, serializeGraph, serializeMachineGraph, writeRunArtifacts, } from "../workflow/session-artifacts.js";
+import { readSpecSnapshot } from "../workflow/snapshot.js";
+import { readAuditTrail, readRunUsage, readVariables } from "../workflow/state.js";
+import { listSessions, summarizeCheckpointedSession } from "./summary.js";
+export { describeMachineTopology };
+export function createSessionOperations(deps) {
+    const { checkpointer, sessionStore, workspace, mountPrefixes, dispose } = deps;
+    return {
+        list: () => checkpointer instanceof BackendCheckpointSaver && sessionStore.capabilities.list
+            ? listSessions(workspace, checkpointer)
+            : Promise.resolve([]),
+        // One session's projection via `getTuple` alone, so it works for any
+        // checkpointer — it must: `null` means "this session has not run yet", and
+        // resolution would then treat a live session's next turn as its first.
+        get: (sessionId) => summarizeCheckpointedSession(checkpointer, sessionId),
+        messageCount: async (sessionId) => {
+            const tuple = await checkpointer.getTuple({ configurable: { thread_id: sessionId } });
+            const messages = tuple?.checkpoint.channel_values?.messages;
+            return Array.isArray(messages) ? messages.length : 0;
+        },
+        delete: async (sessionId) => {
+            // Evict live checkpointer state first so a deleted session cannot be resumed
+            // from memory, then remove the persisted namespace through the store.
+            await checkpointer.deleteThread(sessionId);
+            const removed = await sessionStore.deleteSession(sessionId);
+            dispose(sessionId);
+            return removed;
+        },
+        seed: async (sessionId, files) => {
+            const idRejection = sessionIdRejection(sessionId, mountPrefixes);
+            if (idRejection)
+                throw new SessionStoreIdError(sessionId, idRejection);
+            const id = sessionId.replace(/^\/+/, "");
+            // Validate every path before writing any.
+            const entries = Object.entries(files).map(([path, value]) => {
+                const canonical = canonicalizeRelPath(path);
+                const zone = classifyWorkspacePath(path, mountPrefixes);
+                if (zone !== "run" && zone !== "run-open") {
+                    throw new Error(`Cannot seed ${JSON.stringify(path)}: it resolves to the '${zone}' zone. ` +
+                        `Seedable paths are agent-visible session files (e.g. 'trigger.json', 'scratchpad/…').`);
+                }
+                const contents = typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`;
+                return [canonical.path, contents];
+            });
+            // Address the store as `<sessionId>/…` explicitly, like the checkpointer.
+            const store = new Workspace(sessionStore.backend);
+            for (const [path, contents] of entries) {
+                const key = `${id}/${path}`;
+                try {
+                    await store.writeText(key, contents);
+                }
+                catch (err) {
+                    // A create-only backend refuses to overwrite; replace the whole content
+                    // through `edit` instead (seeding is idempotent).
+                    const existing = await store.readText(key);
+                    if (existing == null)
+                        throw err;
+                    if (existing !== contents)
+                        await store.editText(key, existing, contents);
+                }
+            }
+        },
+    };
+}
+export function createArtifactEmitter(deps) {
+    const { graph, machine, workspace, workflowName, runtimeContract, usage, emit } = deps;
+    return async (sessionId, trajectory, opts) => {
+        // One checkpoint read serves the trail, the usage and the variables.
+        // `undefined` means unreadable — distinct from a checkpoint that holds
+        // nothing: an empty trail.json must mean "no transitions", never "unreadable".
+        async function readCheckpointValues() {
+            try {
+                const snapshot = await asDecisionGraph(graph).getState({ configurable: { thread_id: sessionId } });
+                return snapshot?.values;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        // A governed session's graph is the machine's own topology; a plain agent
+        // has only its compiled graph.
+        const [serialized, values] = await Promise.all([
+            machine ? serializeMachineGraph(machine) : serializeGraph(graph),
+            machine ? readCheckpointValues() : undefined,
+        ]);
+        const trail = machine
+            ? (opts?.trail ?? (values !== undefined ? readAuditTrail(values) : undefined))
+            : undefined;
+        // Usage comes from the checkpoint when there is one (a session resumed in
+        // another process would otherwise report only this process's share); the
+        // in-memory tracker is the fallback.
+        const checkpointed = values !== undefined ? readRunUsage(values) : undefined;
+        const sessionUsage = checkpointed && hasUsage(checkpointed) ? checkpointed : usage.totals(sessionId);
+        // An empty store is still recorded: "took no seeded input" is a fact.
+        const variables = machine && values !== undefined ? readVariables(values) : undefined;
+        return writeRunArtifacts(workspace, workflowName, sessionId, {
+            graph: serialized,
+            trajectory,
+            metadata: {
+                runtimeContract,
+                packageVersion: PACKAGE_VERSION,
+                ...(machine ? { specHash: machine.specHash } : {}),
+                ...(hasUsage(sessionUsage) ? { usage: sessionUsage } : {}),
+            },
+            ...(trail ? { trail } : {}),
+            ...(variables !== undefined ? { variables } : {}),
+        }, emit);
+    };
+}
+/** Resolve a persisted machine spec by its `specHash`, or `null`. */
+export function createSpecSnapshotReader(workspace) {
+    return (hash) => readSpecSnapshot(workspace, hash);
+}
+//# sourceMappingURL=operations.js.map

package/dist/sessions/operations.js.map

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

package/dist/sessions/resolve.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Session resolution: given a firing, decide how it lands on its session —
+ * without invoking the graph or any model.
+ *
+ * The rule: **a session whose turn has finished takes its next turn on the same
+ * session, continuing from the state it is in; a session whose turn is still
+ * open resumes from the state where it parked.** A session is extended, never
+ * copied, so there is one id and nothing to map it to. A mid-turn session fails
+ * closed: a competing turn would break the checkpointer's single-writer guarantee.
+ */
+import type { WorkflowMachine } from "../machine/machine.js";
+import { type SessionPath } from "../machine/triggers.js";
+import type { SessionSummary } from "./summary.js";
+/**
+ * How a firing lands on its session: it opens a `turn`, it `resume`s the state
+ * the session parked in, or — a session parked at a human state — it is a `reply`,
+ * answered without moving the run.
+ */
+export type SessionDisposition = "turn" | "resume" | "reply";
+export interface ResolvedSession {
+    /** The session to invoke (`turn`) or deliver to (`resume`) — the only id there is. */
+    sessionId: string;
+    disposition: SessionDisposition;
+    /**
+     * `turn` only: where the turn begins — the retained position of a session that
+     * already has one, else the entry state the firing's trigger declares.
+     */
+    startState?: string;
+    /**
+     * `resume` and `reply` only: the state the session is parked at — the one a
+     * delivery resumes, or the human state a message is answered at.
+     */
+    state?: string;
+    /** @deprecated Use {@link ResolvedSession.state}; kept for one release. */
+    node?: string;
+    /** Whether the id was minted for this session because the firing declared none. */
+    native: boolean;
+}
+/**
+ * Thrown when a firing maps to a session whose turn is still in progress: a
+ * session has a single writer, so the firing must wait. A human-parked session
+ * is *not* this case — it resolves to `reply`.
+ */
+export declare class SessionNotResumableError extends Error {
+    readonly sessionId: string;
+    readonly status: string | undefined;
+    constructor(sessionId: string, status: string | undefined);
+}
+/** Thrown when a firing names a trigger no state of the workflow declares. */
+export declare class UnknownSessionTriggerError extends Error {
+    readonly trigger: string;
+    constructor(trigger: string);
+}
+/** What the caller supplies for one firing. */
+export interface ResolveSessionInput {
+    trigger?: {
+        id: string;
+    };
+    /** The variables the firing carries — the same map an invoke or delivery seeds. */
+    variables?: Record<string, unknown>;
+    /** An explicit id, taking precedence over every path. */
+    sessionId?: string;
+    /**
+     * Where to read the id from for this firing — the same dotted path a
+     * `triggers` entry declares (`triggers.-1.conversationId`), overriding what
+     * the workflow says.
+     */
+    sessionPath?: string;
+}
+/** The lookups resolution needs from the runtime, kept injectable for testing. */
+export interface SessionLookup {
+    /** The session's state, projected from its own checkpoint — or `null` when the id names no session yet. */
+    findSession(sessionId: string): Promise<SessionSummary | null>;
+    /** Mint an id for a firing that declares no session of its own. */
+    mintSessionId(): string;
+}
+/**
+ * Derive a firing's session id: the explicit one, else the invoking trigger's
+ * declared path resolved over the firing's variables, else a minted id (the
+ * firing is its own session). Every turn belongs to exactly one session.
+ */
+export declare function deriveSessionId(path: SessionPath | undefined, input: ResolveSessionInput, nativeId: string): {
+    sessionId: string;
+    native: boolean;
+    unresolvedPath?: SessionPath;
+};
+/**
+ * Resolve and classify a firing. Never invokes the graph: the caller decides
+ * whether to start the run or deliver into it.
+ */
+export declare function resolveSession(machine: WorkflowMachine, lookup: SessionLookup, input: ResolveSessionInput, onWarning?: (message: string) => void): Promise<ResolvedSession>;
+/** Thrown when a caller-supplied session path is not a usable dotted path. */
+export declare class InvalidSessionPathError extends Error {
+    readonly path: string;
+    readonly reason: string;
+    constructor(path: string, reason: string);
+}