@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/activities/execute-deep-agent/turn-settle.js

@@ -0,0 +1,141 @@
+/**
+ * The native deep-agent harness's settle — from a consumed stream to a
+ * `TurnOutcome`.
+ *
+ * In order: drain the inline publishes the stream fired and, on a finished
+ * turn, run the auto-publish safety net; settle the gate's unattended skips
+ * (the one settlement whose evidence exists only inside this harness); on
+ * the runtime's stop, mark in-flight sub-agent rows through the shared act
+ * and settle `interrupted` with nothing further; the graph's
+ * `structuredResponse` folded onto the rows; the interrupts a completed
+ * stream left pending proposed through the builder as WAITING rows; and the
+ * outcome.
+ *
+ * What this module never does: write a phase, a terminal copy or
+ * `completedAt` — those are the runtime's (`harness/run-turn.ts`,
+ * `terminal-table.ts`); close the transcript's streaming flags — the
+ * runtime's, once `runTurn` returns, on every path (since #1097; until then this
+ * settle finalized the builder itself, and a turn that threw before
+ * reaching it left its last message streaming); settle SKIP and REJECT rows — the runtime's
+ * (`harness/approval-decisions.ts`, after every outcome); withhold secret
+ * content — the runtime's chokepoint does it on every write; finalize the
+ * write-back — the runtime's epilogue; capture the turn's file changes or
+ * decide whether a review is pending — the runtime's (`harness/capture.ts`,
+ * once, over whatever the whole turn left on the tree, after this settle
+ * returns; since #1096). Transcript rows it CREATES go through the builder
+ * (`approval_proposed`, since #1097); the one row it AMENDS by identity is the
+ * gate's unattended skip (`reconcileUnattendedSkips`), whose evidence exists
+ * only inside this harness.
+ *
+ * The structured response is folded BEFORE the outcome is decided, so a turn
+ * the runtime then pauses for file review persists it and the pure
+ * file-review resume completes with it (the runtime's text fallback runs on
+ * the review-pending path too).
+ *
+ * Moved from `index.ts` (post-stream through the terminal arms) in #1096,
+ * where the capture boundary also left for the runtime.
+ */
+import { cancelInProgressSubAgentProtos } from "../../shared/subagent-rows.js";
+import { redactSensitiveArgs } from "../../shared/args-preview.js";
+import { captureApprovalArtifacts } from "./approval-file-change.js";
+import { autoPublishWrittenFiles } from "./auto-publish.js";
+import { detectPendingInterrupts, reconcileUnattendedSkips } from "./hitl.js";
+export async function settleDeepAgentTurn(deps) {
+    const { input, sink, engine, transcript, stream } = deps;
+    const { executionId } = input;
+    const { rows } = sink;
+    // Drain the publishes the stream fired (fire-and-forget completions) BEFORE
+    // the safety net: its publisher skips a file only when the file's row is
+    // already on the status, so an upload still in flight would be sent twice.
+    // The net scans tool calls for files the stream missed and runs only on a
+    // finished turn, as it always did.
+    await transcript.sideEffects.drainPublishes();
+    if (stream.reason === "completed") {
+        try {
+            await autoPublishWrittenFiles(rows, transcript.publisher);
+        }
+        catch (err) {
+            console.warn(`[turn-settle] execution=${executionId} — auto-publish safety net error: ${err}`);
+        }
+    }
+    sink.recordActivity();
+    // Terminalize every tool call the gate auto-skipped under UNATTENDED
+    // approval mode: the skip has no human decision behind it, so the
+    // runtime's terminalizer cannot see it; the gate's registry is this
+    // harness's evidence.
+    reconcileUnattendedSkips(rows, engine.gate.unattendedSkips);
+    if (stream.reason === "interrupted") {
+        // A stopped turn aborted the graph run, so any sub-agent the parent had
+        // delegated is no longer executing: CANCELLED through the one shared act
+        // (the runtime marks them itself only on its thrown arms). There is no
+        // review to open.
+        cancelInProgressSubAgentProtos(rows.subAgentRuns);
+        return { kind: "interrupted" };
+    }
+    // The graph's structured response, when the run surfaced one: folded now,
+    // so a turn the runtime pauses for review persists it and the pure
+    // file-review resume completes with it.
+    if (engine.hasStructuredOutput) {
+        const sr = stream.runOutput?.structuredResponse;
+        if (sr != null && typeof sr === "object" && !Array.isArray(sr)) {
+            rows.structuredOutput = sr;
+        }
+        else if (sr !== undefined) {
+            console.warn(`[turn-settle] structuredResponse is not a plain object for execution ${executionId}: type=${typeof sr}`);
+        }
+    }
+    if (stream.reason === "awaiting_approval") {
+        return { kind: "awaiting_approval" };
+    }
+    // A completed stream can still leave the graph interrupted at a gate whose
+    // tool start produced no row (the durable savers resume without a
+    // tool_started; the replay path never re-drives it): read the checkpoint
+    // once more and seed a WAITING row per pending interrupt. Skipped under
+    // the global bypass, where no gate is installed.
+    if (!engine.gate.globalBypass && (await seedPendingInterrupts(deps))) {
+        return { kind: "awaiting_approval" };
+    }
+    return { kind: "completed" };
+}
+/**
+ * Propose, through the builder, one approval per interrupt the graph left
+ * pending — the gate's hold reaching the transcript as `approval_proposed`
+ * (since #1097). LangGraph's `interrupt()` ran before the tool
+ * handler, so the stream showed no row for the call; the builder creates
+ * the WAITING row on the message whose text proposed it, with the redacted
+ * args read from the AI message in graph state (the single source of truth
+ * for the proposed call; issue #754: a placeholder without args rendered a
+ * pathless header). Until #1097 this settle built the message and the rows
+ * itself, on a new empty AI message of its own, with no by-id check against
+ * rows the stream had created (the upsert closes it).
+ * Returns whether any was proposed.
+ */
+async function seedPendingInterrupts(deps) {
+    const { input, sink, engine } = deps;
+    const graphState = await engine.graph.getState(engine.langgraphConfig);
+    const pending = detectPendingInterrupts(graphState);
+    if (pending.length === 0)
+        return false;
+    const graphMessages = graphState.values.messages;
+    const aiMessages = Array.isArray(graphMessages) ? graphMessages : [];
+    console.log(`[turn-settle] Detected ${pending.length} pending interrupt(s) for execution ${input.executionId} — awaiting approval`);
+    for (const intr of pending) {
+        // A hook's rewrite is what an approval lets run, so the card shows it;
+        // otherwise the model's own arguments, read from graph state.
+        const { args } = intr.args !== undefined
+            ? { args: redactSensitiveArgs(intr.args) }
+            : captureApprovalArtifacts({ toolCallId: intr.toolCallId, messages: aiMessages });
+        sink.transcript.apply({
+            kind: "approval_proposed",
+            callId: intr.toolCallId,
+            name: intr.toolName,
+            mcpServerSlug: intr.mcpServerSlug,
+            message: intr.message,
+            ...(args ? { args } : {}),
+            ...(intr.policySource ? { provenance: intr.policySource } : {}),
+            ...(intr.policyHook !== undefined ? { policyHook: intr.policyHook } : {}),
+        });
+    }
+    return sink.transcript.awaitingApproval;
+}
+//# sourceMappingURL=turn-settle.js.map

