@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/ARCHITECTURE.md

@@ -1088,12 +1088,12 @@ All overflow recovery settings live under `contextWindow.overflowRecovery` in th
 
 ### Key Source Files
 
-| File                                     | Purpose                                                                       |
-| ---------------------------------------- | ----------------------------------------------------------------------------- |
-| `src/daemon/context-overflow-reducer.ts` | Tiered reducer: four-tier pipeline with idempotent steps and cumulative state |
-| `src/daemon/context-overflow-policy.ts`  | Overflow policy resolver: maps config + interactivity to concrete action      |
-| `src/daemon/conversation-agent-loop.ts`  | Integration: preflight budget check, convergence loop, emergency compaction   |
-| `src/config/core-schema.ts`              | `ContextOverflowRecoveryConfigSchema` with defaults and validation            |
+| File                                                          | Purpose                                                                       |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `src/plugins/defaults/compaction/context-overflow-reducer.ts` | Tiered reducer: four-tier pipeline with idempotent steps and cumulative state |
+| `src/daemon/context-overflow-policy.ts`                       | Overflow policy resolver: maps config + interactivity to concrete action      |
+| `src/daemon/conversation-agent-loop.ts`                       | Integration: preflight budget check, convergence loop, emergency compaction   |
+| `src/config/core-schema.ts`                                   | `ContextOverflowRecoveryConfigSchema` with defaults and validation            |
 
 ---
 

package/bun.lock

@@ -5,7 +5,7 @@
     "": {
       "name": "@vellumai/assistant",
       "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",
@@ -71,7 +71,7 @@
     "path-to-regexp": "8.4.2",
   },
   "packages": {
-    "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.16.1", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-1ad+Sc/0sCtZGHthxxvgEUo5Wsbw16I+aF+YwdiLnPwkZG8KAGUEAPK6LM6Pf69lCyJPt1Aomk1d+8oE3C4ZEw=="],
+    "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.25.0", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-wU1VgXNtMvdVotX49txc3WJUDV+/QbLpsgjMvFhlRmp37osdLbI7L7y+iwAlQATwfjLxcv1r1p3ZxZBcXlGhcQ=="],
 
     "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.78.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-PzQhR715td/m1UaaN5hHXjYB8Gl2lF9UVhrrGrZeysiF6Rb74Wc9GCB8hzLdzmQtBd1qe89F9OptgB9Za1Ib5w=="],
 

package/examples/plugins/echo/README.md

@@ -1,43 +1,59 @@
 # Echo plugin
 
-Minimal example plugin. Observes every assistant pipeline and logs one JSON
-line per invocation to `stderr`:
+Minimal example plugin. Observes the assistant's turn-lifecycle hooks and logs
+one JSON line per hook invocation to `stderr`:
 
 ```json
-{"plugin":"echo","pipeline":"compaction","durationMs":1590,"outcome":"success"}
-{"plugin":"echo","pipeline":"overflowReduce","durationMs":42,"outcome":"success"}
+{
+  "plugin": "echo",
+  "hook": "post-tool-use",
+  "conversationId": "conv_abc123"
+}
 ```
 
 Use this as a starting point for writing your own plugin, or as a quick way
-to eyeball which pipelines fire during a conversation and how long they
-take.
+to eyeball which hooks fire during a conversation.
 
-For the full plugin authoring guide, see
-[`assistant/docs/plugins.md`](../../../docs/plugins.md).
+For the full plugin authoring guide — manifest shape, every contribution
+surface, hook patterns, and conventions — see
+[`experimental/plugins/README.md`](../../../../experimental/plugins/README.md).
+[`simple-memory`](../../../../experimental/plugins/simple-memory/) is the
+canonical reference implementation that exercises every wired surface.
 
 ## What it does
 
-- Registers one observer middleware per slot in
-  `PipelineMiddlewareMap` — `compaction`, `overflowReduce`, and
-  `circuitBreaker`.
-- Each middleware calls `next(args)` to pass the request through unchanged,
-  measures wall-clock duration, and emits one line to `stderr` whether the
-  downstream succeeded or threw.
-- Never modifies arguments, never rewrites results, never swallows errors.
-  It is purely observational — safe to stack alongside any other plugin.
+- Contributes one observer hook per turn-lifecycle event:
+  `user-prompt-submit`, `post-tool-use`, and `stop`.
+- Each hook emits one line to `stderr` and returns `void`, so the threaded
+  context flows through unchanged.
+- Never modifies the turn's messages, tool results, or stop decision. It is
+  purely observational — safe to stack alongside any other plugin.
+
+## Directory layout
+
+The assistant discovers a plugin by its `package.json` manifest and builds the
+`Plugin` from the interface directories — `hooks/<name>.ts` files whose default
+export is the hook function. Files under `src/` are internal helpers and are
+not walked by the loader.
+
+```
+echo/
+├── package.json               # Manifest (name + @vellumai/plugin-api range)
+├── README.md
+├── hooks/
+│   ├── user-prompt-submit.ts  # default export = hook function
+│   ├── post-tool-use.ts
+│   └── stop.ts
+└── src/
+    └── emit.ts                # shared stderr emitter (not a surface)
+```
 
 ## Install locally
 
 The assistant scans `<workspaceDir>/plugins/*` (e.g.
-`~/.vellum/workspace/plugins/`) for subdirectories containing a
-`register.{ts,js}` file and dynamic-imports each one during assistant
-startup. Dropping (or symlinking) this directory in place is enough to
-enable it.
-
-The plugin reads `registerPlugin` from `globalThis.__vellumPluginRuntime`,
-which the daemon attaches before scanning plugins. This works against both
-the `bun --compile`-bundled daemon binary AND a daemon running from
-source — no special install procedure required either way.
+`~/.vellum/workspace/plugins/`) for subdirectories containing a `package.json`
+and loads each one during assistant startup. Dropping (or symlinking) this
+directory in place is enough to enable it.
 
 ### Option 1 — symlink from the repo (simplest in-repo dev)
 
