@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/plugins/defaults/surface-completion-nudge/hooks/post-model-call.ts

@@ -0,0 +1,276 @@
+/**
+ * Default `post-model-call` hook: when a user-facing turn is about to end with a
+ * progress surface the model showed but never closed, nudge the model — once
+ * per run — to complete or dismiss it, then re-query so it can act.
+ *
+ * Motivation: the model can call `ui_show` with a `task_progress` card (or a
+ * `work_result` in an `in_progress` state) to show live progress, but weaker
+ * models often never advance it to a terminal status or `ui_dismiss` it. The
+ * surface then renders a spinner forever, long after the work finished. Static
+ * prompt guidance is easy to ignore; a reminder injected at the moment the turn
+ * would otherwise end — with a concrete "you left this open" signal — is far
+ * more salient.
+ *
+ * The nudge is strictly best-effort and self-targeting:
+ * - It fires at most once per run (no looping if the model declines).
+ * - It is advisory — the model may leave the surface open if the work it
+ *   represents is genuinely still running.
+ * - A model that already completed or dismissed its surfaces is never nudged,
+ *   so capable models that close their surfaces pay nothing.
+ *
+ * Only a finalized, no-tool, main-agent reply is actionable:
+ * - A provider rejection carries no turn content to assess (a recovery hook
+ *   like history-repair owns that).
+ * - A tool-bearing turn continues naturally — the loop runs the tools and the
+ *   model gets another chance to close the surface — so we leave it alone.
+ * - Background call sites (wake, title-gen, memory) have no live user watching
+ *   a spinner, so the nudge would only burn a model round.
+ *
+ * No subagent guard is needed: the `ui-surface` tools are gated on a connected
+ * client (see `conversation-tool-setup.ts`), and subagents have none — so a
+ * subagent can never create a surface and so can never trigger this hook.
+ *
+ * The dangling-surface signal is derived from the current response cycle (the
+ * messages after the last genuine user prompt) by correlating each progress
+ * `ui_show` with its `surface_id` result and folding in later `ui_update` /
+ * `ui_dismiss` calls. Deriving the cycle boundary from history content rather
+ * than an index means mid-run compaction (which rewrites the array in place)
+ * can't invalidate it.
+ *
+ * The one-shot bound is split across two hooks: this hook marks the
+ * conversation when it nudges, and the sibling `stop` hook clears the mark when
+ * the turn terminates, so the next run nudges afresh.
+ *
+ * Defaults register before any user plugin, so this hook runs at the front of
+ * the `post-model-call` chain — later hooks see (and may override) its decision.
+ */
+
+import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+
+import type { ContentBlock, Message } from "../../../../providers/types.js";
+import {
+  isSurfaceCompletionNudged,
+  markSurfaceCompletionNudged,
+} from "../nudge-state-store.js";
+
+/**
+ * Canonical nudge text. Shown to the model as provider-only context, never to
+ * the user. Kept verbatim so a plugin that wraps the default sees a stable
+ * string. Deliberately soft: the model may leave the surface open if the work
+ * is genuinely still running.
+ */
+export const SURFACE_COMPLETION_NUDGE_TEXT =
+  '<system_notice>You showed the user a progress surface this turn (a task_progress card or a work_result) and are about to end the turn with it still marked in_progress. If that work is finished, advance it to a terminal state now — call ui_update to set its status to "completed" (or "failed"), or ui_dismiss it — so the user is not left watching a card spin forever. Do this only if the work it represents is actually done; if it is genuinely still running, leave it. Then give your final reply.</system_notice>';
+
+/**
+ * Surface statuses that mean the progress surface has reached a terminal state
+ * and needs no completion nudge. Covers both `task_progress`
+ * (`completed`/`failed`) and `work_result` (`completed`/`partial`/`failed`),
+ * plus `cancelled` for tolerance.
+ */
+const TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "partial",
+  "cancelled",
+]);
+
+function hasToolUse(content: ReadonlyArray<ContentBlock>): boolean {
+  return content.some((block) => block.type === "tool_use");
+}
+
+/** A user-role message carrying only tool results, not a fresh prompt. */
+function isToolResultMessage(message: Message): boolean {
+  return (
+    message.role === "user" &&
+    message.content.length > 0 &&
+    message.content.every((block) => block.type === "tool_result")
+  );
+}
+
+/**
+ * Messages belonging to the current response cycle: everything after the last
+ * genuine user prompt. Falls back to the whole history when none is found.
+ */
+function currentCycleMessages(
+  messages: ReadonlyArray<Message>,
+): ReadonlyArray<Message> {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role === "user" && !isToolResultMessage(message)) {
+      return messages.slice(i + 1);
+    }
+  }
+  return messages;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * Pull a surface status out of a `ui_show` / `ui_update` input, tolerating the
+ * shapes the server-side normalization accepts: nested under
+ * `data.templateData` (task_progress), under `data` (work_result), or at the
+ * top level. Returns a lowercased status, or `undefined` when none is present.
+ */
+function extractStatus(input: Record<string, unknown>): string | undefined {
+  const data = asRecord(input.data);
+  const templateData =
+    asRecord(data?.templateData) ?? asRecord(input.templateData);
+  const raw = templateData?.status ?? data?.status ?? input.status;
+  return typeof raw === "string" ? raw.trim().toLowerCase() : undefined;
+}
+
+/**
+ * Whether a `ui_show` input describes a surface with a progress lifecycle: a
+ * `task_progress` card or a `work_result`. Returns the initial status when so.
+ */
+function progressShowInfo(input: Record<string, unknown>): {
+  isProgress: boolean;
+  status: string | undefined;
+} {
+  const surfaceType = input.surface_type;
+  if (surfaceType === "work_result") {
+    return { isProgress: true, status: extractStatus(input) };
+  }
+  if (surfaceType === "card") {
+    const data = asRecord(input.data);
+    const template = data?.template ?? input.template;
+    if (template === "task_progress") {
+      return { isProgress: true, status: extractStatus(input) };
+    }
+  }
+  return { isProgress: false, status: undefined };
+}
+
+function surfaceIdOf(input: Record<string, unknown>): string | undefined {
+  return typeof input.surface_id === "string" ? input.surface_id : undefined;
+}
+
+/** Parse the `{ surfaceId }` JSON a successful `ui_show` returns. */
+function parseSurfaceId(content: string): string | undefined {
+  try {
+    const parsed = JSON.parse(content) as unknown;
+    const record = asRecord(parsed);
+    return typeof record?.surfaceId === "string" ? record.surfaceId : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+interface SurfaceState {
+  /** Latest known status, lowercased; `undefined` when never set explicitly. */
+  status: string | undefined;
+  dismissed: boolean;
+}
+
+function isNonTerminal(state: SurfaceState): boolean {
+  if (state.dismissed) return false;
+  return state.status === undefined || !TERMINAL_STATUSES.has(state.status);
+}
+
+/**
+ * True when the current response cycle left at least one progress surface
+ * (a `task_progress` card or `work_result`) open: shown but neither advanced to
+ * a terminal status nor dismissed.
+ *
+ * Each progress `ui_show` is correlated to its `surface_id` via the matching
+ * tool result (the result lands in the next message; updates and dismisses
+ * arrive in later messages, after the model has the id in hand). Later
+ * `ui_update` / `ui_dismiss` calls fold their status / dismissal onto the
+ * tracked surface.
+ */
+function hasDanglingProgressSurface(messages: ReadonlyArray<Message>): boolean {
+  const surfaces = new Map<string, SurfaceState>();
+  // tool_use_id -> initial status of a progress ui_show awaiting its result id.
+  const pendingShows = new Map<string, string | undefined>();
+
+  for (const message of currentCycleMessages(messages)) {
+    if (message.role === "assistant") {
+      for (const block of message.content) {
+        if (block.type !== "tool_use") continue;
+        if (block.name === "ui_show") {
+          const info = progressShowInfo(block.input);
+          if (info.isProgress) pendingShows.set(block.id, info.status);
+        } else if (block.name === "ui_update") {
+          const id = surfaceIdOf(block.input);
+          const status = extractStatus(block.input);
+          if (id && status !== undefined) {
+            const existing = surfaces.get(id);
+            if (existing) existing.status = status;
+            else surfaces.set(id, { status, dismissed: false });
+          }
+        } else if (block.name === "ui_dismiss") {
+          const id = surfaceIdOf(block.input);
+          if (id) {
+            const existing = surfaces.get(id);
+            if (existing) existing.dismissed = true;
+            else surfaces.set(id, { status: undefined, dismissed: true });
+          }
+        }
+      }
+      continue;
+    }
+    if (message.role !== "user") continue;
+    for (const block of message.content) {
+      // guard:allow-tool-result-only — only the local tool executor's
+      // `tool_result` carries a `ui_show` `surfaceId` to correlate. A
+      // `web_search_tool_result` comes from a `server_tool_use`, never a
+      // `ui_show`, so it can never match a pending show and is correctly skipped.
+      if (block.type !== "tool_result") continue;
+      if (!pendingShows.has(block.tool_use_id)) continue;
+      const initialStatus = pendingShows.get(block.tool_use_id);
+      pendingShows.delete(block.tool_use_id);
+      const id = parseSurfaceId(block.content);
+      if (!id) continue;
+      const existing = surfaces.get(id);
+      // A later update/dismiss can register the id before its show result is
+      // scanned only if history was reordered; guard so we never clobber a
+      // known terminal/dismissed state with the initial status.
+      if (existing) {
+        if (existing.status === undefined && !existing.dismissed) {
+          existing.status = initialStatus;
+        }
+      } else {
+        surfaces.set(id, { status: initialStatus, dismissed: false });
+      }
+    }
+  }
+
+  for (const state of surfaces.values()) {
+    if (isNonTerminal(state)) return true;
+  }
+  return false;
+}
+
+const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+  // A provider rejection carries no turn content to assess (a recovery hook
+  // owns the rejection).
+  if (ctx.error) return;
+  // A tool-bearing turn continues mid-run — the loop runs the tools and the
+  // model gets another chance to close the surface — so leave it alone.
+  if (hasToolUse(ctx.content)) return;
+  // Only nudge the user-facing reply: background call sites have no live user
+  // watching a spinner.
+  if (ctx.callSite !== "mainAgent") return;
+  // One nudge per run; the sibling `stop` hook clears the mark on terminal stop.
+  if (isSurfaceCompletionNudged(ctx.conversationId)) return;
+
+  if (!hasDanglingProgressSurface(ctx.messages)) return;
+
+  markSurfaceCompletionNudged(ctx.conversationId);
+  ctx.messages.push({
+    role: "user",
+    content: [{ type: "text", text: SURFACE_COMPLETION_NUDGE_TEXT }],
+  });
+  ctx.decision = "continue";
+  ctx.logger.info(
+    { plugin: "surface-completion-nudge", conversationId: ctx.conversationId },
+    "Turn ending with an open progress surface — nudging the model to complete or dismiss it",
+  );
+};
+
+export default postModelCall;

package/src/plugins/defaults/surface-completion-nudge/hooks/stop.ts

@@ -0,0 +1,22 @@
+/**
+ * Default `stop` hook: clears the per-conversation surface-completion nudge
+ * bound when a turn terminates.
+ *
+ * The `post-model-call` hook (see `./post-model-call.ts`) marks the bound when
+ * it nudges the model to close a dangling progress surface. `stop` is the
+ * definitive terminal hook — it fires exactly once when the turn is truly
+ * ending, after every retry decision has been made — so clearing the bound here
+ * unconditionally guarantees the next run nudges afresh, no matter how the turn
+ * ended (a finalized reply, an abort, or a retry the loop's per-run backstop
+ * refused).
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import { clearSurfaceCompletionNudged } from "../nudge-state-store.js";
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  clearSurfaceCompletionNudged(ctx.conversationId);
+};
+
+export default stop;

package/src/plugins/defaults/surface-completion-nudge/nudge-state-store.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-conversation surface-completion nudge state.
+ *
+ * The `post-model-call` hook nudges the model — once per run — to complete or
+ * dismiss a progress surface it left `in_progress` when the turn was about to
+ * end, asking the loop to re-query so the model can act on it. That nudge is
+ * bounded to one pass per run: if the model declines or fails to close the
+ * surface, the hook lets the turn end rather than looping on it.
+ *
+ * The two hooks split this state's lifecycle: `post-model-call` marks a
+ * conversation when it issues the nudge, and the sibling `stop` hook clears the
+ * mark when the turn terminates. A conversation therefore only holds an entry
+ * while a nudge is in flight, and the next run nudges afresh.
+ *
+ * This module is side-effect free: importing it only initializes an empty store
+ * and registers no plugin.
+ */
+
+/** Conversations with a surface-completion nudge in flight for the current run. */
+const nudgeInFlight = new Set<string>();
+
+/** Whether the conversation already issued its one nudge this run. */
+export function isSurfaceCompletionNudged(conversationId: string): boolean {
+  return nudgeInFlight.has(conversationId);
+}
+
+/** Record that the conversation issued its one nudge this run. */
+export function markSurfaceCompletionNudged(conversationId: string): void {
+  nudgeInFlight.add(conversationId);
+}
+
+/**
+ * Clear the conversation's nudge mark so the next run nudges afresh. The
+ * sibling `stop` hook calls this when the turn terminates.
+ */
+export function clearSurfaceCompletionNudged(conversationId: string): void {
+  nudgeInFlight.delete(conversationId);
+}
+
+/**
+ * Test-only: drop every conversation's nudge state so a suite that drives the
+ * hook directly starts each case from an empty store.
+ */
+export function resetSurfaceCompletionNudgeStoreForTests(): void {
+  nudgeInFlight.clear();
+}

package/src/plugins/defaults/surface-completion-nudge/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "default-surface-completion-nudge",
+  "version": "1.0.0",
+  "description": "First-party default plugin that nudges the model to complete or dismiss a progress surface it left in_progress when the turn ends.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/task-progress-nudge/hooks/post-tool-use.ts

@@ -48,6 +48,7 @@
 import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
 
 import type { ContentBlock, Message } from "../../../../providers/types.js";
+import { isWeakOpenModel } from "../../../../providers/weak-open-model.js";
 
 /**
  * Canonical nudge notice. Module-level constant so tests and wrapping plugins
@@ -56,7 +57,7 @@ import type { ContentBlock, Message } from "../../../../providers/types.js";
  * are fine and the model may skip it when wrapping up.
  */
 export const TASK_PROGRESS_NUDGE_TEXT =
-  '<system_notice>You are several tool calls into this turn and have not shown the user a progress card. If you are doing multi-step work, call ui_show now with surface_type "card" and template "task_progress" (coarse steps are fine — a rough "Working on X" beats no signal) so the user can see what is happening, and keep it updated with ui_update as you go. Skip this if you are about to finish; never let it interrupt the actual work.</system_notice>';
+  '<system_notice>You are several tool calls into this turn with no progress card shown. A card is optional, not required: if the turn is wrapping up, is not really multi-step, or you cannot form clean steps, skip it and keep working — a one-line note of what you are doing is a fine substitute, and proceeding with no card is also fine. Only if a live step tracker would genuinely help the user, show it with a SINGLE self-contained ui_show call that already contains the steps: ui_show({ surface_type: "card", data: { template: "task_progress", templateData: { title: "<what you are doing>", status: "in_progress", steps: [{ label: "<step 1>", status: "in_progress" }, { label: "<step 2>", status: "pending" }] } } }). Coarse steps are fine. Do not call ui_show with an empty `data: {}` and fill it in afterward — an empty card renders as a blank box; either include the steps now or skip the card. Advance it later with ui_update under `data.templateData`. Never let the card interrupt the actual work; if one ever looks wrong, just dismiss it and move on. You will not be nudged about this again this turn.</system_notice>';
 
 /**
  * Number of tool-use rounds in a turn, with no task_progress card shown, that
@@ -66,17 +67,6 @@ export const TASK_PROGRESS_NUDGE_TEXT =
  */
 export const TASK_PROGRESS_NUDGE_ROUND_THRESHOLD = 3;
 
-/**
- * Weaker open models that disregard the static progress-card instruction and
- * so get the mid-turn nudge: Kimi, DeepSeek, and MiniMax. Family-level matching
- * spans provider naming conventions (OpenRouter `moonshotai/kimi-k2.6`,
- * `deepseek/deepseek-chat`, `minimax/minimax-m3`; Fireworks
- * `accounts/fireworks/models/minimax-m3`, `kimi-k2p6`). Extend as other models
- * show the same gap. Capable models (Claude, GPT) follow the prompt and are
- * intentionally excluded.
- */
-const WEAK_MODEL_PATTERN = /kimi|deepseek|minimax/i;
-
 /**
  * Round count at the last nudge, per conversation. A non-zero entry means the
  * turn has already been nudged; it resets when the round count drops below the
@@ -145,7 +135,7 @@ function scanTurn(messages: ReadonlyArray<Message>): {
 }
 
 const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
-  if (!WEAK_MODEL_PATTERN.test(ctx.model)) return;
+  if (!isWeakOpenModel(ctx.model)) return;
 
   const { rounds, taskProgressShown } = scanTurn(ctx.messages);
 

package/src/plugins/defaults/title-generate/hooks/stop.ts

@@ -1,16 +1,16 @@
 /**
- * Default `stop` hook: triggers the second-pass conversation-title
- * regeneration once a conversation has accumulated enough context.
+ * Default `stop` hook: triggers conversation-title retry/regeneration once a
+ * conversation has accumulated useful context.
  *
  * The first title is generated from the opening prompt alone (see
  * `./user-prompt-submit.ts`). After a few exchanges the conversation's real
  * topic is usually clearer, so a single second pass re-titles using the most
- * recent messages. This hook is the trigger — it fires the regeneration when
- * the conversation reaches its third user turn — and delegates the title
- * itself to the service (`memory/conversation-title-service.ts`), which
- * re-checks that the title is still auto-generated, resolves the title
- * provider, persists, and broadcasts the `conversation_title_updated` /
- * `sync_changed` events.
+ * recent messages. This hook is the trigger — it retries placeholder titles
+ * after successful turns and fires the second-pass regeneration when the
+ * conversation reaches its third user turn. The service
+ * (`memory/conversation-title-service.ts`) re-checks that the title is still
+ * auto-generated, resolves the title provider, persists, and broadcasts the
+ * `conversation_title_updated` / `sync_changed` events.
  *
  * Turn count is read from history rather than an external counter: the number
  * of genuine user prompts — user-role messages that aren't purely tool results
@@ -22,7 +22,11 @@ import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
 
 import { getConfig } from "../../../../config/loader.js";
 import { getConversation } from "../../../../memory/conversation-crud.js";
-import { queueRegenerateConversationTitle } from "../../../../memory/conversation-title-service.js";
+import {
+  AUTO_TITLE_DETERMINISTIC,
+  isReplaceableTitle,
+  queueRegenerateConversationTitle,
+} from "../../../../memory/conversation-title-service.js";
 import type { Message } from "../../../../providers/types.js";
 
 /**
@@ -50,37 +54,68 @@ function countUserTurns(messages: ReadonlyArray<Message>): number {
   return turns;
 }
 
+function shouldRetryFallbackTitle(conversation: {
+  title: string | null;
+  isAutoTitle: number;
+}): boolean {
+  if (!conversation.isAutoTitle) return false;
+  return (
+    isReplaceableTitle(conversation.title) ||
+    conversation.isAutoTitle === AUTO_TITLE_DETERMINISTIC
+  );
+}
+
 const stop: PluginHookFn<StopContext> = async (ctx) => {
   // Re-title only at a genuine successful turn end (the model returned a reply
   // with no tool calls). Any other terminal — a provider rejection, abort, or
   // an output-limit cutoff — produced no new topic to re-title from.
   if (ctx.exitReason !== "no_tool_calls") return;
 
-  if (getConfig().conversations.skipAutoRetitling) return;
-
-  if (countUserTurns(ctx.messages) !== SECOND_PASS_USER_TURN) return;
+  const userTurns = countUserTurns(ctx.messages);
+  if (userTurns === 0) return;
 
   // System conversations (background/scheduled) keep their deterministic
   // bootstrap title — multi-prompt background jobs can reach three user-role
   // turns with no human present, and a refined LLM title isn't worth the
   // tokens there. The lookup fails open: on a read error the hook behaves as
   // before (queues regeneration; the service re-checks isAutoTitle).
+  let retryFallbackTitle = false;
   try {
     const conversation = getConversation(ctx.conversationId);
     if (conversation && conversation.conversationType !== "standard") return;
+    retryFallbackTitle = conversation
+      ? shouldRetryFallbackTitle(conversation)
+      : false;
   } catch {
     // Fall through to queueing.
   }
 
-  const { conversationId } = ctx;
-  // Deferred to a later macrotask so the just-completed turn's persistence
-  // settles first. The service regenerates from the most recent stored
-  // messages, so it must run after the reply is persisted to reflect it. The
-  // service is itself fire-and-forget and re-checks replaceability, owning
-  // provider resolution, persistence, and the resulting broadcast.
-  setTimeout(() => {
-    queueRegenerateConversationTitle({ conversationId });
-  }, 0);
+  if (
+    userTurns === SECOND_PASS_USER_TURN &&
+    !getConfig().conversations.skipAutoRetitling
+  ) {
+    const { conversationId } = ctx;
+    // Deferred to a later macrotask so the just-completed turn's persistence
+    // settles first. The service regenerates from the most recent stored
+    // messages, so it must run after the reply is persisted to reflect it. The
+    // service is itself fire-and-forget and re-checks replaceability, owning
+    // provider resolution, persistence, and the resulting broadcast.
+    setTimeout(() => {
+      queueRegenerateConversationTitle({ conversationId });
+    }, 0);
+    return;
+  }
+
+  if (retryFallbackTitle) {
+    const { conversationId } = ctx;
+    setTimeout(() => {
+      queueRegenerateConversationTitle({
+        conversationId,
+        onlyIfReplaceable: true,
+      });
+    }, 0);
+    return;
+  }
 };
 
 export default stop;

package/src/prompts/persona-resolver.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
 import {
-  findContactByChannelExternalId,
+  findContactByAddress,
   findGuardianForChannel,
   listGuardianChannels,
 } from "../contacts/contact-store.js";
@@ -88,7 +88,7 @@ function resolveUserFilename(
       }
     } else if (trustContext.requesterExternalUserId) {
       // Channel-routed request — look up contact by channel identity
-      const contactWithChannels = findContactByChannelExternalId(
+      const contactWithChannels = findContactByAddress(
         trustContext.sourceChannel,
         trustContext.requesterExternalUserId,
       );
@@ -96,13 +96,23 @@ function resolveUserFilename(
         filename = contactWithChannels.userFile ?? null;
       } else if (trustContext.trustClass === "guardian") {
         // Managed desktop: the JWT principal ID used as requesterExternalUserId
-        // may differ from the contact channel's external_user_id (they are
-        // separate identity concepts). Fall back to the channel-type guardian.
+        // may differ from the contact channel's address (they are separate
+        // identity concepts). Fall back to the channel-type guardian.
         const guardian = findGuardianForChannel(trustContext.sourceChannel);
         if (guardian) {
           filename = guardian.contact.userFile ?? "guardian.md";
         }
       }
+    } else if (trustContext.trustClass === "guardian") {
+      // Guardian-trust turn carrying no requester identity — background and
+      // scheduled turns (heartbeat, scheduled pulses) run under the guardian
+      // trust class but have no per-actor address to look up. Resolve the
+      // channel's guardian user file so they load the same persona as a
+      // foreground guardian turn instead of falling back to users/default.md.
+      const guardian = findGuardianForChannel(trustContext.sourceChannel);
+      if (guardian) {
+        filename = guardian.contact.userFile ?? "guardian.md";
+      }
     }
   } catch (err) {
     // Contacts table may be absent — happens during early bootstrap

package/src/prompts/templates/system-sections.ts

@@ -259,6 +259,13 @@ Meet your user where they are. If they are nontechnical, prefer "Gmail needs rec
 Err toward brevity; expand only when the user follows up or their style calls for more.
 
 These are default guidelines. Always prioritize communication preferences that you've established through your relationship with your human.
+`,
+  },
+  {
+    id: "01-delegate-subagents",
+    body: `## Delegate independent work
+
+When part of a task can run on its own — a research sweep, a multi-file investigation, a build-and-test loop — hand it off instead of grinding through it inline: load the \`subagent\` skill, then \`subagent_spawn\` early and in parallel. Make delegating that kind of work your default, not a last resort; an unnecessary subagent is cheaper than serialized work, and a long inline dig floods your own context.
 `,
   },
   {
@@ -267,8 +274,6 @@ These are default guidelines. Always prioritize communication preferences that y
 Batch independent tool calls into the same response. An extra LLM round trip costs orders of magnitude more than a few wasted tool calls — err on the side of parallelizing when calls are independent. Reading multiple files, \`glob\`/\`grep\`, \`ls\`, \`git status\`/\`diff\`/\`log\`, type-checks, and tests should be batched.
 
 Before emitting a single tool call, ask whether your next turn would be another tool call that doesn't consume this one's output — if so, they belong together. Serialized tool calls without a real data dependency are a bug.
-
-For non-trivial independent workstreams — research, coding, multi-step investigations — delegate to subagents (load the \`subagent\` skill) and spawn them early and in parallel; an unnecessary subagent is cheaper than serialized work.
 </use_parallel_tool_calls>
 `,
   },

package/src/providers/__tests__/provider-env-vars.test.ts

@@ -35,6 +35,7 @@ describe("getLlmProviderEnvVar", () => {
     expect(getLlmProviderEnvVar("brave")).toBeUndefined();
     expect(getLlmProviderEnvVar("perplexity")).toBeUndefined();
     expect(getLlmProviderEnvVar("tavily")).toBeUndefined();
+    expect(getLlmProviderEnvVar("firecrawl")).toBeUndefined();
   });
 
   test("returns undefined for unknown provider", () => {
@@ -55,6 +56,10 @@ describe("getSearchProviderEnvVar", () => {
     expect(getSearchProviderEnvVar("tavily")).toBe("TAVILY_API_KEY");
   });
 
+  test("returns FIRECRAWL_API_KEY for firecrawl", () => {
+    expect(getSearchProviderEnvVar("firecrawl")).toBe("FIRECRAWL_API_KEY");
+  });
+
   test("returns undefined for LLM providers (out of scope)", () => {
     expect(getSearchProviderEnvVar("anthropic")).toBeUndefined();
     expect(getSearchProviderEnvVar("openai")).toBeUndefined();
@@ -75,6 +80,7 @@ describe("getAnyProviderEnvVar", () => {
     expect(getAnyProviderEnvVar("brave")).toBe("BRAVE_API_KEY");
     expect(getAnyProviderEnvVar("perplexity")).toBe("PERPLEXITY_API_KEY");
     expect(getAnyProviderEnvVar("tavily")).toBe("TAVILY_API_KEY");
+    expect(getAnyProviderEnvVar("firecrawl")).toBe("FIRECRAWL_API_KEY");
   });
 
   test("returns undefined for ollama (keyless LLM provider)", () => {

package/src/providers/__tests__/provider-secret-catalog.test.ts

@@ -44,5 +44,6 @@ describe("API_KEY_PROVIDERS", () => {
     expect(API_KEY_PROVIDERS).toContain("brave");
     expect(API_KEY_PROVIDERS).toContain("perplexity");
     expect(API_KEY_PROVIDERS).toContain("tavily");
+    expect(API_KEY_PROVIDERS).toContain("firecrawl");
   });
 });