@testdriverai/mcp 7.11.5-test → 7.11.7-canary

package/mcp-server/src/core/actions.ts

@@ -18,9 +18,10 @@
  * mirroring how the stdio MCP server has always behaved.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { generateActionCode } from "../codegen.js";
 import { getProvisionOptions, SessionStartInputSchema, type SessionStartInput } from "../provision-types.js";
-import { sessionManager, type SessionState } from "../session.js";
+import { SessionManager, sessionManager as globalSessionManager, type SessionState } from "../session.js";
 
 // Re-export the input contract so adapters (MCP server, eve tools) share one
 // source of truth for the session_start schema instead of redeclaring it.
@@ -62,21 +63,120 @@ export class NoActiveSessionError extends Error {
 }
 
 // =============================================================================
-// Singleton state (single sandbox per process)
+// Per-connection state (isolated via AsyncLocalStorage)
 // =============================================================================
 
-let sdk: any = null;
-let lastScreenshotBase64: string | null = null;
+/**
+ * The mutable state a single sandbox session needs: the live SDK handle, the
+ * element-ref map from `find`/`findall`, the "last screenshot" `check` diffs
+ * against, the adapter recovery hook, the in-flight reconnect promise, and the
+ * session-lifecycle manager.
+ *
+ * This used to be a bag of module-level singletons ("single sandbox per
+ * process"). That is correct for hosts that ARE one-session-per-process — eve
+ * (each durable turn is its own recycled process) and the stdio MCP server — but
+ * the Streamable-HTTP MCP server is one long-lived process serving *concurrent*
+ * clients, where shared singletons let one client's tool call read another
+ * client's sandbox. So the state moves into {@link CoreContext} and is resolved
+ * per async call via {@link als}.
+ */
+export interface CoreContext {
+  sdk: any;
+  lastScreenshotBase64: string | null;
+  reconnectResolver: ReconnectResolver | null;
+  /** In-flight reconnect, so concurrent actions in one context share one rebuild. */
+  reconnecting: Promise<void> | null;
+  /** Stored element instances from `find`/`findall`, addressable by ref. */
+  elementRefs: Map<
+    string,
+    { element: any; description: string; coords: { x: number; y: number; centerX: number; centerY: number } }
+  >;
+  /** Session lifecycle for THIS context. */
+  sessions: SessionManager;
+  /**
+   * Opaque per-connection scratch space for adapters (e.g. the MCP server's
+   * image store). mcp-core doesn't read this; it just guarantees each isolated
+   * context gets its own object, so adapter-side per-connection state rides along
+   * with the same AsyncLocalStorage isolation instead of needing a second one.
+   */
+  adapter: Record<string, unknown>;
+}
+
+/** Build a fresh, empty context. Callers that want isolation mint one per connection. */
+export function createCoreContext(): CoreContext {
+  return {
+    sdk: null,
+    lastScreenshotBase64: null,
+    reconnectResolver: null,
+    reconnecting: null,
+    elementRefs: new Map(),
+    // Reuse the shared SessionManager for the global context so that consumers
+    // still importing `sessionManager` from ../session observe the same state;
+    // isolated contexts get their own instance.
+    sessions: globalSessionManager,
+    adapter: {},
+  };
+}
+
+const als = new AsyncLocalStorage<CoreContext>();
+
+/**
+ * The fallback context used when no isolated context is active — i.e. for eve
+ * and the stdio MCP server, which are one-session-per-process and never call
+ * {@link runInContext}. Behavior for those hosts is byte-identical to the old
+ * module-global singletons.
+ */
+const globalContext: CoreContext = createCoreContext();
+
+/** Resolve the active context: the ALS store if one is running, else the global. */
+function ctx(): CoreContext {
+  return als.getStore() ?? globalContext;
+}
+
+/**
+ * Run `fn` with `context` as the active {@link CoreContext}, isolating every
+ * action's state (sdk, element refs, session, recovery hook) for the duration.
+ * The HTTP MCP server wraps each connection's request handling in this so
+ * concurrent clients never share a sandbox. Hosts that don't call this keep
+ * using {@link globalContext} exactly as before.
+ */
+export function runInContext<T>(context: CoreContext, fn: () => T): T {
+  return als.run(context, fn);
+}
+
+/** Build an isolated context whose SessionManager is its own (not the global). */
+export function createIsolatedContext(): CoreContext {
+  const c = createCoreContext();
+  c.sessions = new SessionManager();
+  return c;
+}
+
+/** The active context's adapter scratch space (see {@link CoreContext.adapter}). */
+export function getAdapterState(): Record<string, unknown> {
+  return ctx().adapter;
+}
+
+/** The active context's current session (null when none). Adapters use this for
+ *  read-only lookups (e.g. the MCP server's testFile/expiry) that must resolve
+ *  the caller's own session, not a process-global one. */
+export function getCurrentSession(): SessionState | null {
+  return ctx().sessions.getCurrentSession();
+}
+
+/** Time remaining (ms) on a session in the active context. */
+export function getSessionTimeRemaining(sessionId: string): number {
+  return ctx().sessions.getTimeRemaining(sessionId);
+}
 
 /**
- * Optional adapter-supplied recovery hook. When the singleton SDK is missing or
- * stale at action time, {@link requireActiveSession} calls this to obtain the
- * params needed to rebuild the connection from the still-alive sandbox, then
- * reconnects before throwing NO_SESSION.
+ * Optional adapter-supplied recovery hook. When the SDK is missing or stale at
+ * action time, {@link requireActiveSession} calls this to obtain the params
+ * needed to rebuild the connection from the still-alive sandbox, then reconnects
+ * before throwing NO_SESSION.
  *
  * Why a hook instead of mcp-core owning the handle: the durable facts (sandbox
  * id, config) and the API key must survive a host process recycle, but this
- * module's globals do NOT — they reset on the very recycle we're recovering
+ * context's state does NOT — it resets on the very recycle we're recovering
  * from. So the *durable owner* (eve's per-session state) registers a resolver
  * that reads its own durable store and re-resolves the key per call. Hosts with
  * one long-lived process (stdio MCP server, CLI) register nothing: the resolver
@@ -85,38 +185,28 @@ let lastScreenshotBase64: string | null = null;
  *
  * The resolver returns `null` when it has nothing to recover from (no sandbox
  * provisioned this session), in which case we fall through to the normal throw.
- * It is re-registered each step by the adapter (module globals reset on recycle),
+ * It is re-registered each step by the adapter (context state resets on recycle),
  * so a stale closure can't outlive the process it was bound to.
  */
 export type ReconnectResolver = () => Promise<ReconnectParams | null>;