@@ -54,23 +70,10 @@ pick up changes.
 ### Option 2 — standalone copy
 
 A plain `cp -R` of this directory into `~/.vellum/workspace/plugins/echo/`
-works for the runtime imports (which go through the global bridge), but
-the `import type` lines at the top of `register.ts` still resolve into
-the in-repo assistant source tree. If your standalone copy lives outside
-a vellum-assistant checkout, rewrite those `import type` paths to point
-at an absolute path inside any checkout — they're erased at compile time
-and have no module-identity effect at runtime:
-
-```ts
-// before (repo-local):
-import type { VellumPluginRuntime } from "../../../src/plugins/external-api.js";
-import type { Plugin } from "../../../src/plugins/types.js";
-// after (standalone, edit to your checkout path):
-import type { VellumPluginRuntime } from "/path/to/vellum-assistant/assistant/src/plugins/external-api.js";
-import type { Plugin } from "/path/to/vellum-assistant/assistant/src/plugins/types.js";
-```
-
-No runtime-import rewriting is needed — the bridge already handles that.
+works as-is. The hooks import their types from the public `@vellumai/plugin-api`
+specifier, which the daemon materializes as a workspace-level shim before it
+loads any plugin — so the copied directory resolves it without any path
+rewriting, in or out of a vellum-assistant checkout.
 
 ### Restart the assistant
 
@@ -84,24 +87,23 @@ vellum restart
 ## Verify it works
 
 With the plugin installed and the assistant restarted, send any message
-that exercises a pipeline — a conversation turn, a tool call, a title
-generation — and tail the assistant's stderr log:
+that exercises a turn — a conversation reply, a tool call — and tail the
+assistant's stderr log:
 
 ```bash
 tail -f ~/.vellum/daemon.log
 ```
 
-You should see one line per pipeline invocation, similar to:
+You should see one line per hook invocation, similar to:
 
 ```json
-{"plugin":"echo","pipeline":"compaction","durationMs":1590,"outcome":"success"}
-{"plugin":"echo","pipeline":"overflowReduce","durationMs":42,"outcome":"success"}
+{
+  "plugin": "echo",
+  "hook": "post-tool-use",
+  "conversationId": "conv_abc123"
+}
 ```
 
-If a pipeline throws (for example, a tool that errors out), you'll see a
-line with `"outcome":"error"` — the plugin rethrows after logging so the
-original error still propagates.
-
 ## Uninstall
 
 Remove the symlink (or the copied directory) and restart the assistant:
@@ -113,14 +115,13 @@ vellum restart
 
 ## Next steps
 
-- Read [`assistant/docs/plugins.md`](../../../docs/plugins.md) for the full
-  plugin authoring guide: manifest shape, middleware patterns
-  (observe / transform / short-circuit / veto), strict-fail semantics, the
-  per-pipeline timeout table, credential and config access, and
-  troubleshooting.
+- Read [`experimental/plugins/README.md`](../../../../experimental/plugins/README.md)
+  for the full plugin authoring guide: manifest shape, every contribution
+  surface, hook patterns (observe / transform), tool contributions, and
+  conventions.
 - Look at the first-party default plugins under
-  `assistant/src/plugins/defaults/` for examples of non-observational
-  middleware.
+  `assistant/src/plugins/defaults/` for examples of hooks that transform a
+  turn rather than just observing it.
 - Build your own plugin by copying this directory, renaming the manifest
-  `name`, and replacing the observer with a middleware that does whatever
-  you need.
+  `name`, and replacing the observer hooks with ones that do whatever you
+  need.

package/examples/plugins/echo/hooks/post-tool-use.ts

