@vellumai/assistant 0.6.3 → 0.6.5

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

@@ -9,6 +9,20 @@ export {
   createExtensionCdpClient,
   ExtensionCdpClient,
 } from "./extension-cdp-client.js";
-export { getCdpClient } from "./factory.js";
+export {
+  buildCandidateList,
+  buildChainedClient,
+  buildPinnedCandidateList,
+  getCdpClient,
+  type GetCdpClientOptions,
+} from "./factory.js";
 export { createLocalCdpClient, LocalCdpClient } from "./local-cdp-client.js";
-export type { CdpClient, CdpClientKind, ScopedCdpClient } from "./types.js";
+export type {
+  AttemptDiagnostic,
+  AttemptStage,
+  BackendCandidate,
+  BrowserMode,
+  CdpClient,
+  CdpClientKind,
+  ScopedCdpClient,
+} from "./types.js";

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

@@ -41,6 +41,51 @@ export interface CdpClient {
  */
 export type CdpClientKind = "local" | "extension" | "cdp-inspect";
 
+/**
+ * Backend mode preference for the CDP factory. Controls which
+ * transport is selected:
+ *
+ *  - `"auto"` — default, existing priority-ordered fallback
+ *    (extension → cdp-inspect → local).
+ *  - `"extension"` — pin to the chrome-extension backend. Fails
+ *    immediately if the host browser proxy is unavailable.
+ *  - `"cdp-inspect"` — pin to the cdp-inspect backend. Fails
+ *    immediately if cdp-inspect cannot connect.
+ *  - `"local"` — pin to the local Playwright backend. No fallback.
+ */
+export type BrowserMode = "auto" | "extension" | "cdp-inspect" | "local";
+
+/**
+ * Stage at which a candidate attempt ended. Used in
+ * {@link AttemptDiagnostic} to indicate how far the attempt progressed.
+ */
+export type AttemptStage =
+  | "candidate_selection" // failed before construction (precondition not met)
+  | "construction" // create() threw
+  | "send" // manager.send() threw or returned an error envelope
+  | "success"; // command completed successfully
+
+/**
+ * Structured diagnostic for a single candidate attempt during the
+ * factory's failover walk. Collected into an array and attached to
+ * thrown {@link CdpError} instances so higher layers can render
+ * detailed failure information in user-facing tool errors.
+ */
+export interface AttemptDiagnostic {
+  /** Which backend kind was attempted. */
+  readonly candidateKind: CdpClientKind;
+  /** Why this candidate was included (from {@link BackendCandidate.reason}). */
+  readonly inclusionReason: string;
+  /** How far the attempt progressed before it ended. */
+  readonly stage: AttemptStage;
+  /** Error code from the CdpError, if the attempt failed. */
+  readonly errorCode?: string;
+  /** Error message from the CdpError, if the attempt failed. */
+  readonly errorMessage?: string;
+  /** Discovery-level error code extracted from the underlying error, if any. */
+  readonly discoveryCode?: string;
+}
+
 /**
  * Concrete CdpClient instance returned by the factory. Carries the
  * backend `kind` for transport-aware branches in tool code.
@@ -50,3 +95,26 @@ export interface ScopedCdpClient extends CdpClient {
   /** Stable conversation id this client is bound to. */
   readonly conversationId: string;
 }
+
+/**
+ * A deferred backend candidate used by the chained factory. Each
+ * candidate carries a `kind` label and a `create` thunk that
+ * materialises the underlying {@link CdpClient} + {@link BrowserBackend}
+ * on demand. The factory only calls `create()` when the candidate is
+ * actually selected (either as the primary or as a failover target),
+ * so backends that are never reached pay zero setup cost.
+ */
+export interface BackendCandidate {
+  readonly kind: CdpClientKind;
+  /** Human-readable reason this candidate was included. */
+  readonly reason: string;
+  /**
+   * Materialise the backend. Called at most once — the factory caches
+   * the result after the first successful CDP command so subsequent
+   * commands reuse the same backend (sticky semantics).
+   */
+  create(): {
+    client: CdpClient;
+    backend: import("../../../browser-session/types.js").BrowserBackend;
+  };
+}

package/src/tools/credentials/tool-policy.ts

@@ -5,17 +5,48 @@
  * based on the credential's allowed tools list.
  */
 
