@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091853.fbaa2ae

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.8.8
+  version: 0.8.9
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -95,7 +95,12 @@ paths:
     post:
       operationId: acp_by_id_steer_post
       summary: Steer ACP session
-      description: Send a steering instruction to an active ACP session.
+      description:
+        "Send a steering instruction to an ACP session. Sessions no longer in memory (completed, or lost to a
+        daemon restart) are transparently resumed from persisted history first, when the agent supports ACP session
+        loading. Resuming a terminal session re-spawns the host agent, so it requires guardian approval: the route acks
+        immediately with approvalPending=true and performs the resume in the background once approved, streaming results
+        over SSE."
       tags:
         - acp
       responses:
@@ -110,6 +115,14 @@ paths:
                     type: string
                   steered:
                     type: boolean
+                  resumed:
+                    description: True when the session was resumed from persisted history before steering.
+                    type: boolean
+                  approvalPending:
+                    description:
+                      True when the steer triggered a guardian-approval-gated resume that will run asynchronously; watch SSE for
+                      the outcome.
+                    type: boolean
                 required:
                   - acpSessionId
                   - steered
@@ -136,7 +149,9 @@ paths:
     delete:
       operationId: acp_sessions_delete
       summary: Bulk-clear terminal ACP sessions
-      description: Remove every terminal-state row (completed/failed/cancelled) from the persisted acp_session_history table.
+      description:
+        Remove every terminal-state row (completed/failed/cancelled) from the persisted acp_session_history table.
+        Rows whose session is currently active in memory (e.g. resumed) or has a resume in flight are excluded.
       tags:
         - acp
       responses:
@@ -238,8 +253,8 @@ paths:
       operationId: acp_sessions_by_id_delete
       summary: Delete ACP session from history
       description:
-        Remove a persisted ACP session row. Rejects with 409 when the session is still active in memory; idempotent
-        for unknown ids.
+        Remove a persisted ACP session row. Rejects with 409 when the session is still active in memory or has a
+        resume in flight; idempotent for unknown ids.
       tags:
         - acp
       responses:
@@ -473,6 +488,8 @@ paths:
                           type: string
                         createdAt:
                           type: number
+                        updatedAt:
+                          type: number
                         version:
                           type: string
                         contentId:
@@ -481,6 +498,7 @@ paths:
                         - id
                         - name
                         - createdAt
+                        - updatedAt
                         - version
                         - contentId
                       additionalProperties: false
@@ -15847,10 +15865,10 @@ paths:
               type: object
               properties: {}
               additionalProperties: false
-  /v1/memory/v3/health:
+  /v1/memory/v3/backfill-sections:
     post:
-      operationId: memory_v3_health_post
-      summary: Print the v3 structural health report (read-only)
+      operationId: memory_v3_backfillsections_post
+      summary: "One-time: embed every page's sections (incl synthetic skill/CLI rows) into the dense store"
       tags:
         - memory
       responses:
@@ -15861,31 +15879,16 @@ paths:
               schema:
                 type: object
                 properties:
-                  rendered:
-                    type: string
-                  counts:
-                    type: object
-                    properties:
-                      unassigned:
-                        type: number
-                      danglingRefs:
-                        type: number
-                      novelClusters:
-                        type: number
-                      oversizedLeaves:
-                        type: number
-                      tinyLeaves:
-                        type: number
-                    required:
-                      - unassigned
-                      - danglingRefs
-                      - novelClusters
-                      - oversizedLeaves
-                      - tinyLeaves
-                    additionalProperties: false
+                  articles:
+                    type: number
+                  sections:
+                    type: number
+                  failures:
+                    type: number
                 required:
-                  - rendered
-                  - counts
+                  - articles
+                  - sections
+                  - failures
                 additionalProperties: false
   /v1/memory/v3/rebuild-index:
     post:
@@ -15907,93 +15910,6 @@ paths:
                 required:
                   - ok
                 additionalProperties: false
