@vellumai/assistant 0.8.1 → 0.8.3

package/src/daemon/host-app-control-proxy.ts

@@ -17,9 +17,16 @@
  * targets the user's actual desktop application, which is a host-wide
  * resource. It is acquired optimistically when `app_control_start` is
  * dispatched (storing `(conversationId, app)`) so that the synchronous
- * guard and the asynchronous host round-trip cannot race; it is released
- * when the host returns a non-running state, the dispatch fails, or the
- * owning proxy's `dispose()` fires.
+ * guard and the asynchronous host round-trip cannot race. A separate
+ * `confirmedAppControlSession` tracks the last session the host reported
+ * `running`; the rollback path on a failed `start` restores from the
+ * current confirmed pointer (not from a per-call snapshot of a sibling
+ * optimistic write), so two overlapping starts that both fail cannot
+ * leave a phantom lock. Each session carries a monotonic `dispatchedAt`
+ * counter so out-of-order `running` responses promote in dispatch order:
+ * the latest-dispatched start that the host confirms becomes the
+ * confirmed baseline, regardless of which response arrived last. The
+ * lock is released outright when the owning proxy's `dispose()` fires.
  *
  * `app_control_start` is the only tool that can acquire the lock — the
  * user's medium-risk approval at start time is the consent boundary. All
@@ -78,37 +85,78 @@ export interface ActiveAppControlSession {
    * the `app` of subsequent non-start tool calls.
    */
   app: string;
+  /**
+   * Strictly monotonic counter assigned when the session is created (in
+   * `request()` for a `start`). Used by {@link promoteStartIfCurrent} to
+   * tell which of two confirmations from overlapping starts is newer when
+   * host responses arrive out of order. Larger values are newer.
+   */
+  dispatchedAt: number;
 }
 
 /**
- * Currently active session, or `undefined` when no session is held.
+ * Monotonic counter that stamps each `start`'s {@link
+ * ActiveAppControlSession.dispatchedAt}. Process-lifetime monotonic; the
+ * absolute value is meaningless — only ordering matters.
+ */
+let nextDispatchedAt = 1;
+
+/**
+ * Currently active session, or `undefined` when no session is held. This
+ * is the optimistic value: it is set the moment a `start` is dispatched
+ * and only promoted to {@link confirmedAppControlSession} when the host
+ * returns `running`.
  *
  * Exported for test inspection only. Production code paths must not read
  * or mutate this directly — use the proxy methods.
  */
 let activeAppControlSession: ActiveAppControlSession | undefined;
 
-/** Test-only helper: read current session. */
+/**
+ * Last session whose `start` was confirmed by the host (`payload.state ===
+ * "running"`). Used as the rollback baseline so a failed start never
+ * restores a sibling in-flight optimistic write — only a session that was
+ * actually running can re-emerge from a rollback.
+ */
+let confirmedAppControlSession: ActiveAppControlSession | undefined;
+
+/** Test-only helper: read current (optimistic) session. */
 export function _getActiveAppControlSession():
   | ActiveAppControlSession
   | undefined {
   return activeAppControlSession;
 }
 
-/** Test-only helper: clear session between test cases. */
+/** Test-only helper: read the last host-confirmed session. */
+export function _getConfirmedAppControlSession():
+  | ActiveAppControlSession
+  | undefined {
+  return confirmedAppControlSession;
+}
+
+/** Test-only helper: clear both session pointers between test cases. */
 export function _resetActiveAppControlSession(): void {
   activeAppControlSession = undefined;
+  confirmedAppControlSession = undefined;
 }
 
 /**
- * Test-only helper: prime the active session without a full `start` round-trip.
- * Useful for tests that exercise non-start tool paths and don't need to
- * verify the start flow itself.
+ * Test-only helper: prime both session pointers without a full `start`
+ * round-trip. Useful for tests that exercise non-start tool paths and
+ * don't need to verify the start flow itself.
  */
