@vellumai/assistant 0.8.0 → 0.8.2

package/src/platform/client.test.ts

@@ -15,7 +15,7 @@ let mockAssistantId = "";
 // Module mocks
 // ---------------------------------------------------------------------------
 
-mock.module("../providers/managed-proxy/context.js", () => ({
+mock.module("../providers/platform-proxy/context.js", () => ({
   resolveManagedProxyContext: async () => mockManagedProxyCtx,
 }));
 

package/src/platform/client.ts

@@ -6,7 +6,7 @@
  */
 
 import { getPlatformAssistantId } from "../config/env.js";
-import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { resolveManagedProxyContext } from "../providers/platform-proxy/context.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";

package/src/plugin-api/constants.ts

@@ -0,0 +1,26 @@
+/**
+ * Public hook-name constants.
+ *
+ * Plugin authors reference hooks by name in two places: the keys on
+ * `Plugin.hooks` and the daemon's `runHook(name, ctx)` call sites.
+ * Centralizing the string literals here keeps the typo surface minimal
+ * and lets call sites import a typed constant instead of repeating a
+ * free-form string.
+ *
+ * New hooks land here as additional `HOOKS.*` entries. The runtime
+ * `runHook(name, ctx)` accepts any string (so test fixtures and
+ * forward-compat hooks can still chain through), but call sites in
+ * first-party code should always reach for a `HOOKS.*` constant.
+ */
+
+export const HOOKS = {
+  /** Plugin bootstrap. Fires once when the daemon loads the plugin. */
+  INIT: "init",
+  /** Plugin teardown. Fires once when the daemon unloads the plugin. */
+  SHUTDOWN: "shutdown",
+  /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
+  USER_PROMPT_SUBMIT: "user-prompt-submit",
+} as const;
+
+/** Union of every hook name declared in {@link HOOKS}. */
+export type HookName = (typeof HOOKS)[keyof typeof HOOKS];

package/src/plugin-api/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Public entry point for the `@vellumai/plugin-api` package.
+ *
+ * Plugin authors import from `"@vellumai/plugin-api"`; this file is what
+ * their import lands on (directly via the published npm package, or via a
+ * boot-time shim that re-exports from the assistant binary's embedded
+ * bundle).
+ *
+ * Keep this file's surface stable across minor/patch releases. Anything
+ * exported here is part of the public contract.
+ *
+ * ## Surface today
+ *
+ * The public package is intentionally **declarative**: a plugin is a
+ * directory whose `package.json` is the manifest and whose `hooks/` /
+ * `tools/` / `skills/` / `routes/` subdirectories are the contributions.
+ * The host introspects the directory at load time and wires it into the
+ * runtime — plugin authors never call a runtime registration function.
+ *
+ * What this module exposes is therefore types-only: the context shapes
+ * the host hands to plugin hooks, and the logger shape they include.
+ *
+ * - {@link PluginInitContext} — passed to `init` hook at bootstrap
+ * - {@link PluginShutdownContext} — passed to `shutdown` hook at teardown
+ * - {@link UserPromptSubmitContext} — passed to `user-prompt-submit` hook,
+ *   fired immediately before the agent loop receives a user's prompt
+ * - {@link PluginLogger} — pino-compatible logger shape on the contexts
+ * - {@link ToolContext} — passed to a plugin tool's `execute` method
+ * - {@link ToolExecutionResult} — return shape of a plugin tool's `execute`
+ *
+ * Pipeline-argument types (`LLMCallArgs`, `MemoryArgs`, etc.) currently
+ * live in `assistant/src/plugins/types.ts` and have not yet migrated into
+ * this package. A follow-up PR will move them into this surface as the
+ * per-pipeline schemas stabilize.
+ */
+
+export type { HookName } from "./constants.js";
+export { HOOKS } from "./constants.js";
+export type {
+  PluginInitContext,
+  PluginLogger,
+  PluginShutdownContext,
+  ToolContext,
+  ToolExecutionResult,
+  UserPromptSubmitContext,
+} from "./types.js";

package/src/plugin-api/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@vellumai/plugin-api",
+  "version": "0.0.0-source",
+  "description": "Public API surface for Vellum assistant plugins. Source-of-truth lives here; the bundled artifact is what gets published to npm and embedded into the assistant binary.",
+  "type": "module",
+  "private": true,
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/src/plugin-api/types.ts

@@ -0,0 +1,144 @@
+/**
+ * Public plugin-API types.
+ *
+ * This module is the entry point plugin authors land on when they import
+ * from `@vellumai/plugin-api`. The shapes here are the canonical public
+ * contract — anything exported is part of the surface that semver gates.
+ *
+ * ## Tool-execution types
+ *
+ * `ToolContext` and `ToolExecutionResult` are re-exports of the narrow,
+ * stable bases defined alongside their daemon-internal counterparts in
+ * `assistant/src/tools/types.ts`. The daemon-internal `ToolContext` /
+ * `ToolExecutionResult` (with CES, trust classification, lifecycle
+ * events, sensitive-output bindings, risk metadata, etc.) `extends`
+ * the public bases, so the runtime can hand plugins the full value
+ * without a manual cast and tsc enforces the structural relationship.
+ * Plugin tools see the narrow surface only — they MUST NOT set fields
+ * that belong to the daemon-internal extension.
+ *
+ * ## Hook contexts
+ *
+ * The init / shutdown hook contexts are owned by this module directly.
+ * They have no daemon-internal extension today (the daemon constructs
+ * and hands them straight through), so there's nothing to inherit from.
+ *
+ * ## Compatibility
+ *
+ * Adding fields to any public shape is non-breaking. Renaming or
+ * removing fields is breaking and gated on a major bump of
+ * `@vellumai/plugin-api`.
+ */
+
+import type { Message } from "../providers/types.js";
+
+// ─── Tool-execution types (re-exported from daemon source-of-truth) ──────────
+
+export type {
+  PluginToolContext as ToolContext,
+  PluginToolExecutionResult as ToolExecutionResult,
+} from "../tools/types.js";
+
+// ─── Logger ──────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal pino-compatible logger surface handed to plugin hooks. The host
+ * supplies a pino child logger bound to `{ plugin: <name> }`; this
+ * interface intentionally captures only the two call shapes plugin code
+ * needs (structured object + optional message), so the public surface
+ * doesn't take a dependency on pino's full type machinery.
+ *
+ * Each method accepts a structured-fields object followed by an optional
+ * message string. Plugin authors that need pino's wider API (`child()`,
+ * `level`, etc.) can cast to their own narrower interface in plugin code
+ * — but the canonical contract here covers the 99% case.
+ */
+export interface PluginLogger {
+  info(obj: Record<string, unknown>, msg?: string): void;
+  warn(obj: Record<string, unknown>, msg?: string): void;
+  error(obj: Record<string, unknown>, msg?: string): void;
+  debug(obj: Record<string, unknown>, msg?: string): void;
+}
+
+// ─── Init context ────────────────────────────────────────────────────────────
+
+/**
+ * Context passed to `Plugin.init()` during bootstrap. Carries resolved
+ * config/credentials, a pino-compatible logger scoped to the plugin, a
+ * per-plugin writable data directory, and the assistant's version metadata.
+ */
+export interface PluginInitContext {
+  /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
+  config: unknown;
+  /** Resolved credential values keyed by the entries of `manifest.requiresCredential`. */
+  credentials: Record<string, string>;
+  /** Pino-compatible child logger bound to `{ plugin: <name> }`. */
+  logger: PluginLogger;
+  /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
+  pluginStorageDir: string;
+  /**
+   * Assistant semver. Plugins can compare against this for defensive
+   * runtime checks — but the canonical compat contract is the host
+   * version against the plugin's `peerDependencies["@vellumai/plugin-api"]`
+   * semver range, enforced at load time by the external-plugin loader.
+   */
+  assistantVersion: string;
+}
+
+// ─── Shutdown context ────────────────────────────────────────────────────────
+
+/**
+ * Context passed to the `shutdown` hook during daemon teardown. Kept
+ * intentionally narrower than {@link PluginInitContext} — most teardown
+ * paths only need to know which assistant version they're shutting
+ * down against (e.g. for version-conditional cleanup of state files
+ * written by a previous boot).
+ *
+ * Additional fields may be added as concrete plugin needs surface; the
+ * `assistantVersion` field mirrors the init context's so plugins that
+ * stash a version stamp at init can compare against the same name on
+ * tear-down without keeping their own copy.
+ */
+export interface PluginShutdownContext {
+  /** Assistant semver for compatibility checks inside the plugin. */
+  assistantVersion: string;
+}
+
+// ─── User-prompt-submit hook context ─────────────────────────────────────────
+
+/**
+ * Context passed to the `user-prompt-submit` hook. Fires once per user
+ * turn, after the agent loop has prepared the message list (PKB / NOW /
+ * memory-graph injections, history repair, overflow reduction all already
+ * applied) and immediately before the messages are handed to the agent
+ * loop's tool/LLM iteration.
+ *
+ * The hook may transform `latestMessages` either by mutating it in place
+ * (`push` / `splice` / `length = 0`) or by returning a new context with
+ * a fresh `latestMessages` array — see {@link PluginHookFn}'s polymorphic
+ * return shape. The daemon threads the final `latestMessages` value into
+ * `agentLoop.run()` as the run-messages argument.
+ *
+ * `originalMessages` is the user's original message list, frozen for the
+ * hook. Plugins should treat it as a stable reference point if they need
+ * to recover from earlier transformations or compare against the pristine
+ * state.
+ *
+ * Multiple plugins' hooks chain in registration order — each plugin's
+ * hook sees the previous plugin's mutations (whether by reassignment or
+ * in-place mutation).
+ */
+export interface UserPromptSubmitContext {
+  /** Conversation ID the user prompt was submitted on. */
+  readonly conversationId: string;
+  /**
+   * The user's original message list, immutable for the hook. Plugins
+   * may snapshot or compare against this but MUST NOT mutate it.
+   */
+  readonly originalMessages: ReadonlyArray<Message>;
+  /**
+   * The working message list that flows into `agentLoop.run`. Plugins
+   * may mutate this in place or replace it by returning a new context.
+   */
+  latestMessages: Message[];
+}

package/src/plugins/defaults/circuit-breaker.ts

@@ -55,11 +55,6 @@ export const defaultCircuitBreakerPlugin: Plugin = {
   manifest: {
     name: "default-circuit-breaker",
     version: "1.0.0",
-    provides: { circuitBreakerApi: "v1" },
-    requires: {
-      pluginRuntime: "v1",
-      circuitBreakerApi: "v1",
-    },
   },
 
   middleware: {

package/src/plugins/defaults/compaction.ts

@@ -112,10 +112,6 @@ export const defaultCompactionPlugin: Plugin = {
   manifest: {
     name: DEFAULT_COMPACTION_PLUGIN_NAME,
     version: "1.0.0",
-    requires: {
-      pluginRuntime: "v1",
-      compactionApi: "v1",
-    },
   },
   middleware: {
     compaction: defaultCompactionMiddleware,

package/src/plugins/defaults/empty-response.ts

@@ -95,8 +95,6 @@ export const defaultEmptyResponsePlugin: Plugin = {
   manifest: {
     name: "default-empty-response",
     version: "1.0.0",
-    provides: { emptyResponseApi: "v1" },
-    requires: { pluginRuntime: "v1", emptyResponseApi: "v1" },
   },
   middleware: {
     emptyResponse: passthrough,

package/src/plugins/defaults/history-repair.ts

@@ -54,8 +54,6 @@ export const defaultHistoryRepairPlugin: Plugin = {
   manifest: {
     name: "default-history-repair",
     version: "1.0.0",
-    provides: { historyRepair: "v1" },
-    requires: { pluginRuntime: "v1", historyRepairApi: "v1" },
   },
   middleware: {
     historyRepair: passthrough,

package/src/plugins/defaults/injectors.ts

@@ -19,6 +19,7 @@
  * | `pkb-reminder`           | 35    | after-memory-prefix     |
  * | `memory-v2-static`       | 38    | after-memory-prefix     |
  * | `now-md`                 | 40    | after-memory-prefix     |
+ * | `active-documents`       | 45    | prepend-user-tail       |
  * | `subagent-status`        | 50    | append-user-tail        |
  * | `slack-messages`         | 60    | replace-run-messages    |
  * | `thread-focus`           | 70    | append-user-tail        |
@@ -91,6 +92,7 @@ export const DEFAULT_INJECTOR_ORDER = {
   pkbReminder: 35,
   memoryV2Static: 38,
   nowMd: 40,
+  activeDocuments: 45,
   subagentStatus: 50,
   slackMessages: 60,
   threadFocus: 70,
@@ -251,9 +253,24 @@ const pkbReminderInjector: Injector = {
     const mode = inputs.mode ?? "full";
     if (mode !== "full") return null;
     if (!inputs.pkbActive) return null;
+    // The `memory-retrospective` feature flag enables a focused background
+    // retrospective pass that catches what the in-conversation `remember`
+    // calls miss. When that backstop is on, the per-turn pressure to call
+    // `remember` softens to a judgment framing. When it's off, the original
+    // high-pressure BODY is used so users without the retrospective still
+    // get aggressive capture in-conversation.
+    let relaxed = false;
+    try {
+      relaxed = isAssistantFeatureFlagEnabled(
+        "memory-retrospective",
+        getConfig(),
+      );
+    } catch {
+      // Best-effort — fall back to the default (non-relaxed) BODY.
+    }
     const reminder = isPkbInjectionSilencedByV2()
-      ? buildPkbReminder([])
-      : await buildPkbReminderWithHints(inputs);
+      ? buildPkbReminder([], relaxed)
+      : await buildPkbReminderWithHints(inputs, relaxed);
     return {
       id: "pkb-reminder",
       text: reminder,
@@ -283,6 +300,7 @@ function buildPkbContextBlock(content: string): string {
  */
 async function buildPkbReminderWithHints(
   inputs: TurnInjectionInputs,
+  relaxed: boolean,
 ): Promise<string> {
   let hints: string[] = [];
   const queryVector = inputs.pkbQueryVector;
@@ -343,7 +361,7 @@ async function buildPkbReminderWithHints(
       hints = [];
     }
   }
-  return buildPkbReminder(hints);
+  return buildPkbReminder(hints, relaxed);
 }
 
 /**
@@ -422,6 +440,39 @@ const nowMdInjector: Injector = {
   },
 };
 
+/**
+ * `active-documents` injector — order 45, prepend-user-tail.
+ *
+ * Injects an `<active_documents>` block listing open documents in the
+ * conversation so the assistant can target them with `document_update`
+ * instead of creating duplicates via `document_create`.
+ *
+ * Gating:
+ *  - `mode === "full"`.
+ *  - `activeDocuments` has at least one entry.
+ */
+const activeDocumentsInjector: Injector = {
+  name: "active-documents",
+  order: DEFAULT_INJECTOR_ORDER.activeDocuments,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    const inputs = readInjectionInputs(ctx);
+    const mode = inputs.mode ?? "full";
+    if (mode !== "full") return null;
+    const docs = inputs.activeDocuments;
+    if (!docs || docs.length === 0) return null;
+    const lines = docs.map(
+      (d) =>
+        `- surface_id: "${d.surfaceId}", title: "${d.title}", words: ${d.wordCount}`,
+    );
+    const text = `<active_documents>\nThe following documents are open in this conversation. Use document_update with the surface_id to edit them — do NOT call document_create for documents that already exist.\n${lines.join("\n")}\n</active_documents>`;
+    return {
+      id: "active-documents",
+      text,
+      placement: "prepend-user-tail",
+    };
+  },
+};
+
 /**
  * `subagent-status` injector — order 50, append-user-tail.
  *
@@ -546,9 +597,6 @@ export const defaultInjectorsPlugin: Plugin = {
   manifest: {
     name: "default-injectors",
     version: "1.0.0",
-    requires: {
-      pluginRuntime: "v1",
-    },
   },
   injectors: [
     diskPressureWarningInjector,
@@ -558,6 +606,7 @@ export const defaultInjectorsPlugin: Plugin = {
     pkbReminderInjector,
     memoryV2StaticInjector,
     nowMdInjector,
+    activeDocumentsInjector,
     subagentStatusInjector,
     slackMessagesInjector,
     threadFocusInjector,

package/src/plugins/defaults/llm-call.ts

@@ -42,8 +42,6 @@ export const defaultLlmCallPlugin: Plugin = {
   manifest: {
     name: "default-llm-call",
     version: "1.0.0",
-    provides: { llmCall: "v1" },
-    requires: { pluginRuntime: "v1" },
   },
   middleware: {
     llmCall: async function defaultLlmCall(

package/src/plugins/defaults/memory-retrieval.ts

@@ -190,7 +190,6 @@ export const defaultMemoryRetrievalPlugin: Plugin = {
   manifest: {
     name: "default-memory-retrieval",
     version: "0.0.1",
-    requires: { pluginRuntime: "v1", memoryApi: "v1" },
   },
   middleware: {
     memoryRetrieval: defaultMemoryRetrievalMiddleware,

package/src/plugins/defaults/overflow-reduce.ts

@@ -156,7 +156,6 @@ export const defaultOverflowReducePlugin: Plugin = {
   manifest: {
     name: "default-overflow-reduce",
     version: "1.0.0",
-    requires: { pluginRuntime: "v1", overflowReduceApi: "v1" },
   },
   middleware: {
     overflowReduce: defaultOverflowReduceMiddleware,

package/src/plugins/defaults/persistence.ts

@@ -98,8 +98,6 @@ export const defaultPersistencePlugin: Plugin = {
   manifest: {
     name: "default-persistence",
     version: "1.0.0",
-    provides: { persistence: "v1" },
-    requires: { pluginRuntime: "v1" },
   },
   middleware: {
     persistence: passthrough,

package/src/plugins/defaults/title-generate.ts

@@ -64,11 +64,6 @@ export const defaultTitleGeneratePlugin: Plugin = {
   manifest: {
     name: "default-title-generate",
     version: "1.0.0",
-    provides: { titleGenerate: "v1" },
-    requires: {
-      pluginRuntime: "v1",
-      titleGenerateApi: "v1",
-    },
   },
 };
 

package/src/plugins/defaults/token-estimate.ts

@@ -72,8 +72,6 @@ export const defaultTokenEstimatePlugin: Plugin = {
   manifest: {
     name: "default-token-estimate",
     version: "1.0.0",
-    provides: { tokenEstimate: "v1" },
-    requires: { pluginRuntime: "v1", tokenEstimateApi: "v1" },
   },
   middleware: {
     tokenEstimate: passthrough,

package/src/plugins/defaults/tool-error.ts

@@ -90,13 +90,6 @@ export const defaultToolErrorPlugin: Plugin = {
   manifest: {
     name: "default-tool-error",
     version: "1.0.0",
-    requires: {
-      pluginRuntime: "v1",
-      toolErrorApi: "v1",
-    },
-    provides: {
-      toolError: "v1",
-    },
   },
   middleware: {
     toolError: defaultToolErrorMiddleware,

package/src/plugins/defaults/tool-execute.ts

@@ -58,8 +58,6 @@ export const defaultToolExecutePlugin: Plugin = {
   manifest: {
     name: "default-tool-execute",
     version: "1.0.0",
-    provides: { toolExecuteApi: "v1" },
-    requires: { pluginRuntime: "v1", toolExecuteApi: "v1" },
   },
   middleware: {
     toolExecute: defaultToolExecute,

package/src/plugins/defaults/tool-result-truncate.ts

@@ -55,10 +55,6 @@ export const defaultToolResultTruncatePlugin: Plugin = {
   manifest: {
     name: "default-tool-result-truncate",
     version: "1.0.0",
-    requires: {
-      pluginRuntime: "v1",
-      toolResultTruncateApi: "v1",
-    },
   },
   middleware: {
     toolResultTruncate: passthrough,

package/src/plugins/ensure-plugin-api-shim.ts

@@ -0,0 +1,96 @@
+/**
+ * Materializes the workspace-level `@vellumai/plugin-api` shim so that
+ * user plugins under `<workspaceDir>/plugins/<name>/` can resolve a
+ * standard bare import:
+ *
+ *     import { ... } from "@vellumai/plugin-api";
+ *
+ * Bun's Node-style resolution walks up from the plugin directory and
+ * finds `<workspaceDir>/node_modules/@vellumai/plugin-api/` — a tiny
+ * shim package whose `index.js` re-binds the plugin-api namespace that
+ * the assistant already loaded into its module graph (and parked on
+ * `globalThis` under {@link PLUGIN_API_REGISTRY_KEY}).
+ *
+ * This avoids duplicating the plugin-api package per plugin while still
+ * letting the assistant's compiled binary be the single source of truth
+ * for the public API. The runtime mechanism is uniform across:
+ *   - JIT / Docker: plugin-api loads from source, shim re-binds via globalThis
+ *   - `bun --compile` (macOS bare-metal): plugin-api ships inside the
+ *     binary's regular code graph (Bun's bundler resolves
+ *     `import * as pluginApi from "../plugin-api/index.js"` at compile
+ *     time, inlining relative imports), shim re-binds via globalThis
+ *
+ * Idempotent: safe to call repeatedly. The shim's contents are
+ * deterministic given the runtime export list — fresh exports (added in
+ * later PRs) automatically expand the generated `index.js`.
+ *
+ * Called from {@link loadUserPlugins} at the top of its body so the
+ * ordering constraint (shim exists before any plugin's
+ * `import "@vellumai/plugin-api"` is parsed) is enforced by code, not
+ * by a docstring in `lifecycle.ts`.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import assistantPkg from "../../package.json" with { type: "json" };
+import {
+  PLUGIN_API_EXPORTS,
+  PLUGIN_API_REGISTRY_KEY,
+} from "../embedded/plugin-api.js";
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
+
+const log = getLogger("plugin-api-shim");
+
+const PACKAGE_NAME = "@vellumai/plugin-api";
+
+/**
+ * Build the body of the workspace shim's `index.js`. Exported so the
+ * smoke test can assert against the same generator the daemon uses.
+ */
+export function buildShimSource(
+  exports: readonly string[] = PLUGIN_API_EXPORTS,
+  registryKey: symbol = PLUGIN_API_REGISTRY_KEY,
+): string {
+  const description = registryKey.description ?? "";
+  const lines = [
+    `const api = globalThis[Symbol.for(${JSON.stringify(description)})];`,
+    ...exports.map((name) => `export const ${name} = api.${name};`),
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+export async function ensurePluginApiShim(opts?: {
+  /** Override the workspace root. Defaults to `getWorkspaceDir()`. */
+  workspaceDir?: string;
+}): Promise<void> {
+  const workspaceDir = opts?.workspaceDir ?? getWorkspaceDir();
+  const shimDir = join(workspaceDir, "node_modules", PACKAGE_NAME);
+
+  await mkdir(shimDir, { recursive: true });
+
+  const indexJs = buildShimSource();
+  const packageJson = `${JSON.stringify(
+    {
+      name: PACKAGE_NAME,
+      version: assistantPkg.version,
+      type: "module",
+      main: "./index.js",
+    },
+    null,
+    2,
+  )}\n`;
+
+  await writeFile(join(shimDir, "index.js"), indexJs);
+  await writeFile(join(shimDir, "package.json"), packageJson);
+
+  log.info(
+    {
+      shimDir,
+      exports: PLUGIN_API_EXPORTS,
+      version: assistantPkg.version,
+    },
+    "plugin-api shim materialized",
+  );
+}