@stigmer/runner 3.19.1-dev.20260920100552 → 3.21.0

package/dist/harness/turn-timeline.js

@@ -0,0 +1,213 @@
+/**
+ * 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";
+/** The `stigmer_timing` selector of the line this module emits. */
+export const TURN_PHASES_EVENT = "turn_phases";
+export class TurnTimeline {
+    clock;
+    firstEventMs;
+    firstVisibleTokenMs;
+    firstTextMs;
+    lastEventMs;
+    maxGapMs;
+    rounds = new Map();
+    tools = new Map();
+    subAgents = new Map();
+    constructor(clock) {
+        this.clock = clock;
+    }
+    /** The builder's observer: place one folded event on the timeline. */
+    observe(event) {
+        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 = event;
+                throw new Error(`unknown transcript event ${String(exhaustive.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) {
+        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);
+    }
+    noteEvent(at) {
+        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. */
+    open(spans, id, name, at) {
+        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. */
+    close(spans, id, at) {
+        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.
+     */
+    placeObserved(observedAt, foldAt) {
+        if (observedAt === undefined)
+            return foldAt;
+        const wallMs = Date.parse(observedAt);
+        if (Number.isNaN(wallMs))
+            return foldAt;
+        return this.clock.originMs + (wallMs - this.clock.originWallMs);
+    }
+    offset(absoluteMs) {
+        return absoluteMs === undefined ? null : round1(absoluteMs - this.clock.originMs);
+    }
+}
+function toolSpanName(name, mcpServerSlug) {
+    return mcpServerSlug ? `tool:${mcpServerSlug}/${name}` : `tool:${name}`;
+}
+function round1(ms) {
+    return Math.round(ms * 10) / 10;
+}
+//# sourceMappingURL=turn-timeline.js.map

package/dist/harness/turn-timeline.js.map

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

package/dist/shared/blueprint-resolver.d.ts

@@ -6,13 +6,21 @@
  * 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.
  */
 import type { StigmerClient } from "../client/stigmer-client.js";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
-import type { AgentSpec, McpServerUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { McpServerUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
@@ -23,8 +31,8 @@ export interface CloudRepo {
     startingRef?: string;
 }
 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;
@@ -37,7 +45,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 declare function resolveBlueprint(client: StigmerClient, session: Session): Promise<ResolvedBlueprint>;
 /**

package/dist/shared/blueprint-resolver.js

@@ -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.
@@ -20,24 +28,29 @@ export { mergeMcpServerUsages } from "./mcp-resolver.js";
  * 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, session) {
     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;
-    const mergedMcpServerUsages = mergeMcpServerUsages(agentSpec.mcpServerUsages, sessionSpec.mcpServerUsages);
-    const mergedSkillRefs = mergeSkillRefs(agentSpec.skillRefs, sessionSpec.skillRefs);
+    let agent;
+    let agentSpec;
+    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 ?? [], sessionSpec.mcpServerUsages);
+    const mergedSkillRefs = mergeSkillRefs(agentSpec?.skillRefs ?? [], sessionSpec.skillRefs);
     const cloudRepos = resolveCloudRepos(sessionSpec.workspaceEntries);
     return {
         agent,
-        agentSpec,
         session,
         sessionSpec,
-        instructions: agentSpec.instructions,
-        subAgents: agentSpec.subAgents,
+        instructions: agentSpec?.instructions ?? "",
+        subAgents: agentSpec?.subAgents ?? [],
         mergedMcpServerUsages,
         mergedSkillRefs,
         cloudRepos,

package/dist/shared/blueprint-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint-resolver.js","sourceRoot":"","sources":["../../src/shared/blueprint-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,iCAAiC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAmBzD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAqB,EACrB,OAAgB;IAEhB,MAAM,WAAW,GAAG,OAAO,CAAC,IAAK,CAAC;IAElC,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;IACjF,MAAM,OAAO,GAAG,aAAa,CAAC,IAAK,CAAC,OAAO,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,KAAK,CAAC,IAAK,CAAC;IAE9B,MAAM,qBAAqB,GAAG,oBAAoB,CAChD,SAAS,CAAC,eAAe,EACzB,WAAW,CAAC,eAAe,CAC5B,CAAC;IAEF,MAAM,eAAe,GAAG,cAAc,CACpC,SAAS,CAAC,SAAS,EACnB,WAAW,CAAC,SAAS,CACtB,CAAC;IAEF,MAAM,UAAU,GAAG,iBAAiB,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAEnE,OAAO;QACL,KAAK;QACL,SAAS;QACT,OAAO;QACP,WAAW;QACX,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,qBAAqB;QACrB,eAAe;QACf,UAAU;KACX,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,gBAAkC;IAClE,MAAM,KAAK,GAAgB,EAAE,CAAC;IAE9B,KAAK,MAAM,KAAK,IAAI,gBAAgB,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC;gBACT,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,WAAW,EAAE,GAAG,CAAC,MAAM,IAAI,SAAS;aACrC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAiC,EACjC,WAAmC;IAEnC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgC,CAAC;IAEvD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,GAAG,CAAC,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"blueprint-resolver.js","sourceRoot":"","sources":["../../src/shared/blueprint-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,iCAAiC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAmBzD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAqB,EACrB,OAAgB;IAEhB,MAAM,WAAW,GAAG,OAAO,CAAC,IAAK,CAAC;IAElC,IAAI,KAAwB,CAAC;IAC7B,IAAI,SAAgC,CAAC;IACrC,IAAI,WAAW,CAAC,eAAe,KAAK,EAAE,EAAE,CAAC;QACvC,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QACjF,MAAM,OAAO,GAAG,aAAa,CAAC,IAAK,CAAC,OAAO,CAAC;QAC5C,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,SAAS,GAAG,KAAK,CAAC,IAAK,CAAC;IAC1B,CAAC;IAED,MAAM,qBAAqB,GAAG,oBAAoB,CAChD,SAAS,EAAE,eAAe,IAAI,EAAE,EAChC,WAAW,CAAC,eAAe,CAC5B,CAAC;IAEF,MAAM,eAAe,GAAG,cAAc,CACpC,SAAS,EAAE,SAAS,IAAI,EAAE,EAC1B,WAAW,CAAC,SAAS,CACtB,CAAC;IAEF,MAAM,UAAU,GAAG,iBAAiB,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAEnE,OAAO;QACL,KAAK;QACL,OAAO;QACP,WAAW;QACX,YAAY,EAAE,SAAS,EAAE,YAAY,IAAI,EAAE;QAC3C,SAAS,EAAE,SAAS,EAAE,SAAS,IAAI,EAAE;QACrC,qBAAqB;QACrB,eAAe;QACf,UAAU;KACX,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,gBAAkC;IAClE,MAAM,KAAK,GAAgB,EAAE,CAAC;IAE9B,KAAK,MAAM,KAAK,IAAI,gBAAgB,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC;gBACT,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,WAAW,EAAE,GAAG,CAAC,MAAM,IAAI,SAAS;aACrC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAiC,EACjC,WAAmC;IAEnC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgC,CAAC;IAEvD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,GAAG,CAAC,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC"}

package/dist/shared/builtin-assistant-prompt.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare const BUILT_IN_ASSISTANT_NAME = "Assistant";
+export declare const BUILT_IN_ASSISTANT_INSTRUCTIONS: string;
+/**
+ * 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 declare function effectiveInstructions(instructions: string): string;

package/dist/shared/builtin-assistant-prompt.js

@@ -0,0 +1,36 @@
+/**
+ * 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) {
+    return instructions === "" ? BUILT_IN_ASSISTANT_INSTRUCTIONS : instructions;
+}
+//# sourceMappingURL=builtin-assistant-prompt.js.map

package/dist/shared/builtin-assistant-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-assistant-prompt.js","sourceRoot":"","sources":["../../src/shared/builtin-assistant-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAG,WAAW,CAAC;AAEnD,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,+KAA+K;IAC/K,oIAAoI;CACrI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,OAAO,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,YAAY,CAAC;AAC9E,CAAC"}

package/dist/shared/cold-start-timing.d.ts

@@ -24,7 +24,7 @@ export interface TimingSegment {
     readonly durationMs: number;
 }
 /**
- * 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
@@ -35,11 +35,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 declare class TimingRecorder {
     private readonly originMs;
     private readonly segments;
     private lastMarkMs;
+    /** Absolute end of the segment that ends latest, by either idiom. */
+    private latestEndMs;
     /**
      * @param originMs absolute `performance.now()`-scale origin. Defaults to
      *   "now" (per-execution timelines). Pass 0 for a process-lifetime timeline
@@ -49,7 +60,12 @@ export declare class TimingRecorder {
     constructor(originMs?: number);
     /** Close the span since the previous mark (or origin) and name it. */
     mark(name: string): void;
-    /** Total elapsed time from the origin to the latest mark (ms). */
+    /**
+     * 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;
+    /** Elapsed time from the origin to the latest end on the timeline (ms). */
     totalMs(): number;
     snapshot(): readonly TimingSegment[];
 }

package/dist/shared/cold-start-timing.js

@@ -21,7 +21,7 @@
 // while per-call dynamic imports raced under concurrent emissions.
 import { getInstruments } from "../otel-metrics.js";
 /**
- * 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
@@ -32,11 +32,22 @@ import { getInstruments } from "../otel-metrics.js";
  * 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 {
     originMs;
     segments = [];
     lastMarkMs;
+    /** Absolute end of the segment that ends latest, by either idiom. */
+    latestEndMs;
     /**
      * @param originMs absolute `performance.now()`-scale origin. Defaults to
      *   "now" (per-execution timelines). Pass 0 for a process-lifetime timeline
@@ -46,6 +57,7 @@ export class TimingRecorder {
     constructor(originMs = performance.now()) {
         this.originMs = originMs;
         this.lastMarkMs = originMs;
+        this.latestEndMs = originMs;
     }
     /** Close the span since the previous mark (or origin) and name it. */
     mark(name) {
@@ -56,10 +68,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, startMs, endMs) {
+        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() {
-        return round1(this.lastMarkMs - this.originMs);
+        return round1(this.latestEndMs - this.originMs);
     }
     snapshot() {
         return this.segments;

package/dist/shared/cold-start-timing.js.map

@@ -1 +1 @@
-{"version":3,"file":"cold-start-timing.js","sourceRoot":"","sources":["../../src/shared/cold-start-timing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cold-start-timing.js","sourceRoot":"","sources":["../../src/shared/cold-start-timing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.19.1-dev.20260920100552",
+  "version": "3.21.0",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -104,10 +104,10 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/outbound": "3.19.1-dev.20260920100552",
-    "@stigmer/protos": "3.19.1-dev.20260920100552",
-    "@stigmer/temporal-codecs": "3.19.1-dev.20260920100552",
-    "@stigmer/zip-structure": "3.19.1-dev.20260920100552",
+    "@stigmer/outbound": "3.21.0",
+    "@stigmer/protos": "3.21.0",
+    "@stigmer/temporal-codecs": "3.21.0",
+    "@stigmer/zip-structure": "3.21.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/common": "1.16.2",
     "@temporalio/interceptors-opentelemetry": "1.16.2",

package/src/__test-utils__/execution-record-fixture.ts

@@ -75,6 +75,13 @@ export interface ExecutionRecordOptions {
   readonly structuredOutputSchema?: JsonObject;
   /** The agent's declared sub-agents (`AgentSpec.sub_agents`). */
   readonly subAgents?: SubAgent[];
+  /**
+   * The built-in assistant: the session names NO agent instance, so the
+   * record carries no instance and no agent and the activity must run on
+   * the one built-in prompt with the session's own tools. `instructions`
+   * and `subAgents` are ignored (there is no agent to declare them).
+   */
+  readonly builtInAssistant?: boolean;
   /** The control plane's STOP lever; see `ExecutionRecordInput.controlSignal`. */
   readonly controlSignal?: ExecutionRecordInput["controlSignal"];
   readonly ids?: ExecutionRecordIds;
@@ -100,10 +107,19 @@ export function executionRecordFixture(options: ExecutionRecordOptions): Executi
   const session: Session = create(SessionSchema, {
     metadata: create(ApiResourceMetadataSchema, { id: ids.sessionId, org: ids.org, name: ids.sessionId }),
     spec: create(SessionSpecSchema, {
-      agentInstanceId: ids.agentInstanceId,
+      agentInstanceId: options.builtInAssistant === true ? "" : ids.agentInstanceId,
       workspaceEntries: options.workspaceEntries ?? [],
     }),
   });
+  if (options.builtInAssistant === true) {
+    return new ExecutionRecord({
+      execution,
+      session,
+      agentInstance: undefined,
+      agent: undefined,
+      controlSignal: options.controlSignal,
+    });
+  }
   const agentInstance: AgentInstance = create(AgentInstanceSchema, {
     metadata: create(ApiResourceMetadataSchema, { id: ids.agentInstanceId, org: ids.org, name: ids.agentInstanceId }),
     spec: create(AgentInstanceSpecSchema, { agentId: ids.agentId }),