@vellumai/assistant 0.9.1-staging.1 → 0.10.0-staging.2

package/src/runtime/routes/tool-call-question-enrichment.ts

@@ -0,0 +1,66 @@
+/**
+ * Render-time enrichment of history tool calls with in-flight question context.
+ *
+ * `pendingQuestion` — the outstanding `ask_question` prompt for a tool call
+ * still awaiting a user answer — is read from the in-memory
+ * `pending-interactions` registry (the authoritative store of unresolved
+ * prompts) and stamped onto its tool call so the web/API clients can restore
+ * the same question card on a cold reconnect (or a history reopen after the
+ * live event buffer has aged out) that the live `question_request` SSE stream
+ * would have produced. It appears only while the prompt is genuinely
+ * outstanding. Mirrors the confirmation enrichment in
+ * `tool-call-confirmation-enrichment.ts`.
+ */
+
+import type { QuestionEntry } from "../../api/events/question-request.js";
+import type { ConversationMessageToolCall } from "../../api/responses/conversation-message.js";
+import { getByConversation } from "../pending-interactions.js";
+
+/** A pending question matched to the tool call it prompts for, keyed by `toolUseId`. */
+interface PendingQuestionMatch {
+  requestId: string;
+  entries: QuestionEntry[];
+}
+
+/**
+ * Build the `toolUseId → pending question` lookup for a conversation from the
+ * registry. Only question interactions that carry both a `toolUseId` and
+ * `questionDetails` can be stamped onto a wire tool call.
+ */
+export function collectPendingQuestions(
+  conversationId: string,
+): Map<string, PendingQuestionMatch> {
+  const byToolUseId = new Map<string, PendingQuestionMatch>();
+  for (const interaction of getByConversation(conversationId)) {
+    if (
+      interaction.kind === "question" &&
+      interaction.questionDetails &&
+      interaction.toolUseId
+    ) {
+      byToolUseId.set(interaction.toolUseId, {
+        requestId: interaction.requestId,
+        entries: interaction.questionDetails.entries,
+      });
+    }
+  }
+  return byToolUseId;
+}
+
+/**
+ * Layer any outstanding `pendingQuestion` onto a message's rendered tool calls.
+ * Returns a new array; tool calls without a match are returned unchanged.
+ */
+export function enrichToolCallsWithQuestion(
+  toolCalls: ConversationMessageToolCall[],
+  opts: { pendingQuestions: ReadonlyMap<string, PendingQuestionMatch> },
+): ConversationMessageToolCall[] {
+  if (opts.pendingQuestions.size === 0) return toolCalls;
+  return toolCalls.map((tc) => {
+    const match = tc.id ? opts.pendingQuestions.get(tc.id) : undefined;
+    if (!match) return tc;
+    return {
+      ...tc,
+      pendingQuestion: { requestId: match.requestId, entries: match.entries },
+    };
+  });
+}

package/src/runtime/routes/workflow-routes.test.ts