-export function _setActiveAppControlSession(
-  session: ActiveAppControlSession,
-): void {
-  activeAppControlSession = session;
+export function _setActiveAppControlSession(session: {
+  conversationId: string;
+  app: string;
+  dispatchedAt?: number;
+}): void {
+  const full: ActiveAppControlSession = {
+    conversationId: session.conversationId,
+    app: session.app,
+    dispatchedAt: session.dispatchedAt ?? nextDispatchedAt++,
+  };
+  activeAppControlSession = full;
+  confirmedAppControlSession = full;
 }
 
 /**
@@ -236,6 +284,7 @@ export class HostAppControlProxy extends HostProxyBase<
     // belong to the active session and target the same `app`. Without this
     // gate, prompt-injected calls would bypass the start-time approval and
     // send raw input to arbitrary apps.
+    let attemptedSession: ActiveAppControlSession | undefined;
     if (input.tool === "start") {
       if (
         activeAppControlSession != null &&
@@ -253,12 +302,16 @@ export class HostAppControlProxy extends HostProxyBase<
       // synchronous guard and the asynchronous `dispatchRequest` below. Two
       // concurrent starts from different conversations would otherwise both
       // see `activeAppControlSession == null` and both pass the guard. The
-      // lock is released below if dispatch fails or the host returns a
-      // non-running state.
-      activeAppControlSession = {
+      // lock is rolled back below if dispatch fails or the host returns a
+      // non-running state — keyed on object identity so that a later
+      // overlapping start that has already replaced our write is not
+      // clobbered by a stale rollback.
+      attemptedSession = {
         conversationId: this.conversationId,
         app: input.app,
+        dispatchedAt: nextDispatchedAt++,
       };
+      activeAppControlSession = attemptedSession;
     } else {
       const sessionError = checkNonStartAuthorization(
         input,
@@ -278,10 +331,17 @@ export class HostAppControlProxy extends HostProxyBase<
         undefined,
         targetClientId,
       );
-      return this.handleSuccess(input, payload);
+      if (input.tool === "start") {
+        if (payload.state === "running") {
+          this.promoteStartIfCurrent(attemptedSession);
+        } else {
+          this.rollbackStartIfCurrent(attemptedSession);
+        }
+      }
+      return this.handleSuccess(payload);
     } catch (err) {
       if (input.tool === "start") {
-        this.releaseSessionIfHeld();
+        this.rollbackStartIfCurrent(attemptedSession);
       }
       if (err instanceof HostProxyRequestError) {
         if (err.reason === "timeout") {
@@ -301,10 +361,85 @@ export class HostAppControlProxy extends HostProxyBase<
     }
   }
 
+  /**
+   * Roll back the optimistic overwrite performed by a `start` when the
+   * dispatch fails or the host returns non-running. Keyed on the
+   * `attempted` reference, not just `conversationId`, so that an
+   * out-of-order failure does not clobber a newer overlapping start that
+   * already replaced our write — e.g. start A → start B (pending) →
+   * start C (success); when B later fails, the live session is C and the
+   * identity check makes our rollback a no-op rather than restoring A.
+   *
+   * Restores from the *current* `confirmedAppControlSession`, not a
+   * per-call snapshot of it. This matters when a late-arriving `running`
+   * for an older overlapping start has updated `confirmedAppControlSession`
+   * in the meantime: if A is dispatched, then C is dispatched (overwriting
+   * active), then A returns `running` (confirming A), then C returns
+   * non-running, the rollback must restore active to A — not undefined.
+   */
+  private rollbackStartIfCurrent(
+    attempted: ActiveAppControlSession | undefined,
+  ): void {
+    if (attempted != null && activeAppControlSession === attempted) {
+      activeAppControlSession = confirmedAppControlSession;
+    }
+  }
+
+  /**
+   * Promote this start's session to the confirmed pointer when the host
+   * returns `running`. Two gates:
+   *
+   * 1. The live optimistic write must still belong to this conversation —
+   *    if `dispose()` cleared the lock or another conversation acquired
+   *    it, this confirmation must not resurrect a stale session.
+   * 2. The confirming session must be at least as recent as the currently
+   *    confirmed one, compared via {@link
+   *    ActiveAppControlSession.dispatchedAt}. The dispatch counter is
+   *    assigned synchronously in `request()`, so it captures dispatch
+   *    order even when host responses arrive out of order. The latest
+   *    dispatched start that confirms wins, which is the right baseline
+   *    for the rollback path: if a newer start later fails, rollback
+   *    restores the most recently confirmed session, not an older one.
+   *
+   * Also advance the active pointer when it is strictly older than the
+   * newly-confirmed session. This handles the case where an even newer
+   * optimistic write has already failed and rolled active back to the
+   * previous confirmed session; without this, observe/actions for the
+   * newly-confirmed session would target the older app. A newer
+   * in-flight optimistic write (higher `dispatchedAt`) is preserved.
+   */
+  private promoteStartIfCurrent(
+    attempted: ActiveAppControlSession | undefined,
+  ): void {
+    if (attempted == null) return;
+    if (activeAppControlSession?.conversationId !== attempted.conversationId) {
+      return;
+    }
+    if (
+      confirmedAppControlSession != null &&
+      attempted.dispatchedAt <= confirmedAppControlSession.dispatchedAt
+    ) {
+      return;
+    }
+    confirmedAppControlSession = attempted;
+    if (activeAppControlSession.dispatchedAt < attempted.dispatchedAt) {
+      activeAppControlSession = attempted;
+    }
+  }
+
+  /**
+   * Release both the optimistic and confirmed module-level session
+   * pointers if this proxy is the current holder. Used by `dispose()` —
+   * distinct from `rollbackStartIfCurrent` because dispose is keyed on
+   * ownership (conversationId) rather than on a specific in-flight start.
+   */
   private releaseSessionIfHeld(): void {
     if (activeAppControlSession?.conversationId === this.conversationId) {
       activeAppControlSession = undefined;
     }
+    if (confirmedAppControlSession?.conversationId === this.conversationId) {
+      confirmedAppControlSession = undefined;
+    }
   }
 
   // ---------------------------------------------------------------------------
@@ -312,7 +447,6 @@ export class HostAppControlProxy extends HostProxyBase<
   // ---------------------------------------------------------------------------
 
   private handleSuccess(
-    input: HostAppControlInput,
     payload: HostAppControlResultPayload,
   ): ToolExecutionResult {
     // Update PNG-hash loop tracking only for the "running" state — other
@@ -332,14 +466,6 @@ export class HostAppControlProxy extends HostProxyBase<
       }
     }
 
