@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

package/src/plugins/defaults/advisor/__tests__/context-pack-gating.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Personal-memory gating for the advisor context pack: NOW.md and PKB must only
+ * reach the advisor when the turn's trust admits personal memory (and, for
+ * NOW.md, when the scratchpad-injection toggle is on) — the same policy the
+ * runtime memory injectors apply. Without it, a low-risk advisor consult on a
+ * remote/trusted-contact turn could forward private content the main agent
+ * would never receive.
+ *
+ * Mocks are isolated to this file (the test runner runs each file in its own
+ * process), so the broad module stubs here don't leak into other suites.
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+let personalAllowed = false;
+let scratchpadEnabled = true;
+let gateArg: unknown = null;
+
+mock.module("../../../../daemon/trust-context.js", () => ({
+  isPersonalMemoryAllowed: (trust: unknown) => {
+    gateArg = trust;
+    return personalAllowed;
+  },
+}));
+mock.module("../../../../daemon/now-scratchpad.js", () => ({
+  readNowScratchpad: () => "NOW-CONTENT",
+}));
+mock.module("../../../../memory/pkb/context.js", () => ({
+  readPkbContext: () => "PKB-CONTENT",
+}));
+mock.module("../../../../config/loader.js", () => ({
+  getConfig: () => ({
+    memory: {
+      retrieval: { scratchpadInjection: { enabled: scratchpadEnabled } },
+    },
+    llm: {},
+  }),
+}));
+// Keep every other section empty so the assertions isolate NOW.md / PKB.
+mock.module("../../../../daemon/conversation-workspace.js", () => ({
+  resolveWorkspaceTopLevelContext: () => null,
+}));
+mock.module("../../../../daemon/conversation-runtime-assembly.js", () => ({
+  buildActiveDocuments: () => null,
+}));
+mock.module("../../../../runtime/capabilities.js", () => ({
+  resolveCapabilities: () => ({ canAccessMemory: false }),
+}));
+mock.module("../../../../config/skills.js", () => ({
+  loadSkillCatalog: () => [],
+}));
+
+const { buildAdvisorContext } = await import("../context-pack.js");
+
+const sources = {
+  conversationId: "c1",
+  workingDir: "/tmp",
+  // A remote, non-guardian per-turn snapshot — the case the live-state read
+  // could have wrongly elevated.
+  trustClass: "unknown" as const,
+  sourceChannel: "telegram",
+  transcript: [],
+  allowedToolNames: new Set<string>(),
+};
+
+beforeEach(() => {
+  personalAllowed = false;
+  scratchpadEnabled = true;
+  gateArg = null;
+});
+
+describe("advisor context pack — personal-memory gating", () => {
+  test("withholds NOW.md and PKB when personal memory is disallowed", async () => {
+    personalAllowed = false;
+    const ctx = (await buildAdvisorContext(sources)) ?? "";
+    expect(ctx).not.toContain("NOW-CONTENT");
+    expect(ctx).not.toContain("PKB-CONTENT");
+  });
+
+  test("includes NOW.md and PKB when allowed and the scratchpad toggle is on", async () => {
+    personalAllowed = true;
+    scratchpadEnabled = true;
+    const ctx = await buildAdvisorContext(sources);
+    expect(ctx).toContain("NOW-CONTENT");
+    expect(ctx).toContain("PKB-CONTENT");
+  });
+
+  test("withholds NOW.md when the scratchpad toggle is off, PKB still allowed", async () => {
+    personalAllowed = true;
+    scratchpadEnabled = false;
+    const ctx = (await buildAdvisorContext(sources)) ?? "";
+    expect(ctx).not.toContain("NOW-CONTENT");
+    expect(ctx).toContain("PKB-CONTENT");
+  });
+
+  test("feeds the gate the per-turn trust snapshot, not live conversation state", async () => {
+    personalAllowed = true;
+    await buildAdvisorContext(sources);
+    // The gate must see exactly the snapshot threaded from ToolContext —
+    // trustClass + executionChannel — so a concurrent live-trust change can't
+    // elevate this invocation.
+    expect(gateArg).toEqual({
+      sourceChannel: "telegram",
+      trustClass: "unknown",
+    });
+  });
+});

