@vellumai/assistant 0.8.7-dev.202606052232.2ddc989 → 0.8.8

package/examples/plugins/echo/README.md

@@ -1,59 +1,43 @@
 # Echo plugin
 
-Minimal example plugin. Observes the assistant's turn-lifecycle hooks and logs
-one JSON line per hook invocation to `stderr`:
+Minimal example plugin. Observes every assistant pipeline and logs one JSON
+line per invocation to `stderr`:
 
 ```json
-{
-  "plugin": "echo",
-  "hook": "post-tool-use",
-  "conversationId": "conv_abc123"
-}
+{"plugin":"echo","pipeline":"compaction","durationMs":1590,"outcome":"success"}
+{"plugin":"echo","pipeline":"overflowReduce","durationMs":42,"outcome":"success"}
 ```
 
 Use this as a starting point for writing your own plugin, or as a quick way
-to eyeball which hooks fire during a conversation.
+to eyeball which pipelines fire during a conversation and how long they
+take.
 
-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.
+For the full plugin authoring guide, see
+[`assistant/docs/plugins.md`](../../../docs/plugins.md).
 
 ## What it does
 
-- 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)
-```
+- 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.
 
 ## Install locally
 
 The assistant scans `<workspaceDir>/plugins/*` (e.g.
-`~/.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.
+`~/.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.
 
 ### Option 1 — symlink from the repo (simplest in-repo dev)
 
@@ -70,10 +54,23 @@ pick up changes.
 ### Option 2 — standalone copy
 
 A plain `cp -R` of this directory into `~/.vellum/workspace/plugins/echo/`
-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.
+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.
 
 ### Restart the assistant
 
@@ -87,23 +84,24 @@ vellum restart
 ## Verify it works
 
 With the plugin installed and the assistant restarted, send any message
-that exercises a turn — a conversation reply, a tool call — and tail the
-assistant's stderr log:
+that exercises a pipeline — a conversation turn, a tool call, a title
+generation — and tail the assistant's stderr log:
 
 ```bash
 tail -f ~/.vellum/daemon.log
 ```
 
-You should see one line per hook invocation, similar to:
+You should see one line per pipeline invocation, similar to:
 
 ```json
-{
-  "plugin": "echo",
-  "hook": "post-tool-use",
-  "conversationId": "conv_abc123"
-}
+{"plugin":"echo","pipeline":"compaction","durationMs":1590,"outcome":"success"}
+{"plugin":"echo","pipeline":"overflowReduce","durationMs":42,"outcome":"success"}
 ```
 
+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:
@@ -115,13 +113,14 @@ vellum restart
 
 ## Next steps
 
-- 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.
+- 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.
 - Look at the first-party default plugins under
-  `assistant/src/plugins/defaults/` for examples of hooks that transform a
-  turn rather than just observing it.
+  `assistant/src/plugins/defaults/` for examples of non-observational
+  middleware.
 - Build your own plugin by copying this directory, renaming the manifest
-  `name`, and replacing the observer hooks with ones that do whatever you
-  need.
+  `name`, and replacing the observer with a middleware that does whatever
+  you need.

package/examples/plugins/echo/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@vellumai/plugin-echo-example",
   "version": "0.1.0",
-  "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.",
+  "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.",
   "private": true,
   "license": "MIT",
   "type": "module",
+  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },

package/examples/plugins/echo/register.ts

@@ -0,0 +1,143 @@
+/**
+ * Echo plugin — observes every assistant pipeline and logs one structured
+ * line per invocation to stderr.
+ *
+ * Bundled in the repository as an authoring reference. To try it locally,
+ * symlink (or copy) this directory into `<workspaceDir>/plugins/echo/` and
+ * restart the assistant. See `README.md` in this directory for the install
+ * recipe and `assistant/docs/plugins.md` for general plugin authoring docs.
+ *
+ * ## Runtime bridge
+ *
+ * The plugin reads `registerPlugin` from `globalThis.__vellumPluginRuntime`,
+ * a stable handle the daemon attaches at startup. This lets the same plugin
+ * file work whether the daemon is running from source (relative or absolute
+ * imports would resolve to the daemon's modules) or as a `bun --compile`
+ * binary (where absolute imports would load a disjoint disk copy with a
+ * separate registry instance). The bridge is documented in
+ * `assistant/src/plugins/external-api.ts`.
+ *
+ * Type imports below still come from the in-repo source tree. Types are
+ * erased at runtime, so they don't affect module identity — but they only
+ * resolve while this file lives inside the vellum-assistant checkout. For a
+ * standalone-copy install, rewrite the `import type` paths to absolute paths
+ * inside a checkout (or vendor only the types you need).
+ *
+ * ## Design
+ *
+ * - Registers an observer middleware on every slot of `PipelineMiddlewareMap`.
+ * - Each middleware records a start timestamp, calls `next(args)`, and on
+ *   return — whether successful or not — emits one JSON line on `stderr` with
+ *   `{ plugin, pipeline, durationMs, outcome }`. A `try { return await next(); }
+ *   catch { outcome = "error"; rethrow; } finally { log(); }` pattern keeps the
+ *   observation strictly non-interfering: the plugin never swallows errors
+ *   and never rewrites arguments or results.
+ * - Middleware is declared as async functions with stable names so the
+ *   pipeline runner's `chain` log field attributes them correctly.
+ *
+ * The file exports no named symbols at module level — it only runs
+ * `registerPlugin(echoPlugin)` as an import-time side effect, matching the
+ * user-plugin-loader contract (see `assistant/src/plugins/user-loader.ts`).
+ */
+
+import type { VellumPluginRuntime } from "../../../src/plugins/external-api.js";
+import type {
+  CircuitBreakerArgs,
+  CircuitBreakerResult,
+  CompactionArgs,
+  CompactionResult,
+  OverflowReduceArgs,
+  OverflowReduceResult,
+  Plugin,
+} from "../../../src/plugins/types.js";
+
+const runtime = (globalThis as { __vellumPluginRuntime?: VellumPluginRuntime })
+  .__vellumPluginRuntime;
+if (!runtime || runtime.version !== 1) {
+  throw new Error(
+    "echo plugin: globalThis.__vellumPluginRuntime is missing or has an unexpected version — install a recent assistant build",
+  );
+}
+const { registerPlugin } = runtime;
+
+const PLUGIN_NAME = "echo";
+
+/**
+ * One line written to stderr per pipeline invocation. Kept intentionally
+ * compact — pino-style JSON so operators can pipe the assistant's stderr
+ * through `jq` without reshaping.
+ */
+function emit(
+  pipelineName: string,
+  startMs: number,
+  outcome: "success" | "error",
+): void {
+  const durationMs = Math.round(performance.now() - startMs);
+  const record = {
+    plugin: PLUGIN_NAME,
+    pipeline: pipelineName,
+    durationMs,
+    outcome,
+  };
+  process.stderr.write(`${JSON.stringify(record)}\n`);
+}
+
+/**
+ * Factory for a pipeline-agnostic observer middleware. The returned function
+ * carries a `name` so `runPipeline`'s `chain` log field attributes this
+ * plugin's frame correctly. Error paths rethrow — the plugin is purely
+ * observational and must never change the turn's outcome.
+ */
+function makeObserver<A, R>(
+  pipelineName: string,
+): (args: A, next: (args: A) => Promise<R>, _ctx: unknown) => Promise<R> {
+  const fn = async function echoObserver(
+    args: A,
+    next: (args: A) => Promise<R>,
+    _ctx: unknown,
+  ): Promise<R> {
+    const start = performance.now();
+    let outcome: "success" | "error" = "success";
+    try {
+      return await next(args);
+    } catch (err) {
+      outcome = "error";
+      throw err;
+    } finally {
+      emit(pipelineName, start, outcome);
+    }
+  };
+  return fn;
+}
+
+/**
+ * The echo plugin. Declares one middleware per slot in
+ * `PipelineMiddlewareMap` — all thin observers produced by `makeObserver`.
+ *
+ * Manifest:
+ * - Host-compat range lives in `package.json` under
+ *   `peerDependencies["@vellumai/plugin-api"]`. The external-plugin loader
+ *   validates it against the running assistant version via
+ *   `semver.satisfies()` before this file is even imported.
+ * - No `requiresCredential` or `requiresFlag` — the plugin needs no external
+ *   state and runs unconditionally.
+ */
+const echoPlugin: Plugin = {
+  manifest: {
+    name: PLUGIN_NAME,
+    version: "0.1.0",
+  },
+  middleware: {
+    compaction: makeObserver<CompactionArgs, CompactionResult>("compaction"),
+    overflowReduce: makeObserver<OverflowReduceArgs, OverflowReduceResult>(
+      "overflowReduce",
+    ),
+    circuitBreaker: makeObserver<CircuitBreakerArgs, CircuitBreakerResult>(
+      "circuitBreaker",
+    ),
+  },
+};
+
+// Side-effect registration — the user-plugin loader dynamic-imports this
+// file and expects the registry to pick up the plugin during that import.
+registerPlugin(echoPlugin);

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