package/dist/activities/execute-deep-agent/turn-settle.js.map

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

package/dist/activities/execute-deep-agent/turn-setup.d.ts

@@ -0,0 +1,281 @@
+/**
+ * The native deep-agent harness's setup — what the LangGraph engine needs
+ * before it can run a turn, as small named steps over the runtime's resolved
+ * `TurnInput`, each returning a typed slice (the Cursor adapter's
+ * `turn-setup.ts` mold; never one long function).
+ *
+ * Everything harness-agnostic has already happened when these run: the
+ * execution, session and blueprint are fetched, the workspace is provisioned
+ * and locked, the MCP servers are resolved with the approval default's MCP
+ * half and the agent's tool scope, the skills
+ * are mounted per owner, the attachments are resolved, the transcript is
+ * seeded. What remains is this engine's own reading of that record: the
+ * checkpointer; the deepagents backend and the CAS observer, rooted at the
+ * tree the runtime locked; the MCP connection that turns resolved servers
+ * into LangChain tools; the model; the middleware stack with the tool scope
+ * and the approval gate over the runtime's default; the compiled
+ * sub-agents, each under its own narrowed scope; the system
+ * prompt and the user message; `createDeepAgent`; and the checkpoint read
+ * that decides between a `Command(resume)` and a fresh message. The
+ * file-review capture is the runtime's (`harness/capture.ts`); this harness
+ * hands it only what its CAS observer saw (`turn.ts`).
+ *
+ * Every step reads `TurnInput` and the sink and nothing else of the
+ * runtime's. The `execution_setup` cold-start line is emitted here, once the
+ * graph exists, over the runtime's timeline (`sink.setupTiming`), so the one
+ * timeline reads end to end. The three progress labels only this harness
+ * knows are reported through the sink exactly as the orchestrator reported
+ * them (the resolution labels are the runtime's).
+ *
+ * One root for everything: the deepagents backend, the CAS
+ * observer, the gate's path normalization and the publisher are all rooted
+ * at `workspace.primaryDir` — the same tree the runtime locks, links and
+ * captures. For zero or one workspace entry this is byte-identical to the
+ * orchestrator's `workspaceBackend.rootDir`.
+ *
+ * Moved from `setup.ts` `performSetup` (the LangGraph half; the resolution
+ * half is the runtime's twelve phases) in #1096; the step bodies are the
+ * orchestrator's, verbatim where nothing changed.
+ */
+import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+import type { DynamicStructuredTool } from "@langchain/core/tools";
+import type { Command } from "@langchain/langgraph";
+import type { Config } from "../../config.js";
+import type { TurnInput, TurnSink } from "../../harness/types.js";
+import type { WorkspaceBackend } from "../../shared/workspace/types.js";
+import { type McpConnectionResult } from "../../shared/mcp-manager.js";
+import type { PersonRefusal } from "../../middleware/approval-gate.js";
+import { type ModelPricing } from "../../shared/model-pricing.js";
+import { type McpApprovalDefault } from "../../shared/approval-policy.js";
+import type { McpToolListing } from "../../shared/mcp-tool-listing.js";
+import { type ToolScope, type TurnToolInventory } from "../../shared/tool-lists.js";
+import type { ToolApprovalCategory } from "../../shared/tool-kind.js";
+import type { RecalledMemoriesContent } from "../../shared/recalled-memories.js";
+import { CasCaptureObserver } from "./cas-capture-observer.js";
+import { ApprovalAction } from "../../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+/**
+ * The runner config this harness reads per turn, as a named slice
+ * (`execute-cursor/turn-setup.ts` `CursorAdapterConfig` is the idiom): a
+ * whole `Config` satisfies it, a test constructs these fields and nothing
+ * else. Smaller than the orchestrator's reach — the synthesized attachments'
+ * endpoints it read are the runtime's now (since #1096).
+ */
+export type DeepAgentAdapterConfig = Pick<Config, "checkpointerType" | "checkpointerProxyEndpoint" | "stigmerTokenRef" | "proxyEndpoint" | "mode" | "cursorStreamStallTimeoutMs">;
+/** The deepagents graph as this module holds it; deepagents exports no stable type for the compiled agent. */
+export type AgentGraph = any;
+/** The workspace as this engine sees it: one backend and one CAS observer, both rooted at the runtime's primary tree. */
+export interface DeepAgentWorkspace {
+    readonly backend: WorkspaceBackend;
+    readonly casObserver: CasCaptureObserver;
+    /** Git-tracked capturability, consulted by the gate to route a file write to git-diff (tracked) vs CAS (ignored). */
+    readonly isCapturablePath: (rawPath: string) => Promise<boolean>;
+}
+/** The tool surface once connected: LangChain tools plus the tool → server map the builders attribute by. */
+export interface DeepAgentTools {
+    /** Absent when the turn has no servers to connect: `MultiServerMCPClient` refuses an empty config. */
+    readonly connection: McpConnectionResult | undefined;
+    /** The main agent's MCP tools: its servers' (the platform's own included), never a server only a subagent has. */
+    readonly mcpTools: readonly DynamicStructuredTool[];
+    /** Every connected server's tools, the subagents' servers included, by slug. */
+    readonly serverToolMap: ReadonlyMap<string, readonly DynamicStructuredTool[]>;
+    readonly toolServerMap: ReadonlyMap<string, string>;
+}
+/** The gate's posture for this turn, read once and shared by the builders, the reconciler and the sub-agents. */
+export interface DeepAgentGateState {
+    /** The approval default's MCP half: which MCP tools ask, and which servers a lease cleared. */
+    readonly mcpDefault: McpApprovalDefault;
+    readonly toolServerMap: ReadonlyMap<string, string>;
+    readonly leasedCategories: ReadonlySet<ToolApprovalCategory>;
+    /** Pre-armed spec.auto_approve_all — the one unscoped, whole-run bypass; the gate is not installed under it. */
+    readonly globalBypass: boolean;
+    /** Unattended approval mode: the gate auto-skips instead of interrupting. */
+    readonly unattended: boolean;
+    /** Tool-call ids the gate auto-skipped this turn, each with the hook whose ask it was (`null`: the default's); written by the gate, read by `reconcileUnattendedSkips`. */
+    readonly unattendedSkips: Map<string, string | null>;
+    /** The calls a person skipped or rejected among the decisions this turn resumes with. */
+    readonly refusedByPerson?: ReadonlyMap<string, PersonRefusal>;
+}
+/** The engine this turn runs on and everything the stream and the settle read from it. */
+export interface DeepAgentEngine {
+    readonly graph: AgentGraph;
+    readonly checkpointer: BaseCheckpointSaver;
+    readonly langgraphConfig: Record<string, unknown>;
+    /** The registry id the turn runs on (pricing and sub-agent inheritance key on it). */
+    readonly modelName: string;
+    readonly pricing: ModelPricing;
+    readonly gate: DeepAgentGateState;
+    readonly hasStructuredOutput: boolean;
+}
+/** What the graph is invoked with: a resume of the paused gate, or the turn's user message. */
+export type DeepAgentGraphInput = {
+    readonly kind: "resume";
+    readonly command: Command;
+} | {
+    readonly kind: "message";
+    readonly input: Record<string, unknown>;
+};
+/**
+ * The registry id the turn runs on: the model the turn's resolved settings
+ * name, as the runtime already read it (`input.model.requested`, `"default"` when the
+ * turn's resolved settings name none — the runtime is the one reader of
+ * `status.runConfig.modelName`, and the Cursor adapter reads the same
+ * value), or the registry's default for `"default"`.
+ * The same reading the runtime's attachment phase made for the vision budget,
+ * so the model that sees the images is the model that runs. (Until #1096 this
+ * read the spec field beside the runtime's resolved copy.)
+ */
+export declare function resolveModelName(input: TurnInput): Promise<string>;
+/**
+ * The checkpoint saver. The durable local (sqlite) backend keys its file
+ * per session — a session has exactly one thread (`thread-{sessionId}`), so
+ * checkpoint lifetime tracks session lifetime. Opened per turn and closed
+ * in the adapter's `finally` (`turn.ts`).
+ */
+export declare function openCheckpointer(input: TurnInput, sink: TurnSink, config: DeepAgentAdapterConfig): Promise<BaseCheckpointSaver>;
+/**
+ * The workspace as the engine sees it, rooted at the runtime's primary tree
+ * (the one root). The platform dir the shared provision ensured rides along so
+ * the backend routes `.stigmer/…` reads to it.
+ *
+ * CAS capture: the single per-turn observer owns the
+ * before-bytes of first-touched CAS-owned paths AND the secret-blocked
+ * paths, keyed workspace-root-relative. Shared by the parent AND every
+ * sub-agent CAS backend, giving race-free first-touch-wins across
+ * concurrent graphs. In a git work tree it owns the .gitignored set only
+ * (git captures the tracked ones); in a non-git workspace it owns every
+ * touched path. Its ownership predicate is memoized, so `git check-ignore`
+ * runs at most once per distinct path.
+ */
+export declare function buildDeepAgentWorkspace(input: TurnInput): DeepAgentWorkspace;
+/**
+ * Connect the runtime's resolved servers (synthesized attachments included)
+ * and each saved subagent's servers into LangChain tools, each server once
+ * by slug: a server the main agent and a subagent both have is one
+ * connection. The main agent binds only its own servers' tools
+ * (`mcpTools`); a subagent's graph binds its own (`buildEngine`). The connect covers the whole fan-out — stdio servers
+ * spawn npx/uvx subprocesses here, so on-demand package installs land in
+ * this span. A turn with no servers connects nothing: `MultiServerMCPClient`
+ * refuses an empty config, which is what the orchestrator's MCP gate
+ * (`mcp-gate.ts`) guarded against beside its channel-only reason; the
+ * runtime resolves unconditionally, so the one remaining question is
+ * "anything to connect?" (since #1096).
+ */
+export declare function connectTools(input: TurnInput, sink: TurnSink): Promise<DeepAgentTools>;
+/** The connected tools of `servers`, in their order. */
+export declare function toolsOf(serverToolMap: ReadonlyMap<string, readonly DynamicStructuredTool[]>, servers: readonly {
+    readonly slug: string;
+}[]): DynamicStructuredTool[];
+/**
+ * What the tools this engine loaded say of themselves: each plugin server's
+ * tools whose own MCP annotation says `destructiveHint: true`
+ * (`@langchain/mcp-adapters` keeps a loaded tool's annotations on its
+ * `metadata`). The platform's own servers are never read: none of their
+ * tools asks. Read live every turn, so a tool its maker marks destructive
+ * asks first from the turn after the mark appears; a server that did not
+ * connect has no tools to call, so none is left unread.
+ */
+export declare function listingOfLoadedTools(serverToolMap: ReadonlyMap<string, readonly DynamicStructuredTool[]>, platformServerSlugs: ReadonlySet<string>): McpToolListing;
+/**
+ * The gate's posture. Two distinct bypasses (`shared/approval-policy.ts`
+ * `ActiveLeases`): the pre-armed spec.auto_approve_all is the one whole-run
+ * global bypass; an interactive APPROVE_ALL grants a run-lifetime lease
+ * scoped to that action's class. Server leases ride the runtime's approval
+ * default, completed here with the marks of the tools this engine loaded;
+ * built-in category leases are applied inside the gate. Both flow into
+ * sub-agents via the shared gate config.
+ */
+export declare function readGateState(input: TurnInput, tools: DeepAgentTools): DeepAgentGateState;
+/** The skip and reject decisions among a turn's resumed approvals, by tool-call id, each with the reason given. */
+export declare function refusalsOf(decisions: ReadonlyMap<string, ApprovalAction>, denyMessages?: ReadonlyMap<string, string>): ReadonlyMap<string, PersonRefusal>;
+/**
+ * The system prompt over the runtime's resolved record: every input the
+ * builder renders is read from `TurnInput` here, in one place, so the mapping
+ * is a pure step a test can pin whole (`__tests__/prompt-goldens.test.ts`
+ * calls exactly this) rather than a stretch of `buildEngine`. The one input
+ * that is not on the record is the memoized memory selection, which the
+ * caller awaits (the runtime stamps the report on the status the first time
+ * it is pulled, before this turn's first persist).
+ *
+ * Nothing here reads the turn's message or payload: the system prompt is the
+ * session's (`prompt-builder.ts` says why), so every mounted skill is
+ * described and the turn's files ride its message (`composeTurnMessage`).
+ * The approved plan's path is the one fact taken from the attachments, and
+ * only on a build-from-plan turn, where the mode already changes the prompt.
+ */
+export declare function composeSystemPrompt(input: TurnInput, recalledMemories: RecalledMemoriesContent | undefined): string;
+/**
+ * The turn's user message over the runtime's resolved record: what the user
+ * typed, with this turn's payload (its input files and referenced paths) and
+ * the conversation catchup composed around it (`prompt-builder.ts`
+ * `composeUserMessage`). The twin of `composeSystemPrompt` for the turn's
+ * half, so the goldens pin this mapping and not a copy of it.
+ */
+export declare function composeTurnMessage(input: TurnInput): string;
+/**
+ * Build the engine: the model, the middleware stack with the gate, the
+ * tools, the compiled sub-agents, the system prompt and `createDeepAgent`.
+ *
+ * The service tier and the thinking mode resolved ONCE by the runtime ride
+ * every model this execution constructs — the primary AND the sub-agent
+ * factory — so the provider account's default can never pick the price of
+ * any turn (#361), and every graph thinks in its own model's form.
+ * `max_tool_rounds` resolves to one recursion limit that feeds BOTH the hard
+ * stop on the invoke config and the budget middleware's ~80% advisory, so
+ * the warning and the enforcement can never disagree.
+ *
+ * Nothing in the middleware stack stops the run (since #1096):
+ * the runtime's abort is the platform's one stop, and its TERMINATED arm the
+ * one enforcement of `max_cost_usd`; the cost advisory warns the model at
+ * ~80% of the cap the way the budget middleware warns at ~80% of the
+ * recursion limit.
+ */
+export declare function buildEngine(input: TurnInput, sink: TurnSink, config: DeepAgentAdapterConfig, args: {
+    readonly modelName: string;
+    readonly checkpointer: BaseCheckpointSaver;
+    readonly workspace: DeepAgentWorkspace;
+    readonly tools: DeepAgentTools;
+    readonly gate: DeepAgentGateState;
+}): Promise<DeepAgentEngine>;
+/**
+ * What one graph of this turn has, for deciding whether a list entry names
+ * anything: its native built-ins and the live tools of the servers it binds
+ * (`boundServers`; every connected server when absent). The platform's own
+ * servers are left out: no list can name them.
+ */
+export declare function turnToolInventory(boundNames: readonly string[], tools: DeepAgentTools, platformServerSlugs: ReadonlySet<string>, boundServers?: readonly {
+    readonly slug: string;
+}[]): TurnToolInventory;
+/**
+ * Check the agent's lists (and the turn's over them) and each subagent's
+ * against what its graph binds: an entry naming nothing is logged, and a
+ * `tools` list that resolves to nothing throws `ToolListResolutionError`.
+ * A subagent's graph binds no to-do list. Only a subagent the main agent's
+ * `Agent(type, …)` admits is checked: one it keeps from compiling
+ * (`transformAndCompileSubagents` applies the same filter) can never run, so
+ * its lists cannot refuse the turn.
+ *
+ * A plugin subagent binds the parent's tools, and its lists are judged
+ * against the agent's layers alone, the prefix of the main scope before the
+ * turn's (`mainToolScope` puts the agent's first, and adds it only when it
+ * carries a list): the agent's definition is what they are written against,
+ * so a turn that narrows the agent, as an eval's read-only set does, never
+ * refuses the turn over a plugin subagent that lists only write or shell
+ * tools. The turn still narrows what it may use, since its graph runs
+ * under the whole scope. A saved subagent binds its own servers, and its
+ * own lists are judged against them alone, before the turn's cap.
+ */
+export declare function checkTurnToolLists(input: Pick<TurnInput, "mcp" | "blueprint" | "subagents">, tools: DeepAgentTools, parentScope: ToolScope, shellCapable: boolean): void;
+/**
+ * What the graph is invoked with. The checkpoint is read once (on the
+ * durable http saver an extra `getState` is a network round-trip): pending
+ * interrupts that the runtime's decisions answer make a `Command(resume)`;
+ * anything else is the turn's user message — this turn's payload and the
+ * conversation catchup framed before it (`composeTurnMessage`; in the USER
+ * MESSAGE so it enters the checkpointer with the turn and the system prompt
+ * stays the session's), the structured-output contract appended, and
+ * the inline images FIRST as content blocks when the turn carries any (per
+ * Anthropic's images-before-text guidance; a plain string otherwise). A
+ * eval-run try's recorded conversation goes ahead of that message when
+ * the thread holds none yet (`resumed-history.ts`).
+ */
+export declare function composeGraphInput(input: TurnInput, engine: DeepAgentEngine): Promise<DeepAgentGraphInput>;