-let reconnectResolver: ReconnectResolver | null = null;
 
 /**
  * Register (or clear, with `null`) the recovery hook. Durable adapters call this
  * at the start of each step with a resolver bound to the current tool context.
  */
 export function setReconnectResolver(resolver: ReconnectResolver | null): void {
-  reconnectResolver = resolver;
+  ctx().reconnectResolver = resolver;
 }
 
-/** In-flight reconnect, so concurrent actions in one step share one rebuild. */
-let reconnecting: Promise<void> | null = null;
-
-/** Stored element instances from `find`/`findall`, addressable by ref. */
-const elementRefs = new Map<
-  string,
-  { element: any; description: string; coords: { x: number; y: number; centerX: number; centerY: number } }
->();
-
 /** Expose internals the adapters legitimately need (read-only intent). */
 export function getSdk(): any {
-  return sdk;
+  return ctx().sdk;
 }
 export function getLastScreenshotBase64(): string | null {
-  return lastScreenshotBase64;
+  return ctx().lastScreenshotBase64;
 }
 export function getElementRef(ref: string) {
-  return elementRefs.get(ref);
+  return ctx().elementRefs.get(ref);
 }
 
 /**
@@ -127,8 +217,9 @@ export function getElementRef(ref: string) {
  * does NOT refresh the keepAlive window — it only reports liveness.
  */
 export function hasLiveSession(): boolean {
-  const session = sessionManager.getCurrentSession();
-  return !!sdk && !!session && sessionManager.isSessionValid(session.sessionId);
+  const c = ctx();
+  const session = c.sessions.getCurrentSession();
+  return !!c.sdk && !!session && c.sessions.isSessionValid(session.sessionId);
 }
 
 // =============================================================================
