@stigmer/runner 3.19.1-dev.20260920100552 → 3.21.0

package/src/harness/turn-timeline.ts

@@ -0,0 +1,248 @@
+/**
+ * The turn runtime's timeline of one engine turn, folded from the transcript
+ * events every harness already emits, and written once at settle as the
+ * `turn_phases` `stigmer_timing` line.
+ *
+ * What it answers, for every harness alike and for any harness added later
+ * without a line in an adapter: when the user first saw something happen,
+ * how many model rounds and tool calls the turn took, where the sub-agents
+ * ran, and where the turn's longest silence was. It is the per-turn,
+ * CLIENT-PERCEIVED measurement from the runner's vantage, from the turn's
+ * origin (the activity's start, the same origin `execution_setup` counts
+ * from, so the two lines subtract without a join) to the adapter's return;
+ * the completion epilogue and the terminal persist that follow are the
+ * client's own end-to-end, read at `subscribe`. Its counterpart is the cloud
+ * proxy's `ProxyTiming` (`agentexecution/v1/usage.proto`): per model CALL,
+ * server-side, what the provider did. Neither restates the other; a report
+ * that wants both joins them by `execution_id`.
+ *
+ * Why a fold over the transcript events and not a mark in each adapter: the
+ * transcript builder (`transcript/builder.ts`) is the one view the runtime
+ * has of every harness's turn — model rounds, text, tools, sub-agents all
+ * reach it as a translator's output on one union — so a fold over it is
+ * written once and holds for the Cursor adapter, the native adapter and the
+ * next one. `UsageAccumulator` (`usage-accumulator.ts`) is the same shape
+ * for the usage deltas; this is that shape for the events.
+ *
+ * The fold's rules, each with an arm in `__tests__/turn-timeline.test.ts`:
+ *
+ *   - Three instants, ROOT scope only (a sub-agent's text is not what the
+ *     user is watching): `first_event_ms`, the first event of any kind;
+ *     `first_visible_token_ms`, the first `text_delta` or `reasoning_delta`
+ *     (both stream into the console as tokens); `first_text_ms`, the first
+ *     `text_delta`. The two token instants are the cross-harness axes: with
+ *     extended thinking on, the visible instant moves earlier and the text
+ *     instant later, and a comparison needs both. `first_event_ms` is
+ *     harness-relative — on native the first event is `message_start`, the
+ *     model stream opening; on Cursor it is whatever the SDK delivered first —
+ *     and is kept as a forensic (engine-ready to first model event), never as
+ *     an axis. An instant that never happened is `null`.
+ *   - One `model_round` span per `runId`, `message_start` to `message_finish`.
+ *     What a `runId` is belongs to the translator: LangGraph's LLM-call run on
+ *     native, one model round; a minted segment `<run>:<n>` on Cursor, a
+ *     stretch of assistant output between tool calls, which the SDK does not
+ *     let us tell apart from a provider round. The line's `rounds` reads the
+ *     same way.
+ *   - One `tool:<name>` span per `callId` (`tool:<slug>/<name>` for an MCP
+ *     tool, so the MCP phase the runner skill's law asks for is legible),
+ *     `tool_started` to the FIRST `tool_finished` or `tool_error`; a later
+ *     fact for a settled span changes nothing, the builder's own upsert rule
+ *     (Cursor completes every call twice). `approval_proposed` opens nothing:
+ *     a call the engine held before it ran is not a tool phase.
+ *   - One `sub_agent:<name>` span per `subAgentId`, opened by
+ *     `sub_agent_started`, closed by `finished` or `failed`.
+ *   - A fact that carries `observedAt` is placed at that instant, everything
+ *     else at the fold's clock — the builder's rule for `completedAt`
+ *     (`transcript/events.ts`, `Observed`), restated here because the
+ *     alternative repeats the error #1097 fixed, for tool phases and on Cursor
+ *     alone: a completion the SDK's delta channel reported is folded one
+ *     stream event later, seconds while the model narrates, and a comparison
+ *     that read the fold's clock would charge those seconds to Cursor's tools.
+ *     Placing an observed instant needs a wall-clock origin beside the
+ *     `performance.now()` one; the runtime captures both together.
+ *   - `max_gap_ms`, the longest wait between two consecutive events, whatever
+ *     their kind: the turn's longest silence as the user experienced it.
+ *     `null` under two events.
+ *   - A span still open at settle closes at settle: an interrupted turn's
+ *     spans end where the turn did.
+ *
+ * The line: `emitTimingLog("turn_phases", context, recorder)` over a
+ * `TimingRecorder` on the turn's origin, every span appended in start order
+ * through `span()`. This is the first `stigmer_timing` event whose segments
+ * OVERLAP (a tool inside a round, a sub-agent across rounds); the recorder's
+ * `total_ms` is the latest end, not a sum, and a reader that summed the
+ * other timelines' segments must not sum this one's. No histogram mirrors it
+ * yet: the benchmark report is its reader and reads the log; an aggregate
+ * earns its instrument when a dashboard asks.
+ *
+ * Failure posture, the timing module's: the fold is arithmetic over the
+ * event and cannot affect a turn; `emit` is best-effort through
+ * `emitTimingLog`. Nothing here is persisted, and nothing branches on it.
+ */
+
+import { TimingRecorder, emitTimingLog } from "../shared/cold-start-timing.js";
+import type { TranscriptEvent } from "./transcript/events.js";
+
+/** The `stigmer_timing` selector of the line this module emits. */
+export const TURN_PHASES_EVENT = "turn_phases";
+
+/**
+ * The two clocks the timeline places facts on, captured together at the
+ * turn's origin. `now` is `performance.now` in production; tests inject a
+ * scripted one. `originWallMs` is the `Date.now()` of the same instant, the
+ * scale `observedAt` stamps are on.
+ */
+export interface TurnTimelineClock {
+  /** `performance.now()`-scale origin, the one `execution_setup` shares. */
+  readonly originMs: number;
+  /** `Date.now()`-scale reading of the same instant. */
+  readonly originWallMs: number;
+  readonly now: () => number;
+}
+
+/** The facts the runtime adds to the line beside the fold's own. */
+export type TurnPhasesContext = Record<string, string | number | boolean | null | undefined>;
+
+/** One span the fold has closed or is still tracking. Absolute `performance.now()` scale. */
+interface OpenSpan {
+  readonly name: string;
+  readonly startMs: number;
+  endMs: number | undefined;
+}
+
+export class TurnTimeline {
+  private readonly clock: TurnTimelineClock;
+
+  private firstEventMs: number | undefined;
+  private firstVisibleTokenMs: number | undefined;
+  private firstTextMs: number | undefined;
+  private lastEventMs: number | undefined;
+  private maxGapMs: number | undefined;
+
+  private readonly rounds = new Map<string, OpenSpan>();
+  private readonly tools = new Map<string, OpenSpan>();
+  private readonly subAgents = new Map<string, OpenSpan>();
+
+  constructor(clock: TurnTimelineClock) {
+    this.clock = clock;
+  }
+
+  /** The builder's observer: place one folded event on the timeline. */
+  observe(event: TranscriptEvent): void {
+    const at = this.clock.now();
+    this.noteEvent(at);
+
+    // Root scope only: a sub-agent's tokens stream into its own row, not the
+    // thread the user is watching.
+    if ((event.kind === "text_delta" || event.kind === "reasoning_delta") && event.subAgentId === undefined) {
+      this.firstVisibleTokenMs ??= at;
+      if (event.kind === "text_delta") this.firstTextMs ??= at;
+    }
+
+    switch (event.kind) {
+      case "message_start":
+        this.open(this.rounds, event.runId, "model_round", at);
+        return;
+      case "message_finish":
+        this.close(this.rounds, event.runId, at);
+        return;
+      case "tool_started":
+        this.open(this.tools, event.callId, toolSpanName(event.name, event.mcpServerSlug), at);
+        return;
+      case "tool_finished":
+      case "tool_error":
+        this.close(this.tools, event.callId, this.placeObserved(event.observedAt, at));
+        return;
+      case "sub_agent_started":
+        this.open(this.subAgents, event.subAgentId, `sub_agent:${event.name}`, at);
+        return;
+      case "sub_agent_finished":
+      case "sub_agent_failed":
+        this.close(this.subAgents, event.subAgentId, at);
+        return;
+      case "text_delta":
+      case "reasoning_delta":
+      case "tool_arg_delta":
+      case "tool_output_delta":
+      case "approval_proposed":
+      case "system_note":
+        return;
+      default: {
+        const exhaustive: never = event;
+        throw new Error(`unknown transcript event ${String((exhaustive as { kind: string }).kind)}`);
+      }
+    }
+  }
+
+  /**
+   * Write the line, once, at settle. Spans still open close now; the
+   * runtime's context (`execution_id`, `session_id`, `turn_seq`, `harness`,
+   * `outcome`) rides beside the fold's facts.
+   */
+  emit(context: TurnPhasesContext): void {
+    const settledAt = this.clock.now();
+    const recorder = new TimingRecorder(this.clock.originMs);
+    const spans = [...this.rounds.values(), ...this.tools.values(), ...this.subAgents.values()]
+      .sort((a, b) => a.startMs - b.startMs);
+    for (const span of spans) {
+      recorder.span(span.name, span.startMs, span.endMs ?? settledAt);
+    }
+    emitTimingLog(TURN_PHASES_EVENT, {
+      ...context,
+      first_event_ms: this.offset(this.firstEventMs),
+      first_visible_token_ms: this.offset(this.firstVisibleTokenMs),
+      first_text_ms: this.offset(this.firstTextMs),
+      rounds: this.rounds.size,
+      tool_calls: this.tools.size,
+      sub_agents: this.subAgents.size,
+      max_gap_ms: this.maxGapMs === undefined ? null : round1(this.maxGapMs),
+    }, recorder);
+  }
+
+  private noteEvent(at: number): void {
+    this.firstEventMs ??= at;
+    if (this.lastEventMs !== undefined) {
+      const gap = at - this.lastEventMs;
+      if (this.maxGapMs === undefined || gap > this.maxGapMs) this.maxGapMs = gap;
+    }
+    this.lastEventMs = at;
+  }
+
+  /** A span per identity: a re-emitted start (a resumed seeded call) keeps the first start. */
+  private open(spans: Map<string, OpenSpan>, id: string, name: string, at: number): void {
+    if (spans.has(id)) return;
+    spans.set(id, { name, startMs: at, endMs: undefined });
+  }
+
+  /** The FIRST close settles a span; a later fact for it changes nothing. A close for an unknown id is ignored. */
+  private close(spans: Map<string, OpenSpan>, id: string, at: number): void {
+    const span = spans.get(id);
+    if (!span || span.endMs !== undefined) return;
+    span.endMs = at;
+  }
+
+  /**
+   * Where a fact goes on the `performance.now()` scale: its observed instant
+   * translated through the paired origins when it carries one, else the fold's
+   * clock. An unparseable stamp falls back to the fold's clock rather than
+   * losing the fact.
+   */
+  private placeObserved(observedAt: string | undefined, foldAt: number): number {
+    if (observedAt === undefined) return foldAt;
+    const wallMs = Date.parse(observedAt);
+    if (Number.isNaN(wallMs)) return foldAt;
+    return this.clock.originMs + (wallMs - this.clock.originWallMs);
+  }
+
+  private offset(absoluteMs: number | undefined): number | null {
+    return absoluteMs === undefined ? null : round1(absoluteMs - this.clock.originMs);
+  }
+}
+
+function toolSpanName(name: string, mcpServerSlug: string): string {
+  return mcpServerSlug ? `tool:${mcpServerSlug}/${name}` : `tool:${name}`;
+}
+
+function round1(ms: number): number {
+  return Math.round(ms * 10) / 10;
+}

