@vellumai/assistant 0.8.6 → 0.8.7

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

@@ -24,6 +24,7 @@ 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(),
@@ -34,6 +35,7 @@ export const LlmContextResponseSchema = z.object({
   logs: z.array(LLMRequestLogEntrySchema),
   memoryRecall: MemoryRecallLogSchema.nullable(),
   memoryV2Activation: MemoryV2ActivationLogSchema.nullable(),
+  memoryV3Selection: MemoryV3SelectionLogSchema.nullish(),
 });
 
 export type LlmContextResponse = z.infer<typeof LlmContextResponseSchema>;

package/src/api/responses/memory-v3-selection-log.ts

@@ -0,0 +1,50 @@
+/**
+ * Wire contract for the memory v3 selection set surfaced in the inspector's
+ * Memory tab. Mirrors the return value of `getMemoryV3SelectionForInspector`
+ * in `assistant/src/memory/v3/selection-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`.
+ *
+ * `live` / `shadow` reflect the CURRENT `memory-v3-live` / `memory-v3-shadow`
+ * flag state, not the per-turn history (the selection rows don't record which
+ * mode was active when they were written). When `live` is true the rendered
+ * `injectedText` block was actually injected into the turn; when only `shadow`
+ * is true it is the block that WOULD have been injected. For stable-flag
+ * shadow validation these coincide; recording per-turn `injected` is a
+ * documented follow-up.
+ */
+
+import { z } from "zod";
+
+/**
+ * One selected page in the v3 set. `source` is the lane that surfaced it —
+ * the daemon emits `l1+l2`, `core+l2`, `needle`, or `carry-forward` — but the
+ * schema stays a permissive string so a new lane label doesn't break parsing
+ * on the FE. `pinned` marks a slug carried forward across turns.
+ */
+export const MemoryV3SelectionRowSchema = z.object({
+  slug: z.string(),
+  source: z.string(),
+  pinned: z.boolean(),
+});
+
+export type MemoryV3SelectionRow = z.infer<typeof MemoryV3SelectionRowSchema>;
+
+/**
+ * Memory v3 selection log shape. `injectedText` is the rendered
+ * `<memory>…</memory>` block for the selection (actual when `live`, would-be
+ * when `shadow`-only).
+ */
+export const MemoryV3SelectionLogSchema = z.object({
+  turn: z.number(),
+  live: z.boolean(),
+  shadow: z.boolean(),
+  selections: z.array(MemoryV3SelectionRowSchema),
+  injectedText: z.string(),
+});
+
+export type MemoryV3SelectionLog = z.infer<typeof MemoryV3SelectionLogSchema>;

package/src/api/responses/subagent-detail.ts

@@ -0,0 +1,48 @@
+/**
+ * Wire contract for the subagent-detail REST endpoint
+ * (`GET /subagents/:id`). Returns a subagent's objective, live status,
+ * cumulative usage, and the reconstructed event history parsed from its
+ * stored message rows.
+ *
+ * Reuses the canonical `SubagentStatusSchema` and `SubagentUsageStatsSchema`
+ * defined alongside the `subagent_status_changed` SSE event so the polled
+ * REST detail and the streamed status update share one status/usage 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 {
+  SubagentStatusSchema,
+  SubagentUsageStatsSchema,
+} from "../events/subagent-status-changed.js";
+
+/**
+ * A single reconstructed event in a subagent's history. Built from the
+ * subagent conversation's stored message rows (assistant text, tool calls,
+ * tool results), so `type` is an open string rather than a closed enum.
+ */
+export const SubagentDetailEventSchema = z.object({
+  type: z.string(),
+  content: z.string(),
+  toolName: z.string().optional(),
+  isError: z.boolean().optional(),
+  messageId: z.string().optional(),
+});
+
+export type SubagentDetailEvent = z.infer<typeof SubagentDetailEventSchema>;
+
+export const SubagentDetailResponseSchema = z.object({
+  subagentId: z.string(),
+  objective: z.string().optional(),
+  status: SubagentStatusSchema.optional(),
+  usage: SubagentUsageStatsSchema.optional(),
+  events: z.array(SubagentDetailEventSchema),
+});
+
+export type SubagentDetailResponse = z.infer<
+  typeof SubagentDetailResponseSchema
+>;

package/src/approvals/guardian-decision-primitive.ts

@@ -198,19 +198,17 @@ export async function applyGuardianDecision(
     decisionContext,
   } = params;
 
-  const effectiveDecision: ApprovalDecisionResult = decision;
-
   // Capture pending approval info before handleChannelDecision resolves
   // (and removes) the pending interaction. Needed for grant minting.
   const approvalInfo = getApprovalInfoByConversation(approval.conversationId);
