@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/Dockerfile

@@ -77,6 +77,7 @@ RUN apt-get update && apt-get install -y \
     debootstrap \
     debian-archive-keyring \
     debconf \
+    e2fsprogs \
     ffmpeg \
     fonts-freefont-ttf \
     g++ \
@@ -113,11 +114,13 @@ RUN apt-get update && apt-get install -y \
     libxtst6 \
     lsof \
     make \
+    mount \
     openssl \
     procps \
     python3 \
     sqlite3 \
     sudo \
+    util-linux \
     unzip \
     uuid-runtime \
     vim \
@@ -180,7 +183,8 @@ RUN printf '%s\n' \
 RUN printf '%s\n' \
     '#!/usr/bin/env sh' \
     'set -eu' \
-    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '. /app/assistant/docker-kata-runtime-family.sh' \
+    'if ! vellum_is_kata_family_runtime; then' \
     '  exec /usr/bin/apt-get "$@"' \
     'fi' \
     'export DEBIAN_FRONTEND=noninteractive' \
@@ -195,7 +199,8 @@ RUN printf '%s\n' \
     printf '%s\n' \
     '#!/usr/bin/env sh' \
     'set -eu' \
-    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '. /app/assistant/docker-kata-runtime-family.sh' \
+    'if ! vellum_is_kata_family_runtime; then' \
     '  exec /usr/bin/apt "$@"' \
     'fi' \
     'export DEBIAN_FRONTEND=noninteractive' \
@@ -210,7 +215,8 @@ RUN printf '%s\n' \
     printf '%s\n' \
     '#!/usr/bin/env sh' \
     'set -eu' \
-    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '. /app/assistant/docker-kata-runtime-family.sh' \
+    'if ! vellum_is_kata_family_runtime; then' \
     '  exec /usr/bin/dpkg "$@"' \
     'fi' \
     'DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"' \
@@ -236,7 +242,17 @@ ENV IS_CONTAINERIZED=true
 # and the generated meet-join manifest from the builder stage.
 COPY --from=builder /app /app
 
