@vellumai/assistant 0.10.3 → 0.10.4-staging.1

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

@@ -1,288 +0,0 @@
-/**
- * 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/hooks/post-model-call.ts

@@ -1,34 +0,0 @@
-/**
- * `post-model-call` hook: snapshot the transcript the executor just saw. Fires
- * after the model returns its message (which may carry the `advisor` tool_use)
- * but before tools run, so when `advisor.execute()` runs an instant later it
- * reads exactly this snapshot.
- *
- * Pure observer: never mutates `content` or the continue/stop `decision`. Gated
- * to the user-facing reply, so background/subagent/compaction calls — and the
- * advisor's own `inference`-call-site sub-call — are ignored.
- */
-
-import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
-
-import { recordMessages } from "../advisor-state-store.js";
-
-const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
-  if (ctx.callSite !== "mainAgent") return;
-  if (ctx.error) return;
-  // `ctx.messages` is the pre-reply history; the turn the model just produced —
-  // including any text/plan it wrote before the `advisor` tool_use — lives in
-  // `ctx.content` and is not yet in `messages`. Append it (cloned) so the
-  // advisor reviews the full current transcript, not just the prior history.
-  // `transcript.ts` strips the pending tool_use from this final assistant turn.
-  const messages =
-    ctx.content.length > 0
-      ? [
-          ...ctx.messages,
-          { role: "assistant" as const, content: [...ctx.content] },
-        ]
-      : ctx.messages;
-  recordMessages(ctx.conversationId, messages);
-};
-
-export default postModelCall;

package/src/plugins/defaults/advisor/hooks/pre-model-call.ts

@@ -1,30 +0,0 @@
-/**
- * `pre-model-call` hook: for the user-facing reply (`mainAgent`), capture the
- * executor's system prompt (steering stripped) so the advisor can be given it
- * as context, and inject the advisor steering so the model reaches for the
- * tool. Idempotent via the steering marker.
- */
-
-import type { HookFunction, PreModelCallContext } from "@vellumai/plugin-api";
-
-import { advisorEnabledForProfile } from "../advisor-gate.js";
-import { recordSystemPrompt } from "../advisor-state-store.js";
-import { ADVISOR_CONFIG } from "../config.js";
-import { appendSteering, stripSteering } from "../steering.js";
-
-const preModelCall: HookFunction<PreModelCallContext> = async (ctx) => {
-  if (ctx.callSite !== "mainAgent") return;
-
-  recordSystemPrompt(ctx.conversationId, stripSteering(ctx.systemPrompt));
-
-  // Steer the model to consult only when the steering is globally on AND the
-  // chat profile this turn routes to has the advisor enabled (default on).
-  if (
-    ADVISOR_CONFIG.steeringEnabled &&
-    advisorEnabledForProfile(ctx.modelProfile)
-  ) {
-    ctx.systemPrompt = appendSteering(ctx.systemPrompt);
-  }
-};
-
-export default preModelCall;

package/src/plugins/defaults/advisor/hooks/user-prompt-submit.ts

@@ -1,19 +0,0 @@
-/**
- * `user-prompt-submit` hook: seed the per-conversation capture at the start of a
- * user turn with the inbound history, so an advisor call on the very first model
- * turn still has context even before `post-model-call` snapshots the running
- * transcript.
- */
-
-import type {
-  HookFunction,
-  UserPromptSubmitContext,
-} from "@vellumai/plugin-api";
-
-import { seedCapture } from "../advisor-state-store.js";
-
-const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
-  seedCapture(ctx.conversationId, ctx.latestMessages);
-};
-
-export default userPromptSubmit;

package/src/plugins/defaults/advisor/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "default-advisor",
-  "version": "1.0.0",
-  "description": "First-party default plugin that adds an `advisor` tool: a no-argument tool the model calls mid-task to consult a stronger inference profile on the full conversation transcript for strategic guidance, routed through the assistant's own inference.",
-  "private": true,
-  "license": "MIT",
-  "type": "module",
-  "engines": {
-    "node": ">=20.12.0"
-  },
-  "peerDependencies": {
-    "@vellumai/plugin-api": "^0.8.0"
-  }
-}

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

