@vellumai/assistant 0.7.3 → 0.8.1

package/src/permissions/prompter.ts

@@ -11,19 +11,14 @@ import type { AllowlistOption, ScopeOption, UserDecision } from "./types.js";
 
 const log = getLogger("permission-prompter");
 
-interface PendingPrompt {
-  resolve: (value: {
-    decision: UserDecision;
-    selectedPattern?: string;
-    selectedScope?: string;
-    decisionContext?: string;
-    wasTimeout?: boolean;
-    wasSystemCancel?: boolean;
-  }) => void;
-  reject: (reason: Error) => void;
-  timer: ReturnType<typeof setTimeout>;
-  toolUseId?: string;
-}
+type ConfirmResult = {
+  decision: UserDecision;
+  selectedPattern?: string;
+  selectedScope?: string;
+  decisionContext?: string;
+  wasTimeout?: boolean;
+  wasSystemCancel?: boolean;
+};
 
 export type ConfirmationStateCallback = (
   requestId: string,
@@ -33,7 +28,13 @@ export type ConfirmationStateCallback = (
 ) => void;
 
 export class PermissionPrompter {
-  private pending = new Map<string, PendingPrompt>();
+  /**
+   * Tracks which requestIds belong to this prompter instance so that
+   * denyAllPending / dispose can scope their cleanup to this conversation.
+   * The full per-request state (callbacks, timer, toolUseId) lives in
+   * pendingInteractions, matching the host proxy pattern.
+   */
+  private ownedIds = new Set<string>();
   private sendToClient: (msg: ServerMessage) => void;
   private onStateChanged?: ConfirmationStateCallback;
 
@@ -69,74 +70,68 @@ export class PermissionPrompter {
     riskReason?: string,
     isContainerized?: boolean,
     directoryScopeOptions?: readonly { scope: string; label: string }[],
-  ): Promise<{
-    decision: UserDecision;
-    selectedPattern?: string;
-    selectedScope?: string;
-    decisionContext?: string;
-    wasTimeout?: boolean;
-    wasSystemCancel?: boolean;
-    wasAbort?: boolean;
-  }> {
+  ): Promise<ConfirmResult & { wasAbort?: boolean }> {
     if (signal?.aborted) return { decision: "deny", wasAbort: true };
 
     const requestId = uuid();
 
-    // Self-register in pendingInteractions so /v1/confirm can route the
-    // response to this conversation without going through broadcastMessage.
-    if (conversationId) {
-      pendingInteractions.register(requestId, {
-        conversationId,
-        kind: "confirmation",
-        confirmationDetails: {
-          toolName,
-          input: redactSensitiveFields(input),
-          riskLevel,
-          executionTarget,
-          allowlistOptions: allowlistOptions.map((o) => ({
-            label: o.label,
-            description: o.description,
-            pattern: o.pattern,
-          })),
-          scopeOptions: scopeOptions.map((o) => ({
-            label: o.label,
-            scope: o.scope,
-          })),
-          persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
-        },
-      });
-    }
-
     return new Promise((resolve, reject) => {
       const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
+
       const timer = setTimeout(() => {
-        this.pending.delete(requestId);
-        pendingInteractions.resolve(requestId);
+        const interaction = pendingInteractions.resolve(requestId);
+        this.ownedIds.delete(requestId);
         log.warn(
           { requestId, toolName },
           "Permission prompt timed out, defaulting to deny",
         );
         this.onStateChanged?.(requestId, "timed_out", "timeout", toolUseId);
-        resolve({
-          decision: "deny",
-          wasTimeout: true,
-          decisionContext: `The permission prompt for the "${toolName}" tool timed out. The user did not explicitly deny this request — they may have been away or busy. You may retry this tool call if it is still needed for the current task.`,
-        });
+        (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
+          {
+            decision: "deny",
+            wasTimeout: true,
+            decisionContext: `The permission prompt for the "${toolName}" tool timed out. The user did not explicitly deny this request — they may have been away or busy. You may retry this tool call if it is still needed for the current task.`,
+          },
+        );
       }, timeoutMs);
 
-      this.pending.set(requestId, {
-        resolve,
-        reject,
-        timer,
-        toolUseId,
-      });
+      // Register all lifecycle state in pendingInteractions — same pattern as
+      // host proxies. The prompter tracks ownership via ownedIds.
+      // Always register unconditionally so rpcResolve/rpcReject/timer
+      // are reachable by resolveConfirmation, denyAllPending, and the timeout
+      // handler even when conversationId is absent. Routes return 404 for
+      // interactions with an empty conversationId, which is correct behaviour.
+      pendingInteractions.register(requestId, {
+        conversationId: conversationId ?? "",
+        kind: "confirmation",
+          confirmationDetails: {
+            toolName,
+            input: redactSensitiveFields(input),
+            riskLevel,
+            executionTarget,
+            allowlistOptions: allowlistOptions.map((o) => ({
+              label: o.label,
+              description: o.description,
+              pattern: o.pattern,
+            })),
+            scopeOptions: scopeOptions.map((o) => ({
+              label: o.label,
+              scope: o.scope,
+            })),
+            persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
+          },
+          rpcResolve: resolve as (value: unknown) => void,
+          rpcReject: reject,
+          timer,
+          toolUseId,
+        });
+      this.ownedIds.add(requestId);
 
       if (signal) {
         const onAbort = () => {
-          if (this.pending.has(requestId)) {
-            clearTimeout(timer);
-            this.pending.delete(requestId);
+          if (this.ownedIds.has(requestId)) {
             pendingInteractions.resolve(requestId);
+            this.ownedIds.delete(requestId);
             resolve({ decision: "deny", wasAbort: true });
           }
         };
@@ -175,17 +170,17 @@ export class PermissionPrompter {
   }
 
   hasPendingRequest(requestId: string): boolean {
-    return this.pending.has(requestId);
+    return this.ownedIds.has(requestId);
   }
 
   /** Returns all currently pending request IDs. */
   getPendingRequestIds(): string[] {
-    return [...this.pending.keys()];
+    return [...this.ownedIds];
   }
 
   /** Returns the toolUseId associated with a pending request, if any. */
   getToolUseId(requestId: string): string | undefined {
-    return this.pending.get(requestId)?.toolUseId;
+    return pendingInteractions.get(requestId)?.toolUseId;
   }
 
   resolveConfirmation(
@@ -195,22 +190,17 @@ export class PermissionPrompter {
     selectedScope?: string,
     decisionContext?: string,
   ): void {
-    const pending = this.pending.get(requestId);
-    if (!pending) {
+    if (!this.ownedIds.has(requestId)) {
       log.warn({ requestId }, "No pending prompt for confirmation response");
       return;
     }
-    clearTimeout(pending.timer);
-    this.pending.delete(requestId);
-    // Idempotent — approval-routes already calls pendingInteractions.resolve()
-    // before routing here, but we call it defensively for non-route paths.
-    pendingInteractions.resolve(requestId);
-    pending.resolve({
-      decision,
-      selectedPattern,
-      selectedScope,
-      decisionContext,
-    });
+    // The prompter owns deregistration; all callers use get() to peek before
+    // routing to resolveConfirmation, which fires the rpcResolve callback.
+    const interaction = pendingInteractions.resolve(requestId);
+    this.ownedIds.delete(requestId);
+    (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
+      { decision, selectedPattern, selectedScope, decisionContext },
+    );
   }
 
   /**
@@ -219,31 +209,31 @@ export class PermissionPrompter {
    * see the denial and can re-request if still needed.
    */
   denyAllPending(): void {
-    for (const [requestId, pending] of this.pending) {
-      clearTimeout(pending.timer);
-      this.pending.delete(requestId);
-      pendingInteractions.resolve(requestId);
-      pending.resolve({
-        decision: "deny",
-        wasSystemCancel: true,
-        decisionContext:
-          "The user sent a new message instead of responding to this permission prompt. Stop what you are doing and respond to the user's new message. Do NOT retry this tool or request permission again until the user asks you to.",
-      });
+    for (const requestId of [...this.ownedIds]) {
+      const interaction = pendingInteractions.resolve(requestId);
+      this.ownedIds.delete(requestId);
+      (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
+        {
+          decision: "deny",
+          wasSystemCancel: true,
+          decisionContext:
+            "The user sent a new message instead of responding to this permission prompt. Stop what you are doing and respond to the user's new message. Do NOT retry this tool or request permission again until the user asks you to.",
+        },
+      );
     }
   }
 
   get hasPending(): boolean {
-    return this.pending.size > 0;
+    return this.ownedIds.size > 0;
   }
 
   dispose(): void {
-    for (const [requestId, pending] of this.pending) {
-      clearTimeout(pending.timer);
-      pendingInteractions.resolve(requestId);
-      pending.reject(
+    for (const requestId of [...this.ownedIds]) {
+      const interaction = pendingInteractions.resolve(requestId);
+      this.ownedIds.delete(requestId);
+      interaction?.rpcReject?.(
         new AssistantError("Prompter disposed", ErrorCode.INTERNAL_ERROR),
       );
     }
-    this.pending.clear();
   }
 }

package/src/permissions/secret-prompter.ts

@@ -20,12 +20,6 @@ export interface SecretPromptResult {
   error?: "unsupported_channel";
 }
 
-interface PendingSecretPrompt {
-  resolve: (result: SecretPromptResult) => void;
-  reject: (reason: Error) => void;
-  timer: ReturnType<typeof setTimeout>;
-}
-
 export interface SecretPrompterChannelContext {
   /** The channel the conversation was initiated from (e.g. "slack", "macos"). */
   channel?: string;
@@ -34,7 +28,13 @@ export interface SecretPrompterChannelContext {
 }
 
 export class SecretPrompter {
-  private pending = new Map<string, PendingSecretPrompt>();
+  /**
+   * Tracks which requestIds belong to this prompter instance so that
+   * dispose can scope its cleanup to this conversation.
+   * The full per-request state (callbacks, timer) lives in pendingInteractions,
+   * matching the host proxy and PermissionPrompter pattern.
+   */
+  private ownedIds = new Set<string>();
   private channelContext?: SecretPrompterChannelContext;
 
   setChannelContext(ctx: SecretPrompterChannelContext | undefined): void {
@@ -45,12 +45,9 @@ export class SecretPrompter {
    * Broadcast a secret_request to all connected clients and wait for a
    * response.
    *
-   * The request is always published to the SSE hub via
-   * {@link broadcastMessage} so any connected client (desktop, web) can
-   * display the secure prompt dialog.
-   *
-   * Pending interaction registration is handled by {@link broadcastMessage}
-   * when the secret_request event is published to the hub.
+   * Registers all lifecycle state (rpcResolve, rpcReject, timer) in
+   * pendingInteractions before broadcasting — identical to the host proxy
+   * and PermissionPrompter pattern.
    *
    * SECURITY: Logs only metadata (requestId, service, field) — never the
    * returned secret value. The timeout path also returns a null value
@@ -72,21 +69,24 @@ export class SecretPrompter {
 
     return new Promise((resolve, reject) => {
       const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
+
       const timer = setTimeout(() => {
-        this.pending.delete(requestId);
         pendingInteractions.resolve(requestId);
+        this.ownedIds.delete(requestId);
         log.warn({ requestId, service, field }, "Secret prompt timed out");
         resolve({ value: null, delivery: "store" });
       }, timeoutMs);
 
-      this.pending.set(requestId, { resolve, reject, timer });
-
-      // Self-register in pendingInteractions so /v1/secret can route the
-      // response to this conversation without relying on broadcastMessage.
+      // Register all lifecycle state in pendingInteractions — same pattern as
+      // host proxies and PermissionPrompter. The prompter tracks ownership via ownedIds.
       pendingInteractions.register(requestId, {
         conversationId: effectiveConversationId,
         kind: "secret",
+        rpcResolve: resolve as (value: unknown) => void,
+        rpcReject: reject,
+        timer,
       });
+      this.ownedIds.add(requestId);
 
       const config = getConfig();
       const msg: SecretRequestMessage = {
@@ -109,7 +109,7 @@ export class SecretPrompter {
   }
 
   hasPendingRequest(requestId: string): boolean {
-    return this.pending.has(requestId);
+    return this.ownedIds.has(requestId);
   }
 
   /**
@@ -124,26 +124,26 @@ export class SecretPrompter {
     value?: string,
     delivery?: SecretDelivery,
   ): void {
-    const pending = this.pending.get(requestId);
-    if (!pending) {
+    if (!this.ownedIds.has(requestId)) {
       log.warn({ requestId }, "No pending prompt for secret response");
       return;
     }
-    clearTimeout(pending.timer);
-    this.pending.delete(requestId);
-    // Clean up the global map (may already be removed by approval-routes).
-    pendingInteractions.resolve(requestId);
-    pending.resolve({ value: value ?? null, delivery: delivery ?? "store" });
+    // approval-routes calls pendingInteractions.get() before routing here;
+    // the prompter owns deregistration so it fires the Promise callback cleanly.
+    const interaction = pendingInteractions.resolve(requestId);
+    this.ownedIds.delete(requestId);
+    (interaction?.rpcResolve as ((v: SecretPromptResult) => void) | undefined)?.(
+      { value: value ?? null, delivery: delivery ?? "store" },
+    );
   }
 
   dispose(): void {
-    for (const [requestId, pending] of this.pending) {
-      clearTimeout(pending.timer);
-      pendingInteractions.resolve(requestId);
-      pending.reject(
+    for (const requestId of [...this.ownedIds]) {
+      const interaction = pendingInteractions.resolve(requestId);
+      this.ownedIds.delete(requestId);
+      interaction?.rpcReject?.(
         new AssistantError("Prompter disposed", ErrorCode.INTERNAL_ERROR),
       );
     }
-    this.pending.clear();
   }
 }

package/src/plugin-api/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+
+export type { PluginInitContext, PluginShutdownContext } 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,62 @@
+/**
+ * Public plugin-API types.
+ *
+ * This module is the source-of-truth for types that plugin authors depend on.
+ * The rest of the assistant imports from here via relative paths
+ * (`../plugin-api/types.js`). At publish time, this file's contents are
+ * bundled into the `@vellumai/plugin-api` npm package; at runtime in the
+ * assistant binary, the same source is reachable to user plugins via a
+ * boot-time shim that re-exports from the embedded bundle.
+ *
+ * Today this module is intentionally narrow — only `PluginInitContext` and
+ * `PluginShutdownContext`. Additional public types migrate over in
+ * follow-up PRs as the surface stabilizes.
+ *
+ * Internal-only types (pipeline shapes, middleware, manifest validation,
+ * etc.) stay in `assistant/src/plugins/types.ts` until they're ready to
+ * become public.
+ */
+
+// ─── 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> }`. Untyped here
+   * to avoid pulling pino into the types module.
+   */
+  logger: unknown;
+  /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
+  pluginStorageDir: string;
+  /** Assistant semver for compatibility checks inside the plugin. */
+  assistantVersion: string;
+  /** Capability → version-list map (`ASSISTANT_API_VERSIONS`) for defensive runtime checks. */
+  apiVersions: Record<string, 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;
+}

package/src/plugins/defaults/injectors.ts

@@ -50,7 +50,6 @@ import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-fl
 import { getConfig } from "../../config/loader.js";
 import { getInContextPkbPaths } from "../../daemon/pkb-context-tracker.js";
 import { buildPkbReminder } from "../../daemon/pkb-reminder-builder.js";
-import { isMemoryV2ReadActive } from "../../memory/context-search/sources/memory-v2.js";
 import { searchPkbFiles } from "../../memory/pkb/pkb-search.js";
 import { getLogger } from "../../util/logger.js";
 import { registerPlugin } from "../registry.js";
@@ -139,7 +138,7 @@ const diskPressureWarningInjector: Injector = {
  * state independent of PKB and fires unchanged.
  */
 function isPkbInjectionSilencedByV2(): boolean {
-  return isMemoryV2ReadActive(getConfig());
+  return getConfig().memory.v2.enabled;
 }
 
 /**
@@ -252,9 +251,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,
@@ -284,6 +298,7 @@ function buildPkbContextBlock(content: string): string {
  */
 async function buildPkbReminderWithHints(
   inputs: TurnInjectionInputs,
+  relaxed: boolean,
 ): Promise<string> {
   let hints: string[] = [];
   const queryVector = inputs.pkbQueryVector;
@@ -344,7 +359,7 @@ async function buildPkbReminderWithHints(
       hints = [];
     }
   }
-  return buildPkbReminder(hints);
+  return buildPkbReminder(hints, relaxed);
 }
 
 /**