@vellumai/assistant 0.8.4 → 0.8.6

package/src/api/events/generation-handoff.ts

@@ -0,0 +1,41 @@
+/**
+ * `generation_handoff` SSE event.
+ *
+ * Emitted when an assistant turn finishes and the daemon's agent loop
+ * yields control to the next queued user message in the same
+ * conversation. Functionally similar to `message_complete` — same
+ * attachment payload, same `messageId` semantics — but tells the
+ * client that another turn is about to begin without an intervening
+ * idle state, so the UI can keep the activity indicator on.
+ *
+ * `queuedCount` is the depth of the conversation's pending-message
+ * queue at handoff time (not including the just-finished turn). Used
+ * by the client to size queued-message UI affordances.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+import { AssistantOutboundAttachmentSchema } from "./assistant-outbound-attachment.js";
+
+export const GenerationHandoffEventSchema = z
+  .object({
+    type: z.literal("generation_handoff"),
+    conversationId: z.string().optional(),
+    /** Daemon request id of the just-finished turn — correlates with
+     *  the request id surfaced by the inbound user message. */
+    requestId: z.string().optional(),
+    /** Depth of the pending-message queue at handoff time. */
+    queuedCount: z.number(),
+    /** Database row id of the just-finished assistant turn. */
+    messageId: z.string().optional(),
+    attachments: z.array(AssistantOutboundAttachmentSchema).optional(),
+    attachmentWarnings: z.array(z.string()).optional(),
+  })
+  .strict();
+
+export type GenerationHandoffEvent = z.infer<
+  typeof GenerationHandoffEventSchema
+>;

package/src/api/events/message-complete.ts

@@ -0,0 +1,42 @@
+/**
+ * `message_complete` SSE event.
+ *
+ * Marks the end of an assistant turn — emitted once per turn after the
+ * final `assistant_text_delta` (or as the sole turn event for canned
+ * one-shot messages, recording-handler echoes, slash-command outputs,
+ * and aux notifier injections that don't stream text). Clients gate
+ * task-completion side effects on this event.
+ *
+ * `messageId` is the database row id of the completed assistant turn;
+ * shared with the `assistant_text_delta` chunks that streamed it. May
+ * be absent on synthetic completions that don't bind to a persisted
+ * row.
+ *
+ * `source` distinguishes a real main-turn completion from auxiliary
+ * notifier injections (call transcripts, call summaries, watch
+ * notifier outputs). Clients gate the task-complete sound and similar
+ * side effects on `source !== "aux"`. Absent is treated as `"main"`
+ * for backwards compatibility.
+ *
+ * Canonical wire-contract source. Daemon code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+import { AssistantOutboundAttachmentSchema } from "./assistant-outbound-attachment.js";
+
+export const MessageCompleteEventSchema = z
+  .object({
+    type: z.literal("message_complete"),
+    messageId: z.string().optional(),
+    conversationId: z.string().optional(),
+    source: z.enum(["main", "aux"]).optional(),
+    attachments: z.array(AssistantOutboundAttachmentSchema).optional(),
+    /** Soft warnings produced while resolving attachments (e.g. format
+     *  conversions, size truncations). Display-only — not blocking. */
+    attachmentWarnings: z.array(z.string()).optional(),
+  })
+  .strict();
+
+export type MessageCompleteEvent = z.infer<typeof MessageCompleteEventSchema>;

package/src/api/events/open-url.ts

