@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/src/permissions/gateway-threshold-reader.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Tests for the gateway-backed threshold reader, focused on
+ * refreshAutoApproveThreshold(): the cache-bypassing re-read performed
+ * before a permission prompt is surfaced. The reader's caches (5s
+ * conversation TTL with negative caching, 30s global TTL) are never
+ * invalidated by threshold writes, so without the refresh a user who just
+ * switched to Full access could still be prompted from a stale snapshot.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Silence logger output during tests.
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// ── Controllable IPC mock ────────────────────────────────────────────────────
+
+type IpcHandler = (params?: Record<string, unknown>) => unknown;
+
+const ipcHandlers = new Map<string, IpcHandler>();
+const ipcCallLog: Array<{ method: string; params?: Record<string, unknown> }> =
+  [];
+
+mock.module("../ipc/gateway-client.js", () => ({
+  ipcCall: async (method: string, params?: Record<string, unknown>) => {
+    ipcCallLog.push({ method, params });
+    const handler = ipcHandlers.get(method);
+    return handler ? handler(params) : undefined;
+  },
+  ipcCallPersistent: async () => undefined,
+  resetPersistentClient: () => {},
+}));
+
+import {
+  _clearGlobalCacheForTesting,
+  _resetFailureCoalesceForTesting,
+  getAutoApproveThreshold,
+  refreshAutoApproveThreshold,
+} from "./gateway-threshold-reader.js";
+
+function countCalls(method: string): number {
+  return ipcCallLog.filter((c) => c.method === method).length;
+}
+
+describe("refreshAutoApproveThreshold", () => {
+  beforeEach(() => {
+    _clearGlobalCacheForTesting();
+    _resetFailureCoalesceForTesting();
+    ipcHandlers.clear();
+    ipcCallLog.length = 0;
+  });
+
+  test("bypasses a stale conversation cache and returns the fresh override", async () => {
+    // Seed the cache with "low" via the normal read path.
+    ipcHandlers.set("get_conversation_threshold", () => ({
+      threshold: "low",
+    }));
+    expect(await getAutoApproveThreshold("conv-1", "conversation")).toBe("low");
+
+    // The user switches the conversation to Full access — the gateway now
+    // returns "high", but the reader's 5s cache still holds "low".
+    ipcHandlers.set("get_conversation_threshold", () => ({
+      threshold: "high",
+    }));
+    expect(await getAutoApproveThreshold("conv-1", "conversation")).toBe("low");
+
+    // The refresh bypasses the cache and sees the new value.
+    expect(await refreshAutoApproveThreshold("conv-1", "conversation")).toBe(
+      "high",
+    );
+  });
+
+  test("primes the conversation cache so subsequent reads skip IPC", async () => {
+    ipcHandlers.set("get_conversation_threshold", () => ({
+      threshold: "high",
+    }));
+
+    expect(await refreshAutoApproveThreshold("conv-2", "conversation")).toBe(
+      "high",
+    );
+    const callsAfterRefresh = countCalls("get_conversation_threshold");
+
+    expect(await getAutoApproveThreshold("conv-2", "conversation")).toBe(
+      "high",
+    );
+    // Cache hit — no additional IPC round-trip.
+    expect(countCalls("get_conversation_threshold")).toBe(callsAfterRefresh);
+  });
+
+  test("returns null when the conversation override read fails", async () => {
+    // No handler registered → ipcCall returns undefined (transport failure).
+    expect(
+      await refreshAutoApproveThreshold("conv-3", "conversation"),
+    ).toBeNull();
+    // Must not fall through to the global read: without the override we
+    // cannot know whether the conversation is stricter than the global.
+    expect(countCalls("get_global_thresholds")).toBe(0);
+  });
+
+  test("falls through to a fresh global read when no override exists", async () => {
+    ipcHandlers.set("get_conversation_threshold", () => null);
+    ipcHandlers.set("get_global_thresholds", () => ({
+      interactive: "high",
+      autonomous: "low",
+      headless: "none",
+    }));
+
+    expect(await refreshAutoApproveThreshold("conv-4", "conversation")).toBe(
+      "high",
+    );
+  });
+
+  test("bypasses a stale global cache", async () => {
+    ipcHandlers.set("get_global_thresholds", () => ({
+      interactive: "medium",
+      autonomous: "low",
+      headless: "none",
+    }));
+    expect(await getAutoApproveThreshold(undefined, "conversation")).toBe(
+      "medium",
+    );
+
+    // The user switches the global interactive threshold to Full access —
+    // the reader's 30s global cache still holds "medium".
+    ipcHandlers.set("get_global_thresholds", () => ({
+      interactive: "high",
+      autonomous: "low",
+      headless: "none",
+    }));
+    expect(await getAutoApproveThreshold(undefined, "conversation")).toBe(
+      "medium",
+    );
+
+    expect(await refreshAutoApproveThreshold(undefined, "conversation")).toBe(
+      "high",
+    );
+
+    // The refresh primed the global cache with the fresh values.
+    expect(await getAutoApproveThreshold(undefined, "conversation")).toBe(
+      "high",
+    );
+  });
+
+  test("resolves the context-appropriate global field", async () => {
+    ipcHandlers.set("get_global_thresholds", () => ({
+      interactive: "high",
+      autonomous: "medium",
+      headless: "none",
+    }));
+
+    expect(await refreshAutoApproveThreshold("conv-5", "background")).toBe(
+      "medium",
+    );
+    expect(await refreshAutoApproveThreshold("conv-5", "headless")).toBe(
+      "none",
+    );
+    // Background/headless contexts never consult the per-conversation
+    // override, mirroring getAutoApproveThreshold.
+    expect(countCalls("get_conversation_threshold")).toBe(0);
+  });
+
+  test("returns null when the global read fails", async () => {
+    expect(
+      await refreshAutoApproveThreshold(undefined, "conversation"),
+    ).toBeNull();
+  });
+
+  test("returns null for an invalid global value", async () => {
+    ipcHandlers.set("get_global_thresholds", () => ({
+      interactive: "bogus",
+      autonomous: "low",
+      headless: "none",
+    }));
+    expect(
+      await refreshAutoApproveThreshold(undefined, "conversation"),
+    ).toBeNull();
+  });
+});

