@vellumai/assistant 0.6.2 → 0.6.4

package/src/permissions/defaults.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { getIsContainerized } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
 import { getBundledSkillsDir } from "../config/skills.js";
+import { resolveGuardianPersonaPath } from "../prompts/persona-resolver.js";
 import { getWorkspaceDir } from "../util/platform.js";
 
 export interface DefaultRuleTemplate {
@@ -15,6 +16,16 @@ export interface DefaultRuleTemplate {
   allowHighRisk?: boolean;
 }
 
+/**
+ * Escape minimatch metacharacters so a literal path is matched literally when
+ * interpolated into a rule pattern. Without this, characters like `*`, `?`,
+ * `[`, `]`, `{`, `}` in a filename would be treated as wildcards and broaden
+ * the resulting allow rule beyond the intended file.
+ */
+function escapeMinimatchPath(p: string): string {
+  return p.replace(/[?*[\]{}()!|\\]/g, "\\$&");
+}
+
 const HOST_FILE_TOOLS = [
   "host_file_read",
   "host_file_write",
@@ -118,7 +129,6 @@ export function getDefaultRuleTemplates(): DefaultRuleTemplate[] {
   const workspaceDir = getWorkspaceDir().replaceAll("\\", "/");
   const WORKSPACE_PROMPT_FILES = [
     "IDENTITY.md",
-    "USER.md",
     "SOUL.md",
     "BOOTSTRAP.md",
     "UPDATES.md",
@@ -139,6 +149,40 @@ export function getDefaultRuleTemplates(): DefaultRuleTemplate[] {
     })),
   );
 
+  // Guardian persona file — the contact-store-resolved `users/<slug>.md`
+  // for the current guardian. Once the workspace has a guardian contact,
+  // their per-user persona file should be readable/editable without a
+  // prompt.
+  //
+  // Resolved dynamically at template-build time (rather than hardcoded
+  // like WORKSPACE_PROMPT_FILES) because the slug depends on the
+  // installed guardian. The try/catch protects against early-boot paths
+  // where the DB may not yet be initialized — in that case no guardian
+  // persona rules are emitted and the agent will be prompted on first
+  // edit until the guardian contact is created.
+  let guardianPersonaRules: DefaultRuleTemplate[] = [];
+  try {
+    const guardianPath = resolveGuardianPersonaPath();
+    if (guardianPath) {
+      const posixPath = guardianPath.replaceAll("\\", "/");
+      const escapedPath = escapeMinimatchPath(posixPath);
+      guardianPersonaRules = WORKSPACE_FILE_TOOLS.map((tool) => ({
+        id: `default:allow-${tool}-guardian-persona`,
+        tool,
+        pattern: `${tool}:${escapedPath}`,
+        scope: "everywhere",
+        decision: "allow" as const,
+        priority: 100,
+      }));
+    }
+  } catch {
+    // If guardian resolution fails at default-rule computation, the rule
+    // will be missing until the trust cache is invalidated and rebuilt.
+    // Runtime guardian-creation paths invalidate the cache via
+    // `clearTrustCache()` in `contacts-write.createGuardianBinding` so
+    // that the next `getRules()` call picks up the new auto-allow rule.
+  }
+
   const bootstrapDeleteRule: DefaultRuleTemplate = {
     id: "default:allow-bash-rm-bootstrap",
     tool: "bash",
@@ -248,6 +292,8 @@ export function getDefaultRuleTemplates(): DefaultRuleTemplate[] {
     "browser_snapshot",
     "browser_screenshot",
     "browser_close",
+    "browser_attach",
+    "browser_detach",
     "browser_click",
     "browser_type",
     "browser_press_key",
@@ -258,6 +304,7 @@ export function getDefaultRuleTemplates(): DefaultRuleTemplate[] {
     "browser_extract",
     "browser_wait_for_download",
     "browser_fill_credential",
+    "browser_status",
   ] as const;
 
   const browserToolRules: DefaultRuleTemplate[] = BROWSER_TOOLS_NO_SLASH.map(
@@ -303,6 +350,7 @@ export function getDefaultRuleTemplates(): DefaultRuleTemplate[] {
     ...computerUseRules,
     ...managedSkillRules,
     ...workspacePromptRules,
+    ...guardianPersonaRules,
     bootstrapDeleteRule,
     updatesDeleteRule,
     ...skillSourceMutationRules,

package/src/permissions/permission-mode.ts

@@ -1,27 +1,20 @@
 import { z } from "zod";
 
 /**
- * Two-axis permission model:
- * - `askBeforeActing` — LLM behavior toggle: when true the assistant checks in
- *   with the user before taking actions.
- * - `hostAccess` — System-enforced gate: when true the assistant can execute
- *   commands on the host machine without prompting.
+ * Host-access permission state.
+ *
+ * The only remaining permission-mode axis is whether the assistant can
+ * execute commands on the host machine without prompting.
  */
 export type PermissionMode = {
-  askBeforeActing: boolean;
   hostAccess: boolean;
 };
 
 export const DEFAULT_PERMISSION_MODE: PermissionMode = {
-  askBeforeActing: true,
   hostAccess: false,
 };
 
 export const PermissionModeSchema = z.object({
-  askBeforeActing: z
-    .boolean({ error: "permissionMode.askBeforeActing must be a boolean" })
-    .default(true)
-    .describe("Whether the assistant should check in before taking actions"),
   hostAccess: z
     .boolean({ error: "permissionMode.hostAccess must be a boolean" })
     .default(false)

package/src/permissions/prompter.ts

@@ -20,6 +20,7 @@ interface PendingPrompt {
   reject: (reason: Error) => void;
   timer: ReturnType<typeof setTimeout>;
   toolUseId?: string;
+  hostAccessEnablePrompt?: boolean;
 }
 
 export type ConfirmationStateCallback = (
@@ -64,6 +65,7 @@ export class PermissionPrompter {
     signal?: AbortSignal,
     temporaryOptionsAvailable?: Array<"allow_10m" | "allow_conversation">,
     toolUseId?: string,
+    hostAccessEnablePrompt?: boolean,
   ): Promise<{
     decision: UserDecision;
     selectedPattern?: string;
@@ -89,7 +91,13 @@ export class PermissionPrompter {
         });
       }, timeoutMs);
 
-      this.pending.set(requestId, { resolve, reject, timer, toolUseId });
+      this.pending.set(requestId, {
+        resolve,
+        reject,
+        timer,
+        toolUseId,
+        hostAccessEnablePrompt,
+      });
 
       if (signal) {
         const onAbort = () => {
@@ -143,6 +151,10 @@ export class PermissionPrompter {
     return this.pending.get(requestId)?.toolUseId;
   }
 
+  isHostAccessEnablePrompt(requestId: string): boolean {
+    return this.pending.get(requestId)?.hostAccessEnablePrompt === true;
+  }
+
   resolveConfirmation(
     requestId: string,
     decision: UserDecision,

package/src/permissions/trust-store.ts

@@ -6,7 +6,6 @@ import {
   renameSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { Minimatch } from "minimatch";
@@ -14,6 +13,7 @@ import { v4 as uuid } from "uuid";
 
 import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
+import { getProtectedDir } from "../util/platform.js";
 import { getDefaultRuleTemplates } from "./defaults.js";
 import * as trustClient from "./trust-client.js";
 import type {
@@ -135,12 +135,12 @@ function getTrustPath(): string {
  * Resolve the gateway security directory.
  *
  * Docker: `GATEWAY_SECURITY_DIR` env var.
- * Local:  falls back to `~/.vellum/` + `protected/`.
+ * Local:  the per-instance protected directory resolved by `getProtectedDir()`.
  */
 function getGatewaySecurityDir(): string {
   const securityDir = process.env.GATEWAY_SECURITY_DIR;
   if (securityDir) return securityDir;
-  return join(homedir(), ".vellum", "protected");
+  return getProtectedDir();
 }
 
 /**

package/src/permissions/v2-consent-policy.ts

@@ -0,0 +1,87 @@
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import { getConfig } from "../config/loader.js";
+import { getConversationHostAccess as loadConversationHostAccess } from "../memory/conversation-crud.js";
+import { isSideEffectTool } from "../tools/side-effects.js";
+import type { ToolContext } from "../tools/types.js";
+import type { AllowlistOption, ScopeOption, UserDecision } from "./types.js";
+import { isHostTool } from "./workspace-policy.js";
+
+export type V2ConsentDisposition =
+  | "legacy"
+  | "auto_allow"
+  | "prompt_host_access";
+
+type PromptLike = {
+  toolName: string;
+  allowlistOptions?: readonly AllowlistOption[];
+  scopeOptions?: readonly ScopeOption[];
+  persistentDecisionsAllowed?: boolean;
+  temporaryOptionsAvailable?: readonly ("allow_10m" | "allow_conversation")[];
+};
+
+export const CONVERSATION_HOST_ACCESS_PROMPT = Object.freeze({
+  allowlistOptions: [] as AllowlistOption[],
+  scopeOptions: [] as ScopeOption[],
+  persistentDecisionsAllowed: false as const,
+  temporaryOptionsAvailable: undefined as
+    | Array<"allow_10m" | "allow_conversation">
+    | undefined,
+});
+
+export function isPermissionControlsV2Enabled(): boolean {
+  return isAssistantFeatureFlagEnabled("permission-controls-v2", getConfig());
+}
+
+export function isConversationHostAccessEnabled(
+  conversationId: string,
+): boolean {
+  return loadConversationHostAccess(conversationId);
+}
+
+export function evaluateV2ConsentDisposition(
+  toolName: string,
+  input: Record<string, unknown>,
+  context: ToolContext,
+): V2ConsentDisposition {
+  if (!isPermissionControlsV2Enabled()) {
+    return "legacy";
+  }
+
+  if (context.requireFreshApproval) {
+    return "legacy";
+  }
+
+  if (context.forcePromptSideEffects && isSideEffectTool(toolName, input)) {
+    return "legacy";
+  }
+
+  if (!isHostTool(toolName)) {
+    return "auto_allow";
+  }
+
+  return loadConversationHostAccess(context.conversationId)
+    ? "auto_allow"
+    : "prompt_host_access";
+}
+
+export function isConversationHostAccessEnablePrompt(
+  details: PromptLike | undefined,
+): boolean {
+  if (!details) {
+    return false;
+  }
+
+  return (
+    isHostTool(details.toolName) &&
+    (details.allowlistOptions?.length ?? 0) === 0 &&
+    (details.scopeOptions?.length ?? 0) === 0 &&
+    details.persistentDecisionsAllowed === false &&
+    (details.temporaryOptionsAvailable?.length ?? 0) === 0
+  );
+}
+
+export function isConversationHostAccessDecision(
+  decision: UserDecision,
+): decision is "allow" | "deny" {
+  return decision === "allow" || decision === "deny";
+}

package/src/permissions/workspace-policy.ts

@@ -65,6 +65,9 @@ const NETWORK_TOOLS = new Set([
   "browser_hover",
   "browser_screenshot",
   "browser_close",
+  "browser_attach",
+  "browser_detach",
+  "browser_status",
   "network_request",
 ]);
 

package/src/platform/client.test.ts

@@ -23,6 +23,16 @@ mock.module("../config/env.js", () => ({
   getPlatformAssistantId: () => mockAssistantId,
 }));
 
+// Stub the credential-store fallback so tests stay hermetic and do not
+// read real values from the host credential backend.
+mock.module("../security/secure-keys.js", () => ({
+  getSecureKeyAsync: async () => null,
+}));
+
+mock.module("../security/credential-key.js", () => ({
+  credentialKey: (namespace: string, key: string) => `${namespace}:${key}`,
+}));
+
 // ---------------------------------------------------------------------------
 // Import under test (after mocks)
 // ---------------------------------------------------------------------------

package/src/platform/sync-identity.ts

@@ -0,0 +1,129 @@
+/**
+ * Sync assistant identity fields to the platform Assistant record.
+ *
+ * When IDENTITY.md changes on disk the daemon broadcasts an
+ * `identity_changed` event to connected clients.  This module hooks into
+ * that same change signal and PATCHes the platform `Assistant` record so
+ * the name (and, in future, other fields) stays in sync.
+ *
+ * Requests are serialized so that rapid name changes (A → B) never race:
+ * only the most recently requested name is sent, and a stale in-flight
+ * response cannot overwrite a newer value.
+ *
+ * The sync is best-effort and fire-and-forget — network failures are
+ * logged but never surface to callers.
+ */
+
+import { getLogger } from "../util/logger.js";
+import { VellumPlatformClient } from "./client.js";
+
+const log = getLogger("sync-identity");
+
+/** Track the last successfully synced name (used inside doSync to skip redundant PATCHes). */
+let lastSyncedName: string | null = null;
+
+/** Track the last requested name (used for dedup at enqueue time). */
+let lastRequestedName: string | null = null;
+
+/**
+ * Monotonically increasing sequence number.  Each call to
+ * `syncIdentityNameToPlatform` bumps this; after a PATCH completes we
+ * only update `lastSyncedName` when `seq` still matches, guaranteeing
+ * the newest name always wins.
+ */
+let seq = 0;
+
+/** Chain promise that serializes in-flight PATCH requests. */
+let pending: Promise<void> = Promise.resolve();
+
+/**
+ * Push the current assistant name to the platform `Assistant` record.
+ *
+ * No-op when:
+ * - The platform client cannot be created (not platform-hosted / missing creds).
+ * - No assistant ID is configured.
+ * - The name is empty or unchanged since the last request.
+ */
+export function syncIdentityNameToPlatform(name: string): void {
+  if (!name || name === lastRequestedName) return;
+
+  lastRequestedName = name;
+
+  const mySeq = ++seq;
+
+  pending = pending
+    .then(() => doSync(name, mySeq))
+    .catch(() => {
+      // swallowed — doSync already logs internally
+    });
+}
+
+async function doSync(name: string, requestSeq: number): Promise<void> {
+  try {
+    // A newer call has already been enqueued — skip this stale request.
+    if (requestSeq !== seq) return;
+
+    // Re-check after awaiting the previous request in the chain.
+    if (name === lastSyncedName) return;
+
+    const client = await VellumPlatformClient.create();
+    if (!client) {
+      clearRequestedIfLatest(requestSeq);
+      return;
+    }
+
+    const assistantId = client.platformAssistantId;
+    if (!assistantId) {
+      clearRequestedIfLatest(requestSeq);
+      return;
+    }
+
+    const resp = await client.fetch(
+      `/v1/assistants/${encodeURIComponent(assistantId)}/`,
+      {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name }),
+        signal: AbortSignal.timeout(15_000),
+      },
+    );
+
+    if (resp.ok) {
+      // Only update cache if no newer request has been enqueued since we
+      // started this PATCH — prevents a slow response from overwriting a
+      // fresher value.
+      if (requestSeq === seq) {
+        lastSyncedName = name;
+      }
+      log.info({ name, assistantId }, "Synced assistant name to platform");
+    } else {
+      clearRequestedIfLatest(requestSeq);
+      const text = await resp.text();
+      log.warn(
+        { status: resp.status, body: text, assistantId },
+        "Failed to sync assistant name to platform",
+      );
+    }
+  } catch (err) {
+    clearRequestedIfLatest(requestSeq);
+    log.warn({ err }, "Error syncing assistant name to platform");
+  }
+}
+
+/**
+ * Reset `lastRequestedName` when the latest request failed, so that the
+ * next call with the same name is allowed through instead of being deduped.
+ */
+function clearRequestedIfLatest(requestSeq: number): void {
+  if (requestSeq === seq) {
+    lastRequestedName = lastSyncedName;
+  }
+}
+
+/** Reset cached state (for testing). */
+export function _resetSyncState(): void {
+  lastSyncedName = null;
+  lastRequestedName = null;
+  seq = 0;
+  pending = Promise.resolve();
+}

package/src/prompts/persona-resolver.ts

@@ -1,5 +1,10 @@
-import { existsSync, readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
 
 import {
   findContactByChannelExternalId,
@@ -16,6 +21,28 @@ import { stripCommentLines } from "../util/strip-comment-lines.js";
 
 const log = getLogger("persona-resolver");
 
+// ── Guardian persona template ─────────────────────────────────────
+//
+// Scaffold written to `users/<slug>.md` when a guardian is resolved
+// but no per-user persona file yet exists. Kept in sync with the
+// legacy workspace USER.md template so that upgrading users preserve
+// the same editable shape. Exported so consumers can detect the
+// unmodified scaffold (e.g. heartbeat's `isShallowProfile`).
+export const GUARDIAN_PERSONA_TEMPLATE = `_ Lines starting with _ are comments - they won't appear in the system prompt
+
+# User Profile
+
+Store details about your user here. Edit freely - build this over time as you learn about them. Don't be pushy about seeking details, but when you learn something, write it down. More context makes you more useful.
+
+- Preferred name/reference:
+- Pronouns:
+- Locale:
+- Work role:
+- Goals:
+- Hobbies/fun:
+- Daily tools:
+`;
+
 // ── Types ──────────────────────────────────────────────────────────
 
 export interface PersonaContext {
@@ -98,6 +125,22 @@ function resolveUserFilename(
   return null;
 }
 
+/**
+ * Resolve the absolute on-disk path to the guardian's per-user persona
+ * file (e.g. `<workspace>/users/sidd.md`). Returns `null` when no
+ * guardian is resolvable (no guardian contact, or its `userFile` is
+ * unusable / fails basename validation).
+ *
+ * This does not check whether the file exists — it only resolves the
+ * path. Callers use it alongside `ensureGuardianPersonaFile` to open
+ * or scaffold the file.
+ */
+export function resolveGuardianPersonaPath(): string | null {
+  const filename = resolveUserFilename(undefined);
+  if (!filename) return null;
+  return join(getWorkspaceDir(), "users", filename);
+}
+
 /**
  * Resolve a short slug identifying the current user, derived from
  * their contact's userFile. Used to scope per-user workspace directories
@@ -192,3 +235,84 @@ export function resolvePersonaContext(
 export function resolveGuardianPersona(): string | null {
   return resolveUserPersona(undefined);
 }
+
+/**
+ * Resolve the guardian's user persona strictly from their own
+ * `users/<slug>.md` file, with NO fallback to `users/default.md`.
+ *
+ * Returns `null` when no guardian contact is resolvable, the
+ * guardian's userFile is unset, or the file is missing / empty.
+ *
+ * Used by callers that derive guardian-specific attributes (name,
+ * pronouns) where `default.md` content would incorrectly override an
+ * intentional caller-supplied fallback such as `Contact.displayName`.
+ * System-prompt callers that want the default.md fallback should
+ * continue to use `resolveGuardianPersona`.
+ */
+export function resolveGuardianPersonaStrict(): string | null {
+  const filename = resolveUserFilename(undefined);
+  if (!filename) return null;
+  const filePath = join(getWorkspaceDir(), "users", filename);
+  if (!existsSync(filePath)) return null;
+  return readPersonaFile(filePath);
+}
+
+/**
+ * Write the guardian persona template scaffold to `users/<userFile>`
+ * when the file does not yet exist. No-op when the file already
+ * exists (safe against clobbering user edits).
+ *
+ * @param userFile - A filename (not a bare slug), matching the shape
+ *   of `Contact.userFile` — a basename with a `.md` suffix
+ *   (e.g. `"sidd.md"`). The path traversal guard rejects values that
+ *   are not a clean basename.
+ *
+ * Creates the parent `users/` directory if missing.
+ */
+export function ensureGuardianPersonaFile(userFile: string): void {
+  if (basename(userFile) !== userFile || userFile === ".." || userFile === ".") {
+    log.warn(
+      { userFile },
+      "Guardian persona userFile contains path traversal; refusing to write",
+    );
+    return;
+  }
+
+  const filePath = join(getWorkspaceDir(), "users", userFile);
+  if (existsSync(filePath)) return;
+
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, GUARDIAN_PERSONA_TEMPLATE, "utf-8");
+  log.debug({ path: filePath }, "Wrote guardian persona scaffold");
+}
+
+/**
+ * Return `true` when the persona file at `filePath` has been edited by
+ * the user (its stripped content differs from the bare scaffold
+ * template). Returns `false` when the file is missing, unreadable,
+ * empty after stripping, or byte-identical to the template after
+ * stripping comment lines.
+ *
+ * Used by the vbundle importer to decide whether a legacy
+ * `prompts/USER.md` entry may safely overwrite `users/<slug>.md`.
+ */
+export function isGuardianPersonaCustomized(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    log.warn(
+      { err, path: filePath },
+      "Failed to read persona file while checking customization",
+    );
+    return false;
+  }
+
+  const stripped = stripCommentLines(content);
+  if (stripped.length === 0) return false;
+
+  const templateStripped = stripCommentLines(GUARDIAN_PERSONA_TEMPLATE);
+  return stripped !== templateStripped;
+}