@@ -0,0 +1,30 @@
+/**
+ * `open_url` SSE event.
+ *
+ * Sent by the assistant when it wants the client to open a URL — OAuth
+ * authorization popups, system-settings deep links, and browser hand-offs
+ * from tool execution. The web client routes the URL through same-origin
+ * detection, an OAuth popup, or `window.open`, depending on the URL shape.
+ *
+ * Canonical wire-contract source. Assistant code imports the type directly
+ * from this file; external consumers import via `@vellumai/assistant-api`.
+ *
+ * `conversationId` is optional: emit sites with a conversation context
+ * (OAuth orchestrator, conversation-scoped tools) should set it on the
+ * inner message; CLI signal-file broadcasts and other global flows omit
+ * it. The parser never grafts the envelope-level routing key onto the
+ * typed event — the schema is the contract.
+ */
+
+import { z } from "zod";
+
+export const OpenUrlEventSchema = z
+  .object({
+    type: z.literal("open_url"),
+    url: z.string().min(1),
+    title: z.string().optional(),
+    conversationId: z.string().optional(),
+  })
+  .strict();
+
+export type OpenUrlEvent = z.infer<typeof OpenUrlEventSchema>;

package/src/api/events/relationship-state-updated.ts

@@ -0,0 +1,25 @@
+/**
+ * `relationship_state_updated` SSE event.
+ *
+ * Broadcast by the daemon after a successful write of
+ * `relationship-state.json` to disk. Subscribers refetch
+ * `GET /v1/home/state` to read the new state — payload here just
+ * carries the new `updatedAt` for cache-tag comparison.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const RelationshipStateUpdatedEventSchema = z
+  .object({
+    type: z.literal("relationship_state_updated"),
+    updatedAt: z.string(),
+  })
+  .strict();
+
+export type RelationshipStateUpdatedEvent = z.infer<
+  typeof RelationshipStateUpdatedEventSchema
+>;

package/src/api/events/tool-use-start.ts

@@ -0,0 +1,32 @@
+/**
+ * `tool_use_start` SSE event.
+ *
+ * Emitted by the daemon's agent loop when a tool invocation begins —
+ * carries the tool name, the structured input the model produced, and
+ * correlation ids for the conversation, the message, and the tool_use
+ * block itself.
+ *
+ * `messageId` is the database row id of the assistant message that owns
+ * this tool_use block; absent on streams produced by older daemons that
+ * pre-date the anchor protocol. Same semantics as
+ * `AssistantTextDeltaEvent.messageId`.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const ToolUseStartEventSchema = z
+  .object({
+    type: z.literal("tool_use_start"),
+    toolName: z.string(),
+    input: z.record(z.string(), z.unknown()),
+    toolUseId: z.string().optional(),
+    messageId: z.string().optional(),
+    conversationId: z.string().optional(),
+  })
+  .strict();
+
+export type ToolUseStartEvent = z.infer<typeof ToolUseStartEventSchema>;

package/src/api/index.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+
+import { AssistantTextDeltaEventSchema } from "./events/assistant-text-delta.js";
+import { AssistantTurnStartEventSchema } from "./events/assistant-turn-start.js";
+import { DocumentCommentCreatedEventSchema } from "./events/document-comment-created.js";
+import { DocumentCommentDeletedEventSchema } from "./events/document-comment-deleted.js";
+import { DocumentCommentReopenedEventSchema } from "./events/document-comment-reopened.js";
+import { DocumentCommentResolvedEventSchema } from "./events/document-comment-resolved.js";
+import { GenerationCancelledEventSchema } from "./events/generation-cancelled.js";
+import { GenerationHandoffEventSchema } from "./events/generation-handoff.js";
+import { MessageCompleteEventSchema } from "./events/message-complete.js";
+import { OpenUrlEventSchema } from "./events/open-url.js";
+import { RelationshipStateUpdatedEventSchema } from "./events/relationship-state-updated.js";
+import { ToolUseStartEventSchema } from "./events/tool-use-start.js";
+
+export { CALL_SITE_SYNTHETIC_AGENT_ERROR_MESSAGE } from "./constants/call-sites.js";
+export {
+  type AssistantOutboundAttachment,
+  AssistantOutboundAttachmentSchema,
+} from "./events/assistant-outbound-attachment.js";
+export {
+  type AssistantTextDeltaEvent,
+  AssistantTextDeltaEventSchema,
+} from "./events/assistant-text-delta.js";
+export {
+  type AssistantTurnStartEvent,
+  AssistantTurnStartEventSchema,
+} from "./events/assistant-turn-start.js";
+export {
+  type DocumentCommentCreatedEvent,
+  DocumentCommentCreatedEventSchema,
+} from "./events/document-comment-created.js";
+export {
+  type DocumentCommentDeletedEvent,
+  DocumentCommentDeletedEventSchema,
+} from "./events/document-comment-deleted.js";
+export {
+  type DocumentCommentReopenedEvent,
+  DocumentCommentReopenedEventSchema,
+} from "./events/document-comment-reopened.js";
+export {
+  type DocumentCommentResolvedEvent,
+  DocumentCommentResolvedEventSchema,
+} from "./events/document-comment-resolved.js";
+export {
+  type GenerationCancelledEvent,
+  GenerationCancelledEventSchema,
+} from "./events/generation-cancelled.js";
+export {
+  type GenerationHandoffEvent,
+  GenerationHandoffEventSchema,
+} from "./events/generation-handoff.js";
+export {
+  type MessageCompleteEvent,
+  MessageCompleteEventSchema,
+} from "./events/message-complete.js";
+export { type OpenUrlEvent, OpenUrlEventSchema } from "./events/open-url.js";
+export {
+  type RelationshipStateUpdatedEvent,
+  RelationshipStateUpdatedEventSchema,
+} from "./events/relationship-state-updated.js";
+export {
+  type ToolUseStartEvent,
+  ToolUseStartEventSchema,
+} from "./events/tool-use-start.js";
+export {
+  type LlmContextResponse,
+  LlmContextResponseSchema,
+} from "./responses/llm-context-response.js";
+export {
+  type LLMCallSummary,
+  LLMCallSummarySchema,
+  type LLMContextSection,
+  LLMContextSectionSchema,
+  type LLMRequestLogEntry,
+  LLMRequestLogEntrySchema,
+} from "./responses/llm-request-log-entry.js";
+export {
+  type MemoryCandidate,
+  MemoryCandidateSchema,
+  type MemoryDegradation,
+  MemoryDegradationSchema,
+  type MemoryRecallLog,
+  MemoryRecallLogSchema,
+} from "./responses/memory-recall-log.js";
+export {
+  type MemoryV2ActivationLog,
+  MemoryV2ActivationLogSchema,
+  type MemoryV2ConceptRow,
+  MemoryV2ConceptRowSchema,
+  type MemoryV2ConfigSnapshot,
+  MemoryV2ConfigSnapshotSchema,
+} from "./responses/memory-v2-activation-log.js";
+
+/**
+ * Canonical SSE event schema for the assistant runtime.
+ *
+ * Discriminated union over the `type` field. Each member is the
+ * canonical wire-contract schema for a single event type, defined
+ * alongside the daemon code that emits it. Consumers (web client,
+ * gateway, evals) parse incoming events with this single schema
+ * rather than maintaining their own dispatch table.
+ *
+ * Add new events by exporting their schema from `./events/` and
+ * appending them to the union below. See `./README.md` for the full
+ * migration recipe.
+ */
+export const AssistantEventSchema = z.discriminatedUnion("type", [
+  AssistantTextDeltaEventSchema,
+  AssistantTurnStartEventSchema,
+  DocumentCommentCreatedEventSchema,
+  DocumentCommentDeletedEventSchema,
+  DocumentCommentReopenedEventSchema,
+  DocumentCommentResolvedEventSchema,
+  GenerationCancelledEventSchema,
+  GenerationHandoffEventSchema,
+  MessageCompleteEventSchema,
+  OpenUrlEventSchema,
+  RelationshipStateUpdatedEventSchema,
+  ToolUseStartEventSchema,
+]);
+
+/**
+ * Inferred TypeScript union for every event currently covered by
+ * `AssistantEventSchema`. Consumers should reference this single type
+ * rather than re-listing the individual member types — as each new
+ * event migrates into the schema, it appears here automatically.
+ */
+export type AssistantEvent = z.infer<typeof AssistantEventSchema>;

