@vellumai/assistant 0.6.4 → 0.6.6

package/src/runtime/agent-wake.ts

@@ -119,9 +119,19 @@ export interface WakeOptions {
   source: string;
 }
 
+/**
+ * Reason a wake returned `invoked: false`. Callers (CLI, update-bulletin
+ * job) need to distinguish "conversation doesn't exist" from "conversation
+ * exists but stayed busy past the wait-until-idle timeout" — the former is
+ * a user-visible error, the latter is an expected transient condition.
+ */
+export type WakeSkipReason = "not_found" | "timeout" | "no_resolver";
+
 export interface WakeResult {
   invoked: boolean;
   producedToolCalls: boolean;
+  /** Present only when `invoked: false`; identifies why the wake was skipped. */
+  reason?: WakeSkipReason;
 }
 
 /**
@@ -223,13 +233,12 @@ async function waitUntilIdle(
   target: WakeTarget,
   nowFn: () => number,
   timeoutMs = 30_000,
-): Promise<void> {
+): Promise<boolean> {
   const deadline = nowFn() + timeoutMs;
-  // 50ms backoff is fine — wakes are not latency-critical and a user turn
-  // typically completes on the order of seconds.
   while (target.isProcessing() && nowFn() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, 50));
   }
+  return !target.isProcessing();
 }
 
 /**
@@ -300,7 +309,7 @@ export async function wakeAgentForOpportunity(
       { conversationId, source },
       "agent-wake: no resolver available (default resolver not registered and no deps passed); skipping",
     );
-    return { invoked: false, producedToolCalls: false };
+    return { invoked: false, producedToolCalls: false, reason: "no_resolver" };
   }
   const nowFn = deps?.now ?? Date.now;
   const startedAt = nowFn();
@@ -312,10 +321,17 @@ export async function wakeAgentForOpportunity(
         { conversationId, source },
         "agent-wake: conversation not found; skipping",
       );
-      return { invoked: false, producedToolCalls: false };
+      return { invoked: false, producedToolCalls: false, reason: "not_found" };
     }
 
-    await waitUntilIdle(target, nowFn);
+    const idle = await waitUntilIdle(target, nowFn);
+    if (!idle) {
+      log.warn(
+        { conversationId, source },
+        "agent-wake: conversation still processing after timeout; skipping",
+      );
+      return { invoked: false, producedToolCalls: false, reason: "timeout" };
+    }
 
     const baseline = target.getMessages();
     const hintContent = `[opportunity:${source}] ${hint}`;
@@ -346,6 +362,7 @@ export async function wakeAgentForOpportunity(
     let producedToolCalls = false;
     let toolUseNames: string[] = [];
     let tailMessageCount = 0;
+    let drainedInTry = false;
     try {
       let updatedHistory: Message[];
       try {
@@ -375,8 +392,11 @@ export async function wakeAgentForOpportunity(
       // `drainSingleMessage` reads `ctx.messages` mid-tail and writes a
       // DB row that lands out of chronological order (queued user msg
       // before the wake's just-produced assistant outputs).
-      const { tailMessages, hasVisibleText, toolUseNames: names } =
-        inspectWakeOutput(baseline.length, updatedHistory);
+      const {
+        tailMessages,
+        hasVisibleText,
+        toolUseNames: names,
+      } = inspectWakeOutput(baseline.length, updatedHistory);
       toolUseNames = names;
       producedToolCalls = names.length > 0;
       const producedOutput = producedToolCalls || hasVisibleText;
@@ -431,11 +451,12 @@ export async function wakeAgentForOpportunity(
         }
       }
 
-      return { invoked: true, producedToolCalls };
-    } finally {
-      // Release the processing marker regardless of success/failure so
-      // the next user turn (or wake) isn't blocked waiting on a stale
-      // flag.
+      // Drain queued messages AFTER tail is pushed + persisted so the
+      // next dequeued user message sees the complete, up-to-date
+      // history. markProcessing(false) must come first (the queue only
+      // accepts entries while processing === true, and drain expects
+      // processing to already be false). The finally block handles the
+      // error/early-return paths where no tail was produced.
       try {
         target.markProcessing(false);
       } catch (err) {
@@ -444,15 +465,6 @@ export async function wakeAgentForOpportunity(
           "agent-wake: markProcessing(false) threw; continuing",
         );
       }
-      // Drain any messages queued during the wake. Order matters:
-      // `enqueueMessage()` only queues when `processing === true`, so
-      // late sends arriving while the wake was running landed on the
-      // queue. The canonical user-turn finally calls drain after
-      // resetting `processing = false` AND after `ctx.messages` has
-      // been updated with the new tail; mirror that here so a queued
-      // message is picked up against an updated history rather than
-      // stranded behind an out-of-order DB row. Wrapped in try/catch
-      // so a drain failure can't propagate out of the wake.
       if (target.drainQueue) {
         try {
           await target.drainQueue();
@@ -463,6 +475,35 @@ export async function wakeAgentForOpportunity(
           );
         }
       }
+      drainedInTry = true;
+
+      return { invoked: true, producedToolCalls };
+    } finally {
+      // The success path (above) already called markProcessing(false)
+      // + drainQueue after tail persist. This catch-all handles the
+      // error and early-return paths where no tail was produced — those
+      // exit the try body before reaching the drain block, so
+      // `drainedInTry` is still false.
+      if (!drainedInTry) {
+        try {
+          target.markProcessing(false);
+        } catch (err) {
+          log.warn(
+            { conversationId, source, err },
+            "agent-wake: markProcessing(false) threw; continuing",
+          );
+        }
+        if (target.drainQueue) {
+          try {
+            await target.drainQueue();
+          } catch (err) {
+            log.warn(
+              { conversationId, source, err },
+              "agent-wake: drainQueue threw; continuing",
+            );
+          }
+        }
+      }
 
       const durationMs = nowFn() - startedAt;
       if (runError) {

package/src/runtime/auth/route-policy.ts

@@ -214,6 +214,10 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
     endpoint: "integrations/slack/channel/config:DELETE",
     scopes: ["settings.write"],
   },
+  {
+    endpoint: "integrations/slack/channel/oauth-install:POST",
+    scopes: ["settings.write"],
+  },
   { endpoint: "channel-verification-sessions", scopes: ["settings.write"] },
   {
     endpoint: "channel-verification-sessions:DELETE",

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,7 +29,15 @@ 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;
@@ -89,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/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/client-registry.ts

@@ -0,0 +1,261 @@
+/**
+ * Unified registry of active client connections.
+ *
+ * Tracks all clients currently connected to the assistant — macOS desktop
+ * (SSE), iOS (SSE), web (SSE), chrome-extension (WebSocket), CLI, and
+ * channel interfaces. Each entry records the interface type, derived
+ * capabilities, connection timestamps, and optional host environment fields.
+ *
+ * The registry is populated by:
+ *   - `handleSendMessage` in conversation-routes.ts (registers/refreshes on
+ *     every inbound message with the interface and transport metadata)
+ *
+ * Future enhancements:
+ *   - Deregister on SSE disconnect (events-routes.ts abort signal)
+ *   - Surface ChromeExtensionRegistry entries through `listAll()`
+ *   - Stale-client eviction sweep
+ *
+ * Consumers:
+ *   - `assistant clients list` CLI command (via `list_clients` IPC route)
+ *   - Future: deferred host tool routing (Phase 2)
+ */
+
+import type { HostProxyCapability, InterfaceId } from "../channels/types.js";
+import { supportsHostProxy } from "../channels/types.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("client-registry");
+
+/**
+ * Default staleness threshold: entries not refreshed within this window are
+ * evicted on the next read. 30 minutes is generous — messages refresh the
+ * entry on every turn, so any actively used client stays well within this.
+ */
+const DEFAULT_STALE_AGE_MS = 30 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** All host-proxy capabilities checked against each interface on register. */
+const ALL_CAPABILITIES: HostProxyCapability[] = [
+  "host_bash",
+  "host_file",
+  "host_cu",
+  "host_browser",
+];
+
+export interface ClientEntry {
+  /** Stable identifier for this client connection. */
+  clientId: string;
+  /** Interface type (e.g. "macos", "ios", "web", "chrome-extension"). */
+  interfaceId: InterfaceId;
+  /** Host-proxy capabilities this client supports. */
+  capabilities: HostProxyCapability[];
+  /** Wall-clock timestamp (ms) when the client first connected. */
+  connectedAt: number;
+  /** Wall-clock timestamp (ms) of the most recent activity. */
+  lastActiveAt: number;
+  /** Home directory on the host machine (only for host-proxy interfaces). */
+  hostHomeDir?: string;
+  /** Username on the host machine (only for host-proxy interfaces). */
+  hostUsername?: string;
+}
+
+/** Serialized form returned by the IPC route / CLI command. */
+export interface ClientEntryJSON {
+  clientId: string;
+  interfaceId: InterfaceId;
+  capabilities: HostProxyCapability[];
+  connectedAt: string;
+  lastActiveAt: string;
+  hostHomeDir?: string;
+  hostUsername?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class ClientRegistry {
+  private clients = new Map<string, ClientEntry>();
+
+  /**
+   * Register or refresh a client connection.
+   *
+   * If a client with the same `clientId` already exists, its `lastActiveAt`
+   * and host environment fields are updated. Otherwise a new entry is created.
+   */
+  register(opts: {
+    clientId: string;
+    interfaceId: InterfaceId;
+    hostHomeDir?: string;
+    hostUsername?: string;
+  }): ClientEntry {
+    const existing = this.clients.get(opts.clientId);
+    const now = Date.now();
+
+    if (existing) {
+      existing.lastActiveAt = now;
+      if (opts.hostHomeDir !== undefined) {
+        existing.hostHomeDir = opts.hostHomeDir;
+      }
+      if (opts.hostUsername !== undefined) {
+        existing.hostUsername = opts.hostUsername;
+      }
+      log.debug(
+        { clientId: opts.clientId, interfaceId: opts.interfaceId },
+        "client refreshed",
+      );
+      return existing;
+    }
+
+    const capabilities = ALL_CAPABILITIES.filter((cap) =>
+      supportsHostProxy(opts.interfaceId, cap),
+    );
+
+    const entry: ClientEntry = {
+      clientId: opts.clientId,
+      interfaceId: opts.interfaceId,
+      capabilities,
+      connectedAt: now,
+      lastActiveAt: now,
+      hostHomeDir: opts.hostHomeDir,
+      hostUsername: opts.hostUsername,
+    };
+
+    this.clients.set(opts.clientId, entry);
+    log.info(
+      {
+        clientId: opts.clientId,
+        interfaceId: opts.interfaceId,
+        capabilities,
+      },
+      "client registered",
+    );
+    return entry;
+  }
+
+  /**
+   * Remove a client connection. No-op if the clientId is not registered.
+   */
+  unregister(clientId: string): void {
+    const entry = this.clients.get(clientId);
+    if (!entry) return;
+    this.clients.delete(clientId);
+    log.info(
+      { clientId, interfaceId: entry.interfaceId },
+      "client unregistered",
+    );
+  }
+
+  /**
+   * Update `lastActiveAt` for a client without changing other fields.
+   * No-op if the clientId is not registered.
+   */
+  touch(clientId: string): void {
+    const entry = this.clients.get(clientId);
+    if (entry) {
+      entry.lastActiveAt = Date.now();
+    }
+  }
+
+  /**
+   * Return a specific client entry, or `undefined` if not registered.
+   */
+  get(clientId: string): ClientEntry | undefined {
+    return this.clients.get(clientId);
+  }
+
+  /**
+   * Return all registered clients, sorted by `lastActiveAt` descending
+   * (most recently active first). Lazily evicts stale entries before
+   * returning so disconnected clients don't linger indefinitely.
+   */
+  listAll(): ClientEntry[] {
+    this.evictStale();
+    return Array.from(this.clients.values()).sort(
+      (a, b) => b.lastActiveAt - a.lastActiveAt,
+    );
+  }
+
+  /**
+   * Return all registered clients that support the given capability,
+   * sorted by `lastActiveAt` descending.
+   */
+  listByCapability(capability: HostProxyCapability): ClientEntry[] {
+    return this.listAll().filter((e) => e.capabilities.includes(capability));
+  }
+
+  /**
+   * Return the most recently active client that supports the given
+   * capability, or `undefined` if none exists.
+   */
+  getMostRecentByCapability(
+    capability: HostProxyCapability,
+  ): ClientEntry | undefined {
+    return this.listByCapability(capability)[0];
+  }
+
+  /**
+   * Remove entries whose `lastActiveAt` is older than `maxAgeMs`.
+   * Called lazily before reads to prevent unbounded map growth from
+   * churning client IDs that are never explicitly unregistered.
+   *
+   * @returns Number of evicted entries.
+   */
+  evictStale(maxAgeMs: number = DEFAULT_STALE_AGE_MS): number {
+    const cutoff = Date.now() - maxAgeMs;
+    let evicted = 0;
+    for (const [id, entry] of this.clients) {
+      if (entry.lastActiveAt < cutoff) {
+        this.clients.delete(id);
+        evicted++;
+        log.debug(
+          { clientId: id, interfaceId: entry.interfaceId },
+          "client evicted (stale)",
+        );
+      }
+    }
+    return evicted;
+  }
+
+  /**
+   * Number of currently registered clients.
+   */
+  get size(): number {
+    return this.clients.size;
+  }
+
+  /**
+   * Serialize a client entry to JSON (ISO timestamps).
+   */
+  static toJSON(entry: ClientEntry): ClientEntryJSON {
+    return {
+      clientId: entry.clientId,
+      interfaceId: entry.interfaceId,
+      capabilities: entry.capabilities,
+      connectedAt: new Date(entry.connectedAt).toISOString(),
+      lastActiveAt: new Date(entry.lastActiveAt).toISOString(),
+      ...(entry.hostHomeDir ? { hostHomeDir: entry.hostHomeDir } : {}),
+      ...(entry.hostUsername ? { hostUsername: entry.hostUsername } : {}),
+    };
+  }
+}
+
+// ── Module-level singleton ────────────────────────────────────────────────
+
+let instance: ClientRegistry | null = null;
+
+export function getClientRegistry(): ClientRegistry {
+  if (!instance) instance = new ClientRegistry();
+  return instance;
+}
+
+/**
+ * Test helper: reset the module-level singleton so each test starts with a
+ * fresh registry.
+ */
+export function __resetClientRegistryForTests(): void {
+  instance = null;
+}