package/src/permissions/gateway-threshold-reader.ts

@@ -288,3 +288,83 @@ async function fetchGlobalThresholds(): Promise<GlobalThresholds> {
   cachedGlobalTimestamp = Date.now();
   return result;
 }
+
+/**
+ * Re-read the auto-approve threshold from the gateway, bypassing both
+ * caches, and prime them with the fresh values.
+ *
+ * Used by the permission checker immediately before surfacing an
+ * interactive prompt: the cached snapshot (5s conversation TTL with
+ * negative caching, 30s global TTL) may predate a threshold change the
+ * user just made — e.g. switching to Full access — because no threshold
+ * write path invalidates these in-process caches (the web picker writes
+ * through the gateway HTTP route, the desktop picker through the
+ * `set_conversation_threshold` IPC). Prompting from a stale threshold
+ * directly contradicts the user's visible setting. A prompt is already a
+ * rare, user-visible interruption, so the extra IPC round-trip is cheap
+ * relative to a wrong prompt.
+ *
+ * Returns the freshly-resolved threshold, or `null` when the gateway
+ * could not be reached. Callers must keep their original decision on
+ * `null` — fail toward prompting, never toward silent approval. The
+ * conversation-override read failing is also treated as `null` (rather
+ * than falling through to the global threshold) because without the
+ * override we cannot know whether the conversation is configured more
+ * strictly than the global default.
+ */
+export async function refreshAutoApproveThreshold(
+  conversationId: string | undefined,
+  executionContext?: ExecutionContext,
+): Promise<Threshold | null> {
+  const ctx: ExecutionContext = executionContext ?? "conversation";
+
+  if (ctx === "conversation" && conversationId) {
+    const result = (await ipcCall("get_conversation_threshold", {
+      conversationId,
+    })) as ConversationThreshold | null | undefined;
+
+    if (result === undefined) {
+      noteFailure(
+        "conversation_threshold",
+        { conversationId },
+        "IPC call failed for conversation threshold refresh, keeping cached decision",
+      );
+      return null;
+    }
+    noteSuccess("conversation_threshold");
+    if (result && isValidThreshold(result.threshold)) {
+      conversationThresholdCache.set(conversationId, {
+        threshold: result.threshold,
+        timestamp: Date.now(),
+      });
+      return result.threshold;
+    }
+    // No override (or unexpected shape) — prime the negative cache and
+    // fall through to a fresh global read.
+    conversationThresholdCache.set(conversationId, {
+      threshold: null,
+      timestamp: Date.now(),
+    });
+  }
+
+  try {
+    const result = (await ipcCall(
+      "get_global_thresholds",
+    )) as GlobalThresholds | null;
+    if (!result) {
+      throw new Error("Gateway IPC returned no result for global thresholds");
+    }
+    noteSuccess("global_thresholds");
+    cachedGlobalThresholds = result;
+    cachedGlobalTimestamp = Date.now();
+    const value = result[mapExecutionContextToField(ctx)];
+    return isValidThreshold(value) ? value : null;
+  } catch (err) {
+    noteFailure(
+      "global_thresholds",
+      { error: String(err) },
+      "Failed to refresh global thresholds, keeping cached decision",
+    );
+    return null;
+  }
+}