-RUN chmod +x /app/assistant/docker-entrypoint.sh /app/assistant/docker-init-apt-root.sh /app/assistant/docker-kata-apt-env.sh
+COPY packages/block-volume-bootstrap/scripts/*.sh /usr/local/bin/
+
+RUN chmod +x \
+    /app/assistant/docker-entrypoint.sh \
+    /app/assistant/docker-init-apt-root.sh \
+    /app/assistant/docker-kata-apt-env.sh \
+    /app/assistant/docker-kata-runtime-family.sh \
+    /usr/local/bin/vellum-block-volume-common.sh \
+    /usr/local/bin/vellum-block-volume-init.sh \
+    /usr/local/bin/vellum-block-volume-mount.sh \
+    /usr/local/bin/vellum-block-volume-resize.sh
 
 # Run the daemon + http server
 CMD ["/app/assistant/docker-entrypoint.sh"]

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/docker-entrypoint.sh

@@ -6,9 +6,11 @@ set -eu
 chmod 1777 /tmp 2>/dev/null || true
 
 KATA_APT_INIT_PID=""
-if [ "${VELLUM_SANDBOX_RUNTIME:-}" = "kata" ] && [ -x /app/assistant/docker-init-apt-root.sh ]; then
+. /app/assistant/docker-kata-runtime-family.sh
+
+if vellum_is_kata_family_runtime && [ -x /app/assistant/docker-init-apt-root.sh ]; then
   export VELLUM_APT_DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"
-  # Warm the chroot used by kata apt wrappers without blocking assistant readiness.
+  # Warm the chroot used by Kata-family apt wrappers without blocking assistant readiness.
   /app/assistant/docker-init-apt-root.sh &
   KATA_APT_INIT_PID="$!"
 fi

package/docker-init-apt-root.sh

@@ -10,7 +10,9 @@ LOCK_DIR="${DATA_ROOT}.rootfs-init.lock"
 LOCK_PID="${LOCK_DIR}/pid"
 HOST_PATH="/usr/sbin:/usr/bin:/sbin:/bin"
 
-if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then
+. /app/assistant/docker-kata-runtime-family.sh
+
+if ! vellum_is_kata_family_runtime; then
   exit 0
 fi
 

package/docker-kata-apt-env.sh

@@ -1,6 +1,8 @@
 #!/usr/bin/env sh
 
-if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then
+. /app/assistant/docker-kata-runtime-family.sh
+
+if ! vellum_is_kata_family_runtime; then
   return 0 2>/dev/null || exit 0
 fi
 

package/docker-kata-runtime-family.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env sh
+
+vellum_is_kata_family_runtime() {
+  case "${VELLUM_SANDBOX_RUNTIME:-}" in
+    kata|firecracker|cloud-hypervisor)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}

package/docs/architecture/memory.md

@@ -244,7 +244,7 @@ graph TB
 
 Normal context compaction (the "Context Window Management" subgraph above) runs proactively as the conversation approaches the token limit, using cooldown guards and a severity-pressure override to balance compaction frequency against cost. This is the primary defense against context overflow.
 
-When compaction alone is insufficient — either because the conversation grew too fast between turns or because a single turn contains extremely large payloads — the overflow recovery pipeline takes over. The pipeline's first tier (forced compaction) reuses the same `maybeCompact()` summarization machinery but with emergency parameters: `force: true` bypasses cooldown guards, `minKeepRecentUserTurns: 0` allows summarizing even the most recent history, and `targetInputTokensOverride` sets a tighter budget. Subsequent tiers (tool-result truncation, media stubbing, injection downgrade) apply progressively more aggressive payload reduction without involving the summarizer.
+When compaction alone is insufficient — either because the conversation grew too fast between turns or because a single turn contains extremely large payloads — the overflow recovery pipeline takes over. The pipeline's first tier (forced compaction) reuses the same `maybeCompact()` summarization machinery but with emergency parameters: `force: true` bypasses cooldown guards and `minKeepRecentUserTurns: 0` allows summarizing even the most recent history. The reducer drives convergence toward a tighter budget by re-invoking each tier until the estimated tokens fall under its `targetTokens` ceiling. Subsequent tiers (tool-result truncation, media stubbing, injection downgrade) apply progressively more aggressive payload reduction without involving the summarizer.
 
 If all four reducer tiers are exhausted, the overflow policy resolver determines whether to compress the latest user turn. All sessions — interactive and non-interactive alike — auto-compress the latest turn without prompting. The only explicit opt-out is setting `contextWindow.overflowRecovery.interactiveLatestTurnCompression` (or `nonInteractiveLatestTurnCompression`) to `"drop"`, which short-circuits to a graceful failure instead. Disabling overflow recovery entirely (`contextWindow.overflowRecovery.enabled: false`) also yields a graceful failure.
 

package/examples/plugins/echo/README.md

@@ -1,45 +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":"toolExecute","durationMs":42,"outcome":"success"}
-{"plugin":"echo","pipeline":"llmCall","durationMs":1873,"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` — `turn`, `llmCall`, `toolExecute`,
-  `memoryRetrieval`, `historyRepair`, `tokenEstimate`, `compaction`,
-  `overflowReduce`, `persistence`, `titleGenerate`, `toolResultTruncate`,
-  `emptyResponse`, `toolError`, 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)
 
@@ -56,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
 
@@ -86,28 +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":"persistence","durationMs":3,"outcome":"success"}
-{"plugin":"echo","pipeline":"tokenEstimate","durationMs":1,"outcome":"success"}
-{"plugin":"echo","pipeline":"memoryRetrieval","durationMs":64,"outcome":"success"}
-{"plugin":"echo","pipeline":"historyRepair","durationMs":0,"outcome":"success"}
-{"plugin":"echo","pipeline":"llmCall","durationMs":1520,"outcome":"success"}
-{"plugin":"echo","pipeline":"turn","durationMs":1590,"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:
@@ -119,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/server-message.ts

@@ -16,9 +16,9 @@
  * Moving the fully typed discriminated union into this package would
  * require relocating `assistant/src/daemon/message-types/` and its
  * cross-file type dependencies (`channels/types.ts`,
- * `skills/skillssh-registry.ts`, `runtime/guardian-decision-types.ts`,
- * `gallery/gallery-manifest.ts`). That is out of scope for PR 3 of the
- * skill-isolation plan and is tracked for later iteration.
+ * `skills/skillssh-registry.ts`, `runtime/guardian-decision-types.ts`).
+ * That is out of scope for PR 3 of the skill-isolation plan and is
+ * tracked for later iteration.
  */
 
 /**

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;
 }
 
 // ---------------------------------------------------------------------------