+/**
+ * Canonical capability key for browser-based credential fills.
+ *
+ * This decouples credential policy from any specific tool name so that
+ * browser fill operations work regardless of whether a
+ * `browser_fill_credential` tool is registered in the manifest.
+ */
+export const BROWSER_FILL_CAPABILITY = "assistant_browser_fill_credential";
+
+/**
+ * Legacy tool names that map to canonical capability keys.
+ *
+ * Credentials stored with `browser_fill_credential` in their
+ * `allowedTools` metadata continue to authorize browser fills
+ * without requiring a manual migration.
+ */
+const LEGACY_ALIASES: ReadonlyMap<string, string> = new Map([
+  ["browser_fill_credential", BROWSER_FILL_CAPABILITY],
+]);
+
+/**
+ * Resolve a tool/capability name to its canonical form.
+ *
+ * If the name is a known legacy alias, returns the canonical key.
+ * Otherwise returns the name unchanged.
+ */
+function resolveCanonical(name: string): string {
+  return LEGACY_ALIASES.get(name) ?? name;
+}
+
 /**
  * Check whether a tool is allowed to use a credential.
  *
  * @param toolName - The name of the tool requesting credential use
  * @param allowedTools - The credential's allowed tools list
- * @returns true if the tool is explicitly listed in allowedTools
+ * @returns true if the tool is authorized after alias resolution
  *
  * Semantics:
- * 1. Explicit allowlist - tool must be listed by exact name
- * 2. No wildcard support in v1
- * 3. Fail-closed on empty or missing list
+ * 1. Both the requesting `toolName` and every entry in `allowedTools`
+ *    are resolved through the legacy-alias map before comparison.
+ * 2. No wildcard support in v1.
+ * 3. Fail-closed on empty or missing list.
  */
 export function isToolAllowed(
   toolName: string,
@@ -24,5 +55,8 @@ export function isToolAllowed(
   if (!Array.isArray(allowedTools) || allowedTools.length === 0) return false;
   if (!toolName || typeof toolName !== "string") return false;
 
-  return allowedTools.includes(toolName);
+  const canonical = resolveCanonical(toolName);
+  return allowedTools.some(
+    (allowed) => resolveCanonical(allowed) === canonical,
+  );
 }

package/src/tools/credentials/vault.ts

@@ -1,5 +1,6 @@
 import { getConfig } from "../../config/loader.js";
 import {
+  clearSlackUserToken,
   setSlackChannelConfig,
   type SlackChannelConfigResult,
 } from "../../daemon/handlers/config-slack-channel.js";
@@ -37,20 +38,24 @@ const log = getLogger("credential-vault");
 function isSlackChannelCredential(
   service: string,
   field: string,
-): field is "bot_token" | "app_token" {
+): field is "bot_token" | "app_token" | "user_token" {
   return (
     service === "slack_channel" &&
-    (field === "bot_token" || field === "app_token")
+    (field === "bot_token" || field === "app_token" || field === "user_token")
   );
 }
 
 async function storeSlackChannelCredential(
-  field: "bot_token" | "app_token",
+  field: "bot_token" | "app_token" | "user_token",
   value: string,
 ): Promise<SlackChannelConfigResult> {
-  return field === "bot_token"
-    ? setSlackChannelConfig(value, undefined)
-    : setSlackChannelConfig(undefined, value);
+  if (field === "bot_token") {
+    return setSlackChannelConfig(value, undefined);
+  }
+  if (field === "app_token") {
+    return setSlackChannelConfig(undefined, value);
+  }
+  return setSlackChannelConfig(undefined, undefined, value);
 }
 
 function formatSlackChannelStatus(result: SlackChannelConfigResult): string {
@@ -121,7 +126,7 @@ class CredentialStoreTool implements Tool {
             type: "array",
             items: { type: "string" },
             description:
-              'Tools allowed to use this credential (for store/prompt actions), e.g. ["browser_fill_credential"]. Empty = deny all.',
+              'Tools/capabilities allowed to use this credential (for store/prompt actions), e.g. ["assistant_browser_fill_credential"]. Empty = deny all.',
           },
           allowed_domains: {
             type: "array",
@@ -457,6 +462,28 @@ class CredentialStoreTool implements Tool {
           };
         }
 
+        // Surgical delete for the Slack user_token: it grants read-only access
+        // to channels the bot isn't a member of, but the Socket Mode connection
+        // is powered by the bot + app tokens. Tearing down the oauth_connection
+        // row when only user_token is removed would flap the integration's
+        // connected state until the next sync. Keep bot+app teardown behavior
+        // unchanged — those tokens are what the connection depends on.
+        if (service === "slack_channel" && field === "user_token") {
+          const slackResult = await clearSlackUserToken();
+          if (!slackResult.success) {
+            return {
+              content: `Error: ${
+                slackResult.error ?? "failed to delete Slack user token"
+              }`,
+              isError: true,
+            };
+          }
+          return {
+            content: `Deleted credential for ${service}/${field}.`,
+            isError: false,
+          };
+        }
+
         const key = credentialKey(service, field);
         const result = await deleteSecureKeyAsync(key);
         if (result === "error") {
@@ -664,6 +691,13 @@ class CredentialStoreTool implements Tool {
               : undefined,
         });
         if (!result.value) {
+          if (result.error === "unsupported_channel") {
+            return {
+              content:
+                "Secure credential entry cannot be opened over this channel. The user needs to complete this step from the desktop app, or run this flow from there directly.",
+              isError: true,
+            };
+          }
           return {
             content: "User cancelled the credential prompt.",
             isError: false,

package/src/tools/executor.ts

@@ -132,6 +132,10 @@ export class ToolExecutor {
         if (!permResult.allowed) {
           return { content: permResult.content, isError: true };
         }
+
+        if (permResult.wasPrompted) {
+          context.approvedViaPrompt = true;
+        }
       }
 
       const hookResult = await getHookManager().trigger("pre-tool-execute", {

package/src/tools/filesystem/write.ts

@@ -1,11 +1,35 @@
+import { join, resolve, sep } from "node:path";
+
+import { enqueuePkbIndexJob } from "../../memory/jobs/embed-pkb-file.js";
+import { PKB_WORKSPACE_SCOPE } from "../../memory/pkb/types.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
+import { getWorkspaceDir } from "../../util/platform.js";
 import { registerTool } from "../registry.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatWriteSummary } from "../shared/filesystem/format-diff.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
+const logger = getLogger("file-write");
+
+/**
+ * Returns `true` iff `absPath` is an absolute path that resolves strictly
+ * inside `pkbRoot`. Matches the containment semantics used elsewhere in the
+ * daemon (e.g. `pkb-context-tracker`): a root-with-separator prefix check,
+ * guarding against `<root>siblingDir` false positives.
+ */
+function isInsidePkbRoot(absPath: string, pkbRoot: string): boolean {
+  const normalizedRoot = resolve(pkbRoot);
+  const normalized = resolve(absPath);
+  if (normalized === normalizedRoot) return false;
+  const rootWithSep = normalizedRoot.endsWith(sep)
+    ? normalizedRoot
+    : normalizedRoot + sep;
+  return normalized.startsWith(rootWithSep);
+}
+
 class FileWriteTool implements Tool {
   name = "file_write";
   description =
@@ -86,6 +110,34 @@ class FileWriteTool implements Tool {
     }
 
     const { filePath, oldContent, newContent, isNewFile } = result.value;
+
+    // If the write landed inside the workspace PKB root, enqueue a
+    // fire-and-forget re-index job so Qdrant stays in sync with on-disk
+    // content. Failures here must never surface to the caller — a file
+    // was written successfully and that is the user-facing contract.
+    try {
+      const pkbRoot = join(getWorkspaceDir(), "pkb");
+      // Gate on `.md` to match `scanPkbFiles`, which only walks markdown.
+      // Indexing `pkb/*.json` (or any other extension) here would produce
+      // chunks the reconciler can't see, leading to orphaned vectors and
+      // pointless embedding work.
+      if (filePath.toLowerCase().endsWith(".md") && isInsidePkbRoot(filePath, pkbRoot)) {
+        enqueuePkbIndexJob({
+          pkbRoot,
+          absPath: filePath,
+          memoryScopeId: PKB_WORKSPACE_SCOPE,
+        });
+      }
+    } catch (err) {
+      logger.warn(
+        {
+          filePath,
+          error: err instanceof Error ? err.message : String(err),
+        },
+        "Failed to enqueue PKB re-index job after file_write",
+      );
+    }
+
     return {
       content: `Successfully wrote to ${filePath} ${formatWriteSummary(
         oldContent,

package/src/tools/host-terminal/host-shell.ts

@@ -31,6 +31,18 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 const log = getLogger("host-shell-tool");
 
+const HOST_BASH_PROXY_ENV_KEYS = [
+  // Preserve per-instance routing so nested `assistant` CLI commands invoked
+  // over host_bash proxy target the same daemon/socket as the origin turn.
+  "BASE_DATA_DIR",
+  "VELLUM_WORKSPACE_DIR",
+  // Keep legacy/diagnostic workspace + environment context aligned.
+  "VELLUM_DATA_DIR",
+  "VELLUM_ENVIRONMENT",
+  // Preserve local control-plane routing when nested commands call APIs.
+  "INTERNAL_GATEWAY_BASE_URL",
+] as const;
+
 function buildHostShellEnv(): Record<string, string> {
   const env = buildSanitizedEnv();
   // Ensure ~/.local/bin and ~/.bun/bin are in PATH so `vellum` and `bun` are
@@ -46,6 +58,29 @@ function buildHostShellEnv(): Record<string, string> {
   return env;
 }
 
+function buildHostBashProxyEnv(
+  hostLockdownActive: boolean,
+  conversationId: string,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const key of HOST_BASH_PROXY_ENV_KEYS) {
+    const value = process.env[key];
+    if (value != null && value.length > 0) {
+      env[key] = value;
+    }
+  }
+
+  if (hostLockdownActive) {
+    env.VELLUM_UNTRUSTED_SHELL = "1";
+  }
+
+  // Keep nested `assistant` CLI calls in host_bash aligned with the
+  // originating conversation so browser IPC can resolve live proxy context.
+  env.__CONVERSATION_ID = conversationId;
+  return env;
+}
+
 class HostShellTool implements Tool {
   name = "host_bash";
   description =
@@ -150,11 +185,13 @@ class HostShellTool implements Tool {
         1,
         Math.min(rawSec, shellMaxTimeoutSec),
       );
-      // Propagate VELLUM_UNTRUSTED_SHELL to the proxied client so CLI
-      // commands self-deny raw-secret flows even when executed remotely.
-      const proxyEnv: Record<string, string> | undefined = hostLockdownActive
-        ? { VELLUM_UNTRUSTED_SHELL: "1" }
-        : undefined;
+      // Forward instance-routing env vars so nested `assistant` CLI commands
+      // executed on a proxied host machine can still resolve the correct
+      // daemon IPC socket and workspace, plus lockdown marker when required.
+      const proxyEnv = buildHostBashProxyEnv(
+        hostLockdownActive,
+        context.conversationId,
+      );
       return context.hostBashProxy.request(
         {
           command,
@@ -199,6 +236,9 @@ class HostShellTool implements Tool {
       if (hostLockdownActive) {
         hostEnv.VELLUM_UNTRUSTED_SHELL = "1";
       }
+      // Match `bash` tool behavior so nested assistant CLI calls can bind to
+      // the active conversation when running through host_bash.
+      hostEnv.__CONVERSATION_ID = context.conversationId;
 
       const child = spawn("bash", ["-c", "--", command], {
         cwd: workingDir,

package/src/tools/memory/register.test.ts

@@ -0,0 +1,185 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+import { PKB_WORKSPACE_SCOPE } from "../../memory/pkb/types.js";
+import type { ToolContext } from "../types.js";
+
+let tmpWorkspace: string;
+let previousWorkspaceEnv: string | undefined;
+
+// Track calls to enqueuePkbIndexJob so we can assert remember wires writes
+// through to the re-index queue. Declared at module scope so the mock.module
+// factory (hoisted) can close over it.
+const enqueueCalls: Array<{
+  pkbRoot: string;
+  absPath: string;
+  memoryScopeId: string;
+}> = [];
+let enqueueShouldThrow = false;
+
+mock.module("../../memory/jobs/embed-pkb-file.js", () => ({
+  enqueuePkbIndexJob: (input: {
+    pkbRoot: string;
+    absPath: string;
+    memoryScopeId: string;
+  }) => {
+    enqueueCalls.push(input);
+    if (enqueueShouldThrow) {
+      throw new Error("simulated enqueue failure");
+    }
+    return "job-mock-id";
+  },
+}));
+
+beforeAll(() => {
+  tmpWorkspace = mkdtempSync(join(tmpdir(), "remember-tool-test-"));
+  previousWorkspaceEnv = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = tmpWorkspace;
+});
+
+afterAll(() => {
+  if (previousWorkspaceEnv === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = previousWorkspaceEnv;
+  }
+  rmSync(tmpWorkspace, { recursive: true, force: true });
+});
+
+// Import after the env var is set so getWorkspaceDir() resolves to the tmpdir.
+const { rememberTool } = await import("./register.js");
+
+function makeContext(overrides: Partial<ToolContext> = {}): ToolContext {
+  return {
+    workingDir: tmpWorkspace,
+    conversationId: "test-conversation",
+    trustClass: "guardian",
+    ...overrides,
+  };
+}
+
+describe("rememberTool.execute — finish_turn", () => {
+  test("omits yieldToUser when finish_turn is not provided", async () => {
+    const result = await rememberTool.execute(
+      { content: "no finish_turn provided" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    expect(result.yieldToUser).toBeUndefined();
+  });
+
+  test("omits yieldToUser when finish_turn is false", async () => {
+    const result = await rememberTool.execute(
+      { content: "finish_turn=false", finish_turn: false },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    expect(result.yieldToUser).toBeUndefined();
+  });
+
+  test("sets yieldToUser=true when finish_turn is true", async () => {
+    const result = await rememberTool.execute(
+      { content: "finish_turn=true", finish_turn: true },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    expect(result.yieldToUser).toBe(true);
+  });
+
+  test("sets yieldToUser=true even when the write fails (empty content)", async () => {
+    const result = await rememberTool.execute(
+      { content: "", finish_turn: true },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.yieldToUser).toBe(true);
+  });
+});
+
+describe("rememberTool.execute — PKB re-index enqueue", () => {
+  beforeEach(() => {
+    enqueueCalls.length = 0;
+    enqueueShouldThrow = false;
+  });
+
+  test("enqueues re-index jobs for both buffer and daily archive paths", async () => {
+    const result = await rememberTool.execute(
+      { content: "index me please" },
+      // Passes a non-default per-conversation scopeId to prove the PKB
+      // enqueue ignores it and pins to PKB_WORKSPACE_SCOPE instead.
+      makeContext({ memoryScopeId: "scope-enqueue" }),
+    );
+    expect(result.isError).toBe(false);
+
+    const pkbRoot = join(tmpWorkspace, "pkb");
+    const bufferPath = join(pkbRoot, "buffer.md");
+
+    // Archive path is dated; derive from today's date the same way
+    // handleRemember does.
+    const now = new Date();
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, "0");
+    const dd = String(now.getDate()).padStart(2, "0");
+    const archivePath = join(pkbRoot, "archive", `${yyyy}-${mm}-${dd}.md`);
+
+    expect(enqueueCalls).toHaveLength(2);
+    expect(enqueueCalls[0]).toEqual({
+      pkbRoot,
+      absPath: bufferPath,
+      memoryScopeId: PKB_WORKSPACE_SCOPE,
+    });
+    expect(enqueueCalls[1]).toEqual({
+      pkbRoot,
+      absPath: archivePath,
+      memoryScopeId: PKB_WORKSPACE_SCOPE,
+    });
+  });
+
+  test("does not enqueue when content is empty (write was skipped)", async () => {
+    const result = await rememberTool.execute(
+      { content: "   " },
+      makeContext({ memoryScopeId: "scope-empty" }),
+    );
+    expect(result.isError).toBe(true);
+    expect(enqueueCalls).toHaveLength(0);
+  });
+
+  test("thrown enqueue does not surface; remember still writes files", async () => {
+    enqueueShouldThrow = true;
+
+    const result = await rememberTool.execute(
+      { content: "enqueue will throw" },
+      makeContext({ memoryScopeId: "scope-throw" }),
+    );
+
+    // Remember call succeeded despite enqueue throwing for each write.
+    expect(result.isError).toBe(false);
+
+    // Both writes attempted their enqueue.
+    expect(enqueueCalls).toHaveLength(2);
+
+    // Files were written correctly.
+    const pkbRoot = join(tmpWorkspace, "pkb");
+    const bufferPath = join(pkbRoot, "buffer.md");
+    const bufferContents = readFileSync(bufferPath, "utf-8");
+    expect(bufferContents).toContain("enqueue will throw");
+
+    const now = new Date();
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, "0");
+    const dd = String(now.getDate()).padStart(2, "0");
+    const archivePath = join(pkbRoot, "archive", `${yyyy}-${mm}-${dd}.md`);
+    const archiveContents = readFileSync(archivePath, "utf-8");
+    expect(archiveContents).toContain("enqueue will throw");
+  });
+});

package/src/tools/memory/register.ts

@@ -29,14 +29,16 @@ class RememberTool implements Tool {
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
+    const typedInput = input as unknown as RememberInput;
     const result = handleRemember(
-      input as unknown as RememberInput,
+      typedInput,
       context.conversationId,
       context.memoryScopeId ?? "default",
     );
     return {
       content: result.message,
       isError: !result.success,
+      ...(typedInput.finish_turn === true ? { yieldToUser: true } : {}),
     };
   }
 }