package/src/platform/client.ts

@@ -45,9 +45,7 @@ export class VellumPlatformClient {
    */
   static async create(): Promise<VellumPlatformClient | null> {
     if (!arePlatformFeaturesEnabled()) {
-      log.debug(
-        "platform-features-in-local-mode is disabled — returning null",
-      );
+      log.debug("platform features disabled — returning null");
       return null;
     }
 

package/src/platform/feature-gate.ts

@@ -1,15 +1,6 @@
-import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
-import { getIsPlatform } from "../config/env-registry.js";
-import type { AssistantConfig } from "../config/schema.js";
+import { getDisablePlatform, getIsPlatform } from "../config/env-registry.js";
 
-const FLAG_KEY = "platform-features-in-local-mode" as const;
-
-export function arePlatformFeaturesEnabled(
-  config?: AssistantConfig,
-): boolean {
+export function arePlatformFeaturesEnabled(): boolean {
   if (getIsPlatform()) return true;
-  return isAssistantFeatureFlagEnabled(
-    FLAG_KEY,
-    (config ?? {}) as AssistantConfig,
-  );
+  return !getDisablePlatform();
 }

package/src/plugin-api/constants.ts

@@ -24,10 +24,12 @@ export const HOOKS = {
   PRE_MODEL_CALL: "pre-model-call",
   /** Fires once per tool result, after the tool returns and before the result is sent to the provider. */
   POST_TOOL_USE: "post-tool-use",
-  /** Fires when the model yields a response with no tool calls — the run's stop boundary. Decides whether to stop or continue with a follow-up turn. */
+  /** Fires once per run when the loop has committed to ending — the definitive terminal hook for teardown. Cannot continue the loop; reports how the turn ended via `exitReason`. */
   STOP: "stop",
-  /** Fires for each finalized assistant message, once per model call, before it is persisted/streamed-final. A hook may transform the message content. */
+  /** Fires at every model-call outcome (finalized reply or provider rejection), before the message is persisted/streamed-final. A hook may transform the content and owns the continue/retry decision. */
   POST_MODEL_CALL: "post-model-call",
+  /** Fires after the loop successfully compacts a conversation mid-turn. */
+  POST_COMPACT: "post-compact",
 } as const;
 
 /** Union of every hook name declared in {@link HOOKS}. */

package/src/plugin-api/index.ts

@@ -11,27 +11,45 @@
  *
  * ## 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.
+ * The primary authoring model is **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.
  *
- * What this module exposes is therefore types-only: the context shapes
+ * Most of what this module exposes is therefore types: the context shapes
  * the host hands to plugin hooks, and the logger shape they include.
  *
+ * Alongside those types, the module exposes a small set of **runtime
+ * handles** for plugins that need to reach the assistant's live singletons
+ * (subscribe to runtime events, read secrets). These resolve to the
+ * assistant's own instances: the host parks the loaded plugin-api namespace
+ * on `globalThis` at boot, and the workspace-level shim re-binds each
+ * runtime export from there — so a plugin's
+ * `import { assistantEventHub } from "@vellumai/plugin-api"` lands on the
+ * same singleton the assistant uses, even when the daemon is a
+ * `bun --compile` binary where an absolute-path import would load a
+ * disjoint module copy.
+ *
+ * - {@link assistantEventHub} — the assistant's pub/sub hub for runtime events
+ * - {@link getSecureKeyAsync} — read a secret from secure storage
+ *
  * - {@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 PostCompactContext} — passed to `post-compact` hook, fired after
+ *   the agent loop compacts a conversation mid-turn to re-apply injections
  * - {@link PreModelCallContext} — passed to `pre-model-call` hook, fired
  *   before each provider call to edit the request / defer output streaming
  * - {@link PostToolUseContext} — passed to `post-tool-use` hook, fired once
  *   per tool result before it joins the provider-bound history
- * - {@link StopContext} — passed to `stop` hook, fired when the model yields
- *   a response with no tool calls
- * - {@link PostModelCallContext} — passed to `post-model-call` hook,
- *   fired for each finalized assistant message to transform its content
+ * - {@link StopContext} — passed to `stop` hook, the definitive terminal hook
+ *   fired exactly once when the turn ends (no continue capability)
+ * - {@link AgentLoopExitReason} — why a turn reached its terminal state, carried
+ *   on {@link StopContext} and the `agent_loop_exit` event
+ * - {@link PostModelCallContext} — passed to `post-model-call` hook, fired at
+ *   every model-call outcome (a finalized reply or a provider rejection) to
+ *   transform content and decide whether to retry
  * - {@link PluginHookFn} — signature every lifecycle hook implements
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
  * - {@link ToolDefinition} — author-facing tool spec (default-export shape
@@ -42,19 +60,53 @@
 
 export type { HookName } from "./constants.js";
 export { HOOKS } from "./constants.js";
+// Conversation message/content shapes. A hook receives the live message
+// history (e.g. `PostToolUseContext.latestMessages: Message[]`), so plugins
+// that inspect or narrow content blocks — reading a `tool_use` block's input,
+// matching a `tool_result` — need to name these types.
+export type {
+  ContentBlock,
+  FileContent,
+  ImageContent,
+  Message,
+  RedactedThinkingContent,
+  ServerToolUseContent,
+  TextContent,
+  ThinkingContent,
+  ToolResultContent,
+  ToolUseContent,
+  WebSearchToolResultContent,
+} from "../providers/types.js";
 export type {
+  AgentLoopExitReason,
   PluginHookFn,
   PluginInitContext,
   PluginLogger,
   PluginShutdownContext,
+  PostCompactContext,
   PostModelCallContext,
+  PostModelCallDecision,
   PostToolUseContext,
   PreModelCallContext,
   StopContext,
-  StopDecision,
   ToolContext,
   ToolDefinition,
   ToolExecutionResult,
   UserPromptSubmitContext,
 } from "./types.js";
 export { RiskLevel } from "./types.js";
+
+// ─── Runtime handles ─────────────────────────────────────────────────────────
+// Values (not just types) that plugins consume at module-load / init time.
+// Workspace-local plugins resolve these via the boot-time shim, which
+// re-binds each from the assistant's globalThis-parked namespace so they
+// share module identity with the assistant's own singletons.
+export type { AssistantEvent } from "../runtime/assistant-event.js";
+export type {
+  AssistantEventCallback,
+  AssistantEventFilter,
+  AssistantEventHub,
+  AssistantEventSubscription,
+} from "../runtime/assistant-event-hub.js";
+export { assistantEventHub } from "../runtime/assistant-event-hub.js";
+export { getSecureKeyAsync } from "../security/secure-keys.js";