@@ -1,92 +0,0 @@
-/**
- * The `advisor` tool — a no-argument tool the model calls to consult a stronger
- * model for strategic guidance. The model supplies no input; the plugin reads
- * the transcript captured by the lifecycle hooks and runs the consult, routed
- * through the assistant's own inference.
- *
- * Default export = the tool definition. `defaults/index.ts` finalizes it and
- * attaches it to the advisor plugin's `tools` array, which `bootstrapPlugins`
- * registers into the model-visible tool catalog.
- */
-
-import type {
-  ToolContext,
-  ToolDefinition,
-  ToolExecutionResult,
-} from "@vellumai/plugin-api";
-import { RiskLevel } from "@vellumai/plugin-api";
-
-import { advisorEnabledForProfile } from "../advisor-gate.js";
-import { getCapture } from "../advisor-state-store.js";
-import { consultAdvisor } from "../consult.js";
-import { buildAdvisorContext } from "../context-pack.js";
-
-const advisorTool: ToolDefinition = {
-  name: "advisor",
-  description:
-    "Consult a stronger advisor model to shape your plan and get strategic guidance. " +
-    "Takes NO parameters — your full conversation (the task, every tool call, and every " +
-    "result) is forwarded automatically, along with your available tools and skills, the " +
-    "workspace/project context, and relevant memory. Call it BEFORE you start building: it " +
-    "can lay out a plan when you don't have one yet, or review and sharpen the plan you've " +
-    "already drafted. Also call it when you're stuck, when weighing a change in approach, and " +
-    "once before declaring a task complete. It runs on its own — if you call it alongside " +
-    "other tools, those are held back until you've seen its guidance. Give its guidance " +
-    "serious weight.",
-  input_schema: { type: "object", properties: {}, additionalProperties: false },
-  // Read-only advice; low risk so the consult isn't gated behind a prompt.
-  defaultRiskLevel: RiskLevel.Low,
-  // Runs alone in its turn: the loop defers any sibling tool calls so the model
-  // incorporates the advisor's guidance before acting on anything else.
-  exclusive: true,
-  async execute(
-    _input: Record<string, unknown>,
-    ctx: ToolContext,
-  ): Promise<ToolExecutionResult> {
-    // Defense-in-depth: the steering is already gated per profile, but a model
-    // could still call the tool. Honor the chat profile this turn runs under —
-    // the per-turn override (per-conversation / profile-session) when present,
-    // else the workspace active profile.
-    if (!advisorEnabledForProfile(ctx.overrideProfile ?? null)) {
-      return {
-        content: "(advisor is disabled for the active profile)",
-        isError: false,
-      };
-    }
-    try {
-      const capture = getCapture(ctx.conversationId);
-      const messages = capture?.messages ?? [];
-      // Gather the agent's situational context (tools, skills, workspace,
-      // memory) so the advisor reasons with the same awareness the agent has.
-      // Best-effort: a failure here must not block the consult.
-      const runtimeContext = await buildAdvisorContext({
-        conversationId: ctx.conversationId,
-        workingDir: ctx.workingDir,
-        allowedToolNames: ctx.allowedToolNames,
-        // Per-turn trust snapshot — gates personal-memory surfaces off the same
-        // values the executor captured for this invocation, not live state.
-        trustClass: ctx.trustClass,
-        sourceChannel: ctx.executionChannel,
-        transcript: messages,
-        signal: ctx.signal,
-      }).catch(() => null);
-      const advice = await consultAdvisor({
-        systemPrompt: capture?.systemPrompt ?? null,
-        messages,
-        runtimeContext,
-        signal: ctx.signal,
-        // Stream the advisor's guidance live as it generates: each delta is
-        // surfaced as a `tool_output_chunk` for this tool call and rendered in
-        // the tool-detail drawer. The complete text is still returned below.
-        onText: (chunk) => ctx.onOutput?.(chunk),
-      });
-      return { content: advice, isError: false };
-    } catch (err) {
-      // Degrade like the advisor tool: never fail the turn over a consult.
-      const reason = err instanceof Error ? err.message : String(err);
-      return { content: `(advisor unavailable: ${reason})`, isError: false };
-    }
-  },
-};
-
-export default advisorTool;