package/src/api/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@vellumai/assistant-api",
+  "version": "0.0.0-source",
+  "description": "Public API surface for consumers of the assistant API (web client, gateway, evals, etc.).",
+  "type": "module",
+  "private": true,
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/src/api/responses/llm-context-response.ts

@@ -0,0 +1,39 @@
+/**
+ * Wire contract for the full payload returned by
+ * `GET /v1/conversations/llm-context`. Hydrates the Overview / Memory
+ * / Prompt / Response tabs from a single fetch.
+ *
+ * Canonical wire-contract source. Assistant code imports the types
+ * directly from this file via relative paths; external consumers
+ * (web client, gateway, evals) import via `@vellumai/assistant-api`.
+ *
+ * The route is reachable on web through the gateway's runtime-proxy
+ * wildcard at
+ * `/v1/assistants/{assistantId}/conversations/llm-context/`. The
+ * response is built in `assistant/src/runtime/routes/conversation-query-routes.ts`.
+ *
+ * `conversationTotalEstimatedCostUsd` is the running total of priced
+ * LLM costs across every call in the conversation, sourced from the
+ * daemon's `conversations.total_estimated_cost` column. The field is
+ * optional because older daemons predate it — treat undefined / null
+ * as "unavailable".
+ */
+
+import { z } from "zod";
+
+import { LLMRequestLogEntrySchema } from "./llm-request-log-entry.js";
+import { MemoryRecallLogSchema } from "./memory-recall-log.js";
+import { MemoryV2ActivationLogSchema } from "./memory-v2-activation-log.js";
+
+export const LlmContextResponseSchema = z.object({
+  messageId: z.string().nullish(),
+  conversationKey: z.string().nullish(),
+  conversationId: z.string().nullish(),
+  conversationKind: z.string(),
+  conversationTotalEstimatedCostUsd: z.number().nullish(),
+  logs: z.array(LLMRequestLogEntrySchema),
+  memoryRecall: MemoryRecallLogSchema.nullable(),
+  memoryV2Activation: MemoryV2ActivationLogSchema.nullable(),
+});
+
+export type LlmContextResponse = z.infer<typeof LlmContextResponseSchema>;

