@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/telemetry/tool-audit.ts

@@ -7,10 +7,12 @@
  *
  *   - `recordToolExecuted` / `recordToolError` / `recordToolDenied` write the
  *     always-on `tool_invocations` audit row (redacting secrets from the
- *     stored input/result), and — for prompted calls — the consent-gated
- *     `permission_decided` lifecycle-telemetry row.
- *   - `recordToolPermissionPrompted` writes the consent-gated
- *     `permission_prompt` lifecycle-telemetry row.
+ *     stored input/result).
+ *   - `recordToolPermissionPrompted` / `recordToolPermissionDecided` write the
+ *     consent-gated `permission_prompt` and `permission_decided`
+ *     lifecycle-telemetry rows. Both are called from the one site that owns an
+ *     interactive prompt (`tools/permission-checker.ts`), so every prompt has
+ *     exactly one decision and the two series reconcile.
  *   - `logToolFailure` emits the operator-facing failure log.
  *
  * The telemetry-only columns (payload sizes + model attribution) are the
@@ -24,8 +26,10 @@
  * are unaffected — `tool_invocations` is a local always-on audit log.
  */
 
-import { isAllowDecision, type UserDecision } from "../permissions/types.js";
-import { recordLifecycleEvent } from "../persistence/lifecycle-events-store.js";
+import {
+  type LifecycleEventAttributes,
+  recordLifecycleEvent,
+} from "../persistence/lifecycle-events-store.js";
 import { getRawShareAnalytics } from "../platform/consent-cache.js";
 import { redactJsonStringLeaves } from "../security/redact-json.js";
 import { redactSensitiveFields } from "../security/redaction.js";
@@ -62,8 +66,6 @@ interface ExecutedAuditEntry {
   durationMs: number;
   /** Model attribution at invocation time; `null` when unavailable. */
   attribution: UsageAttributionSnapshot | null;
-  /** True when this call was interactively approved via a permission prompt. */
-  wasPrompted: boolean;
 }
 
 interface ErrorAuditEntry {
@@ -90,8 +92,6 @@ interface DeniedAuditEntry {
   riskLevel: string;
   matchedTrustRuleId?: string;
   durationMs: number;
-  /** True when the denial followed an interactive permission prompt. */
-  wasPrompted: boolean;
 }
 
 /** Record an audit row for a tool that ran to completion. */
@@ -111,10 +111,6 @@ export function recordToolExecuted(entry: ExecutedAuditEntry): void {
     durationMs: entry.durationMs,
     ...telemetryColumns(entry.attribution, rawInput, entry.resultBytes),
   });
-
-  if (entry.wasPrompted && isAllowDecision(entry.decision as UserDecision)) {
-    recordToolPermissionDecided(entry.toolName, entry.decision);
-  }
 }
 
 /** Record an audit row and operator log for a tool that failed. */
@@ -156,32 +152,89 @@ export function recordToolDenied(entry: DeniedAuditEntry): void {
     // No telemetry columns: the tool never executed, and denied rows are
     // filtered out of the tool_executed projection anyway.
   });
+}
 
-  if (entry.wasPrompted) {
-    recordToolPermissionDecided(entry.toolName, "deny");
-  }
+/**
+ * How an interactive permission prompt ended.
+ *
+ * `allow` / `deny` are answers a human gave. `abandoned` covers every way a
+ * prompt stops without one: it timed out, a new user message superseded it,
+ * the turn was cancelled, or the prompter was disposed (client disconnect /
+ * conversation teardown). The daemon resolves all of those to a deny for the
+ * agent loop, so without this bucket they are indistinguishable from a human
+ * saying no.
+ */
+export type PermissionPromptOutcome = "allow" | "deny" | "abandoned";
+
+/**
+ * Grouping dimensions recorded on both halves of a permission-prompt pair.
+ * The tool and its risk are always known at the prompt site, so they tighten
+ * to required; the rest are the lifecycle attributes as declared. Metadata
+ * only: never a file path, a command string, or any tool input.
+ */
+export interface PermissionPromptTelemetry extends LifecycleEventAttributes {
+  toolName: string;
+  riskLevel: string;
 }
 
