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

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/docs/activation-funnel-telemetry.md

@@ -0,0 +1,310 @@
+# Activation Funnel Telemetry — Runbook + Analytics Handoff
+
+> **Linear:** JARVIS-1102 (event emission) — gates JARVIS-1092 (10% rollout) and JARVIS-1093 (dashboard).
+> **Funnel version:** `activation_v1_2026_06`
+> **LD flag:** `experiment-activation-flow-2026-06-03`
+> **Cohort arm tag:** `ab_variant = "variant-a"` (treatment); `control` = the no-rail arm.
+
+This doc is the single executable reference for the activation-rail funnel
+telemetry: what it measures, how it flows, the event vocabulary, the dedup
+contract, the local smoke-test runbook, the BigQuery verification query, and the
+canonical handoff blurb for the dashboard work. It is meant to be runnable by
+another engineer without reading the implementation.
+
+---
+
+## 1. Overview — what it measures and how it flows
+
+The activation funnel measures how far a new user gets on their first run of the
+**activation rail** (the onboarding experience driven by
+`BOOTSTRAP-ACTIVATION-RAIL.md`). It emits five milestone ("funnel") events per
+session into the **existing onboarding telemetry substrate** — no new event type,
+no new ingest endpoint, no new BigQuery table.
+
+The north-star "≥5 user messages within 24h per LD variant" metric is **not** a
+materialized activation event. It is computed downstream by joining the existing
+per-user-message `turn` telemetry events (`turn_index` per conversation) to the
+platform's `flag_assignment_raw` cohort-assignment table — so a dedicated event
+and a custom daemon turn-counting hook are not needed.
+
+Flow, end to end:
+
+1. **Daemon records** an activation event into the SQLite `onboarding_events`
+   table via `recordActivationEvent()` in
+   `assistant/src/memory/onboarding-events-store.ts`:
+   - emission is **deterministic, tied to a `ui_show` surface** — there is no
+     model-facing tool. The model tags the surface it is already rendering for a
+     rail move with an optional `activation_moment` parameter on `ui_show`; the
+     daemon captures that tag on the surface's server-side state and records the
+     milestone (gated on `isActivationSession`). **Timing is per-moment**
+     (`ACTIVATION_MOMENT_EMIT_AT` in `activation-funnel.ts`): most moments record
+     when the user **commits** the surface (clicks an action / submits /
+     selects) via `handleSurfaceAction()`; the one exception is
+     `first_wow_executed`, which records at **render time** in
+     `surfaceProxyResolver` — the Run result/`work_result` surface is often
+     display-only and may never be committed, so a commit-time emit would never
+     fire (and deferring it to a later click would conflate "executed" with
+     "interacted"). Show-timing tags are recorded immediately and not stored, so
+     the commit path never double-emits. The token→step-name map and the
+     show/commit timing both live in
+     `assistant/src/telemetry/activation-funnel.ts`;
+   - emission is best-effort (wrapped in try/catch) and never blocks or alters
+     the surface-action flow;
+   - `recordActivationEvent` respects the `getConfig().collectUsageData` opt-out
+     gate (returns `null` / no row when disabled).
+2. **Reporter flushes** every ~5 min: `usage-telemetry-reporter.ts`
+   (`REPORT_INTERVAL_MS = 5 * 60 * 1000`, with a one-time
+   `INITIAL_FLUSH_DELAY_MS = 30_000` after startup) POSTs unreported onboarding
+   rows to `/v1/telemetry/ingest/` as `type: "onboarding"` events, mapping the
+   funnel columns onto the wire shape.
+3. **Platform ingests** the onboarding events and writes GCS NDJSON.
+4. **BigQuery** exposes them via the external table
+   `vellum-ai-prod.telemetry.onboarding_raw`, which already carries the
+   `session_id / step_name / step_index / completed_at / funnel_version /
+ab_variant` columns. The existing dbt model dedups on `daemon_event_id`
+   (earliest-wins).
+
+No platform / dbt / terraform change is required — the activation events ride the
+`type: "onboarding"` substrate that already exists end to end.
+
+---
+
+## 2. Event vocabulary
+
+The single source of truth is `assistant/src/telemetry/activation-funnel.ts`
+(`ACTIVATION_STEPS`). `funnel_version = "activation_v1_2026_06"`
+(`ACTIVATION_FUNNEL_VERSION`). `ab_variant = "variant-a"`
+(`ACTIVATION_AB_VARIANT`, the treatment arm).
+
+Each step is recorded when the user commits the `ui_show` surface the model
+tagged with the corresponding `activation_moment` token (see §1). The
+token→step-name map is the `moment_*` column below.
+
+| step_index | step_name                         | `activation_moment` token | Recorded on commit of                                           |
+| ---------- | --------------------------------- | ------------------------- | --------------------------------------------------------------- |
+| 1          | `activation_moment_1_complete`    | `moment_1`                | Port-summary card OR no-port intake `choice` surface            |
+| 2          | `activation_moment_2_complete`    | `moment_2`                | Propose offer surface (the `ui_show` offer card/choice)         |
+| 3          | `activation_moment_3_complete`    | `moment_3`                | task-selection surface                                          |
+| 4          | `activation_first_wow_executed`   | `first_wow_executed`      | Run result surface (e.g. `work_result`)                         |
+| 5          | `activation_first_wow_interacted` | `first_wow_interacted`    | user clicks an action on the tagged result surface (see §1, §4) |
+
+All five steps are recorded deterministically on surface commit. The north star
+(≥5 user messages) is derived downstream from the existing `turn` telemetry, not
+a materialized activation event (see §1).
+
+On the wire, each onboarding event also sets `screen = step_name` (to satisfy the
+SQLite `screen TEXT NOT NULL` column and the platform's legacy-path validation),
+and `completed_at` is the ISO-8601 record time.
+
+---
+
+## 3. Dedup contract
+
+Activation rows carry a **deterministic** `daemon_event_id`:
+
+```
+daemon_event_id = `${funnel_version}:${session_id}:${step_name}`
+```
+
+Built by `buildActivationDaemonEventId()` in
+`assistant/src/telemetry/activation-funnel.ts`. The reporter overrides
+`daemon_event_id` for activation rows (where `session_id && step_name &&
+funnel_version` are all present) and keys it on the **row's stored
+`funnel_version`**, NOT the running binary's current constant. This keeps the id
+stable across a version bump so rows queued offline / flushed after an upgrade
+still collapse with already-ingested rows from the same session.
+
+A moment that fires more than once (e.g. a model double-emit) therefore lands
+with the same `daemon_event_id` and is collapsed downstream by the existing dbt
+earliest-wins dedup on `daemon_event_id`. For boolean "moment complete"
+semantics, earliest-wins is correct.
+
+**Checkpoint safety:** the SQLite watermark cursor in the reporter advances on the
+row `id` / `createdAt`, NOT on `daemon_event_id`. The deterministic id is a
+wire-only override, so overriding it never affects flush checkpointing.
+
+---
+
+## 4. Cohort scoping
+
+Events only emit for conversations explicitly marked as **activation-rail
+sessions**:
+
+- The marker lives in the `activation_sessions` table
+  (`assistant/src/memory/activation-session-store.ts`,
+  `markActivationSession` / `isActivationSession`).
+- It is set in `assistant/src/prompts/system-prompt.ts` **only when the
+  `BOOTSTRAP-ACTIVATION-RAIL.md` template is actually active** (i.e.
+  `bootstrapTemplate === ACTIVATION_RAIL_BOOTSTRAP_TEMPLATE`), which the web
+  prechat context selects only for users whose
+  `experiment-activation-flow-2026-06-03` cohort puts them on the rail. (It is
+  also set up-front in `conversation.ts` `setOnboardingContext` so the marker is
+  available before the first turn's tool resolution.)
+- Emission is **gated on the marker at commit time**: when a tagged `ui_show`
+  surface is committed, the daemon records the milestone only if
+  `isActivationSession(conversationId)` is true. A stray `activation_moment` tag
+  in a normal chat is therefore ignored and never pollutes the funnel. (`moment_4`
+  / `first_wow_interacted` deduping is handled the same way as any other moment —
+  see the dedup contract in §3 — and the per-surface tag is cleared after the
+  first record so a single surface commit emits at most once.)
+
+The activation **session id is the daemon `conversation_id`** of the rail
+conversation. That same value is `session_id` on every activation event.
+
+---
+
+## 5. Local smoke-test runbook
+
+Goal: drive one dev session through the activation cohort, emit all five events,
+flush, and verify rows in BigQuery. Executable by another engineer.
+
+### 5.1 Put the dev user in the activation cohort
+
+The rail is gated by the LD flag `experiment-activation-flow-2026-06-03`. Two
+options:
+
+- **In-app feature-flags override (fastest):** open the in-app Feature Flags
+  panel and force `experiment-activation-flow-2026-06-03` ON for the dev user.
+- **LaunchDarkly targeting:** target the dev user for the flag in the LD
+  dashboard (per the LD-flag-two-repo convention, targeting is dashboard-side).
+
+When the flag is ON, the web prechat context selects
+`BOOTSTRAP-ACTIVATION-RAIL.md` as the bootstrap template, and the daemon marks
+the conversation in `activation_sessions` on first build of the system prompt.
+
+### 5.2 Confirm usage-data collection is enabled — and do NOT run in dev mode
+
+Two gates must both be satisfied or no rows reach BigQuery:
+
+1. `recordActivationEvent` no-ops when `config.collectUsageData` is false, so the
+   dev build/config must have usage-data collection enabled, or no rows are
+   written to SQLite.
+2. **Dev mode disables the flush entirely.** `assistant/src/daemon/lifecycle.ts`
+   computes the effective setting as `collectUsageData = !isDevMode &&
+config.collectUsageData`, so when the daemon runs in dev mode (`VELLUM_DEV=1`)
+   the `UsageTelemetryReporter` is never started — rows accumulate in SQLite but
+   are never POSTed, and the "wait/restart for flush" steps below will never
+   reach BigQuery. For an end-to-end smoke test, run the daemon **outside dev
+   mode** (so the reporter starts), or explicitly invoke the reporter's
+   `flush()` via a dev hook. The SQLite rows can still be inspected directly in
+   dev mode, but the BigQuery verification (§6) requires a real flush.
+
+### 5.3 Start a fresh activation conversation and capture its id
+
+Start a brand-new conversation with the flag ON (it must be the rail bootstrap, so
+start it from the web prechat flow / activation entry, not an existing chat).
+Note its `conversation_id` — this is the `session_id` you will query on.
+
+If multiple daemons are running, kill ALL `daemon/main.ts` processes, remove
+`~/.vellum/vellum.sock`, and start fresh, so the conversation is served by a known
+daemon writing to a known SQLite DB.
+
+### 5.4 Drive the rail through all five model moments
+
+Work the conversation through the rail moves so the model tags each surface and
+you commit it (the model tags surfaces via `ui_show`'s `activation_moment`
+parameter; which surface maps to which moment is documented in
+`BOOTSTRAP-ACTIVATION-RAIL.md` and §2). Each milestone records when YOU commit
+the tagged surface:
+
+1. Commit the Port-summary card / no-port intake `choice` → `activation_moment_1_complete`.
+2. Commit the Propose offer surface → `activation_moment_2_complete`.
+3. Commit the task-selection surface → `activation_moment_3_complete`.
+4. Commit the Run result surface → `activation_first_wow_executed`.
+5. Click an action on the result surface → `activation_first_wow_interacted`.
+
+### 5.5 Force / await a telemetry flush
+
+The reporter flushes on a schedule: a first flush ~30s after startup
+(`INITIAL_FLUSH_DELAY_MS`) and then every ~5 min (`REPORT_INTERVAL_MS`). Either:
+
+- **Wait** for the next scheduled flush (≤ ~5 min), or
+- **Restart the daemon** to take the ~30s post-startup flush, or
+- call the reporter's `flush()` path directly if you have a dev hook into the
+  running daemon.
+
+A successful flush POSTs the unreported onboarding rows to
+`/v1/telemetry/ingest/` as `type: "onboarding"` events.
+
+### 5.6 Verify in BigQuery
+
+Wait for the platform → GCS NDJSON → BigQuery pipeline to land the events, then
+run the query in §6.
+
+---
+
+## 6. BigQuery verification query
+
+```sql
+SELECT step_name, step_index, COUNT(*) AS n
+FROM `vellum-ai-prod.telemetry.onboarding_raw`
+WHERE funnel_version = 'activation_v1_2026_06'
+  AND session_id = '<dev conversation id>'
+GROUP BY 1, 2
+ORDER BY 2;
+```
+
+**Expected:** all five `activation_*` step names for the one session, step_index
+1–5, each with `n = 1`:
+
+```
+activation_moment_1_complete      | 1 | 1
+activation_moment_2_complete      | 2 | 1
+activation_moment_3_complete      | 3 | 1
+activation_first_wow_executed     | 4 | 1
+activation_first_wow_interacted   | 5 | 1
+```
+
+A missing row means that milestone never emitted (re-drive that rail move); an
+`n > 1` before dbt dedup is harmless (the deterministic `daemon_event_id`
+collapses it earliest-wins).
+
+---
+
+## 7. Canonical handoff blurb (paste-ready for the final JARVIS-1102 PR description)
+
+> **Activation funnel telemetry — handoff for JARVIS-1093.** The activation rail
+> now emits five milestone funnel events into the existing onboarding telemetry
+> substrate (`type: "onboarding"` → `/v1/telemetry/ingest/` → GCS NDJSON →
+> `vellum-ai-prod.telemetry.onboarding_raw`), so no new event type, ingest
+> endpoint, or BigQuery table is involved. Cohort is gated by the LaunchDarkly
+> flag **`experiment-activation-flow-2026-06-03`**; only rail (treatment)
+> conversations emit. Every event carries **`funnel_version =
+"activation_v1_2026_06"`** and **`ab_variant`** tagged `"variant-a"` for
+> treatment (`"control"` is the no-rail arm, measured for now from generic `turn`
+> events). The event vocabulary (step_name → step_index): `activation_moment_1_complete`
+> (1), `activation_moment_2_complete` (2), `activation_moment_3_complete` (3),
+> `activation_first_wow_executed` (4), `activation_first_wow_interacted` (5).
+> `session_id` is the rail conversation's id. The **north star** ("≥5 user
+> messages within 24h per LD variant") is **not** a funnel event — compute it
+> downstream by joining the existing `turn` telemetry events (`turn_index` per
+> conversation) to the platform's `flag_assignment_raw` cohort-assignment table.
+> **Dedup contract:** each row's `daemon_event_id` is deterministic,
+> `${funnel_version}:${session_id}:${step_name}`, keyed on the row's stored
+> `funnel_version`; the existing dbt earliest-wins dedup on `daemon_event_id`
+> collapses any repeated moment to a single row. Build funnel conversion as a
+> step_index 1→5 progression per `session_id`, filtered to `funnel_version =
+'activation_v1_2026_06'`.
+
+---
+
+## 8. Notes
+
+- **JARVIS-1102 "naming check" (resolved).** Events fire **deterministically on
+  the real user commit of a `ui_show` surface, not every text turn**. The model
+  passively tags the surface for a rail move with `activation_moment`; the daemon
+  records the milestone in `handleSurfaceAction` when the user commits that
+  surface (firing conditions / surface→moment mapping documented in
+  `BOOTSTRAP-ACTIVATION-RAIL.md`). This removes the standalone
+  `emit_activation_event` tool (and its cohort preactivation) entirely and ties
+  emission to a genuine user action, resolving the naming-check open
+  interpretation.
+- **Stream B (multivariate cohort flag conversion) is NOT in this work.** It is
+  gated on the platform team's in-flight string-flag serving — until the platform
+  can serve string/multivariate flags, flipping
+  `experiment-activation-flow-2026-06-03` boolean→multivariate client-side would
+  silently disable the live allowlisted rail. Until then, `ab_variant` is the
+  constant `"variant-a"` (only treatment runs the rail), and the **control side**
+  of the comparison is measured from generic `turn` events split by the
+  platform's experiment exposure mapping. Once Stream B lands, the daemon tags the
+  real assigned arm and the cross-cohort comparison works with zero rework.

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