@@ -1,6 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
-import type { WorkflowRun } from "../../workflows/journal-store.js";
+import type {
+  WorkflowJournalEntry,
+  WorkflowRun,
+} from "../../workflows/journal-store.js";
 import type { SavedWorkflowEntry } from "../../workflows/library.js";
 import {
   WorkflowResumeNotPossibleError,
@@ -58,6 +61,22 @@ interface FakeManager {
   resume: (id: string) => { runId: string };
 }
 
+function makeJournalEntry(
+  overrides: Partial<WorkflowJournalEntry> = {},
+): WorkflowJournalEntry {
+  return {
+    runId: "run-1",
+    seq: 0,
+    callHash: "call-0",
+    kind: "agent",
+    request: null,
+    result: null,
+    status: "completed",
+    createdAt: 1000,
+    ...overrides,
+  };
+}
+
 function setup(opts: {
   runs?: WorkflowRun[];
   saved?: SavedWorkflowEntry[];
@@ -65,6 +84,8 @@ function setup(opts: {
   resume?: (id: string) => { runId: string };
   /** Resolved auto-approve threshold for the resume posture gate. */
   threshold?: "none" | "low" | "medium" | "high";
+  /** Journal entries returned by getJournal, keyed by run id. */
+  journal?: Record<string, WorkflowJournalEntry[]>;
 }): {
   aborted: string[];
   resumed: string[];
@@ -97,6 +118,7 @@ function setup(opts: {
     getManager: () => manager,
     listWorkflows: () => opts.saved ?? [],
     getAutoApproveThreshold: async () => opts.threshold ?? "none",
+    getJournal: (runId) => opts.journal?.[runId] ?? [],
   });
   return { aborted, resumed, listCalls };
 }
@@ -303,6 +325,208 @@ describe("workflow routes (happy paths)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Journal projection
+// ---------------------------------------------------------------------------
+
+interface WireLeaf {
+  seq: number;
+  kind: string;
+  label?: string;
+  phase?: string;
+  promptSummary?: string;
+  status: string;
+  resultSummary?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  createdAt: number | null;
+}
+
+interface WireJournal {
+  runId: string;
+  status: string;
+  agentsSpawned: number;
+  inputTokens: number;
+  outputTokens: number;
+  leaves: WireLeaf[];
+}
+
+describe("getWorkflowRunJournal", () => {
+  test("projects agent leaves with label/phase/promptSummary/resultSummary extracted", async () => {
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            kind: "agent",
+            request: {
+              prompt: "Investigate the failing build",
+              opts: { label: "investigate", phase: "triage" },
+            },
+            result: { summary: "found the flaky test" },
+            status: "completed",
+            inputTokens: 120,
+            outputTokens: 45,
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    expect(result.runId).toBe("run-1");
+    expect(result.status).toBe("running");
+    expect(result.agentsSpawned).toBe(2);
+    expect(result.leaves.map((l) => l.seq)).toEqual([0]);
+
+    const first = result.leaves[0];
+    expect(first.kind).toBe("agent");
+    expect(first.label).toBe("investigate");
+    expect(first.phase).toBe("triage");
+    expect(first.promptSummary).toBe("Investigate the failing build");
+    expect(first.resultSummary).toContain("found the flaky test");
+    // Per-leaf token usage is projected onto the wire leaf.
+    expect(first.inputTokens).toBe(120);
+    expect(first.outputTokens).toBe(45);
+    // The bulky raw request/result payloads are dropped.
+    expect(first).not.toHaveProperty("request");
+    expect(first).not.toHaveProperty("result");
+  });
+
+  test("omits per-leaf token fields when the journal entry carries none", async () => {
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            kind: "agent",
+            request: { prompt: "no tokens recorded", opts: {} },
+            status: "completed",
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    const leaf = result.leaves[0];
+    expect(leaf).not.toHaveProperty("inputTokens");
+    expect(leaf).not.toHaveProperty("outputTokens");
+  });
+
+  test("excludes kind:workflow entries so the backfill matches the live agent-only stream", async () => {
+    // The live `workflow_leaf_*` stream is emitted only for agent leaves; nested
+    // `workflow(name)` resolutions never reach it. The journal route must filter
+    // to agent leaves too, or a nested-workflow run renders a phantom unlabeled
+    // node on backfill and a different leaf set than live.
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            kind: "agent",
+            request: { prompt: "first agent", opts: { label: "first" } },
+            status: "completed",
+          }),
+          makeJournalEntry({
+            seq: 1,
+            kind: "workflow",
+            request: { name: "child", args: { foo: 1 } },
+            result: "child done",
+            status: "completed",
+          }),
+          makeJournalEntry({
+            seq: 2,
+            kind: "agent",
+            request: { prompt: "second agent", opts: { label: "second" } },
+            status: "completed",
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    // Only the agent leaves survive, in seq order; the workflow-kind entry (seq
+    // 1) is dropped entirely.
+    expect(result.leaves.map((l) => l.seq)).toEqual([0, 2]);
+    expect(result.leaves.every((l) => l.kind === "agent")).toBe(true);
+    expect(result.leaves.map((l) => l.label)).toEqual(["first", "second"]);
+  });
+
+  test("surfaces a failed leaf's { error } result as resultSummary", async () => {
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            status: "failed",
+            request: { prompt: "do the thing", opts: {} },
+            result: { error: "agent crashed: out of tokens" },
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    expect(result.leaves[0].status).toBe("failed");
+    expect(result.leaves[0].resultSummary).toContain(
+      "agent crashed: out of tokens",
+    );
+  });
+
+  test("truncates a long prompt/result to ~200 chars", async () => {
+    const longPrompt = "x".repeat(500);
+    const longResult = "y".repeat(500);
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            request: { prompt: longPrompt, opts: {} },
+            result: longResult,
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    const leaf = result.leaves[0];
+    expect(leaf.promptSummary!.length).toBeLessThanOrEqual(201);
+    expect(leaf.promptSummary!.startsWith("x")).toBe(true);
+    // A truncated summary ends with the ellipsis marker.
+    expect(leaf.promptSummary!.endsWith("…")).toBe(true);
+    expect(leaf.resultSummary!.length).toBeLessThanOrEqual(201);
+  });
+
+  test("returns an empty leaf list for a run with no journal entries", async () => {
+    setup({ runs: [makeRun({ id: "run-1" })] });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+    expect(result.leaves).toEqual([]);
+  });
+
+  test("throws NotFoundError for an unknown id", () => {
+    setup({ runs: [] });
+    expect(() =>
+      route("getWorkflowRunJournal").handler({ pathParams: { id: "nope" } }),
+    ).toThrow(NotFoundError);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Unknown run → 404
 // ---------------------------------------------------------------------------

package/src/runtime/routes/workflow-routes.ts

@@ -12,7 +12,11 @@ import { z } from "zod";
 import { getAutoApproveThreshold } from "../../permissions/gateway-threshold-reader.js";
 import { isFullAccessThreshold } from "../../permissions/threshold.js";
 import { manifestGrantsSideEffects } from "../../workflows/capabilities.js";
-import type { WorkflowRun } from "../../workflows/journal-store.js";
+import {
+  getJournal,
+  type WorkflowJournalEntry,
+  type WorkflowRun,
+} from "../../workflows/journal-store.js";
 import { listWorkflows } from "../../workflows/library.js";
 import {
   getWorkflowRunManager,
@@ -40,6 +44,7 @@ export interface WorkflowRoutesDeps {
   >;
   listWorkflows: typeof listWorkflows;
   getAutoApproveThreshold: typeof getAutoApproveThreshold;
+  getJournal: typeof getJournal;
 }
 
 function defaultDeps(): WorkflowRoutesDeps {
@@ -47,6 +52,7 @@ function defaultDeps(): WorkflowRoutesDeps {
     getManager: getWorkflowRunManager,
     listWorkflows,
     getAutoApproveThreshold,
+    getJournal,
   };
 }
 
@@ -93,6 +99,29 @@ const savedWorkflowSchema = z.object({
   path: z.string(),
 });
 
+const workflowLeafSchema = z.object({
+  seq: z.number(),
+  kind: z.enum(["agent", "workflow"]),
+  label: z.string().optional(),
+  phase: z.string().optional(),
+  promptSummary: z.string().optional(),
+  status: z.string(),
+  resultSummary: z.string().optional(),
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  createdAt: z.number().nullable(),
+});
+
+const workflowJournalSchema = z.object({
+  runId: z.string(),
+  status: z.enum(VALID_RUN_STATUSES).optional(),
+  agentsSpawned: z.number().optional(),
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  phase: z.string().optional(),
+  leaves: z.array(workflowLeafSchema),
+});
+
 // ---------------------------------------------------------------------------
 // Handlers (transport-agnostic)
 // ---------------------------------------------------------------------------
@@ -122,6 +151,64 @@ export function toWireRun(run: WorkflowRun): WorkflowRunWire {
   };
 }
 
+/**
+ * Render an arbitrary journal value (prompt, result, `{ error }`) into a short
+ * single-string preview, truncating to `max` characters. Objects are
+ * JSON-stringified so a structured result still produces a readable summary.
+ */
+function summarize(value: unknown, max = 200): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  let text: string;
+  if (typeof value === "string") {
+    text = value;
+  } else {
+    try {
+      text = JSON.stringify(value);
+    } catch {
+      return undefined;
+    }
+  }
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/**
+ * Project a journal entry into the bounded leaf wire shape, dropping the bulky
+ * raw `request`/`result` payloads in favor of short summaries. The `request`
+ * and `result` columns are `unknown`, so read their fields defensively.
+ */
+export function toWireLeaf(
+  entry: WorkflowJournalEntry,
+): z.infer<typeof workflowLeafSchema> {
+  const request =
+    entry.request && typeof entry.request === "object"
+      ? (entry.request as Record<string, unknown>)
+      : undefined;
+  const opts =
+    request?.opts && typeof request.opts === "object"
+      ? (request.opts as Record<string, unknown>)
+      : undefined;
+  const label = typeof opts?.label === "string" ? opts.label : undefined;
+  const phase = typeof opts?.phase === "string" ? opts.phase : undefined;
+  const promptSummary = summarize(request?.prompt);
+  const resultSummary = summarize(entry.result);
+  return {
+    seq: entry.seq,
+    kind: entry.kind,
+    ...(label !== undefined ? { label } : {}),
+    ...(phase !== undefined ? { phase } : {}),
+    ...(promptSummary !== undefined ? { promptSummary } : {}),
+    status: entry.status,
+    ...(resultSummary !== undefined ? { resultSummary } : {}),
+    ...(entry.inputTokens !== undefined
+      ? { inputTokens: entry.inputTokens }
+      : {}),
+    ...(entry.outputTokens !== undefined
+      ? { outputTokens: entry.outputTokens }
+      : {}),
+    createdAt: entry.createdAt,
+  };
+}
+
 function parseLimit(raw: string | undefined): number | undefined {
   if (raw === undefined) return undefined;
   const n = Number(raw);
@@ -156,6 +243,28 @@ function handleGetRun(id: string) {
   return toWireRun(run);
 }
 
+function handleGetRunJournal(id: string) {
+  const run = deps.getManager().status(id);
+  if (!run) {
+    throw new NotFoundError(`Workflow run ${id} not found`);
+  }
+  return {
+    runId: run.id,
+    status: run.status,
+    agentsSpawned: run.agentsSpawned,
+    inputTokens: run.inputTokens,
+    outputTokens: run.outputTokens,
+    // Only agent leaves; the live `workflow_leaf_*` stream is emitted solely for
+    // agent leaves (nested workflow resolutions never reach it), so the
+    // backfilled set must match. `kind: "workflow"` entries carry no label and
+    // would render as phantom unlabeled nodes.
+    leaves: deps
+      .getJournal(id)
+      .filter((entry) => entry.kind === "agent")
+      .map(toWireLeaf),
+  };
+}
+
 function handleAbortRun(id: string) {
   // status() is the source of truth for existence; abort() itself is a no-op
   // for unknown/finished runs, so 404 on an unknown id is surfaced here.
@@ -271,6 +380,27 @@ export const ROUTES: RouteDefinition[] = [
     additionalResponses: { "404": { description: "Run not found" } },
     handler: ({ pathParams }: RouteHandlerArgs) => handleGetRun(pathParams!.id),
   },
+  {
+    operationId: "getWorkflowRunJournal",
+    endpoint: "workflows/runs/:id/journal",
+    method: "GET",
+    // Unlike the run list/status routes (settings metadata), the journal returns
+    // per-leaf prompt/result summaries — conversation/work-product content — so it
+    // requires `chat.read`, matching the subagent-detail route (the analogous
+    // content surface), not the `settings.read` used by the management routes.
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get workflow run journal",
+    description:
+      "Return a workflow run's leaf journal as bounded per-leaf summaries (one entry per finished leaf).",
+    tags: ["workflows"],
+    responseBody: workflowJournalSchema,
+    additionalResponses: { "404": { description: "Run not found" } },
+    handler: ({ pathParams }: RouteHandlerArgs) =>
+      handleGetRunJournal(pathParams!.id),
+  },
   {
     operationId: "abortWorkflowRun",
     endpoint: "workflows/runs/:id/abort",

package/src/runtime/tool-grant-request-helper.ts

@@ -13,12 +13,14 @@
 
 import type { ChannelId } from "../channels/types.js";
 import {
-  createCanonicalGuardianDelivery,
   createCanonicalGuardianRequest,
   listCanonicalGuardianRequests,
 } from "../memory/canonical-guardian-store.js";
+import {
+  recordApprovalCardDelivery,
+  recordGuardianRequestDeliveries,
+} from "../notifications/canonical-delivery-recorder.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
-import type { NotificationSourceChannel } from "../notifications/signal.js";
 import { getLogger } from "../util/logger.js";
 import { getGuardianBinding } from "./channel-verification-service.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "./routes/channel-route-shared.js";
@@ -140,12 +142,16 @@ export function createOrReuseToolGrantRequest(
     canonicalRequest.requestCode ??
     canonicalRequest.id.slice(0, 6).toUpperCase();
 
+  // The vellum delivery row is created up front in onConversationCreated so the
+  // in-app client sees it immediately; the post-resolve recorder reuses it.
+  let vellumDeliveryId: string | undefined;
+
   // Emit notification so guardian is alerted. Uses 'guardian.question' as
   // sourceEventName so that existing request-code guidance in the notification
   // pipeline is preserved.
   const signalPromise = emitNotificationSignal({
     sourceEventName: "guardian.question",
-    sourceChannel: sourceChannel as NotificationSourceChannel,
+    sourceChannel,
     sourceContextId: conversationId,
     requiresConversation: true,
     attentionHints: {
@@ -167,25 +173,21 @@ export function createOrReuseToolGrantRequest(
     },
     dedupeKey: `tool-grant-request:${canonicalRequest.id}`,
     onConversationCreated: (info) => {
-      createCanonicalGuardianDelivery({
+      vellumDeliveryId = recordApprovalCardDelivery({
         requestId: canonicalRequest.id,
-        destinationChannel: "vellum",
-        destinationConversationId: info.conversationId,
-      });
+        channel: "vellum",
+        conversationId: info.conversationId,
+      })?.id;
     },
   });
 
   // Record deliveries from the notification pipeline results (fire-and-forget).
   void signalPromise.then((signalResult) => {
-    for (const result of signalResult.deliveryResults) {
-      if (result.channel === "vellum") continue; // handled in onConversationCreated
-      createCanonicalGuardianDelivery({
-        requestId: canonicalRequest.id,
-        destinationChannel: result.channel,
-        destinationChatId:
-          result.destination.length > 0 ? result.destination : undefined,
-      });
-    }
+    recordGuardianRequestDeliveries({
+      requestId: canonicalRequest.id,
+      deliveryResults: signalResult.deliveryResults,
+      vellumDeliveryId,
+    });
   });
 
   log.info(

package/src/runtime/trust-context-resolver.ts

@@ -16,6 +16,7 @@ import {
   type ResolveActorTrustInput,
   toTrustContext,
 } from "./actor-trust-resolver.js";
+import { resolveCapabilities } from "./capabilities.js";
 
 /**
  * Resolve route-level trust context from canonical identity state.
@@ -64,14 +65,15 @@ export interface RoutingState {
  * Compute the routing state for a channel actor turn.
  *
  * Guardian actors are always interactive (they self-approve).
- * Trusted contacts are only interactive when a guardian binding exists
- * to receive approval notifications. Unknown actors are never interactive.
+ * Trusted and unverified contacts are only interactive when a guardian
+ * binding exists to receive approval notifications. Unknown actors are
+ * never interactive.
  */
 export function resolveRoutingState(
   ctx: Pick<TrustContext, "trustClass" | "guardianExternalUserId">,
 ): RoutingState {
+  const caps = resolveCapabilities(ctx.trustClass);
   const isGuardian = ctx.trustClass === "guardian";
-  const isTrustedContact = ctx.trustClass === "trusted_contact";
 
   // Guardians self-approve — they are always interactive and route-resolvable.
   if (isGuardian) {
@@ -82,12 +84,13 @@ export function resolveRoutingState(
     };
   }
 
-  // Trusted contacts can be interactive only if a guardian destination
+  // Identity-known non-guardian contacts (trusted_contact /
+  // unverified_contact) can be interactive only if a guardian destination
   // exists. The guardian binding populates guardianExternalUserId during
   // trust resolution; its presence means there is a verified guardian
   // to route approval notifications to.
   const guardianRouteResolvable = !!ctx.guardianExternalUserId;
-  if (isTrustedContact) {
+  if (caps.mayBeInteractive) {
     return {
       canBeInteractive: true,
       guardianRouteResolvable,

package/src/schedule/schedule-store.ts

@@ -158,7 +158,7 @@ export function createSchedule(params: {
   const routingIntent = params.routingIntent ?? "all_channels";
   const routingHints = params.routingHints ?? {};
   const quiet = params.quiet ?? false;
-  const reuseConversation = params.reuseConversation ?? !isOneShot;
+  const reuseConversation = params.reuseConversation ?? false;
   const maxRetries = params.maxRetries ?? 3;
   const retryBackoffMs = params.retryBackoffMs ?? 60000;
   const timeoutMs = params.timeoutMs ?? null;

package/src/schedule/scheduler-types.ts

@@ -7,7 +7,11 @@
 import type { LLMCallSite } from "../config/schemas/llm.js";
 
 export interface ScheduleMessageOptions {
-  trustClass?: "guardian" | "trusted_contact" | "unknown";
+  trustClass?:
+    | "guardian"
+    | "trusted_contact"
+    | "unverified_contact"
+    | "unknown";
   taskRunId?: string;
   /**
    * Optional LLM call-site identifier propagated to the per-call provider

package/src/security/__tests__/provider-key-env-fallback.test.ts

@@ -53,6 +53,7 @@ describe("getProviderKeyAsync env-var fallback (regression #27126)", () => {
     "BRAVE_API_KEY",
     "PERPLEXITY_API_KEY",
     "TAVILY_API_KEY",
+    "FIRECRAWL_API_KEY",
     "ANTHROPIC_API_KEY",
     "OPENAI_API_KEY",
   ];
@@ -103,6 +104,11 @@ describe("getProviderKeyAsync env-var fallback (regression #27126)", () => {
     expect(await getProviderKeyAsync("tavily")).toBe("tavily-env-test");
   });
 
+  test("returns FIRECRAWL_API_KEY from process.env when secure store is empty", async () => {
+    process.env.FIRECRAWL_API_KEY = "fc-env-test";
+    expect(await getProviderKeyAsync("firecrawl")).toBe("fc-env-test");
+  });
+
   test("returns ANTHROPIC_API_KEY from process.env when secure store is empty (LLM regression)", async () => {
     process.env.ANTHROPIC_API_KEY = "anthropic-env-test";
     expect(await getProviderKeyAsync("anthropic")).toBe("anthropic-env-test");

package/src/security/secret-patterns.ts

@@ -133,4 +133,7 @@ export const PREFIX_PATTERNS: SecretPrefixPattern[] = [
 
   // -- Tavily --
   { label: "Tavily API Key", regex: /tvly-[A-Za-z0-9]{20,}/ },
+
+  // -- Firecrawl --
+  { label: "Firecrawl API Key", regex: /fc-[A-Za-z0-9]{20,}/ },
 ];