package/src/plugins/defaults/advisor/__tests__/context-pack.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+
+import type { Message } from "../../../../providers/types.js";
+import { buildAdvisorContext, deriveRecallQuery } from "../context-pack.js";
+
+const userMsg = (t: string): Message => ({
+  role: "user",
+  content: [{ type: "text", text: t }],
+});
+
+describe("deriveRecallQuery", () => {
+  test("returns the most recent user message text", () => {
+    const query = deriveRecallQuery([
+      userMsg("the original task"),
+      { role: "assistant", content: [{ type: "text", text: "ok" }] },
+      userMsg("the latest question"),
+    ]);
+    expect(query).toBe("the latest question");
+  });
+
+  test("returns null when there is no user text", () => {
+    expect(
+      deriveRecallQuery([
+        { role: "assistant", content: [{ type: "text", text: "hi" }] },
+      ]),
+    ).toBeNull();
+    expect(deriveRecallQuery([])).toBeNull();
+  });
+});
+
+describe("buildAdvisorContext", () => {
+  test("lists the agent's available tools, skipping the advisor itself", async () => {
+    const context = await buildAdvisorContext({
+      conversationId: "ctx-1",
+      workingDir: "/tmp/does-not-exist",
+      allowedToolNames: new Set(["bash", "advisor", "read_file"]),
+      trustClass: "unknown",
+      transcript: [userMsg("hi")],
+    });
+
+    expect(context).toContain("## Available tools");
+    expect(context).toContain("- bash");
+    expect(context).toContain("- read_file");
+    // The advisor advises; it never tells the agent to consult itself.
+    expect(context).not.toContain("- advisor");
+  });
+
+  test("omits the tools section when no tools are available", async () => {
+    const context = await buildAdvisorContext({
+      conversationId: "ctx-2",
+      workingDir: "/tmp/does-not-exist",
+      allowedToolNames: new Set(),
+      trustClass: "unknown",
+      transcript: [],
+    });
+    // Other sources (e.g. the skills catalog) may still contribute, but with no
+    // allowed tools the tools section must not appear.
+    if (context !== null) expect(context).not.toContain("## Available tools");
+  });
+});

package/src/plugins/defaults/advisor/consult.ts

@@ -16,7 +16,11 @@ import {
   getConfiguredProvider,
   userMessage,
 } from "../../../providers/provider-send-message.js";
-import type { Message } from "../../../providers/types.js";
+import type {
+  Message,
+  ProviderEvent,
+  ToolDefinition,
+} from "../../../providers/types.js";
 import { ADVISOR_CONFIG } from "./config.js";
 import { advisorRequestText, buildAdvisorSystem } from "./steering.js";
 import { toAdvisorMessages } from "./transcript.js";
@@ -26,6 +30,26 @@ import { toAdvisorMessages } from "./transcript.js";
 // on via `llm.advisorProfile`, which we float above the call-site layers.
 const ADVISOR_CALL_SITE: LLMCallSite = "advisor";
 
+/**
+ * The single tool the consult may attach: a `web_search`-named tool that
+ * provider-native search (Anthropic/OpenAI) substitutes for its server-side
+ * web tool. Only passed when `provider.supportsNativeWebSearch` is true, so the
+ * provider runs the search itself and returns results inline — no agent loop,
+ * which keeps the consult a one-shot completion.
+ */
+const ADVISOR_WEB_SEARCH_TOOL: ToolDefinition = {
+  name: "web_search",
+  description:
+    "Search the web for current information to ground your guidance.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "The search query." },
+    },
+    required: ["query"],
+  },
+};
+
 /**
  * Resolve the routing override for the advisor consult. When the workspace has
  * set `llm.advisorProfile`, force it above the call-site layers so it is
@@ -45,7 +69,22 @@ function advisorOverride(): {
 export interface ConsultParams {
   systemPrompt: string | null;
   messages: ReadonlyArray<Message>;
+  /**
+   * The agent's runtime context (available tools and skills, workspace/project
+   * context, recalled memory), gathered by the tool from its `ToolContext`.
+   * Embedded in the advisor's system prompt so its advice is grounded in what
+   * the agent can actually do. Omitted/null when nothing could be gathered.
+   */
+  runtimeContext?: string | null;
   signal?: AbortSignal;
+  /**
+   * Optional sink for the advisor's live activity as it generates: incremental
+   * advice text, the reasoning summary (when surfaced), and a note per web
+   * search. Wiring this to the tool's `onOutput` surfaces the consult live as
+   * `tool_output_chunk` while the advisor is still working; the complete
+   * guidance is still returned as the resolved string. See `advisorActivitySink`.
+   */
+  onText?: (chunk: string) => void;
 }
 
 /** Combine the caller's signal with a consult timeout. */
