@vellumai/assistant 0.11.2 → 0.11.3-staging.1

package/src/tools/types.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+import type { AnsweredQuestion } from "../api/events/question-answered.js";
 import type { InterfaceId } from "../channels/types.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
@@ -133,6 +134,14 @@ export interface ToolExecutionResult {
   /** Structured activity metadata for client rendering (web search, web fetch, etc).
    *  Populated by daemon-internal tools; plugins must not set this. */
   activityMetadata?: ToolActivityMetadata;
+  /**
+   * Typed side channel from the `ask_question` executor to the agent loop: the
+   * questions asked and the answers the user gave. The loop forwards it on the
+   * `tool_result` event and persists it on the tool_use block, so the answered
+   * card renders live and survives a history reopen instead of the decision
+   * disappearing with the interactive prompt. Set only by `ask_question`.
+   */
+  answeredQuestion?: AnsweredQuestion;
 }
 
 export type ProxyToolResolver = (
@@ -407,6 +416,14 @@ export interface ToolContext {
    * @legacy
    */
   overrideProfile?: string;
+  /**
+   * The firing's `cron_runs.id` when a schedule triggered this turn, `null`
+   * otherwise. Tools that spawn further LLM work (`subagent_spawn`,
+   * `subagent_message`) forward it so the delegated usage rows carry the same
+   * stamp and attribute to the firing rather than dropping out of schedule
+   * cost reporting.
+   */
+  cronRunId?: string | null;
   /**
    * The LLM call site of the turn currently executing this tool (`mainAgent`,
    * `heartbeatAgent`, scheduled work, etc.). `subagent_spawn` reads it to
@@ -418,10 +435,12 @@ export interface ToolContext {
   invokingCallSite?: LLMCallSite;
   /**
    * Canonical principal ID of the actor on whose behalf this tool invocation
-   * is running. Sourced from `conversation.trustContext.guardianPrincipalId`.
+   * is running — the turn's actor principal, falling back to the trust
+   * context's `guardianPrincipalId` (see `resolveTurnActorPrincipalId`).
    * Used by host proxies to bind cross-client targeted execution to the same
-   * authenticated user identity. May be undefined for legacy/internal flows
-   * with no resolved actor identity.
+   * authenticated user identity, so it must resolve to the SAME principal a
+   * desktop client registers with on its SSE stream. May be undefined for
+   * legacy/internal flows with no resolved actor identity.
    * @legacy
    */
   sourceActorPrincipalId?: string;

package/src/tools/ui-surface/surface-shape-docs.ts

@@ -132,7 +132,7 @@ export const SURFACE_SHAPE_DOCS: Record<string, SurfaceShapeDoc> = {
   oauth_connect: {
     purpose: "managed OAuth connection button for an integration account",
     shape:
-      "{ providerKey, displayName?, description?, logoUrl? } — managed OAuth connection CTA; use when the task needs a managed integration account (Google, Linear, GitHub, ...) instead of settings or shell OAuth. Do not include OAuth scopes; managed providers use the platform's configured scopes",
+      "{ providerKey, requestedScopes?, displayName?, description?, logoUrl? }: managed OAuth connection CTA; use when the task needs a managed integration account (Google, Linear, GitHub, ...) instead of settings or shell OAuth. requestedScopes is an optional FULL replacement set of OAuth scopes: when set, the connection is granted exactly these scopes instead of the platform defaults, so include every scope the connection should keep; omit it to use the platform's default scopes",
     missingContent: (data) =>
       isNonEmptyString(data.providerKey)
         ? null

package/src/tools/ui-surface/visual-validation.ts

@@ -79,8 +79,10 @@ export const WIDGET_TOKEN_PROPERTIES: readonly string[] = [
   // System / status
   "--system-positive-strong",
   "--system-positive-weak",
+  "--system-positive-on-weak",
   "--system-negative-strong",
   "--system-negative-weak",
+  "--system-negative-on-weak",
   "--system-negative-hover",
   "--system-mid-strong",
   "--system-mid-weak",

package/src/usage/__tests__/subagent-attribution.test.ts

@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import { getDb } from "../../persistence/db-connection.js";
+import { initializeDb } from "../../persistence/db-init.js";
+import {
+  resetSubagentAttributionCacheForTests,
+  resolveSubagentAttribution,
+} from "../subagent-attribution.js";
+
+await initializeDb();
+
+let counter = 0;
+
+function insertConversation(opts: {
+  subagentRole?: string;
+  subagentSpawnMode?: string;
+}): string {
+  counter += 1;
+  const id = `conv-attr-${counter}`;
+  const db = getDb();
+  db.run(
+    `INSERT INTO conversations (id, conversation_type, created_at, updated_at, subagent_role, subagent_spawn_mode)
+     VALUES ('${id}', 'background', 1000, 1000, ${
+       opts.subagentRole === undefined ? "NULL" : `'${opts.subagentRole}'`
+     }, ${
+       opts.subagentSpawnMode === undefined
+         ? "NULL"
+         : `'${opts.subagentSpawnMode}'`
+     })`,
+  );
+  return id;
+}
+
+describe("resolveSubagentAttribution", () => {
+  beforeEach(() => {
+    resetSubagentAttributionCacheForTests();
+  });
+
+  test("returns the stamped role and spawn mode for a subagent conversation", () => {
+    const id = insertConversation({
+      subagentRole: "advisor",
+      subagentSpawnMode: "advisor_consult",
+    });
+
+    expect(resolveSubagentAttribution(id)).toEqual({
+      subagentRole: "advisor",
+      subagentSpawnMode: "advisor_consult",
+    });
+  });
+
+  test("returns nulls for an ordinary conversation", () => {
+    const id = insertConversation({});
+
+    expect(resolveSubagentAttribution(id)).toEqual({
+      subagentRole: null,
+      subagentSpawnMode: null,
+    });
+  });
+
+  test("returns nulls without a conversation id", () => {
+    expect(resolveSubagentAttribution(undefined)).toEqual({
+      subagentRole: null,
+      subagentSpawnMode: null,
+    });
+    expect(resolveSubagentAttribution("")).toEqual({
+      subagentRole: null,
+      subagentSpawnMode: null,
+    });
+  });
+
+  test("returns nulls for an unknown conversation and does not cache the miss", () => {
+    // The columns are stamped at conversation creation, so a miss means the
+    // row has not landed yet, and caching it would pin an empty result.
+    expect(resolveSubagentAttribution("conv-not-yet")).toEqual({
+      subagentRole: null,
+      subagentSpawnMode: null,
+    });
+
+    const db = getDb();
+    db.run(
+      `INSERT INTO conversations (id, conversation_type, created_at, updated_at, subagent_role, subagent_spawn_mode)
+       VALUES ('conv-not-yet', 'background', 1000, 1000, 'coder', 'regular')`,
+    );
+
+    expect(resolveSubagentAttribution("conv-not-yet")).toEqual({
+      subagentRole: "coder",
+      subagentSpawnMode: "regular",
+    });
+  });
+
+  test("memoizes a resolved conversation", () => {
+    const id = insertConversation({
+      subagentRole: "general",
+      subagentSpawnMode: "fork",
+    });
+    expect(resolveSubagentAttribution(id).subagentSpawnMode).toBe("fork");
+
+    // The columns are immutable after creation, so a later write must not be
+    // observable, proving the second call did not hit the database.
+    const db = getDb();
+    db.run(
+      `UPDATE conversations SET subagent_spawn_mode = 'regular' WHERE id = '${id}'`,
+    );
+
+    expect(resolveSubagentAttribution(id).subagentSpawnMode).toBe("fork");
+    resetSubagentAttributionCacheForTests();
+    expect(resolveSubagentAttribution(id).subagentSpawnMode).toBe("regular");
+  });
+});

package/src/usage/subagent-attribution.ts

@@ -0,0 +1,108 @@
+import { rawGet } from "../persistence/raw-query.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("subagent-attribution");
+
+/**
+ * The two delegated-work attribution dimensions carried on a conversation:
+ * the subagent role it was spawned with, and how it was spawned. Both null
+ * for a conversation that is not a subagent.
+ */
+export interface SubagentAttribution {
+  subagentRole: string | null;
+  subagentSpawnMode: string | null;
+}
+
+const NOT_A_SUBAGENT: SubagentAttribution = {
+  subagentRole: null,
+  subagentSpawnMode: null,
+};
+
+/**
+ * Bound on the memo below. Both columns are stamped once at conversation
+ * creation and never updated, so a hit is always correct and the only cost of
+ * a bounded cache is an occasional re-read. Sized to comfortably cover the
+ * conversations resident in one process without becoming a memory concern.
+ */
+const MAX_CACHED_CONVERSATIONS = 2048;
+
+/**
+ * Insertion-ordered memo. `Map` iteration order is insertion order, so
+ * dropping the first key evicts the oldest entry, sufficient for a lookup
+ * whose values are immutable and whose miss cost is a single primary-key read.
+ */
+const cache = new Map<string, SubagentAttribution>();
+
+/**
+ * Resolve the delegated-work attribution for a conversation, for forwarding on
+ * the runtime proxy's `X-Vellum-Subagent-*` headers.
+ *
+ * Reads the columns stamped at spawn time (migration 362) rather than the
+ * `subagents` table: `subagents` rows are deleted on dispose, and the billing
+ * path must not depend on a row that may already be gone.
+ *
+ * Never throws. This runs on the provider dispatch hot path and attribution
+ * must never be able to take a model request down. Any failure degrades to
+ * "no attribution", which is exactly how the platform treats a missing header.
+ */
+export function resolveSubagentAttribution(
+  conversationId: string | undefined,
+): SubagentAttribution {
+  if (conversationId === undefined || conversationId.length === 0) {
+    return NOT_A_SUBAGENT;
+  }
+  const cached = cache.get(conversationId);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const row = readRow(conversationId);
+  if (!row) {
+    // Either no row yet, or the read failed. Deliberately NOT cached: caching
+    // a miss would pin an empty result for a conversation whose row lands
+    // moments later, or for the whole process after one transient DB error.
+    return NOT_A_SUBAGENT;
+  }
+
+  const attribution: SubagentAttribution = {
+    subagentRole: row.subagent_role,
+    subagentSpawnMode: row.subagent_spawn_mode,
+  };
+  if (cache.size >= MAX_CACHED_CONVERSATIONS) {
+    const oldest = cache.keys().next();
+    if (!oldest.done) {
+      cache.delete(oldest.value);
+    }
+  }
+  cache.set(conversationId, attribution);
+  return attribution;
+}
+
+interface ConversationSubagentRow {
+  subagent_role: string | null;
+  subagent_spawn_mode: string | null;
+}
+
+/**
+ * Read the two columns, or `null` when the conversation has no row or the
+ * read fails. Failure covers the pre-migration case (columns absent) and any
+ * DB-unavailable context, such as a unit test exercising the provider stack
+ * alone. Attribution must never be able to take a model request down.
+ */
+function readRow(conversationId: string): ConversationSubagentRow | null {
+  try {
+    return rawGet<ConversationSubagentRow>(
+      "usage:subagentAttribution",
+      `SELECT subagent_role, subagent_spawn_mode FROM conversations WHERE id = ?`,
+      conversationId,
+    );
+  } catch (err) {
+    log.debug({ err, conversationId }, "Subagent attribution lookup failed");
+    return null;
+  }
+}
+
+/** Test seam: drops every memoized entry. */
+export function resetSubagentAttributionCacheForTests(): void {
+  cache.clear();
+}

package/src/util/__tests__/sqlite-retry.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Tests for `withSqliteRetry()`, the shared retry wrapper for transient
+ * SQLite write contention (`SQLITE_BUSY*` / `SQLITE_IOERR*`).
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { isRetryableSqliteError, withSqliteRetry } from "../sqlite-retry.js";
+
+function sqliteError(code: string): Error {
+  const err = new Error(code);
+  (err as Error & { code: string }).code = code;
+  return err;
+}
+
+describe("isRetryableSqliteError", () => {
+  test("matches the SQLITE_BUSY and SQLITE_IOERR families", () => {
+    expect(isRetryableSqliteError(sqliteError("SQLITE_BUSY"))).toBe(true);
+    expect(isRetryableSqliteError(sqliteError("SQLITE_BUSY_SNAPSHOT"))).toBe(
+      true,
+    );
+    expect(isRetryableSqliteError(sqliteError("SQLITE_IOERR"))).toBe(true);
+    expect(isRetryableSqliteError(sqliteError("SQLITE_IOERR_SHORT_READ"))).toBe(
+      true,
+    );
+  });
+
+  test("rejects non-transient errors", () => {
+    expect(isRetryableSqliteError(sqliteError("SQLITE_CONSTRAINT"))).toBe(
+      false,
+    );
+    expect(isRetryableSqliteError(new Error("database is locked"))).toBe(false);
+    expect(isRetryableSqliteError(null)).toBe(false);
+    expect(isRetryableSqliteError(undefined)).toBe(false);
+  });
+});
+
+describe("withSqliteRetry", () => {
+  test("returns the wrapped value on first success", async () => {
+    let calls = 0;
+    const result = await withSqliteRetry(
+      () => {
+        calls += 1;
+        return "ok";
+      },
+      { op: "test-op" },
+    );
+    expect(result).toBe("ok");
+    expect(calls).toBe(1);
+  });
+
+  test("retries transient contention and returns the eventual success", async () => {
+    let calls = 0;
+    const result = await withSqliteRetry(
+      () => {
+        calls += 1;
+        if (calls <= 2) {
+          throw sqliteError("SQLITE_BUSY");
+        }
+        return "recovered";
+      },
+      { op: "test-op", baseDelayMs: 1 },
+    );
+    expect(result).toBe("recovered");
+    expect(calls).toBe(3);
+  });
+
+  test("awaits an async wrapped function", async () => {
+    let calls = 0;
+    const result = await withSqliteRetry(
+      async () => {
+        calls += 1;
+        if (calls === 1) {
+          throw sqliteError("SQLITE_IOERR");
+        }
+        return 42;
+      },
+      { op: "test-op", baseDelayMs: 1 },
+    );
+    expect(result).toBe(42);
+    expect(calls).toBe(2);
+  });
+
+  test("throws immediately on a non-retryable error", async () => {
+    let calls = 0;
+    await expect(
+      withSqliteRetry(
+        () => {
+          calls += 1;
+          throw sqliteError("SQLITE_CONSTRAINT_PRIMARYKEY");
+        },
+        { op: "test-op", baseDelayMs: 1 },
+      ),
+    ).rejects.toThrow("SQLITE_CONSTRAINT_PRIMARYKEY");
+    expect(calls).toBe(1);
+  });
+
+  test("rethrows after exhausting maxRetries", async () => {
+    let calls = 0;
+    await expect(
+      withSqliteRetry(
+        () => {
+          calls += 1;
+          throw sqliteError("SQLITE_BUSY");
+        },
+        { op: "test-op", maxRetries: 2, baseDelayMs: 1 },
+      ),
+    ).rejects.toThrow("SQLITE_BUSY");
+    // Initial attempt + 2 retries.
+    expect(calls).toBe(3);
+  });
+});

package/src/util/abort-reasons.ts

@@ -46,6 +46,22 @@ export function createAbortReason(
   };
 }
 
+/**
+ * True when the abort came from a person stopping the turn they are watching
+ * (the Stop button, Esc, or the CLI's cancel signal file) rather than from the
+ * conversation going away or another subsystem seizing it.
+ *
+ * The distinction matters for the message queue. A user interrupt ends the
+ * turn in flight; it says nothing about the messages the same user queued
+ * behind it, so those survive the abort and run on the interrupted turn's
+ * drain. Every other kind (dispose, eviction, voice supersession, subagent
+ * teardown) is the conversation or its owner disappearing, where a queued
+ * message has nothing left to run on and is discarded.
+ */
+export function isUserInterruptAbort(reason: AbortReason | undefined): boolean {
+  return reason?.kind === "user_cancel" || reason?.kind === "signal_cancel";
+}
+
 export function isAbortReason(value: unknown): value is AbortReason {
   if (typeof value !== "object" || value === null) {
     return false;

package/src/util/ansi.ts

@@ -0,0 +1,44 @@
+/**
+ * Stripping of terminal escape sequences and control characters from
+ * untrusted strings before they reach a terminal or notification copy.
+ *
+ * One pattern serves every call site so coverage cannot drift between
+ * hand-rolled copies. CSI sequences carry the full parameter and
+ * intermediate byte ranges; OSC sequences match through their BEL/ST
+ * terminator, with the terminator optional so an unterminated sequence
+ * cannot smuggle its body past the strip.
+ */
+
+/**
+ * Well-formed ANSI escape sequences: CSI (`ESC [ params intermediates final`,
+ * covering colors, cursor moves, erase) and OSC (`ESC ] payload BEL|ST`,
+ * covering window-title writes and hyperlinks).
+ */
+const ANSI_SEQUENCE_RE =
+  /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?/g;
+
+/**
+ * Runs of C0/C1 control characters, including DEL and any bare ESC left by a
+ * malformed sequence. `\r` and `\n` are C0, so this also flattens newlines.
+ */
+const CONTROL_CHAR_RUN_RE = /[\u0000-\u001f\u007f-\u009f]+/g;
+
+/**
+ * Remove ANSI CSI/OSC escape sequences, leaving other control characters
+ * (newlines, tabs) intact. For multi-line text whose line structure matters.
+ */
+export function stripAnsiSequences(value: string): string {
+  return value.replace(ANSI_SEQUENCE_RE, "");
+}
+
+/**
+ * Remove ANSI CSI/OSC escape sequences, then replace every remaining run of
+ * C0/C1 control characters with `replacement` (removed by default). For
+ * single-line rendering where no control character may survive.
+ */
+export function stripAnsiAndControlChars(
+  value: string,
+  replacement = "",
+): string {
+  return stripAnsiSequences(value).replace(CONTROL_CHAR_RUN_RE, replacement);
+}

package/src/util/disk-usage.ts

@@ -1,5 +1,6 @@
-import { spawnSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { existsSync, statfsSync } from "node:fs";
+import { promisify } from "node:util";
 
 import {
   getIsContainerized,
@@ -8,6 +9,8 @@ import {
 } from "../config/env-registry.js";
 import { getWorkspaceDir } from "./platform.js";
 
+const execFileAsync = promisify(execFile);
+
 export interface DiskUsageInfo {
   path: string;
   totalMb: number;
@@ -19,21 +22,17 @@ export interface DiskUsageInfo {
  * Measure the on-disk usage of one or more directory paths using `du -sb`.
  * Returns the sum of all paths in bytes, or null on failure.
  */
-function getDirectorySizeBytes(paths: string[]): number | null {
+async function getDirectorySizeBytes(paths: string[]): Promise<number | null> {
   try {
     const existing = paths.filter((p) => existsSync(p));
     if (existing.length === 0) {
       return null;
     }
-    const result = spawnSync("du", ["-sb", ...existing], {
-      encoding: "utf-8",
+    const { stdout } = await execFileAsync("du", ["-sb", ...existing], {
       timeout: 30_000,
     });
-    if (result.status !== 0) {
-      return null;
-    }
     let total = 0;
-    for (const line of result.stdout.trim().split("\n")) {
+    for (const line of stdout.trim().split("\n")) {
       const size = parseInt(line.split("\t")[0], 10);
       if (!isNaN(size) && size > 0) {
         total += size;
@@ -46,14 +45,19 @@ function getDirectorySizeBytes(paths: string[]): number | null {
 }
 
 const DU_CACHE_TTL_MS = 60_000;
-let duCacheValue: number | null = null;
+// Caches the in-flight promise so concurrent callers share one `du` run.
+let duCacheValue: Promise<number | null> | null = null;
 let duCacheTime = 0;
 let duCachePaths: string | null = null;
 
-function getCachedDirectorySizeBytes(paths: string[]): number | null {
+function getCachedDirectorySizeBytes(paths: string[]): Promise<number | null> {
   const key = paths.join("\0");
   const now = Date.now();
-  if (duCachePaths === key && now - duCacheTime < DU_CACHE_TTL_MS) {
+  if (
+    duCacheValue !== null &&
+    duCachePaths === key &&
+    now - duCacheTime < DU_CACHE_TTL_MS
+  ) {
     return duCacheValue;
   }
   duCacheValue = getDirectorySizeBytes(paths);
@@ -119,7 +123,7 @@ function classifyWorkspaceVolume(
   return { kind: "none" };
 }
 
-export function getDiskUsageInfo(): DiskUsageInfo | null {
+export async function getDiskUsageInfo(): Promise<DiskUsageInfo | null> {
   try {
     const wsDir = getWorkspaceDir();
     const diskPath = existsSync(wsDir) ? wsDir : "/";
@@ -135,7 +139,7 @@ export function getDiskUsageInfo(): DiskUsageInfo | null {
       if (diskPath !== "/data" && existsSync("/data")) {
         volumePaths.push("/data");
       }
-      const usedBytes = getCachedDirectorySizeBytes(volumePaths);
+      const usedBytes = await getCachedDirectorySizeBytes(volumePaths);
       if (usedBytes !== null) {
         const totalBytes =
           reporting.kind === "fixed-cap"

package/src/util/image-conversion.ts

@@ -13,7 +13,6 @@
  * conversions of the same image (or daemon restarts) skip the sips call.
  */
 
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   closeSync,
@@ -101,10 +100,10 @@ export interface ConvertToJpegOptions {
   quality?: number;
 }
 
-function runSips(
+async function runSips(
   inputBytes: Uint8Array,
   options: ConvertToJpegOptions,
-): Buffer | null {
+): Promise<Buffer | null> {
   const stamp = `${Date.now()}-${uuid().slice(0, 8)}`;
   const srcPath = join(tmpdir(), `vellum-img-opt-${stamp}-src`);
   const outPath = join(tmpdir(), `vellum-img-opt-${stamp}-out.jpg`);
@@ -133,7 +132,15 @@ function runSips(
       "--out",
       outPath,
     );
-    execFileSync("sips", args, { stdio: "pipe", timeout: 15_000 });
+    const proc = Bun.spawn(["sips", ...args], {
+      stdout: "ignore",
+      stderr: "ignore",
+      timeout: 15_000,
+    });
+    await proc.exited;
+    if (proc.exitCode !== 0) {
+      return null;
+    }
     return readFileSync(outPath) as Buffer;
   } catch {
     return null;
@@ -155,10 +162,10 @@ function runSips(
  * Convert an image to JPEG, optionally downscaling. Returns null when
  * conversion is unavailable (non-macOS) or fails; callers keep the original.
  */
-export function convertImageToJpeg(
+export async function convertImageToJpeg(
   bytes: Uint8Array,
   options: ConvertToJpegOptions = {},
-): Buffer | null {
+): Promise<Buffer | null> {
   const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
   // Options qualify the key so full-resolution storage conversions and
   // resized transport conversions of the same source never collide.
@@ -173,7 +180,7 @@ export function convertImageToJpeg(
     return cached;
   }
 
-  const converted = runSips(bytes, options);
+  const converted = await runSips(bytes, options);
   if (!converted) {
     return null;
   }
@@ -346,12 +353,12 @@ export interface NormalizedImageBytes {
  * {@link jpegFilenameFor} when `converted` is true — a MIME-only correction
  * sets `converted: false` and keeps the filename.
  */
-export function normalizeImageBytes(
+export async function normalizeImageBytes(
   mimeType: string,
   bytes: Uint8Array,
-): NormalizedImageBytes {
+): Promise<NormalizedImageBytes> {
   if (isHeifImage(bytes)) {
-    const converted = convertImageToJpeg(bytes, {
+    const converted = await convertImageToJpeg(bytes, {
       quality: STORAGE_JPEG_QUALITY,
     });
     if (!converted) {
@@ -376,14 +383,14 @@ export interface NormalizedImageBase64 {
  * Base64 variant of {@link normalizeImageBytes}. Sniffs the decoded head
  * first so non-HEIF payloads skip the full decode.
  */
-export function normalizeImageBase64(
+export async function normalizeImageBase64(
   mimeType: string,
   dataBase64: string,
-): NormalizedImageBase64 {
+): Promise<NormalizedImageBase64> {
   // 16 base64 chars decode to the 12 bytes the ftyp/signature sniffs need.
   const head = Buffer.from(dataBase64.slice(0, 16), "base64");
   if (isHeifImage(head)) {
-    const normalized = normalizeImageBytes(
+    const normalized = await normalizeImageBytes(
       mimeType,
       Buffer.from(dataBase64, "base64"),
     );

package/src/util/schedule-source-key.ts

@@ -0,0 +1,23 @@
+/**
+ * Plugin-declared schedules record their provenance in the `source_key`
+ * column as `plugin:<pluginName>/<scheduleName>`. The format is minted by
+ * `pluginScheduleSourceKey` in schedule/plugin-schedule-declarations.ts;
+ * this leaf parser lets display surfaces (CLI tables, tool output) derive
+ * the owning plugin without importing the daemon's schedule modules.
+ */
+
+const PLUGIN_SOURCE_KEY_RE = /^plugin:([^/]+)\//;
+
+/**
+ * Display attribution for a schedule row: the owning plugin's name, the raw
+ * key when it does not match the format so provenance is never silently
+ * dropped, or null when the row is imperative.
+ */
+export function describeScheduleSource(
+  sourceKey: string | null | undefined,
+): string | null {
+  if (!sourceKey) {
+    return null;
+  }
+  return PLUGIN_SOURCE_KEY_RE.exec(sourceKey)?.[1] ?? sourceKey;
+}