@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/api/responses/conversation-message.ts

@@ -0,0 +1,374 @@
+/**
+ * Wire contract for the conversation history / messages endpoints.
+ *
+ *   - `GET /v1/assistants/:id/messages` → `{ messages: ConversationMessage[] }`
+ *   - `POST /v1/messages` send acks echo an `assistantMessage: ConversationMessage`
+ *
+ * Holds the canonical history-row shape produced by the daemon's
+ * `renderHistoryContent` + conversation-routes serializer and consumed by
+ * every history client (web, CLI, evals). Defining it here — rather than
+ * re-declaring it in the daemon's `http-types.ts` and again in the web's
+ * `chat/api/messages.ts` — means the producer and all consumers derive from
+ * one source and cannot drift.
+ *
+ * The arrays use a positional encoding:
+ *   - `contentOrder` entries are `"<type>:<index>"` strings (e.g. `"text:0"`,
+ *     `"thinking:1"`, `"tool:0"`, `"surface:0"`, `"attachment:0"`). The index
+ *     points into the matching array below.
+ *   - `textSegments`, `thinkingSegments` are plain string arrays.
+ *   - `toolCalls`, `surfaces`, `attachments` are object arrays.
+ *
+ * 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`.
+ */
+
+import { z } from "zod";
+
+import {
+  AllowlistOptionSchema,
+  DirectoryScopeOptionSchema,
+  ScopeOptionSchema,
+} from "../events/confirmation-request.js";
+import { ToolActivityMetadataSchema } from "../events/tool-result.js";
+
+// ---------------------------------------------------------------------------
+// Attachment metadata
+// ---------------------------------------------------------------------------
+
+/** Structured attachment metadata attached to a history row. */
+export const ConversationMessageAttachmentSchema = z.object({
+  id: z.string(),
+  filename: z.string(),
+  mimeType: z.string(),
+  sizeBytes: z.number(),
+  kind: z.string(),
+  /** Base64-encoded file data. Only populated for images on history reload. */
+  data: z.string().optional(),
+  /** Base64-encoded thumbnail, when one was generated. */
+  thumbnailData: z.string().optional(),
+  /** True when the attachment bytes are backed by a file on disk. */
+  fileBacked: z.boolean().optional(),
+});
+export type ConversationMessageAttachment = z.infer<
+  typeof ConversationMessageAttachmentSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Tool call
+// ---------------------------------------------------------------------------
+
+const RiskScopeOptionSchema = z.object({
+  pattern: z.string(),
+  label: z.string(),
+});
+
+const RiskAllowlistOptionSchema = z.object({
+  label: z.string(),
+  description: z.string(),
+  pattern: z.string(),
+});
+
+const RiskDirectoryScopeOptionSchema = z.object({
+  scope: z.string(),
+  label: z.string(),
+});
+
+/**
+ * In-flight permission prompt awaiting a user decision, mirrored onto a
+ * history tool call so a cold reconnect (or a conversation reopened after the
+ * event-buffer window has elapsed) can restore the inline confirmation card
+ * without replaying the live `confirmation_request` SSE event.
+ *
+ * The daemon stamps this at render time by consulting the in-memory
+ * `pending-interactions` registry (the authoritative store of unresolved
+ * prompts) — it is not persisted to the database, so it appears only while the
+ * prompt is genuinely outstanding and disappears once the interaction
+ * resolves. The shape mirrors the `confirmation_request` event the live path
+ * delivers, so both paths hydrate the same client state.
+ */
+export const PendingToolConfirmationSchema = z.object({
+  requestId: z.string(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  toolName: z.string().optional(),
+  riskLevel: z.string().optional(),
+  riskReason: z.string().optional(),
+  input: z.record(z.string(), z.unknown()).optional(),
+  allowlistOptions: z.array(AllowlistOptionSchema).optional(),
+  scopeOptions: z.array(ScopeOptionSchema).optional(),
+  directoryScopeOptions: z.array(DirectoryScopeOptionSchema).optional(),
+  persistentDecisionsAllowed: z.boolean().optional(),
+});
+export type PendingToolConfirmation = z.infer<
+  typeof PendingToolConfirmationSchema
+>;
+
+/**
+ * Closed set of confirmation outcomes recorded for a tool call. The daemon
+ * only ever persists one of these three values (the outcome map is gated to
+ * them in `conversation-agent-loop.ts`), so the wire carries the closed enum
+ * rather than a free string and clients consume it without re-narrowing.
+ */
+export const ConfirmationDecisionSchema = z.enum([
+  "approved",
+  "denied",
+  "timed_out",
+]);
+export type ConfirmationDecision = z.infer<typeof ConfirmationDecisionSchema>;
+
+/**
+ * A single tool call rendered into a history row. Mirrors the object the
+ * daemon's `renderHistoryContent` emits; `contentOrder` references it as
+ * `tool:N` where `N` indexes into `toolCalls`.
+ */
+export const ConversationMessageToolCallSchema = z.object({
+  /** Stable tool-call id: the provider `tool_use` id, or a synthesized positional id. Guaranteed present as of daemon v0.8.8; optional for skew with older daemons. */
+  id: z.string().optional(),
+  name: z.string(),
+  input: z.record(z.string(), z.unknown()),
+  result: z.string().optional(),
+  isError: z.boolean().optional(),
+  /** Base64-encoded image data from tool contentBlocks. @deprecated Use imageDataList. */
+  imageData: z.string().optional(),
+  /** Base64-encoded image data from tool contentBlocks (e.g. browser_screenshot, image generation). */
+  imageDataList: z.array(z.string()).optional(),
+  /** Unix ms when the tool started executing. */
+  startedAt: z.number().optional(),
+  /** Unix ms when the tool completed. */
+  completedAt: z.number().optional(),
+  /**
+   * Confirmation outcome for this tool call, when one was recorded. Closed
+   * enum: the daemon has only ever emitted these three values since the field
+   * was introduced, so every daemon that carries it conforms — no version gate.
+   */
+  confirmationDecision: ConfirmationDecisionSchema.optional(),
+  /** Friendly label for the confirmation (e.g. "Edit File", "Run Command"). */
+  confirmationLabel: z.string().optional(),
+  /** Risk level classification at invocation time ("low" | "medium" | "high" | "unknown"). */
+  riskLevel: z.string().optional(),
+  /** Human-readable reason for the risk classification. */
+  riskReason: z.string().optional(),
+  /** ID of the trust rule that matched this invocation (if any). */
+  matchedTrustRuleId: z.string().optional(),
+  /** @deprecated Use `approvalMode` and `approvalReason` instead. */
+  autoApproved: z.boolean().optional(),
+  /** How the approval decision was reached: prompted, auto, blocked, or unknown (legacy). */
+  approvalMode: z.string().optional(),
+  /** Why the approval decision was reached (stable enum for client display). */
+  approvalReason: z.string().optional(),
+  /** Snapshot of the auto-approve threshold at execution time. */
+  riskThreshold: z.string().optional(),
+  /** Display-only regex ladder for the rule editor (narrowest → broadest). */
+  riskScopeOptions: z.array(RiskScopeOptionSchema).optional(),
+  /** Minimatch save patterns for the rule editor (narrowest → broadest). */
+  riskAllowlistOptions: z.array(RiskAllowlistOptionSchema).optional(),
+  /** Directory scope ladder for the rule editor. */
+  riskDirectoryScopeOptions: z.array(RiskDirectoryScopeOptionSchema).optional(),
+  /**
+   * Structured tool activity (web_search / web_fetch) for rich client cards.
+   * Persisted alongside the tool call so the activity card survives a history
+   * reopen instead of degrading to the plain `result` text. Mirrors the live
+   * `tool_result` event's `activityMetadata`. Guaranteed present for tool calls
+   * that produced activity as of daemon v0.8.8; absent for older history rows.
+   */
+  activityMetadata: ToolActivityMetadataSchema.optional(),
+  /**
+   * Confirmation scope ladder (`{label, scope}`) for scope-aware tools
+   * (file/bash). Derived at render time via the permission checker's pure
+   * `generateScopeOptions(workspaceDir, toolName)`, so it is reconstructed for
+   * completed tool calls on history reopen rather than persisted. Feeds the
+   * rule editor's trust-rule suggestion fallback. Distinct from the
+   * regex-flavored `riskScopeOptions` (`{pattern, label}`). Guaranteed present
+   * for scope-aware tools as of daemon v0.8.8; absent for older history rows.
+   */
+  scopeOptions: z.array(ScopeOptionSchema).optional(),
+  /**
+   * In-flight permission prompt, present only while the tool call is awaiting
+   * a user decision (read from the `pending-interactions` registry at render
+   * time). Lets a cold reconnect restore the inline confirmation card.
+   * Guaranteed present for outstanding prompts as of daemon v0.8.8.
+   */
+  pendingConfirmation: PendingToolConfirmationSchema.optional(),
+});
+export type ConversationMessageToolCall = z.infer<
+  typeof ConversationMessageToolCallSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Surface
+// ---------------------------------------------------------------------------
+
+const SurfaceActionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  style: z.string().optional(),
+  data: z.record(z.string(), z.unknown()).optional(),
+});
+
+/**
+ * A UI surface (widget) embedded in a history row. `contentOrder` references
+ * it as `surface:N` where `N` indexes into `surfaces`.
+ */
+export const ConversationMessageSurfaceSchema = z.object({
+  surfaceId: z.string(),
+  surfaceType: z.string(),
+  title: z.string().optional(),
+  data: z.record(z.string(), z.unknown()),
+  actions: z.array(SurfaceActionSchema).optional(),
+  display: z.string().optional(),
+  persistent: z.boolean().optional(),
+  completed: z.boolean().optional(),
+  completionSummary: z.string().optional(),
+  /** Id of the tool call that produced this surface (the `ui_show` proxy tool). */
+  toolCallId: z.string().optional(),
+});
+export type ConversationMessageSurface = z.infer<
+  typeof ConversationMessageSurfaceSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Subagent notification
+// ---------------------------------------------------------------------------
+
+/** Daemon-injected subagent lifecycle notification attached to a history row. */
+export const ConversationSubagentNotificationSchema = z.object({
+  subagentId: z.string(),
+  label: z.string(),
+  status: z.string(),
+  error: z.string().optional(),
+  conversationId: z.string().optional(),
+  objective: z.string().optional(),
+});
+export type ConversationSubagentNotification = z.infer<
+  typeof ConversationSubagentNotificationSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Slack message envelope
+// ---------------------------------------------------------------------------
+
+const SlackMessageLinkSchema = z.object({
+  appUrl: z.string().optional(),
+  webUrl: z.string().optional(),
+});
+
+/** Slack provenance for a history row that originated from a Slack channel. */
+export const ConversationSlackMessageSchema = z.object({
+  channelId: z.string(),
+  channelName: z.string().optional(),
+  channelTs: z.string(),
+  threadTs: z.string().optional(),
+  sender: z
+    .object({
+      displayName: z.string().optional(),
+      externalUserId: z.string().optional(),
+    })
+    .optional(),
+  messageLink: SlackMessageLinkSchema.optional(),
+  threadLink: SlackMessageLinkSchema.optional(),
+});
+export type ConversationSlackMessage = z.infer<
+  typeof ConversationSlackMessageSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Content block (unified ordered content)
+// ---------------------------------------------------------------------------
+
+/**
+ * A single ordered content block. `contentBlocks` is the unified, display-ready
+ * projection of a message's model-native content — one ordered tagged array so
+ * clients render by mapping a single list instead of cross-referencing the
+ * parallel positional arrays.
+ *
+ * Discriminants and field names mirror the model-loop `ContentBlock` union
+ * (`providers/types.ts`) so logic reads the same whether it runs in a
+ * plugin/hook (raw provider blocks) or on a client (this cleaned wire form).
+ * The wire form differs from the raw provider union in three deliberate ways:
+ *   - `tool_use` carries its paired result (`toolCall.result`): the daemon
+ *     merges the separate `tool_result` block at read time so clients never
+ *     re-pair calls with their results.
+ *   - internal/sensitive provider fields are dropped (risk/approval scratch
+ *     fields, raw base64 image bytes, provider thought signatures, opaque
+ *     server-tool blobs).
+ *   - vellum projections with no provider analog (`surface`, `attachment`)
+ *     reuse the existing history schemas.
+ *
+ * The daemon builds this array directly from the model-native content while
+ * rendering history (`renderHistoryContent`); the serializer never reconstructs
+ * it from the positional arrays, so it stays correct once those are retired.
+ */
+export const ConversationContentBlockSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), text: z.string() }),
+  z.object({ type: z.literal("thinking"), thinking: z.string() }),
+  z.object({
+    type: z.literal("tool_use"),
+    toolCall: ConversationMessageToolCallSchema,
+  }),
+  z.object({
+    type: z.literal("surface"),
+    surface: ConversationMessageSurfaceSchema,
+  }),
+  z.object({
+    type: z.literal("attachment"),
+    attachment: ConversationMessageAttachmentSchema,
+  }),
+]);
+export type ConversationContentBlock = z.infer<
+  typeof ConversationContentBlockSchema
+>;
+
+// ---------------------------------------------------------------------------
+// Conversation message (history row)
+// ---------------------------------------------------------------------------
+
+/**
+ * A single consolidated history row as returned by the daemon's messages
+ * endpoint. Consecutive assistant DB rows are merged into one display row;
+ * `mergedMessageIds` records the folded ids.
+ */
+export const ConversationMessageSchema = z.object({
+  id: z.string(),
+  /**
+   * Server message ids folded into this display row when consecutive
+   * assistant messages were consolidated for history rendering.
+   */
+  mergedMessageIds: z.array(z.string()).optional(),
+  /**
+   * Renderable conversation roles only. The messages endpoint emits a
+   * UI-facing transcript, so it excludes the `system` rows that the
+   * underlying `MessageRole` column also permits — those are agent-context
+   * scaffolding, never a displayed turn.
+   */
+  role: z.enum(["user", "assistant"]),
+  /**
+   * Flat plain-text body (joined text segments). Redundant with
+   * `textSegments`/`contentOrder` for clients that render from the positional
+   * arrays (web, CLI), but the legacy Swift macOS client reads `content`
+   * directly and drops any history row missing it (its
+   * `HistoryReconstructionService` skips rows with empty text). The serializer
+   * always emits it — do not remove without updating that client.
+   */
+  content: z.string().optional(),
+  /** Display timestamp as an ISO-8601 string. */
+  timestamp: z.string(),
+  attachments: z.array(ConversationMessageAttachmentSchema),
+  toolCalls: z.array(ConversationMessageToolCallSchema).optional(),
+  surfaces: z.array(ConversationMessageSurfaceSchema).optional(),
+  textSegments: z.array(z.string()).optional(),
+  thinkingSegments: z.array(z.string()).optional(),
+  /** Positional `"<type>:<index>"` content ordering (e.g. `"text:0"`, `"thinking:1"`). */
+  contentOrder: z.array(z.string()).optional(),
+  /**
+   * Unified ordered content blocks — the display-ready projection of the
+   * row's model-native content. Ships alongside the positional
+   * `contentOrder`/`textSegments`/`thinkingSegments` arrays during the client
+   * migration; a client that consumes `contentBlocks` can ignore the
+   * positional arrays entirely.
+   */
+  contentBlocks: z.array(ConversationContentBlockSchema).optional(),
+  subagentNotification: ConversationSubagentNotificationSchema.optional(),
+  slackMessage: ConversationSlackMessageSchema.optional(),
+});
+export type ConversationMessage = z.infer<typeof ConversationMessageSchema>;