-  const matchedInfo = effectiveDecision.requestId
-    ? approvalInfo.find((a) => a.requestId === effectiveDecision.requestId)
+  const matchedInfo = decision.requestId
+    ? approvalInfo.find((a) => a.requestId === decision.requestId)
     : approvalInfo[0];
 
   // Apply the decision to the underlying session
   const result = await handleChannelDecision(
     approval.conversationId,
-    effectiveDecision,
+    decision,
     decisionContext,
   );
 
@@ -218,15 +216,13 @@ export async function applyGuardianDecision(
     return {
       applied: false,
       reason: "stale",
-      requestId: effectiveDecision.requestId,
+      requestId: decision.requestId,
     };
   }
 
   // Update the guardian approval request record
   const approvalStatus =
-    effectiveDecision.action === "reject"
-      ? ("denied" as const)
-      : ("approved" as const);
+    decision.action === "reject" ? ("denied" as const) : ("approved" as const);
   updateApprovalDecision(approval.id, {
     status: approvalStatus,
     decidedByExternalUserId: actorExternalUserId ?? actorPrincipalId,
@@ -236,17 +232,13 @@ export async function applyGuardianDecision(
   // Skip when neither actor identity is available -- minting a grant without
   // a known guardian identity is meaningless (e.g. requester self-cancel).
   const effectiveGuardianId = actorExternalUserId ?? actorPrincipalId;
-  if (
-    effectiveDecision.action !== "reject" &&
-    matchedInfo &&
-    effectiveGuardianId
-  ) {
+  if (decision.action !== "reject" && matchedInfo && effectiveGuardianId) {
     tryMintToolApprovalGrant({
       approvalInfo: matchedInfo,
       approval,
       decisionChannel: actorChannel,
       guardianExternalUserId: effectiveGuardianId,
-      effectiveAction: effectiveDecision.action,
+      effectiveAction: decision.action,
     });
   }
 

package/src/approvals/guardian-request-resolvers.ts

@@ -203,14 +203,9 @@ const pendingInteractionResolver: GuardianRequestResolver = {
         reason: `conversation_not_found: ${interaction.conversationId}`,
       };
     }
-    conversation.handleConfirmationResponse(
-      request.id,
-      userDecision,
-      undefined,
-      undefined,
-      undefined,
-      ctx.emissionContext,
-    );
+    conversation.handleConfirmationResponse(request.id, userDecision, {
+      emissionContext: ctx.emissionContext,
+    });
 
     log.info(
       {
@@ -505,7 +500,9 @@ const accessRequestResolver: GuardianRequestResolver = {
           sourceChannel: "phone",
           externalUserId: requesterExternalUserId,
           ...(requesterChatId ? { externalChatId: requesterChatId } : {}),
-          ...(requesterDisplayName ? { displayName: requesterDisplayName } : {}),
+          ...(requesterDisplayName
+            ? { displayName: requesterDisplayName }
+            : {}),
         },
       };
     }

package/src/avatar/__tests__/avatar-manifest.test.ts

@@ -0,0 +1,236 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  type AvatarState,
+  deriveStateFromLegacyFiles,
+  readManifest,
+  writeManifest,
+} from "../avatar-manifest.js";
+
+const VALID_TRAITS = { bodyShape: "round", eyeStyle: "happy", color: "blue" };
+
+describe("avatar-manifest", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "avatar-manifest-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  describe("readManifest / writeManifest", () => {
+    test("round-trips a written manifest", () => {
+      const state: AvatarState = {
+        kind: "character",
+        traits: VALID_TRAITS,
+        source: "builder",
+        image: null,
+      };
+      writeManifest(state, dir);
+      expect(readManifest(dir)).toEqual(state);
+    });
+
+    test("round-trips an image manifest", () => {
+      const state: AvatarState = {
+        kind: "image",
+        traits: null,
+        source: "upload",
+        image: { updatedAt: "2024-01-01T00:00:00.000Z", etag: "abc123" },
+      };
+      writeManifest(state, dir);
+      expect(readManifest(dir)).toEqual(state);
+    });
+
+    test("returns null when manifest is missing", () => {
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when manifest is corrupt JSON", () => {
+      writeFileSync(join(dir, "avatar.json"), "{ not json");
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is invalid", () => {
+      writeFileSync(
+        join(dir, "avatar.json"),
+        JSON.stringify({
+          kind: "bogus",
+          traits: null,
+          source: null,
+          image: null,
+        }),
+      );
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is missing", () => {
+      writeFileSync(join(dir, "avatar.json"), JSON.stringify({ traits: null }));
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is character but traits are null", () => {
+      writeFileSync(
+        join(dir, "avatar.json"),
+        JSON.stringify({
+          kind: "character",
+          traits: null,
+          source: null,
+          image: null,
+        }),
+      );
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is character but traits are missing", () => {
+      writeFileSync(
+        join(dir, "avatar.json"),
+        JSON.stringify({ kind: "character" }),
+      );
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is character but traits are incomplete", () => {
+      writeFileSync(
+        join(dir, "avatar.json"),
+        JSON.stringify({
+          kind: "character",
+          traits: { bodyShape: "round" },
+          source: null,
+          image: null,
+        }),
+      );
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is image but image meta is null", () => {
+      writeFileSync(
+        join(dir, "avatar.json"),
+        JSON.stringify({
+          kind: "image",
+          traits: null,
+          source: null,
+          image: null,
+        }),
+      );
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is image but image meta is missing", () => {
+      writeFileSync(
+        join(dir, "avatar.json"),
+        JSON.stringify({ kind: "image" }),
+      );
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is image but etag is empty", () => {
+      writeFileSync(
+        join(dir, "avatar.json"),
+        JSON.stringify({
+          kind: "image",
+          traits: null,
+          source: null,
+          image: { updatedAt: "2024-01-01T00:00:00.000Z", etag: "" },
+        }),
+      );
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns null when kind is image but updatedAt is missing", () => {
+      writeFileSync(
+        join(dir, "avatar.json"),
+        JSON.stringify({
+          kind: "image",
+          traits: null,
+          source: null,
+          image: { etag: "abc123" },
+        }),
+      );
+      expect(readManifest(dir)).toBeNull();
+    });
+
+    test("returns the manifest when kind is none (no payload required)", () => {
+      const state: AvatarState = {
+        kind: "none",
+        traits: null,
+        source: null,
+        image: null,
+      };
+      writeFileSync(join(dir, "avatar.json"), JSON.stringify({ kind: "none" }));
+      expect(readManifest(dir)).toEqual(state);
+    });
+  });
+
+  describe("deriveStateFromLegacyFiles", () => {
+    test("traits-only → character", () => {
+      writeFileSync(
+        join(dir, "character-traits.json"),
+        JSON.stringify(VALID_TRAITS),
+      );
+      const state = deriveStateFromLegacyFiles(dir);
+      expect(state.kind).toBe("character");
+      expect(state.traits).toEqual(VALID_TRAITS);
+      expect(state.source).toBeNull();
+      expect(state.image).toBeNull();
+    });
+
+    test("image-only → image with computed etag and updatedAt", () => {
+      writeFileSync(join(dir, "avatar-image.png"), Buffer.from("fake png"));
+      const state = deriveStateFromLegacyFiles(dir);
+      expect(state.kind).toBe("image");
+      expect(state.traits).toBeNull();
+      expect(state.source).toBeNull();
+      expect(state.image?.etag).toMatch(/^[0-9a-f]{16}$/);
+      expect(state.image?.updatedAt).toMatch(
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/,
+      );
+    });
+
+    test("both present → character (traits-first, ignores PNG mtime)", () => {
+      // Write traits first, then PNG so the PNG is strictly newer — mirrors
+      // how the builder writes files. Traits-first must still win.
+      writeFileSync(
+        join(dir, "character-traits.json"),
+        JSON.stringify(VALID_TRAITS),
+      );
+      writeFileSync(join(dir, "avatar-image.png"), Buffer.from("fake png"));
+      const state = deriveStateFromLegacyFiles(dir);
+      expect(state.kind).toBe("character");
+      expect(state.traits).toEqual(VALID_TRAITS);
+      expect(state.image).toBeNull();
+    });
+
+    test("corrupt traits json + image present → image", () => {
+      writeFileSync(join(dir, "character-traits.json"), "{ broken");
+      writeFileSync(join(dir, "avatar-image.png"), Buffer.from("fake png"));
+      const state = deriveStateFromLegacyFiles(dir);
+      expect(state.kind).toBe("image");
+      expect(state.image).not.toBeNull();
+    });
+
+    test("incomplete traits (missing fields) + image present → image", () => {
+      writeFileSync(
+        join(dir, "character-traits.json"),
+        JSON.stringify({ bodyShape: "round" }),
+      );
+      writeFileSync(join(dir, "avatar-image.png"), Buffer.from("fake png"));
+      const state = deriveStateFromLegacyFiles(dir);
+      expect(state.kind).toBe("image");
+    });
+
+    test("neither → none", () => {
+      const state = deriveStateFromLegacyFiles(dir);
+      expect(state).toEqual({
+        kind: "none",
+        traits: null,
+        source: null,
+        image: null,
+      });
+    });
+  });
+});