package/src/shared/__tests__/blueprint-resolver.test.ts

@@ -1,17 +1,87 @@
 /**
- * `shared/blueprint-resolver.ts` `mergeSkillRefs`: the one merge of the
+ * `shared/blueprint-resolver.ts`: `mergeSkillRefs`, the one merge of the
  * agent's and the session's skill refs the turn runtime resolves from
- * (`resolveAgentBlueprint`). Union, deduplicated by slug, the session's ref
- * winning a collision (it may pin a different version).
+ * (`resolveBlueprint`) — union, deduplicated by slug, the session's ref
+ * winning a collision (it may pin a different version); and
+ * `resolveBlueprint`'s two arms: the agent chain walked when the session
+ * names an instance, and the built-in assistant when it does not — no
+ * instance or agent read, empty instructions, no sub-agents, and the
+ * session's own usages and refs as the whole tool set.
  *
- * Carried from `skill-writer.test.ts` in #1096, when the native
- * orchestrator's byte-twin of this function was deleted with its module;
- * until then the runtime's copy was tested only through the twin.
+ * `mergeSkillRefs` carried from `skill-writer.test.ts` in #1096, when the
+ * native orchestrator's byte-twin of this function was deleted with its
+ * module; until then the runtime's copy was tested only through the twin.
  */
 
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import { mergeSkillRefs } from "../blueprint-resolver.js";
+import { mockStigmerClient } from "../../__test-utils__/mock-client.js";
+import { mergeSkillRefs, resolveBlueprint } from "../blueprint-resolver.js";
+
+describe("resolveBlueprint", () => {
+  it("walks session -> instance -> agent and merges with the session's tools", async () => {
+    const client = mockStigmerClient({
+      getAgentInstance: vi.fn().mockResolvedValue(
+        create(AgentInstanceSchema, { metadata: { id: "agi_1" }, spec: { agentId: "agt_1" } }),
+      ),
+      getAgent: vi.fn().mockResolvedValue(
+        create(AgentSchema, {
+          metadata: { id: "agt_1", name: "builder" },
+          spec: {
+            instructions: "You build things.",
+            mcpServerUsages: [{ mcpServerRef: { org: "acme", slug: "github" } }],
+            skillRefs: [{ org: "acme", slug: "release" }],
+          },
+        }),
+      ),
+    });
+    const session = create(SessionSchema, {
+      metadata: { id: "ses_1", org: "acme" },
+      spec: {
+        agentInstanceId: "agi_1",
+        mcpServerUsages: [{ mcpServerRef: { org: "acme", slug: "notes" } }],
+      },
+    });
+
+    const blueprint = await resolveBlueprint(client, session);
+
+    expect(blueprint.agent?.metadata?.id).toBe("agt_1");
+    expect(blueprint.instructions).toBe("You build things.");
+    expect(blueprint.mergedMcpServerUsages.map((u) => u.mcpServerRef?.slug).sort()).toEqual(["github", "notes"]);
+    expect(blueprint.mergedSkillRefs.map((r) => r.slug)).toEqual(["release"]);
+    expect(client.getAgentInstance).toHaveBeenCalledWith("agi_1");
+    expect(client.getAgent).toHaveBeenCalledWith("agt_1");
+  });
+
+  it("answers the built-in assistant for a session with no instance: no agent read, the session's tools alone", async () => {
+    const client = mockStigmerClient({
+      getAgentInstance: vi.fn().mockRejectedValue(new Error("must not be reached")),
+      getAgent: vi.fn().mockRejectedValue(new Error("must not be reached")),
+    });
+    const session = create(SessionSchema, {
+      metadata: { id: "ses_2", org: "acme" },
+      spec: {
+        agentInstanceId: "",
+        mcpServerUsages: [{ mcpServerRef: { org: "acme", slug: "notes" } }],
+        skillRefs: [{ org: "acme", slug: "writing" }],
+      },
+    });
+
+    const blueprint = await resolveBlueprint(client, session);
+
+    expect(blueprint.agent).toBeUndefined();
+    expect(blueprint.instructions).toBe("");
+    expect(blueprint.subAgents).toEqual([]);
+    expect(blueprint.mergedMcpServerUsages.map((u) => u.mcpServerRef?.slug)).toEqual(["notes"]);
+    expect(blueprint.mergedSkillRefs.map((r) => r.slug)).toEqual(["writing"]);
+    expect(client.getAgentInstance).not.toHaveBeenCalled();
+    expect(client.getAgent).not.toHaveBeenCalled();
+  });
+});
 
 function makeRef(slug: string, org = "test-org"): ApiResourceReference {
   return { slug, org, $typeName: "ai.stigmer.commons.apiresource.ApiResourceReference" } as ApiResourceReference;

package/src/shared/__tests__/cold-start-timing.test.ts

@@ -3,11 +3,13 @@
  *
  * The warm-agent-surfaces baseline report derives its waterfall from these
  * emissions, so the invariants pinned here are load-bearing for a spend
- * decision: segments must partition the timeline (total == sum, no gaps),
- * the emitted line must keep its stable shape (`stigmer_timing` selector,
- * context spread, `segments` with per-segment `start_ms`/`duration_ms`),
- * and the process-boot timeline must emit exactly once — a worker restart
- * inside one process must never produce a bogus second timeline.
+ * decision: `mark` segments must partition the timeline (total == sum, no
+ * gaps), `span` segments may overlap and never move the mark cursor (so the
+ * two idioms compose on one recorder), the emitted line must keep its stable
+ * shape (`stigmer_timing` selector, context spread, `segments` with
+ * per-segment `start_ms`/`duration_ms`), and the process-boot timeline must
+ * emit exactly once — a worker restart inside one process must never produce
+ * a bogus second timeline.
  *
  * The boot singleton is module-level state, so those tests re-import the
  * module fresh via `vi.resetModules()` to get an unlatched instance.
@@ -101,6 +103,52 @@ describe("TimingRecorder", () => {
   });
 });
 