-  /v1/memory/v3/reconcile:
-    post:
-      operationId: memory_v3_reconcile_post
-      summary: v1 convergence/prune pass over page+core refs (no rename detection without a prior snapshot)
-      tags:
-        - memory
-      responses:
-        "200":
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  renames:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        id:
-                          type: string
-                        oldPath:
-                          type: string
-                        newPath:
-                          type: string
-                      required:
-                        - oldPath
-                        - newPath
-                      additionalProperties: false
-                  deleted:
-                    type: array
-                    items:
-                      type: string
-                  prunedCore:
-                    type: array
-                    items:
-                      type: string
-                required:
-                  - renames
-                  - deleted
-                  - prunedCore
-                additionalProperties: false
-  /v1/memory/v3/set-core:
-    post:
-      operationId: memory_v3_setcore_post
-      summary: Add/remove always-on core leaves (validates + previews cost)
-      tags:
-        - memory
-      responses:
-        "200":
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  nextCore:
-                    type: array
-                    items:
-                      type: string
-                  alwaysOnPageCount:
-                    type: number
-                  written:
-                    type: boolean
-                required:
-                  - nextCore
-                  - alwaysOnPageCount
-                  - written
-                additionalProperties: false
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                add:
-                  type: array
-                  items:
-                    type: string
-                remove:
-                  type: array
-                  items:
-                    type: string
-                write:
-                  type: boolean
-              additionalProperties: false
   /v1/messages:
     get:
       operationId: messages_get
@@ -16020,8 +15936,13 @@ paths:
                           type: array
                           items:
                             type: string
+                        clientMessageId:
+                          type: string
                         role:
                           type: string
+                          enum:
+                            - user
+                            - assistant
                         content:
                           type: string
                         timestamp:
@@ -16413,6 +16334,10 @@ paths:
                                     const: thinking
                                   thinking:
                                     type: string
+                                  startedAt:
+                                    type: number
+                                  completedAt:
+                                    type: number
                                 required:
                                   - type
                                   - thinking
@@ -16985,6 +16910,12 @@ paths:
                   type: string
                 clientTimezone:
                   type: string
+                clientMessageId:
+                  type: string
+                  description:
+                    Client-generated idempotency nonce. Persisted on the row and echoed back on the message_echo event and the
+                    messages snapshot so the client can correlate its optimistic row by identity. Duplicate sends for
+                    the same (conversation, clientMessageId) are deduplicated server-side.
                 inferenceProfile:
                   anyOf:
                     - type: string
@@ -19416,6 +19347,181 @@ paths:
           required: true
           schema:
             type: string
