imprint-mcp 0.7.1 → 0.7.2

package/README.md

@@ -34,6 +34,8 @@ renewed cookies for later calls without overwriting newer saved authentication.
 Same-name host-only and domain cookies keep their distinct scopes across replay
 and browser restoration.
 That continuity still needs verification against the requested data operation.
+Local stdio MCP servers can opt in to [session renewal](docs/getting-started.md#renew-authenticated-mcp-sessions)
+for read-only tools, with client approval before sending a new sign-in challenge.
 
 ## Quick Start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Teach an AI agent how to use any website. Once. Records a real browser session + narration; generates a deterministic MCP tool plus a DOM-replay playbook fallback.",
   "type": "module",
   "exports": {

package/prompts/auth-compile-agent.md

@@ -217,6 +217,12 @@ semantics.
   Verify the session-reuse path and each login/MFA path actually offered by the
   observed flow separately. Do not restart login just to repeat an already
   passing reuse check, and do not claim an untested branch works.
+- For a pause during managed MCP recovery, use `resume: "automatic"` only if the next action can begin
+  without waiting for input through the auth tool. A bounded poll for an
+  already sent approval request can start while the user approves it with the
+  provider. Keep each new approval request in its own action and classify
+  its dispatch effect. The MCP host asks for consent before unsafe actions.
+  After handing off to the auth tool, callers follow one declared action per call.
 - `persist` names durable credential interfaces that data tools consume later as
   `${credential.NAME}`. Cookies persist automatically. These interface names do
   not constrain your internal capture names. When they differ, set

package/src/imprint/backend-ladder.ts

@@ -350,6 +350,8 @@ export async function runWithLadder(
     /** Per-site CDP browser pool so cdp-replay reuses a live Chrome across
      *  calls (~2-5s) instead of launching a fresh one each time (~33s). */
     cdpPool?: Map<string, CdpBrowserFetch>;
+    /** A managed continuation must use the browser that produced it. */
+    authBrowser?: CdpBrowserFetch;
     /** Per-session memo of the backend that last served each tool. Once set, the
      *  next call starts at that backend instead of re-walking the doomed early
      *  rungs — the runtime analog of the compile path's `compileWinningBackend`.
@@ -492,6 +494,7 @@ export async function runWithLadder(
             options?.signal,
             options?.onResponse ? onResponse : undefined,
             options?.onPreparedRequest ? onPreparedRequest : undefined,
+            options?.authBrowser,
           );
           break;
         case 'stealth-fetch': {
@@ -1131,6 +1134,7 @@ async function runCdpReplay(
   signal?: AbortSignal,
   onResponse?: (observation: ResponseObservation) => void,
   onPreparedRequest?: (observation: PreparedRequestObservation) => void,
+  authBrowser?: CdpBrowserFetch,
 ): Promise<ToolResult> {
   const credentials = credentialOverride ??
     (await loadCredentialStore(tool.site, signal)) ?? {
@@ -1162,7 +1166,31 @@ async function runCdpReplay(
       .update(bootstrapUrl ?? baseUrl)
       .digest('hex'),
   );
-  const poolKey = cdpReplayPoolKey(tool.site, tool.workflow.toolName, bootstrapUrl ?? baseUrl);
+  const pinned =
+    authBrowser && cdpPool
+      ? [...cdpPool].find(([, browser]) => browser === authBrowser)?.[0]
+      : undefined;
+  if (authBrowser && pinned === undefined) {
+    return {
+      ok: false,
+      error: 'AUTH_EXPIRED',
+      message: 'The browser for this sign-in has closed.',
+    };
+  }
+  const requestedKey = cdpReplayPoolKey(tool.site, tool.workflow.toolName, bootstrapUrl ?? baseUrl);
+  if (
+    pinned &&
+    pinned !== requestedKey &&
+    tool.workflow.bootstrap?.captures?.some((capture) => capture.source !== 'cookie')
+  ) {
+    return {
+      ok: false,
+      error: 'STATE_MISSING',
+      message:
+        'This sign-in action needs captures from a different bootstrap page. Use standalone sign-in.',
+    };
+  }
+  const poolKey = pinned ?? requestedKey;
   if (tool.workflow.toolKind !== 'authenticate') await prepareTeachBrowserContext(cdpPool, poolKey);
   if (signal?.aborted) throw abortSignalError(signal);
   const credentialHash = credentialStateHash(credentials);
@@ -1247,8 +1275,11 @@ async function runCdpReplay(
     if (cdpPool) cdpPool.set(poolKey, cf);
   }
 
+  // Existing callers keep their normal timing. Managed auth owns this browser
+  // and closes it when the recovery deadline or client cancellation fires.
+  const authSignal = credentials.authCommitRevision === undefined ? undefined : signal;
   try {
-    const jar = await cf.mintJar();
+    const jar = await withAbortSignal(() => cf.mintJar(), authSignal);
     if (signal?.aborted) throw abortSignalError(signal);
     const observedCookies = jar.cookies.map((c) => ({
       name: c.name,
@@ -1283,16 +1314,26 @@ async function runCdpReplay(
       return captureResult.result;
     }
 
+    const navigate = cf.navigate?.bind(cf);
+    const snapshotCookies = cf.snapshotCookies?.bind(cf);
+    const fetchImpl: typeof fetch = authSignal
+      ? Object.assign(
+          (input: Parameters<typeof fetch>[0], init?: RequestInit) =>
+            withAbortSignal(() => cf.fetchImpl(input, init), authSignal),
+          { preconnect: cf.fetchImpl.preconnect },
+        )
+      : cf.fetchImpl;
     let runtimeCookies: CredentialStore['cookies'] | undefined;
     let result = await tool.toolFn(paramsWithDefaults, {
       credentials: bootstrappedCredentials,
       initialState: { ...callerState, ...captureResult.state },
-      fetchImpl: cf.fetchImpl,
+      fetchImpl,
       browser:
-        cf.navigate && cf.snapshotCookies
+        navigate && snapshotCookies
           ? {
-              navigate: cf.navigate.bind(cf),
-              snapshotCookies: cf.snapshotCookies.bind(cf),
+              navigate: (...args: Parameters<NonNullable<CdpBrowserFetch['navigate']>>) =>
+                withAbortSignal(() => navigate(...args), authSignal),
+              snapshotCookies: () => withAbortSignal(snapshotCookies, authSignal),
               initialCookies: observedCookies,
             }
           : undefined,
@@ -1327,9 +1368,10 @@ async function runCdpReplay(
     }
     if (jarLikelyStale(result)) clearJar(cacheDir);
     if (result.ok) {
+      if (authSignal) return result;
       if (cdpPool && ownsSession) cdpPool.set(poolKey, cf);
       try {
-        const postJar = await cf.mintJar();
+        const postJar = await withAbortSignal(() => cf.mintJar(), authSignal);
         recordBrowserCookieState(
           { ...credentials, cookies: postJar.cookies },
           'cdp-after-request',
@@ -1390,14 +1432,16 @@ async function runCdpReplay(
       // A paused auth action is healthy progress. Retain the browser so the next
       // declared action sees the same cookies, page, and browser-owned state.
       if (ownsSession) cdpPool.set(poolKey, cf);
-      try {
-        const postJar = await cf.mintJar();
-        saveJar(cacheDir, { ...postJar, credentialStateHash: credentialHash });
-      } catch (err) {
-        clearJar(cacheDir);
-        log(
-          `cdp-replay paused cookie snapshot unavailable: ${err instanceof Error ? err.message : String(err)}`,
-        );
+      if (credentials.authCommitRevision === undefined) {
+        try {
+          const postJar = await cf.mintJar();
+          saveJar(cacheDir, { ...postJar, credentialStateHash: credentialHash });
+        } catch (err) {
+          clearJar(cacheDir);
+          log(
+            `cdp-replay paused cookie snapshot unavailable: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
       }
       // Deliberately do NOT close cf — the pool retains it for the completion phase.
     } else if (cdpPool) {

package/src/imprint/cdp-browser-fetch.ts

@@ -45,6 +45,7 @@ import {
 } from './chromium.ts';
 import { recordBrowserCredentialObservation } from './credential-observation.ts';
 import { createLog } from './log.ts';
+import type { BrowserRequestInit } from './types.ts';
 import type { NavigationNetworkResponseMatcher } from './types.ts';
 
 const log = createLog('cdp-browser');
@@ -1106,6 +1107,7 @@ export function buildInPageFetchExpr(
   body: string | null,
   reqTimeoutMs: number,
   sameOriginIframeSrc?: string,
+  allowAmbiguousRetry = true,
 ): string {
   const iframeNativeFetchSetup = `
           ifr = document.createElement('iframe');
@@ -1157,10 +1159,12 @@ export function buildInPageFetchExpr(
           if (ifr) try { ifr.remove(); } catch (_) {}
           return { ok: false, error: String(e) };
         }`;
+  const primarySetup =
+    !allowAmbiguousRetry && !sameOriginIframeSrc ? iframeNativeFetchSetup : iframeSetup;
   return `(async () => {
-      const primary = await (async () => {${fetchOnce(iframeSetup)}
+      const primary = await (async () => {${fetchOnce(primarySetup)}
       })();
-      if (${sameOriginIframeSrc ? 'false' : 'true'} && !primary.ok) {
+      if (${allowAmbiguousRetry && !sameOriginIframeSrc} && !primary.ok) {
         const fallback = await (async () => {${fetchOnce(iframeNativeFetchSetup)}
         })();
         return JSON.stringify(fallback);
@@ -1258,10 +1262,12 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
   const activeNetworkBodyReads = new Set<Promise<void>>();
   let finishActiveNetworkResponse: ((requestId: string) => void) | undefined;
   let navigationInProgress = false;
+  let lifecycle = 0;
   let discoveryRequested = false;
   let discovery: AuthBrowserDiscovery | undefined;
 
   async function close(): Promise<void> {
+    lifecycle++;
     discovery?.close();
     discovery = undefined;
     const c = client;
@@ -1300,6 +1306,10 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
 
   async function ensure(): Promise<CdpClient> {
     if (client && bootstrapped) return client;
+    const startedIn = lifecycle;
+    const checkOpen = () => {
+      if (lifecycle !== startedIn) throw new Error('Browser closed during CDP startup.');
+    };
     try {
       const headed = opts.headed ?? false;
       if (!chrome) {
@@ -1309,24 +1319,52 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
         // Page.navigate AFTER the override rather than passing the URL at launch.
         // headless renders offscreen (no display); headed needs one (Xvfb on Linux).
         const launch = chromiumLauncherForTest ?? launchChromium;
-        chrome = await withTimeout(
+        const launched = await withTimeout<LaunchedChromium>(
           launch({
             headless: !headed,
             extraArgs: gpuLaunchArgs(),
             ...(headed ? { display: opts.display } : {}),
+          }).then(async (launched) => {
+            // Closing a late handle rejects readiness even if no caller adopted it.
+            void launched.ready.catch(() => {});
+            if (lifecycle === startedIn) return launched;
+            await launched.close();
+            throw new Error('Browser closed during Chromium launch.');
           }),
           'Chromium launch',
           cdpCommandTimeoutMs,
         );
-        await withTimeout(chrome.ready, 'Chromium CDP readiness', cdpCommandTimeoutMs);
+        // Close can run after the launch promise resolves and before this await
+        // resumes. Keep the handle local until ownership has been checked.
+        if (lifecycle !== startedIn) {
+          await launched.close();
+          checkOpen();
+        }
+        chrome = launched;
+        await withTimeout(launched.ready, 'Chromium CDP readiness', cdpCommandTimeoutMs);
+        checkOpen();
         // Register the Chrome PID for exit-time cleanup (leak prevention for
         // probe subprocesses that exit before the idle-close timer fires).
         if (chrome.process.pid !== undefined) __registerChromePid(chrome.process.pid);
       }
       if (!client) {
         const connectCdp = cdpConnectorForTest ?? ((port: number) => CDP({ port }));
-        client = await withTimeout(connectCdp(chrome.port), 'CDP connect', cdpCommandTimeoutMs);
+        const connected = await withTimeout<CdpClient>(
+          connectCdp(chrome.port).then(async (connected) => {
+            if (lifecycle === startedIn) return connected;
+            await connected.close();
+            throw new Error('Browser closed during CDP connect.');
+          }),
+          'CDP connect',
+          cdpCommandTimeoutMs,
+        );
+        if (lifecycle !== startedIn) {
+          await connected.close();
+          checkOpen();
+        }
+        client = connected;
       }
+      checkOpen();
       const { Runtime, Network, Input, Page } = client;
       await withTimeout(Runtime.enable(), 'CDP Runtime.enable', cdpCommandTimeoutMs);
       await withTimeout(Network.enable(), 'CDP Network.enable', cdpCommandTimeoutMs);
@@ -1685,10 +1723,11 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
         i++;
       }
       log(`_abck status after interaction: ~${status}~`);
+      checkOpen();
       bootstrapped = true;
       return client;
     } catch (err) {
-      await close();
+      if (lifecycle === startedIn) await close();
       throw err;
     }
   }
@@ -1713,7 +1752,7 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
 
   const fetchImpl: typeof fetch = (async (
     input: string | URL | Request,
-    init?: RequestInit,
+    init?: BrowserRequestInit,
   ): Promise<Response> => {
     const c = await ensure();
     const url =
@@ -1766,6 +1805,7 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
         body,
         reqTimeoutMs,
         sameOriginIframeSrc,
+        init?.allowAmbiguousRetry,
       );
       const { result } = await withTimeout(
         c.Runtime.evaluate({
@@ -1908,6 +1948,9 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
             headers: new Headers(payload.headers),
           });
         }
+        if (init?.allowAmbiguousRetry === false) {
+          throw new Error('The browser could not confirm the request outcome. No retry was sent.');
+        }
         // The in-page sibling fetch failed — almost always a genuine CORS block
         // (the page can't read the cross-origin response). Fall back to plain
         // fetch so the request still goes out (it just won't carry the live

package/src/imprint/credential-lock.ts

@@ -95,6 +95,7 @@ export async function withCredentialLock<T>(
   directory: string,
   signal: AbortSignal | undefined,
   work: () => Promise<T>,
+  pollMs = 20,
 ): Promise<T> {
   signal?.throwIfAborted();
   mkdirSync(directory, { recursive: true, mode: 0o700 });
@@ -123,7 +124,7 @@ export async function withCredentialLock<T>(
             (other.ticket === owner.ticket && other.nonce < nonce)),
       );
       if (!ahead) break;
-      await abortableDelay(20, signal);
+      await abortableDelay(pollMs, signal);
     }
     signal?.throwIfAborted();
     result = await work();

package/src/imprint/credential-store.ts

@@ -694,6 +694,7 @@ export interface SiteCredentialView {
   storage: StorageRecord[];
   /** Raw durable material identity, before runtime normalization or env input. */
   revision: string;
+  legacy?: true;
 }
 
 function credentialRevision(material: Omit<SiteCredentialView, 'revision'>): string {
@@ -739,6 +740,34 @@ async function withSiteCredentialLock<T>(
   });
 }
 
+/** Serializes a complete sign-in independently of the credential reads and commits it performs. */
+export async function acquireSiteAuthRecoveryLock(
+  site: string,
+  signal: AbortSignal,
+): Promise<() => Promise<void>> {
+  signal.throwIfAborted();
+  const backend = await getCredentialBackend();
+  const directory = pathJoin(
+    `${credentialLockDirectory(site, backend)}-auth-recovery`,
+    createHash('sha256').update(site).digest('hex'),
+  );
+  return new Promise((resolve, reject) => {
+    const held = withCredentialLock(
+      directory,
+      signal,
+      () =>
+        new Promise<void>((release) => {
+          resolve(() => {
+            release();
+            return held;
+          });
+        }),
+      250,
+    );
+    void held.catch(reject);
+  });
+}
+
 /** Loads everything we know about a site, falling back through the backends.
  *  Used at request time by runtime.executeWorkflow. */
 export async function loadSiteCredentials(
@@ -779,7 +808,7 @@ async function loadSiteCredentialsUnlocked(
         values: legacy.values,
         storage: [],
       });
-      const result = { ...material, revision: credentialRevision(material) };
+      const result = { ...material, revision: credentialRevision(material), legacy: true as const };
       const observation = credentialObservation(result, 'legacy-json');
       if (observation) recordCredentialEvent('load', observation);
       return result;
@@ -881,14 +910,22 @@ export async function commitSiteAuthState(
   site: string,
   cookies: CookieRecord[],
   secrets: Record<string, string>,
-  options?: { signal?: AbortSignal },
+  options?: { signal?: AbortSignal; expectedRevision?: string },
 ): Promise<void> {
   const signal = options?.signal;
   await withSiteCredentialLock(site, signal, async (backend) => {
     signal?.throwIfAborted();
+    let nextSecrets = secrets;
+    if (options?.expectedRevision !== undefined) {
+      const current = await loadSiteCredentialsUnlocked(site, backend);
+      if (current.revision !== options.expectedRevision) {
+        throw new Error('the saved session changed while this sign-in was running');
+      }
+      if (current.legacy) nextSecrets = { ...current.values, ...secrets };
+    }
     const previousCookies = structuredClone(await backend.getCookies(site));
     const previousSecrets = new Map<string, string | null>();
-    for (const name of Object.keys(secrets)) {
+    for (const name of Object.keys(nextSecrets)) {
       signal?.throwIfAborted();
       previousSecrets.set(name, await backend.getSecret(site, name));
     }
@@ -897,7 +934,7 @@ export async function commitSiteAuthState(
       signal?.throwIfAborted();
       await backend.setCookies(site, cookies);
       signal?.throwIfAborted();
-      for (const [name, value] of Object.entries(secrets)) {
+      for (const [name, value] of Object.entries(nextSecrets)) {
         await backend.setSecret(site, name, value);
         signal?.throwIfAborted();
       }

package/src/imprint/mcp-cdp-sessions.ts

@@ -19,7 +19,11 @@ export class McpCdpSessions {
     }
   }
 
-  finishCall(site: string, toolName: string): void {
+  finishCall(
+    site: string,
+    toolName: string,
+    onIdle?: (browser: CdpBrowserFetch, closing: Promise<void>) => void,
+  ): void {
     this.beginCall(site, toolName);
     const prefix = cdpReplayPoolKey(site, toolName, '');
     for (const [key, session] of this.pool) {
@@ -29,7 +33,8 @@ export class McpCdpSessions {
         if (this.pool.get(key) !== session) return;
         this.pool.delete(key);
         this.winners.delete(`${site}:${toolName}`);
-        void session.close().catch(() => {});
+        const closing = session.close().catch(() => {});
+        onIdle?.(session, closing);
       }, this.idleMs);
       timer.unref();
       this.timers.set(key, timer);