+describe("TimingRecorder.span", () => {
+  // Explicit bounds are absolute, like the origin; offsets come out relative.
+  it("records a segment with explicit bounds, relative to the origin", () => {
+    const origin = 1_000;
+    const recorder = new TimingRecorder(origin);
+    recorder.span("model_round", origin + 100, origin + 350.26);
+
+    expect(recorder.snapshot()).toEqual([{ name: "model_round", startMs: 100, durationMs: 250.3 }]);
+    expect(recorder.totalMs()).toBe(350.3);
+  });
+
+  it("lets spans overlap: the timeline is not partitioned and total is the latest end", () => {
+    const origin = 0;
+    const recorder = new TimingRecorder(origin);
+    recorder.span("model_round", 10, 500);
+    recorder.span("tool:read_file", 200, 300);
+    recorder.span("sub_agent:researcher", 250, 900);
+    recorder.span("model_round", 600, 700);
+
+    const segments = recorder.snapshot();
+    expect(segments.map((s) => s.name)).toEqual(["model_round", "tool:read_file", "sub_agent:researcher", "model_round"]);
+    // The tool sits inside the first round; the sub-agent crosses both rounds.
+    expect(segments[1]!.startMs).toBeGreaterThan(segments[0]!.startMs);
+    expect(segments[1]!.startMs + segments[1]!.durationMs).toBeLessThan(segments[0]!.startMs + segments[0]!.durationMs);
+    // Not the last span's end, and not the sum: the segment that ends latest.
+    expect(recorder.totalMs()).toBe(900);
+  });
+
+  it("never moves the mark cursor: a mark after a span still measures from the previous mark", () => {
+    const origin = performance.now();
+    const recorder = new TimingRecorder(origin);
+    recorder.span("model_round", origin + 100, origin + 250);
+    recorder.mark("after");
+
+    const [span, mark] = recorder.snapshot();
+    expect(span!.startMs).toBe(100);
+    // The mark closes from the ORIGIN (the previous mark cursor), not from
+    // the span's end: a span is a fact placed on the timeline, not progress
+    // of the sequential chain.
+    expect(mark!.startMs).toBe(0);
+    expect(mark!.durationMs).toBeLessThan(100);
+    // The span still ends latest, so it is the total.
+    expect(recorder.totalMs()).toBe(250);
+  });
+});
+
 describe("emitTimingLog", () => {
   it("emits one line with the stable shape the baseline report parses", () => {
     const spy = vi.spyOn(console, "log").mockImplementation(() => {});

package/src/shared/blueprint-resolver.ts

@@ -6,6 +6,14 @@
  * mcp_server_usages. Also merges agent-level and session-level MCP usages
  * and skill refs following the same merge semantics.
  *
+ * A session with an EMPTY agent_instance_id is the built-in assistant
+ * (session/v1/spec.proto): the chain stops at the session, `agent` is
+ * undefined, the instructions are empty (each harness's prompt builder
+ * substitutes the one built-in prompt, shared/builtin-assistant-prompt.ts),
+ * there are no sub-agents, and the session's own MCP usages and skill refs
+ * are the whole tool set — the same merge with an empty agent side, so no
+ * consumer downstream needs an agent-less arm of its own.
+ *
  * Workspace isolation: resolved workspace directories are validated to
  * ensure they never point at the runner's own app directory. Paths
  * containing runner-internal markers are rejected with a warning.
@@ -32,8 +40,8 @@ export interface CloudRepo {
 }
 
 export interface ResolvedBlueprint {
-  agent: Agent;
-  agentSpec: AgentSpec;
+  /** The agent the session is bound to; undefined for the built-in assistant. */
+  agent: Agent | undefined;
   session: Session;
   sessionSpec: SessionSpec;
   instructions: string;
@@ -47,7 +55,9 @@ export interface ResolvedBlueprint {
  * Resolve the full agent blueprint from the execution chain.
  *
  * Chain: execution.spec.sessionId -> session.spec.agentInstanceId ->
- *        agentInstance.spec.agentId -> agent (with full spec)
+ *        agentInstance.spec.agentId -> agent (with full spec); an empty
+ *        agent_instance_id ends the chain at the session (the built-in
+ *        assistant).
  */
 export async function resolveBlueprint(
   client: StigmerClient,
@@ -55,18 +65,22 @@ export async function resolveBlueprint(
 ): Promise<ResolvedBlueprint> {
   const sessionSpec = session.spec!;
 
-  const agentInstance = await client.getAgentInstance(sessionSpec.agentInstanceId);
-  const agentId = agentInstance.spec!.agentId;
-  const agent = await client.getAgent(agentId);
-  const agentSpec = agent.spec!;
+  let agent: Agent | undefined;
+  let agentSpec: AgentSpec | undefined;
+  if (sessionSpec.agentInstanceId !== "") {
+    const agentInstance = await client.getAgentInstance(sessionSpec.agentInstanceId);
+    const agentId = agentInstance.spec!.agentId;
+    agent = await client.getAgent(agentId);
+    agentSpec = agent.spec!;
+  }
 
   const mergedMcpServerUsages = mergeMcpServerUsages(
-    agentSpec.mcpServerUsages,
+    agentSpec?.mcpServerUsages ?? [],
     sessionSpec.mcpServerUsages,
   );
 
   const mergedSkillRefs = mergeSkillRefs(
-    agentSpec.skillRefs,
+    agentSpec?.skillRefs ?? [],
     sessionSpec.skillRefs,
   );
 
@@ -74,11 +88,10 @@ export async function resolveBlueprint(
 
   return {
     agent,
-    agentSpec,
     session,
     sessionSpec,
-    instructions: agentSpec.instructions,
-    subAgents: agentSpec.subAgents,
+    instructions: agentSpec?.instructions ?? "",
+    subAgents: agentSpec?.subAgents ?? [],
     mergedMcpServerUsages,
     mergedSkillRefs,
     cloudRepos,

package/src/shared/builtin-assistant-prompt.ts

@@ -0,0 +1,38 @@
+/**
+ * The built-in assistant's instructions: the ONE text a run reads when its
+ * blueprint carries no instructions — because the session names no agent
+ * (session/v1/spec.proto, an empty agent_instance_id) or because the agent
+ * it names left its instructions empty. Both harnesses' prompt builders
+ * substitute these words on that arm and frame them their own way (the
+ * `prompt-sections.ts` doctrine: the framing is house style, the words are
+ * shared), so a person who picks no agent meets the same assistant on the
+ * native and the Cursor harness, and a maintainer changes the assistant in
+ * one place.
+ *
+ * A prompt is code: versioned here, pinned by the prompt goldens of both
+ * harnesses (`execute-deep-agent/__tests__/goldens/system-prompt.minimal.prompt.md`,
+ * `execute-cursor/__tests__/goldens/*no-instructions*`). There is no stored
+ * "default agent" row anywhere whose instructions could drift from these.
+ *
+ * What the words leave to the builders on purpose: the response rules, the
+ * sub-agent rules, the skills protocol and every other section quote an
+ * engine's tools and stay per harness. These words say who the assistant
+ * is and how it works with a person; nothing here names a tool.
+ */
+
+/** The display name every surface uses for the built-in assistant. */
+export const BUILT_IN_ASSISTANT_NAME = "Assistant";
+
+export const BUILT_IN_ASSISTANT_INSTRUCTIONS = [
+  "You are Stigmer's assistant. Help with whatever the person brings: answer, reason, write and edit, and use the tools and skills attached to this conversation when they help.",
+  "Be direct and concrete. Say what you do not know. Ask when a request is ambiguous. Prefer changing what exists over creating anew.",
+].join("\n");
+
+/**
+ * The instructions a run reads: the blueprint's own when it has any, the
+ * built-in assistant's otherwise. Both prompt builders call this on their
+ * instructions arm so neither carries a second copy of the fallback.
+ */
+export function effectiveInstructions(instructions: string): string {
+  return instructions === "" ? BUILT_IN_ASSISTANT_INSTRUCTIONS : instructions;
+}

package/src/shared/cold-start-timing.ts

@@ -31,7 +31,7 @@ export interface TimingSegment {
 }
 
 /**
- * Records a linear sequence of named segments.
+ * Records named segments on one timeline, two ways.
  *
  * `mark(name)` closes the span from the previous mark (or the origin) and
  * names it — so instrumentation reads as one line placed AFTER the work it
@@ -42,11 +42,22 @@ export interface TimingSegment {
  * const execution = await client.getExecution(executionId);
  * timing.mark("fetch_execution");
  * ```
+ *
+ * `span(name, startMs, endMs)` records a segment with explicit bounds, for a
+ * timeline whose phases OVERLAP (a tool call inside a model round, a
+ * sub-agent across two rounds) and so cannot be written as a chain of marks.
+ * A span never moves the mark cursor: a `mark` after a `span` still measures
+ * from the previous MARK, so the two idioms compose on one recorder without
+ * either changing what the other means. `totalMs()` is the latest end on the
+ * timeline, whichever way it was recorded — for a mark-only recorder that is
+ * the last mark, as it always was.
  */
 export class TimingRecorder {
   private readonly originMs: number;
   private readonly segments: TimingSegment[] = [];
   private lastMarkMs: number;
+  /** Absolute end of the segment that ends latest, by either idiom. */
+  private latestEndMs: number;
 
   /**
    * @param originMs absolute `performance.now()`-scale origin. Defaults to
@@ -57,6 +68,7 @@ export class TimingRecorder {
   constructor(originMs: number = performance.now()) {
     this.originMs = originMs;
     this.lastMarkMs = originMs;
+    this.latestEndMs = originMs;
   }
 
   /** Close the span since the previous mark (or origin) and name it. */
@@ -68,11 +80,25 @@ export class TimingRecorder {
       durationMs: round1(now - this.lastMarkMs),
     });
     this.lastMarkMs = now;
+    if (now > this.latestEndMs) this.latestEndMs = now;
+  }
+
+  /**
+   * Record a segment with explicit absolute bounds (`performance.now()`
+   * scale, like the origin). Leaves the mark cursor where it was.
+   */
+  span(name: string, startMs: number, endMs: number): void {
+    this.segments.push({
+      name,
+      startMs: round1(startMs - this.originMs),
+      durationMs: round1(endMs - startMs),
+    });
+    if (endMs > this.latestEndMs) this.latestEndMs = endMs;
   }
 
-  /** Total elapsed time from the origin to the latest mark (ms). */
+  /** Elapsed time from the origin to the latest end on the timeline (ms). */
   totalMs(): number {
-    return round1(this.lastMarkMs - this.originMs);
+    return round1(this.latestEndMs - this.originMs);
   }
 
   snapshot(): readonly TimingSegment[] {