@vellumai/assistant 0.6.6 → 0.7.0

package/src/tools/acp/steer.test.ts

@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ToolContext } from "../types.js";
+
+interface SteerCall {
+  acpSessionId: string;
+  instruction: string;
+}
+
+const steerCalls: SteerCall[] = [];
+const defaultSteer = (acpSessionId: string, instruction: string) => {
+  steerCalls.push({ acpSessionId, instruction });
+  return Promise.resolve();
+};
+let steerImpl: (acpSessionId: string, instruction: string) => Promise<void> =
+  defaultSteer;
+
+// Spread the real module's exports so transitive importers that pull other
+// names from `../../acp/index.js` (e.g. `broadcastToAllClients` from the
+// HTTP route layer) still resolve at parse time. Bun's `mock.module` is
+// process-global and returns *exactly* the keys the factory returns.
+const realAcpModule = await import("../../acp/index.js");
+mock.module("../../acp/index.js", () => ({
+  ...realAcpModule,
+  getAcpSessionManager: () => ({
+    steer: (acpSessionId: string, instruction: string) =>
+      steerImpl(acpSessionId, instruction),
+  }),
+}));
+
+const { executeAcpSteer } = await import("./steer.js");
+
+function makeContext(): ToolContext {
+  return {
+    workingDir: "/tmp",
+    conversationId: "conv-test",
+    trustClass: "guardian",
+  };
+}
+
+beforeEach(() => {
+  steerCalls.length = 0;
+  steerImpl = defaultSteer;
+});
+
+describe("executeAcpSteer", () => {
+  test("happy path: returns steered status and forwards args to manager", async () => {
+    const result = await executeAcpSteer(
+      { acp_session_id: "acp-123", instruction: "stop, do X instead" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(steerCalls).toEqual([
+      { acpSessionId: "acp-123", instruction: "stop, do X instead" },
+    ]);
+
+    const parsed = JSON.parse(result.content as string);
+    expect(parsed).toEqual({
+      acpSessionId: "acp-123",
+      status: "steered",
+      message: "Interrupted in-flight prompt; new instruction is now running.",
+    });
+  });
+
+  test("missing instruction returns isError", async () => {
+    const result = await executeAcpSteer(
+      { acp_session_id: "acp-123" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('"instruction" is required');
+    expect(steerCalls).toEqual([]);
+  });
+
+  test("missing acp_session_id returns isError", async () => {
+    const result = await executeAcpSteer(
+      { instruction: "do something" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('"acp_session_id" is required');
+    expect(steerCalls).toEqual([]);
+  });
+
+  test("manager.steer throwing 'session not found' surfaces the error", async () => {
+    steerImpl = () =>
+      Promise.reject(new Error('ACP session "acp-x" not found'));
+
+    const result = await executeAcpSteer(
+      { acp_session_id: "acp-x", instruction: "redirect" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Could not steer ACP session "acp-x"');
+    expect(result.content).toContain("not found");
+  });
+});

package/src/tools/acp/steer.ts

@@ -0,0 +1,38 @@
+import { getAcpSessionManager } from "../../acp/index.js";
+import type { ToolContext, ToolExecutionResult } from "../types.js";
+
+export async function executeAcpSteer(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const acpSessionId = input.acp_session_id as string;
+  if (!acpSessionId) {
+    return { content: '"acp_session_id" is required.', isError: true };
+  }
+
+  const instruction = input.instruction as string;
+  if (!instruction) {
+    return { content: '"instruction" is required.', isError: true };
+  }
+
+  try {
+    const manager = getAcpSessionManager();
+    await manager.steer(acpSessionId, instruction);
+
+    return {
+      content: JSON.stringify({
+        acpSessionId,
+        status: "steered",
+        message:
+          "Interrupted in-flight prompt; new instruction is now running.",
+      }),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      content: `Could not steer ACP session "${acpSessionId}": ${msg}`,
+      isError: true,
+    };
+  }
+}

package/src/tools/background-tool-registry.ts

@@ -0,0 +1,98 @@
+/**
+ * In-memory registry for background tool executions.
+ *
+ * Background tools are long-running processes (e.g. bash, host_bash) that the
+ * agent spawns and returns from immediately. When the process finishes, its
+ * output is delivered back to the conversation via `wakeAgentForOpportunity`.
+ *
+ * The registry tracks active background tools so they can be listed, cancelled,
+ * and cleaned up. The `toolName` field is intentionally generic (not limited to
+ * shell tools) to support extending background execution to non-shell tools in
+ * the future.
+ */
+
+export interface BackgroundTool {
+  id: string;
+  /** Tool type identifier (e.g. "bash", "host_bash"). */
+  toolName: string;
+  conversationId: string;
+  command: string;
+  startedAt: number;
+  /** Kills the process (bash) or aborts the proxy (host_bash). */
+  cancel: () => void;
+}
+
+/** Maximum number of concurrent background tools allowed. */
+export const MAX_BACKGROUND_TOOLS = 20;
+
+const registry = new Map<string, BackgroundTool>();
+
+/**
+ * Registers a background tool in the in-memory store.
+ * Throws if the registry would exceed {@link MAX_BACKGROUND_TOOLS}.
+ */
+export function registerBackgroundTool(tool: BackgroundTool): void {
+  if (registry.size >= MAX_BACKGROUND_TOOLS) {
+    throw new Error(
+      `Background tool limit reached (max ${MAX_BACKGROUND_TOOLS}). Cancel an existing background tool before starting a new one.`,
+    );
+  }
+  registry.set(tool.id, tool);
+}
+
+/** Removes a background tool entry by ID. */
+export function removeBackgroundTool(id: string): void {
+  registry.delete(id);
+}
+
+/**
+ * Returns all registered background tools, optionally filtered by
+ * `conversationId`.
+ */
+export function listBackgroundTools(conversationId?: string): BackgroundTool[] {
+  const all = Array.from(registry.values());
+  if (conversationId === undefined) {
+    return all;
+  }
+  return all.filter((t) => t.conversationId === conversationId);
+}
+
+/**
+ * Cancels a background tool by ID: calls `tool.cancel()`, removes the entry,
+ * and returns `true`. Returns `false` if the ID is not found.
+ */
+export function cancelBackgroundTool(id: string): boolean {
+  const tool = registry.get(id);
+  if (!tool) {
+    return false;
+  }
+  tool.cancel();
+  registry.delete(id);
+  return true;
+}
+
+/**
+ * Generates a short prefixed ID for a background tool.
+ * Format: `bg-<8 hex chars>` (e.g. `bg-a1b2c3d4`).
+ */
+export function generateBackgroundToolId(): string {
+  return `bg-${crypto.randomUUID().slice(0, 8)}`;
+}
+
+/**
+ * Returns `true` when the registry is at or over the {@link MAX_BACKGROUND_TOOLS}
+ * limit, meaning no new background tools can be registered. Callers should
+ * check this **before** spawning a process to avoid leaking untracked
+ * processes.
+ */
+export function isBackgroundToolLimitReached(): boolean {
+  return registry.size >= MAX_BACKGROUND_TOOLS;
+}
+
+/**
+ * Clears the entire registry. Intended for test cleanup only — production
+ * code should use {@link cancelBackgroundTool} or {@link removeBackgroundTool}.
+ */
+export function _clearRegistryForTesting(): void {
+  registry.clear();
+}

package/src/tools/browser/browser-execution.ts

@@ -75,13 +75,13 @@ const log = getLogger("headless-browser");
 
 // ── Constants ────────────────────────────────────────────────────────
 
-export const NAVIGATE_TIMEOUT_MS = 15_000;
+const NAVIGATE_TIMEOUT_MS = 15_000;
 
-export const ACTION_TIMEOUT_MS = 10_000;
+const ACTION_TIMEOUT_MS = 10_000;
 
-export const MAX_WAIT_MS = 30_000;
+const MAX_WAIT_MS = 30_000;
 
-export const MAX_EXTRACT_LENGTH = 50_000;
+const MAX_EXTRACT_LENGTH = 50_000;
 
 type StatusCheckMode = BrowserStatusMode;
 
@@ -359,7 +359,7 @@ function isRestrictedChromePageProbeError(error: CdpError): boolean {
  * The returned client is wrapped so its first successful `send()`
  * writes the resolved kind back to the conversation memo.
  */
-export function acquireCdpClientWithMode(
+function acquireCdpClientWithMode(
   input: Record<string, unknown>,
   context: ToolContext,
 ):
@@ -514,7 +514,7 @@ export type ResolvedElement =
  * or when an `element_id` is provided but the snapshot map is
  * empty/stale.
  */
-export function resolveElement(
+function resolveElement(
   conversationId: string,
   input: Record<string, unknown>,
 ): { resolved: ResolvedElement | null; error: string | null } {
@@ -2179,7 +2179,7 @@ function probeFailureActions(mode: StatusCheckMode, error: CdpError): string[] {
       )
     ) {
       actions.push(
-        "Ensure this extension ID is present in meta/browser-extension/chrome-extension-allowlist.json and restart the assistant.",
+        "Ensure this extension ID is present in chrome-extension-allowlist.local.json in $GATEWAY_SECURITY_DIR and restart the assistant.",
       );
     }
     if (
@@ -2286,8 +2286,35 @@ async function checkExtensionModeStatus(
   const proxyBound = Boolean(context.hostBrowserProxy);
   const proxyConnected = context.hostBrowserProxy?.isAvailable() ?? false;
   const isMacOS = context.transportInterface === "macos";
+  const registryClients = context.connectedBrowserClients ?? [];
+  const extensionClients = registryClients.filter(
+    (c) => c.interfaceId === "chrome-extension",
+  );
 
   if (!proxyBound) {
+    // No proxy bound to this conversation, but the client registry may
+    // show a connected chrome-extension client with host_browser capability.
+    // Report that so `assistant browser status` from the CLI is accurate.
+    if (extensionClients.length > 0) {
+      return {
+        mode: BROWSER_STATUS_MODE.EXTENSION,
+        available: false,
+        verified: "preflight",
+        autoCandidate,
+        summary:
+          "Extension mode: a Chrome extension client is connected but no host browser proxy is bound to this conversation. " +
+          "Extension browser operations will be available within a conversation turn initiated from the extension.",
+        userActions: [],
+        tradeoffs: modeTradeoffs(BROWSER_STATUS_MODE.EXTENSION),
+        details: {
+          proxyBound,
+          proxyConnected,
+          connectedExtensionClients: extensionClients,
+          transport: "extension-ws",
+        },
+      };
+    }
+
     return {
       mode: BROWSER_STATUS_MODE.EXTENSION,
       available: false,

package/src/tools/browser/browser-manager.ts

@@ -561,10 +561,7 @@ class BrowserManager {
    * any prior value so an explicit `browser_mode` override on one call
    * becomes the default for subsequent `auto`-mode calls.
    */
-  setPreferredBackendKind(
-    conversationId: string,
-    kind: CdpClientKind,
-  ): void {
+  setPreferredBackendKind(conversationId: string, kind: CdpClientKind): void {
     this.preferredBackendKinds.set(conversationId, kind);
   }
 
@@ -953,7 +950,3 @@ class BrowserManager {
 }
 
 export const browserManager = new BrowserManager();
-
-export function isAuthenticatedForDomain(domain: string): boolean {
-  return authSessionCache.isAuthenticated(domain);
-}

package/src/tools/browser/cdp-client/accessibility-snapshot.ts

@@ -47,7 +47,7 @@ export interface AxSnapshotResult {
 // ── Constants ─────────────────────────────────────────────────────────
 
 /** Default maximum number of interactive elements returned in a snapshot. */
-export const DEFAULT_MAX_ELEMENTS = 150;
+const DEFAULT_MAX_ELEMENTS = 150;
 
 /**
  * AX roles we consider "interactive" and surface to the LLM. Includes

package/src/tools/browser/cdp-client/cdp-inspect/discovery.ts

@@ -25,6 +25,8 @@
  * value.
  */
 
+import type { CdpWsTransport } from "./ws-transport.js";
+
 /**
  * Stable error codes surfaced by discovery helpers.
  *
@@ -704,7 +706,7 @@ interface CdpTargetInfo {
  * @param signal - Optional abort signal for the CDP call.
  */
 export async function discoverTargetsViaWs(opts: {
-  transport: import("./ws-transport.js").CdpWsTransport;
+  transport: CdpWsTransport;
   host: string;
   port: number;
   signal?: AbortSignal;

package/src/tools/browser/cdp-client/types.ts

@@ -7,6 +7,9 @@
  * `send(method, params)` with a CDP method name and return the raw
  * CDP result object; errors are thrown as {@link CdpError}.
  */
+
+import type { BrowserBackend } from "../../../browser-session/types.js";
+
 export interface CdpClient {
   /**
    * Send a CDP command and await the result. `method` must be a
@@ -115,6 +118,6 @@ export interface BackendCandidate {
    */
   create(): {
     client: CdpClient;
-    backend: import("../../../browser-session/types.js").BrowserBackend;
+    backend: BrowserBackend;
   };
 }

package/src/tools/computer-use/definitions.ts

@@ -457,7 +457,7 @@ export const computerUseRespondTool: Tool = {
 // observe
 // ---------------------------------------------------------------------------
 
-export const computerUseObserveTool: Tool = {
+const computerUseObserveTool: Tool = {
   name: "computer_use_observe",
   description:
     "Capture the current screen state. Returns the accessibility tree with [ID] element references and optionally a screenshot.\n\nThe accessibility tree shows interactive elements like [3] AXButton 'Save' or [17] AXTextField 'Search'. Use element_id to target these elements in subsequent actions - this is much more reliable than pixel coordinates.\n\nCall this before your first computer use action, or to check screen state without acting.",

package/src/tools/credential-execution/make-authenticated-request.ts

@@ -6,11 +6,11 @@
  * the outbound request internally and returns the sanitised response.
  *
  * The input schema matches the `MakeAuthenticatedRequestSchema` from
- * `@vellumai/ces-contracts` exactly so the LLM-produced parameters pass
+ * `@vellumai/service-contracts/credential-rpc` exactly so the LLM-produced parameters pass
  * straight through to the CES RPC call with no transformation.
  */
 
-import { GrantProposalSchema, renderProposal } from "@vellumai/ces-contracts";
+import { GrantProposalSchema, renderProposal } from "@vellumai/service-contracts/credential-rpc";
 
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";

package/src/tools/credential-execution/manage-secure-command-tool.ts

@@ -15,7 +15,7 @@
  * verification, and installation inside the CES sandbox.
  */
 
-import type { ManageSecureCommandTool } from "@vellumai/ces-contracts/rpc";
+import type { ManageSecureCommandTool } from "@vellumai/service-contracts/rpc";
 
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";

package/src/tools/credential-execution/run-authenticated-command.ts

@@ -6,11 +6,11 @@
  * runs it inside the CES sandbox - the assistant never sees raw secrets.
  *
  * The input schema matches the `RunAuthenticatedCommandSchema` from
- * `@vellumai/ces-contracts` exactly so the LLM-produced parameters pass
+ * `@vellumai/service-contracts/credential-rpc` exactly so the LLM-produced parameters pass
  * straight through to the CES RPC call with no transformation.
  */
 
-import { GrantProposalSchema, renderProposal } from "@vellumai/ces-contracts";
+import { GrantProposalSchema, renderProposal } from "@vellumai/service-contracts/credential-rpc";
 
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";

package/src/tools/credentials/broker-types.ts

@@ -1,4 +1,5 @@
 /** Opaque token representing a policy-checked authorization to use a credential. */
+import type { CredentialInjectionTemplate } from "./policy-types.js";
 export interface UsageToken {
   tokenId: string;
   credentialId: string;
@@ -95,7 +96,7 @@ export interface ServerUseByIdSuccess {
   credentialId: string;
   service: string;
   field: string;
-  injectionTemplates: import("./policy-types.js").CredentialInjectionTemplate[];
+  injectionTemplates: CredentialInjectionTemplate[];
 }
 
 /** Denied or not-found by-id lookup result. */

package/src/tools/document/editor-template.ts

@@ -234,7 +234,7 @@ export function generateEditorHTML(
   `.trim();
 }
 
-export function escapeHtml(str: string): string {
+function escapeHtml(str: string): string {
   return str
     .replace(/&/g, "&")
     .replace(/</g, "&lt;")

package/src/tools/execution-timeout.ts

@@ -2,7 +2,7 @@ import type { ToolExecutionResult } from "./types.js";
 
 const TIMEOUT_SENTINEL = Symbol("tool-timeout");
 
-export const DEFAULT_TOOL_TIMEOUT_SEC = 120;
+const DEFAULT_TOOL_TIMEOUT_SEC = 120;
 
 /**
  * Convert a config-provided seconds value to a safe milliseconds value,

package/src/tools/executor.ts

@@ -60,16 +60,14 @@ export class ToolExecutor {
      * middleware registered on the `toolExecute` pipeline sees the same
      * context every other pipeline slot uses. When omitted (CLI/test
      * invocations that call `ToolExecutor.execute` directly), the executor
-     * synthesizes a fallback context from the {@link ToolContext}, which
-     * keeps pre-threading behavior intact for legacy callers.
+     * synthesizes a fallback context from the {@link ToolContext}.
      */
     turnContext?: TurnContext,
   ): Promise<ToolExecutionResult> {
     // Prefer the orchestrator-supplied `turnContext` so the pipeline sees
     // the real conversation identity, per-turn trust, and context-window
     // manager. When absent (CLI / test invocations that bypass the agent
-    // loop), synthesize a minimal context from the `ToolContext` — the
-    // same fallback the executor has used since the pipeline was added.
+    // loop), synthesize a minimal context from the `ToolContext`.
     const turnCtx: TurnContext = turnContext ?? {
       requestId: context.requestId ?? "",
       conversationId: context.conversationId,
@@ -85,14 +83,11 @@ export class ToolExecutor {
 
     // No pipeline-level timeout: `executeInternal` already wraps the real
     // tool invocation in `executeWithTimeout`, which is the sole enforcer
-    // of the per-tool budget. Propagating `perToolTimeoutMs` to
-    // `runPipeline` made the pipeline race everything upstream of the
-    // tool call — permission checks, approval waits, middleware — against
-    // the same budget, so a slow human clicking "allow" produced a
-    // `PluginTimeoutError` thrown past `executeInternal`'s catch block,
-    // breaking the `execute()` never-throws contract. Letting the pipeline
-    // run untimed keeps the contract intact; runaway middleware is a
-    // plugin-health concern handled by per-plugin timeouts, not here.
+    // of the per-tool budget. The pipeline itself runs untimed so that
+    // upstream phases (permission checks, approval waits, middleware) are
+    // not racing the tool budget — only the actual tool call is. Runaway
+    // middleware is a plugin-health concern handled by per-plugin timeouts,
+    // not here.
     return runPipeline<ToolExecuteArgs, ToolExecuteResult>(
       "toolExecute",
       middlewares,
@@ -177,6 +172,7 @@ export class ToolExecutor {
             riskLevel: string;
             riskReason: string;
             riskScopeOptions: Array<{ pattern: string; label: string }>;
+            riskDirectoryScopeOptions?: Array<{ scope: string; label: string }>;
             isContainerized?: boolean;
           }
         | undefined;
@@ -204,6 +200,7 @@ export class ToolExecutor {
             riskLevel: permRiskMeta?.riskLevel,
             riskReason: permRiskMeta?.riskReason,
             riskScopeOptions: permRiskMeta?.riskScopeOptions,
+            riskDirectoryScopeOptions: permRiskMeta?.riskDirectoryScopeOptions,
             isContainerized: permRiskMeta?.isContainerized,
           };
         }
@@ -423,6 +420,7 @@ export class ToolExecutor {
           riskLevel: permRiskMeta.riskLevel,
           riskReason: permRiskMeta.riskReason,
           riskScopeOptions: permRiskMeta.riskScopeOptions,
+          riskDirectoryScopeOptions: permRiskMeta.riskDirectoryScopeOptions,
           isContainerized: permRiskMeta.isContainerized,
         };
       }
@@ -491,9 +489,6 @@ export class ToolExecutor {
 // `executor.ts` continue to work without changing their imports.
 export { isSideEffectTool } from "./side-effects.js";
 
-// Re-export PermissionChecker for consumers that need direct access
-export { PermissionChecker } from "./permission-checker.js";
-
 /**
  * Compute the effective per-tool execution timeout in milliseconds.
  *