@vellumai/assistant 0.6.5 → 0.6.6

package/examples/plugins/echo/README.md

@@ -0,0 +1,132 @@
+# Echo plugin
+
+Minimal example plugin. Observes every assistant pipeline and logs one JSON
+line per invocation to `stderr`:
+
+```json
+{"plugin":"echo","pipeline":"toolExecute","durationMs":42,"outcome":"success"}
+{"plugin":"echo","pipeline":"llmCall","durationMs":1873,"outcome":"success"}
+```
+
+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.
+
+For the full plugin authoring guide, see
+[`assistant/docs/plugins.md`](../../../docs/plugins.md).
+
+## 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.
+
+## Install locally
+
+The assistant scans `~/.vellum/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.
+
+### Option 1 — symlink from the repo (recommended)
+
+From the repo root:
+
+```bash
+mkdir -p ~/.vellum/plugins
+ln -s "$(pwd)/assistant/examples/plugins/echo" ~/.vellum/plugins/echo
+```
+
+Symlinks let you edit the plugin in-place and restart the assistant to
+pick up changes. **This is the only zero-edit install path** — the
+`register.ts` in this directory uses relative imports
+(`../../../src/plugins/registry.js`) that resolve into the in-repo
+assistant sources, so the file must stay reachable at that relative
+location.
+
+### Option 2 — standalone copy (requires edits)
+
+If you want a fully isolated install that does not depend on a local
+vellum-assistant checkout, a plain `cp -R` of this directory into
+`~/.vellum/plugins/echo/` will **not** work as-is: the relative imports
+in `register.ts` resolve to `~/.vellum/src/plugins/...`, which does not
+exist. The assistant does not currently publish the plugin API as an npm
+package, so to copy-and-adapt this template into a standalone plugin you
+must rewrite the imports in `register.ts` to point at an absolute path
+inside a vellum-assistant checkout, for example:
+
+```ts
+// before (repo-local):
+import { registerPlugin } from "../../../src/plugins/registry.js";
+// after (standalone, edit to your checkout path):
+import { registerPlugin } from "/path/to/vellum-assistant/assistant/src/plugins/registry.js";
+```
+
+Apply the same rewrite to the `import type` line that pulls from
+`../../../src/plugins/types.js`. Until a published package exists, the
+symlink recipe above is simpler and more portable for day-to-day
+development.
+
+### Restart the assistant
+
+Plugins register at assistant startup. After installing, restart the
+assistant:
+
+```bash
+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:
+
+```bash
+tail -f ~/.vellum/daemon.log
+```
+
+You should see one line per pipeline 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"}
+```
+
+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:
+
+```bash
+rm ~/.vellum/plugins/echo
+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.
+- Look at the first-party default plugins under
+  `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 with a middleware that does whatever
+  you need.

package/examples/plugins/echo/package.json

@@ -0,0 +1,17 @@
+{
+  "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.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "./register.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "@types/node": "25.5.0",
+    "typescript": "5.9.3"
+  }
+}

package/examples/plugins/echo/register.ts

@@ -0,0 +1,187 @@
+/**
+ * Echo plugin — observes every assistant pipeline and logs one structured
+ * line per invocation to stderr.
+ *
+ * This plugin is bundled in the repository as an authoring reference. It is
+ * not shipped with the assistant runtime; to try it locally, symlink this
+ * directory into `~/.vellum/plugins/echo/` and restart the assistant. See
+ * `README.md` in this directory for the full install recipe and
+ * `assistant/docs/plugins.md` for general plugin authoring docs.
+ *
+ * ## IMPORTANT — imports below are REPO-LOCAL
+ *
+ * The relative imports from `../../../src/plugins/...` resolve correctly
+ * only while this file lives inside the vellum-assistant repo at
+ * `assistant/examples/plugins/echo/`. The path walks back to
+ * `assistant/src/plugins/` so the example compiles against the assistant's
+ * in-repo types.
+ *
+ * If you copy (rather than symlink) this directory to
+ * `~/.vellum/plugins/echo/`, these imports will fail because
+ * `~/.vellum/src/plugins/...` does not exist. The assistant does not
+ * currently publish the plugin API as an npm package, so the only
+ * zero-edit install path is the symlink recipe (Option 1 in README.md).
+ *
+ * For a standalone copy that lives outside the repo, you must either:
+ * - Point the imports at an absolute path into a vellum-assistant checkout
+ *   (`/path/to/vellum-assistant/assistant/src/plugins/registry.js`), or
+ * - Rewrite the plugin to consume only the public types you need and drop
+ *   the direct registry import in favor of your own entry-point wiring.
+ *
+ * See README.md "Option 2 — standalone copy" for the recommended
+ * standalone-template adaptation steps.
+ *
+ * ## 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 { registerPlugin } from "../../../src/plugins/registry.js";
+import type {
+  CircuitBreakerArgs,
+  CircuitBreakerResult,
+  CompactionArgs,
+  CompactionResult,
+  EmptyResponseArgs,
+  EmptyResponseResult,
+  HistoryRepairArgs,
+  HistoryRepairResult,
+  LLMCallArgs,
+  LLMCallResult,
+  MemoryArgs,
+  MemoryResult,
+  OverflowReduceArgs,
+  OverflowReduceResult,
+  PersistArgs,
+  PersistResult,
+  Plugin,
+  TitleArgs,
+  TitleResult,
+  TokenEstimateArgs,
+  TokenEstimateResult,
+  ToolErrorArgs,
+  ToolErrorResult,
+  ToolExecuteArgs,
+  ToolExecuteResult,
+  ToolResultTruncateArgs,
+  ToolResultTruncateResult,
+  TurnArgs,
+  TurnResult,
+} from "../../../src/plugins/types.js";
+
+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:
+ * - `requires.pluginRuntime: "v1"` satisfies the registry's mandatory
+ *   capability negotiation.
+ * - `provides: {}` — the plugin exposes no capabilities to other plugins.
+ * - No `requiresCredential` or `requiresFlag` — the plugin needs no external
+ *   state and runs unconditionally.
+ */
+const echoPlugin: Plugin = {
+  manifest: {
+    name: PLUGIN_NAME,
+    version: "0.1.0",
+    provides: {},
+    requires: { pluginRuntime: "v1" },
+  },
+  middleware: {
+    turn: makeObserver<TurnArgs, TurnResult>("turn"),
+    llmCall: makeObserver<LLMCallArgs, LLMCallResult>("llmCall"),
+    toolExecute: makeObserver<ToolExecuteArgs, ToolExecuteResult>(
+      "toolExecute",
+    ),
+    memoryRetrieval: makeObserver<MemoryArgs, MemoryResult>("memoryRetrieval"),
+    historyRepair: makeObserver<HistoryRepairArgs, HistoryRepairResult>(
+      "historyRepair",
+    ),
+    tokenEstimate: makeObserver<TokenEstimateArgs, TokenEstimateResult>(
+      "tokenEstimate",
+    ),
+    compaction: makeObserver<CompactionArgs, CompactionResult>("compaction"),
+    overflowReduce: makeObserver<OverflowReduceArgs, OverflowReduceResult>(
+      "overflowReduce",
+    ),
+    persistence: makeObserver<PersistArgs, PersistResult>("persistence"),
+    titleGenerate: makeObserver<TitleArgs, TitleResult>("titleGenerate"),
+    toolResultTruncate: makeObserver<
+      ToolResultTruncateArgs,
+      ToolResultTruncateResult
+    >("toolResultTruncate"),
+    emptyResponse: makeObserver<EmptyResponseArgs, EmptyResponseResult>(
+      "emptyResponse",
+    ),
+    toolError: makeObserver<ToolErrorArgs, ToolErrorResult>("toolError"),
+    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/egress-proxy/src/types.ts

@@ -197,12 +197,19 @@ export type PolicyDecision =
 /**
  * Callback invoked by the proxy HTTP forwarder for each outbound request.
  * Returns injected headers on allow, or `null` to block the request.
+ *
+ * `method` and `requestHeaders` are populated for plain-HTTP proxied
+ * requests (absolute-URL form). For HTTPS CONNECT tunnels the proxy has
+ * not yet terminated TLS and cannot see HTTP-level details, so these are
+ * left undefined.
  */
 export type PolicyCallback = (
   hostname: string,
   port: number | null,
   path: string,
   scheme: "http" | "https",
+  method?: string,
+  requestHeaders?: Record<string, string | string[] | undefined>,
 ) => Promise<Record<string, string> | null>;
 
 /**
@@ -216,6 +223,18 @@ export interface ProxyApprovalRequest {
     | PolicyDecisionAskUnauthenticated;
   /** The proxy session ID that originated the request. */
   sessionId: ProxySessionId;
+  /**
+   * HTTP method of the incoming request, when available. Undefined for HTTPS
+   * CONNECT tunnels — at CONNECT time the proxy has not terminated TLS so
+   * no HTTP-level information is visible.
+   */
+  method?: string;
+  /**
+   * Curated subset of request headers, when available. Only non-sensitive
+   * headers are surfaced (content-type, content-length, user-agent, accept).
+   * Undefined for HTTPS CONNECT tunnels.
+   */
+  requestHeaders?: Record<string, string>;
 }
 
 /**