@vellumai/assistant 0.6.4 → 0.6.6

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>;
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/http-server.ts

@@ -36,6 +36,7 @@ import {
   handleVoiceWebhook,
 } from "../calls/twilio-routes.js";
 import { parseChannelId } from "../channels/types.js";
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import {
   getGatewayInternalBaseUrl,
   hasUngatedHttpAuthDisabled,
@@ -53,7 +54,10 @@ import {
   type SignalType,
 } from "../memory/conversation-attention-store.js";
 import {
+  addMessage,
   type ConversationRow,
+  createConversation,
+  deleteConversation,
   forkConversation as forkConversationInStore,
   getConversation,
   getDisplayMetaForConversations,
@@ -62,11 +66,13 @@ import { resolveConversationId } from "../memory/conversation-key-store.js";
 import {
   countConversations,
   listConversations,
+  listConversationsByTitlePrefix,
   listPinnedConversations,
 } from "../memory/conversation-queries.js";
 import type { ExternalConversationBinding } from "../memory/external-conversation-store.js";
 import * as externalConversationStore from "../memory/external-conversation-store.js";
 import { listGroups } from "../memory/group-crud.js";
+import { enqueueMemoryJob } from "../memory/jobs-store.js";
 import { resolveStreamingTranscriber } from "../providers/speech-to-text/resolve.js";
 import {
   consumeCallback,
@@ -206,6 +212,7 @@ import {
   handlePairingStatus,
   pairingRouteDefinitions,
 } from "./routes/pairing-routes.js";
+import { playgroundRouteDefinitions } from "./routes/playground/index.js";
 import { profilerRouteDefinitions } from "./routes/profiler-routes.js";
 import { recordingRouteDefinitions } from "./routes/recording-routes.js";
 import { scheduleRouteDefinitions } from "./routes/schedule-routes.js";
@@ -223,7 +230,6 @@ import { ttsRouteDefinitions } from "./routes/tts-routes.js";
 import { upgradeBroadcastRouteDefinitions } from "./routes/upgrade-broadcast-routes.js";
 import { usageRouteDefinitions } from "./routes/usage-routes.js";
 import { userRouteDefinitions } from "./routes/user-routes.js";
-import { watchRouteDefinitions } from "./routes/watch-routes.js";
 import { workItemRouteDefinitions } from "./routes/work-items-routes.js";
 import { workspaceCommitRouteDefinitions } from "./routes/workspace-commit-routes.js";
 import { workspaceRouteDefinitions } from "./routes/workspace-routes.js";
@@ -356,7 +362,6 @@ export class RuntimeHttpServer {
   private getSkillContext?: RuntimeHttpServerOptions["getSkillContext"];
   private conversationManagementDeps?: RuntimeHttpServerOptions["conversationManagementDeps"];
   private getModelSetContext?: RuntimeHttpServerOptions["getModelSetContext"];
-  private getWatchDeps?: RuntimeHttpServerOptions["getWatchDeps"];
   private getRecordingDeps?: RuntimeHttpServerOptions["getRecordingDeps"];
   private getCesClient?: RuntimeHttpServerOptions["getCesClient"];
   private onProviderCredentialsChanged?: RuntimeHttpServerOptions["onProviderCredentialsChanged"];
@@ -381,7 +386,6 @@ export class RuntimeHttpServer {
     this.getSkillContext = options.getSkillContext;
     this.conversationManagementDeps = options.conversationManagementDeps;
     this.getModelSetContext = options.getModelSetContext;
-    this.getWatchDeps = options.getWatchDeps;
     this.getRecordingDeps = options.getRecordingDeps;
     this.getCesClient = options.getCesClient;
     this.onProviderCredentialsChanged = options.onProviderCredentialsChanged;
@@ -1066,6 +1070,12 @@ export class RuntimeHttpServer {
     // tokens minted by a session manager).
     const skillMatch = matchSkillRoute(path, req.method);
     if (skillMatch) {
+      if (skillMatch.kind === "methodMismatch") {
+        return new Response("Method Not Allowed", {
+          status: 405,
+          headers: { Allow: skillMatch.allow.join(", ") },
+        });
+      }
       return await skillMatch.route.handler(req, skillMatch.match);
     }
 
@@ -1851,6 +1861,21 @@ export class RuntimeHttpServer {
               404,
             );
           try {
+            // Snapshot current state to detect whether the seen cursor
+            // actually advances (avoids emitting on no-op signals).
+            // Only consider a conversation "unseen" when a latest assistant
+            // message exists and the seen cursor is behind it — matching
+            // the hasUnseenLatestAssistantMessage logic in buildAssistantAttention.
+            const priorState = getAttentionStateByConversationIds([
+              conversationId,
+            ]).get(conversationId);
+            const wasUnseen =
+              priorState != null &&
+              priorState.latestAssistantMessageAt != null &&
+              (priorState.lastSeenAssistantMessageAt == null ||
+                priorState.lastSeenAssistantMessageAt <
+                  priorState.latestAssistantMessageAt);
+
             recordConversationSeenSignal({
               conversationId,
               sourceChannel: (body.sourceChannel as string) ?? "vellum",
@@ -1863,6 +1888,21 @@ export class RuntimeHttpServer {
               metadata: body.metadata as Record<string, unknown> | undefined,
               observedAt: body.observedAt as number | undefined,
             });
+            if (wasUnseen) {
+              assistantEventHub
+                .publish(
+                  buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
+                    type: "conversation_list_invalidated",
+                    reason: "seen_changed",
+                  }),
+                )
+                .catch((err) => {
+                  log.warn(
+                    { err },
+                    "Failed to publish conversation_list_invalidated (seen_changed)",
+                  );
+                });
+            }
             return Response.json({ ok: true });
           } catch (err) {
             log.error(
@@ -1894,7 +1934,22 @@ export class RuntimeHttpServer {
               404,
             );
           try {
-            markConversationUnread(conversationId);
+            const changed = markConversationUnread(conversationId);
+            if (changed) {
+              assistantEventHub
+                .publish(
+                  buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
+                    type: "conversation_list_invalidated",
+                    reason: "seen_changed",
+                  }),
+                )
+                .catch((err) => {
+                  log.warn(
+                    { err },
+                    "Failed to publish conversation_list_invalidated (seen_changed)",
+                  );
+                });
+            }
             return Response.json({ ok: true });
           } catch (err) {
             if (err instanceof UserError) {
@@ -1944,6 +1999,76 @@ export class RuntimeHttpServer {
         suggestionInFlight: this.suggestionInFlight,
         getHeartbeatService: this.getHeartbeatService,
       }),
+      ...playgroundRouteDefinitions({
+        getConversationById: async (id) => {
+          // Gate on DB existence first so genuinely-missing IDs return
+          // `undefined` (preserving the route handlers' 404 path) rather
+          // than triggering `getOrCreateConversation`'s create branch and
+          // masking the not-found case. For existing-but-not-loaded rows
+          // (e.g. freshly seeded by `POST /playground/seed-conversation`),
+          // hydrate the in-memory `Conversation` on demand so conv-scoped
+          // playground routes work without first opening the conversation
+          // in the main window.
+          if (!getConversation(id)) return undefined;
+          const sendDeps = this.sendMessageDeps;
+          if (!sendDeps) {
+            // Fall back to the in-memory active map when the daemon hasn't
+            // wired the hydration-capable accessor (e.g. unit tests).
+            const s = this.findConversation?.(id);
+            if (!s || !("abort" in s)) return undefined;
+            return s as import("../daemon/conversation.js").Conversation;
+          }
+          return sendDeps.getOrCreateConversation(id);
+        },
+        isPlaygroundEnabled: () =>
+          isAssistantFeatureFlagEnabled("compaction-playground", getConfig()),
+        listConversationsByTitlePrefix: (prefix) =>
+          listConversationsByTitlePrefix(prefix),
+        deleteConversationById: (id) => {
+          // Existence check first so we can report `false` for missing rows
+          // — `deleteConversation` always returns a result object even when
+          // no row matched.
+          if (!getConversation(id)) return false;
+          // Mirror the canonical DELETE /v1/conversations/:id handler in
+          // conversation-management-routes.ts: tear down the in-memory
+          // Conversation first (so a running agent loop can't write to a
+          // deleted row and trip FK constraints), then drop the DB row,
+          // then enqueue Qdrant vector cleanup for the returned segment
+          // and summary IDs. Without this, seeded-then-deleted playground
+          // conversations leak vectors and zombie Conversation objects.
+          if (this.findConversation?.(id)) {
+            this.conversationManagementDeps?.destroyConversation(id);
+          }
+          const deleted = deleteConversation(id);
+          for (const segId of deleted.segmentIds) {
+            enqueueMemoryJob("delete_qdrant_vectors", {
+              targetType: "segment",
+              targetId: segId,
+            });
+          }
+          for (const summaryId of deleted.deletedSummaryIds) {
+            enqueueMemoryJob("delete_qdrant_vectors", {
+              targetType: "summary",
+              targetId: summaryId,
+            });
+          }
+          return true;
+        },
+        createConversation: async (title) => {
+          const row = createConversation({ title });
+          return { id: row.id };
+        },
+        addMessage: async (conversationId, role, contentJson, options) => {
+          const persisted = await addMessage(
+            conversationId,
+            role,
+            contentJson,
+            undefined,
+            options,
+          );
+          return { id: persisted.id };
+        },
+      }),
       ...globalSearchRouteDefinitions(),
       ...approvalRouteDefinitions(),
       ...hostBashRouteDefinitions(),
@@ -1981,11 +2106,6 @@ export class RuntimeHttpServer {
       ...oauthAppsRouteDefinitions(),
       ...attachmentRouteDefinitions(),
 
-      ...(this.getWatchDeps
-        ? watchRouteDefinitions({
-            getWatchDeps: this.getWatchDeps,
-          })
-        : []),
       ...(this.getRecordingDeps
         ? recordingRouteDefinitions({
             getRecordingDeps: this.getRecordingDeps,

package/src/runtime/http-types.ts

@@ -2,10 +2,18 @@
  * Shared types for the runtime HTTP server and its route handlers.
  */
 import type { ChannelId, InterfaceId } from "../channels/types.js";
+import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { CesClient } from "../credential-execution/client.js";
 import type { Conversation } from "../daemon/conversation.js";
 import type { TrustContext } from "../daemon/conversation-runtime-assembly.js";
-import type { ConversationCreateOptions } from "../daemon/handlers/shared.js";
+import type {
+  ConversationCreateOptions,
+  SlackInboundMessageMetadata,
+} from "../daemon/handlers/shared.js";
+
+// Re-export so route modules (background-dispatch, etc.) can pull the type
+// from the runtime barrel without reaching into daemon internals.
+export type { SlackInboundMessageMetadata };
 import type { SkillOperationContext } from "../daemon/handlers/skills.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import type {
@@ -132,6 +140,20 @@ export interface RuntimeMessageConversationOptions {
   commandIntent?: { type: string; payload?: string; languageCode?: string };
   /** Optional callback to receive real-time agent loop events (text deltas, tool starts, etc.). */
   onEvent?: (msg: ServerMessage) => void;
+  /**
+   * Optional LLM call-site identifier. Channel ingress and other inbound paths
+   * may pass this so the daemon's per-call provider config picks up the right
+   * profile via `resolveCallSiteConfig`. PRs 7-11 wire individual call-site
+   * literals into specific call paths.
+   */
+  callSite?: LLMCallSite;
+  /**
+   * Slack inbound metadata captured at the channel ingress boundary. When
+   * present (and the turn channel resolves to Slack), persistence writes a
+   * `slackMeta` sub-object into the message's `metadata` JSON for the
+   * chronological renderer to consume.
+   */
+  slackInbound?: SlackInboundMessageMetadata;
 }
 
 export type MessageProcessor = (
@@ -226,8 +248,6 @@ export interface RuntimeHttpServerOptions {
   conversationManagementDeps?: ConversationManagementDeps;
   /** Lazy factory for model config set context (conversation eviction, config reload suppression). */
   getModelSetContext?: () => import("../daemon/handlers/config-model.js").ModelSetContext;
-  /** Provider for watch observation dependencies (watch routes). */
-  getWatchDeps?: () => import("./routes/watch-routes.js").WatchDeps;
   /** Provider for recording dependencies (recording routes). */
   getRecordingDeps?: () => import("./routes/recording-routes.js").RecordingDeps;
   /** Accessor for the CES client, used to push API key updates to CES after hatch. */