@@ -206,36 +297,37 @@ function realtimeIsHealthy(s: any): boolean {
  * {@link reconnecting} so a parked socket isn't reconnected N times in parallel.
  */
 async function tryRecoverSession(): Promise<boolean> {
-  if (!reconnectResolver) return false;
-  if (!reconnecting) {
-    const resolver = reconnectResolver;
-    reconnecting = (async () => {
+  const c = ctx();
+  if (!c.reconnectResolver) return false;
+  if (!c.reconnecting) {
+    const resolver = c.reconnectResolver;
+    c.reconnecting = (async () => {
       const params = await resolver();
       if (!params?.sandboxId) return; // nothing provisioned this session
       // Close any half-dead socket on the outgoing SDK before replacing it, so a
       // parked-then-rebuilt session doesn't leak an orphaned Ably connection.
       try {
-        sdk?.sandbox?._ably?.close?.();
+        c.sdk?.sandbox?._ably?.close?.();
       } catch {
         /* best effort — reconnectSession installs a fresh SDK regardless */
       }
       await reconnectSession(params);
     })().finally(() => {
-      reconnecting = null;
+      c.reconnecting = null;
     });
   }
   try {
-    await reconnecting;
+    await c.reconnecting;
   } catch (err) {
-    sdk = null;
+    c.sdk = null;
     if (err instanceof NoActiveSessionError) throw err;
     throw new NoActiveSessionError(
       "SESSION_EXPIRED",
       `Could not reconnect to the sandbox: ${err instanceof Error ? err.message : String(err)}. The sandbox has expired — call session_start again to create a new one.`
     );
   }
-  const session = sessionManager.getCurrentSession();
-  return !!sdk && !!session && sessionManager.isSessionValid(session.sessionId);
+  const session = c.sessions.getCurrentSession();
+  return !!c.sdk && !!session && c.sessions.isSessionValid(session.sessionId);
 }
 
 /**
@@ -249,18 +341,19 @@ async function tryRecoverSession(): Promise<boolean> {
  * to recover from.
  */
 async function requireActiveSession(): Promise<void> {
-  const session = sessionManager.getCurrentSession();
+  const c = ctx();
+  const session = c.sessions.getCurrentSession();
 
   // Recoverable conditions:
-  //  - singletons wiped by a host recycle (`!sdk || !session`), or
+  //  - context state wiped by a host recycle (`!sdk || !session`), or
   //  - the SDK exists but its realtime socket died during a park
   //    (`!realtimeIsHealthy`). We only treat a dead socket as recoverable when a
   //    recovery hook is registered — i.e. a durable host (eve) that actually
   //    parks. Long-lived hosts (stdio MCP, CLI) register no resolver, so a
   //    transient in-process Ably blip is left to Ably's own auto-reconnect rather
-  //    than forcing a full singleton rebuild — preserving their prior behavior.
-  const socketDead = !!sdk && !!session && !!reconnectResolver && !realtimeIsHealthy(sdk);
-  const needsRecovery = !sdk || !session || socketDead;
+  //    than forcing a full rebuild — preserving their prior behavior.
+  const socketDead = !!c.sdk && !!session && !!c.reconnectResolver && !realtimeIsHealthy(c.sdk);
+  const needsRecovery = !c.sdk || !session || socketDead;
   if (needsRecovery) {
     const recovered = await tryRecoverSession();
     if (!recovered) {
@@ -268,14 +361,14 @@ async function requireActiveSession(): Promise<void> {
       // If the socket was dead, don't send the action into the void — surface
       // SESSION_EXPIRED so the agent re-provisions instead of hanging.
       if (socketDead) {
-        sdk = null;
+        c.sdk = null;
         throw new NoActiveSessionError(
           "SESSION_EXPIRED",
           "The sandbox connection was lost and could not be restored. Call session_start again to create a new sandbox session.",
           session?.sessionId
         );
       }
-      // Otherwise the singleton was simply absent — the standard NO_SESSION.
+      // Otherwise the SDK was simply absent — the standard NO_SESSION.
       throw new NoActiveSessionError(
         "NO_SESSION",
         "No active session. Call session_start first to create a sandbox before using any other tools."
@@ -283,9 +376,9 @@ async function requireActiveSession(): Promise<void> {
     }
   }
 
-  const current = sessionManager.getCurrentSession();
-  if (!current || !sessionManager.isSessionValid(current.sessionId)) {
-    sdk = null;
+  const current = c.sessions.getCurrentSession();
+  if (!current || !c.sessions.isSessionValid(current.sessionId)) {
+    c.sdk = null;
     throw new NoActiveSessionError(
       "SESSION_EXPIRED",
       "Session has expired or timed out. Call session_start again to create a new sandbox session.",
@@ -294,13 +387,13 @@ async function requireActiveSession(): Promise<void> {
   }
 
   // Reset the keepAlive timer on each command so active use doesn't expire.
-  sessionManager.refreshSession(current.sessionId);
+  c.sessions.refreshSession(current.sessionId);
 }
 
 /** Capture a fresh full-screen screenshot as bare base64 (or null on failure). */
 async function captureScreen(): Promise<string | null> {
   try {
-    const b64 = await sdk.agent.system.captureScreenBase64(1, false, true);
+    const b64 = await ctx().sdk.agent.system.captureScreenBase64(1, false, true);
     return b64 || null;
   } catch {
     return null;
@@ -326,6 +419,7 @@ export async function sessionStart(
   resolved: { os: "linux" | "windows"; e2bTemplateId?: string; apiKey?: string },
   hooks: SessionStartHooks = {}
 ): Promise<ActionResult> {
+  const c = ctx();
   const progress = hooks.onProgress ?? (() => {});
 
   // Validate required fields for specific provision types (unless reconnecting).
@@ -338,7 +432,7 @@ export async function sessionStart(
     }
   }
 
-  const newSession = sessionManager.createSession({
+  const newSession = c.sessions.createSession({
     os: resolved.os,
     keepAlive: params.keepAlive,
     testFile: params.testFile,
@@ -366,7 +460,7 @@ export async function sessionStart(
   }
 
   const TestDriverSDK = (await loadTestDriverSdk()).default;
-  sdk = new TestDriverSDK(apiKey, {
+  c.sdk = new TestDriverSDK(apiKey, {
     os: resolved.os,
     logging: false,
     apiRoot,
@@ -378,13 +472,13 @@ export async function sessionStart(
   // Debug mode — attach to an existing sandbox, skip provisioning.
   if (params.sandboxId) {
     progress(`Connecting to existing sandbox ${params.sandboxId}...`);
-    await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
-    const instance = sdk.getInstance();
-    sessionManager.activateSession(newSession.sessionId, instance?.instanceId || params.sandboxId);
+    await c.sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+    const instance = c.sdk.getInstance();
+    c.sessions.activateSession(newSession.sessionId, instance?.instanceId || params.sandboxId);
 
     progress("Capturing screenshot...");
     const shot = await captureScreen();
-    if (shot) lastScreenshotBase64 = shot;
+    if (shot) c.lastScreenshotBase64 = shot;
 
     return {
       ok: true,
@@ -396,10 +490,10 @@ export async function sessionStart(
   }
 
   progress(instanceIp ? `Connecting to self-hosted instance ${instanceIp}...` : "Connecting to cloud sandbox...");
-  await sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
+  await c.sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
 
-  const instance = sdk.getInstance();
-  sessionManager.activateSession(newSession.sessionId, instance?.instanceId || "unknown");
+  const instance = c.sdk.getInstance();
+  c.sessions.activateSession(newSession.sessionId, instance?.instanceId || "unknown");
 
   const provisionOptions = getProvisionOptions(params);
   let provisionCmd = "";
@@ -407,30 +501,30 @@ export async function sessionStart(
   progress(`Provisioning ${params.type}...`);
   switch (params.type) {
     case "chrome":
-      await sdk.provision.chrome(provisionOptions);
+      await c.sdk.provision.chrome(provisionOptions);
       provisionCmd = "provision.chrome";
       break;
     case "chromeExtension":
-      await sdk.provision.chromeExtension(provisionOptions);
+      await c.sdk.provision.chromeExtension(provisionOptions);
       provisionCmd = "provision.chromeExtension";
       break;
     case "vscode":
-      await sdk.provision.vscode(provisionOptions);
+      await c.sdk.provision.vscode(provisionOptions);
       provisionCmd = "provision.vscode";
       break;
     case "installer":
-      await sdk.provision.installer(provisionOptions);
+      await c.sdk.provision.installer(provisionOptions);
       provisionCmd = "provision.installer";
       break;
     case "electron":
-      await sdk.provision.electron(provisionOptions);
+      await c.sdk.provision.electron(provisionOptions);
       provisionCmd = "provision.electron";
       break;
   }
 
   progress("Capturing screenshot...");
   const shot = await captureScreen();
-  if (shot) lastScreenshotBase64 = shot;
+  if (shot) c.lastScreenshotBase64 = shot;
 
   const debuggerUrl = instance?.debuggerUrl || (instanceIp ? `http://${instanceIp}:9222` : null);
   const connectionType = instanceIp ? `Self-hosted (${instanceIp})` : "Cloud";
@@ -492,17 +586,18 @@ export interface ReconnectParams {
  * knows to call session_start again.
  */
 export async function reconnectSession(params: ReconnectParams): Promise<string> {
+  const c = ctx();
   const apiRoot = params.apiRoot || process.env.TD_API_ROOT || "https://api.testdriver.ai";
   const previewMode = process.env.TD_PREVIEW || "ide";
 
-  const session = sessionManager.createSession({
+  const session = c.sessions.createSession({
     os: params.os,
     keepAlive: params.keepAlive,
     testFile: params.testFile,
   });
 
   const TestDriverSDK = (await loadTestDriverSdk()).default;
-  sdk = new TestDriverSDK(params.apiKey, {
+  c.sdk = new TestDriverSDK(params.apiKey, {
     os: params.os,
     logging: false,
     apiRoot,
@@ -511,9 +606,9 @@ export async function reconnectSession(params: ReconnectParams): Promise<string>
     e2bTemplateId: params.e2bTemplateId,
   });
 
-  await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
-  const instance = sdk.getInstance();
-  sessionManager.activateSession(session.sessionId, instance?.instanceId || params.sandboxId);
+  await c.sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+  const instance = c.sdk.getInstance();
+  c.sessions.activateSession(session.sessionId, instance?.instanceId || params.sandboxId);
   return session.sessionId;
 }
 
@@ -530,9 +625,10 @@ export async function reconnectSession(params: ReconnectParams): Promise<string>
  * them exactly as before.
  */
 export async function ensureActiveSession(params?: ReconnectParams): Promise<boolean> {
-  const session = sessionManager.getCurrentSession();
+  const c = ctx();
+  const session = c.sessions.getCurrentSession();
   // Already have a live SDK + valid session — nothing to do.
-  if (sdk && session && sessionManager.isSessionValid(session.sessionId)) {
+  if (c.sdk && session && c.sessions.isSessionValid(session.sessionId)) {
     return false;
   }
   // No durable handle to recover from — leave the (missing/expired) state as-is
@@ -548,7 +644,7 @@ export async function ensureActiveSession(params?: ReconnectParams): Promise<boo
     // The sandbox is gone (server killed it after grace/disconnect cap, or the
     // id is stale). Surface a SESSION_EXPIRED so the adapter's mapper tells the
     // agent to call session_start again, instead of a raw connect error.
-    sdk = null;
+    c.sdk = null;
     throw new NoActiveSessionError(
       "SESSION_EXPIRED",
       `Could not reconnect to sandbox ${params.sandboxId}: ${err instanceof Error ? err.message : String(err)}. The sandbox has expired — call session_start again to create a new one.`,
@@ -560,18 +656,19 @@ export async function ensureActiveSession(params?: ReconnectParams): Promise<boo
 /** Disconnect the SDK (best-effort); used by adapters on cancel/teardown. */
 export async function disconnect(): Promise<void> {
   try {
-    await sdk?.disconnect?.();
+    await ctx().sdk?.disconnect?.();
   } catch {
     /* best effort */
   }
 }
 
 export function sessionStatus(): ActionResult {
-  const session = sessionManager.getCurrentSession();
+  const c = ctx();
+  const session = c.sessions.getCurrentSession();
   if (!session) {
     return { ok: false, text: "No active session", data: { error: "No active session. Call session_start first." } };
   }
-  const summary = sessionManager.getSessionSummary(session.sessionId);
+  const summary = c.sessions.getSessionSummary(session.sessionId);
   return {
     ok: true,
     text: `Session: ${session.sessionId}\nStatus: ${session.status}\nTime remaining: ${Math.round((summary?.timeRemaining || 0) / 1000)}s`,
@@ -580,10 +677,11 @@ export function sessionStatus(): ActionResult {
 }
 
 export function sessionExtend(additionalMs: number): ActionResult {
-  const session = sessionManager.getCurrentSession();
+  const c = ctx();
+  const session = c.sessions.getCurrentSession();
   if (!session) return { ok: false, text: "No active session", data: { action: "session_extend" } };
-  sessionManager.extendSession(session.sessionId, additionalMs);
-  const newExpiry = sessionManager.getTimeRemaining(session.sessionId);
+  c.sessions.extendSession(session.sessionId, additionalMs);
+  const newExpiry = c.sessions.getTimeRemaining(session.sessionId);
   return {
     ok: true,
     text: `Session extended by ${additionalMs / 1000}s. New expiry: ${Math.round(newExpiry / 1000)}s`,
@@ -597,13 +695,14 @@ export function sessionExtend(additionalMs: number): ActionResult {
 
 export async function find(description: string, timeout?: number): Promise<ActionResult> {
   await requireActiveSession();
-  const element = await sdk.find(description, timeout ? { timeout } : undefined);
+  const c = ctx();
+  const element = await c.sdk.find(description, timeout ? { timeout } : undefined);
   const found = element.found();
   const coords = element.getCoordinates();
 
   const ref = `el-${Date.now()}`;
   if (found && coords) {
-    elementRefs.set(ref, {
+    c.elementRefs.set(ref, {
       element,
       description,
       coords: { x: coords.x, y: coords.y, centerX: coords.centerX, centerY: coords.centerY },
@@ -638,7 +737,8 @@ export async function find(description: string, timeout?: number): Promise<Actio
 
 export async function findAll(description: string, timeout?: number): Promise<ActionResult> {
   await requireActiveSession();
-  const elements = await sdk.findAll(description, timeout ? { timeout } : undefined);
+  const c = ctx();
+  const elements = await c.sdk.findAll(description, timeout ? { timeout } : undefined);
   const count = elements.length;
 
   const refs: string[] = [];
@@ -648,7 +748,7 @@ export async function findAll(description: string, timeout?: number): Promise<Ac
     const coords = el.getCoordinates();
     if (!coords) continue;
     const ref = `el-${Date.now()}-${i}`;
-    elementRefs.set(ref, { element: el, description: `${description} [${i}]`, coords });
+    c.elementRefs.set(ref, { element: el, description: `${description} [${i}]`, coords });
     refs.push(ref);
     elementInfos.push({ ref, x: coords.x, y: coords.y, centerX: coords.centerX, centerY: coords.centerY, confidence: el.confidence });
   }
@@ -685,7 +785,8 @@ async function actOnRef(
   action: "click" | "hover"
 ): Promise<ActionResult> {
   await requireActiveSession();
-  const stored = elementRefs.get(ref);
+  const c = ctx();
+  const stored = c.elementRefs.get(ref);
   if (!stored) {
     return { ok: false, text: `Element reference "${ref}" not found. Use 'find' first to locate the element.`, data: { error: "Element reference not found" } };
   }
@@ -697,7 +798,7 @@ async function actOnRef(
   else if (verb === "hover") await element.hover();
 
   const shot = await captureScreen();
-  if (shot) lastScreenshotBase64 = shot;
+  if (shot) c.lastScreenshotBase64 = shot;
   const data = leanResponse(element._response);
 
   if (action === "hover") {
@@ -727,7 +828,8 @@ export function hover(ref: string): Promise<ActionResult> {
 
 export async function findAndClick(description: string, action: "click" | "double-click" | "right-click" = "click"): Promise<ActionResult> {
   await requireActiveSession();
-  const element = await sdk.find(description);
+  const c = ctx();
+  const element = await c.sdk.find(description);
   const found = element.found();
 
   if (!found) {
@@ -748,7 +850,7 @@ export async function findAndClick(description: string, action: "click" | "doubl
 
   const coords = element.getCoordinates();
   const ref = `el-${Date.now()}`;
-  if (coords) elementRefs.set(ref, { element, description, coords });
+  if (coords) c.elementRefs.set(ref, { element, description, coords });
 
   if (action === "click") await element.click();
   else if (action === "double-click") await element.doubleClick();
@@ -781,7 +883,7 @@ export async function findAndClick(description: string, action: "click" | "doubl
 
 export async function type(text: string, secret = false, delay?: number): Promise<ActionResult> {
   await requireActiveSession();
-  await sdk.type(text, { secret, delay });
+  await ctx().sdk.type(text, { secret, delay });
   return {
     ok: true,
     text: `Typed: ${secret ? "[secret text]" : `"${text}"`}`,
@@ -792,7 +894,7 @@ export async function type(text: string, secret = false, delay?: number): Promis
 
 export async function pressKeys(keys: string[]): Promise<ActionResult> {
   await requireActiveSession();
-  await sdk.pressKeys(keys);
+  await ctx().sdk.pressKeys(keys);
   return {
     ok: true,
     text: `Pressed keys: ${keys.join(" + ")}`,
@@ -803,7 +905,7 @@ export async function pressKeys(keys: string[]): Promise<ActionResult> {
 
 export async function scroll(direction: "up" | "down" | "left" | "right" = "down", amount?: number): Promise<ActionResult> {
   await requireActiveSession();
-  await sdk.scroll(direction, amount ? { amount } : undefined);
+  await ctx().sdk.scroll(direction, amount ? { amount } : undefined);
   return {
     ok: true,
     text: `Scrolled ${direction}${amount ? ` by ${amount}px` : ""}`,
@@ -814,7 +916,7 @@ export async function scroll(direction: "up" | "down" | "left" | "right" = "down
 
 export async function focusApplication(name: string): Promise<ActionResult> {
   await requireActiveSession();
-  await sdk.focusApplication(name);
+  await ctx().sdk.focusApplication(name);
   return {
     ok: true,
     text: `Focused application: "${name}"`,
@@ -825,7 +927,7 @@ export async function focusApplication(name: string): Promise<ActionResult> {
 
 export async function wait(timeout: number): Promise<ActionResult> {
   await requireActiveSession();
-  await sdk.wait(timeout);
+  await ctx().sdk.wait(timeout);
   return {
     ok: true,
     text: `Waited for ${timeout}ms`,
@@ -836,7 +938,7 @@ export async function wait(timeout: number): Promise<ActionResult> {
 
 export async function exec(language: "sh" | "pwsh", code: string, timeout = 30000): Promise<ActionResult> {
   await requireActiveSession();
-  const output = await sdk.exec(language, code, timeout);
+  const output = await ctx().sdk.exec(language, code, timeout);
   return {
     ok: true,
     text: `Executed ${language} code:\n${output || "(no output)"}`,
@@ -851,7 +953,7 @@ export async function exec(language: "sh" | "pwsh", code: string, timeout = 3000
 
 export async function assert(assertion: string): Promise<ActionResult> {
   await requireActiveSession();
-  const result = await sdk.assert(assertion);
+  const result = await ctx().sdk.assert(assertion);
   return {
     ok: result,
     text: result ? `✓ Assertion passed: "${assertion}"` : `✗ Assertion failed: "${assertion}"`,
@@ -867,14 +969,15 @@ export async function assert(assertion: string): Promise<ActionResult> {
  */
 export async function check(task: string, referenceImage?: string): Promise<ActionResult> {
   await requireActiveSession();
-  const currentScreenshot = await sdk.agent.system.captureScreenBase64(1, false, true);
-  const beforeScreenshot = referenceImage || lastScreenshotBase64 || currentScreenshot;
-  lastScreenshotBase64 = currentScreenshot;
+  const c = ctx();
+  const currentScreenshot = await c.sdk.agent.system.captureScreenBase64(1, false, true);
+  const beforeScreenshot = referenceImage || c.lastScreenshotBase64 || currentScreenshot;
+  c.lastScreenshotBase64 = currentScreenshot;
 
-  const mousePosition = await sdk.agent.system.getMousePosition();
-  const activeWindow = await sdk.agent.system.activeWin();
+  const mousePosition = await c.sdk.agent.system.getMousePosition();
+  const activeWindow = await c.sdk.agent.system.activeWin();
 
-  const response = await sdk.agent.sdk.req("check", {
+  const response = await c.sdk.agent.sdk.req("check", {
     tasks: [task],
     images: [beforeScreenshot, currentScreenshot],
     mousePosition,
@@ -899,8 +1002,9 @@ export async function check(task: string, referenceImage?: string): Promise<Acti
 /** Capture a screenshot for the user (cursor visible). */
 export async function screenshot(): Promise<ActionResult> {
   await requireActiveSession();
-  const shot = await sdk.agent.system.captureScreenBase64(1, false, true);
-  if (shot) lastScreenshotBase64 = shot;
+  const c = ctx();
+  const shot = await c.sdk.agent.system.captureScreenBase64(1, false, true);
+  if (shot) c.lastScreenshotBase64 = shot;
   return {
     ok: !!shot,
     text: shot ? "Captured screenshot" : "Failed to capture screenshot",