-    // The optimistic lock acquired in `request()` for `start` stays held
-    // only when the host confirms the session is running. Non-running
-    // outcomes (missing/minimized) release it so a retry or another
-    // conversation can acquire.
-    if (input.tool === "start" && payload.state !== "running") {
-      this.releaseSessionIfHeld();
-    }
-
     return this.formatResult(payload, stuck);
   }
 

package/src/daemon/host-proxy-preactivation.ts

@@ -29,6 +29,9 @@
 import type { HostProxyCapability, InterfaceId } from "../channels/types.js";
 import { supportsHostProxy } from "../channels/types.js";
 import { assistantEventHub } from "../runtime/assistant-event-hub.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("host-proxy-preactivation");
 
 /**
  * Subset of Conversation/ProcessConversationContext that
@@ -36,9 +39,29 @@ import { assistantEventHub } from "../runtime/assistant-event-hub.js";
  * `ProcessConversationContext` satisfy this structurally.
  */
 export interface HostProxyPreactivationTarget {
+  readonly conversationId: string;
   addPreactivatedSkillId(id: string): void;
 }
 
+/**
+ * Why an attachment decision went the way it did. Logged per turn so that
+ * silent-gate failures (e.g. ATL-609: computer-use never reaches the LLM
+ * surface for a macOS user) can be diagnosed from production logs without
+ * extra instrumentation.
+ */
+export type HostProxyAttachmentReason =
+  | "native_support"
+  | "cross_client"
+  | "denied_no_interface"
+  | "denied_chrome_extension"
+  | "denied_no_clients";
+
+export interface HostProxyAttachmentDecision {
+  shouldAttach: boolean;
+  reason: HostProxyAttachmentReason;
+  clientCount?: number;
+}
+
 /**
  * Registry mapping each host-proxy capability to the skill that must be
  * preactivated when that capability is supported by the source interface.
@@ -62,45 +85,89 @@ export const HOST_PROXY_SKILL_PREACTIVATIONS: ReadonlyArray<{
 ];
 
 /**
- * Returns true when a host-proxy for the given capability should be attached
- * (instantiated and preactivated) for the current turn. Two cases qualify:
+ * Returns the full attachment decision for a host-proxy capability — used both
+ * to gate proxy instantiation and to feed the structured preactivation log so
+ * silent gates can be diagnosed without re-instrumenting after the fact.
  *
- *  1. The source interface natively supports the capability (e.g. macOS → host_cu).
- *  2. The source interface doesn't support the capability natively but at least
- *     one connected client does — cross-client routing. `chrome-extension` is
- *     excluded as a security boundary: it is its own executor context and cannot
- *     broker cross-client routing to a macOS client.
+ *  1. No source interface → `denied_no_interface`.
+ *  2. Source interface natively supports the capability → `native_support`.
+ *  3. `chrome-extension` source can never broker cross-client routing to a
+ *     macOS client (security boundary) → `denied_chrome_extension`.
+ *  4. At least one connected client advertises the capability →
+ *     `cross_client` with `clientCount`.
+ *  5. Otherwise → `denied_no_clients` with `clientCount: 0`.
  *
- * This is the single source of truth for both preactivation and proxy
- * instantiation, so the two decisions stay in sync.
+ * Single source of truth for preactivation and proxy instantiation.
+ */
+export function evaluateHostProxyAttachment(
+  capability: HostProxyCapability,
+  sourceInterface: InterfaceId | undefined,
+): HostProxyAttachmentDecision {
+  if (!sourceInterface) {
+    return { shouldAttach: false, reason: "denied_no_interface" };
+  }
+  if (supportsHostProxy(sourceInterface, capability)) {
+    return { shouldAttach: true, reason: "native_support" };
+  }
+  if (sourceInterface === "chrome-extension") {
+    return { shouldAttach: false, reason: "denied_chrome_extension" };
+  }
+  const clientCount =
+    assistantEventHub.listClientsByCapability(capability).length;
+  if (clientCount > 0) {
+    return { shouldAttach: true, reason: "cross_client", clientCount };
+  }
+  return { shouldAttach: false, reason: "denied_no_clients", clientCount: 0 };
+}
+
+/**
+ * Boolean wrapper retained for the proxy-instantiation call sites that only
+ * need the gate result. Prefer `evaluateHostProxyAttachment` when the reason
+ * is also useful (e.g. for logging or telemetry).
  */
 export function shouldAttachHostProxyForCapability(
   capability: HostProxyCapability,
   sourceInterface: InterfaceId | undefined,
 ): boolean {
-  if (!sourceInterface) return false;
-  if (supportsHostProxy(sourceInterface, capability)) return true;
-  if (sourceInterface === "chrome-extension") return false;
-  return assistantEventHub.listClientsByCapability(capability).length > 0;
+  return evaluateHostProxyAttachment(capability, sourceInterface).shouldAttach;
 }
 
 /**
  * Preactivate every host-proxy-backed skill that the given source interface
- * supports. No-op when `sourceInterface` is undefined.
+ * supports, and emit one structured `log.info` line per turn capturing each
+ * capability's decision + the final preactivated skill IDs.
+ *
+ * The log line fires unconditionally — even when `sourceInterface` is
+ * undefined — because "preactivation never ran because no interface" is
+ * itself the diagnostic signal we want visible in production.
  *
  * Callers are responsible for any additional gating (e.g. only preactivating
  * when the conversation is idle vs. when re-adding after dequeue), since
- * those constraints differ across create vs. drain paths. This helper just
- * iterates the registry and dispatches.
+ * those constraints differ across create vs. drain paths.
  */
 export function preactivateHostProxySkills(
   conversation: HostProxyPreactivationTarget,
   sourceInterface: InterfaceId | undefined,
 ): void {
-  if (!sourceInterface) return;
+  const decisions: Record<string, HostProxyAttachmentDecision> = {};
+  const preactivatedSkillIds: string[] = [];
+
   for (const { capability, skillId } of HOST_PROXY_SKILL_PREACTIVATIONS) {
-    if (shouldAttachHostProxyForCapability(capability, sourceInterface)) {
+    const decision = evaluateHostProxyAttachment(capability, sourceInterface);
+    decisions[capability] = decision;
+    if (decision.shouldAttach) {
       conversation.addPreactivatedSkillId(skillId);
+      preactivatedSkillIds.push(skillId);
     }
   }
+
+  log.info(
+    {
+      conversationId: conversation.conversationId,
+      sourceInterface,
+      decisions,
+      preactivatedSkillIds,
+    },
+    "host-proxy preactivation decision",
+  );
 }