@stigmer/runner 3.20.0 → 3.21.0

package/src/activities/execute-cursor/prompt-builder.ts

@@ -48,6 +48,7 @@ import {
   type StandingSectionKind,
   type VisionPromptInfo,
 } from "../../shared/prompt-sections.js";
+import { effectiveInstructions } from "../../shared/builtin-assistant-prompt.js";
 import { formatTurnRecoveryText } from "./turn-recovery.js";
 import type { SkillMetadata } from "../../shared/skill-resolver.js";
 import type { AgentResolution, AgentResolutionReason } from "./session-lifecycle.js";
@@ -201,9 +202,10 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
     sections.push(implementPlan);
   }
 
-  if (options.instructions) {
-    sections.push(formatInstructions(options.instructions));
-  }
+  // The blueprint's instructions, or the built-in assistant's when it
+  // carries none (a session with no agent, or an agent that left them
+  // empty) — the one text both harnesses read on this arm.
+  sections.push(formatInstructions(effectiveInstructions(options.instructions)));
 
   if (options.skills.length > 0) {
     sections.push(formatSkillsSection(options.skills));
@@ -241,6 +243,9 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
     sections.push(formatReferencedFiles(options.workspaceFileRefs));
   }
 
+  // The engine-facing house rules ride along when the blueprint itself
+  // said nothing about how to respond; an author's instructions are taken
+  // to have covered them.
   if (!options.instructions) {
     sections.push(formatResponseRules());
   }

package/src/activities/execute-deep-agent/__tests__/goldens/system-prompt.minimal.prompt.md

@@ -1,4 +1,5 @@
-You are a helpful AI assistant.
+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.
 
 ## Response rules
 

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__/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/turn-context.ts

@@ -759,7 +759,9 @@ export async function resolveMcpServersAndPolicies(
     execution.spec?.recalledMemories,
     {
       org: session.metadata?.org ?? "",
-      agentId: blueprint.agent.metadata?.id ?? "",
+      // Provenance, not scope: empty for the built-in assistant, and the
+      // carrier omits an empty field (memory-attachment.ts).
+      agentId: blueprint.agent?.metadata?.id ?? "",
       sessionId,
       agentExecutionId: executionId,
     },

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/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;
+}