package/src/api/responses/llm-request-log-entry.ts

@@ -0,0 +1,93 @@
+/**
+ * Wire contract for a single LLM request log row, as returned by
+ * `GET /v1/conversations/llm-context`. Hydrates each call rail entry
+ * + tab in the inspector.
+ *
+ * Canonical wire-contract source. Assistant code imports the types
+ * directly from this file via relative paths; external consumers (web
+ * client, gateway, evals) import via `@vellumai/assistant-api`.
+ *
+ * The route is implemented in
+ * `assistant/src/runtime/routes/conversation-query-routes.ts` and the
+ * row shape is constructed by `normalizeLlmContextLog` there. Keep the
+ * schemas here aligned with that constructor — the schema IS the
+ * contract; types are `z.infer`-derived.
+ *
+ * `requestPayload` / `responsePayload` are always `null` on the list
+ * endpoint; raw JSON is fetched lazily through
+ * `/v1/llm-request-logs/{logId}/payload`.
+ */
+
+import { z } from "zod";
+
+/**
+ * Provider-normalized summary attached to each request log. `null` /
+ * missing fields are common — formatters fall back to a shared
+ * "Unavailable" placeholder.
+ *
+ * `durationMs` isn't in the macOS reference shape today but the daemon
+ * already populates it for some providers — surfaced when present so
+ * web debugging gets the extra signal.
+ */
+export const LLMCallSummarySchema = z.object({
+  provider: z.string().nullish(),
+  model: z.string().nullish(),
+  status: z.string().nullish(),
+  inputTokens: z.number().nullish(),
+  outputTokens: z.number().nullish(),
+  cacheCreationInputTokens: z.number().nullish(),
+  cacheReadInputTokens: z.number().nullish(),
+  stopReason: z.string().nullish(),
+  requestMessageCount: z.number().nullish(),
+  requestToolCount: z.number().nullish(),
+  responseMessageCount: z.number().nullish(),
+  responseToolCallCount: z.number().nullish(),
+  responsePreview: z.string().nullish(),
+  toolCallNames: z.array(z.string()).nullish(),
+  estimatedCostUsd: z.number().nullish(),
+  durationMs: z.number().nullish(),
+});
+
+export type LLMCallSummary = z.infer<typeof LLMCallSummarySchema>;
+
+/**
+ * A single normalized request- or response-side section. The daemon
+ * splits a provider payload into kind-tagged blocks before returning;
+ * each block becomes one card in the Prompt / Response tabs.
+ */
+export const LLMContextSectionSchema = z.object({
+  kind: z.string(),
+  label: z.string().nullish(),
+  role: z.string().nullish(),
+  text: z.string().nullish(),
+  toolName: z.string().nullish(),
+  data: z.unknown().optional(),
+  language: z.string().nullish(),
+});
+
+export type LLMContextSection = z.infer<typeof LLMContextSectionSchema>;
+
+/**
+ * One LLM request log row.
+ *
+ * `callSite` is the logical call site that produced this row —
+ * `mainAgent`, `compactionAgent`, `syntheticAgentErrorMessage`, etc.
+ * `null` on pre-migration-264 rows or callers that hadn't been wired
+ * through yet. The inspector branches on this value alone to
+ * distinguish real LLM calls from synthetic error-message rows. See
+ * `../constants/call-sites.ts` for the canonical identifiers.
+ */
+export const LLMRequestLogEntrySchema = z.object({
+  id: z.string(),
+  createdAt: z.number(),
+  requestPayload: z.null(),
+  responsePayload: z.null(),
+  provider: z.string().nullish(),
+  summary: LLMCallSummarySchema.nullish(),
+  requestSections: z.array(LLMContextSectionSchema).nullish(),
+  responseSections: z.array(LLMContextSectionSchema).nullish(),
+  agentLoopExitReason: z.string().nullish(),
+  callSite: z.string().nullish(),
+});
+
+export type LLMRequestLogEntry = z.infer<typeof LLMRequestLogEntrySchema>;