@@ -0,0 +1,18 @@
+/**
+ * `post-tool-use` hook for the echo plugin.
+ *
+ * Purely observational — logs one structured line to stderr and returns
+ * `void`, leaving the tool result untouched.
+ *
+ * Convention: the default export is the function the harness invokes.
+ */
+
+import type { PostToolUseContext } from "@vellumai/plugin-api";
+
+import { emit } from "../src/emit.js";
+
+export default async function postToolUse(
+  ctx: PostToolUseContext,
+): Promise<void> {
+  emit("post-tool-use", ctx.conversationId);
+}

package/examples/plugins/echo/hooks/stop.ts

@@ -0,0 +1,16 @@
+/**
+ * `stop` hook for the echo plugin.
+ *
+ * Purely observational — logs one structured line to stderr and returns
+ * `void`, leaving the stop decision untouched.
+ *
+ * Convention: the default export is the function the harness invokes.
+ */
+
+import type { StopContext } from "@vellumai/plugin-api";
+
+import { emit } from "../src/emit.js";
+
+export default async function stop(ctx: StopContext): Promise<void> {
+  emit("stop", ctx.conversationId);
+}

package/examples/plugins/echo/hooks/user-prompt-submit.ts

@@ -0,0 +1,18 @@
+/**
+ * `user-prompt-submit` hook for the echo plugin.
+ *
+ * Purely observational — logs one structured line to stderr and returns
+ * `void`, leaving the threaded context (message list, injections) untouched.
+ *
+ * Convention: the default export is the function the harness invokes.
+ */
+
+import type { UserPromptSubmitContext } from "@vellumai/plugin-api";
+
+import { emit } from "../src/emit.js";
+
+export default async function userPromptSubmit(
+  ctx: UserPromptSubmitContext,
+): Promise<void> {
+  emit("user-prompt-submit", ctx.conversationId);
+}

package/examples/plugins/echo/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@vellumai/plugin-echo-example",
   "version": "0.1.0",
-  "description": "Example plugin that observes every assistant pipeline and logs one structured line per invocation to stderr. Meant as an authoring reference — not shipped with the assistant runtime.",
+  "description": "Example plugin that observes every assistant turn-lifecycle hook and logs one structured line per invocation to stderr. Meant as an authoring reference — not shipped with the assistant runtime.",
   "private": true,
   "license": "MIT",
   "type": "module",
-  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },

package/examples/plugins/echo/src/emit.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared stderr emitter for the echo plugin's hooks.
+ *
+ * Files under `src/` are internal helpers — the external-plugin loader does
+ * not walk this directory, so it contributes no surface of its own. The
+ * `hooks/` files import from here.
+ */
+
+export const PLUGIN_NAME = "echo";
+
+/**
+ * One line written to stderr per hook invocation. Kept intentionally compact —
+ * pino-style JSON so operators can pipe the assistant's stderr through `jq`
+ * without reshaping.
+ */
+export function emit(hook: string, conversationId: string): void {
+  const record = { plugin: PLUGIN_NAME, hook, conversationId };
+  process.stderr.write(`${JSON.stringify(record)}\n`);
+}

package/node_modules/@vellumai/skill-host-contracts/src/skill-host.ts

@@ -194,8 +194,12 @@ export interface ProvidersFacet {
 // Memory
 // ---------------------------------------------------------------------------
 
-/** Valid message roles for `memory.addMessage`. */
-export type MessageRole = "user" | "assistant" | "system";
+/**
+ * Valid message roles for `memory.addMessage`. The messages store is
+ * UI-facing (`ConversationMessage`), so only renderable turns are accepted —
+ * agent-context `system` rows are not persisted via this facet.
+ */
+export type MessageRole = "user" | "assistant";
 
 /**
  * Callable signature for `memory.addMessage`. Mirrors the daemon's
@@ -247,10 +251,7 @@ export interface Subscription {
 export interface EventsFacet {
   publish(event: AssistantEvent): Promise<void>;
   subscribe(filter: Filter, cb: AssistantEventCallback): Subscription;
-  buildEvent(
-    message: ServerMessage,
-    conversationId?: string,
-  ): AssistantEvent;
+  buildEvent(message: ServerMessage, conversationId?: string): AssistantEvent;
 }
 
 // ---------------------------------------------------------------------------

package/openapi.yaml

@@ -95,7 +95,9 @@ 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.
       tags:
         - acp
       responses:
@@ -110,6 +112,9 @@ paths:
                     type: string
                   steered:
                     type: boolean
+                  resumed:
+                    description: True when the session was resumed from persisted history before steering.
+                    type: boolean
                 required:
                   - acpSessionId
                   - steered
@@ -136,7 +141,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 +245,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:
@@ -16020,8 +16027,13 @@ paths:
                           type: array
                           items:
                             type: string
+                        clientMessageId:
+                          type: string
                         role:
                           type: string
+                          enum:
+                            - user
+                            - assistant
                         content:
                           type: string
                         timestamp:
@@ -16985,6 +16997,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 +19434,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 +19640,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-staging.2",
   "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",