-/** Record the consent-gated telemetry row for an interactive permission prompt. */
-export function recordToolPermissionPrompted(toolName: string): void {
-  try {
-    recordLifecycleEvent(`permission_prompt:${toolName}`);
-  } catch (err) {
-    log.warn({ err, toolName }, "Failed to record permission prompt telemetry");
-  }
+/**
+ * Server bounds on the lifecycle `event_name` and `tool_name`. A field over
+ * its bound fails validation, and a failed event is acked and discarded rather
+ * than retried, so both are clamped here. `event_name` has one variable-length
+ * part (the tool name, which can be a long `mcp__server__tool` id) and is much
+ * the tighter of the two, which is why `tool_name` carries the full-length
+ * value consumers join a prompt to its decision on.
+ */
+const LIFECYCLE_EVENT_NAME_LIMIT = 64;
+const LIFECYCLE_TOOL_NAME_LIMIT = 255;
+
+function permissionEventName(
+  prefix: string,
+  toolName: string,
+  suffix: string,
+): string {
+  const budget = LIFECYCLE_EVENT_NAME_LIMIT - prefix.length - suffix.length;
+  return `${prefix}${toolName.slice(0, Math.max(budget, 0))}${suffix}`;
 }
 
-function recordToolPermissionDecided(toolName: string, decision: string): void {
+function recordPermissionLifecycleEvent(
+  eventName: string,
+  entry: PermissionPromptTelemetry,
+  failureMessage: string,
+): void {
   try {
-    recordLifecycleEvent(`permission_decided:${toolName}:${decision}`);
+    recordLifecycleEvent(eventName, {
+      ...entry,
+      toolName: entry.toolName.slice(0, LIFECYCLE_TOOL_NAME_LIMIT),
+    });
   } catch (err) {
-    log.warn(
-      { err, toolName, decision },
-      "Failed to record permission decision telemetry",
-    );
+    log.warn({ err, eventName, toolName: entry.toolName }, failureMessage);
   }
 }
 
+/** Record the consent-gated telemetry row for an interactive permission prompt. */
+export function recordToolPermissionPrompted(
+  entry: PermissionPromptTelemetry,
+): void {
+  recordPermissionLifecycleEvent(
+    permissionEventName("permission_prompt:", entry.toolName, ""),
+    entry,
+    "Failed to record permission prompt telemetry",
+  );
+}
+
+/** Record the consent-gated telemetry row for how that prompt ended. */
+export function recordToolPermissionDecided(
+  entry: PermissionPromptTelemetry,
+  outcome: PermissionPromptOutcome,
+): void {
+  recordPermissionLifecycleEvent(
+    permissionEventName("permission_decided:", entry.toolName, `:${outcome}`),
+    entry,
+    "Failed to record permission decision telemetry",
+  );
+}
+
 /** Operator-facing failure log: warn for expected failures, error otherwise. */
 function logToolFailure(entry: ErrorAuditEntry): void {
   const meta = {

package/src/telemetry/tool-executed-events-store.test.ts

@@ -123,7 +123,6 @@ describe("tool-executed-events-store", () => {
         riskLevel: "low",
         durationMs: 5,
         attribution: null,
-        wasPrompted: false,
       });
 
     recordExecuted("t-opted-in-before");

package/src/telemetry/turn-outcome.ts

@@ -31,6 +31,26 @@ export interface TurnOutcomeExtras {
   batchedInto?: string;
   /** For `"failed"`: stable classified error code (never free-form text). */
   failureCode?: string;
+  /**
+   * For `"failed"`: the classification's authored user-facing message
+   * (`classifyConversationError(...).userMessage`), so downstream failure
+   * reporting (background-job alerts) can render the actionable prose the
+   * chat banner shows instead of reconstructing degraded text from the code.
+   */
+  failureMessage?: string;
+  /** For `"failed"`: the classification's machine-readable category. */
+  failureCategory?: string;
+  /**
+   * For `"failed"`: name of the `provider_connections` row in play when the
+   * failure occurred, when the classifier had it in scope.
+   */
+  failureConnection?: string;
+  /**
+   * For `"failed"`: the resolved profile key the failing call ran under,
+   * when the classifier had it in scope. This is dispatch's own attribution,
+   * so consumers scope failure identity by it instead of re-resolving.
+   */
+  failureProfile?: string;
 }
 
 /**
@@ -49,10 +69,25 @@ export function stampTurnOutcome(
   extras: TurnOutcomeExtras = {},
 ): void {
   try {
+    // The failure* keys are read back by `readTurnFailure` only; the turn
+    // telemetry projection (`queryUnreportedTurnEvents`) extracts none of
+    // them, so nothing here changes the platform wire contract.
     updateMessageMetadata(userMessageId, {
       turnOutcome: outcome,
       ...(extras.batchedInto ? { turnBatchedInto: extras.batchedInto } : {}),
       ...(extras.failureCode ? { turnFailureCode: extras.failureCode } : {}),
+      ...(extras.failureMessage
+        ? { turnFailureMessage: extras.failureMessage }
+        : {}),
+      ...(extras.failureCategory
+        ? { turnFailureCategory: extras.failureCategory }
+        : {}),
+      ...(extras.failureConnection
+        ? { turnFailureConnection: extras.failureConnection }
+        : {}),
+      ...(extras.failureProfile
+        ? { turnFailureProfile: extras.failureProfile }
+        : {}),
     });
   } catch (err) {
     log.warn(
@@ -75,6 +110,14 @@ export function stampTurnOutcome(
 export interface TurnFailure {
   /** Stable classified error code (never free-form text). */
   failureCode?: string;
+  /** The classification's authored user-facing message, when stamped. */
+  userMessage?: string;
+  /** The classification's machine-readable category, when stamped. */
+  errorCategory?: string;
+  /** Connection row in play when the failure occurred, when stamped. */
+  connectionName?: string;
+  /** Resolved profile key the failing call ran under, when stamped. */
+  profileName?: string;
 }
 
 /**
@@ -106,11 +149,39 @@ export function readTurnFailure(userMessageId: string): TurnFailure | null {
   if (typeof parsed !== "object" || parsed === null) {
     return null;
   }
-  const meta = parsed as { turnOutcome?: unknown; turnFailureCode?: unknown };
+  const meta = parsed as {
+    turnOutcome?: unknown;
+    turnFailureCode?: unknown;
+    turnFailureMessage?: unknown;
+    turnFailureCategory?: unknown;
+    turnFailureConnection?: unknown;
+    turnFailureProfile?: unknown;
+  };
   if (meta.turnOutcome !== "failed") {
     return null;
   }
-  return typeof meta.turnFailureCode === "string"
-    ? { failureCode: meta.turnFailureCode }
-    : {};
+  const str = (value: unknown): string | undefined =>
+    typeof value === "string" ? value : undefined;
+  const failure: TurnFailure = {};
+  const failureCode = str(meta.turnFailureCode);
+  if (failureCode !== undefined) {
+    failure.failureCode = failureCode;
+  }
+  const userMessage = str(meta.turnFailureMessage);
+  if (userMessage !== undefined) {
+    failure.userMessage = userMessage;
+  }
+  const errorCategory = str(meta.turnFailureCategory);
+  if (errorCategory !== undefined) {
+    failure.errorCategory = errorCategory;
+  }
+  const connectionName = str(meta.turnFailureConnection);
+  if (connectionName !== undefined) {
+    failure.connectionName = connectionName;
+  }
+  const profileName = str(meta.turnFailureProfile);
+  if (profileName !== undefined) {
+    failure.profileName = profileName;
+  }
+  return failure;
 }

package/src/tools/client-os.ts

@@ -0,0 +1,115 @@
+import {
+  type ClientOs,
+  type HostProxyCapability,
+  type InterfaceId,
+  parseClientOs,
+  supportsHostProxy,
+} from "../channels/types.js";
+import { assistantEventHub } from "../runtime/assistant-event-hub.js";
+
+interface HostClientContext {
+  clientOs?: ClientOs;
+  transportInterface?: InterfaceId;
+  sourceActorPrincipalId?: string;
+}
+
+export function supportsClientOs(
+  supportedClientOs: readonly ClientOs[] | undefined,
+  clientOs: ClientOs | undefined,
+): boolean {
+  return (
+    clientOs === undefined ||
+    supportedClientOs === undefined ||
+    supportedClientOs.includes(clientOs)
+  );
+}
+
+export function getSkillToolHostCapability(
+  toolName: string,
+): HostProxyCapability | undefined {
+  if (toolName.startsWith("computer_use_")) {
+    return "host_cu";
+  }
+  if (toolName.startsWith("app_control_")) {
+    return "host_app_control";
+  }
+  return undefined;
+}
+
+export function getEligibleHostClientOs(
+  capability: HostProxyCapability,
+  context: HostClientContext,
+): Set<ClientOs> {
+  const eligible = new Set<ClientOs>();
+  const sourceClientOs =
+    context.transportInterface === "macos" ||
+    context.transportInterface === "windows"
+      ? context.transportInterface
+      : context.clientOs;
+  if (
+    sourceClientOs !== undefined &&
+    context.transportInterface !== undefined &&
+    supportsHostProxy(context.transportInterface, capability)
+  ) {
+    eligible.add(sourceClientOs);
+  }
+
+  if (context.sourceActorPrincipalId !== undefined) {
+    for (const client of assistantEventHub.listClientsByCapability(
+      capability,
+    )) {
+      if (client.actorPrincipalId !== context.sourceActorPrincipalId) {
+        continue;
+      }
+      const clientOs = parseClientOs(client.interfaceId);
+      if (clientOs !== null) {
+        eligible.add(clientOs);
+      }
+    }
+  }
+  return eligible;
+}
+
+export function supportsClientOsForSkillTool(
+  supportedClientOs: readonly ClientOs[] | undefined,
+  toolName: string,
+  context: HostClientContext,
+): boolean {
+  if (supportedClientOs === undefined) {
+    return true;
+  }
+  const capability = getSkillToolHostCapability(toolName);
+  if (capability === undefined) {
+    return supportsClientOs(supportedClientOs, context.clientOs);
+  }
+  const eligible = getEligibleHostClientOs(capability, context);
+  if (eligible.size === 0) {
+    return supportsClientOs(supportedClientOs, context.clientOs);
+  }
+  for (const clientOs of eligible) {
+    if (supportedClientOs.includes(clientOs)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function resolveInvocationHostClientOs(
+  capability: HostProxyCapability,
+  input: Record<string, unknown>,
+  context: HostClientContext,
+): ClientOs | undefined {
+  const targetClientId =
+    typeof input.target_client_id === "string" && input.target_client_id !== ""
+      ? input.target_client_id
+      : undefined;
+  if (targetClientId !== undefined) {
+    const client = assistantEventHub.getClientById(targetClientId);
+    return client?.capabilities.includes(capability)
+      ? (parseClientOs(client.interfaceId) ?? undefined)
+      : undefined;
+  }
+
+  const eligible = getEligibleHostClientOs(capability, context);
+  return eligible.size === 1 ? eligible.values().next().value : undefined;
+}

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

@@ -1,9 +1,9 @@
 /**
  * Computer-use tool definitions.
  *
- * These tools mirror the macOS client's ToolDefinitions.swift schemas, prefixed
+ * These tools mirror the desktop client's computer-use schemas, prefixed
  * with `computer_use_` to avoid collisions with existing daemon tools.  They are all
- * proxy tools - execution is forwarded to a connected macOS client and never
+ * proxy tools. Execution is forwarded to a connected desktop client and never
  * handled locally by the daemon.
  */
 
@@ -19,7 +19,7 @@ import type {
 // ---------------------------------------------------------------------------
 
 /**
- * Forward execution to the connected macOS client via the request-bound
+ * Forward execution to the connected desktop client via the request-bound
  * `proxyToolResolver`. Returns a structured error when no resolver is
  * configured (e.g. no client connected) so callers see a normal tool
  * failure rather than an unhandled throw.
@@ -31,7 +31,7 @@ function proxyExecute(toolName: string) {
   ): Promise<ToolExecutionResult> => {
     if (!context.proxyToolResolver) {
       return {
-        content: `No proxy resolver configured for proxy tool "${toolName}". This tool requires an external resolver (e.g. a connected macOS client for computer-use tools).`,
+        content: `No proxy resolver configured for proxy tool "${toolName}". This tool requires a connected desktop client.`,
         isError: true,
       };
     }
@@ -131,7 +131,7 @@ export const computerUseTypeTextTool = {
 export const computerUseKeyTool = {
   name: "computer_use_key",
   description:
-    "Press a key or keyboard shortcut. Supported: enter, tab, escape, backspace, delete, up, down, left, right, space, cmd+a, cmd+c, cmd+v, cmd+z, cmd+tab, cmd+w, shift+tab, option+tab",
+    "Press a key or keyboard shortcut. Supported: enter, tab, escape, backspace, delete, up, down, left, right, space, cmd+a, cmd+c, cmd+v, cmd+z, cmd+tab, cmd+w, shift+tab, option+tab. On Windows use ctrl/alt in place of cmd/option.",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionTarget: "host",
@@ -141,7 +141,8 @@ export const computerUseKeyTool = {
     properties: {
       key: {
         type: "string",
-        description: "Key or shortcut to press (e.g. enter, tab, cmd+c, cmd+v)",
+        description:
+          "Key or shortcut to press (e.g. enter, tab, ctrl+c, cmd+c)",
       },
       reasoning: {
         type: "string",
@@ -223,6 +224,7 @@ export const computerUseDragTool = {
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionTarget: "host",
+  supportedClientOs: ["macos", "windows"],
 
   input_schema: {
     type: "object",
@@ -311,10 +313,11 @@ export const computerUseWaitTool = {
 export const computerUseOpenAppTool = {
   name: "computer_use_open_app",
   description:
-    "Open or switch to a macOS application by name. Preferred over cmd+tab for switching apps - more reliable and explicit.",
+    "Open or switch to a desktop application by name. Preferred over cmd+tab / alt+tab for switching apps - more reliable and explicit.",
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionTarget: "host",
+  supportedClientOs: ["macos", "windows"],
 
   input_schema: {
     type: "object",
@@ -352,6 +355,7 @@ export const computerUseRunAppleScriptTool = {
   category: "computer-use",
   defaultRiskLevel: RiskLevel.Low,
   executionTarget: "host",
+  supportedClientOs: ["macos"],
 
   input_schema: {
     type: "object",

package/src/tools/computer-use/skill-proxy-bridge.ts

@@ -2,7 +2,7 @@
  * Shared helper for computer-use skill wrapper scripts.
  *
  * Each wrapper calls forwardComputerUseProxyTool() to delegate execution to
- * the proxy resolver, which forwards the call to the connected macOS client.
+ * the proxy resolver, which forwards the call to the connected desktop client.
  */
 
 import type { ToolContext, ToolExecutionResult } from "../types.js";
@@ -20,7 +20,7 @@ export function forwardComputerUseProxyTool(
 ): Promise<ToolExecutionResult> {
   if (!context.proxyToolResolver) {
     return Promise.resolve({
-      content: `Cannot execute ${toolName}: no proxy resolver available. This tool requires a connected macOS client.`,
+      content: `Cannot execute ${toolName}: no proxy resolver available. This tool requires a connected desktop client.`,
       isError: true,
     });
   }

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

@@ -1,51 +1,3 @@
-/** 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;
-  service: string;
-  field: string;
-  toolName: string;
-  /** Timestamp (epoch ms) when this token was created. */
-  createdAt: number;
-  /** Whether this token has been consumed (single-use). */
-  consumed: boolean;
-}
-
-/** Request to authorize the use of a credential. */
-export interface AuthorizeRequest {
-  service: string;
-  field: string;
-  toolName: string;
-  /** Optional domain for domain-policy checking (used by browser tools). */
-  domain?: string;
-}
-
-/** Successful authorization result. */
-export interface AuthorizeSuccess {
-  authorized: true;
-  token: UsageToken;
-}
-
-/** Denied authorization result. */
-export interface AuthorizeDenied {
-  authorized: false;
-  reason: string;
-}
-
-export type AuthorizeResult = AuthorizeSuccess | AuthorizeDenied;
-
-/** Result of consuming a token. */
-export interface ConsumeResult {
-  success: boolean;
-  /** The storage key to read the secret from (only present on success). */
-  storageKey?: string;
-  /** The resolved value when a transient (one-time) credential was consumed. */
-  value?: string;
-  /** Error reason if consumption failed. */
-  reason?: string;
-}
-
 /** Request for the broker to fill a browser field without exposing plaintext. */
 export interface BrowserFillRequest {
   service: string;
@@ -83,26 +35,3 @@ export interface ServerUseResult<T> {
   result?: T;
   reason?: string;
 }
-
-/** Request to look up a credential by ID for proxy injection (no secret exposed). */
-export interface ServerUseByIdRequest {
-  credentialId: string;
-  requestingTool: string;
-}
-
-/** Successful by-id lookup result - metadata + injection templates, never plaintext. */
-export interface ServerUseByIdSuccess {
-  success: true;
-  credentialId: string;
-  service: string;
-  field: string;
-  injectionTemplates: CredentialInjectionTemplate[];
-}
-
-/** Denied or not-found by-id lookup result. */
-export interface ServerUseByIdDenied {
-  success: false;
-  reason: string;
-}
-
-export type ServerUseByIdResult = ServerUseByIdSuccess | ServerUseByIdDenied;