package/src/api/responses/memory-recall-log.ts

@@ -0,0 +1,65 @@
+/**
+ * Wire contract for the memory-recall log surfaced in the inspector's
+ * Memory tab. Mirrors `MemoryRecallLog` from
+ * `assistant/src/memory/memory-recall-log-store.ts`.
+ *
+ * Canonical wire-contract source. Assistant code imports the types
+ * directly from this file via relative paths; external consumers
+ * (web client, gateway, evals) import via `@vellumai/assistant-api`.
+ *
+ * Returned as part of `LlmContextResponse` — see
+ * `./llm-context-response.ts`.
+ */
+
+import { z } from "zod";
+
+/**
+ * A single recalled memory candidate, normalized by the daemon from
+ * the SSE-event format into inspector format.
+ */
+export const MemoryCandidateSchema = z.object({
+  nodeId: z.string(),
+  score: z.number(),
+  semanticSimilarity: z.number(),
+  recencyBoost: z.number(),
+  type: z.string().optional(),
+});
+
+export type MemoryCandidate = z.infer<typeof MemoryCandidateSchema>;
+
+/**
+ * Degradation details when memory recall ran in a degraded mode.
+ */
+export const MemoryDegradationSchema = z.object({
+  reason: z.string(),
+  semanticUnavailable: z.boolean(),
+  fallbackSources: z.array(z.string()),
+});
+
+export type MemoryDegradation = z.infer<typeof MemoryDegradationSchema>;
+
+/**
+ * Memory recall log shape.
+ */
+export const MemoryRecallLogSchema = z.object({
+  enabled: z.boolean(),
+  degraded: z.boolean(),
+  provider: z.string().nullable(),
+  model: z.string().nullable(),
+  degradation: MemoryDegradationSchema.nullable(),
+  semanticHits: z.number().nullish(),
+  mergedCount: z.number().nullish(),
+  selectedCount: z.number().nullish(),
+  tier1Count: z.number().nullish(),
+  tier2Count: z.number().nullish(),
+  hybridSearchLatencyMs: z.number().nullish(),
+  sparseVectorUsed: z.boolean().nullish(),
+  injectedTokens: z.number().nullish(),
+  latencyMs: z.number().nullish(),
+  topCandidates: z.array(MemoryCandidateSchema),
+  injectedText: z.string().nullable(),
+  reason: z.string().nullable(),
+  queryContext: z.string().nullable(),
+});
+
+export type MemoryRecallLog = z.infer<typeof MemoryRecallLogSchema>;