@@ -54,6 +93,55 @@ function withTimeout(signal: AbortSignal | undefined, ms: number): AbortSignal {
   return signal ? AbortSignal.any([signal, timeout]) : timeout;
 }
 
+/**
+ * Build the streaming sink for a consult: forward the advisor's live activity
+ * to `onText` so the tool-output drawer streams throughout the consult instead
+ * of sitting silent until the final advice lands.
+ *
+ * The consult searches the web (up to 5×) and reasons over full context before
+ * writing its guidance. Forwarding the visible advice text alone would leave
+ * the drawer blank for that whole prefix, so the sink also surfaces the
+ * reasoning summary (when the model emits one) and a one-line note per web
+ * search — a success note with the query, or a failure note when the search
+ * errors. The complete guidance is still returned by `consultAdvisor`; the
+ * renderer swaps it in once the tool result arrives.
+ */
+function advisorActivitySink(
+  onText: (chunk: string) => void,
+): (event: ProviderEvent) => void {
+  return (event) => {
+    switch (event.type) {
+      case "text_delta":
+        if (event.text) onText(event.text);
+        break;
+      case "thinking_delta":
+        if (event.thinking) onText(event.thinking);
+        break;
+      case "server_tool_start":
+        if (event.name === "web_search") onText("\n🔎 Searching the web…\n");
+        break;
+      case "server_tool_complete": {
+        const rawQuery = event.resolvedInput?.["query"];
+        const query = typeof rawQuery === "string" ? rawQuery.trim() : "";
+        if (event.isError) {
+          // A failed search (e.g. `query_too_long`, `max_uses_exceeded`) must
+          // not be announced as a success — the advisor proceeds without it.
+          onText(
+            query
+              ? `\n⚠️ Web search failed: ${query}\n`
+              : "\n⚠️ Web search failed.\n",
+          );
+        } else if (query) {
+          onText(`\n🔎 Searched: ${query}\n`);
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  };
+}
+
 /**
  * Returns the advisor's guidance text, or a short benign notice when the
  * advisor can't run. Callers should surface the string as a non-error tool
@@ -73,17 +161,33 @@ export async function consultAdvisor(params: ConsultParams): Promise<string> {
   }
 
   // Append the consult instruction as the final user turn, then run a
-  // tool-less completion through the resolved provider. No `max_tokens` is
-  // set, so the resolver applies the profile's normal output budget rather
-  // than an advisor-specific cap.
+  // completion through the resolved provider. No `max_tokens` is set, so the
+  // resolver applies the profile's normal output budget rather than an
+  // advisor-specific cap.
   const messages: Message[] = [...history, userMessage(advisorRequestText())];
 
+  // Give the advisor live web access when — and only when — the resolved
+  // provider runs search server-side (provider-native). Passing a `web_search`
+  // tool to a non-native provider would surface a client tool call this
+  // one-shot consult cannot execute, so we gate strictly on the capability and
+  // otherwise keep the consult tool-less.
+  const webEnabled = provider.supportsNativeWebSearch === true;
+
+  const { onText } = params;
   const response = await provider.sendMessage(messages, {
-    systemPrompt: buildAdvisorSystem(params.systemPrompt),
+    systemPrompt: buildAdvisorSystem(
+      params.systemPrompt,
+      params.runtimeContext,
+    ),
+    ...(webEnabled ? { tools: [ADVISOR_WEB_SEARCH_TOOL] } : {}),
+    // Stream the consult's activity live (advice text, reasoning summary, and a
+    // note per web search) so the drawer isn't blank while the advisor searches
+    // and reasons before writing its guidance. See `advisorActivitySink`.
+    onEvent: onText ? advisorActivitySink(onText) : undefined,
     config: {
       callSite: ADVISOR_CALL_SITE,
       ...override,
-      tool_choice: { type: "none" },
+      tool_choice: webEnabled ? { type: "auto" } : { type: "none" },
     },
     signal: withTimeout(params.signal, ADVISOR_CONFIG.timeoutMs),
   });

package/src/plugins/defaults/advisor/context-pack.ts

@@ -0,0 +1,288 @@
+/**
+ * Assemble the runtime context the advisor needs to make grounded
+ * recommendations — the same situational awareness the executing agent has:
+ *  - the tools available to it this turn,
+ *  - the skills it can load,
+ *  - the loaded workspace / project context, NOW.md, PKB, and open documents,
+ *  - and relevant memory pulled through the recall search.
+ *
+ * The advisor already receives the agent's transcript and system prompt; this
+ * adds the situational context that lives *outside* the prompt (tools and
+ * skills are passed to the model as a separate catalog, not inlined) plus a
+ * fresh, task-focused memory recall.
+ *
+ * Personal-memory surfaces are gated to the same policy the main agent's
+ * memory injectors apply: the recall search honors `canAccessMemory` (like the
+ * `recall` tool), and NOW.md / PKB honor `isPersonalMemoryAllowed` (plus the
+ * scratchpad-injection toggle for NOW.md). The advisor tool is low-risk and can
+ * run on remote/trusted-contact turns, so without these gates it could forward
+ * private content the main agent itself would not receive.
+ *
+ * Every section is best-effort: each source is wrapped so a failure or empty
+ * result drops just that section, never the consult. Daemon- and memory-side
+ * modules are pulled in via dynamic `import()` so this plugin module — loaded
+ * at bootstrap through `defaults/index.ts` — never forms a static import cycle
+ * with them. The result is a single string injected into the advisor's system
+ * prompt (see `buildAdvisorSystem`), or `null` when nothing could be gathered.
+ */
+
+import type { ChannelId } from "../../../channels/types.js";
+import type { TrustContext } from "../../../daemon/trust-context.js";
+import type { Message } from "../../../providers/types.js";
+import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+
+export interface AdvisorContextSources {
+  conversationId: string;
+  workingDir: string;
+  /** The live tool set the executor sees this turn (`ToolContext.allowedToolNames`). */
+  allowedToolNames?: ReadonlySet<string>;
+  /**
+   * Trust class of the turn's actor, from the per-turn `ToolContext.trustClass`
+   * snapshot. Gates the memory recall and (with {@link sourceChannel}) the
+   * personal-memory surfaces.
+   */
+  trustClass: TrustClass;
+  /**
+   * Channel the turn originates on, from the per-turn `ToolContext.executionChannel`
+   * snapshot. Combined with {@link trustClass} to evaluate personal-memory
+   * access exactly as the injectors do, off the same per-turn snapshot rather
+   * than the mutable live conversation trust.
+   */
+  sourceChannel?: string;
+  /** The captured transcript, used to derive the recall query. */
+  transcript: ReadonlyArray<Message>;
+  signal?: AbortSignal;
+}
+
+/** Cap a block so the assembled context never balloons the consult prompt. */
+function truncate(text: string, max: number): string {
+  const trimmed = text.trim();
+  return trimmed.length <= max ? trimmed : `${trimmed.slice(0, max)}…`;
+}
+
+/** First sentence (or a capped prefix) of a tool/skill description. */
+function summarize(description: string | undefined, max = 160): string {
+  if (!description) return "";
+  const firstSentence = description.split(/(?<=[.!?])\s/)[0] ?? description;
+  return truncate(firstSentence, max);
+}
+
+/** Pull the most recent user-authored text to seed the memory recall query. */
+export function deriveRecallQuery(
+  transcript: ReadonlyArray<Message>,
+): string | null {
+  for (let i = transcript.length - 1; i >= 0; i--) {
+    const message = transcript[i];
+    if (message.role !== "user") continue;
+    const text = message.content
+      .map((block) => (block.type === "text" ? block.text : ""))
+      .join(" ")
+      .trim();
+    if (text.length > 0) return truncate(text, 500);
+  }
+  return null;
+}
+
+/** `## Available tools` — the live tool set the agent can act with this turn. */
+async function buildToolsSection(
+  allowedToolNames: ReadonlySet<string> | undefined,
+): Promise<string | null> {
+  if (!allowedToolNames || allowedToolNames.size === 0) return null;
+  try {
+    const { getTool } = await import("../../../tools/registry.js");
+    const lines: string[] = [];
+    for (const name of [...allowedToolNames].sort()) {
+      // The advisor advises; it never recommends consulting itself.
+      if (name === "advisor") continue;
+      const summary = summarize(getTool(name)?.description);
+      lines.push(summary ? `- ${name} — ${summary}` : `- ${name}`);
+    }
+    if (lines.length === 0) return null;
+    return `## Available tools (what the agent can do)\n${lines.join("\n")}`;
+  } catch {
+    return null;
+  }
+}
+
+/** `## Available skills` — the skills the agent can load via `skill_load`. */
+async function buildSkillsSection(): Promise<string | null> {
+  try {
+    const { loadSkillCatalog } = await import("../../../config/skills.js");
+    const catalog = loadSkillCatalog();
+    if (catalog.length === 0) return null;
+    const lines = catalog.slice(0, 60).map((skill) => {
+      const summary = summarize(skill.description);
+      const when = skill.activationHints?.length
+        ? ` (use when: ${truncate(skill.activationHints.join("; "), 120)})`
+        : "";
+      const label = skill.displayName || skill.name || skill.id;
+      return `- ${label} (${skill.id})${summary ? ` — ${summary}` : ""}${when}`;
+    });
+    const more =
+      catalog.length > 60 ? `\n- …and ${catalog.length - 60} more` : "";
+    return `## Available skills (load with skill_load)\n${lines.join("\n")}${more}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether personal-memory surfaces (NOW.md, PKB) may be exposed to the advisor
+ * — the same `isPersonalMemoryAllowed` gate the runtime memory injectors apply.
+ *
+ * Derived from the per-turn trust snapshot (`ToolContext.trustClass` /
+ * `executionChannel`, threaded in via {@link AdvisorContextSources}), NOT the
+ * live `findConversation().trustContext`: that conversation state is mutable
+ * and a concurrent guardian/meta command could flip it to guardian mid-flight,
+ * granting a remote/non-guardian turn access its own snapshot was never given.
+ * Fail-closed: if the gate can't be resolved, returns false.
+ */
+async function personalMemoryAllowedForAdvisor(
+  trustClass: TrustClass,
+  sourceChannel: string | undefined,
+): Promise<boolean> {
+  try {
+    const { isPersonalMemoryAllowed } =
+      await import("../../../daemon/trust-context.js");
+    // `isPersonalMemoryAllowed` reads only `sourceChannel` + `trustClass`; build
+    // a minimal trust context from the per-turn snapshot. The channel may be
+    // absent (local/internal turns), which the gate treats as non-remote.
+    const snapshot = {
+      sourceChannel: sourceChannel as ChannelId | undefined,
+      trustClass,
+    } as TrustContext;
+    return isPersonalMemoryAllowed(snapshot);
+  } catch {
+    return false;
+  }
+}
+
+/** `## Workspace & project context` — the loaded environment around the agent. */
+async function buildWorkspaceSection(
+  sources: AdvisorContextSources,
+): Promise<string | null> {
+  const { conversationId } = sources;
+  const parts: string[] = [];
+
+  // The `<workspace>` directory listing is not personal memory — the agent's
+  // own file tools already operate in this cwd — so it is surfaced ungated, the
+  // same way the workspace-context injector does.
+  try {
+    const { resolveWorkspaceTopLevelContext } =
+      await import("../../../daemon/conversation-workspace.js");
+    const workspace = resolveWorkspaceTopLevelContext(conversationId);
+    if (workspace) parts.push(truncate(workspace, 2500));
+  } catch {
+    /* best-effort */
+  }
+
+  // NOW.md and PKB are personal-memory surfaces. Gate them behind the same
+  // `isPersonalMemoryAllowed` policy (and, for NOW.md, the scratchpad-injection
+  // toggle) the runtime injectors use, evaluated off the per-turn trust
+  // snapshot, so a low-risk advisor consult cannot forward private content the
+  // main agent would never receive.
+  if (
+    await personalMemoryAllowedForAdvisor(
+      sources.trustClass,
+      sources.sourceChannel,
+    )
+  ) {
+    try {
+      const [{ readNowScratchpad }, { getConfig }] = await Promise.all([
+        import("../../../daemon/now-scratchpad.js"),
+        import("../../../config/loader.js"),
+      ]);
+      if (getConfig().memory.retrieval.scratchpadInjection.enabled) {
+        const now = readNowScratchpad();
+        if (now) parts.push(`NOW.md scratchpad:\n${truncate(now, 1500)}`);
+      }
+    } catch {
+      /* best-effort */
+    }
+
+    try {
+      const { readPkbContext } = await import("../../../memory/pkb/context.js");
+      const pkb = readPkbContext();
+      if (pkb) parts.push(truncate(pkb, 1500));
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  try {
+    const { buildActiveDocuments } =
+      await import("../../../daemon/conversation-runtime-assembly.js");
+    const docs = buildActiveDocuments(conversationId);
+    if (docs && docs.length > 0) {
+      const titles = docs
+        .slice(0, 20)
+        .map((doc) => `- ${doc.title} (${doc.wordCount} words)`)
+        .join("\n");
+      parts.push(`Open documents:\n${titles}`);
+    }
+  } catch {
+    /* best-effort */
+  }
+
+  if (parts.length === 0) return null;
+  return `## Workspace & project context\n${parts.join("\n\n")}`;
+}
+
+/** `## Relevant memory (recall)` — a fresh, task-focused recall search. */
+async function buildMemorySection(
+  sources: AdvisorContextSources,
+): Promise<string | null> {
+  try {
+    const { resolveCapabilities } =
+      await import("../../../runtime/capabilities.js");
+    // Recall reads sensitive local context; honor the same trust gate the
+    // `recall` tool applies. Non-guardian turns get no fresh recall here.
+    if (!resolveCapabilities(sources.trustClass).canAccessMemory) return null;
+
+    const query = deriveRecallQuery(sources.transcript);
+    if (!query) return null;
+
+    const [{ runDeterministicRecallSearch }, { getConfig }] = await Promise.all(
+      [
+        import("../../../memory/context-search/search.js"),
+        import("../../../config/loader.js"),
+      ],
+    );
+
+    const { evidence } = await runDeterministicRecallSearch(
+      { query, max_results: 8 },
+      {
+        workingDir: sources.workingDir,
+        conversationId: sources.conversationId,
+        config: getConfig(),
+        signal: sources.signal,
+      },
+    );
+    if (evidence.length === 0) return null;
+
+    const lines = evidence.slice(0, 8).map((item) => {
+      const excerpt = truncate(item.excerpt, 220);
+      return `- [${item.source}] ${item.title} (${item.locator}): ${excerpt}`;
+    });
+    return `## Relevant memory (recall: "${truncate(query, 120)}")\n${lines.join("\n")}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gather the advisor's runtime context block, or `null` if nothing is
+ * available. Sections run concurrently; each is independently best-effort.
+ */
+export async function buildAdvisorContext(
+  sources: AdvisorContextSources,
+): Promise<string | null> {
+  const sections = await Promise.all([
+    buildToolsSection(sources.allowedToolNames),
+    buildSkillsSection(),
+    buildWorkspaceSection(sources),
+    buildMemorySection(sources),
+  ]);
+  const present = sections.filter((s): s is string => s !== null);
+  return present.length > 0 ? present.join("\n\n") : null;
+}

package/src/plugins/defaults/advisor/steering.ts

@@ -33,9 +33,15 @@ export function stripSteering(systemPrompt: string | null): string | null {
  * System prompt for the advisor sub-call. Frames the advisor's role and, for
  * context, quotes the executor's own system prompt (as the advisor tool does —
  * the advisor sees the system prompt as context about the executor's task).
+ *
+ * `runtimeContext`, when present, carries the agent's situational context that
+ * lives outside its system prompt — available tools and skills, workspace /
+ * project context, and recalled memory (see `buildAdvisorContext`) — so the
+ * advisor can ground its recommendations in what the agent can actually do.
  */
 export function buildAdvisorSystem(
   originalSystemPrompt: string | null,
+  runtimeContext?: string | null,
 ): string {
   const base = `You are a senior advisor consulted by another AI agent working on a task — most often at the planning stage, before it starts building, but sometimes partway through. The entire conversation above is the agent's working context: its task or goal, every tool call it has made, and every result it has seen. The agent has paused to consult you because you bring a second, independent perspective it cannot get from inside its own reasoning loop. Your job is to maximize its odds of completing the task correctly and efficiently.
 
@@ -54,8 +60,14 @@ How to advise:
 - Stay in your lane. Advise the agent; do not role-play as it, write its final deliverable, or take its next action for it. If the agent is already on the right track, confirm it and sharpen the plan rather than manufacturing objections.
 
 Write as much as the guidance genuinely needs, and no more.`;
-  if (!originalSystemPrompt) return base;
-  return `${base}\n\nFor context, the agent is operating under this system prompt:\n<agent_system_prompt>\n${originalSystemPrompt}\n</agent_system_prompt>`;
+  let prompt = base;
+  if (originalSystemPrompt) {
+    prompt += `\n\nFor context, the agent is operating under this system prompt:\n<agent_system_prompt>\n${originalSystemPrompt}\n</agent_system_prompt>`;
+  }
+  if (runtimeContext) {
+    prompt += `\n\nThe agent's runtime context — the tools and skills available to it, the loaded workspace/project context, and relevant memory — follows. Ground your recommendations in what the agent can actually do and what is around it; reference specific tools, skills, files, or memory where relevant.\n<agent_runtime_context>\n${runtimeContext}\n</agent_runtime_context>`;
+  }
+  return prompt;
 }
 
 /**