@vellumai/assistant 0.11.10-dev.202609091913.5b4889c → 0.11.10-dev.202609092016.c7aa45c

package/AGENTS.md

@@ -30,7 +30,7 @@ DB migrations run asynchronously during startup: the HTTP server binds (so `/hea
 
 Existing enforcement, which new code must not bypass:
 
-- **HTTP** requests are gated per-route in `runtime/http-server.ts`; **IPC** methods in `ipc/assistant-server.ts`; both derive their exempt set from `DB_MIGRATION_READINESS_EXEMPT_OPERATIONS` in `daemon-readiness.ts` (health/liveness probes only — anything exempted must never touch the DB).
+- **HTTP** requests are gated per-route in `runtime/http-server.ts`; **IPC** methods in `ipc/assistant-server.ts`; both derive their exempt set from `DB_MIGRATION_READINESS_EXEMPT_OPERATIONS` in `daemon-readiness.ts` (health/liveness probes plus in-memory diagnostics such as `debug/database` — anything exempted must never touch the DB).
 - **Message sinks** (`processMessage`, `processMessageInBackground`) guard via `assertDbMigrationsReadyForTurn()`.
 - **Background sweeps** are started by lifecycle only after migrations settle (`startRuntimeHttpServerBackgroundSweeps`).
 - The **migration-repair surface** (`admin/rollback-migrations` plus all `migrations/import*` / preflight transports and their job-status route) is additionally allowed in the terminal `failed` state only — see `DB_MIGRATION_FAILED_STATE_EXEMPT_OPERATIONS`. Never widen this to the `running` state: a rollback or import would race the in-flight migration runner. A successful repair does not clear the failed latch — the daemon must be restarted to re-run migrations and become ready.

package/node_modules/@vellumai/gateway-client/src/ipc-client.ts

@@ -340,7 +340,8 @@ type PendingRequest = {
 export type PersistentIpcClientOptions = {
   /**
    * Additional delays (ms) before each reconnect attempt after a retryable
-   * connect failure. Pass `[]` to fail on the first miss (tests).
+   * connect failure. Pass `[]` to fail on the first miss (tests and callers
+   * that already own a retry budget, such as classify_risk).
    */
   connectRetryBackoffsMs?: readonly number[];
 };
@@ -350,8 +351,9 @@ export type PersistentIpcClientOptions = {
  * reconnection on failure. Multiplexes requests by ID so many concurrent
  * callers can share one socket.
  *
- * Designed for hot-path calls (e.g. classify_risk) where connecting per call
- * adds unacceptable overhead.
+ * Designed for multiplexed calls over one socket. Control-plane callers
+ * typically keep the default connect retries for sibling boot races.
+ * Callers that already own a retry budget pass `connectRetryBackoffsMs: []`.
  */
 export class PersistentIpcClient {
   private socket: Socket | null = null;

package/openapi.yaml

@@ -1713,6 +1713,99 @@ paths:
       responses:
         "204":
           description: Successful response
+    get:
+      operationId: attachments_get
+      summary: List conversation attachments
+      description:
+        Return metadata for every attachment linked to a conversation's messages, newest first, across fork
+        lineage. Camera frames kept by live vision are flagged. Bytes come from GET /attachments/{id}/content.
+      tags:
+        - attachments
+      parameters:
+        - name: conversationId
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Conversation whose attachments to list
+        - name: sightFrames
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - only
+              - exclude
+          description: Restrict to camera frames, or leave them out
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+          description: Page size, default 200, max 1000
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  attachments:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        filename:
+                          type: string
+                        mimeType:
+                          type: string
+                        sizeBytes:
+                          type: number
+                        kind:
+                          type: string
+                        messageId:
+                          type: string
+                        createdAt:
+                          type: number
+                          description: "Capture time: the carrying message's created_at"
+                        fileBacked:
+                          type: boolean
+                        thumbnailData:
+                          type: string
+                        sightFrame:
+                          type: boolean
+                        ambientKeep:
+                          type: boolean
+                      required:
+                        - id
+                        - filename
+                        - mimeType
+                        - sizeBytes
+                        - kind
+                        - messageId
+                        - createdAt
+                        - sightFrame
+                        - ambientKeep
+                      additionalProperties: false
+                  total:
+                    type: number
+                  hasMore:
+                    type: boolean
+                required:
+                  - attachments
+                  - total
+                  - hasMore
+                additionalProperties: false
+        "400":
+          description: Missing or invalid query
     post:
       operationId: attachments_post
       summary: Upload attachment
@@ -11081,6 +11174,71 @@ paths:
                   - exitCode
                   - timedOut
                 additionalProperties: false
+  /v1/debug/database:
+    get:
+      operationId: debug_database_get
+      summary: Database migration diagnostics
+      description:
+        Return the in-memory DB migration latch, including failed and deferred steps. Does not query SQLite, so it
+        stays answerable while migrations are running or have failed.
+      tags:
+        - debug
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ready:
+                    type: boolean
+                  state:
+                    type: string
+                    enum:
+                      - not_started
+                      - running
+                      - failed
+                      - ready
+                  reason:
+                    type: string
+                  error:
+                    type: string
+                  failed:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        name:
+                          type: string
+                        error:
+                          type: string
+                      required:
+                        - name
+                      additionalProperties: false
+                  deferred:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        name:
+                          type: string
+                        missing:
+                          type: array
+                          items:
+                            type: string
+                      required:
+                        - name
+                        - missing
+                      additionalProperties: false
+                  validationError:
+                    type: string
+                required:
+                  - ready
+                  - state
+                  - failed
+                  - deferred
+                additionalProperties: false
   /v1/defer/cancel:
     post:
       operationId: defer_cancel_post
@@ -13442,6 +13600,35 @@ paths:
                         type: string
                       error:
                         type: string
+                      failedMigrations:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            name:
+                              type: string
+                            error:
+                              type: string
+                          required:
+                            - name
+                          additionalProperties: false
+                      deferredMigrations:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            name:
+                              type: string
+                            missing:
+                              type: array
+                              items:
+                                type: string
+                          required:
+                            - name
+                            - missing
+                          additionalProperties: false
+                      validationError:
+                        type: string
                     required:
                       - ready
                       - state
@@ -13647,6 +13834,35 @@ paths:
                         type: string
                       error:
                         type: string
+                      failedMigrations:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            name:
+                              type: string
+                            error:
+                              type: string
+                          required:
+                            - name
+                          additionalProperties: false
+                      deferredMigrations:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            name:
+                              type: string
+                            missing:
+                              type: array
+                              items:
+                                type: string
+                          required:
+                            - name
+                            - missing
+                          additionalProperties: false
+                      validationError:
+                        type: string
                     required:
                       - ready
                       - state

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.10-dev.202609091913.5b4889c",
+  "version": "0.11.10-dev.202609092016.c7aa45c",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/config-schema.test.ts

@@ -757,6 +757,7 @@ describe("AssistantConfigSchema", () => {
       maxFileSizeBytes: 256000,
       historyCompaction: { enabled: true },
       interactiveGitTimeoutMs: 10000,
+      stageBatchSize: 1000,
       enrichmentQueueSize: 50,
       enrichmentConcurrency: 1,
       enrichmentJobTimeoutMs: 30000,
@@ -811,6 +812,31 @@ describe("AssistantConfigSchema", () => {
     expect(result.success).toBe(false);
   });
 
+  test("applies workspaceGit.stageBatchSize default", () => {
+    expect(AssistantConfigSchema.parse({}).workspaceGit.stageBatchSize).toBe(
+      1000,
+    );
+  });
+
+  test("accepts custom workspaceGit.stageBatchSize", () => {
+    const result = AssistantConfigSchema.parse({
+      workspaceGit: { stageBatchSize: 250 },
+    });
+    expect(result.workspaceGit.stageBatchSize).toBe(250);
+  });
+
+  test("rejects non-positive workspaceGit.stageBatchSize", () => {
+    const zeroResult = AssistantConfigSchema.safeParse({
+      workspaceGit: { stageBatchSize: 0 },
+    });
+    expect(zeroResult.success).toBe(false);
+
+    const negativeResult = AssistantConfigSchema.safeParse({
+      workspaceGit: { stageBatchSize: -1 },
+    });
+    expect(negativeResult.success).toBe(false);
+  });
+
   test("applies sight defaults", () => {
     expect(AssistantConfigSchema.parse({}).sight).toEqual({
       keepLatestFrames: 2,

package/src/__tests__/db-readiness-http-gate.test.ts

@@ -123,6 +123,49 @@ describe("DB migration readiness HTTP gate", () => {
     expect(body.reason).toBe("db_migrations_failed");
   });
 
+  test("continues serving debug/database while migrations are running", async () => {
+    setDbMigrating();
+    await startServer();
+
+    const response = await fetch(url("/debug/database"));
+    expect(response.status).toBe(200);
+
+    const body = (await response.json()) as Record<string, unknown>;
+    expect(body.ready).toBe(false);
+    expect(body.state).toBe("running");
+    expect(body.reason).toBe("db_migrations_running");
+    expect(body.failed).toEqual([]);
+    expect(body.deferred).toEqual([]);
+  });
+
+  test("continues serving debug/database when migrations have failed", async () => {
+    setDbMigrationFailed(new Error("boom"), {
+      failedMigrations: [{ name: "flakyStep", error: "transient failure" }],
+      deferredMigrations: [{ name: "dependentStep", missing: ["flakyStep"] }],
+      validationError: "schema mismatch",
+    });
+    await startServer();
+
+    const response = await fetch(url("/debug/database"));
+    expect(response.status).toBe(200);
+
+    const body = (await response.json()) as Record<string, unknown>;
+    expect(body.ready).toBe(false);
+    expect(body.state).toBe("failed");
+    expect(body.reason).toBe("db_migrations_failed");
+    expect(body.error).toBe("boom");
+    expect(body.failed).toEqual([
+      { name: "flakyStep", error: "transient failure" },
+    ]);
+    expect(body.deferred).toEqual([
+      { name: "dependentStep", missing: ["flakyStep"] },
+    ]);
+    expect(body.validationError).toBe("schema mismatch");
+
+    const conversations = await fetch(url("/conversations"));
+    expect(conversations.status).toBe(503);
+  });
+
   test("blocks config schema while migrations are running", async () => {
     setDbMigrating();
     await startServer();

package/src/__tests__/error-handler-friendly-messages.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
+import { IpcConnectError } from "@vellumai/gateway-client/ipc-client";
+
 import { withErrorHandling } from "../runtime/middleware/error-handler.js";
 import { ConfigError, ProviderNotConfiguredError } from "../util/errors.js";
 
@@ -42,4 +44,17 @@ describe("withErrorHandling – friendly error messages", () => {
     };
     expect(body.error.message).toBe("Twilio phone number not configured.");
   });
+
+  test("IpcConnectError surfaces as 503 SERVICE_UNAVAILABLE", async () => {
+    const response = await withErrorHandling("test", async () => {
+      throw new IpcConnectError("connect ENOENT", "ENOENT");
+    });
+
+    expect(response.status).toBe(503);
+    const body = (await response.json()) as {
+      error: { code: string; message: string };
+    };
+    expect(body.error.code).toBe("SERVICE_UNAVAILABLE");
+    expect(body.error.message).toContain("Gateway is not reachable over IPC");
+  });
 });

package/src/__tests__/identity-routes.test.ts

@@ -483,13 +483,18 @@ describe("identity routes — /readyz readiness gate", () => {
   });
 
   test("returns 503 when DB migrations fail", async () => {
-    setDbMigrationFailed(new Error("migration failed"));
+    setDbMigrationFailed(new Error("migration failed"), {
+      failedMigrations: [{ name: "flakyStep", error: "transient failure" }],
+    });
     const res = handleReadyz();
     expect(res.status).toBe(503);
     const body = (await res.json()) as Record<string, unknown>;
     expect(body.ready).toBe(false);
     expect(body.reason).toBe("db_migrations_failed");
     expect((body.dbMigrations as Record<string, unknown>).state).toBe("failed");
+    expect((body.dbMigrations as Record<string, unknown>).failedMigrations).toEqual(
+      [{ name: "flakyStep", error: "transient failure" }],
+    );
   });
 
   test("returns 200 even if CES is down", async () => {

package/src/__tests__/workspace-git-service.test.ts

@@ -25,6 +25,7 @@ import {
   isDeadlineExpired,
   WorkspaceGitService,
 } from "../workspace/git-service.js";
+import { setConfig } from "./helpers/set-config.js";
 
 describe("WorkspaceGitService", () => {
   let testDir: string;
@@ -356,6 +357,174 @@ describe("WorkspaceGitService", () => {
     });
   });
 
+  describe("batched add and commit", () => {
+    const withStageBatchSize = async (
+      size: number,
+      fn: () => Promise<void>,
+    ) => {
+      const configPath = getWorkspaceConfigPath();
+      mkdirSync(dirname(configPath), { recursive: true });
+      const previous = existsSync(configPath)
+        ? readFileSync(configPath, "utf-8")
+        : null;
+      setConfig("workspaceGit", { stageBatchSize: size });
+      try {
+        await fn();
+      } finally {
+        if (previous === null) {
+          rmSync(configPath, { force: true });
+        } else {
+          writeFileSync(configPath, previous);
+        }
+      }
+    };
+
+    const commitFileLists = (skipInitial = true): string[][] => {
+      const hashes = execFileSync("git", ["log", "--pretty=%H", "--reverse"], {
+        cwd: testDir,
+        encoding: "utf-8",
+      })
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+      const selected = skipInitial ? hashes.slice(1) : hashes;
+      return selected.map((hash) =>
+        execFileSync(
+          "git",
+          ["diff-tree", "--no-commit-id", "--name-only", "-r", hash],
+          { cwd: testDir, encoding: "utf-8" },
+        )
+          .trim()
+          .split("\n")
+          .filter(Boolean),
+      );
+    };
+
+    const trackedFiles = () =>
+      execFileSync("git", ["ls-files"], { cwd: testDir, encoding: "utf-8" })
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+
+    test("splits a large dirty set into multiple add+commit batches", async () => {
+      const service = new WorkspaceGitService(testDir);
+      await service.ensureInitialized();
+
+      const names = ["a.txt", "b.txt", "c.txt", "d.txt", "e.txt"];
+      for (const name of names) {
+        writeFileSync(join(testDir, name), name);
+      }
+
+      await withStageBatchSize(2, async () => {
+        await service.commitChanges("Add files in batches");
+      });
+
+      const batches = commitFileLists();
+      expect(batches).toHaveLength(3);
+      expect(batches[0]).toHaveLength(2);
+      expect(batches[1]).toHaveLength(2);
+      expect(batches[2]).toHaveLength(1);
+      expect(batches.flat().sort()).toEqual(names);
+      for (const name of names) {
+        expect(trackedFiles()).toContain(name);
+      }
+
+      const messages = execFileSync("git", ["log", "--pretty=%B", "--reverse"], {
+        cwd: testDir,
+        encoding: "utf-8",
+      });
+      expect(messages).toContain("batch: 1/3");
+      expect(messages).toContain("batch: 2/3");
+      expect(messages).toContain("batch: 3/3");
+    });
+
+    test("unstage-first keeps an already-staged dump from landing in one commit", async () => {
+      const service = new WorkspaceGitService(testDir);
+      await service.ensureInitialized();
+
+      const names = ["w.txt", "x.txt", "y.txt", "z.txt"];
+      for (const name of names) {
+        writeFileSync(join(testDir, name), name);
+      }
+      execFileSync("git", ["add", "-A"], { cwd: testDir });
+
+      await withStageBatchSize(2, async () => {
+        await service.commitChanges("Split pre-staged files");
+      });
+
+      const batches = commitFileLists();
+      expect(batches).toHaveLength(2);
+      expect(batches[0]).toHaveLength(2);
+      expect(batches[1]).toHaveLength(2);
+      expect(batches.flat().sort()).toEqual(names);
+    });
+
+    test("commitIfDirty batches the same way as commitChanges", async () => {
+      const service = new WorkspaceGitService(testDir);
+      await service.ensureInitialized();
+
+      for (const name of ["p.txt", "q.txt", "r.txt"]) {
+        writeFileSync(join(testDir, name), name);
+      }
+
+      await withStageBatchSize(2, async () => {
+        const result = await service.commitIfDirty(() => ({
+          message: "Dirty batches",
+        }));
+        expect(result.committed).toBe(true);
+      });
+
+      const batches = commitFileLists();
+      expect(batches).toHaveLength(2);
+      expect(batches.flat().sort()).toEqual(["p.txt", "q.txt", "r.txt"]);
+    });
+
+    test("batched commits still skip oversized files", async () => {
+      const service = new WorkspaceGitService(testDir);
+      await service.ensureInitialized();
+      const big = Buffer.alloc(256001, 120);
+
+      writeFileSync(join(testDir, "one.txt"), "one");
+      writeFileSync(join(testDir, "two.txt"), "two");
+      writeFileSync(join(testDir, "three.txt"), "three");
+      writeFileSync(join(testDir, "huge.bin"), big);
+
+      await withStageBatchSize(2, async () => {
+        await service.commitChanges("Mixed size batches");
+      });
+
+      expect(trackedFiles()).toContain("one.txt");
+      expect(trackedFiles()).toContain("two.txt");
+      expect(trackedFiles()).toContain("three.txt");
+      expect(trackedFiles()).not.toContain("huge.bin");
+      expect(existsSync(join(testDir, "huge.bin"))).toBe(true);
+    });
+
+    test("batched commits include deletions", async () => {
+      const service = new WorkspaceGitService(testDir);
+      await service.ensureInitialized();
+
+      for (const name of ["keep.txt", "gone-a.txt", "gone-b.txt", "gone-c.txt"]) {
+        writeFileSync(join(testDir, name), name);
+      }
+      await service.commitChanges("Seed files");
+
+      rmSync(join(testDir, "gone-a.txt"));
+      rmSync(join(testDir, "gone-b.txt"));
+      rmSync(join(testDir, "gone-c.txt"));
+      writeFileSync(join(testDir, "keep.txt"), "updated");
+
+      await withStageBatchSize(2, async () => {
+        await service.commitChanges("Delete in batches");
+      });
+
+      expect(trackedFiles()).toContain("keep.txt");
+      expect(trackedFiles()).not.toContain("gone-a.txt");
+      expect(trackedFiles()).not.toContain("gone-b.txt");
+      expect(trackedFiles()).not.toContain("gone-c.txt");
+    });
+  });
+
   describe("getStatus", () => {
     test("returns clean status for new workspace", async () => {
       const service = new WorkspaceGitService(testDir);
@@ -2100,7 +2269,7 @@ describe("WorkspaceGitService", () => {
       await service.ensureInitialized();
 
       // A loose blob with no referencing commit — e.g. an external
-      // `git add` that stageAllLocked later reset out of the index.
+      // `git add` that staging later reset out of the index.
       const blobSha = execFileSync("git", ["hash-object", "-w", "--stdin"], {
         cwd: testDir,
         input: bigContent(),

package/src/__tests__/workspace-heartbeat-service.test.ts

@@ -23,10 +23,15 @@ import type {
 import {
   _getConsecutiveFailures,
   _resetGitServiceRegistry,
+  getWorkspaceGitService,
   WorkspaceGitService,
 } from "../workspace/git-service.js";
 import {
+  _resetHeartbeatServiceForTests,
   _resetHeartbeatState,
+  commitAllPendingWorkspaceChanges,
+  startWorkspaceHeartbeatService,
+  stopWorkspaceHeartbeatService,
   WorkspaceHeartbeatService,
 } from "../workspace/heartbeat-service.js";
 
@@ -570,4 +575,40 @@ describe("WorkspaceHeartbeatService", () => {
       expect(capturedCtx!.changedFiles).toContain("shutdown-file.txt");
     });
   });
+
+  describe("process singleton", () => {
+    afterEach(async () => {
+      await _resetHeartbeatServiceForTests();
+    });
+
+    test("stopWorkspaceHeartbeatService is a no-op when never started", async () => {
+      await _resetHeartbeatServiceForTests();
+      await stopWorkspaceHeartbeatService();
+    });
+
+    test("startWorkspaceHeartbeatService is idempotent", async () => {
+      await _resetHeartbeatServiceForTests();
+      startWorkspaceHeartbeatService();
+      startWorkspaceHeartbeatService();
+      await stopWorkspaceHeartbeatService();
+    });
+
+    test("commitAllPendingWorkspaceChanges constructs on demand", async () => {
+      await _resetHeartbeatServiceForTests();
+      _resetGitServiceRegistry();
+      const registered = getWorkspaceGitService(testDir);
+      await registered.ensureInitialized();
+      writeFileSync(join(testDir, "shutdown-on-demand.txt"), "pending");
+
+      await commitAllPendingWorkspaceChanges();
+
+      const commitMsg = execFileSync("git", ["log", "-1", "--pretty=%B"], {
+        cwd: testDir,
+        encoding: "utf-8",
+      });
+      expect(commitMsg).toContain("auto-commit");
+      expect(commitMsg).toContain("shutdown");
+      expect(commitMsg).toContain("safety net");
+    });
+  });
 });

package/src/config/bundled-skills/conversation-groups/SKILL.md

@@ -21,6 +21,7 @@ Organize the user's conversations into sidebar groups. Groups are the sections s
 
 ## Usage
 
+- When mentioning a conversation in Vellum chat, link it as `[Title](/assistant/conversations/<id>)`. Use that path only in Vellum chat. Do not use it in Slack, Telegram, Discord, email, or notifications.
 - `conversation_move_to_group` defaults to the **current** conversation, so "file this chat under Work" needs no conversation id.
 - Groups can be referenced by name (case-insensitive) or id. Prefer names; fall back to ids when names are ambiguous.
 - When the user asks to organize their conversations, check the existing groups first (`conversation_group_list`) and reuse a fitting group rather than creating near-duplicates ("Work" vs "Work stuff").