@@ -194,12 +194,8 @@ export interface ProvidersFacet {
 // Memory
 // ---------------------------------------------------------------------------
 
-/**
- * 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";
+/** Valid message roles for `memory.addMessage`. */
+export type MessageRole = "user" | "assistant" | "system";
 
 /**
  * Callable signature for `memory.addMessage`. Mirrors the daemon's
@@ -251,7 +247,10 @@ 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

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.8.7
+  version: 0.8.8
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -95,9 +95,7 @@ paths:
     post:
       operationId: acp_by_id_steer_post
       summary: Steer 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.
+      description: Send a steering instruction to an active ACP session.
       tags:
         - acp
       responses:
@@ -112,9 +110,6 @@ paths:
                     type: string
                   steered:
                     type: boolean
-                  resumed:
-                    description: True when the session was resumed from persisted history before steering.
-                    type: boolean
                 required:
                   - acpSessionId
                   - steered
@@ -141,9 +136,7 @@ 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.
-        Rows whose session is currently active in memory (e.g. resumed) or has a resume in flight are excluded.
+      description: Remove every terminal-state row (completed/failed/cancelled) from the persisted acp_session_history table.
       tags:
         - acp
       responses:
@@ -245,8 +238,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 or has a
-        resume in flight; idempotent for unknown ids.
+        Remove a persisted ACP session row. Rejects with 409 when the session is still active in memory; idempotent
+        for unknown ids.
       tags:
         - acp
       responses:
@@ -16029,9 +16022,6 @@ paths:
                             type: string
                         role:
                           type: string
-                          enum:
-                            - user
-                            - assistant
                         content:
                           type: string
                         timestamp:

package/package.json

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

package/src/__tests__/agent-loop-exit-reason.test.ts

@@ -13,7 +13,7 @@
  * Sites not exercised here (`aborted_via_error`) require deeper provider
  * fakery and are best covered by integration tests.
  */
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 
 import type {
   AgentEvent,
@@ -23,6 +23,7 @@ import type {
 } from "../agent/loop.js";
 import { AgentLoop, isMaxTokensStopReason } from "../agent/loop.js";
 import type { TurnContext } from "../plugins/types.js";
+import { PluginTimeoutError } from "../plugins/types.js";
 import type {
   Message,
   Provider,
@@ -101,8 +102,8 @@ const userMessage: Message = {
 };
 
 // A turn context whose `contextWindowManager.maybeCompact` returns a canned
-// result, so the loop's compaction call runs without the real orchestrator
-// machinery.
+// result, so the loop's native compaction pipeline runs without the real
+// orchestrator machinery.
 function fakeCompactionTurnContext(result: {
   compacted: boolean;
   exhausted: boolean;
@@ -118,6 +119,22 @@ function fakeCompactionTurnContext(result: {
   } as unknown as TurnContext;
 }
 
+// A turn context whose compaction call times out, exercising the loop's
+// PluginTimeoutError handling.
+function timeoutCompactionTurnContext(): TurnContext {
+  return {
+    requestId: "req-compact",
+    conversationId: "conv-compact",
+    turnIndex: 0,
+    trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    contextWindowManager: {
+      maybeCompact: async () => {
+        throw new PluginTimeoutError("compaction", "default-compaction", 1);
+      },
+    },
+  } as unknown as TurnContext;
+}
+
 function lastExitEvent(
   events: AgentEvent[],
 ): Extract<AgentEvent, { type: "agent_loop_exit" }> | undefined {
@@ -399,6 +416,42 @@ describe("AgentLoop exit-reason instrumentation", () => {
     expect(result.exitReason).not.toBe("budget");
   });
 
+  test("yields 'budget' when inline compaction times out", async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse("t1", "read_file", { path: "/a.txt" }),
+      textResponse("never reached"),
+    ]);
+    const toolExecutor = async () => ({ content: "ok", isError: false });
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
+
+    const compaction: MidLoopCompaction = {
+      postCompactionHook: async () => {
+        throw new Error("postCompactionHook must not run after a timeout");
+      },
+    };
+    const recordOutcomeSpy = spyOn(loop.compactionCircuit, "recordOutcome");
+
+    // WHEN the compaction pipeline throws a PluginTimeoutError
+    const result = await loop.run([userMessage], () => {}, {
+      resolveContextWindow: () => ({
+        maxInputTokens: 10,
+        overflowRecovery: { enabled: true, safetyMarginRatio: 0 },
+      }),
+      compaction,
+      turnContext: timeoutCompactionTurnContext(),
+    });
+
+    // THEN the loop records the timeout as a compaction failure against its
+    // own circuit breaker, and yields for budget so the orchestrator can
+    // escalate.
+    expect(recordOutcomeSpy).toHaveBeenCalledTimes(1);
+    expect(recordOutcomeSpy.mock.calls[0]?.[1]).toBe(true);
+    expect(result.exitReason).toBe("budget");
+  });
+
   test("yields 'budget' when inline compaction reports exhausted", async () => {
     const { provider } = createMockProvider([
       toolUseResponse("t1", "read_file", { path: "/a.txt" }),

package/src/__tests__/anthropic-provider.test.ts

@@ -102,7 +102,7 @@ mock.module("@anthropic-ai/sdk", () => ({
 }));
 
 // Import after mocking
-import { cachedTextBlock } from "../plugins/defaults/memory-v3-shadow/provider-blocks.js";
+import { cachedTextBlock } from "../memory/v3/provider-blocks.js";
 import { AnthropicProvider } from "../providers/anthropic/client.js";
 import {
   isPlaceholderSentinelText,

package/src/__tests__/app-control-flow.test.ts

@@ -103,7 +103,7 @@ const { ROUTES } = await import("../runtime/routes/host-app-control-routes.js");
 const { surfaceProxyResolver } =
   await import("../daemon/conversation-surfaces.js");
 const { setConversation, clearConversations } =
-  await import("../daemon/conversation-registry.js");
+  await import("../daemon/conversation-store.js");
 type SurfaceConversationContext =
   import("../daemon/conversation-surfaces.js").SurfaceConversationContext;
 

package/src/__tests__/app-dir-path-guard.test.ts

@@ -19,7 +19,6 @@ const ALLOWLIST = new Set([
   "assistant/src/memory/app-store.ts", // defines getAppsDir
   "assistant/src/memory/app-git-service.ts", // uses getAppsDir for git repo root, not per-app paths
   "assistant/src/daemon/app-source-watcher.ts", // uses getAppsDir for recursive fs.watch root, not per-app paths
-  "assistant/src/tools/filesystem/write.ts", // uses getAppsDir as an exemption root for the artifact-HTML guard, not per-app paths
 ]);
 
 function isTestFile(filePath: string): boolean {

package/src/__tests__/approval-routes-http.test.ts

@@ -119,15 +119,12 @@ mock.module("../permissions/trust-store.js", () => ({
 // ---------------------------------------------------------------------------
 let _conversationFactory: (() => Conversation) | undefined;
 
-mock.module("../daemon/conversation-registry.js", () => ({
+mock.module("../daemon/conversation-store.js", () => ({
   findConversation: () => {
     // Return the current test session for any conversation ID lookup.
     if (!_conversationFactory) return undefined;
     return _conversationFactory();
   },
-}));
-
-mock.module("../daemon/conversation-store.js", () => ({
   getOrCreateConversation: async () => {
     if (!_conversationFactory)
       throw new Error("_conversationFactory not set in test");

package/src/__tests__/channel-approval-routes.test.ts

@@ -16,7 +16,7 @@ mock.module("../util/logger.js", () => ({
 }));
 
 const _conversationMocks = new Map<string, unknown>();
-mock.module("../daemon/conversation-registry.js", () => ({
+mock.module("../daemon/conversation-store.js", () => ({
   findConversation: (id: string) => _conversationMocks.get(id),
 }));
 

package/src/__tests__/channel-approvals.test.ts

@@ -11,7 +11,7 @@ mock.module("../util/logger.js", () => ({
 
 // Map conversationId → mock session so findConversation returns the right mock.
 const conversationMocks = new Map<string, unknown>();
-mock.module("../daemon/conversation-registry.js", () => ({
+mock.module("../daemon/conversation-store.js", () => ({
   findConversation: (id: string) => conversationMocks.get(id),
 }));