@vellumai/assistant 0.6.3 → 0.6.5

package/src/runtime/auth/token-service.ts

@@ -22,6 +22,7 @@ import {
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
+import { getIsContainerized } from "../../config/env-registry.js";
 import { getLogger } from "../../util/logger.js";
 import { getDeprecatedDir } from "../../util/platform.js";
 import { CURRENT_POLICY_EPOCH, isStaleEpoch } from "./policy.js";
@@ -115,6 +116,58 @@ export function loadOrCreateSigningKey(): Buffer {
   return newKey;
 }
 
+/**
+ * Best-effort sync of the env-resolved signing key to the canonical disk
+ * path so out-of-process CLI commands (e.g. browser relay) that load from
+ * disk converge on the same key the daemon uses.
+ *
+ * Security note: this does NOT expand the signing key's exposure surface.
+ * `loadOrCreateSigningKey()` already writes a signing key to the exact same
+ * disk path (getSigningKeyPath()) with the same mode (0600). A signing key
+ * is always on disk for CLI subprocesses to read — this function just
+ * ensures the disk key matches the env-provided key so those subprocesses
+ * mint tokens the daemon will actually accept.
+ *
+ * Skipped in containerized mode where disk key files are not used.
+ * Uses atomic write (tmp + rename) with mode 0600 for safe persistence.
+ * Never throws -- logs a warning on write failure and continues with
+ * the in-memory key.
+ */
+function syncEnvSigningKeyToDiskIfNeeded(key: Buffer): void {
+  if (getIsContainerized()) {
+    return;
+  }
+
+  const keyPath = getSigningKeyPath();
+
+  try {
+    // If the file already exists and is byte-equal, no-op.
+    if (existsSync(keyPath)) {
+      const existing = readFileSync(keyPath);
+      if (existing.length === key.length && timingSafeEqual(existing, key)) {
+        return;
+      }
+    }
+
+    // Write atomically: tmp file + rename.
+    const dir = dirname(keyPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const tmpPath = keyPath + ".tmp." + process.pid;
+    writeFileSync(tmpPath, key, { mode: 0o600 });
+    renameSync(tmpPath, keyPath);
+    chmodSync(keyPath, 0o600);
+
+    log.info("Synced env signing key to disk for CLI convergence");
+  } catch (err) {
+    log.warn(
+      { err },
+      "Failed to sync env signing key to disk — continuing with in-memory key",
+    );
+  }
+}
+
 /**
  * Resolve the signing key for the daemon from the `ACTOR_TOKEN_SIGNING_KEY`
  * env var (hex-encoded, 64 chars). The CLI launcher sets this before
@@ -128,8 +181,10 @@ export function resolveSigningKey(): Buffer {
         `Invalid ACTOR_TOKEN_SIGNING_KEY: expected 64 hex characters, got ${envKey.length} chars`,
       );
     }
+    const key = Buffer.from(envKey, "hex");
+    syncEnvSigningKeyToDiskIfNeeded(key);
     log.info("Signing key loaded from ACTOR_TOKEN_SIGNING_KEY env var");
-    return Buffer.from(envKey, "hex");
+    return key;
   }
 
   // Fallback: env var not set (e.g. daemon spawned by cli/src/lib/local.ts

package/src/runtime/btw-sidechain.ts

@@ -1,3 +1,4 @@
+import type { LLMCallSite } from "../config/schemas/llm.js";
 import { buildToolDefinitions } from "../daemon/conversation-tool-setup.js";
 import { buildSystemPrompt } from "../prompts/system-prompt.js";
 import {
@@ -7,7 +8,6 @@ import {
 } from "../providers/provider-send-message.js";
 import type {
   Message,
-  ModelIntent,
   Provider,
   ProviderEvent,
   ProviderResponse,
@@ -29,12 +29,21 @@ export interface RunBtwSidechainParams {
   systemPrompt?: string;
   tools?: ToolDefinition[];
   maxTokens?: number;
-  modelIntent?: ModelIntent;
+  /**
+   * Unified call-site identifier. The provider layer resolves
+   * provider/model/maxTokens/effort/speed/temperature/thinking/contextWindow
+   * via `resolveCallSiteConfig(callSite, config.llm)`. Defaults to
+   * `'identityIntro'` since this side-chain runner was originally introduced
+   * for the identity intro generation path; callers (greeting, title, etc.)
+   * override it with their own call-site ID.
+   */
+  callSite?: LLMCallSite;
   signal?: AbortSignal;
   timeoutMs?: number;
   onEvent?: (event: ProviderEvent) => void;
   userPersona?: string | null;
   channelPersona?: string | null;
+  userSlug?: string | null;
 }
 
 export interface RunBtwSidechainResult {
@@ -70,6 +79,7 @@ export async function runBtwSidechain(
           excludeBootstrap: true,
           userPersona: params.userPersona,
           channelPersona: params.channelPersona,
+          userSlug: params.userSlug,
         }));
 
   const { signal: timeoutSignal, cleanup } = createTimeout(
@@ -87,7 +97,9 @@ export async function runBtwSidechain(
       config: {
         max_tokens: params.maxTokens ?? 1024,
         tool_choice: { type: "none" },
-        modelIntent: params.modelIntent ?? "latency-optimized",
+        // Default call site is "identityIntro" — the original purpose of
+        // this side-chain runner. Callers may override per invocation.
+        callSite: params.callSite ?? ("identityIntro" as LLMCallSite),
       },
       onEvent: (event) => {
         if (event.type === "text_delta") {

package/src/runtime/capability-tokens.ts

@@ -27,7 +27,6 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { getLogger } from "../util/logger.js";
@@ -375,18 +374,19 @@ export function verifyHostBrowserCapability(
  * (PRs 7/12/13).
  */
 export function getDaemonTokenFilePath(): string {
-  // Always under `~/.vellum/` (not the configurable workspace dir) so the
-  // native messaging helper can find it at a fixed path regardless of
-  // workspace overrides. This is a dev-only convenience path — production
-  // pairing goes through the native messaging flow.
-  return join(homedir(), ".vellum", "daemon-token");
+  // Stored under the per-instance protected directory. Both writer and
+  // reader run in the same daemon process, so they resolve the same
+  // per-instance path (honoring BASE_DATA_DIR for multi-instance setups).
+  // This is a dev-only convenience path — production pairing goes through
+  // the native messaging flow.
+  return join(getProtectedDir(), "daemon-token");
 }
 
 /**
- * Write a freshly-minted capability token to `~/.vellum/daemon-token` with
- * 0600 permissions. Swallows errors so a failure here never blocks daemon
- * startup — this is a dev-convenience path, not a production auth
- * requirement.
+ * Write a freshly-minted capability token to the per-instance dev token
+ * file (see `getDaemonTokenFilePath`) with 0600 permissions. Swallows
+ * errors so a failure here never blocks daemon startup — this is a
+ * dev-convenience path, not a production auth requirement.
  */
 export function writeDaemonTokenFallback(guardianId: string): void {
   try {

package/src/runtime/channel-invite-transport.ts

@@ -58,7 +58,7 @@ export interface ChannelInviteAdapter {
 
   /**
    * Resolve the channel-specific handle to reach the assistant (e.g.
-   * "@botName", "+15551234567", "hello@domain.agentmail.to").
+   * "@botName", "+15551234567", "hello@vellum.me").
    * Returns `undefined` when the handle cannot be resolved (e.g.
    * credentials not yet configured).
    */

package/src/runtime/channel-invite-transports/email.ts

@@ -2,17 +2,16 @@
  * Email channel invite adapter.
  *
  * Resolves the assistant's email address for use in invite instructions.
- * Uses the EmailService's cached primary inbox lookup so the real address
- * is returned when an inbox is configured. Falls back to `undefined` when
- * no inbox exists, which causes the invite instruction generator to emit
- * generic "on Email" wording instead of a misleading stub address.
+ * Reads the address from workspace config (`email.address`). Returns
+ * `undefined` when no address is configured, which causes the invite
+ * instruction generator to emit generic "on Email" wording.
  *
  * Email invites use the universal 6-digit code path for redemption, so
  * this adapter only implements `resolveChannelHandleAsync` — no
  * `buildShareLink` or `extractInboundToken` needed.
  */
 
-import { getEmailService } from "../../email/service.js";
+import { getNestedValue, loadRawConfig } from "../../config/loader.js";
 import type { ChannelInviteAdapter } from "../channel-invite-transport.js";
 
 // ---------------------------------------------------------------------------
@@ -23,6 +22,15 @@ export const emailInviteAdapter: ChannelInviteAdapter = {
   channel: "email",
 
   async resolveChannelHandleAsync(): Promise<string | undefined> {
-    return getEmailService().getPrimaryInboxAddress();
+    try {
+      const raw = loadRawConfig();
+      const address = getNestedValue(raw, "email.address");
+      if (typeof address === "string" && address.length > 0) {
+        return address;
+      }
+    } catch {
+      // Config unavailable
+    }
+    return undefined;
   },
 };

package/src/runtime/channel-readiness-service.ts

@@ -1,9 +1,8 @@
 import { resolveTwilioPhoneNumber } from "../calls/twilio-config.js";
 import { hasTwilioCredentials } from "../calls/twilio-rest.js";
 import { getChannelInvitePolicy } from "../channels/config.js";
-import { getConfig, loadRawConfig } from "../config/loader.js";
+import { getConfig, getNestedValue, loadRawConfig } from "../config/loader.js";
 import { isEmailEnabled } from "../email/feature-gate.js";
-import { getEmailService } from "../email/service.js";
 import { shouldUsePlatformCallbacks } from "../inbound/platform-callback-registration.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
@@ -81,8 +80,9 @@ async function checkCredential(
 
 /** Check that public ingress is configured and enabled. */
 function checkIngress(allowManagedCallbacks = false): ReadinessCheckResult {
-  const { configured, usesManagedCallbacks } =
-    hasWebhookRoutingConfigured(allowManagedCallbacks);
+  const { configured, usesManagedCallbacks } = hasWebhookRoutingConfigured(
+    allowManagedCallbacks,
+  );
   return check(
     "ingress",
     configured,
@@ -150,17 +150,13 @@ const telegramProbe: ChannelProbe = {
 const emailProbe: ChannelProbe = {
   channel: "email",
   async runLocalChecks(): Promise<ReadinessCheckResult[]> {
-    const hasApiKey = !!(
-      (await getSecureKeyAsync("agentmail")) ||
-      (await getSecureKeyAsync(credentialKey("agentmail", "api_key")))
-    );
     const invitePolicy = getChannelInvitePolicy("email");
     return [
       check(
-        "agentmail_api_key",
-        hasApiKey,
-        "AgentMail API key is configured",
-        "AgentMail API key is not configured",
+        "platform_email",
+        true,
+        "Email is handled through the platform (Mailgun)",
+        "Email requires platform registration",
       ),
       check(
         "invite_policy",
@@ -172,23 +168,17 @@ const emailProbe: ChannelProbe = {
     ];
   },
   async runRemoteChecks(): Promise<ReadinessCheckResult[]> {
-    // Only worth checking if the API key is present
-    const hasApiKey = !!(
-      (await getSecureKeyAsync("agentmail")) ||
-      (await getSecureKeyAsync(credentialKey("agentmail", "api_key")))
-    );
-    if (!hasApiKey) return [];
-
     try {
-      const address = await getEmailService().getPrimaryInboxAddress();
-      const hasInbox = !!address;
+      const raw = loadRawConfig();
+      const address = getNestedValue(raw, "email.address");
+      const hasInbox = typeof address === "string" && address.length > 0;
       return [
         {
           name: "inbox_configured",
           passed: hasInbox,
           message: hasInbox
             ? `Inbox address is configured (${address})`
-            : "No inbox address configured — create one with: assistant email setup inboxes",
+            : "No inbox address configured — register one with: assistant email register <username>",
         },
       ];
     } catch (err) {

package/src/runtime/channel-reply-delivery.ts

@@ -1,6 +1,12 @@
 import { renderHistoryContent } from "../daemon/handlers/shared.js";
 import * as attachmentsStore from "../memory/attachments-store.js";
-import { getMessages } from "../memory/conversation-crud.js";
+import {
+  getMessageById,
+  getMessages,
+  updateMessageMetadata,
+} from "../memory/conversation-crud.js";
+import { readSlackMetadata } from "../messaging/providers/slack/message-metadata.js";
+import { getLogger } from "../util/logger.js";
 import type { ChannelDeliveryResult } from "./gateway-client.js";
 import { deliverChannelReply } from "./gateway-client.js";
 import type { RuntimeAttachmentMetadata } from "./http-types.js";
@@ -9,6 +15,8 @@ import {
   textToSlackBlocks,
 } from "./slack-block-formatting.js";
 
+const log = getLogger("channel-reply-delivery");
+
 const INTER_SEGMENT_DELAY_MS = 150;
 
 type DeliverRenderedReplyParams = {
@@ -206,6 +214,22 @@ export async function deliverReplyViaCallback(
       kind: a.kind,
     }));
 
+    // Compose an `onMessageTs` that reconciles `slackMeta.channelTs` on the
+    // persisted assistant row once Slack returns the authoritative ts. The
+    // assistant row was written BEFORE the gateway POST in
+    // `handleMessageComplete`, so the partial `slackMeta` it carries is
+    // missing `channelTs` and would otherwise be rejected by
+    // `readSlackMetadata`, dropping the row out of chronological/thread-tag
+    // rendering. We only act on the FIRST ts (top-level segment); any
+    // subsequent split segments become independent Slack messages with
+    // their own ts and are not represented as separate DB rows.
+    const reconcileOnMessageTs = makeChannelTsReconciler(msgs[i].id);
+    const callerOnMessageTs = options?.onMessageTs;
+    const composedOnMessageTs = (ts: string): void => {
+      reconcileOnMessageTs(ts);
+      callerOnMessageTs?.(ts);
+    };
+
     await deliverRenderedReplyViaCallback({
       callbackUrl,
       chatId: externalChatId,
@@ -219,8 +243,88 @@ export async function deliverReplyViaCallback(
       ephemeral: options?.ephemeral,
       user: options?.user,
       messageTs: options?.messageTs,
-      onMessageTs: options?.onMessageTs,
+      onMessageTs: composedOnMessageTs,
     });
     break;
   }
 }
+
+/**
+ * Build a one-shot `onMessageTs` handler that reconciles the persisted
+ * assistant message's `slackMeta.channelTs` from Slack's authoritative `ts`.
+ *
+ * Behavior:
+ * - Acts only on the first invocation per delivery (subsequent segments
+ *   correspond to independent Slack messages with their own ts and are not
+ *   represented as separate DB rows).
+ * - No-op when the row was not persisted with a `slackMeta` envelope (the
+ *   channel was not Slack at write-time, e.g. vellum/telegram outbound).
+ * - No-op when the row's existing `slackMeta` already parses cleanly via
+ *   `readSlackMetadata` (channelTs already present, e.g. from a prior
+ *   reconciliation).
+ * - Failures are logged and swallowed so a transient DB error cannot break
+ *   the outbound delivery itself.
+ */
+function makeChannelTsReconciler(messageId: string): (ts: string) => void {
+  let applied = false;
+  return (ts: string): void => {
+    if (applied) return;
+    applied = true;
+    if (!ts) return;
+    try {
+      // Re-read the row's current metadata so a concurrent edit-propagation
+      // write (e.g. `editedAt`) is not clobbered. `updateMessageMetadata`
+      // shallow-merges into the top-level envelope, and the slackMeta
+      // sub-object is merged manually below so we can preserve fields on
+      // the partial pre-send envelope (`mergeSlackMetadata` would call
+      // `readSlackMetadata` which rejects the partial form for lacking
+      // channelTs — exactly the state we are reconciling).
+      const row = getMessageById(messageId);
+      if (row === null || row.metadata === null) return;
+      let envelope: Record<string, unknown>;
+      try {
+        envelope = JSON.parse(row.metadata) as Record<string, unknown>;
+      } catch {
+        return;
+      }
+      const slackMetaRaw =
+        typeof envelope.slackMeta === "string" ? envelope.slackMeta : null;
+      if (slackMetaRaw === null) return;
+      // If the existing slackMeta already parses cleanly via the strict
+      // reader, channelTs is already present (a prior reconciliation ran,
+      // or backfill stamped the field) — nothing to do.
+      if (readSlackMetadata(slackMetaRaw) !== null) return;
+      // Lenient parse of the partial slackMeta so we can preserve every
+      // field already written by `handleMessageComplete` (source,
+      // eventKind, channelId, threadTs, ...) while patching channelTs in.
+      let existingSlackMeta: Record<string, unknown>;
+      try {
+        const parsed = JSON.parse(slackMetaRaw) as unknown;
+        if (
+          parsed === null ||
+          typeof parsed !== "object" ||
+          Array.isArray(parsed)
+        ) {
+          return;
+        }
+        existingSlackMeta = parsed as Record<string, unknown>;
+      } catch {
+        return;
+      }
+      const mergedSlackMeta = JSON.stringify({
+        ...existingSlackMeta,
+        channelTs: ts,
+        // Force `source: "slack"` for parity with `mergeSlackMetadata`'s
+        // invariant — the reader rejects anything else and we never want a
+        // reconciled row to slip through with a stale source.
+        source: "slack",
+      });
+      updateMessageMetadata(messageId, { slackMeta: mergedSlackMeta });
+    } catch (err) {
+      log.warn(
+        { err, messageId },
+        "Failed to reconcile slackMeta.channelTs on outbound assistant row",
+      );
+    }
+  };
+}

package/src/runtime/chrome-extension-registry.ts

@@ -20,8 +20,10 @@
  *   - When a caller does not pin a specific instance, the registry picks
  *     the "most recently active" instance for the guardian (highest
  *     `lastActiveAt` timestamp). `lastActiveAt` is bumped on register and
- *     on every successful `send()`, which is a good enough stand-in for
- *     WebSocket heartbeats under the current load profile.
+ *     on every successful `send()` — but NOT by keepalive pings. Keepalive
+ *     frames update a separate `lastKeepaliveAt` field that is used only
+ *     for liveness checks, preventing idle instances from stealing the
+ *     routing default via periodic keepalive traffic.
  *   - When no `clientInstanceId` is present on the handshake (older
  *     extension builds, dev bypass paths), we synthesize a placeholder
  *     `legacy:<connectionId>` key. The send/lookup path treats it the
@@ -65,8 +67,20 @@ export interface ChromeExtensionConnection {
    * connection — updated on register and on each successful `send()`.
    * Used by the default-send routing path to pick the "most recently
    * active" instance when the caller does not pin a specific one.
+   *
+   * Crucially, this is NOT updated by keepalive pings — those update
+   * `lastKeepaliveAt` instead. This separation prevents idle instances
+   * from stealing the routing default via periodic keepalive traffic.
    */
   lastActiveAt: number;
+  /**
+   * Wall-clock timestamp (ms) of the most recent keepalive ping
+   * received on this connection. Updated exclusively by `touch()`
+   * (i.e. keepalive frames). Does NOT affect routing — used only for
+   * liveness checks (e.g. a future stale-connection sweep can evict
+   * connections whose `lastKeepaliveAt` is too far in the past).
+   */
+  lastKeepaliveAt?: number;
   /**
    * Monotonic registration sequence number assigned by the registry
    * on each `register()` call. Used as a tuple-secondary tiebreaker
@@ -198,6 +212,28 @@ export class ChromeExtensionRegistry {
     }
   }
 
+  /**
+   * Update the `lastKeepaliveAt` timestamp for the connection identified
+   * by `connectionId`, without changing routing semantics or registration
+   * state. Used by keepalive frames to signal that the extension is still
+   * alive and reachable. Deliberately does NOT update `lastActiveAt` — that
+   * field is reserved for actual CDP traffic (register, send) so that idle
+   * instances cannot steal the routing default via periodic keepalive pings.
+   *
+   * No-op if no connection with the given id is currently registered
+   * (e.g. after a race between disconnect and a trailing keepalive frame).
+   */
+  touch(connectionId: string): void {
+    for (const instances of this.byGuardian.values()) {
+      for (const conn of instances.values()) {
+        if (conn.id === connectionId) {
+          conn.lastKeepaliveAt = Date.now();
+          return;
+        }
+      }
+    }
+  }
+
   /**
    * Return the default "active" connection for a guardian — the
    * instance with the most recent `lastActiveAt` timestamp. Ties on

package/src/runtime/decision-token.ts

@@ -0,0 +1,116 @@
+/**
+ * Lightweight informational decision token for interactive UI outcomes.
+ *
+ * Minted when a confirmation-style surface is `submitted`. The token is
+ * **non-authoritative** — it carries metadata about the decision for
+ * audit and correlation purposes only. It does not grant any capability
+ * and must not be used for enforcement or replay protection (that is
+ * explicitly out of scope for v1).
+ *
+ * Format: base64url-encoded JSON payload + `.` + random nonce.
+ * The nonce makes tokens unique even for identical payloads; the
+ * payload is readable by any consumer without a secret.
+ *
+ * This module is intentionally decoupled from the existing auth/token
+ * infrastructure in `runtime/auth/` — it serves a different purpose
+ * and should remain independent.
+ */
+
+import { randomBytes } from "node:crypto";
+
+// ── Token shape ──────────────────────────────────────────────────────
+
+export interface DecisionTokenPayload {
+  /** Conversation the decision belongs to. */
+  conversationId: string;
+  /** Surface identifier that was displayed. */
+  surfaceId: string;
+  /** The action ID the user selected (e.g. "confirm"). Only present on affirmative confirmation. */
+  action: string;
+  /** ISO-8601 timestamp when the decision was recorded. */
+  issuedAt: string;
+  /** ISO-8601 timestamp after which the token should be considered stale. */
+  expiresAt: string;
+}
+
+/** Default token lifetime: 5 minutes. */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+// ── Minting ──────────────────────────────────────────────────────────
+
+/**
+ * Mint an informational decision token.
+ *
+ * The returned string is `<base64url-payload>.<random-nonce>`. It is
+ * short-lived (default 5 minutes) and non-authoritative.
+ *
+ * @param opts - Decision metadata.
+ * @param opts.conversationId - Conversation scope.
+ * @param opts.surfaceId - Surface that was displayed.
+ * @param opts.action - Terminal action taken by the user.
+ * @param opts.ttlMs - Token lifetime in milliseconds (default 5 min).
+ * @returns The minted token string.
+ */
+export function mintDecisionToken(opts: {
+  conversationId: string;
+  surfaceId: string;
+  action: string;
+  ttlMs?: number;
+}): string {
+  const now = new Date();
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const expiresAt = new Date(now.getTime() + ttl);
+
+  const payload: DecisionTokenPayload = {
+    conversationId: opts.conversationId,
+    surfaceId: opts.surfaceId,
+    action: opts.action,
+    issuedAt: now.toISOString(),
+    expiresAt: expiresAt.toISOString(),
+  };
+
+  const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const nonce = randomBytes(12).toString("hex");
+
+  return `${encoded}.${nonce}`;
+}
+
+// ── Decoding (informational only) ────────────────────────────────────
+
+/**
+ * Decode a decision token's payload.
+ *
+ * This is a pure decoding step — there is no signature verification
+ * because the token is non-authoritative. Consumers should treat the
+ * payload as informational metadata, not a trust assertion.
+ *
+ * @param token - The token string produced by {@link mintDecisionToken}.
+ * @returns The decoded payload, or `null` if the token is malformed.
+ */
+export function decodeDecisionToken(
+  token: string,
+): DecisionTokenPayload | null {
+  const dotIdx = token.indexOf(".");
+  if (dotIdx < 0) return null;
+
+  const encodedPayload = token.slice(0, dotIdx);
+  try {
+    const json = Buffer.from(encodedPayload, "base64url").toString("utf-8");
+    const parsed = JSON.parse(json) as Record<string, unknown>;
+
+    // Minimal structural validation
+    if (
+      typeof parsed.conversationId !== "string" ||
+      typeof parsed.surfaceId !== "string" ||
+      typeof parsed.action !== "string" ||
+      typeof parsed.issuedAt !== "string" ||
+      typeof parsed.expiresAt !== "string"
+    ) {
+      return null;
+    }
+
+    return parsed as unknown as DecisionTokenPayload;
+  } catch {
+    return null;
+  }
+}

package/src/runtime/gateway-client.ts

@@ -397,8 +397,8 @@ export async function deliverApprovalPrompt(
   approval: ApprovalUIMetadata,
   assistantId?: string,
   bearerToken?: string,
-): Promise<void> {
-  await deliverChannelReply(
+): Promise<ChannelDeliveryResult> {
+  return deliverChannelReply(
     callbackUrl,
     { chatId, text, approval, assistantId },
     bearerToken,

package/src/runtime/http-router.ts

@@ -48,6 +48,29 @@ export interface RouteQueryParam {
  * The generate-openapi script converts these to JSON Schema via z.toJSONSchema(). */
 export type RouteBodySchema = z.ZodType;
 
+/**
+ * Description for a non-200 response variant. Used when an endpoint has
+ * meaningful alternate response shapes that clients should handle (e.g.
+ * 502 `fetch_failed` on POST /v1/migrations/import when the URL body path
+ * can't reach the upstream bundle host).
+ */
+export interface RouteAdditionalResponse {
+  description: string;
+  /** Zod schema or plain JSON Schema fragment. */
+  schema?: RouteBodySchema | Record<string, unknown>;
+}
+
+/**
+ * Request-body variant keyed by Content-Type. Use this when an endpoint
+ * accepts multiple body shapes (e.g. `application/octet-stream` OR
+ * `application/json`). For the common single-JSON case, use `requestBody`.
+ */
+export interface RouteRequestBodyVariant {
+  contentType: string;
+  /** Zod schema or plain JSON Schema fragment. Plain objects are embedded verbatim. */
+  schema: RouteBodySchema | Record<string, unknown>;
+}
+
 /**
  * A single route entry in the declarative table.
  *
@@ -76,8 +99,17 @@ export interface RouteDefinition {
   queryParams?: RouteQueryParam[];
   /** Zod schema for the request body (POST/PUT/PATCH/DELETE). */
   requestBody?: RouteBodySchema;
+  /**
+   * Alternate request-body variants keyed by Content-Type. When set,
+   * overrides `requestBody` in the generated OpenAPI spec — use this for
+   * endpoints that accept multiple body shapes on the same URL (e.g.
+   * raw bytes OR JSON URL).
+   */
+  requestBodies?: RouteRequestBodyVariant[];
   /** Zod schema for the 200 response body. */
   responseBody?: RouteBodySchema;
+  /** Additional non-200 responses documented in the generated OpenAPI spec. */
+  additionalResponses?: Record<string, RouteAdditionalResponse>;
 }
 
 // ---------------------------------------------------------------------------