@testdriverai/mcp 7.11.6-test → 7.11.7-canary

package/mcp-server/dist/core/actions.d.ts

@@ -18,7 +18,7 @@
  * mirroring how the stdio MCP server has always behaved.
  */
 import { SessionStartInputSchema, type SessionStartInput } from "../provision-types.js";
-import { type SessionState } from "../session.js";
+import { SessionManager, type SessionState } from "../session.js";
 export { SessionStartInputSchema, type SessionStartInput };
 export interface ActionImage {
     kind: "screenshot" | "cropped";
@@ -44,14 +44,75 @@ export declare class NoActiveSessionError extends Error {
     constructor(code: "NO_SESSION" | "SESSION_EXPIRED", message: string, expiredSessionId?: string);
 }
 /**
- * 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.
+ * 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 declare function createCoreContext(): CoreContext;
+/**
+ * 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 declare function runInContext<T>(context: CoreContext, fn: () => T): T;
+/** Build an isolated context whose SessionManager is its own (not the global). */
+export declare function createIsolatedContext(): CoreContext;
+/** The active context's adapter scratch space (see {@link CoreContext.adapter}). */
+export declare function getAdapterState(): Record<string, unknown>;
+/** 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 declare function getCurrentSession(): SessionState | null;
+/** Time remaining (ms) on a session in the active context. */
+export declare function getSessionTimeRemaining(sessionId: string): number;
+/**
+ * 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
@@ -60,7 +121,7 @@ export declare class NoActiveSessionError extends Error {
  *
  * 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>;

package/mcp-server/dist/core/actions.js

@@ -17,9 +17,10 @@
  * State is process-global and single-session by design: one sandbox at a time,
  * mirroring how the stdio MCP server has always behaved.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import { generateActionCode } from "../codegen.js";
 import { getProvisionOptions, SessionStartInputSchema } from "../provision-types.js";
-import { sessionManager } from "../session.js";
+import { SessionManager, sessionManager as globalSessionManager } 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.
 export { SessionStartInputSchema };
@@ -34,32 +35,79 @@ export class NoActiveSessionError extends Error {
         this.expiredSessionId = expiredSessionId;
     }
 }
-// =============================================================================
-// Singleton state (single sandbox per process)
-// =============================================================================
-let sdk = null;
-let lastScreenshotBase64 = null;
-let reconnectResolver = null;
+/** Build a fresh, empty context. Callers that want isolation mint one per connection. */
+export function createCoreContext() {
+    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();
+/**
+ * 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 = createCoreContext();
+/** Resolve the active context: the ALS store if one is running, else the global. */
+function ctx() {
+    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(context, fn) {
+    return als.run(context, fn);
+}
+/** Build an isolated context whose SessionManager is its own (not the global). */
+export function createIsolatedContext() {
+    const c = createCoreContext();
+    c.sessions = new SessionManager();
+    return c;
+}
+/** The active context's adapter scratch space (see {@link CoreContext.adapter}). */
+export function getAdapterState() {
+    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() {
+    return ctx().sessions.getCurrentSession();
+}
+/** Time remaining (ms) on a session in the active context. */
+export function getSessionTimeRemaining(sessionId) {
+    return ctx().sessions.getTimeRemaining(sessionId);
+}
 /**
  * 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 = resolver;
+    ctx().reconnectResolver = resolver;
 }
-/** In-flight reconnect, so concurrent actions in one step share one rebuild. */
-let reconnecting = null;
-/** Stored element instances from `find`/`findall`, addressable by ref. */
-const elementRefs = new Map();
 /** Expose internals the adapters legitimately need (read-only intent). */
 export function getSdk() {
-    return sdk;
+    return ctx().sdk;
 }
 export function getLastScreenshotBase64() {
-    return lastScreenshotBase64;
+    return ctx().lastScreenshotBase64;
 }
 export function getElementRef(ref) {
-    return elementRefs.get(ref);
+    return ctx().elementRefs.get(ref);
 }
 /**
  * Cheap, side-effect-free check for a usable in-process session: a live SDK and
@@ -69,8 +117,9 @@ export function getElementRef(ref) {
  * does NOT refresh the keepAlive window — it only reports liveness.
  */
 export function hasLiveSession() {
-    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);
 }
 // =============================================================================
 // Helpers
@@ -144,38 +193,39 @@ function realtimeIsHealthy(s) {
  * {@link reconnecting} so a parked socket isn't reconnected N times in parallel.
  */
 async function tryRecoverSession() {
-    if (!reconnectResolver)
+    const c = ctx();
+    if (!c.reconnectResolver)
         return false;
-    if (!reconnecting) {
-        const resolver = reconnectResolver;
-        reconnecting = (async () => {
+    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);
 }
 /**
  * Validate the active session and auto-extend it (active use keeps it alive),
@@ -188,17 +238,18 @@ async function tryRecoverSession() {
  * to recover from.
  */
 async function requireActiveSession() {
-    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) {
@@ -206,25 +257,25 @@ async function requireActiveSession() {
             // 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.");
         }
     }
-    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.", current?.sessionId);
     }
     // 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() {
     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 {
@@ -237,6 +288,7 @@ async function captureScreen() {
  * neutral result (including the initial screenshot and provision code).
  */
 export async function sessionStart(params, resolved, hooks = {}) {
+    const c = ctx();
     const progress = hooks.onProgress ?? (() => { });
     // Validate required fields for specific provision types (unless reconnecting).
     if (!params.sandboxId) {
@@ -247,7 +299,7 @@ export async function sessionStart(params, resolved, hooks = {}) {
             return { ok: false, text: "electron type requires 'appPath' parameter", data: { error: "Missing required parameter: appPath" } };
         }
     }
-    const newSession = sessionManager.createSession({
+    const newSession = c.sessions.createSession({
         os: resolved.os,
         keepAlive: params.keepAlive,
         testFile: params.testFile,
@@ -272,7 +324,7 @@ export async function sessionStart(params, resolved, hooks = {}) {
         };
     }
     const TestDriverSDK = (await loadTestDriverSdk()).default;
-    sdk = new TestDriverSDK(apiKey, {
+    c.sdk = new TestDriverSDK(apiKey, {
         os: resolved.os,
         logging: false,
         apiRoot,
@@ -283,13 +335,13 @@ export async function sessionStart(params, resolved, hooks = {}) {
     // 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;
+            c.lastScreenshotBase64 = shot;
         return {
             ok: true,
             text: `Connected to existing sandbox (debug mode)\nSession: ${newSession.sessionId}\nSandbox: ${params.sandboxId}\n\nUse find, click, type, etc. to interact.`,
@@ -299,38 +351,38 @@ export async function sessionStart(params, resolved, hooks = {}) {
         };
     }
     progress(instanceIp ? `Connecting to self-hosted instance ${instanceIp}...` : "Connecting to cloud sandbox...");
-    await sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
-    const instance = sdk.getInstance();
-    sessionManager.activateSession(newSession.sessionId, instance?.instanceId || "unknown");
+    await c.sdk.connect({ reconnect: params.reconnect, keepAlive: params.keepAlive, ip: instanceIp });
+    const instance = c.sdk.getInstance();
+    c.sessions.activateSession(newSession.sessionId, instance?.instanceId || "unknown");
     const provisionOptions = getProvisionOptions(params);
     let provisionCmd = "";
     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;
+        c.lastScreenshotBase64 = shot;
     const debuggerUrl = instance?.debuggerUrl || (instanceIp ? `http://${instanceIp}:9222` : null);
     const connectionType = instanceIp ? `Self-hosted (${instanceIp})` : "Cloud";
     return {
@@ -367,15 +419,16 @@ export async function sessionStart(params, resolved, hooks = {}) {
  * knows to call session_start again.
  */
 export async function reconnectSession(params) {
+    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,
@@ -383,9 +436,9 @@ export async function reconnectSession(params) {
         ip: params.ip,
         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;
 }
 /**
@@ -401,9 +454,10 @@ export async function reconnectSession(params) {
  * them exactly as before.
  */
 export async function ensureActiveSession(params) {
-    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
@@ -420,25 +474,26 @@ export async function ensureActiveSession(params) {
         // 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.`, params.sandboxId);
     }
 }
 /** Disconnect the SDK (best-effort); used by adapters on cancel/teardown. */
 export async function disconnect() {
     try {
-        await sdk?.disconnect?.();
+        await ctx().sdk?.disconnect?.();
     }
     catch {
         /* best effort */
     }
 }
 export function sessionStatus() {
-    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`,
@@ -446,11 +501,12 @@ export function sessionStatus() {
     };
 }
 export function sessionExtend(additionalMs) {
-    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`,
@@ -462,12 +518,13 @@ export function sessionExtend(additionalMs) {
 // =============================================================================
 export async function find(description, timeout) {
     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 },
@@ -501,7 +558,8 @@ export async function find(description, timeout) {
 }
 export async function findAll(description, timeout) {
     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 = [];
     const elementInfos = [];
@@ -511,7 +569,7 @@ export async function findAll(description, timeout) {
         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 });
     }
@@ -541,7 +599,8 @@ export async function findAll(description, timeout) {
 // =============================================================================
 async function actOnRef(ref, verb, action) {
     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" } };
     }
@@ -556,7 +615,7 @@ async function actOnRef(ref, verb, action) {
         await element.hover();
     const shot = await captureScreen();
     if (shot)
-        lastScreenshotBase64 = shot;
+        c.lastScreenshotBase64 = shot;
     const data = leanResponse(element._response);
     if (action === "hover") {
         return {
@@ -583,7 +642,8 @@ export function hover(ref) {
 }
 export async function findAndClick(description, action = "click") {
     await requireActiveSession();
-    const element = await sdk.find(description);
+    const c = ctx();
+    const element = await c.sdk.find(description);
     const found = element.found();
     if (!found) {
         const raw = element._response || {};
@@ -605,7 +665,7 @@ export async function findAndClick(description, action = "click") {
     const coords = element.getCoordinates();
     const ref = `el-${Date.now()}`;
     if (coords)
-        elementRefs.set(ref, { element, description, coords });
+        c.elementRefs.set(ref, { element, description, coords });
     if (action === "click")
         await element.click();
     else if (action === "double-click")
@@ -637,7 +697,7 @@ export async function findAndClick(description, action = "click") {
 // =============================================================================
 export async function type(text, secret = false, delay) {
     await requireActiveSession();
-    await sdk.type(text, { secret, delay });
+    await ctx().sdk.type(text, { secret, delay });
     return {
         ok: true,
         text: `Typed: ${secret ? "[secret text]" : `"${text}"`}`,
@@ -647,7 +707,7 @@ export async function type(text, secret = false, delay) {
 }
 export async function pressKeys(keys) {
     await requireActiveSession();
-    await sdk.pressKeys(keys);
+    await ctx().sdk.pressKeys(keys);
     return {
         ok: true,
         text: `Pressed keys: ${keys.join(" + ")}`,
@@ -657,7 +717,7 @@ export async function pressKeys(keys) {
 }
 export async function scroll(direction = "down", amount) {
     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` : ""}`,
@@ -667,7 +727,7 @@ export async function scroll(direction = "down", amount) {
 }
 export async function focusApplication(name) {
     await requireActiveSession();
-    await sdk.focusApplication(name);
+    await ctx().sdk.focusApplication(name);
     return {
         ok: true,
         text: `Focused application: "${name}"`,
@@ -677,7 +737,7 @@ export async function focusApplication(name) {
 }
 export async function wait(timeout) {
     await requireActiveSession();
-    await sdk.wait(timeout);
+    await ctx().sdk.wait(timeout);
     return {
         ok: true,
         text: `Waited for ${timeout}ms`,
@@ -687,7 +747,7 @@ export async function wait(timeout) {
 }
 export async function exec(language, code, timeout = 30000) {
     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)"}`,
@@ -700,7 +760,7 @@ export async function exec(language, code, timeout = 30000) {
 // =============================================================================
 export async function assert(assertion) {
     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}"`,
@@ -715,12 +775,13 @@ export async function assert(assertion) {
  */
 export async function check(task, referenceImage) {
     await requireActiveSession();
-    const currentScreenshot = await sdk.agent.system.captureScreenBase64(1, false, true);
-    const beforeScreenshot = referenceImage || lastScreenshotBase64 || currentScreenshot;
-    lastScreenshotBase64 = currentScreenshot;
-    const mousePosition = await sdk.agent.system.getMousePosition();
-    const activeWindow = await sdk.agent.system.activeWin();
-    const response = await sdk.agent.sdk.req("check", {
+    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 c.sdk.agent.system.getMousePosition();
+    const activeWindow = await c.sdk.agent.system.activeWin();
+    const response = await c.sdk.agent.sdk.req("check", {
         tasks: [task],
         images: [beforeScreenshot, currentScreenshot],
         mousePosition,
@@ -741,9 +802,10 @@ export async function check(task, referenceImage) {
 /** Capture a screenshot for the user (cursor visible). */
 export async function screenshot() {
     await requireActiveSession();
-    const shot = await sdk.agent.system.captureScreenBase64(1, false, true);
+    const c = ctx();
+    const shot = await c.sdk.agent.system.captureScreenBase64(1, false, true);
     if (shot)
-        lastScreenshotBase64 = shot;
+        c.lastScreenshotBase64 = shot;
     return {
         ok: !!shot,
         text: shot ? "Captured screenshot" : "Failed to capture screenshot",