@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/src/shared/mcp-resolver.ts

@@ -3,9 +3,8 @@
  * ResolvedMcpServer format.
  *
  * THE single resolver for both harnesses (oss#387 retired the Cursor
- * harness's near-duplicate): the deep-agent harness
- * (execute-deep-agent/setup.ts), the Cursor harness
- * (execute-cursor/index.ts), the connect backfill
+ * harness's near-duplicate): the turn runtime's MCP phase
+ * (harness/turn-context.ts, serving both adapters), the connect backfill
  * (shared/connect-backfill.ts), and the discovery activity
  * (activities/discover-mcp-server.ts, via mcpServerToResolved) all consume
  * it. Each harness maps the result into its SDK format at the last hop:
@@ -217,8 +216,8 @@ export function mcpServerToResolved(
  * - If both reference the same slug, session-level takes precedence —
  *   the WHOLE usage, including enabled_tools and approval overrides
  *
- * Shared by both harnesses (blueprint-resolver.ts for Cursor,
- * execute-deep-agent/setup.ts for the native harness) so a duplicate slug
+ * Shared by both harnesses (through blueprint-resolver.ts, the turn
+ * runtime's blueprint phase) so a duplicate slug
  * resolves identically everywhere: exactly one usage per server, whose
  * enabled_tools is the one the enforcement filter honors.
  */

package/src/shared/persist-decision.ts

@@ -1,10 +1,9 @@
 /**
  * Streaming persist decision for a harness turn.
  *
- * Harness-agnostic: the Cursor stream loop is today's only caller, the turn
- * runtime takes it over in S2 M3, and S3 retires the native twin below.
- *
- * Mirrors the native deep-agent harness (execute-deep-agent/streaming.ts):
+ * Harness-agnostic, and both adapters' stream loops read it
+ * (`execute-cursor/turn-stream.ts`, `execute-deep-agent/turn-stream.ts`; the
+ * native orchestrator's own copy of the rule retired with it at S3 M2b):
  * `shouldPersist = forceFlush || scheduler.shouldSendUpdate(eventCount)`.
  * Both harnesses thus share one cadence model — discrete state changes flush
  * immediately, high-frequency token deltas ride a bounded time cadence.

package/src/shared/plan-mode-permissions.ts

@@ -22,12 +22,12 @@
  * (shared/workspace/stigmer-link.ts), an in-root path string in either
  * dialect.
  *
- * Applied in execute-deep-agent/setup.ts to the parent graph AND threaded
+ * Applied in execute-deep-agent/turn-setup.ts to the parent graph AND threaded
  * into every compiled sub-agent graph: deepagents' parent-permission
  * inheritance covers only spec-style sub-agents, and ours are pre-built
  * CompiledSubAgents, so each sub-agent graph must carry the rules itself
  * (issue #255). Kept as its own side-effect-free module so tests can pin the
- * production rules without dragging in setup.ts's import graph.
+ * production rules without dragging in the engine build's import graph.
  *
  * Invariant: never combine these rules with a shell-capable (sandbox)
  * backend — deepagents rejects that pairing at graph construction (see the

package/src/shared/plan-mode-prompt.ts

@@ -16,7 +16,7 @@
  * is house style; the words are shared.
  *
  * Enforcement is separate from instruction: the native harness ALSO denies
- * filesystem writes at the tool layer (see execute-deep-agent/setup.ts), so
+ * filesystem writes at the tool layer (see execute-deep-agent/turn-setup.ts), so
  * for it this directive is guidance toward a well-formed plan, not the
  * enforcement mechanism. The Cursor harness has no tool-level lever (the
  * Cursor SDK exposes no mode parameter), so there this directive is the

package/src/shared/prompt-sections.ts

@@ -0,0 +1,256 @@
+/**
+ * The prompt glue both harnesses share: WHICH sections, in WHAT order, with
+ * WHICH lines — never the framing, never the placement.
+ *
+ * The doctrine is `plan-mode-prompt.ts`'s: "the framing is house style; the
+ * words are shared." Every section BODY already has one home
+ * (`sender-identity.ts`, `declared-preferences.ts`, `recalled-memories.ts`,
+ * `session-context.ts`, `context-bridge.ts`, `attachment-vision.ts`,
+ * `attachment-download-urls.ts`). What the two prompt builders duplicated
+ * until S3 M5 (Q-S3-10, Q-M2b-8) was the glue around those bodies: the order
+ * the five standing sections read in, with the same doctrine comments written
+ * twice; the input-files bullet and disclosure lines; which skills a prompt
+ * highlights when there are many. This module is that glue, written once.
+ *
+ * What stays with each harness, on purpose:
+ *  - Framing and placement. The native harness renders `## Heading` sections
+ *    into a system prompt rebuilt on every turn; the Cursor harness renders
+ *    `<xml_tag>` sections into the FIRST user message of a session
+ *    (`capabilities.systemPrompt` is the declared reason). Each builder maps a
+ *    section `kind` to its own label (`Record<StandingSectionKind, string>`,
+ *    exhaustive by the compiler) and wraps the body itself. This module never
+ *    learns a heading or a tag.
+ *  - Words that quote an engine's tools: the native `## Skills` activation
+ *    protocol (`read`, `execute(...)`) and Cursor's `<available_skills>` line
+ *    (`the Read tool`); the response rules; the sub-agent rules; the
+ *    structured-output directives (two mechanisms, two texts); Cursor's
+ *    tool-approval protocol, which exists because of Cursor's gate model and
+ *    would be false on a harness that interrupts before a tool runs.
+ *
+ * Fences: nothing under `shared/` imports `harness/` (and
+ * `harness/__tests__/import-direction.test.ts` forbids `shared/` reaching
+ * `activities/`), so every function here takes a plain struct that both
+ * builders' option objects satisfy structurally — never `TurnInput`. Pure:
+ * no I/O, no logging (a builder that wants to log what the selection did
+ * does so at its own call site).
+ */
+
+import type { ResolvedAttachment } from "./attachment-resolver.js";
+import { visionDisclosureLines, type NotViewableEntry } from "./attachment-vision.js";
+import { downloadUrlDisclosureLine, type DownloadUrlKind } from "./attachment-download-urls.js";
+import { formatContextBridgeText } from "./context-bridge.js";
+import { formatDeclaredPreferencesText, type DeclaredPreferencesContent } from "./declared-preferences.js";
+import { formatRecalledMemoriesText, type RecalledMemoriesContent } from "./recalled-memories.js";
+import { formatSenderIdentityText, type SenderIdentity } from "./sender-identity.js";
+import { formatSessionContextText } from "./session-context.js";
+import { filterSkills } from "./skill-relevance.js";
+import type { SkillMetadata } from "./skill-resolver.js";
+import { STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
+
+// ---------------------------------------------------------------------------
+// The standing context: five sections, one order
+// ---------------------------------------------------------------------------
+
+/**
+ * The standing sections a prompt may carry, in the order they read. A builder
+ * labels each kind in its own vocabulary; adding a kind here fails every
+ * builder's label map until it names the new section — the point of a closed
+ * union over a bag of optional fields.
+ */
+export type StandingSectionKind =
+  | "conversation-sender"
+  | "declared-preferences"
+  | "recalled-memories"
+  | "session-context"
+  | "previous-conversation";
+
+export interface StandingSection {
+  readonly kind: StandingSectionKind;
+  /** The section's words, from the body's own module; the builder frames them. */
+  readonly body: string;
+}
+
+/**
+ * The standing facts as both builders already hold them (their option
+ * objects satisfy this structurally). Every field optional: an absent value
+ * renders no section, so a runner predating a fact simply says nothing.
+ */
+export interface StandingPromptContext {
+  readonly senderIdentity?: SenderIdentity;
+  readonly declaredPreferences?: DeclaredPreferencesContent;
+  readonly recalledMemories?: RecalledMemoriesContent;
+  readonly sessionContext?: string;
+  readonly contextBridge?: string;
+}
+
+/**
+ * The present standing sections in the one ruled order. The order is the
+ * doctrine, stated once:
+ *
+ *  1. The conversation sender first: standing context about WHO the
+ *     conversation is with, which everything after may refer back to.
+ *  2. Platform-declared standing facts precede embedder-supplied context
+ *     (DD-002 D3): both are standing background, but the declared preferences
+ *     are platform-authored while session context is the embedder's overlay —
+ *     the more specific overlay reads later and naturally refines.
+ *  3. Declared-by-humans precedes learned-and-confirmed (DD-006 D4): both are
+ *     platform-authored standing background, but a preference is the user's
+ *     exact words while a memory is an agent's confirmed inference — the exact
+ *     statement reads first.
+ *  4. Standing facts about the user (session context) come before the carried
+ *     conversation (bridge): the bridge may refer back to them.
+ *
+ * Where the block sits in a prompt, and on which turns, is the builder's
+ * (native: every turn, the system prompt is rebuilt; Cursor: the session's
+ * first message, the agent's own store carries it after).
+ */
+export function standingContextSections(standing: StandingPromptContext): readonly StandingSection[] {
+  const sections: StandingSection[] = [];
+  if (standing.senderIdentity) {
+    sections.push({ kind: "conversation-sender", body: formatSenderIdentityText(standing.senderIdentity) });
+  }
+  if (standing.declaredPreferences) {
+    sections.push({ kind: "declared-preferences", body: formatDeclaredPreferencesText(standing.declaredPreferences) });
+  }
+  if (standing.recalledMemories) {
+    sections.push({ kind: "recalled-memories", body: formatRecalledMemoriesText(standing.recalledMemories) });
+  }
+  if (standing.sessionContext) {
+    sections.push({ kind: "session-context", body: formatSessionContextText(standing.sessionContext) });
+  }
+  if (standing.contextBridge) {
+    sections.push({ kind: "previous-conversation", body: formatContextBridgeText(standing.contextBridge) });
+  }
+  return sections;
+}
+
+// ---------------------------------------------------------------------------
+// The input files: the lines, not the frame
+// ---------------------------------------------------------------------------
+
+/**
+ * Which images ride the user message inline (in send order) and which
+ * degraded to the file-pointer story — the vision facts a prompt discloses
+ * beside its input files (`attachment-vision.ts` owns the wording). Derived
+ * per turn from the resolved attachments; never carried across turns.
+ */
+export interface VisionPromptInfo {
+  readonly inlineFilenames: readonly string[];
+  readonly notViewable: readonly NotViewableEntry[];
+}
+
+/**
+ * The vision facts as the runtime's attachment phase resolves them (the
+ * `TurnInput.attachments` shape, structurally): the inline images in send
+ * order and the ones that degraded. `undefined` when the turn has neither, so
+ * the section renders no vision lines at all rather than an empty disclosure.
+ */
+export function visionPromptInfoOf(attachments: {
+  readonly visionImages: readonly { readonly filename: string }[];
+  readonly visionNotViewable: readonly NotViewableEntry[];
+}): VisionPromptInfo | undefined {
+  if (attachments.visionImages.length === 0 && attachments.visionNotViewable.length === 0) return undefined;
+  return {
+    inlineFilenames: attachments.visionImages.map((v) => v.filename),
+    notViewable: attachments.visionNotViewable,
+  };
+}
+
+/** The input-files section's lines; the builder supplies the intro and the frame. */
+export interface InputFileLines {
+  /** One bullet per file: path, size, the rename disclosure, the download URL. */
+  readonly entries: readonly string[];
+  /** The URL hand-off line, present only when some listed file carries a URL. */
+  readonly urlHandoff: string | undefined;
+  /** The vision disclosure lines; empty when the turn carries no vision facts. */
+  readonly vision: readonly string[];
+}
+
+/**
+ * The input-files lines over the runtime's own `ResolvedAttachment` — one
+ * type, one truth (a structural twin once lived in each builder; native's
+ * silently dropped the size, Cursor's was deleted at S3 M5, Q-M5-5).
+ *
+ * Each bullet discloses the size (so the agent can weigh a read — the field's
+ * own stated purpose; Cursor's line gained it at S3 M5, Q-M5-3), the original
+ * name of a duplicate-renamed file (`attachment-naming.ts`; so the agent can
+ * connect "the two report.pdfs" in the user's message to distinct files on
+ * disk), and the download URL when one was minted
+ * (`attachment-download-urls.ts`; for the remote hand-off story). The URL
+ * hand-off line renders only when some listed file actually carries a URL —
+ * its wording keys on what kind of URL the storage backend mints. The vision
+ * lines tell the model which of these files it can already SEE inline versus
+ * which degraded to path-only; without them an agent silently ignores a photo
+ * the user believes it can see.
+ */
+export function inputFileLines(
+  files: readonly ResolvedAttachment[],
+  vision: VisionPromptInfo | undefined,
+  downloadUrlKind: DownloadUrlKind | undefined,
+): InputFileLines {
+  const entries = files.map((f) => {
+    const size = ` (${f.sizeBytes} bytes)`;
+    const rename = f.renamedFrom !== undefined ? ` (renamed from duplicate '${f.renamedFrom}')` : "";
+    const url = f.downloadUrl !== undefined ? ` — download URL: ${f.downloadUrl}` : "";
+    return `- \`${f.relativePath}\`${size}${rename}${url}`;
+  });
+  const urlHandoff =
+    downloadUrlKind !== undefined && files.some((f) => f.downloadUrl !== undefined)
+      ? downloadUrlDisclosureLine(downloadUrlKind)
+      : undefined;
+  return {
+    entries,
+    urlHandoff,
+    vision: vision ? visionDisclosureLines(vision.inlineFilenames, vision.notViewable) : [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The skills: which to highlight
+// ---------------------------------------------------------------------------
+
+/** Which mounted skills a prompt highlights, and which it only names. */
+export interface SkillSelection {
+  /** The skills the prompt describes in full, in the filter's order. */
+  readonly highlighted: readonly SkillMetadata[];
+  /** The names of the skills left out of the highlighted set; empty below the threshold. */
+  readonly alsoAvailable: readonly string[];
+}
+
+/**
+ * The relevance selection over the turn's message (`skill-relevance.ts`):
+ * below `SKILL_COUNT_THRESHOLD` every skill is highlighted; at and above it,
+ * the skills the message's terms reach are highlighted and the rest are
+ * named, so the agent can still activate one on its own judgement (the Agent
+ * Skills spec's progressive disclosure: metadata up front, instructions on
+ * demand). The native harness calls this on every turn; the Cursor harness
+ * lists every skill today and its adoption is S4's (Q-M5-4).
+ */
+export function selectSkillsForPrompt(userMessage: string, skills: readonly SkillMetadata[]): SkillSelection {
+  const filter = filterSkills(
+    userMessage,
+    skills.map((s) => s.name),
+    skills.map((s) => s.description),
+  );
+  return {
+    highlighted: filter.includedIndices.map((i) => skills[i]),
+    alsoAvailable: filter.excludedNames,
+  };
+}
+
+/**
+ * The tool-neutral sentence that names the skills a prompt did not highlight
+ * (`SkillSelection.alsoAvailable`), so the agent can activate one by reading
+ * its SKILL.md at the mounted path. The sentence names no tool, so it serves
+ * any harness; the heading above it is the builder's framing. Empty for no
+ * names.
+ */
+export function alsoAvailableSkillsNote(excludedNames: readonly string[]): string {
+  if (excludedNames.length === 0) return "";
+  const names = excludedNames.map((n) => `\`${n}\``).join(", ");
+  return (
+    `These skills are installed but were not highlighted above: ${names}. ` +
+    "If you determine one of them is relevant to your task, " +
+    `read its SKILL.md at \`${STIGMER_LOCAL_STATE_DIR}/skills/<name>/SKILL.md\` to activate it.`
+  );
+}

package/src/shared/skill-resolver.ts

@@ -13,8 +13,10 @@
  * platform dir the runtime owns; the harness renders the returned metadata
  * into its prompt in its own placement. Moved from
  * `activities/execute-cursor/` at S2 M3b; the native harness's twin
- * (`skill-writer.ts` `fetchSkillsByRefs` + `mountSkills`) is what S3
- * reconciles it with.
+ * (`skill-writer.ts` `fetchSkillsByRefs` + `mountSkills`) retired at S3 M2b,
+ * and the module itself at S3 M5 — the one renderer it kept is
+ * `shared/prompt-sections.ts` `alsoAvailableSkillsNote`. This is the one
+ * skills path for every harness.
  *
  * The mount is cached by the skill's content-addressed version hash
  * (stigmer/stigmer#672): metadata is fetched on every execution (that keeps

package/src/shared/tool-rounds.ts

@@ -13,6 +13,12 @@
  * The SAME resolved limit must feed both LangGraph's hard stop (the invoke
  * config) and the ExecutionBudgetMiddleware's wrap-up advisory, so the
  * "~80% of budget" warning and the enforcement point can never disagree.
+ *
+ * The knob and its terminal copy live together (the `cost-guard.ts` shape):
+ * when the budget is exhausted the adapter ends its turn `tool_call_limit`
+ * and the runtime's `toolCallLimitArm` writes TERMINATED with the copy
+ * below — the platform deliberately stopped the run, work is checkpointed,
+ * and the conversation continues on the next message.
  */
 
 export const SUPER_STEPS_PER_ROUND = 6;
@@ -54,3 +60,45 @@ function clampToolRounds(requested: number): number {
   }
   return requested;
 }
+
+/**
+ * Stable prefix of the tool-call-limit terminal error. This is a cross-repo
+ * contract: consumers that need to distinguish "ran out of tool-call budget"
+ * from other TERMINATED causes (Stigmer Cloud's channel reply extractor,
+ * which shows channel users a friendly limit message instead of generic
+ * error copy) match on this prefix with `startsWith`, because
+ * AgentExecutionStatus carries no structured termination reason. Do not
+ * reword without updating them. `COST_LIMIT_ERROR_PREFIX` (`cost-guard.ts`)
+ * mirrors it.
+ */
+export const TOOL_CALL_LIMIT_ERROR_PREFIX = "Agent reached the tool-call limit";
+
+/** The terminal `status.error` for a tool-call-limit stop; the prefix is the contract, the rest is prose. */
+export function formatToolCallLimitError(): string {
+  return `${TOOL_CALL_LIMIT_ERROR_PREFIX} for this message. Send another message to continue.`;
+}
+
+/**
+ * User-facing system message for a tool-call-limit stop. Honest about the
+ * limit, clear that nothing is lost; the cost-cap copy is its parallel.
+ */
+export const TOOL_CALL_LIMIT_USER_COPY =
+  "The agent reached the tool-call limit for this message. " +
+  "Work completed so far has been saved. " +
+  "Send another message to continue where the agent left off.";
+
+/**
+ * Whether an error thrown out of a LangGraph run is the graph exhausting the
+ * recursion limit `resolveRecursionLimit` placed on it — the budget's own
+ * signal, not a failure: the adapter ends the turn `tool_call_limit`.
+ * Matched by class name and message because the error class is not
+ * exported on a stable path across `@langchain/langgraph` versions.
+ */
+export function isGraphRecursionError(err: unknown): boolean {
+  if (err instanceof Error) {
+    return err.constructor.name === "GraphRecursionError" ||
+      err.message.includes("GraphRecursionError") ||
+      err.message.includes("Recursion limit");
+  }
+  return false;
+}

package/src/shared/tool-row.ts

@@ -62,6 +62,67 @@ export function stampFileEditRow(tc: ToolCall, changeSetId: string): void {
   }
 }
 
+/**
+ * The turn-boundary pass over a transcript: stamp every file-edit row
+ * (category write/delete) that FLOWED this turn with the change set id, so
+ * the row stays visible in place as an observational record while
+ * `file_change_sets` remains the single decision surface (DD-24). Skips:
+ *
+ *  - already-stamped rows — the idempotency AND cross-turn guard: a resume
+ *    seeds prior turns' rows into this transcript, and re-stamping them with
+ *    this turn's id would mis-attribute them ({@link stampFileEditRow});
+ *  - legacy hidden rows (sessions persisted before stamping existed) — they
+ *    belong to an earlier turn's set;
+ *  - ids in `skipToolCallIds` — the sub-agent callers' pre-turn snapshot
+ *    ({@link collectSubAgentToolCallIds}), since sub-agent rows have neither
+ *    of the two shields above; top-level callers omit it;
+ *  - rows `flowed` refuses — the caller's evidence that a row did NOT flow
+ *    (the Cursor deny-gate's ledger tokens; a status rule). Omit to stamp
+ *    every write/delete row, the deep-agent posture where every such row flowed.
+ *
+ * One pass for every harness (S3 M4; until then each adapter carried a copy
+ * differing only in the `flowed` predicate).
+ */
+export function stampFlowedFileEditRows(
+  messages: readonly AgentMessage[],
+  changeSetId: string,
+  opts: {
+    readonly skipToolCallIds?: ReadonlySet<string>;
+    readonly flowed?: (tc: ToolCall) => boolean;
+  } = {},
+): void {
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      if (tc.fileChangeSetId) continue;
+      if (opts.skipToolCallIds?.has(tc.id)) continue;
+      if (isToolCallRowHidden(tc)) continue;
+      const category = toolApprovalCategory(tc.name);
+      if (category !== "write" && category !== "delete") continue;
+      if (opts.flowed && !opts.flowed(tc)) continue;
+      stampFileEditRow(tc, changeSetId);
+    }
+  }
+}
+
+/**
+ * The same pass over the turn's sub-agent transcripts. Sub-agent writes fold
+ * their files into the SAME parent turn set (shared git diff + one shared CAS
+ * observation, DD-19), so they carry the parent change set id and badge
+ * against the same set the parent's rows do. Scoped to this turn by
+ * `priorToolCallIds` (the sub-agent tool-call ids that existed before the
+ * turn's stream), because sub-agent rows lack the top-level pass's shields.
+ */
+export function stampFlowedSubAgentFileEditRows(
+  subAgents: readonly SubAgentExecution[],
+  changeSetId: string,
+  priorToolCallIds: ReadonlySet<string>,
+  flowed?: (tc: ToolCall) => boolean,
+): void {
+  for (const sa of subAgents) {
+    stampFlowedFileEditRows(sa.messages, changeSetId, { skipToolCallIds: priorToolCallIds, flowed });
+  }
+}
+
 /**
  * Withhold a file-mutating row's CONTENT while keeping its path visible: reduce
  * `args` to `{ path }` (or `undefined` when the path cannot be determined) and

package/src/shared/workspace/__tests__/stigmer-link.test.ts

@@ -10,7 +10,6 @@ import {
   STIGMER_LOCAL_STATE_DIR,
 } from "../stigmer-link.js";
 import { LocalWorkspaceBackend } from "../local-backend.js";
-import { injectAttachments } from "../../../activities/execute-deep-agent/attachment-injector.js";
 
 /**
  * The `.stigmer` symlink is the bridge that makes platform-mounted content
@@ -114,31 +113,17 @@ describe("stigmer-link", () => {
       return agentBackend.read(path) as Promise<{ content?: string; error?: string }>;
     }
 
-    it("approved plan injected via injectAttachments is readable by the deepagents backend", async () => {
+    it("an approved plan mounted under .stigmer/inputs is readable by the deepagents backend once the link exists", async () => {
       const planFileName = "notes_ab12cd34.plan.md";
       const planText = "# The Approved Plan\n\nStep 1: do the thing.\n";
-      const uploadPath = join(platformDir, "upload-src.md");
-      await writeFile(uploadPath, planText);
 
-      // Write path: exactly what the build turn does — the attachment is
-      // materialized through the platform-routing backend at the mount path
-      // the implement-plan directive will tell the model to read.
+      // Write path: the attachment lands in the platform dir at the mount
+      // path the implement-plan directive tells the model to read — here
+      // through the platform-routing backend, the same physical write
+      // `shared/attachment-resolver.ts` performs (it ensures the link itself,
+      // which is why the link's absence is staged by hand below).
       const workspaceBackend = new LocalWorkspaceBackend(workspaceDir, platformDir);
-      const injected = await injectAttachments({
-        backend: workspaceBackend,
-        attachments: [{
-          filename: planFileName,
-          storageKey: "",
-          mountPath: `.stigmer/inputs/${planFileName}`,
-          contentType: "text/markdown",
-          extract: false,
-          localPath: uploadPath,
-          $typeName: "ai.stigmer.agentic.agentexecution.v1.Attachment",
-        } as any],
-        storage: undefined,
-        isLocalMode: true,
-      });
-      expect(injected.map((f) => f.path)).toEqual([`.stigmer/inputs/${planFileName}`]);
+      await workspaceBackend.writeFile(`.stigmer/inputs/${planFileName}`, planText);
 
       // Without the symlink the agent cannot see the plan — the bug this
       // module fixes for the native harness. Pinned so the link stays