package/src/api/responses/memory-v2-activation-log.ts

@@ -0,0 +1,78 @@
+/**
+ * Wire contract for the memory v2 activation log surfaced in the
+ * inspector's Memory tab. Mirrors the return value of
+ * `getMemoryV2ActivationLogByMessageIds` in
+ * `assistant/src/memory/memory-v2-activation-log-store.ts`.
+ *
+ * Canonical wire-contract source. Assistant code imports the types
+ * directly from this file via relative paths; external consumers
+ * (web client, gateway, evals) import via `@vellumai/assistant-api`.
+ *
+ * Returned as part of `LlmContextResponse` — see
+ * `./llm-context-response.ts`.
+ *
+ * Note: daemon emits the `config` block with snake_case keys; the
+ * schema below preserves that on the wire.
+ */
+
+import { z } from "zod";
+
+/**
+ * One concept row in the V2 activation log. Mirrors
+ * `MemoryV2ConceptRowRecord` from
+ * `assistant/src/memory/memory-v2-activation-log-store.ts`.
+ *
+ * `source` and `status` are open-ended strings on the wire — the
+ * daemon emits known values like `prior_state`, `ann_top50`, `both`
+ * for `source` and `in_context`, `injected`, `not_injected`,
+ * `page_missing` for `status`, but the schema stays permissive so a
+ * new daemon value doesn't break parsing on the FE.
+ */
+export const MemoryV2ConceptRowSchema = z.object({
+  slug: z.string(),
+  finalActivation: z.number(),
+  ownActivation: z.number(),
+  priorActivation: z.number(),
+  simUser: z.number(),
+  simAssistant: z.number(),
+  simNow: z.number(),
+  simUserRerankBoost: z.number().optional(),
+  simAssistantRerankBoost: z.number().optional(),
+  inRerankPool: z.boolean().optional(),
+  spreadContribution: z.number(),
+  source: z.string(),
+  status: z.string(),
+});
+
+export type MemoryV2ConceptRow = z.infer<typeof MemoryV2ConceptRowSchema>;
+
+/**
+ * Config snapshot used when the V2 activation ran. Mirrors
+ * `MemoryV2ConfigSnapshot` (daemon uses snake_case keys).
+ */
+export const MemoryV2ConfigSnapshotSchema = z.object({
+  d: z.number(),
+  c_user: z.number(),
+  c_assistant: z.number(),
+  c_now: z.number(),
+  k: z.number(),
+  hops: z.number(),
+  top_k: z.number(),
+  epsilon: z.number(),
+});
+
+export type MemoryV2ConfigSnapshot = z.infer<
+  typeof MemoryV2ConfigSnapshotSchema
+>;
+
+/**
+ * Memory v2 activation log shape.
+ */
+export const MemoryV2ActivationLogSchema = z.object({
+  turn: z.number(),
+  mode: z.string(),
+  concepts: z.array(MemoryV2ConceptRowSchema),
+  config: MemoryV2ConfigSnapshotSchema,
+});
+
+export type MemoryV2ActivationLog = z.infer<typeof MemoryV2ActivationLogSchema>;