@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/telemetry/usage-telemetry-reporter.ts

@@ -4,16 +4,14 @@
  * Periodically flushes LLM usage events and turn events (user messages) from
  * the local SQLite database and POSTs them to the platform telemetry endpoint.
  *
- * Two auth modes:
- * - Authenticated: Api-Key header via managed proxy context
- * - Anonymous: unauthenticated POST (telemetry endpoints are public)
+ * Authenticated-only: events are sent via the managed proxy context
+ * (Api-Key header). When no platform credentials are available, or when
+ * platform features are disabled (VELLUM_DISABLE_PLATFORM in local mode), the
+ * flush is skipped and retried next cycle.
  */
 
-import {
-  getPlatformBaseUrl,
-  getPlatformOrganizationId,
-  getPlatformUserId,
-} from "../config/env.js";
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import { getPlatformOrganizationId, getPlatformUserId } from "../config/env.js";
 import { getConfig } from "../config/loader.js";
 import { queryUnreportedAuthFallbackEvents } from "../memory/auth-fallback-events-store.js";
 import {
@@ -26,7 +24,17 @@ import { queryUnreportedOnboardingEvents } from "../memory/onboarding-events-sto
 import { queryUnreportedSkillLoadedEvents } from "../memory/skill-loaded-events-store.js";
 import { queryUnreportedToolExecutedEvents } from "../memory/tool-executed-events-store.js";
 import { queryUnreportedTurnEvents } from "../memory/turn-events-store.js";
+import {
+  assembleBoundedTurnTrace,
+  isTurnSettled,
+} from "../memory/turn-trace-store.js";
 import { VellumPlatformClient } from "../platform/client.js";
+import {
+  getCachedShareAnalytics,
+  getCachedShareDiagnostics,
+  getCachedShareDiagnosticsVersion,
+} from "../platform/consent-cache.js";
+import { arePlatformFeaturesEnabled } from "../platform/feature-gate.js";
 import type { UsageAttributionProfileSource } from "../usage/types.js";
 import { getDeviceId } from "../util/device-id.js";
 import { getLogger } from "../util/logger.js";
@@ -35,6 +43,7 @@ import {
   type ActivationStepName,
   buildActivationDaemonEventId,
 } from "./activation-funnel.js";
+import { isDiagnosticsConsentVersionEligible } from "./trace-collection-policy.js";
 import type { TelemetryEvent, TurnTelemetryClientInfo } from "./types.js";
 
 const log = getLogger("usage-telemetry");
@@ -128,7 +137,7 @@ export class UsageTelemetryReporter {
     // reporter shipping its rows: an absent watermark means no flush (opted
     // in or out) has ever advanced it, so rows recorded before this build —
     // including any opted-out period under older builds that gated the
-    // reporter on collectUsageData — would otherwise ship retroactively.
+    // reporter on the usage-data opt-out — would otherwise ship retroactively.
     // Initialize an absent watermark to "now" at construction. Construction
     // happens during daemon startup before any tool runs, so no legitimate
     // row falls behind the watermark — initializing at first FLUSH instead
@@ -137,8 +146,8 @@ export class UsageTelemetryReporter {
     // absent and re-initialize later. An EXISTING watermark is never touched:
     // opted-out sessions keep it advancing via the opt-out flush branch, and
     // overwriting it here would drop a legitimate unshipped backlog.
-    // `skill_loaded` needs no init: recording is gated on collectUsageData,
-    // so opt-out rows never exist and its standard 0 default is safe.
+    // `skill_loaded` needs no init: recording is gated on share_analytics
+    // consent, so opt-out rows never exist and its standard 0 default is safe.
     //
     // Best-effort: DB init failures are tolerated at daemon startup (degraded
     // mode), so this must never throw out of the constructor — matching
@@ -162,7 +171,8 @@ export class UsageTelemetryReporter {
     // Delay the first flush to allow the credential infrastructure (CES
     // handshake) to complete. Without this delay, VellumPlatformClient.create()
     // returns null because the credential backend hasn't resolved yet, causing
-    // telemetry to fall back to anonymous mode permanently.
+    // the initial flush to be skipped (we send authenticated-only); the
+    // delay lets credentials resolve so the first flush can actually ship.
     this.initialFlushTimer = setTimeout(() => {
       this.initialFlushTimer = null;
       this.flush().catch((err) => {
@@ -205,22 +215,32 @@ export class UsageTelemetryReporter {
     try {
       if (batchCount >= MAX_CONSECUTIVE_BATCHES) return;
 
-      // Respect opt-out: if the user has disabled usage data collection, skip
-      // the flush and advance watermarks so events recorded during the
-      // opt-out window are never sent retroactively. The daemon runs the
-      // reporter even when opted out specifically so this branch keeps
-      // executing — every cycle plus the final flush in stop() — which is
-      // what lets a later opt-in (runtime or via restart) resume from a
-      // watermark that already covers the opt-out window. One caveat: a
-      // RUNTIME false→true flip can still ship up to one flush interval
-      // (≤5 min) of pre-toggle rows recorded since the last opted-out flush;
+      // Skip when platform features are disabled (VELLUM_DISABLE_PLATFORM in
+      // local mode; the flag is ignored when IS_PLATFORM is set, matching
+      // VellumPlatformClient.create()). Watermarks are NOT advanced here: this
+      // is a deployment/local-mode toggle, not a privacy opt-out, so the unsent
+      // backlog ships once the flag is cleared.
+      if (!arePlatformFeaturesEnabled()) {
+        return;
+      }
+
+      // Respect opt-out: if the platform owner has not granted
+      // `share_analytics` consent, skip the flush and advance watermarks so
+      // events recorded during the opt-out window are never sent
+      // retroactively. The daemon runs the reporter even when opted out
+      // specifically so this branch keeps executing — every cycle plus the
+      // final flush in stop() — which is what lets a later opt-in (runtime or
+      // via restart) resume from a watermark that already covers the opt-out
+      // window. One caveat: a RUNTIME false→true flip can still ship up to one
+      // flush interval (≤5 min) of pre-toggle rows recorded since the last
+      // opted-out flush;
       // the restart path is fully covered by the final flush in stop(). The
       // caveat applies to the always-on tables without a write-time opt-out
       // gate (llm_usage, turn events) and to tool_invocations rows recorded
       // under builds predating the audit listener's write-time gate — new
       // opted-out tool_invocations rows persist NULL telemetry columns and
       // are unreportable by construction regardless of watermark timing.
-      if (!getConfig().collectUsageData) {
+      if (!getCachedShareAnalytics()) {
         // Advance the timestamp watermarks and pin the ID watermarks to a
         // sentinel that sorts above any real UUID. The sentinel (rather than
         // "") keeps the compound-cursor branch active — a falsy ID would
@@ -332,9 +352,68 @@ export class UsageTelemetryReporter {
         BATCH_SIZE,
       );
 
+      // Trace completeness barrier (trace-eligible owners only).
+      //
+      // When trace collection is on, a turn's trace must only be sent once that
+      // turn is COMPLETE — otherwise a flush that races an in-progress reply
+      // would capture a partial transcript and the watermark would advance past
+      // the turn, leaving it permanently partial. So we report only the leading
+      // run of complete turns and STOP at the first incomplete (in-flight) one:
+      // the turn watermark is a single monotonic `(createdAt, id)` cursor, so a
+      // later complete turn cannot be reported past an earlier deferred one
+      // without skipping it. The deferred turn (and everything after it) is
+      // picked up on a later flush once its response settles.
+      //
+      // When trace collection is OFF, no turn is deferred and reporting timing
+      // is unchanged for everyone else — `turn_raw` behavior is untouched.
+      //
+      // Trace eligibility is composed daemon-side to mirror the platform's
+      // authoritative owner-based ingest gate, so traces for ineligible owners
+      // never leave the device. Three parts, fail-closed (all must be true):
+      //   1. the `trace-collection` LaunchDarkly flag (delivered via the
+      //      assistant-tagged flag sync, already evaluated server-side for this
+      //      assistant's owner),
+      //   2. the owner's cached `share_diagnostics` consent, and
+      //   3. the owner's cached `share_diagnostics_accepted_version` being at or
+      //      past the disclosing version — the platform applies the identical
+      //      check, so an old consent never yields a trace here or there.
+      const traceEligible =
+        isAssistantFeatureFlagEnabled("trace-collection", getConfig()) &&
+        getCachedShareDiagnostics() &&
+        isDiagnosticsConsentVersionEligible(getCachedShareDiagnosticsVersion());
+      let reportableTurnEvents = turnEvents;
+      if (traceEligible && turnEvents.length > 0) {
+        let barrier = turnEvents.length;
+        for (let i = 0; i < turnEvents.length; i++) {
+          const t = turnEvents[i];
+          if (
+            !isTurnSettled({
+              conversationId: t.conversationId,
+              userMessageId: t.id,
+              userMessageCreatedAt: t.createdAt,
+            })
+          ) {
+            barrier = i;
+            break;
+          }
+        }
+        if (barrier < turnEvents.length) {
+          reportableTurnEvents = turnEvents.slice(0, barrier);
+          log.debug(
+            {
+              deferredTurnId: turnEvents[barrier].id,
+              deferredConversationId: turnEvents[barrier].conversationId,
+              reportedTurns: barrier,
+              deferredTurns: turnEvents.length - barrier,
+            },
+            "Deferring in-progress turn(s) from telemetry until complete",
+          );
+        }
+      }
+
       if (
         events.length === 0 &&
-        turnEvents.length === 0 &&
+        reportableTurnEvents.length === 0 &&
         lifecycleEvents.length === 0 &&
         onboardingEvents.length === 0 &&
         authFallbackEvents.length === 0 &&
@@ -343,14 +422,21 @@ export class UsageTelemetryReporter {
       )
         return;
 
-      // Resolve auth context — authenticated path uses client, anonymous path
-      // sends unauthenticated (telemetry endpoints are public).
+      // Resolve auth context. We send authenticated-only: if no platform
+      // credentials are available yet, skip without advancing watermarks so the
+      // backlog ships on a later cycle once credentials resolve.
       const client = await VellumPlatformClient.create();
+      if (!client) {
+        log.debug(
+          { pendingEventCount: events.length + turnEvents.length },
+          "Telemetry flush: no platform credentials — skipping, will retry next cycle",
+        );
+        return;
+      }
       log.debug(
         {
-          authenticated: !!client,
           usageCount: events.length,
-          turnCount: turnEvents.length,
+          turnCount: reportableTurnEvents.length,
           lifecycleCount: lifecycleEvents.length,
           onboardingCount: onboardingEvents.length,
           authFallbackCount: authFallbackEvents.length,
@@ -396,7 +482,23 @@ export class UsageTelemetryReporter {
             assistant_version: e.assistantVersion ?? APP_VERSION,
           }),
         ),
-        ...turnEvents.map((e): TelemetryEvent => {
+        ...reportableTurnEvents.map((e): TelemetryEvent => {
+          // Per-turn trace collection gate. `traceEligible` (computed above)
+          // requires the `trace-collection` flag AND the owner's cached
+          // `share_diagnostics` consent AND an eligible accepted consent
+          // version. Fail-closed: when any is off the trace is omitted and the
+          // trace-free turn row flushes as before. The
+          // `share_analytics` gate above already passed, so this is an
+          // additional, independent gate specific to trace PII. Every turn
+          // reaching here is settled (the completeness barrier dropped any
+          // in-flight turns), so the trace is never a partial mid-turn snapshot.
+          const trace = traceEligible
+            ? assembleBoundedTurnTrace({
+                conversationId: e.conversationId,
+                userMessageId: e.id,
+                userMessageCreatedAt: e.createdAt,
+              })
+            : null;
           // `messages.metadata.client` is a nested JSON object extracted
           // via `json_extract`; sqlite returns it as a text representation.
           // Parse defensively — a corrupted blob in the JSON column should
@@ -431,6 +533,11 @@ export class UsageTelemetryReporter {
             interface_id: e.interfaceId,
             channel_id: e.channelId,
             client,
+            // Only attach `trace` when consent is on AND a bounded trace was
+            // assembled. Omitting the key entirely when there's no trace keeps
+            // the wire shape byte-identical to pre-trace turn events for the
+            // common (no-consent) path.
+            ...(trace ? { trace } : {}),
             // Turn events derive from `messages` + `conversations`
             // rather than a dedicated table. Adding `assistant_version`
             // to `messages` is a separate (larger) migration; until
@@ -588,18 +695,12 @@ export class UsageTelemetryReporter {
         body: JSON.stringify(payload),
       };
 
-      let resp: Response;
-      if (client) {
-        resp = await client.fetch(TELEMETRY_PATH, fetchInit);
-      } else {
-        const url = `${getPlatformBaseUrl()}${TELEMETRY_PATH}`;
-        resp = await fetch(url, fetchInit);
-      }
+      const resp = await client.fetch(TELEMETRY_PATH, fetchInit);
 
       if (!resp.ok) {
         const body = await resp.text();
         log.warn(
-          { status: resp.status, authenticated: !!client, body },
+          { status: resp.status, body },
           "Usage telemetry POST failed — will retry next cycle",
         );
         return;
@@ -616,9 +717,11 @@ export class UsageTelemetryReporter {
         setMemoryCheckpoint(CHECKPOINT_KEY_WATERMARK_ID, lastEvent.id);
       }
 
-      // Advance turn watermark (compound cursor)
-      if (turnEvents.length > 0) {
-        const lastTurn = turnEvents[turnEvents.length - 1];
+      // Advance turn watermark (compound cursor) — only to the last REPORTED
+      // turn. Deferred (in-flight) turns sit beyond this cursor and are
+      // re-evaluated on a later flush, so the watermark never skips them.
+      if (reportableTurnEvents.length > 0) {
+        const lastTurn = reportableTurnEvents[reportableTurnEvents.length - 1];
         setMemoryCheckpoint(
           CHECKPOINT_KEY_TURN_WATERMARK,
           String(lastTurn.createdAt),
@@ -693,10 +796,14 @@ export class UsageTelemetryReporter {
         );
       }
 
-      // If we got a full batch of any type, there may be more — recurse
+      // If we got a full batch of any type, there may be more — recurse.
+      // Turns use the REPORTED count: when the completeness barrier truncates
+      // the batch, the deferred turns must wait for a later flush (by which
+      // point they've settled) rather than being re-queried and re-deferred in
+      // a tight recursion.
       if (
         events.length === BATCH_SIZE ||
-        turnEvents.length === BATCH_SIZE ||
+        reportableTurnEvents.length === BATCH_SIZE ||
         lifecycleEvents.length === BATCH_SIZE ||
         onboardingEvents.length === BATCH_SIZE ||
         authFallbackEvents.length === BATCH_SIZE ||

package/src/tools/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## New Non-Skill Tools Are Strongly Discouraged
 
-**Prefer skills over new non-skill tool registrations.** Non-skill tools require approval from Team Jarvis.
+**Prefer skills over new non-skill tool registrations.** Non-skill tools require approval from the core team.
 
 Skills are the preferred approach for adding new capabilities — they are progressively disclosed into context, more portable, and can be iterated on independently. New non-skill tool registrations (`class ... implements Tool` + `registerTool()`) carry additional costs:
 
@@ -48,7 +48,7 @@ See [`assistant/docs/credential-execution-service.md`](../../docs/credential-exe
 
 ## If You Have Approval
 
-If Team Jarvis has approved your new tool:
+If the core team has approved your new tool:
 
 1. The pre-commit hook will block your commit by default
 2. Use `git commit --no-verify` to bypass the hook
@@ -56,4 +56,4 @@ If Team Jarvis has approved your new tool:
 
 ## Questions?
 
-Contact Team Jarvis before shipping a new tool.
+Contact the core team before shipping a new tool.

package/src/tools/browser/__tests__/browser-execution-acquire.test.ts

@@ -54,6 +54,9 @@ const setPreferredBackendKindMock = mock(
   (_conversationId: string, _kind: CdpClientKind) => {},
 );
 const clearPreferredBackendKindMock = mock((_conversationId: string) => {});
+const waitForExtensionClientMock = mock(
+  async (_actor?: string, _targetClientId?: string) => true,
+);
 
 // ---------------------------------------------------------------------------
 // Module mocks (must be declared before dynamic import)
@@ -98,6 +101,7 @@ mock.module("../../../daemon/host-browser-proxy.js", () => ({
       return {
         isAvailable: () => false,
         hasExtensionClient: () => false,
+        waitForExtensionClient: waitForExtensionClientMock,
         request: () => Promise.reject(new Error("no extension")),
       };
     },
@@ -141,9 +145,36 @@ describe("acquireCdpClientWithMode: target_client_id overrides sticky backend mo
     getCdpClientMock.mockClear();
     setPreferredBackendKindMock.mockClear();
     clearPreferredBackendKindMock.mockClear();
+    waitForExtensionClientMock.mockClear();
     stickyKind = null;
   });
 
+  test("extension-pinned acquisition awaits the reconnect grace window", async () => {
+    await executeBrowserAttach(
+      { target_client_id: "host-client-grace" },
+      makeContext("grace-window"),
+    );
+
+    // The grace wait runs before backend selection so a flapping extension
+    // SSE reconnect doesn't hard-fail the dispatch, and it targets the exact
+    // requested client.
+    expect(waitForExtensionClientMock).toHaveBeenCalledTimes(1);
+    expect(waitForExtensionClientMock).toHaveBeenCalledWith(
+      undefined,
+      "host-client-grace",
+    );
+    expect(getCdpClientCalls[0].mode).toBe("extension");
+  });
+
+  test("non-extension (sticky local, no target) does not wait on the extension", async () => {
+    stickyKind = "local";
+
+    await executeBrowserAttach({}, makeContext("no-grace-for-local"));
+
+    expect(waitForExtensionClientMock).not.toHaveBeenCalled();
+    expect(getCdpClientCalls[0].mode).toBe("local");
+  });
+
   test("sticky local + target_client_id → getCdpClient receives mode:extension, not local", async () => {
     // Simulate a prior turn that pinned the conversation to the local backend.
     stickyKind = "local";

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

@@ -375,16 +375,17 @@ function isRestrictedChromePageProbeError(error: CdpError): boolean {
  * The returned client is wrapped so its first successful `send()`
  * writes the resolved kind back to the conversation memo.
  */
-function acquireCdpClientWithMode(
+async function acquireCdpClientWithMode(
   input: Record<string, unknown>,
   context: ToolContext,
-):
+): Promise<
   | {
       cdp: ReturnType<typeof getCdpClient>;
       browserMode: BrowserMode;
       errorResult?: never;
     }
-  | { cdp?: never; browserMode?: never; errorResult: ToolExecutionResult } {
+  | { cdp?: never; browserMode?: never; errorResult: ToolExecutionResult }
+> {
   const modeResult = parseBrowserMode(input);
   if (!modeResult.ok) {
     return {
@@ -412,6 +413,16 @@ function acquireCdpClientWithMode(
         ? rememberedKind
         : browserMode;
 
+  // Extension-pinned dispatch (explicit `--browser-mode extension` or a
+  // `target_client_id`) hard-fails when the extension is momentarily
+  // absent. Absorb a brief reconnect blip before selecting the backend.
+  if (effectiveMode === "extension") {
+    await HostBrowserProxy.instance.waitForExtensionClient(
+      context.sourceActorPrincipalId,
+      targetClientId,
+    );
+  }
+
   try {
     const raw = getCdpClient(context, { mode: effectiveMode, targetClientId });
     const cdp = wrapWithKindMemo(raw, context.conversationId);
@@ -655,7 +666,7 @@ export async function executeBrowserNavigate(
   }
 
   // URL validation passed — acquire the CDP client.
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const { cdp, browserMode } = acquired;
 
@@ -1093,7 +1104,7 @@ export async function executeBrowserNavigate(
           }
         } else {
           // Login / 2FA / OAuth - the agent should handle these itself
-          // using browser operations + credential_store. Don't hand off.
+          // using browser operations + stored credentials. Don't hand off.
           lines.push("");
           lines.push(formatAuthChallenge(challenge));
           lines.push("");
@@ -1157,7 +1168,7 @@ export async function executeBrowserSnapshot(
   _input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const acquired = acquireCdpClientWithMode(_input, context);
+  const acquired = await acquireCdpClientWithMode(_input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const { cdp, browserMode } = acquired;
 
@@ -1209,7 +1220,7 @@ export async function executeBrowserScreenshot(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const { cdp, browserMode } = acquired;
   const fullPage = input.full_page === true;
@@ -1266,7 +1277,7 @@ export async function executeBrowserAttach(
   _input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const acquired = acquireCdpClientWithMode(_input, context);
+  const acquired = await acquireCdpClientWithMode(_input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1319,7 +1330,7 @@ export async function executeBrowserDetach(
   _input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const acquired = acquireCdpClientWithMode(_input, context);
+  const acquired = await acquireCdpClientWithMode(_input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1369,7 +1380,7 @@ export async function executeBrowserClose(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1440,7 +1451,7 @@ export async function executeBrowserClick(
   const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1561,7 +1572,7 @@ export async function executeBrowserType(
       ? `element_id "${resolved!.eid}"`
       : resolved!.selector;
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1638,7 +1649,7 @@ export async function executeBrowserPressKey(
         : resolved!.selector;
   }
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1715,7 +1726,7 @@ export async function executeBrowserScroll(
       break;
   }
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1778,7 +1789,7 @@ export async function executeBrowserSelectOption(
       ? `element_id "${resolved!.eid}"`
       : resolved!.selector;
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1894,7 +1905,7 @@ export async function executeBrowserHover(
   const { resolved, error } = resolveElement(context.conversationId, input);
   if (error) return { content: error, isError: true };
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -1988,7 +1999,7 @@ export async function executeBrowserWaitFor(
     return { content: `Waited ${waitMs}ms.`, isError: false };
   }
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -2037,7 +2048,7 @@ export async function executeBrowserExtract(
 ): Promise<ToolExecutionResult> {
   const includeLinks = input.include_links === true;
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {
@@ -2120,7 +2131,7 @@ export async function executeBrowserFillCredential(
       ? `element_id "${resolved!.eid}"`
       : resolved!.selector;
 
-  const acquired = acquireCdpClientWithMode(input, context);
+  const acquired = await acquireCdpClientWithMode(input, context);
   if (acquired.errorResult) return acquired.errorResult;
   const cdp = acquired.cdp;
   try {

package/src/tools/document/document-tool.ts

@@ -13,12 +13,11 @@ import {
   searchDocumentsByTitle,
   updateDocumentContent,
 } from "../../documents/document-store.js";
+import { canActOnPrivilegedDocuments } from "../../runtime/effective-capabilities.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
 function isPrivilegedDocumentActor(context: ToolContext): boolean {
-  return (
-    context.trustClass === "guardian" || context.executionChannel === "vellum"
-  );
+  return canActOnPrivilegedDocuments(context);
 }
 
 export function documentNotFound(surfaceId: string): ToolExecutionResult {

package/src/tools/executor.ts

@@ -5,7 +5,7 @@ import { bridgeCesApproval } from "../credential-execution/approval-bridge.js";
 import { isCesShellLockdownEnabled } from "../credential-execution/feature-gates.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
 import { RiskLevel } from "../permissions/types.js";
-import { isUntrustedTrustClass } from "../runtime/actor-trust-resolver.js";
+import { isUntrustedShellLockdownActive } from "../runtime/effective-capabilities.js";
 import { redactSensitiveFields } from "../security/redaction.js";
 import { getCesClient } from "../security/secure-keys.js";
 import { TokenExpiredError } from "../security/token-manager.js";
@@ -128,8 +128,10 @@ export class ToolExecutor {
       // skip this assignment entirely - defeating the lockdown.
       if (
         name === "host_bash" &&
-        isCesShellLockdownEnabled(getConfig()) &&
-        isUntrustedTrustClass(context.trustClass)
+        isUntrustedShellLockdownActive({
+          trustClass: context.trustClass,
+          lockdownEnabled: isCesShellLockdownEnabled(getConfig()),
+        })
       ) {
         context.forcePromptSideEffects = true;
       }

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

@@ -23,9 +23,9 @@ import { getConfig } from "../../config/loader.js";
 import { isCesShellLockdownEnabled } from "../../credential-execution/feature-gates.js";
 import { HostBashProxy } from "../../daemon/host-bash-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
-import { isUntrustedTrustClass } from "../../runtime/actor-trust-resolver.js";
 import { wakeAgentForOpportunity } from "../../runtime/agent-wake.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+import { isUntrustedShellLockdownActive } from "../../runtime/effective-capabilities.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import { getLogger } from "../../util/logger.js";
 import {
@@ -204,9 +204,10 @@ export const hostShellTool = {
     // NOTE: forcePromptSideEffects is set in executor.ts BEFORE the
     // permission check runs, not here. Setting it here would be too late
     // because execute() is called after permissions have already been evaluated.
-    const hostLockdownActive =
-      isCesShellLockdownEnabled(config) &&
-      isUntrustedTrustClass(context.trustClass);
+    const hostLockdownActive = isUntrustedShellLockdownActive({
+      trustClass: context.trustClass,
+      lockdownEnabled: isCesShellLockdownEnabled(config),
+    });
 
     // Guard: non-host-proxy interfaces need an explicit target when multiple
     // capable clients are connected to avoid ambiguous untargeted broadcasts.

package/src/tools/memory/register.ts

@@ -10,7 +10,7 @@ import {
   graphRememberDefinition,
 } from "../../memory/graph/tools.js";
 import { RiskLevel } from "../../permissions/types.js";
-import { isUntrustedTrustClass } from "../../runtime/actor-trust-resolver.js";
+import { resolveCapabilities } from "../../runtime/capabilities.js";
 import type {
   ToolContext,
   ToolDefinition,
@@ -60,7 +60,7 @@ export const recallTool = {
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
-    if (isUntrustedTrustClass(context.trustClass)) {
+    if (!resolveCapabilities(context.trustClass).canAccessMemory) {
       return {
         content:
           "Recall is only available to the guardian because it can read sensitive local context.",