@stigmer/runner 3.19.1-dev.20260920100552 → 3.21.0

package/src/activities/execute-deep-agent/__tests__/hermetic/built-in-assistant.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Hermetic pin: the BUILT-IN ASSISTANT through the whole `ExecuteDeepAgent`
+ * activity — a session that names no agent instance, so the blueprint chain
+ * stops at the session (`shared/blueprint-resolver.ts`), the control plane
+ * is never asked for an instance or an agent, and the system prompt opens
+ * with the one built-in text (`shared/builtin-assistant-prompt.ts`).
+ *
+ * Invariant pinned: the agent-less record is a first-class turn, not an
+ * error arm — IN_PROGRESS then COMPLETED with the scripted answer, the same
+ * shape as `plain-turn.test.ts`; and the words the model saw are the shared
+ * ones, read off the scripted model's `systemPrompt` context. The status
+ * itself is not goldened here: nothing agent-shaped reaches the status, so
+ * the plain-turn golden already photographs it.
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import { BUILT_IN_ASSISTANT_INSTRUCTIONS } from "../../../../shared/builtin-assistant-prompt.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+
+const USER_MESSAGE = "Say hello.";
+const ASSISTANT_TEXT = "Hello from the built-in assistant.";
+
+describe("ExecuteDeepAgent hermetic — the built-in assistant", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("runs a session with no agent to COMPLETED on the built-in prompt, never reading an instance or an agent", async () => {
+    clock.reset();
+    const record = deepAgentExecutionRecord({ message: USER_MESSAGE, builtInAssistant: true });
+    const systemPrompts: string[] = [];
+    const instanceRead = vi.fn(async () => {
+      throw new Error("must not be reached");
+    });
+    const agentRead = vi.fn(async () => {
+      throw new Error("must not be reached");
+    });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      clientOverrides: { getAgentInstance: instanceRead, getAgent: agentRead },
+      script: (_tools, context) => {
+        systemPrompts.push(context.systemPrompt);
+        return { turns: [{ text: ASSISTANT_TEXT, usage: { inputTokens: 900, outputTokens: 20 } }] };
+      },
+    });
+
+    const invocation = await runDeepAgentTurn(scenario);
+
+    expect(invocation.outcome.kind).toBe("returned");
+    expect(record.persistedPhases).toEqual([
+      ExecutionPhase.EXECUTION_IN_PROGRESS,
+      ExecutionPhase.EXECUTION_COMPLETED,
+    ]);
+    const final = record.lastFullStatus!;
+    const ai = final.messages.filter((m) => m.type === MessageType.MESSAGE_AI);
+    expect(ai).toHaveLength(1);
+    expect(ai[0].content).toBe(ASSISTANT_TEXT);
+
+    // The chain stopped at the session: the refusing reads were never
+    // reached (they would have failed the resolve phase).
+    expect(instanceRead).not.toHaveBeenCalled();
+    expect(agentRead).not.toHaveBeenCalled();
+
+    // The model met the shared words, first.
+    expect(systemPrompts).toHaveLength(1);
+    expect(systemPrompts[0].startsWith(BUILT_IN_ASSISTANT_INSTRUCTIONS)).toBe(true);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/hermetic/turn-phases.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Hermetic proof: the native harness gets the runtime's `turn_phases` timing
+ * line without a line of its own.
+ *
+ * Invariant pinned: driving the REAL deepagents graph through the real native
+ * translator, the turn runtime writes exactly one `turn_phases` line for the
+ * turn, and the line reads what the translator's events said — one model
+ * round per LangGraph run (two here: the proposal and the closing text), one
+ * tool span for the `read_file` call, the three root instants present, the
+ * adapter's own name as `harness`. The fold and its rules are
+ * `harness/__tests__/turn-timeline.test.ts`'s; the runtime's act of writing
+ * the line is `harness/__tests__/run-turn.test.ts`'s against the fake. What
+ * only this file can prove is that the native translator emits the events the
+ * fold needs (`message_start`/`message_finish` per run, `tool_started`/
+ * `tool_finished` per call) in the order it needs them, on a real graph.
+ *
+ * Structural assertions only: the scripted clock makes every number
+ * deterministic, but pinning one would pin the clock's tick quantum, not a
+ * behaviour. The status goldens beside this file are untouched by design —
+ * the line is stdout, never the status — and their byte-identity under this
+ * change is proved by running them.
+ *
+ * Same scenario as `tool-call.test.ts`, so the two files read together.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+vi.mock("../../../../shared/model-client.js", async () =>
+  (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+);
+vi.mock("../../../../client/stigmer-client.js", async () =>
+  (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+);
+
+import {
+  ScriptedClock,
+  createHermeticEnvironment,
+  type HermeticEnvironment,
+} from "../../../../__test-utils__/hermetic-activity.js";
+import { stubRegistryFetch } from "../../../../__test-utils__/model-registry-fixture.js";
+import { captureTimingLines } from "../../../../__test-utils__/timing-lines.js";
+import { TURN_PHASES_EVENT } from "../../../../harness/turn-timeline.js";
+import {
+  beginDeepAgentScenario,
+  deepAgentExecutionRecord,
+  runDeepAgentTurn,
+  sessionWorkspaceDir,
+} from "../../__test-utils__/hermetic-deep-agent.js";
+
+const CALL_ID = "call-hermetic-read-0001";
+const USER_MESSAGE = "What is in README.md?";
+const README = "# Hermetic\n\nA fixture readme.\n";
+const ASSISTANT_TEXT = "README.md holds a one-line fixture description.";
+
+describe("ExecuteDeepAgent hermetic — the runtime's turn_phases line", () => {
+  let env: HermeticEnvironment;
+  let registry: ReturnType<typeof stubRegistryFetch>;
+  const clock = new ScriptedClock();
+
+  beforeAll(() => {
+    env = createHermeticEnvironment();
+    registry = stubRegistryFetch();
+    clock.install();
+  });
+
+  afterAll(() => {
+    clock.uninstall();
+    registry.restore();
+    env.dispose();
+  });
+
+  it("writes one line for the turn, reading the translator's rounds and tool spans", async () => {
+    const record = deepAgentExecutionRecord({ message: USER_MESSAGE });
+    const scenario = beginDeepAgentScenario({
+      env,
+      clock,
+      record,
+      script: () => ({
+        turns: [
+          {
+            text: "Let me read it.",
+            toolCalls: [{ id: CALL_ID, name: "read_file", args: { file_path: "/README.md" } }],
+            usage: { inputTokens: 1_500, outputTokens: 60 },
+          },
+          { text: ASSISTANT_TEXT, usage: { inputTokens: 1_700, outputTokens: 30 } },
+        ],
+      }),
+    });
+    const workspace = sessionWorkspaceDir(env);
+    mkdirSync(workspace, { recursive: true });
+    writeFileSync(join(workspace, "README.md"), README, "utf-8");
+
+    const lines = await captureTimingLines(TURN_PHASES_EVENT, async () => {
+      const invocation = await runDeepAgentTurn(scenario);
+      expect(invocation.outcome.kind).toBe("returned");
+    });
+
+    expect(lines, "one line per turn").toHaveLength(1);
+    const line = lines[0]!;
+    expect(line.harness, "the adapter's diagnostic name, the runtime's vocabulary").toBe("deep-agent");
+    expect(line.outcome).toBe("completed");
+    expect(line.execution_id).toBe(record.execution.metadata!.id);
+    expect(line.turn_seq).toBeTypeOf("number");
+
+    expect(line.rounds, "the proposing run and the closing run").toBe(2);
+    expect(line.tool_calls).toBe(1);
+    expect(line.sub_agents).toBe(0);
+    expect(line.segments.filter((s) => s.name === "model_round")).toHaveLength(2);
+    expect(line.segments.filter((s) => s.name === "tool:read_file")).toHaveLength(1);
+
+    expect(line.first_event_ms).toBeTypeOf("number");
+    expect(line.first_visible_token_ms).toBeTypeOf("number");
+    expect(line.first_text_ms).toBeTypeOf("number");
+    expect(line.total_ms).toBeGreaterThanOrEqual(line.first_text_ms as number);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/prompt-goldens.test.ts

@@ -20,7 +20,7 @@
  * the filter fires, channel templates, referenced files, three input files
  * with a rename and a download URL, the vision disclosure, all five standing
  * sections); the below-threshold skills branch; plan mode; build-from-plan;
- * and the minimal prompt (no instructions, so `DEFAULT_INSTRUCTIONS`). Plan
+ * and the minimal prompt (no instructions, so the built-in assistant's). Plan
  * mode and build-from-plan are mutually exclusive in production, so each has
  * its own golden.
  *

package/src/activities/execute-deep-agent/prompt-builder.ts

@@ -40,6 +40,7 @@ import {
   type StandingSectionKind,
   type VisionPromptInfo,
 } from "../../shared/prompt-sections.js";
+import { effectiveInstructions } from "../../shared/builtin-assistant-prompt.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import {
   buildImplementPlanDirective,
@@ -115,11 +116,8 @@ directly over delegating. Only delegate when context isolation \
 or parallelism genuinely helps the user.
 `;
 
-/** The agent's instructions when the blueprint carries none; the prompt is never empty (since #1096: was `setup.ts`'s alone). */
-export const DEFAULT_INSTRUCTIONS = "You are a helpful AI assistant.";
-
 export interface PromptBuilderInput {
-  /** The blueprint's instructions, raw; empty falls back to {@link DEFAULT_INSTRUCTIONS}. */
+  /** The blueprint's instructions, raw; empty reads the built-in assistant's (shared/builtin-assistant-prompt.ts). */
   instructions: string;
   provisionResults: ProvisionResult[];
   containerRoot: string;
@@ -233,7 +231,7 @@ const STANDING_SECTION_HEADINGS: Record<StandingSectionKind, string> = {
  * sections. Pure function with no I/O.
  */
 export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
-  let prompt = input.instructions || DEFAULT_INSTRUCTIONS;
+  let prompt = effectiveInstructions(input.instructions);
 
   const workspaceSection = buildWorkspacePromptSection(
     input.provisionResults,

package/src/activities/generate-session-subject.ts

@@ -137,22 +137,26 @@ export async function generateSessionSubject(
     return;
   }
 
+  // The agent, when the conversation has one, lends the title its purpose;
+  // the built-in assistant (no agent on the session) is titled from the
+  // message alone rather than left "Untitled".
+  let agentName = "";
+  let agentDescription = "";
   const agentId = await resolveAgentId(execution, session, client);
-  if (agentId === "") {
-    log(`cannot resolve agent_id for execution ${executionId}, skipping`);
-    return;
+  if (agentId !== "") {
+    const agent = await getOrSkip(
+      () => client.getAgent(agentId),
+      `agent not found: ${agentId}`,
+    );
+    if (agent === undefined) return;
+    agentName = agent.metadata?.name ?? "";
+    agentDescription = agent.spec?.description ?? "";
   }
 
-  const agent = await getOrSkip(
-    () => client.getAgent(agentId),
-    `agent not found: ${agentId}`,
-  );
-  if (agent === undefined) return;
-
   const subject = await generateTitle({
     userMessage,
-    agentName: agent.metadata?.name ?? "",
-    agentDescription: agent.spec?.description ?? "",
+    agentName,
+    agentDescription,
     executionId,
     options,
   });
@@ -175,7 +179,8 @@ export async function generateSessionSubject(
 /**
  * The agent behind the execution: the direct agent_id when the execution
  * carries one, else resolved through the session's agent-instance chain.
- * Empty string when unresolvable. Mirrors the cloud activity's resolveAgentId.
+ * Empty string when there is none (the built-in assistant) or when the
+ * instance cannot be read.
  */
 export async function resolveAgentId(
   execution: AgentExecution,
@@ -264,7 +269,9 @@ export function buildUserPrompt(
   agentDescription: string,
 ): string {
   let prompt = `User's first message:\n"${userMessage}"\n\n`;
-  prompt += `Agent: ${agentName}\n`;
+  if (agentName !== "") {
+    prompt += `Agent: ${agentName}\n`;
+  }
   if (agentDescription !== "") {
     prompt += `Agent purpose: ${agentDescription}\n`;
   }

package/src/harness/README.md

@@ -47,6 +47,10 @@ pinned somewhere. Read a row across before searching for anything.
   translator emits.
 - `harness/transcript/builder.ts` — `TranscriptBuilder`, the one builder every
   harness folds its events through.
+- `harness/turn-timeline.ts` — `TurnTimeline`, the runtime's fold over that
+  builder's events into the `turn_phases` timing line every harness gets for
+  free: first visible token, model rounds, tool and sub-agent spans, the
+  longest silence.
 - `harness/capture.ts` — the file-review capture. The runtime owns all of it; an
   adapter supplies one fact, which CAS-owned paths its engine touched.
 - `harness/turn-context.ts` — the resolution phases that build the `TurnInput`
@@ -204,7 +208,6 @@ Every hit falls into one of three classes:
 | `sdk/react/src/workflow/inspector/forms/AgentCallForm.tsx`                                                                                                                     | Two radio buttons, placed by hand.                                                                                                                                                                                                                                                                                            |
 | `sdk/react/src/pricing-governance/BaselineEditor.tsx`                                                                                                                          | A select with one option per harness.                                                                                                                                                                                                                                                                                         |
 | `site/src/components/pages/pricing/ModelPricingTable.tsx`                                                                                                                      | Harness to display label.                                                                                                                                                                                                                                                                                                     |
-| `site/src/data/harness-cost-comparison.json`                                                                                                                                   | Per-harness cost rows.                                                                                                                                                                                                                                                                                                        |
 | `docs/concepts/harnesses.mdx`, `docs/concepts/sessions.mdx`, `docs/guides/runners/cursor-harness.mdx`, `docs/guides/workflows/task-types/agent-call.mdx`, `docs/vocabulary.md` | Hand-authored pages that name the harness set; each has an entry in `docs/_inventory/classification.yaml` to keep current.                                                                                                                                                                                                    |
 
 The cloud composition that serves api.stigmer.ai has sites of the same three

package/src/harness/__tests__/run-turn.test.ts

@@ -53,13 +53,16 @@ import {
   assertFailedSurfaceWritesItsCopy,
   assertNonExecutingDecisionSettlesSkipped,
   assertRejectedBindFails,
+  assertWorkspaceLockTimeoutFails,
   describeHarnessRuntimeContract,
   RuntimeExecutionDriver,
   slimOf,
   systemMessages,
   type RuntimeContractHarness,
 } from "../../__test-utils__/harness-contract/runtime-contract.js";
+import { captureTimingLines } from "../../__test-utils__/timing-lines.js";
 import { TERMINAL_COPY } from "../terminal-table.js";
+import { TURN_PHASES_EVENT } from "../turn-timeline.js";
 import type { HarnessAdapter } from "../types.js";
 
 const TASK_QUEUE = "runtime-test-queue";
@@ -219,6 +222,56 @@ describe("run-turn: the fake adapter through the real runtime", () => {
     });
   });
 
+  describe("the runtime's turn timeline", () => {
+    // `run-turn.ts` emits the `turn_phases` line once, after the adapter
+    // returns and the transcript is finalized, on every outcome; a turn that
+    // never reached the engine emits none. The line's CONTENT is
+    // `turn-timeline.test.ts`'s; what is pinned here is the runtime's act:
+    // that the fold is installed on the one builder the adapter is handed,
+    // that the line names the adapter and the activity's turn, and that it is
+    // written for a failed turn as for a completed one.
+    const turnPhasesLines = (act: () => Promise<void>) => captureTimingLines(TURN_PHASES_EVENT, act);
+
+    it("writes one turn_phases line for a completed turn, naming the adapter, the turn and what the fold saw", async () => {
+      clock.reset();
+      const driver = new RuntimeExecutionDriver(harness, "fake-timeline-completed");
+      const lines = await turnPhasesLines(async () => {
+        const invocation = await driver.turn([scenario.say("Reading it."), scenario.read("t1", "notes.md"), scenario.say("Done.")]);
+        expect(slimOf(subject, invocation).phase).toBe("EXECUTION_COMPLETED");
+      });
+
+      expect(lines).toHaveLength(1);
+      const [line] = lines;
+      expect(line!.harness).toBe(subject.adapter.name);
+      expect(line!.outcome).toBe("completed");
+      expect(line!.turn_seq).toBeTypeOf("number");
+      expect(line!.rounds, "two `say`s, two rounds").toBe(2);
+      expect(line!.tool_calls, "one `read`").toBe(1);
+      expect(line!.first_text_ms).toBeTypeOf("number");
+    });
+
+    it("writes the line for a failed turn too: every outcome is measured", async () => {
+      clock.reset();
+      const driver = new RuntimeExecutionDriver(harness, "fake-timeline-failed");
+      const lines = await turnPhasesLines(async () => {
+        const invocation = await driver.turn([scenario.say("Checking."), scenario.fail("engine gave up")]);
+        expect(slimOf(subject, invocation).phase).toBe("EXECUTION_FAILED");
+      });
+
+      expect(lines).toHaveLength(1);
+      expect(lines[0]!.outcome).toBe("failed");
+      expect(lines[0]!.rounds).toBe(1);
+    });
+
+    it("writes no line for a turn that settled during resolution: no engine, no phases", async () => {
+      clock.reset();
+      const lines = await turnPhasesLines(async () => {
+        await assertWorkspaceLockTimeoutFails(harness, "fake-timeline-no-engine");
+      });
+      expect(lines).toEqual([]);
+    });
+  });
+
   describe("the runtime's write-back rule", () => {
     // `run-turn.ts` calls `frame.writeback.finalize()` in exactly two places:
     // once when a completed turn reaches its epilogue, and once when a resumed