@vellumai/assistant 0.8.5 → 0.8.6

package/src/api/index.ts

@@ -1,4 +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 RelationshipStateUpdated,
-  RelationshipStateUpdatedSchema,
-} from "../events/relationship-state-updated.js";
+  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/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>;