@vellumai/assistant 0.6.4 → 0.6.6

package/docs/skills.md

@@ -12,14 +12,14 @@ Because skills can introduce arbitrary tool behavior, they are subject to strict
 
 Skill-origin tools follow a stricter default permission policy than core tools:
 
-| Scenario                                              | Core tool behavior            | Skill tool behavior |
-| ----------------------------------------------------- | ----------------------------- | ------------------- |
-| Low risk, no matching rule                            | Auto-allowed (workspace mode) | **Prompted**        |
-| Medium risk, no matching rule                         | Prompted                      | Prompted            |
-| High risk, no matching rule                           | Prompted                      | Prompted            |
-| Allow rule matches, non-high risk                     | Auto-allowed                  | Auto-allowed        |
-| Allow rule matches, high risk, `allowHighRisk: true`  | Auto-allowed                  | Auto-allowed        |
-| Allow rule matches, high risk, `allowHighRisk` absent | Prompted                      | Prompted            |
+| Scenario                                          | Core tool behavior            | Skill tool behavior |
+| ------------------------------------------------- | ----------------------------- | ------------------- |
+| Low risk, no matching rule                        | Auto-allowed (workspace mode) | **Prompted**        |
+| Medium risk, no matching rule                     | Prompted                      | Prompted            |
+| High risk, no matching rule                       | Prompted                      | Prompted            |
+| Allow rule matches, non-high risk                 | Auto-allowed                  | Auto-allowed        |
+| Allow rule matches, high risk, containerized bash | Auto-allowed (runtime check)  | Auto-allowed        |
+| Allow rule matches, high risk, other              | Prompted                      | Prompted            |
 
 Even if a skill's `TOOLS.json` declares `"risk": "low"` for one of its tools, the permission checker will prompt the user unless an explicit trust rule in `~/.vellum/protected/trust.json` allows it. This prevents third-party skill tools from silently auto-executing.
 
@@ -73,7 +73,7 @@ Writing to skill source files is treated as a **high-risk** operation by the ris
 - **Workspace skills**: Project-local skill directories
 - **Extra skills**: Additional roots configured by the user
 
-When `file_write`, `file_edit`, `host_file_write`, or `host_file_edit` targets a path inside any of these directories, the risk level is escalated from its normal level (typically Medium) to **High**. High-risk operations always require user approval unless a matching trust rule with `allowHighRisk: true` exists.
+When `file_write`, `file_edit`, `host_file_write`, or `host_file_edit` targets a path inside any of these directories, the risk level is escalated from its normal level (typically Medium) to **High**. High-risk operations always require user approval (only containerized bash is auto-allowed at runtime for high-risk operations).
 
 This escalation prevents the agent from modifying skill code without explicit user consent. Since modifying a skill's source could grant the agent new capabilities or alter existing tool behavior, such mutations are treated as a privilege-escalation vector.
 
@@ -135,7 +135,7 @@ When you modify any file in a skill's directory, the version hash changes. If yo
 
 Writing to skill source paths is classified as high risk because it could alter the agent's capabilities. This is a deliberate security measure.
 
-**Fix**: If you trust the operation, approve it. To permanently allow it, select "Always allow" and choose the `allowHighRisk` option if offered.
+**Fix**: If you trust the operation, approve it. To permanently allow it, select "Always allow". Note that high-risk file operations will still prompt for each invocation since runtime auto-allow only applies to containerized bash.
 
 ### "Why is strict mode prompting for everything?"
 

package/docs/stt-provider-onboarding.md

@@ -39,7 +39,7 @@ The `services.stt.providers` map uses a sparse `z.record(z.string(), ...)` schem
 2. Implement the `transcribe(request)` method using a lazy-imported provider module (follow the pattern in the existing adapters).
 3. Add a `case` branch in `createDaemonBatchTranscriber()` for the new `SttProviderId`. The exhaustive `never` check at the bottom of the switch ensures a compile error if this step is skipped.
 
-If the provider needs a new REST client module, add it under `src/providers/speech-to-text/` following the pattern of `openai-whisper.ts`, `deepgram.ts`, and `google-gemini.ts`.
+If the provider needs a new REST client module, add it under `src/providers/speech-to-text/` following the pattern of `openai-whisper.ts`, `deepgram.ts`, `google-gemini.ts`, and `xai.ts`.
 
 ## 5. Credential plumbing
 
@@ -72,6 +72,7 @@ Add a new entry to the `providers` array with the following fields:
 | `openai-whisper` | `openai`                                    | shared        |
 | `deepgram`       | `deepgram`                                  | exclusive     |
 | `google-gemini`  | `gemini`                                    | shared        |
+| `xai`            | `xai`                                       | exclusive     |
 
 When the provider ID differs from the credential provider name (e.g. `google-gemini` maps to `gemini`), the key is **shared** with other services that use the same credential. The `sttKeyIsExclusive` / `sttKeyIsShared` helpers in the macOS settings layer derive this automatically from the catalog.
 

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/knip.json

@@ -10,7 +10,12 @@
     "../skills/meet-join/**/*.test.ts",
     "../skills/meet-join/**/__tests__/**/*.ts",
     "!../skills/meet-join/bot/**",
-    "../skills/meet-join/contracts/**/__tests__/**/*.ts"
+    "../skills/meet-join/contracts/**/__tests__/**/*.ts",
+    "../skills/meet-join/meet-controller-ext/scripts/build.ts",
+    "../skills/meet-join/meet-controller-ext/src/background.ts",
+    "../skills/meet-join/meet-controller-ext/src/content.ts",
+    "../skills/meet-join/meet-controller-ext/src/avatar/avatar.ts",
+    "../skills/meet-join/meet-controller-ext/src/messaging/content-bridge.ts"
   ],
   "project": [
     "src/**/*.ts",
@@ -22,6 +27,8 @@
   "ignoreDependencies": [
     "@vellumai/ces-contracts",
     "@vellumai/credential-storage",
-    "@vellumai/egress-proxy"
+    "@vellumai/egress-proxy",
+    "@resvg/resvg-js-darwin-arm64",
+    "@resvg/resvg-js-darwin-x64"
   ]
 }

package/node_modules/@vellumai/ces-contracts/package.json

@@ -9,7 +9,8 @@
     "./handles": "./src/handles.ts",
     "./grants": "./src/grants.ts",
     "./rpc": "./src/rpc.ts",
-    "./rendering": "./src/rendering.ts"
+    "./rendering": "./src/rendering.ts",
+    "./trust-rules": "./src/trust-rules.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",