package/src/api/responses/disk-pressure-status.ts

@@ -0,0 +1,26 @@
+/**
+ * Wire contract for the disk-pressure REST endpoints
+ * (`GET /disk-pressure/status`, `POST /disk-pressure/acknowledge`,
+ * `POST /disk-pressure/override`). All three return the current
+ * snapshot wrapped as `{ status }`.
+ *
+ * Reuses the canonical `DiskPressureStatusSchema` defined alongside the
+ * `disk_pressure_status_changed` SSE event so the polled REST fetch and
+ * the streamed update share a single shape.
+ *
+ * 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`.
+ */
+
+import { z } from "zod";
+
+import { DiskPressureStatusSchema } from "../events/disk-pressure-status-changed.js";
+
+export const DiskPressureStatusResponseSchema = z.object({
+  status: DiskPressureStatusSchema,
+});
+
+export type DiskPressureStatusResponse = z.infer<
+  typeof DiskPressureStatusResponseSchema
+>;

package/src/api/responses/home.ts

@@ -0,0 +1,217 @@
+/**
+ * Wire contract for the Home REST endpoints.
+ *
+ *   - `GET /v1/home/feed`   → `HomeFeedResponse`
+ *   - `PATCH /v1/home/feed/:id` → `FeedItem`
+ *   - `GET /v1/home/state`  → `RelationshipState`
+ *
+ * Holds the canonical feed-item, suggested-prompt, and relationship-state
+ * shapes shared by the daemon route handlers, the on-disk feed-file parser
+ * (`home/feed-types.ts`), and every external client. Defining them here —
+ * rather than inline in the route files — means the daemon, the OpenAPI
+ * generator, and the web/CLI clients all derive from one source and cannot
+ * drift.
+ *
+ * A structurally compatible Swift mirror lives at
+ * `clients/shared/Network/FeedItem.swift`. Any change to the feed-item
+ * shape must be mirrored there.
+ *
+ * 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`.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Feed item
+// ---------------------------------------------------------------------------
+
+/** High-level kind of feed item — drives which client view renders it. */
+export const FeedItemTypeSchema = z.literal("notification");
+export type FeedItemType = z.infer<typeof FeedItemTypeSchema>;
+
+/** User-facing lifecycle of a feed item. */
+export const FeedItemStatusSchema = z.enum([
+  "new",
+  "seen",
+  "acted_on",
+  "dismissed",
+]);
+export type FeedItemStatus = z.infer<typeof FeedItemStatusSchema>;
+
+/** Visual urgency treatment — controls badge color independently of sort priority. */
+export const FeedItemUrgencySchema = z.enum([
+  "low",
+  "medium",
+  "high",
+  "critical",
+]);
+export type FeedItemUrgency = z.infer<typeof FeedItemUrgencySchema>;
+
+/** Broad category for grouping and filtering feed items. */
+export const FeedItemCategorySchema = z.enum([
+  "security",
+  "scheduling",
+  "background",
+  "email",
+  "system",
+]);
+export type FeedItemCategory = z.infer<typeof FeedItemCategorySchema>;
+
+/**
+ * A single action button attached to a feed item.
+ *
+ * `prompt` is the pre-seeded user message the action sends to the
+ * assistant when triggered — the HTTP route creates a new conversation
+ * with this prompt as the first user turn.
+ */
+export const FeedActionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  prompt: z.string(),
+});
+export type FeedAction = z.infer<typeof FeedActionSchema>;
+
+/** Which detail panel the client should open for this feed item. */
+export const FeedItemDetailPanelKindSchema = z.enum([
+  "emailDraft",
+  "documentPreview",
+  "permissionChat",
+  "paymentAuth",
+  "toolPermission",
+  "updatesList",
+]);
+export type FeedItemDetailPanelKind = z.infer<
+  typeof FeedItemDetailPanelKindSchema
+>;
+
+/** Server-driven detail panel descriptor attached to a feed item. */
+export const FeedItemDetailPanelSchema = z.object({
+  kind: FeedItemDetailPanelKindSchema,
+});
+export type FeedItemDetailPanel = z.infer<typeof FeedItemDetailPanelSchema>;
+
+/**
+ * A single item rendered in the Home feed.
+ *
+ * Notes:
+ *   - `priority` must be an integer in [0, 100]; string numerics
+ *     (e.g. `"5"`) are rejected — we want deterministic ordering and
+ *     silent coercion tends to mask writer bugs.
+ *   - `status` defaults to `"new"` so the writer does not need to set it
+ *     on every append.
+ *   - `createdAt` is the writer-record time (distinct from `timestamp`,
+ *     the event time). Used for TTL sweeps and stable ordering.
+ *   - `expiresAt` is an absolute ISO-8601 expiry timestamp.
+ *   - `title` is optional — clients fall back to `summary` when a row has
+ *     no header.
+ */
+export const FeedItemSchema = z.object({
+  id: z.string(),
+  type: FeedItemTypeSchema,
+  priority: z.number().int().min(0).max(100),
+  title: z.string().optional(),
+  summary: z.string(),
+  timestamp: z.string(),
+  status: FeedItemStatusSchema.default("new"),
+  expiresAt: z.string().optional(),
+  actions: z.array(FeedActionSchema).optional(),
+  urgency: FeedItemUrgencySchema.optional(),
+  conversationId: z.string().optional(),
+  detailPanel: FeedItemDetailPanelSchema.optional(),
+  category: FeedItemCategorySchema.optional(),
+  noteworthy: z.boolean().optional(),
+  fromAssistant: z.boolean().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  createdAt: z.string(),
+});
+export type FeedItem = z.infer<typeof FeedItemSchema>;
+
+// ---------------------------------------------------------------------------
+// Suggested prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * Origin of a suggested prompt — whether it was deterministically derived
+ * (e.g. from a missing OAuth connection) or generated by the assistant.
+ */
+export const SuggestedPromptSourceSchema = z.enum([
+  "deterministic",
+  "assistant",
+]);
+export type SuggestedPromptSource = z.infer<typeof SuggestedPromptSourceSchema>;
+
+/** A prompt suggestion shown at the top of the Home page. */
+export const SuggestedPromptSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  icon: z.string().optional(),
+  prompt: z.string(),
+  source: SuggestedPromptSourceSchema,
+});
+export type SuggestedPrompt = z.infer<typeof SuggestedPromptSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /v1/home/feed
+// ---------------------------------------------------------------------------
+
+/** Greeting + relative time-away label + new-item count banner. */
+export const ContextBannerSchema = z.object({
+  greeting: z.string(),
+  timeAwayLabel: z.string(),
+  newCount: z.number().int().min(0),
+});
+export type ContextBanner = z.infer<typeof ContextBannerSchema>;
+
+export const HomeFeedResponseSchema = z.object({
+  items: z.array(FeedItemSchema),
+  updatedAt: z.string(),
+  contextBanner: ContextBannerSchema,
+  suggestedPrompts: z.array(SuggestedPromptSchema),
+});
+export type HomeFeedResponse = z.infer<typeof HomeFeedResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /v1/home/state
+// ---------------------------------------------------------------------------
+
+export const FactSchema = z.object({
+  id: z.string(),
+  category: z.enum(["voice", "world", "priorities"]),
+  text: z.string(),
+  confidence: z.enum(["strong", "uncertain"]),
+  source: z.enum(["onboarding", "inferred"]),
+});
+export type Fact = z.infer<typeof FactSchema>;
+export type FactCategory = Fact["category"];
+export type FactConfidence = Fact["confidence"];
+export type FactSource = Fact["source"];
+
+export const CapabilitySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  tier: z.enum(["unlocked", "next-up", "earned"]),
+  gate: z.string(),
+  unlockHint: z.string().optional(),
+  ctaLabel: z.string().optional(),
+});
+export type Capability = z.infer<typeof CapabilitySchema>;
+export type CapabilityTier = Capability["tier"];
+
+export const RelationshipStateSchema = z.object({
+  version: z.literal(1),
+  assistantId: z.string(),
+  tier: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]),
+  progressPercent: z.number(),
+  facts: z.array(FactSchema),
+  capabilities: z.array(CapabilitySchema),
+  conversationCount: z.number(),
+  hatchedDate: z.string(),
+  assistantName: z.string(),
+  userName: z.string().optional(),
+  updatedAt: z.string(),
+});
+export type RelationshipState = z.infer<typeof RelationshipStateSchema>;
+export type RelationshipTier = RelationshipState["tier"];

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

@@ -0,0 +1,41 @@
+/**
+ * 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";
+import { MemoryV3SelectionLogSchema } from "./memory-v3-selection-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(),
+  memoryV3Selection: MemoryV3SelectionLogSchema.nullish(),
+});
+
+export type LlmContextResponse = z.infer<typeof LlmContextResponseSchema>;