@vellumai/assistant 0.7.1 → 0.7.3

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

@@ -0,0 +1,389 @@
+/**
+ * Host app-control proxy.
+ *
+ * Proxies app-control actions (start, observe, press, combo, type, click,
+ * drag, stop) to the desktop client. Targets a specific application by
+ * bundle ID or process name — distinct from the system-wide computer-use
+ * proxy ({@link HostCuProxy}).
+ *
+ * Lifecycle (pending map, timeout, abort SSE, dispose, isAvailable) lives
+ * in {@link HostProxyBase}; this class layers app-control-specific state
+ * (PNG-hash loop guard) and the result-payload → ToolExecutionResult
+ * translation on top.
+ *
+ * **Session lock.** Only one conversation may hold an active app-control
+ * session at a time, and that session is bound to a specific target app.
+ * The lock is module-level (`activeAppControlSession`) because the session
+ * targets the user's actual desktop application, which is a host-wide
+ * resource. It is acquired on a successful `app_control_start` (storing
+ * `(conversationId, app)`) and released 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
+ * other tools (observe / press / combo / sequence / type / click / drag)
+ * require the calling conversation to own an active session targeting the
+ * same `app`; otherwise the call is rejected before any host dispatch.
+ * This prevents prompt-injected tool calls from sending raw input to
+ * arbitrary apps without the user having approved control of that
+ * specific app.
+ *
+ * **No step cap.** Unlike {@link HostCuProxy} which enforces a per-session
+ * step ceiling via `loadConfig().maxStepsPerSession`, app-control sessions
+ * are not capped. App-control flows are typically narrower (single-app,
+ * shorter horizons) and the loop guard plus user oversight are the
+ * intended safeguards.
+ */
+
+import { createHash } from "node:crypto";
+
+import type { ContentBlock } from "../providers/types.js";
+import type { ToolExecutionResult } from "../tools/types.js";
+import { getLogger } from "../util/logger.js";
+import { HostProxyBase, HostProxyRequestError } from "./host-proxy-base.js";
+import type {
+  HostAppControlInput,
+  HostAppControlResultPayload,
+} from "./message-types/host-app-control.js";
+
+const log = getLogger("host-app-control-proxy");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const REQUEST_TIMEOUT_MS = 60 * 1000;
+// Threshold of 4 means the warning fires on the 5th identical observation:
+// the first observation establishes the baseline (count = 0), each
+// subsequent identical observation increments the counter, so count = 4 is
+// reached on the 5th total observation.
+const STUCK_REPEAT_THRESHOLD = 4;
+
+// ---------------------------------------------------------------------------
+// Module-level session lock
+// ---------------------------------------------------------------------------
+
+/**
+ * Active app-control session: the conversation that owns the lock and the
+ * `app` it was approved against. Set on a successful `app_control_start`;
+ * cleared by the owning proxy's `dispose()`.
+ */
+export interface ActiveAppControlSession {
+  conversationId: string;
+  /**
+   * The exact `app` string the user approved at start time (bundle ID or
+   * process name — preserved as-is). Compared case-insensitively against
+   * the `app` of subsequent non-start tool calls.
+   */
+  app: string;
+}
+
+/**
+ * Currently active session, or `undefined` when no session is held.
+ *
+ * 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. */
+export function _getActiveAppControlSession():
+  | ActiveAppControlSession
+  | undefined {
+  return activeAppControlSession;
+}
+
+/** Test-only helper: clear session between test cases. */
+export function _resetActiveAppControlSession(): void {
+  activeAppControlSession = 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.
+ */
+export function _setActiveAppControlSession(
+  session: ActiveAppControlSession,
+): void {
+  activeAppControlSession = session;
+}
+
+/**
+ * Validate a non-start tool call against the active session. Returns a
+ * `ToolExecutionResult` (with `isError: true`) when the call should be
+ * rejected; returns `null` when the call is authorized to dispatch.
+ *
+ * `app` matching is case-insensitive (macOS bundle IDs are
+ * case-insensitive in practice) but strict on form: `"Safari"` and
+ * `"com.apple.Safari"` do not match — the user approved a specific string
+ * and substituting a different form requires a new approval.
+ */
+function checkNonStartAuthorization(
+  input: HostAppControlInput,
+  conversationId: string,
+): ToolExecutionResult | null {
+  if (activeAppControlSession == null) {
+    return {
+      content:
+        "No app-control session is active. Call app_control_start to request " +
+        "user approval to control the target app, then retry.",
+      isError: true,
+    };
+  }
+  if (activeAppControlSession.conversationId !== conversationId) {
+    return {
+      content:
+        `Another conversation (${activeAppControlSession.conversationId}) currently ` +
+        `holds the app-control session. Wait for it to finish, or call ` +
+        `app_control_stop from that conversation first.`,
+      isError: true,
+    };
+  }
+  // `app` is required on every non-start variant of HostAppControlInput
+  // except `stop`, and `stop` short-circuits in conversation-surfaces and
+  // does not reach this method in production. A stop reaching here would
+  // be a defensive bug — surface it explicitly rather than dispatch.
+  const requestedApp = (input as { app?: string }).app;
+  if (requestedApp == null) {
+    return {
+      content:
+        "Tool input missing required 'app' field; cannot validate against " +
+        "the active app-control session.",
+      isError: true,
+    };
+  }
+  if (
+    requestedApp.toLowerCase() !== activeAppControlSession.app.toLowerCase()
+  ) {
+    return {
+      content:
+        `Active app-control session targets ${activeAppControlSession.app}; ` +
+        `cannot send actions to ${requestedApp}. Call app_control_stop and ` +
+        `app_control_start to switch apps.`,
+      isError: true,
+    };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// HostAppControlProxy
+// ---------------------------------------------------------------------------
+
+export class HostAppControlProxy extends HostProxyBase<
+  HostAppControlInput,
+  HostAppControlResultPayload
+> {
+  /** Conversation that owns this proxy instance. Used by `dispose()` to release the session lock only when this proxy is the holder. */
+  private readonly conversationId: string;
+
+  /** sha256 hex of the most recent observation's `pngBase64`, or undefined. */
+  private lastObservationHash?: string;
+
+  /**
+   * Number of consecutive observations whose PNG hash matched the previous
+   * one. Reset to 0 when a different hash is observed. When this reaches
+   * {@link STUCK_REPEAT_THRESHOLD}, results carry a `"stuck"` warning.
+   */
+  private observationHashRepeatCount = 0;
+
+  constructor(conversationId: string) {
+    super({
+      capabilityName: "host_app_control",
+      requestEventName: "host_app_control_request",
+      cancelEventName: "host_app_control_cancel",
+      resultPendingKind: "host_app_control",
+      timeoutMs: REQUEST_TIMEOUT_MS,
+      disposedMessage: "Host app-control proxy disposed",
+    });
+    this.conversationId = conversationId;
+  }
+
+  // ---------------------------------------------------------------------------
+  // State accessors (testing / external inspection)
+  // ---------------------------------------------------------------------------
+
+  get observationRepeatCount(): number {
+    return this.observationHashRepeatCount;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public request entry point
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Dispatch an app-control tool call to the desktop client. Catches the
+   * base's typed lifecycle errors (timeout/aborted/disposed) and returns
+   * a `ToolExecutionResult` instead of letting them bubble.
+   */
+  async request(
+    toolName: string,
+    input: HostAppControlInput,
+    conversationId: string,
+    signal: AbortSignal,
+  ): Promise<ToolExecutionResult> {
+    if (signal.aborted) {
+      return { content: "Aborted", isError: true };
+    }
+
+    // Authorization gate. `start` acquires the session lock (the user's
+    // medium-risk approval is the consent boundary); all other tools must
+    // 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.
+    if (input.tool === "start") {
+      if (
+        activeAppControlSession != null &&
+        activeAppControlSession.conversationId !== conversationId
+      ) {
+        return {
+          content:
+            `Another conversation (${activeAppControlSession.conversationId}) currently holds the ` +
+            `app-control session. Wait for it to finish, or call app_control_stop ` +
+            `from that conversation first.`,
+          isError: true,
+        };
+      }
+    } else {
+      const sessionError = checkNonStartAuthorization(input, conversationId);
+      if (sessionError != null) {
+        return sessionError;
+      }
+    }
+
+    try {
+      const payload = await this.dispatchRequest(
+        toolName,
+        input,
+        conversationId,
+        signal,
+      );
+      return this.handleSuccess(input, payload);
+    } catch (err) {
+      if (err instanceof HostProxyRequestError) {
+        if (err.reason === "timeout") {
+          log.warn({ toolName }, "Host app-control proxy request timed out");
+          return {
+            content:
+              "Host app-control proxy timed out waiting for client response",
+            isError: true,
+          };
+        }
+        if (err.reason === "aborted") {
+          return { content: "Aborted", isError: true };
+        }
+      }
+      // `disposed` and any other unexpected errors propagate.
+      throw err;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Result handling
+  // ---------------------------------------------------------------------------
+
+  private handleSuccess(
+    input: HostAppControlInput,
+    payload: HostAppControlResultPayload,
+  ): ToolExecutionResult {
+    // Update PNG-hash loop tracking only for the "running" state — other
+    // states (missing/minimized) intentionally won't carry a
+    // representative window screenshot, so they should not feed the guard.
+    let stuck = false;
+    if (payload.state === "running" && payload.pngBase64) {
+      const hash = createHash("sha256").update(payload.pngBase64).digest("hex");
+      if (hash === this.lastObservationHash) {
+        this.observationHashRepeatCount++;
+      } else {
+        this.observationHashRepeatCount = 0;
+      }
+      this.lastObservationHash = hash;
+      if (this.observationHashRepeatCount >= STUCK_REPEAT_THRESHOLD) {
+        stuck = true;
+      }
+    }
+
+    // Store the exact `app` form for validation against subsequent
+    // non-start tool calls.
+    if (input.tool === "start" && payload.state === "running") {
+      activeAppControlSession = {
+        conversationId: this.conversationId,
+        app: input.app,
+      };
+    }
+
+    return this.formatResult(payload, stuck);
+  }
+
+  private formatResult(
+    payload: HostAppControlResultPayload,
+    stuck: boolean,
+  ): ToolExecutionResult {
+    const parts: string[] = [];
+
+    if (stuck) {
+      parts.push(
+        `WARNING: ${this.observationHashRepeatCount} consecutive observations ` +
+          `produced an identical screenshot — the app appears stuck. Try a ` +
+          `different action or call app_control_stop and restart.`,
+      );
+      parts.push("");
+    }
+
+    parts.push(`State: ${payload.state}`);
+
+    if (payload.windowBounds) {
+      const { x, y, width, height } = payload.windowBounds;
+      parts.push(`Window bounds: ${width}x${height} at (${x}, ${y})`);
+    }
+
+    if (payload.executionResult) {
+      parts.push("");
+      parts.push(payload.executionResult);
+    }
+
+    const isError = payload.executionError != null;
+    const errorPrefix = isError
+      ? `Action failed: ${payload.executionError}`
+      : null;
+
+    const baseContent = parts.join("\n").trim() || `State: ${payload.state}`;
+    const content = errorPrefix
+      ? `${errorPrefix}\n\n${baseContent}`
+      : baseContent;
+
+    const contentBlocks: ContentBlock[] = [];
+    if (payload.pngBase64) {
+      contentBlocks.push({
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: "image/png",
+          data: payload.pngBase64,
+        },
+      });
+    }
+
+    return {
+      content,
+      isError,
+      ...(contentBlocks.length > 0 ? { contentBlocks } : {}),
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Reject pending requests via the base, then release the session lock
+   * if this proxy is the holder. Idempotent: safe to call multiple times.
+   */
+  override dispose(): void {
+    super.dispose();
+    if (activeAppControlSession?.conversationId === this.conversationId) {
+      activeAppControlSession = undefined;
+    }
+  }
+}

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

@@ -5,25 +5,19 @@ import {
   assistantEventHub,
   broadcastMessage,
 } from "../runtime/assistant-event-hub.js";
+import {
+  ambiguousSameUserError,
+  enforceSameActorOrErrorResult,
+  pickSameUserAutoResolve,
+} from "../runtime/auth/same-actor.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { formatShellOutput } from "../tools/shared/shell-output.js";
 import type { ToolExecutionResult } from "../tools/types.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
-import type { ServerMessage } from "./message-protocol.js";
 
 const log = getLogger("host-bash-proxy");
 
-interface PendingRequest {
-  resolve: (result: ToolExecutionResult) => void;
-  reject: (err: Error) => void;
-  timer: ReturnType<typeof setTimeout>;
-  timeoutSec: number;
-  conversationId: string;
-  /** Detach the abort listener from the caller's signal. No-op when no signal was passed. */
-  detachAbort: () => void;
-}
-
 export class HostBashProxy {
   private static _instance: HostBashProxy | null = null;
 
@@ -53,8 +47,6 @@ export class HostBashProxy {
     HostBashProxy._instance = null;
   }
 
-  private pending = new Map<string, PendingRequest>();
-
   /**
    * Whether a client with `host_bash` capability is connected.
    */
@@ -64,71 +56,105 @@ export class HostBashProxy {
     );
   }
 
-  private send(msg: ServerMessage): void {
-    broadcastMessage(msg, undefined, { targetCapability: "host_bash" });
-  }
-
   request(
     input: {
       command: string;
       working_dir?: string;
       timeout_seconds?: number;
       env?: Record<string, string>;
+      targetClientId?: string;
     },
     conversationId: string,
     signal?: AbortSignal,
+    // Principal ID of the actor on whose behalf this request is initiated.
+    sourceActorPrincipalId?: string,
   ): Promise<ToolExecutionResult> {
     if (signal?.aborted) {
       const result = formatShellOutput("", "Aborted", null, false, 0);
       return Promise.resolve(result);
     }
 
+    let resolvedTargetClientId: string | undefined;
+
+    if (input.targetClientId) {
+      const target = assistantEventHub.getClientById(input.targetClientId);
+      if (!target || !target.capabilities.includes("host_bash")) {
+        return Promise.resolve({
+          content: `Error: client "${input.targetClientId}" is not connected or does not support host_bash. Run \`assistant clients list --capability host_bash\` to see available clients.`,
+          isError: true,
+        });
+      }
+      resolvedTargetClientId = input.targetClientId;
+    } else {
+      // Auto-resolve to the unique same-user client. Reject (rather than
+      // broadcast) when multiple same-user clients are connected so that
+      // a single targeted-style request cannot fan out across every one
+      // of the user's machines. Zero same-user matches falls through to
+      // the existing untargeted code path.
+      const resolved = pickSameUserAutoResolve({
+        hub: assistantEventHub,
+        capability: "host_bash",
+        sourceActorPrincipalId,
+      });
+      if (resolved.kind === "ambiguous") {
+        return Promise.resolve(ambiguousSameUserError("host_bash"));
+      }
+      resolvedTargetClientId =
+        resolved.kind === "match" ? resolved.clientId : undefined;
+    }
+
+    // Targeted requests must be bound to the same authenticated user as the
+    // target client. Fail closed at request time — before pendingInteractions
+    // registration and before broadcast — so a same-daemon caller cannot
+    // execute on another user's connected client.
+    if (resolvedTargetClientId != null) {
+      const rejection = enforceSameActorOrErrorResult({
+        hub: assistantEventHub,
+        sourceActorPrincipalId,
+        targetClientId: resolvedTargetClientId,
+        op: "host_bash",
+      });
+      if (rejection) return Promise.resolve(rejection);
+    }
+
     const requestId = uuid();
 
     return new Promise<ToolExecutionResult>((resolve, reject) => {
       const shellMaxTimeoutSec = getConfig().timeouts.shellMaxTimeoutSec;
       const timeoutSec = input.timeout_seconds ?? shellMaxTimeoutSec;
-      // Proxy timeout: slightly after client-side timeout, but before executor's outer timeout
       const proxyTimeoutSec = timeoutSec + 3;
 
-      // Declared up-front so onAbort (defined before detachAbort is assigned)
-      // can close over a stable reference once it's wired below.
       let detachAbort: () => void = () => {};
 
       const timer = setTimeout(() => {
-        this.pending.delete(requestId);
-        detachAbort();
         pendingInteractions.resolve(requestId);
         log.warn(
           { requestId, command: input.command },
           "Host bash proxy request timed out",
         );
-        resolve(
-          formatShellOutput(
-            "",
-            "Host bash proxy timed out waiting for client response",
-            null,
-            true,
-            timeoutSec,
-          ),
-        );
+        const timeoutMessage = resolvedTargetClientId
+          ? `Host bash proxy timed out waiting for response from client ${resolvedTargetClientId}`
+          : "Host bash proxy timed out waiting for client response";
+        resolve(formatShellOutput("", timeoutMessage, null, true, timeoutSec));
       }, proxyTimeoutSec * 1000);
 
       if (signal) {
         const onAbort = () => {
-          if (this.pending.has(requestId)) {
-            clearTimeout(timer);
-            this.pending.delete(requestId);
-            detachAbort();
+          if (pendingInteractions.get(requestId)) {
             pendingInteractions.resolve(requestId);
             try {
-              this.send({
-                type: "host_bash_cancel",
-                requestId,
+              broadcastMessage(
+                {
+                  type: "host_bash_cancel",
+                  requestId,
+                  conversationId,
+                  targetClientId: resolvedTargetClientId,
+                },
                 conversationId,
-              });
+                { targetClientId: resolvedTargetClientId },
+              );
             } catch {
-              // Best-effort cancel notification — connection may already be closed.
+              // Best-effort cancel notification
             }
             resolve(formatShellOutput("", "Aborted", null, false, 0));
           }
@@ -137,31 +163,41 @@ export class HostBashProxy {
         detachAbort = () => signal.removeEventListener("abort", onAbort);
       }
 
-      this.pending.set(requestId, {
-        resolve,
-        reject,
-        timer,
-        timeoutSec,
+      pendingInteractions.register(requestId, {
         conversationId,
+        kind: "host_bash",
+        rpcResolve: resolve,
+        rpcReject: reject,
+        timer,
         detachAbort,
+        targetClientId: resolvedTargetClientId,
+        targetActorPrincipalId:
+          resolvedTargetClientId != null
+            ? assistantEventHub.getActorPrincipalIdForClient(
+                resolvedTargetClientId,
+              )
+            : undefined,
+        metadata: { timeoutSec },
       });
 
       try {
-        this.send({
-          type: "host_bash_request",
-          requestId,
-          conversationId,
-          command: input.command,
-          working_dir: input.working_dir,
-          timeout_seconds: input.timeout_seconds,
-          ...(input.env && Object.keys(input.env).length > 0
+        broadcastMessage(
+          {
+            type: "host_bash_request",
+            requestId,
+            conversationId,
+            command: input.command,
+            working_dir: input.working_dir,
+            timeout_seconds: input.timeout_seconds,
+            targetClientId: resolvedTargetClientId,
+            ...(input.env && Object.keys(input.env).length > 0
               ? { env: input.env }
               : {}),
-          });
+          },
+          conversationId,
+          { targetClientId: resolvedTargetClientId },
+        );
       } catch (err) {
-        clearTimeout(timer);
-        this.pending.delete(requestId);
-        detachAbort();
         pendingInteractions.resolve(requestId);
         log.warn(
           { requestId, command: input.command, err },
@@ -172,7 +208,10 @@ export class HostBashProxy {
     });
   }
 
-  resolve(
+  /**
+   * Process a client result and resolve the RPC. Called by route handlers.
+   */
+  resolveResult(
     requestId: string,
     response: {
       stdout: string;
@@ -181,49 +220,45 @@ export class HostBashProxy {
       timedOut: boolean;
     },
   ): void {
-    const entry = this.pending.get(requestId);
-    if (!entry) {
+    const interaction = pendingInteractions.resolve(requestId);
+    if (!interaction?.rpcResolve) {
       log.warn({ requestId }, "No pending host bash request for response");
       return;
     }
-    clearTimeout(entry.timer);
-    entry.detachAbort();
-    this.pending.delete(requestId);
+    const timeoutSec = (interaction.metadata?.timeoutSec as number) ?? 0;
     const result = formatShellOutput(
       response.stdout,
       response.stderr,
       response.exitCode,
       response.timedOut,
-      entry.timeoutSec,
+      timeoutSec,
     );
-    entry.resolve(result);
-  }
-
-  hasPendingRequest(requestId: string): boolean {
-    return this.pending.has(requestId);
+    interaction.rpcResolve(result);
   }
 
   dispose(): void {
-    for (const [requestId, entry] of this.pending) {
-        clearTimeout(entry.timer);
-        entry.detachAbort();
-        pendingInteractions.resolve(requestId);
-        try {
-          this.send({
+    for (const entry of pendingInteractions.getByKind("host_bash")) {
+      pendingInteractions.resolve(entry.requestId);
+      try {
+        broadcastMessage(
+          {
             type: "host_bash_cancel",
-            requestId,
+            requestId: entry.requestId,
             conversationId: entry.conversationId,
-          });
-        } catch {
-          // Best-effort cancel notification — connection may already be closed.
-        }
-      entry.reject(
+            targetClientId: entry.targetClientId,
+          },
+          entry.conversationId,
+          { targetClientId: entry.targetClientId },
+        );
+      } catch {
+        // Best-effort cancel notification — connection may already be closed.
+      }
+      entry.rpcReject?.(
         new AssistantError(
           "Host bash proxy disposed",
           ErrorCode.INTERNAL_ERROR,
         ),
       );
     }
-    this.pending.clear();
   }
 }