@vellumai/assistant 0.6.2 → 0.6.4

package/src/stt/wav-encoder.ts

@@ -0,0 +1,175 @@
+/**
+ * Shared PCM16LE-to-WAV utility for STT streaming adapters.
+ *
+ * Wraps raw PCM16LE audio bytes in a valid 44-byte RIFF/WAVE header so that
+ * STT providers that require WAV input (e.g. OpenAI Whisper) can consume
+ * audio captured from streaming sessions.
+ *
+ * This helper is intentionally decoupled from any specific provider adapter
+ * so it can be reused across batch and streaming transcription paths.
+ */
+
+// ---------------------------------------------------------------------------
+// Format options
+// ---------------------------------------------------------------------------
+
+/**
+ * Audio format parameters for the PCM-to-WAV encoder.
+ *
+ * Adapters pass the hardware sample rate captured during the streaming
+ * handshake so the WAV header accurately describes the audio data.
+ */
+export interface WavFormatOptions {
+  /** Sample rate in Hz (e.g. 16000, 44100, 48000). Must be positive. */
+  sampleRate: number;
+  /** Number of audio channels (1 = mono, 2 = stereo). Must be positive. */
+  channels: number;
+  /**
+   * Bits per sample. Defaults to 16 (PCM16LE).
+   *
+   * Only 8, 16, 24, and 32 are supported — these are the standard PCM bit
+   * depths that fit evenly into whole bytes.
+   */
+  bitsPerSample?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_BIT_DEPTHS = new Set([8, 16, 24, 32]);
+
+/**
+ * Validate format options and throw descriptive errors for invalid
+ * configurations. Called internally before encoding.
+ */
+function validateFormatOptions(options: WavFormatOptions): void {
+  const { sampleRate, channels, bitsPerSample = 16 } = options;
+
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+    throw new Error(
+      `Invalid sampleRate: ${sampleRate}. Must be a positive finite number.`,
+    );
+  }
+
+  if (
+    !Number.isFinite(channels) ||
+    channels <= 0 ||
+    !Number.isInteger(channels)
+  ) {
+    throw new Error(
+      `Invalid channels: ${channels}. Must be a positive integer.`,
+    );
+  }
+
+  if (!SUPPORTED_BIT_DEPTHS.has(bitsPerSample)) {
+    throw new Error(
+      `Unsupported bitsPerSample: ${bitsPerSample}. ` +
+        `Supported values: ${[...SUPPORTED_BIT_DEPTHS].join(", ")}.`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// WAV header constants
+// ---------------------------------------------------------------------------
+
+/** Total size of the RIFF/WAVE header for PCM data. */
+const WAV_HEADER_SIZE = 44;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap raw PCM audio bytes in a valid 44-byte RIFF/WAVE header.
+ *
+ * @param pcmData - Raw PCM audio data (e.g. PCM16LE samples).
+ * @param options - Audio format options describing the PCM data.
+ * @returns A `Buffer` containing a complete WAV file (header + PCM payload).
+ *
+ * @example
+ * ```ts
+ * const wav = encodePcm16LeToWav(rawPcmBuffer, {
+ *   sampleRate: 16000,
+ *   channels: 1,
+ * });
+ * ```
+ */
+export function encodePcm16LeToWav(
+  pcmData: Buffer,
+  options: WavFormatOptions,
+): Buffer {
+  validateFormatOptions(options);
+
+  const { sampleRate, channels, bitsPerSample = 16 } = options;
+
+  const bytesPerSample = bitsPerSample / 8;
+  const blockAlign = channels * bytesPerSample;
+  const byteRate = sampleRate * blockAlign;
+  const dataSize = pcmData.length;
+  const fileSize = WAV_HEADER_SIZE + dataSize;
+
+  const buffer = Buffer.alloc(fileSize);
+  let offset = 0;
+
+  // ---- RIFF chunk descriptor ----
+  // ChunkID: "RIFF"
+  buffer.write("RIFF", offset, "ascii");
+  offset += 4;
+
+  // ChunkSize: file size minus 8 bytes (RIFF header)
+  buffer.writeUInt32LE(fileSize - 8, offset);
+  offset += 4;
+
+  // Format: "WAVE"
+  buffer.write("WAVE", offset, "ascii");
+  offset += 4;
+
+  // ---- fmt sub-chunk ----
+  // Subchunk1ID: "fmt "
+  buffer.write("fmt ", offset, "ascii");
+  offset += 4;
+
+  // Subchunk1Size: 16 for PCM
+  buffer.writeUInt32LE(16, offset);
+  offset += 4;
+
+  // AudioFormat: 1 = PCM (uncompressed)
+  buffer.writeUInt16LE(1, offset);
+  offset += 2;
+
+  // NumChannels
+  buffer.writeUInt16LE(channels, offset);
+  offset += 2;
+
+  // SampleRate
+  buffer.writeUInt32LE(sampleRate, offset);
+  offset += 4;
+
+  // ByteRate = SampleRate * NumChannels * BitsPerSample / 8
+  buffer.writeUInt32LE(byteRate, offset);
+  offset += 4;
+
+  // BlockAlign = NumChannels * BitsPerSample / 8
+  buffer.writeUInt16LE(blockAlign, offset);
+  offset += 2;
+
+  // BitsPerSample
+  buffer.writeUInt16LE(bitsPerSample, offset);
+  offset += 2;
+
+  // ---- data sub-chunk ----
+  // Subchunk2ID: "data"
+  buffer.write("data", offset, "ascii");
+  offset += 4;
+
+  // Subchunk2Size: size of the raw audio data
+  buffer.writeUInt32LE(dataSize, offset);
+  offset += 4;
+
+  // ---- PCM payload ----
+  pcmData.copy(buffer, offset);
+
+  return buffer;
+}

package/src/subagent/manager.ts

@@ -19,6 +19,7 @@ import type { ServerMessage } from "../daemon/message-protocol.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
 import { RateLimitProvider } from "../providers/ratelimit.js";
 import { getProvider } from "../providers/registry.js";
+import { createAbortReason } from "../util/abort-reasons.js";
 import { getLogger } from "../util/logger.js";
 import { getSandboxWorkingDir } from "../util/platform.js";
 import {
@@ -88,13 +89,19 @@ interface ManagedSubagent {
   /** Epoch ms after which this terminal entry can be removed by the TTL sweep. */
   retainedUntil?: number;
   /**
-   * Set to true when sendMessage enqueues a follow-up message while the
-   * initial objective loop is running.  runAgentLoop fires drainQueue without
-   * awaiting it, and drainQueue shift()s the item synchronously — so both
-   * hasQueuedMessages() and isProcessing() can return false while the drain
-   * is still active.  This flag lets the finally block in runSubagent defer
-   * the release to the TTL sweep rather than tearing down the conversation
-   * mid-drain.
+   * Sticky monotonic flag: set to true when sendMessage enqueues a follow-up
+   * message while a run is in progress, and never cleared. Needed because the
+   * drain dispatch is racy against the observation window around runAgentLoop's
+   * `finally`: drainQueue is async — it awaits buildPassthroughBatch (which
+   * awaits resolveSlash) before shifting anything — and runAgentLoop fires it
+   * without awaiting. So between the moment `finally` schedules drainQueue and
+   * the moment a queued item is actually dispatched by drainBatch /
+   * drainSingleMessage, `hasQueuedMessages()` and `isProcessing()` can each
+   * flip in either direction (queue empties mid-await, or `processing` flips
+   * false while items are still pending). Checking this sticky flag lets the
+   * finally block in runSubagent reason about "any queued work existed for
+   * this subagent during the run" without racing drain dispatch, and defer
+   * the release to the TTL sweep rather than tearing down mid-drain.
    */
   hadEnqueuedMessages?: boolean;
 }
@@ -142,6 +149,14 @@ export class SubagentManager {
    */
   broadcastToAllClients?: (msg: ServerMessage) => void;
 
+  /**
+   * Resolve a live parent Conversation by conversationId.
+   * Wired by DaemonServer at startup — follows the same pattern as
+   * `onSubagentFinished`.  Used by fork spawn to resolve the parent's
+   * system prompt when `config.parentSystemPrompt` is not provided.
+   */
+  resolveParentConversation?: (conversationId: string) => Conversation | undefined;
+
   // ── Spawn ───────────────────────────────────────────────────────────
 
   /**
@@ -165,7 +180,19 @@ export class SubagentManager {
     }
 
     // ── Resolve role ─────────────────────────────────────────────────
-    const role: SubagentRole = (config.role as SubagentRole) ?? "general";
+    const isFork = config.fork === true;
+    let role: SubagentRole = (config.role as SubagentRole) ?? "general";
+    if (isFork && role !== "general") {
+      log.warn(
+        {
+          requestedRole: role,
+          parentConversationId: config.parentConversationId,
+          label: config.label,
+        },
+        "Fork requested with non-general role — forcing general to preserve KV cache alignment",
+      );
+      role = "general";
+    }
     if (!SUBAGENT_ROLE_REGISTRY[role]) {
       throw new Error(
         `Invalid subagent role "${config.role}". Must be one of: ${Object.keys(SUBAGENT_ROLE_REGISTRY).join(", ")}`,
@@ -194,24 +221,58 @@ export class SubagentManager {
       );
     }
 
-    const systemPrompt =
-      config.systemPromptOverride ??
-      buildSubagentSystemPrompt({ ...config, id: subagentId }, role);
+    let systemPrompt: string;
+    if (isFork) {
+      // Forks use the parent's system prompt directly — no subagent preamble.
+      if (config.parentSystemPrompt) {
+        systemPrompt = config.parentSystemPrompt;
+      } else if (this.resolveParentConversation) {
+        const parentConv = this.resolveParentConversation(config.parentConversationId);
+        const resolved = parentConv?.getCurrentSystemPrompt();
+        if (!resolved) {
+          throw new Error(
+            "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
+            "nor resolveParentConversation yielded one.",
+          );
+        }
+        systemPrompt = resolved;
+      } else {
+        throw new Error(
+          "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
+          "is set nor resolveParentConversation callback is wired.",
+        );
+      }
+    } else {
+      systemPrompt =
+        config.systemPromptOverride ??
+        buildSubagentSystemPrompt({ ...config, id: subagentId }, role);
+    }
     const maxTokens = appConfig.maxTokens;
     const workingDir = getSandboxWorkingDir();
 
-    const memoryPolicy: ConversationMemoryPolicy = {
-      scopeId: `subagent:${subagentId}`,
-      includeDefaultFallback: true,
-      strictSideEffects: false,
-    };
+    const memoryPolicy: ConversationMemoryPolicy = isFork
+      ? {
+          scopeId: "default",
+          includeDefaultFallback: false,
+          strictSideEffects: false,
+        }
+      : {
+          scopeId: `subagent:${subagentId}`,
+          includeDefaultFallback: true,
+          strictSideEffects: false,
+        };
 
     // ── Initialise state ────────────────────────────────────────────
     const now = Date.now();
+    // For forks, default sendResultToUser to false (silent) unless explicitly true.
+    const resolvedSendResultToUser = isFork
+      ? (config.sendResultToUser === true ? true : false)
+      : config.sendResultToUser;
     const state: SubagentState = {
-      config: { ...config, id: subagentId },
+      config: { ...config, id: subagentId, sendResultToUser: resolvedSendResultToUser },
       status: "pending",
       conversationId: conversationRecord.id,
+      isFork,
       createdAt: now,
       usage: { inputTokens: 0, outputTokens: 0, estimatedCost: 0 },
     };
@@ -255,8 +316,16 @@ export class SubagentManager {
     conversation.updateClient(wrappedSendToClient, true);
     conversation.setIsSubagent(true);
 
+    if (isFork) {
+      // Force the fork to use the parent's system prompt as-is without dynamic rebuild.
+      // This ensures KV cache alignment with the parent conversation.
+      conversation.hasSystemPromptOverride = true;
+    }
+
     // Apply role-based tool filter if the role defines one.
-    if (roleConfig.allowedTools) {
+    // Skip for forks — general role has allowedTools: undefined, and forks
+    // should have the same tool access as the parent.
+    if (!isFork && roleConfig.allowedTools) {
       conversation.setSubagentAllowedTools(new Set(roleConfig.allowedTools));
     }
 
@@ -298,6 +367,7 @@ export class SubagentManager {
       parentConversationId: config.parentConversationId,
       label: config.label,
       objective: config.objective,
+      isFork: config.fork ?? false,
     } as ServerMessage);
 
     log.info(
@@ -339,9 +409,37 @@ export class SubagentManager {
     const onEvent = conversation.sendToClient;
 
     try {
+      // For forks, inject the parent's message history before the first message.
+      // This prepends the inherited context so the fork has full conversational
+      // awareness while the objective becomes the latest user turn.
+      if (managed.state.isFork && managed.state.config.parentMessages) {
+        conversation.injectInheritedContext(managed.state.config.parentMessages);
+        // Release the parent message arrays now that they've been injected — holding
+        // them in SubagentState.config would retain significant memory until the TTL
+        // sweep disposes this entry (up to 30 minutes for terminal subagents).
+        managed.state.config.parentMessages = undefined;
+        managed.state.config.parentSystemPrompt = undefined;
+      }
+
       // Send the objective as the first user message and process it.
-      const messageId = await conversation.persistUserMessage(objective, []);
-      await conversation.runAgentLoop(objective, messageId, onEvent);
+      // For forks, wrap the objective in directive framing so it overrides
+      // conversational momentum from the inherited context. Without this,
+      // the fork tends to continue the parent conversation instead of
+      // pivoting to the task — the inherited context is louder than a bare
+      // objective buried after 100k+ tokens of chat history.
+      const message = managed.state.isFork
+        ? [
+            "⎯⎯⎯ FORK TASK ⎯⎯⎯",
+            "You have been forked from the parent conversation to execute a specific task.",
+            "The conversation above is context — do NOT continue it. Do NOT spawn sub-agents.",
+            "Complete this task directly and return only your findings:",
+            "",
+            objective,
+            "⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯",
+          ].join("\n")
+        : objective;
+      const messageId = await conversation.persistUserMessage(message, []);
+      await conversation.runAgentLoop(message, messageId, onEvent);
 
       // Agent loop completed successfully.
       // Copy usage stats from the conversation before sending status (which includes usage).
@@ -373,11 +471,16 @@ export class SubagentManager {
       log.error({ subagentId, err }, "Subagent failed");
     } finally {
       // Release the heavyweight Conversation — output is already persisted in DB.
-      // runAgentLoop fires drainQueue without awaiting it, and drainQueue shift()s
-      // the next item synchronously — so both hasQueuedMessages() and
-      // isProcessing() can return false while a drain is still active.  Use the
-      // hadEnqueuedMessages flag (set in sendMessage) to detect this case and
-      // defer the release to the TTL sweep rather than tearing down mid-drain.
+      // drainQueue is async: it awaits buildPassthroughBatch (which awaits
+      // resolveSlash) before shifting anything, and runAgentLoop fires it
+      // without awaiting. That means by the time this finally runs, a drain
+      // may already be scheduled but not yet dispatched — so checking
+      // hasQueuedMessages() / isProcessing() here races the dispatch and can
+      // observe an empty queue (or `processing === false`) while queued work
+      // is still pending. The hadEnqueuedMessages flag (set in sendMessage)
+      // is a sticky monotonic marker that any queued work existed during this
+      // run, letting us defer the release to the TTL sweep rather than
+      // tearing down mid-drain.
       if (managed.hadEnqueuedMessages) {
         log.debug(
           { subagentId },
@@ -418,7 +521,13 @@ export class SubagentManager {
       return false;
     }
 
-    managed.conversation?.abort();
+    managed.conversation?.abort(
+      createAbortReason(
+        "subagent_aborted",
+        "SubagentManager.abort",
+        managed.conversation.conversationId,
+      ),
+    );
     managed.state.completedAt = Date.now();
     if (parentSendToClient) {
       // Route the status update through the stored parent sender so the
@@ -431,9 +540,10 @@ export class SubagentManager {
       // Skip when the parent LLM itself called subagent_abort (it already has the tool result).
       if (this.onSubagentFinished && !options?.suppressNotification) {
         const label = managed.state.config.label;
+        const prefix = managed.state.isFork ? "Fork" : "Subagent";
         const message =
-          `[Subagent "${label}" was explicitly aborted]\n\n` +
-          `This subagent was cancelled on purpose. Do NOT re-spawn or retry it.`;
+          `[${prefix} "${label}" was explicitly aborted]\n\n` +
+          `This ${prefix.toLowerCase()} was cancelled on purpose. Do NOT re-spawn or retry it.`;
         try {
           // Use the managed subagent's stored parentSendToClient so the
           // notification routes to the parent conversation's socket, not the
@@ -612,7 +722,13 @@ export class SubagentManager {
 
     if (managed.conversation) {
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
-        managed.conversation.abort();
+        managed.conversation.abort(
+          createAbortReason(
+            "subagent_aborted",
+            "SubagentManager.dispose",
+            managed.conversation.conversationId,
+          ),
+        );
       }
       managed.conversation.dispose();
       managed.conversation = null;
@@ -781,10 +897,11 @@ export class SubagentManager {
     if (!managed || TERMINAL_STATUSES.has(managed.state.status)) return false;
     if (!this.onSubagentFinished) return false;
 
-    let notificationString = `[Subagent "${info.label}" — ${urgency}] ${message}`;
+    const prefix = managed.state.isFork ? "Fork" : "Subagent";
+    let notificationString = `[${prefix} "${info.label}" — ${urgency}] ${message}`;
     if (urgency === "blocked") {
       notificationString +=
-        "\nUse subagent_message to send guidance to this subagent.";
+        `\nUse subagent_message to send guidance to this ${prefix.toLowerCase()}.`;
     }
 
     try {
@@ -820,22 +937,34 @@ export class SubagentManager {
     if (!this.onSubagentFinished) return;
 
     const { config } = managed.state;
+    const isFork = managed.state.isFork;
     let message: string;
 
     if (outcome === "completed") {
-      const silent = config.sendResultToUser === false;
-      message =
-        `[Subagent "${config.label}" completed]\n\n` +
-        `Use subagent_read with subagent_id "${config.id}" to retrieve the full output.\n` +
-        (silent
-          ? `This subagent was spawned for internal processing. Read the result for your own use but do NOT share it with the user.\nDo NOT re-spawn this subagent.`
-          : `Do NOT re-spawn this subagent — just read and share the results.`);
+      if (isFork) {
+        const silent = config.sendResultToUser !== true;
+        message =
+          `[Fork "${config.label}" completed]\n\n` +
+          `Use subagent_read with subagent_id "${config.id}" and last_n: 1 to retrieve the final synthesis.\n` +
+          (silent
+            ? `This fork was spawned for internal processing. Process the findings internally — do NOT share raw fork output with the user.`
+            : `Do NOT re-spawn this fork — just read and share the results.`);
+      } else {
+        const silent = config.sendResultToUser === false;
+        message =
+          `[Subagent "${config.label}" completed]\n\n` +
+          `Use subagent_read with subagent_id "${config.id}" to retrieve the full output.\n` +
+          (silent
+            ? `This subagent was spawned for internal processing. Read the result for your own use but do NOT share it with the user.\nDo NOT re-spawn this subagent.`
+            : `Do NOT re-spawn this subagent — just read and share the results.`);
+      }
     } else {
       const error = managed.state.error ?? "Unknown error";
+      const prefix = isFork ? "Fork" : "Subagent";
       message =
-        `[Subagent "${config.label}" failed]\n\n` +
+        `[${prefix} "${config.label}" failed]\n\n` +
         `Error: ${error}\n` +
-        `Do NOT re-spawn or retry this subagent unless the user explicitly asks.`;
+        `Do NOT re-spawn or retry this ${prefix.toLowerCase()} unless the user explicitly asks.`;
     }
 
     const notification: SubagentNotificationInfo = {

package/src/subagent/types.ts

@@ -7,6 +7,7 @@
  */
 
 import type { UsageStats } from "../daemon/message-protocol.js";
+import type { Message } from "../providers/types.js";
 
 // ── Status ──────────────────────────────────────────────────────────────
 
@@ -43,6 +44,22 @@ export interface SubagentConfig {
   sendResultToUser?: boolean;
   /** Optional role for the subagent. Defaults handled by consumers. */
   role?: SubagentRole;
+  /**
+   * When true, the sub-agent inherits the parent's full context instead of
+   * receiving only the objective + context fields.
+   */
+  fork?: boolean;
+  /**
+   * The parent conversation's in-memory message history at fork time.
+   * Only set when `fork: true`.
+   */
+  parentMessages?: Message[];
+  /**
+   * The parent's current resolved system prompt. Only set when `fork: true`.
+   * Distinct from `systemPromptOverride` which replaces the subagent-built prompt;
+   * for forks, this IS the system prompt (no subagent preamble is built).
+   */
+  parentSystemPrompt?: string;
 }
 
 // ── State (runtime) ─────────────────────────────────────────────────────
@@ -52,6 +69,8 @@ export interface SubagentState {
   status: SubagentStatus;
   /** The subagent's own conversationId (different from parentConversationId). */
   conversationId: string;
+  /** Whether this sub-agent is a fork (inherits parent context). Defaults to `false`. */
+  isFork: boolean;
   /** Error message if status is 'failed'. */
   error?: string;
   /** Timestamps (epoch ms). */

package/src/tools/apps/executors.ts

@@ -32,6 +32,7 @@ export interface ExecutorResult {
 export interface AppStoreReader {
   getApp(id: string): AppDefinition | null;
   listApps(): AppDefinition[];
+  appFileExists(appId: string, path: string): boolean;
 }
 
 export interface AppStoreWriter {
@@ -183,8 +184,16 @@ function App() {
 render(<App />, document.getElementById('app')!);
 `;
 
-    store.writeAppFile(app.id, "src/index.html", indexHtml);
-    store.writeAppFile(app.id, "src/main.tsx", mainTsx);
+    // Only write scaffold files when they don't already exist on disk.
+    // The LLM may have written custom source files via file_write before
+    // calling app_create, and overwriting them would destroy the real app
+    // content, leaving only the scaffold placeholder.
+    if (!store.appFileExists(app.id, "src/index.html")) {
+      store.writeAppFile(app.id, "src/index.html", indexHtml);
+    }
+    if (!store.appFileExists(app.id, "src/main.tsx")) {
+      store.writeAppFile(app.id, "src/main.tsx", mainTsx);
+    }
 
     // Compile src/ → dist/
     const appDir = getAppDirPath(app.id);