@vellumai/assistant 0.3.2 → 0.3.3

package/src/daemon/handlers/skills.ts

@@ -5,8 +5,9 @@ import { getConfig, loadRawConfig, saveRawConfig, invalidateConfigCache } from '
 import { loadSkillCatalog, loadSkillBySelector, ensureSkillIcon } from '../../config/skills.js';
 import { resolveSkillStates } from '../../config/skill-state.js';
 import { getWorkspaceSkillsDir } from '../../util/platform.js';
-import { clawhubInstall, clawhubUpdate, clawhubSearch, clawhubCheckUpdates, clawhubInspect } from '../../skills/clawhub.js';
+import { clawhubInstall, clawhubUpdate, clawhubSearch, clawhubCheckUpdates, clawhubInspect, type ClawhubSearchResultItem } from '../../skills/clawhub.js';
 import { removeSkillsIndexEntry, deleteManagedSkill, validateManagedSkillId } from '../../skills/managed-store.js';
+import { listCatalogEntries, installFromVellumCatalog } from '../../tools/skills/vellum-catalog.js';
 import type {
   SkillDetailRequest,
   SkillsEnableRequest,
@@ -186,26 +187,45 @@ export async function handleSkillsInstall(
   ctx: HandlerContext,
 ): Promise<void> {
   try {
-    const result = await clawhubInstall(msg.slug, { version: msg.version });
-    if (!result.success) {
-      ctx.send(socket, {
-        type: 'skills_operation_response',
-        operation: 'install',
-        success: false,
-        error: result.error ?? 'Unknown error',
-      });
-      return;
+    // Check if the slug matches a vellum-skills catalog entry first
+    const catalogEntries = listCatalogEntries();
+    const isVellumSkill = catalogEntries.some((e) => e.id === msg.slug);
+
+    let skillId: string;
+
+    if (isVellumSkill) {
+      // Install from vellum-skills catalog (local copy)
+      const result = installFromVellumCatalog(msg.slug);
+      if (!result.success) {
+        ctx.send(socket, {
+          type: 'skills_operation_response',
+          operation: 'install',
+          success: false,
+          error: result.error ?? 'Unknown error',
+        });
+        return;
+      }
+      skillId = result.skillName ?? msg.slug;
+    } else {
+      // Install from clawhub (community)
+      const result = await clawhubInstall(msg.slug, { version: msg.version });
+      if (!result.success) {
+        ctx.send(socket, {
+          type: 'skills_operation_response',
+          operation: 'install',
+          success: false,
+          error: result.error ?? 'Unknown error',
+        });
+        return;
+      }
+      const rawId = result.skillName ?? msg.slug;
+      skillId = rawId.includes('/') ? rawId.split('/').pop()! : rawId;
     }
 
     // Reload skill catalog so the newly installed skill is picked up
     loadSkillCatalog();
 
     // Auto-enable the newly installed skill so it's immediately usable.
-    // Use basename of slug to match the catalog ID (directory basename), since
-    // install slugs can be namespaced (e.g. "org/name") but skill state keys use
-    // the bare directory name.
-    const rawId = result.skillName ?? msg.slug;
-    const skillId = rawId.includes('/') ? rawId.split('/').pop()! : rawId;
     try {
       const raw = loadRawConfig();
       ensureSkillEntry(raw, skillId).enabled = true;
@@ -404,12 +424,36 @@ export async function handleSkillsSearch(
   ctx: HandlerContext,
 ): Promise<void> {
   try {
-    const result = await clawhubSearch(msg.query);
+    // Search vellum-skills catalog locally
+    const catalogEntries = listCatalogEntries();
+    const query = (msg.query ?? '').toLowerCase();
+    const matchingCatalog = catalogEntries.filter((e) => {
+      if (!query) return true;
+      return e.name.toLowerCase().includes(query) || e.description.toLowerCase().includes(query) || e.id.toLowerCase().includes(query);
+    });
+    const vellumSkills: ClawhubSearchResultItem[] = matchingCatalog.map((e) => ({
+      name: e.name,
+      slug: e.id,
+      description: e.description,
+      author: 'Vellum',
+      stars: 0,
+      installs: 0,
+      version: '',
+      createdAt: 0,
+      source: 'vellum' as const,
+    }));
+
+    // Search clawhub concurrently
+    const clawhubResult = await clawhubSearch(msg.query);
+
+    // Merge: vellum first, then clawhub
+    const merged = { skills: [...vellumSkills, ...clawhubResult.skills] };
+
     ctx.send(socket, {
       type: 'skills_operation_response',
       operation: 'search',
       success: true,
-      data: result,
+      data: merged,
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/src/daemon/ipc-contract-inventory.json

@@ -91,6 +91,7 @@
     "ToolNamesListRequest",
     "ToolPermissionSimulateRequest",
     "TrustRulesList",
+    "TwilioConfigRequest",
     "TwitterAuthStartRequest",
     "TwitterAuthStatusRequest",
     "TwitterIntegrationConfigRequest",
@@ -215,6 +216,7 @@
     "ToolUseStart",
     "TraceEvent",
     "TrustRulesListResponse",
+    "TwilioConfigResponse",
     "TwitterAuthResult",
     "TwitterAuthStatusResponse",
     "TwitterIntegrationConfigResponse",
@@ -338,6 +340,7 @@
     "tool_names_list",
     "tool_permission_simulate",
     "trust_rules_list",
+    "twilio_config",
     "twitter_auth_start",
     "twitter_auth_status",
     "twitter_integration_config",
@@ -462,6 +465,7 @@
     "tool_use_start",
     "trace_event",
     "trust_rules_list_response",
+    "twilio_config_response",
     "twitter_auth_result",
     "twitter_auth_status_response",
     "twitter_integration_config_response",

package/src/daemon/ipc-contract.ts

@@ -67,6 +67,10 @@ export interface SecretResponse {
 
 export interface SessionListRequest {
   type: 'session_list';
+  /** Number of sessions to skip (for pagination). Defaults to 0. */
+  offset?: number;
+  /** Maximum number of sessions to return. Defaults to 50. */
+  limit?: number;
 }
 
 /** Lightweight session transport metadata for channel identity and natural-language guidance. */
@@ -557,6 +561,7 @@ export interface TwilioConfigRequest {
   phoneNumber?: string;       // Only for action: 'assign_number'
   areaCode?: string;          // Only for action: 'provision_number'
   country?: string;           // Only for action: 'provision_number' (ISO 3166-1 alpha-2, default 'US')
+  assistantId?: string;       // Scope number assignment/lookup to a specific assistant
 }
 
 export interface TwilioConfigResponse {
@@ -566,6 +571,8 @@ export interface TwilioConfigResponse {
   phoneNumber?: string;
   numbers?: Array<{ phoneNumber: string; friendlyName: string; capabilities: { voice: boolean; sms: boolean } }>;
   error?: string;
+  /** Non-fatal warning message (e.g. webhook sync failure that did not prevent the primary operation). */
+  warning?: string;
 }
 
 export interface GuardianVerificationRequest {
@@ -573,6 +580,7 @@ export interface GuardianVerificationRequest {
   action: 'create_challenge' | 'status' | 'revoke';
   channel?: string;  // Defaults to 'telegram'
   sessionId?: string;
+  assistantId?: string;  // Defaults to 'self'
 }
 
 export interface GuardianVerificationResponse {
@@ -1271,6 +1279,8 @@ export interface ChannelBinding {
 export interface SessionListResponse {
   type: 'session_list_response';
   sessions: Array<{ id: string; title: string; updatedAt: number; threadType?: ThreadType; channelBinding?: ChannelBinding }>;
+  /** Whether more sessions exist beyond the returned page. */
+  hasMore?: boolean;
 }
 
 export interface SessionsClearResponse {

package/src/daemon/session-agent-loop.ts

@@ -58,6 +58,7 @@ import { repairHistory, deepRepairHistory } from './history-repair.js';
 import { stripMediaPayloadsForRetry, raceWithTimeout } from './session-media-retry.js';
 import { commitTurnChanges } from '../workspace/turn-commit.js';
 import { getWorkspaceGitService } from '../workspace/git-service.js';
+import { commitAppTurnChanges } from '../memory/app-git-service.js';
 import type { UsageActor } from '../usage/actors.js';
 import type { SkillProjectionCache } from './session-skill-tools.js';
 
@@ -859,6 +860,9 @@ export async function runAgentLoopImpl(
           'Turn-boundary commit timed out — continuing without waiting (commit still runs in background)',
         );
       }
+
+      // Commit app changes (fire-and-forget — apps repo is separate from workspace)
+      void commitAppTurnChanges(ctx.conversationId, ctx.turnCount);
     }
 
     ctx.profiler.emitSummary(ctx.traceEmitter, reqId);

package/src/daemon/session-process.ts

@@ -8,12 +8,13 @@
 
 import type { Message } from '../providers/types.js';
 import type { ServerMessage, UserMessageAttachment } from './ipc-protocol.js';
+import type { UsageStats } from './ipc-contract.js';
 import type { MessageQueue } from './session-queue-manager.js';
 import type { QueueDrainReason } from './session-queue-manager.js';
 import type { TraceEmitter } from './trace-emitter.js';
 import { createUserMessage, createAssistantMessage } from '../agent/message-types.js';
 import * as conversationStore from '../memory/conversation-store.js';
-import { resolveSlash } from './session-slash.js';
+import { resolveSlash, type SlashContext } from './session-slash.js';
 import { getConfig } from '../config/loader.js';
 import { getLogger } from '../util/logger.js';
 import { tryRouteCallMessage } from '../calls/call-bridge.js';
@@ -56,6 +57,8 @@ export interface ProcessSessionContext {
   readonly traceEmitter: TraceEmitter;
   currentActiveSurfaceId?: string;
   currentPage?: string;
+  /** Cumulative token usage stats for the session. */
+  readonly usageStats: UsageStats;
   /** Request-scoped skill IDs preactivated via slash resolution. */
   preactivatedSkillIds?: string[];
   persistUserMessage(content: string, attachments: UserMessageAttachment[], requestId?: string, metadata?: Record<string, unknown>): string;
@@ -67,6 +70,20 @@ export interface ProcessSessionContext {
   ): Promise<void>;
 }
 
+/** Build a SlashContext from the current session state and config. */
+function buildSlashContext(session: ProcessSessionContext): SlashContext {
+  const config = getConfig();
+  return {
+    messageCount: session.messages.length,
+    inputTokens: session.usageStats.inputTokens,
+    outputTokens: session.usageStats.outputTokens,
+    maxInputTokens: config.contextWindow.maxInputTokens,
+    model: config.model,
+    provider: config.provider,
+    estimatedCost: session.usageStats.estimatedCost,
+  };
+}
+
 // ── drainQueue ───────────────────────────────────────────────────────
 
 /**
@@ -96,7 +113,7 @@ export function drainQueue(session: ProcessSessionContext, reason: QueueDrainRea
   });
 
   // Resolve slash commands for queued messages
-  const slashResult = resolveSlash(next.content);
+  const slashResult = resolveSlash(next.content, buildSlashContext(session));
 
   // Unknown slash — persist the exchange and continue draining.
   // Persist each message before pushing to session.messages so that a
@@ -242,7 +259,7 @@ export async function processMessage(
   session.currentPage = currentPage;
 
   // Resolve slash commands before persistence
-  const slashResult = resolveSlash(content);
+  const slashResult = resolveSlash(content, buildSlashContext(session));
 
   // Unknown slash command — persist the exchange (user + assistant) so the
   // messageId is real.  Persist each message before pushing to session.messages

package/src/daemon/session-slash.ts

@@ -15,6 +15,18 @@ export type SlashResolution =
   | { kind: 'rewritten'; content: string; skillId: string }
   | { kind: 'unknown'; message: string };
 
+// ── /status command ──────────────────────────────────────────────────
+
+export interface SlashContext {
+  messageCount: number;
+  inputTokens: number;
+  outputTokens: number;
+  maxInputTokens: number;
+  model: string;
+  provider: string;
+  estimatedCost: number;
+}
+
 // ── /model command ───────────────────────────────────────────────────
 
 const AVAILABLE_MODELS = [
@@ -242,11 +254,31 @@ function resolveModelCommand(content: string): SlashResolution | null {
   };
 }
 
+function resolveStatusCommand(context: SlashContext): SlashResolution {
+  const { inputTokens, maxInputTokens, model, provider, messageCount, outputTokens, estimatedCost } = context;
+  const pct = maxInputTokens > 0 ? Math.min(Math.round((inputTokens / maxInputTokens) * 100), 100) : 0;
+  const filled = Math.round(pct / 5);
+  const bar = '█'.repeat(filled) + '░'.repeat(20 - filled);
+  const fmt = (n: number) => n.toLocaleString('en-US');
+  const displayName = MODEL_DISPLAY_NAMES[model] ?? model;
+
+  const lines = [
+    'Session Status\n',
+    `Context:  ${bar}  ${pct}%  (${fmt(inputTokens)} / ${fmt(maxInputTokens)} tokens)`,
+    `Model:    ${displayName} (${provider})`,
+    `Messages: ${fmt(messageCount)}`,
+    `Tokens:   ${fmt(inputTokens)} in / ${fmt(outputTokens)} out`,
+    `Cost:     $${estimatedCost.toFixed(2)} (estimated)`,
+  ];
+
+  return { kind: 'unknown', message: lines.join('\n') };
+}
+
 /**
  * Resolve slash commands against the current skill catalog.
  * Returns `unknown` with a deterministic message, or the (possibly rewritten) content.
  */
-export function resolveSlash(content: string): SlashResolution {
+export function resolveSlash(content: string, context?: SlashContext): SlashResolution {
   // Check provider shortcuts first (/gpt4, /opus, etc.)
   const providerResult = resolveProviderModelCommand(content);
   if (providerResult) return providerResult;
@@ -255,11 +287,27 @@ export function resolveSlash(content: string): SlashResolution {
   const modelResult = resolveModelCommand(content);
   if (modelResult) return modelResult;
 
+  // Handle /status command
+  if (content.trim() === '/status') {
+    if (!context) {
+      return { kind: 'unknown', message: 'Status information is not available in this context.' };
+    }
+    return resolveStatusCommand(context);
+  }
+
   // Handle /commands command
   if (content.trim() === '/commands') {
+    const lines = [
+      '/commands — List all available commands',
+      '/model — Show or switch the current model',
+      '/models — List all available models',
+    ];
+    if (context) {
+      lines.push('/status — Show session status and context usage');
+    }
     return {
       kind: 'unknown',
-      message: '/commands — List all available commands\n/model — Show or switch the current model\n/models — List all available models',
+      message: lines.join('\n'),
     };
   }
 

package/src/daemon/session-surfaces.ts

@@ -429,6 +429,12 @@ export function refreshSurfacesForApp(ctx: SurfaceSessionContext, appId: string,
     };
     stored.data = updatedData;
 
+    // Keep the persisted snapshot in sync so updates survive session restart.
+    const idx = ctx.currentTurnSurfaces.findIndex(s => s.surfaceId === surfaceId);
+    if (idx !== -1) {
+      ctx.currentTurnSurfaces[idx].data = updatedData;
+    }
+
     // Push the update to the client
     ctx.sendToClient({
       type: 'ui_surface_update',
@@ -603,6 +609,13 @@ export async function surfaceProxyResolver(
       surfaceId,
       data: mergedData,
     });
+
+    // Keep the persisted snapshot in sync so updates survive session restart.
+    const idx = ctx.currentTurnSurfaces.findIndex(s => s.surfaceId === surfaceId);
+    if (idx !== -1) {
+      ctx.currentTurnSurfaces[idx].data = mergedData;
+    }
+
     return { content: 'Surface updated', isError: false };
   }
 
@@ -662,7 +675,10 @@ export async function surfaceProxyResolver(
     const seededHomeBase = findSeededHomeBaseApp();
     const defaultPreview = seededHomeBase && seededHomeBase.id === app.id
       ? getPrebuiltHomeBasePreview()
-      : undefined;
+      // Generate a minimal fallback preview from app metadata so that the
+      // surface is always rendered as a clickable preview card (not an
+      // un-clickable fallback chip) after session restart.
+      : { title: app.name, subtitle: app.description };
 
     const surfaceData: DynamicPageSurfaceData = {
       html: app.htmlDefinition,

package/src/inbound/public-ingress-urls.ts

@@ -73,11 +73,20 @@ export function getPublicBaseUrl(config: IngressConfig): string {
 }
 
 /**
- * Build the Twilio voice webhook URL for a given call session.
+ * Build the Twilio voice webhook URL.
+ *
+ * When `callSessionId` is provided (outbound calls), it is included as a
+ * query parameter so the gateway can correlate the webhook to an existing
+ * session. When omitted (phone-number-level webhook configuration for
+ * inbound calls), the URL is returned without the query parameter — the
+ * gateway will create a new session for inbound calls.
  */
-export function getTwilioVoiceWebhookUrl(config: IngressConfig, callSessionId: string): string {
+export function getTwilioVoiceWebhookUrl(config: IngressConfig, callSessionId?: string): string {
   const base = getPublicBaseUrl(config);
-  return `${base}/webhooks/twilio/voice?callSessionId=${callSessionId}`;
+  if (callSessionId) {
+    return `${base}/webhooks/twilio/voice?callSessionId=${callSessionId}`;
+  }
+  return `${base}/webhooks/twilio/voice`;
 }
 
 /**
@@ -114,6 +123,14 @@ export function getOAuthCallbackUrl(config: IngressConfig): string {
   return `${base}/webhooks/oauth/callback`;
 }
 
+/**
+ * Build the Twilio SMS webhook URL.
+ */
+export function getTwilioSmsWebhookUrl(config: IngressConfig): string {
+  const base = getPublicBaseUrl(config);
+  return `${base}/webhooks/twilio/sms`;
+}
+
 /**
  * Build the Telegram webhook URL.
  */

package/src/index.ts

@@ -2,8 +2,6 @@
 
 import { Command } from 'commander';
 import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
-import { spawn } from 'node:child_process';
 
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json') as { version: string };
@@ -58,24 +56,4 @@ registerCompletionsCommand(program);
 registerTwitterCommand(program);
 registerMapCommand(program);
 
-const knownCommands = new Set(program.commands.map(cmd => cmd.name()));
-const firstArg = process.argv[2];
-
-if (firstArg && !firstArg.startsWith('-') && !knownCommands.has(firstArg)) {
-  try {
-    const cliPkgPath = require.resolve('@vellumai/cli/package.json');
-    const cliEntry = join(dirname(cliPkgPath), 'src', 'index.ts');
-    const child = spawn('bun', ['run', cliEntry, ...process.argv.slice(2)], {
-      stdio: 'inherit',
-    });
-    child.on('exit', (code) => {
-      process.exit(code ?? 1);
-    });
-  } catch {
-    console.error(`Unknown command: ${firstArg}`);
-    console.error('Install the full stack with: bun install -g vellum');
-    process.exit(1);
-  }
-} else {
-  program.parse();
-}
+program.parse();

package/src/memory/app-git-service.ts

@@ -141,6 +141,30 @@ export async function commitAppChange(message: string): Promise<void> {
   }
 }
 
+/**
+ * Commit app changes at turn boundaries.
+ *
+ * Called once per agent turn (after all tool calls complete). Only creates
+ * a commit if there are actual changes in the apps directory, so multiple
+ * mutations within a single turn are batched into one version.
+ *
+ * Fire-and-forget safe: errors are logged but never thrown.
+ */
+export async function commitAppTurnChanges(sessionId: string, turnNumber: number): Promise<void> {
+  try {
+    const appsDir = getAppsDir();
+    ensureAppGitignoreRules(appsDir);
+
+    const gitService = getWorkspaceGitService(appsDir);
+    await gitService.commitIfDirty(() => ({
+      message: `Turn ${turnNumber}: app changes`,
+      metadata: { sessionId, turnNumber },
+    }));
+  } catch (err) {
+    log.error({ err, sessionId, turnNumber }, 'Failed to commit app turn changes');
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Query methods
 // ---------------------------------------------------------------------------

package/src/memory/app-store.ts

@@ -29,7 +29,6 @@ import {
   isPrebuiltHomeBaseApp,
   validatePrebuiltHomeBaseHtml,
 } from '../home-base/prebuilt-home-base-updater.js';
-import { commitAppChange } from './app-git-service.js';
 
 export interface AppDefinition {
   id: string;
@@ -211,8 +210,6 @@ export function createApp(params: {
     app.pages = params.pages;
   }
 
-  void commitAppChange(`Create app: ${params.name}`);
-
   return app;
 }
 
@@ -375,27 +372,14 @@ export function updateApp(
     updated.pages = loadedPages;
   }
 
-  const changedFields = Object.keys(updates).filter(k => updates[k as keyof typeof updates] !== undefined);
-  void commitAppChange(`Update app: ${updated.name}\n\nChanged: ${changedFields.join(', ')}`);
-
   return updated;
 }
 
 export function deleteApp(id: string): void {
   validateId(id);
   const dir = getAppsDir();
-
-  // Read app name before deleting for the commit message
-  let appName = id;
   const filePath = join(dir, `${id}.json`);
   if (existsSync(filePath)) {
-    try {
-      const raw = readFileSync(filePath, 'utf-8');
-      const app = JSON.parse(raw);
-      if (app.name) appName = app.name;
-    } catch {
-      // fall back to id
-    }
     unlinkSync(filePath);
   }
   const previewPath = join(dir, `${id}.preview`);
@@ -404,8 +388,6 @@ export function deleteApp(id: string): void {
   }
   const appDir = join(dir, id);
   rmSync(appDir, { recursive: true, force: true });
-
-  void commitAppChange(`Delete app: ${appName}`);
 }
 
 export function createAppRecord(appId: string, data: Record<string, unknown>): AppRecord {
@@ -545,8 +527,6 @@ export function writeAppFile(appId: string, path: string, content: string): void
   const dir = join(resolved, '..');
   mkdirSync(dir, { recursive: true });
   writeFileSync(resolved, content, 'utf-8');
-
-  void commitAppChange(`Write ${path} in app ${appId}`);
 }
 
 /**
@@ -569,7 +549,6 @@ export function editAppFile(
   const result = applyEdit(content, oldString, newString, replaceAll ?? false);
   if (result.ok) {
     writeFileSync(resolved, result.updatedContent, 'utf-8');
-    void commitAppChange(`Edit ${path} in app ${appId}`);
   }
   return result;
 }

package/src/memory/channel-delivery-store.ts

@@ -15,7 +15,7 @@ import { eq, and, lte, isNotNull } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { getDb } from './db.js';
 import { channelInboundEvents, conversations } from './schema.js';
-import { getOrCreateConversation } from './conversation-key-store.js';
+import { getConversationByKey, getOrCreateConversation, setConversationKeyIfAbsent } from './conversation-key-store.js';
 import {
   classifyError,
   retryDelayForAttempt,
@@ -31,6 +31,7 @@ export interface InboundResult {
 
 export interface RecordInboundOptions {
   sourceMessageId?: string;
+  assistantId?: string;
 }
 
 /**
@@ -69,8 +70,30 @@ export function recordInbound(
     };
   }
 
-  const conversationKey = `${sourceChannel}:${externalChatId}`;
-  const mapping = getOrCreateConversation(conversationKey);
+  const assistantId = options?.assistantId;
+  const legacyKey = `${sourceChannel}:${externalChatId}`;
+  const scopedKey = assistantId ? `asst:${assistantId}:${sourceChannel}:${externalChatId}` : legacyKey;
+
+  // Resolve conversation mapping with assistant-scoped keying:
+  // 1. If scoped key exists, use it directly.
+  // 2. If assistantId is "self" and legacy key exists, reuse the legacy
+  //    conversation and create a scoped alias to prevent future bleed.
+  // 3. Otherwise, create/get conversation from the scoped key.
+  let mapping: { conversationId: string; created: boolean };
+  const scopedMapping = assistantId ? getConversationByKey(scopedKey) : null;
+  if (scopedMapping) {
+    mapping = { conversationId: scopedMapping.conversationId, created: false };
+  } else if (assistantId === 'self') {
+    const legacyMapping = getConversationByKey(legacyKey);
+    if (legacyMapping) {
+      mapping = { conversationId: legacyMapping.conversationId, created: false };
+      setConversationKeyIfAbsent(scopedKey, legacyMapping.conversationId);
+    } else {
+      mapping = getOrCreateConversation(scopedKey);
+    }
+  } else {
+    mapping = getOrCreateConversation(scopedKey);
+  }
   const now = Date.now();
   const eventId = uuid();
 
@@ -316,6 +339,54 @@ export function getDeadLetterEvents(): Array<{
     .all();
 }
 
+// ── Deliver-once guard for terminal reply idempotency ────────────────
+//
+// When both the main poll (processChannelMessageWithApprovals) and the
+// post-decision poll (schedulePostDecisionDelivery) race to deliver the
+// final assistant reply for the same run, this guard ensures only one
+// of them actually sends the message. The guard is run-scoped so old
+// assistant messages from previous runs are not affected.
+
+const deliveredRuns = new Set<string>();
+
+/** TTL for delivery claims — 10 minutes, well beyond the poll max-wait. */
+const CLAIM_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * Atomically claim the right to deliver the final reply for a run.
+ * Returns `true` if this caller won the claim (and should proceed with
+ * delivery). Returns `false` if another caller already claimed it.
+ *
+ * This is an in-memory guard — sufficient because both racing pollers
+ * execute within the same process. The Set is never persisted; on restart
+ * there are no in-flight pollers to race.
+ *
+ * Claims are automatically evicted after CLAIM_TTL_MS to prevent
+ * unbounded Set growth over the lifetime of the process.
+ */
+export function claimRunDelivery(runId: string): boolean {
+  if (deliveredRuns.has(runId)) return false;
+  deliveredRuns.add(runId);
+  setTimeout(() => deliveredRuns.delete(runId), CLAIM_TTL_MS);
+  return true;
+}
+
+/**
+ * Reset the deliver-once guard for a run. Used to release a claim when
+ * delivery fails (so the other racing poller can retry) and in tests
+ * for isolation between test cases.
+ */
+export function resetRunDeliveryClaim(runId: string): void {
+  deliveredRuns.delete(runId);
+}
+
+/**
+ * Clear all delivery claims. Used in tests for full isolation.
+ */
+export function resetAllRunDeliveryClaims(): void {
+  deliveredRuns.clear();
+}
+
 /**
  * Reset dead-lettered events back to 'failed' so the sweep can retry
  * them. Resets attempt counter and sets an immediate retry_after.