+    get:
+      operationId: plugins_by_name_get
+      summary: Get a plugin's detail view
+      description:
+        Resolve a single plugin's tracked metadata (description, homepage, license, version, source) plus its
+        README markdown. Unions the locally installed copy, the marketplace manifest, and the plugin's repository at the
+        pinned ref — preferring the installed copy. Names that are neither installed nor present in the catalog return
+        404. Powers the web plugin detail page; mirrors `GET /v1/skills/:id`.
+      tags:
+        - plugins
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  name:
+                    type: string
+                    description: Install name. Matches `assistant plugins install <name>`.
+                  installed:
+                    type: boolean
+                    description: Whether a copy is materialized under `<workspaceDir>/plugins/<name>/`.
+                  description:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: Short description, best-effort across disk, manifest, and repo.
+                  homepage:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: Project homepage URL, when known.
+                  license:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: SPDX license expression, when known.
+                  version:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: Resolved version (installed copy first, then repo `package.json`).
+                  source:
+                    oneOf:
+                      - type: object
+                        properties:
+                          kind:
+                            type: string
+                            const: first-party
+                        required:
+                          - kind
+                        additionalProperties: false
+                      - type: object
+                        properties:
+                          kind:
+                            type: string
+                            const: github
+                          repo:
+                            type: string
+                            description: "`owner/repo` of the external plugin repository."
+                          path:
+                            description: Directory within the repo, when the plugin is not at the root.
+                            type: string
+                          ref:
+                            type: string
+                            description: Pinned git ref the plugin is fetched from.
+                        required:
+                          - kind
+                          - repo
+                          - ref
+                        additionalProperties: false
+                    description: "Origin of the match: a first-party in-repo plugin or a whitelisted external one."
+                  readme:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: README markdown, or null when the plugin ships none.
+                  ref:
+                    type: string
+                    description: Git ref the catalog metadata / README were resolved at.
+                required:
+                  - name
+                  - installed
+                  - description
+                  - homepage
+                  - license
+                  - version
+                  - source
+                  - readme
+                  - ref
+                additionalProperties: false
+        "400":
+          description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
+        "404":
+          description: No installed copy and no catalog entry claims the given name.
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: ref
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Optional git ref to read catalog metadata / README at. Defaults to the CLI's `DEFAULT_PLUGIN_REF`.
+  /v1/plugins/install:
+    post:
+      operationId: plugins_install_post
+      summary: Install a plugin
+      description:
+        "Install a plugin by name from the canonical source — a whitelisted `experimental/plugins/marketplace.json`
+        entry, else the first-party `experimental/plugins/<name>/` convention. Always resolves against the curated
+        default git ref (no caller-supplied ref): installing from an unreviewed revision would bypass the
+        marketplace/first-party curation boundary and let attacker-controlled code be loaded. Materializes the plugin
+        under `<workspaceDir>/plugins/<name>/`; the assistant must be restarted to load it. Mirrors the CLI's `assistant
+        plugins install <name>`. An already-installed name without `force` returns 409; a name that resolves to nothing
+        returns 404. Sibling to `POST /v1/skills/install`."
+      tags:
+        - plugins
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                    const: true
+                  name:
+                    type: string
+                    description: Install name that was materialized.
+                  target:
+                    type: string
+                    description: Absolute path the plugin was materialized into on the host.
+                  fileCount:
+                    type: number
+                    description: Number of files written for the installed plugin.
+                  ref:
+                    type: string
+                    description: Git ref the plugin was fetched from.
+                required:
+                  - ok
+                  - name
+                  - target
+                  - fileCount
+                  - ref
+                additionalProperties: false
+        "400":
+          description: The request body was missing `name` or the name failed sanitization.
+        "404":
+          description: No plugin resolves to the given name at the requested ref.
+        "409":
+          description: A plugin with the same name is already installed and `force` was not set.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                  description: Install name to resolve against the catalog (first-party directory or marketplace entry).
+                force:
+                  description: Overwrite an existing install in place. Defaults to false.
+                  type: boolean
+              required:
+                - name
+              additionalProperties: false
   /v1/plugins/search:
     get:
       operationId: plugins_search_get
@@ -19447,13 +19553,49 @@ paths:
                       properties:
                         name:
                           type: string
-                          description: Directory name under `experimental/plugins/`. Matches `assistant plugins install <name>`.
+                          description: Install name. Matches `assistant plugins install <name>`.
                         path:
                           type: string
-                          description: Repo-relative path of the match (e.g. `experimental/plugins/<name>`).
+                          description:
+                            "Human-readable origin: a repo-relative path (`experimental/plugins/<name>`) for first-party plugins or a
+                            `github:owner/repo@ref` locator for external ones."
+                        description:
+                          description: Short description, when known (external entries only today).
+                          type: string
+                        source:
+                          oneOf:
+                            - type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  const: first-party
+                              required:
+                                - kind
+                              additionalProperties: false
+                            - type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  const: github
+                                repo:
+                                  type: string
+                                  description: "`owner/repo` of the external plugin repository."
+                                path:
+                                  description: Directory within the repo, when the plugin is not at the root.
+                                  type: string
+                                ref:
+                                  type: string
+                                  description: Pinned git ref the plugin is fetched from.
+                              required:
+                                - kind
+                                - repo
+                                - ref
+                              additionalProperties: false
+                          description: "Origin of the match: a first-party in-repo plugin or a whitelisted external one."
                       required:
                         - name
                         - path
+                        - source
                       additionalProperties: false
                     description: Directory matches, sorted alphabetically by name.
                 required:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.8.8",
+  "version": "0.8.9-dev.202606091853.fbaa2ae",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -33,7 +33,7 @@
     "prepack": "node ../scripts/prepack-bundled-deps.mjs"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.16.1",
+    "@agentclientprotocol/sdk": "0.25.0",
     "@anthropic-ai/sdk": "0.78.0",
     "@google/genai": "1.45.0",
     "@modelcontextprotocol/sdk": "1.27.1",

package/src/__tests__/activation-early-marking.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Early activation-session marking.
+ *
+ * The agent loop resolves TOOLS before the SYSTEM PROMPT, so the activation
+ * marker must be written before tool resolution on the first activation-rail
+ * turn — otherwise the `activation` skill is not preactivated and the emit
+ * handler is gated off for the very turn that emits Moment 1. The marking lives
+ * in `applyBootstrapTemplate`, which is called from `setOnboardingContext` (the
+ * earliest point the conversation knows its bootstrap selection) as well as
+ * from `buildSystemPrompt` as an idempotent backstop.
+ *
+ * These tests exercise `applyBootstrapTemplate` directly against the real
+ * DB-backed `isActivationSession` and a real workspace BOOTSTRAP.md, proving the
+ * marker is set INDEPENDENT of any `buildSystemPrompt` render.
+ */
+
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const TEST_DIR = process.env.VELLUM_WORKSPACE_DIR!;
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+const { applyBootstrapTemplate } = await import("../prompts/system-prompt.js");
+const { isActivationSession } =
+  await import("../memory/activation-session-store.js");
+const { ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE } =
+  await import("../telemetry/activation-funnel.js");
+const { getDb } = await import("../memory/db-connection.js");
+const { initializeDb } = await import("../memory/db-init.js");
+const { activationSessions } = await import("../memory/schema.js");
+
+initializeDb();
+
+/** Seed the workspace BOOTSTRAP.md with the unmodified generic template so the
+ *  one-shot reseed inside `applyBootstrapTemplate` fires. */
+function seedGenericBootstrap(): void {
+  mkdirSync(TEST_DIR, { recursive: true });
+  const generic = readFileSync(
+    join(import.meta.dirname, "..", "prompts", "templates", "BOOTSTRAP.md"),
+    "utf-8",
+  );
+  writeFileSync(join(TEST_DIR, "BOOTSTRAP.md"), generic, "utf-8");
+}
+
+describe("applyBootstrapTemplate — early activation marking", () => {
+  beforeEach(() => {
+    getDb().delete(activationSessions).run();
+  });
+
+  test("marks the conversation when the activation-rail template is applied", () => {
+    seedGenericBootstrap();
+    expect(isActivationSession("rail-conv")).toBe(false);
+
+    // No buildSystemPrompt call — marking must happen here.
+    applyBootstrapTemplate(ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE, "rail-conv");
+
+    expect(isActivationSession("rail-conv")).toBe(true);
+  });
+
+  test("does not mark when a non-rail bootstrap template is applied", () => {
+    seedGenericBootstrap();
+
+    applyBootstrapTemplate("BOOTSTRAP-REFERENCE.md", "non-rail-conv");
+
+    expect(isActivationSession("non-rail-conv")).toBe(false);
+  });
+
+  test("does not mark when no conversation id is supplied", () => {
+    seedGenericBootstrap();
+
+    applyBootstrapTemplate(ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE);
+
+    // Nothing to assert by id; confirm the table stayed empty.
+    const rows = getDb().select().from(activationSessions).all();
+    expect(rows.length).toBe(0);
+  });
+
+  test("does not mark when BOOTSTRAP.md is customized to something else", () => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    // A user-customized BOOTSTRAP.md is neither the generic template (so the
+    // reseed no-ops) nor the activation-rail template — the rail is not active.
+    writeFileSync(
+      join(TEST_DIR, "BOOTSTRAP.md"),
+      "# My custom bootstrap\n",
+      "utf-8",
+    );
+
+    applyBootstrapTemplate(ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE, "custom-conv");
+
+    expect(isActivationSession("custom-conv")).toBe(false);
+  });
+
+  test("marks idempotently when BOOTSTRAP.md already holds the rail template", () => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    // Simulate a later turn: BOOTSTRAP.md already holds the rail template, so
+    // the reseed no-ops but marking still fires (idempotent backstop).
+    copyFileSync(
+      join(
+        import.meta.dirname,
+        "..",
+        "prompts",
+        "templates",
+        ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE,
+      ),
+      join(TEST_DIR, "BOOTSTRAP.md"),
+    );
+
+    applyBootstrapTemplate(ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE, "rail-conv-2");
+    applyBootstrapTemplate(ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE, "rail-conv-2");
+
+    expect(isActivationSession("rail-conv-2")).toBe(true);
+  });
+});