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

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

@@ -14,7 +14,7 @@
 import { answerCall } from "../calls/call-domain.js";
 import { findContactChannel } from "../contacts/contact-store.js";
 import { upsertContactChannel } from "../contacts/contacts-write.js";
-import { findConversation } from "../daemon/conversation-store.js";
+import { findConversation } from "../daemon/conversation-registry.js";
 import {
   type CanonicalGuardianRequest,
   getCanonicalGuardianRequest,
@@ -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,
+      });
+    });
+  });
+});

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

@@ -0,0 +1,198 @@
+/**
+ * Tests for the avatar store — atomic artifact + manifest mutations.
+ *
+ * Each operation must leave `avatar.json` consistent with the on-disk
+ * artifacts:
+ *   - setCharacter  → traits.json + PNG (+ ASCII) on disk, `character` manifest
+ *   - setImage      → PNG on disk, character sidecars removed, `image` manifest
+ *   - clearAvatar   → everything removed, `none` manifest
+ *
+ * The avatar directory is controlled per-test via VELLUM_WORKSPACE_DIR, which
+ * `getAvatarDir()` resolves live. Per the test-isolation rule in
+ * assistant/AGENTS.md, this file imports ONLY the module under test
+ * (`avatar-store`); state is asserted by reading `avatar.json` and the artifact
+ * files directly off the per-test workspace dir via `node:fs`.
+ *
+ * `setCharacter` routes through the native @resvg/resvg-js renderer. Rather than
+ * stub that native path (which would require importing production machinery), we
+ * branch on the store's documented return value: when the binding is available
+ * the success path is asserted, and when it is not the `native_unavailable`
+ * failure contract is asserted instead — so the suite passes deterministically
+ * whether or not the native binding is installed in the test environment.
+ */
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  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 { clearAvatar, setCharacter, setImage } from "../avatar-store.js";
+
+// A valid trait triple drawn from the real component set.
+const VALID_TRAITS = { bodyShape: "blob", eyeStyle: "curious", color: "green" };
+
+const IMAGE_FILENAME = "avatar-image.png";
+const TRAITS_FILENAME = "character-traits.json";
+const ASCII_FILENAME = "character-ascii.txt";
+const MANIFEST_FILENAME = "avatar.json";
+const NATIVE_RENDER_TEST_TIMEOUT_MS = 15_000;
+
+interface ManifestShape {
+  kind: string;
+  traits: Record<string, unknown> | null;
+  source: string | null;
+  image: { updatedAt: string; etag: string } | null;
+}
+
+describe("avatar-store", () => {
+  let workspaceDir: string;
+  let avatarDir: string;
+  let prevWorkspaceDir: string | undefined;
+
+  beforeEach(() => {
+    workspaceDir = mkdtempSync(join(tmpdir(), "avatar-store-test-"));
+    // getAvatarDir() === <workspace>/data/avatar
+    avatarDir = join(workspaceDir, "data", "avatar");
+    prevWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+    process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+    // Pre-create the avatar dir so tests that seed legacy artifacts can write
+    // into it before the store's own mkdir runs.
+    mkdirSync(avatarDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (prevWorkspaceDir === undefined) {
+      delete process.env.VELLUM_WORKSPACE_DIR;
+    } else {
+      process.env.VELLUM_WORKSPACE_DIR = prevWorkspaceDir;
+    }
+    rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  const path = (name: string) => join(avatarDir, name);
+
+  /** Reads and parses the on-disk manifest, or returns null when absent. */
+  const readManifestFile = (): ManifestShape | null => {
+    const manifestPath = path(MANIFEST_FILENAME);
+    if (!existsSync(manifestPath)) return null;
+    return JSON.parse(readFileSync(manifestPath, "utf-8")) as ManifestShape;
+  };
+
+  describe("setCharacter", () => {
+    test(
+      "writes traits + PNG and a character manifest when render succeeds",
+      () => {
+        const result = setCharacter(VALID_TRAITS);
+
+        // The native @resvg/resvg-js binding may be absent in this environment.
+        // When it is, the store returns `native_unavailable` and writes nothing —
+        // we assert that contract instead of the success path so the suite is
+        // deterministic either way.
+        if (!result.ok) {
+          expect(result.reason).toBe("native_unavailable");
+          expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+          expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
+          expect(existsSync(path(MANIFEST_FILENAME))).toBe(false);
+          return;
+        }
+
+        expect(existsSync(path(TRAITS_FILENAME))).toBe(true);
+        expect(existsSync(path(IMAGE_FILENAME))).toBe(true);
+        expect(
+          JSON.parse(readFileSync(path(TRAITS_FILENAME), "utf-8")),
+        ).toEqual(VALID_TRAITS);
+
+        const manifest = readManifestFile();
+        expect(manifest).not.toBeNull();
+        expect(manifest!.kind).toBe("character");
+        expect(manifest!.traits).toEqual(VALID_TRAITS);
+        expect(manifest!.source).toBe("builder");
+        expect(manifest!.image).not.toBeNull();
+        expect(manifest!.image!.etag).toMatch(/^[0-9a-f]{16}$/);
+      },
+      NATIVE_RENDER_TEST_TIMEOUT_MS,
+    );
+
+    test("propagates invalid_traits without writing a manifest", () => {
+      const result = setCharacter({ bodyShape: "", eyeStyle: "", color: "" });
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.reason).toBe("invalid_traits");
+      expect(existsSync(path(MANIFEST_FILENAME))).toBe(false);
+      expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
+    });
+  });
+
+  describe("setImage", () => {
+    test("writes the PNG and an image manifest", () => {
+      setImage(Buffer.from("fake png bytes"), "upload");
+
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(true);
+      expect(readFileSync(path(IMAGE_FILENAME)).toString()).toBe(
+        "fake png bytes",
+      );
+
+      const manifest = readManifestFile();
+      expect(manifest).not.toBeNull();
+      expect(manifest!.kind).toBe("image");
+      expect(manifest!.traits).toBeNull();
+      expect(manifest!.source).toBe("upload");
+      expect(manifest!.image).not.toBeNull();
+      expect(manifest!.image!.etag).toMatch(/^[0-9a-f]{16}$/);
+      expect(manifest!.image!.updatedAt).toMatch(
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/,
+      );
+    });
+
+    test("removes stale character sidecars on transition", () => {
+      // Seed legacy character artifacts.
+      writeFileSync(path(TRAITS_FILENAME), JSON.stringify(VALID_TRAITS));
+      writeFileSync(path(ASCII_FILENAME), "ascii art");
+
+      setImage(Buffer.from("png"), "ai");
+
+      expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+      expect(existsSync(path(ASCII_FILENAME))).toBe(false);
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(true);
+      expect(readManifestFile()!.kind).toBe("image");
+    });
+
+    test("is idempotent across repeated calls", () => {
+      setImage(Buffer.from("v1"), "upload");
+      setImage(Buffer.from("v2"), "upload");
+
+      expect(readFileSync(path(IMAGE_FILENAME)).toString()).toBe("v2");
+      expect(readManifestFile()!.kind).toBe("image");
+    });
+  });
+
+  describe("clearAvatar", () => {
+    test("removes all artifacts AND the manifest (none == absence)", () => {
+      writeFileSync(path(IMAGE_FILENAME), Buffer.from("png"));
+      writeFileSync(path(TRAITS_FILENAME), JSON.stringify(VALID_TRAITS));
+      writeFileSync(path(ASCII_FILENAME), "ascii art");
+
+      clearAvatar();
+
+      expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
+      expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+      expect(existsSync(path(ASCII_FILENAME))).toBe(false);
+      // "No avatar" is represented by the absence of avatar.json, so a later
+      // legacy sidecar write isn't shadowed by a stale `none` manifest.
+      expect(readManifestFile()).toBeNull();
+    });
+
+    test("is idempotent when nothing exists", () => {
+      clearAvatar();
+      clearAvatar();
+      expect(readManifestFile()).toBeNull();
+    });
+  });
+});