@stigmer/runner 3.15.1 → 3.15.2-dev.20260913223433

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

@@ -0,0 +1,146 @@
+/**
+ * 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 status; the interrupts a completed
+ * stream left pending seeded 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`); 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; S3 M4). It does mutate `sink.status`'s transcript rows, which
+ * are this harness's to write.
+ *
+ * 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, Q-M4-8).
+ *
+ * Moved from `index.ts` (post-stream through the terminal arms) at S3 M2a;
+ * the capture boundary left for the runtime at M4.
+ */
+import { create } from "@bufbuild/protobuf";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { POLICY_ENGINE_VERSION, toProtoPolicySource } from "../../shared/approval-policy.js";
+import { utcTimestamp } from "../../shared/status.js";
+import { cancelInProgressSubAgentProtos } from "../../shared/subagent-rows.js";
+import { classifyTool } from "../../shared/tool-kind.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 { status } = sink;
+    // Drain the publishes the stream fired (fire-and-forget completions); the
+    // safety net that scans tool calls for files the stream missed runs only
+    // on a finished turn, as it always did.
+    if (stream.pendingPublishPromises.length > 0) {
+        await Promise.allSettled(stream.pendingPublishPromises);
+    }
+    if (stream.reason === "completed") {
+        try {
+            await autoPublishWrittenFiles(status, 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 (DD-014): 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(status, 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), its messages'
+        // streaming flags cleared. There is no review to open.
+        cancelInProgressSubAgentProtos(status.subAgentExecutions);
+        transcript.builder.finalizeSubAgentStreaming();
+        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)) {
+            status.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" };
+}
+/**
+ * Seed one WAITING_APPROVAL row per interrupt the graph left pending, on one
+ * AI message, with the sanitized args preview AND 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). Returns whether any was seeded.
+ */
+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`);
+    const aiMsg = create(AgentMessageSchema, {
+        type: MessageType.MESSAGE_AI,
+        content: "",
+        timestamp: utcTimestamp(),
+        isStreaming: false,
+    });
+    for (const intr of pending) {
+        const toolCall = create(ToolCallSchema, {
+            id: intr.toolCallId,
+            name: intr.toolName,
+            status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+            requiresApproval: true,
+            approvalMessage: intr.message,
+            approvalRequestedAt: utcTimestamp(),
+            mcpServerSlug: intr.mcpServerSlug,
+            startedAt: utcTimestamp(),
+            toolKind: classifyTool(intr.toolName, intr.mcpServerSlug),
+            approvalPolicySource: toProtoPolicySource(intr.policySource),
+            policyEngineVersion: intr.policySource ? POLICY_ENGINE_VERSION : "",
+        });
+        const { argsPreview, args } = captureApprovalArtifacts({ toolCallId: intr.toolCallId, messages: aiMessages });
+        if (argsPreview)
+            toolCall.argsPreview = argsPreview;
+        if (args)
+            toolCall.args = args;
+        aiMsg.toolCalls.push(toolCall);
+    }
+    sink.status.messages.push(aiMsg);
+    return true;
+}
+//# 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,212 @@
+/**
+ * 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 and approval policies are merged, 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 approval
+ * gate over the runtime's policies; the compiled sub-agents; 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 (Q-S3-8): 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) at S3 M2a; 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 ModelPricing } from "../../shared/model-pricing.js";
+import { type MergedToolPolicy } from "../../shared/approval-policy.js";
+import type { ToolApprovalCategory } from "../../shared/tool-kind.js";
+import type { RecalledMemoriesContent } from "../../shared/recalled-memories.js";
+import { CasCaptureObserver } from "./cas-capture-observer.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 (S3 M2a, F-M2a-10).
+ */
+export type DeepAgentAdapterConfig = Pick<Config, "checkpointerType" | "checkpointerProxyEndpoint" | "stigmerToken" | "proxyEndpoint" | "mode">;
+/** 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;
+    readonly mcpTools: readonly DynamicStructuredTool[];
+    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 {
+    readonly policies: ReadonlyMap<string, MergedToolPolicy>;
+    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 (DD-014): the gate auto-skips instead of interrupting. */
+    readonly unattended: boolean;
+    /** Tool-call ids the gate auto-skipped this turn; written by the gate, read by `reconcileUnattendedSkips`. */
+    readonly unattendedSkips: Set<string>;
+}
+/** 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, the thinking heuristic, 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: what the execution asked for, as the
+ * runtime already resolved it (`input.model.requested`, `"default"` when the
+ * spec named none — the one reader of `spec.executionConfig.modelName`, which
+ * the Cursor adapter reads too), 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 S3 M5 this
+ * read the spec field beside the runtime's resolved copy; F-M3-P7.)
+ */
+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
+ * (Q-S3-8). The platform dir the shared provision ensured rides along so
+ * the backend routes `.stigmer/…` reads to it.
+ *
+ * CAS capture (design docs 08/11/12): 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)
+ * into LangChain tools. 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?" (S3 M2a, F-M2a-17).
+ */
+export declare function connectTools(input: TurnInput, sink: TurnSink): Promise<DeepAgentTools>;
+/**
+ * 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 shaped the runtime's policy
+ * map (leased servers dropped); 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 `## Skills` section of the root prompt: the skills the shared selection
+ * highlights for this turn's message (`shared/prompt-sections.ts`
+ * `selectSkillsForPrompt`: every skill below the threshold, the relevant ones
+ * at and above it), rendered with this engine's activation protocol, plus —
+ * when the selection left any out — an `### Also Available` note naming them
+ * (the sentence is the shared, tool-neutral one; the heading is this
+ * harness's markdown framing).
+ */
+export declare function renderRootSkillsSection(input: TurnInput): string;
+/**
+ * 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).
+ */
+export declare function composeSystemPrompt(input: TurnInput, recalledMemories: RecalledMemoriesContent | undefined): 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 resolved ONCE by the runtime rides 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).
+ * `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 (Q-S3-3, landed at S3 M2b):
+ * 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 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 — the conversation catchup
+ * framed before it (cloud DD-006; in the USER MESSAGE so it enters the
+ * checkpointer with the turn), 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).
+ */
+export declare function composeGraphInput(input: TurnInput, engine: DeepAgentEngine): Promise<DeepAgentGraphInput>;