imprint-mcp 0.7.0 → 0.7.2

package/src/imprint/stealth-chromium.ts

@@ -1,5 +1,53 @@
 import { ensurePlaywrightChromiumInstalled } from './chromium.ts';
 
+interface CompatCdpClient {
+  send(method: string, parameters?: unknown): Promise<unknown>;
+}
+interface CompatPage {
+  _client(): CompatCdpClient;
+}
+interface PageSetupPlugin {
+  onPageCreated(page: CompatPage): Promise<void>;
+}
+
+/** Keep a plugin's fire-and-forget CDP calls inside its caught lifecycle hook. */
+export function awaitPluginPageSetup<T extends PageSetupPlugin>(plugin: T): T {
+  const original = plugin.onPageCreated.bind(plugin);
+  plugin.onPageCreated = async (page) => {
+    const commands: Promise<unknown>[] = [];
+    const guardedPage = new Proxy(page, {
+      get(target, property, receiver) {
+        if (property !== '_client') return Reflect.get(target, property, receiver);
+        return () => {
+          const client = target._client();
+          return new Proxy(client, {
+            get(clientTarget, clientProperty, clientReceiver) {
+              if (clientProperty !== 'send')
+                return Reflect.get(clientTarget, clientProperty, clientReceiver);
+              return (method: string, parameters?: unknown) => {
+                const command = clientTarget.send(method, parameters);
+                // Observe immediately, even if the hook yields before it returns.
+                void command.catch(() => {});
+                commands.push(command);
+                return command;
+              };
+            },
+          });
+        };
+      },
+    });
+    try {
+      await original(guardedPage);
+    } finally {
+      await Promise.all(commands);
+    }
+  };
+  return plugin;
+}
+
+let chromiumPromise: Promise<typeof import('playwright').chromium> | undefined;
+let stealthAvailable = false;
+
 /**
  * Shared loader for Playwright's chromium with the stealth plugin applied.
  *
@@ -18,13 +66,30 @@ import { ensurePlaywrightChromiumInstalled } from './chromium.ts';
  * thrown error into their own result shape.
  */
 export async function getStealthChromium(): Promise<typeof import('playwright').chromium> {
+  chromiumPromise ??= loadStealthChromium();
+  return await chromiumPromise;
+}
+
+async function loadStealthChromium(): Promise<typeof import('playwright').chromium> {
   try {
     const pwExtra = await import('playwright-extra');
     const stealthMod = await import('puppeteer-extra-plugin-stealth');
     const stealthFactory =
       (stealthMod as { default?: () => unknown }).default ??
       (stealthMod as unknown as () => unknown);
+    // This upstream evasion does not await client.send. Playwright-extra catches
+    // rejected hook promises, so attach the command to that hook rather than
+    // allowing a browser-close race to become an unhandled rejection.
+    const userAgentModule = await import(
+      // @ts-expect-error The upstream evasion does not publish TypeScript declarations.
+      'puppeteer-extra-plugin-stealth/evasions/user-agent-override/index.js'
+    );
+    const userAgentFactory = userAgentModule.default as (options: unknown) => PageSetupPlugin;
+    pwExtra.chromium.plugins.setDependencyResolution('stealth/evasions/user-agent-override', ((
+      options: unknown,
+    ) => awaitPluginPageSetup(userAgentFactory(options))) as never);
     pwExtra.chromium.use(stealthFactory() as never);
+    stealthAvailable = true;
     return pwExtra.chromium as unknown as typeof import('playwright').chromium;
   } catch {
     const pw = await import('playwright');
@@ -45,13 +110,8 @@ export async function getStealthChromium(): Promise<typeof import('playwright').
  * protection. Import resolution is cached, so probing here is cheap.
  */
 export async function isStealthPluginAvailable(): Promise<boolean> {
-  try {
-    await import('playwright-extra');
-    await import('puppeteer-extra-plugin-stealth');
-    return true;
-  } catch {
-    return false;
-  }
+  await getStealthChromium();
+  return stealthAvailable;
 }
 
 /**

package/src/imprint/teach-browser-resources.ts

@@ -0,0 +1,88 @@
+import type { CdpBrowserFetch } from './cdp-browser-fetch.ts';
+import { abortSignalError, withAbortSignal } from './concurrency.ts';
+
+let previousCheck: Promise<void> = Promise.resolve();
+// The pass owns its pool and drains it on exit. A weak reference lets the host
+// evict an idle pass without extending its lifetime or sharing its browser.
+let retainedPool: WeakRef<Map<string, CdpBrowserFetch>> | undefined;
+const activeBudgetPools = new WeakSet<Map<string, CdpBrowserFetch>>();
+
+/** Evict idle contexts before a transport launches its next browser. Omitting
+ * the key reserves the budget for a transport that does not use the CDP pool. */
+export async function prepareTeachBrowserContext(
+  pool: Map<string, CdpBrowserFetch> | undefined,
+  selectedKey?: string,
+): Promise<void> {
+  if (!pool || !activeBudgetPools.has(pool)) return;
+  const keep = selectedKey === undefined ? undefined : pool.get(selectedKey);
+  const older = new Set<CdpBrowserFetch>();
+  for (const [key, browser] of pool) {
+    if (browser === keep) continue;
+    pool.delete(key);
+    older.add(browser);
+  }
+  await Promise.allSettled([...older].map((browser) => browser.close()));
+}
+
+async function drain(pool: Map<string, CdpBrowserFetch>): Promise<void> {
+  const browsers = [...new Set(pool.values())];
+  pool.clear();
+  await Promise.allSettled(browsers.map((browser) => browser.close()));
+}
+
+async function retainLatestBrowser(pool: Map<string, CdpBrowserFetch>): Promise<void> {
+  const latest = [...pool.entries()].at(-1);
+  if (!latest) return;
+  const older = new Set<CdpBrowserFetch>();
+  for (const [key, browser] of pool) {
+    if (browser === latest[1]) continue;
+    pool.delete(key);
+    older.add(browser);
+  }
+  await Promise.allSettled([...older].map((browser) => browser.close()));
+}
+
+/** Optional host resource limit; agent scheduling and auth checkpoints are unchanged. */
+export async function withTeachBrowserResources<T>(
+  callerPool: Map<string, CdpBrowserFetch> | undefined,
+  signal: AbortSignal | undefined,
+  work: (pool: Map<string, CdpBrowserFetch> | undefined) => Promise<T>,
+): Promise<T> {
+  if (process.env.IMPRINT_TEACH_LOW_MEMORY !== '1') return await work(callerPool);
+
+  const ahead = previousCheck;
+  let release = () => {};
+  const held = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  previousCheck = ahead.then(() => held);
+  const pool = callerPool ?? new Map<string, CdpBrowserFetch>();
+  let admitted = false;
+  let completed = false;
+  try {
+    await withAbortSignal(() => ahead, signal);
+    if (signal?.aborted) throw abortSignalError(signal);
+    admitted = true;
+    const previous = retainedPool?.deref();
+    if (previous && previous !== pool) await drain(previous);
+    retainedPool = undefined;
+    activeBudgetPools.add(pool);
+    const result = await work(pool);
+    completed = true;
+    return result;
+  } finally {
+    try {
+      if (admitted) {
+        activeBudgetPools.delete(pool);
+        if (callerPool && completed && !signal?.aborted) {
+          await retainLatestBrowser(pool);
+          retainedPool = new WeakRef(pool);
+        } else {
+          await drain(pool);
+        }
+      }
+    } finally {
+      release();
+    }
+  }
+}

package/src/imprint/teach-stage-progress.ts

@@ -0,0 +1,38 @@
+/** Keep long agent stages visible without changing their execution or deadline. */
+export async function withTeachStageProgress<T>(
+  options: {
+    label: string;
+    report?: (message: string) => void;
+    intervalMs?: number;
+  },
+  work: () => Promise<T>,
+): Promise<T> {
+  if (!options.report) return await work();
+  const startedAt = performance.now();
+  const elapsed = (): string => {
+    const seconds = Math.floor((performance.now() - startedAt) / 1_000);
+    return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  };
+  const report = (message: string): void => {
+    try {
+      options.report?.(message);
+    } catch {
+      // A diagnostic callback must not interrupt work or replace its error.
+    }
+  };
+  report(`${options.label} started`);
+  const timer = setInterval(
+    () => report(`${options.label} pending (${elapsed()} elapsed)`),
+    options.intervalMs ?? 30_000,
+  );
+  timer.unref();
+  let completed = false;
+  try {
+    const result = await work();
+    completed = true;
+    return result;
+  } finally {
+    clearInterval(timer);
+    report(`${options.label} ${completed ? 'finished' : 'stopped'} (${elapsed()} elapsed)`);
+  }
+}

package/src/imprint/terminal-user-prompt.ts

@@ -0,0 +1,42 @@
+import * as p from '@clack/prompts';
+import { abortSignalError } from './concurrency.ts';
+import { pauseLogsForPrompt } from './log.ts';
+import type { OnUserPrompt } from './user-interaction.ts';
+
+/** The parent terminal owns input; model/stdio child processes never read it. */
+export const terminalUserPrompt: OnUserPrompt = async (prompt, signal) => {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    return {
+      status: 'unavailable',
+      reason:
+        'User input requires an interactive terminal. Run imprint teach without --no-interactive in a terminal, or provide an onPrompt callback.',
+    };
+  }
+  if (signal?.aborted) throw abortSignalError(signal);
+  const resumeLogs = pauseLogsForPrompt();
+  try {
+    const common = {
+      message: prompt.message,
+      signal,
+      input: process.stdin,
+      output: process.stderr,
+    };
+    const answer = prompt.options
+      ? await p.select({
+          ...common,
+          options: prompt.options.map((value) => ({ value, label: value })),
+        })
+      : prompt.sensitive
+        ? await p.password({
+            ...common,
+            validate: (value) => (value?.length ? undefined : 'Enter a value or cancel.'),
+          })
+        : await p.text(common);
+    if (signal?.aborted) throw abortSignalError(signal);
+    if (p.isCancel(answer))
+      return { status: 'cancelled', reason: 'The user cancelled the question.' };
+    return { status: 'answered', value: String(answer) };
+  } finally {
+    resumeLogs();
+  }
+};

package/src/imprint/types.ts

@@ -251,6 +251,9 @@ const BootstrapCaptureSchema = z.discriminatedUnion('source', [
 ]);
 export type BootstrapCapture = z.infer<typeof BootstrapCaptureSchema>;
 
+/** Managed authentication can disable transport retry for an ambiguous dispatch. */
+export type BrowserRequestInit = RequestInit & { allowAmbiguousRetry?: false };
+
 const WorkflowRequestBaseSchema = z.object({
   method: z.string(),
   /** Sequence number of the captured request that grounds this outgoing
@@ -365,6 +368,25 @@ export type NavigationNetworkResponseMatcher = NonNullable<
   NonNullable<WorkflowRequest['navigation']>['networkResponse']
 >;
 
+const AuthOutcomeSchema = z.discriminatedUnion('type', [
+  z
+    .object({
+      type: z.literal('pause'),
+      next: z.string().min(1),
+      resume: z.literal('automatic').optional(),
+      evidence: z.array(z.string().min(1)).optional().default([]),
+      carry: z.array(z.string().min(1)).optional().default([]),
+      message: z.string().min(1),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal('success'),
+      evidence: z.array(z.string().min(1)).optional().default([]),
+    })
+    .strict(),
+]);
+
 const AuthConfigSchema = z
   .object({
     /** Recording-grounded auth program. Action names, boundaries, evidence,
@@ -393,23 +415,13 @@ const AuthConfigSchema = z
                 .strict(),
             )
             .min(1),
-          outcome: z.discriminatedUnion('type', [
-            z
-              .object({
-                type: z.literal('pause'),
-                next: z.string().min(1),
-                evidence: z.array(z.string().min(1)).optional().default([]),
-                carry: z.array(z.string().min(1)).optional().default([]),
-                message: z.string().min(1),
-              })
-              .strict(),
-            z
-              .object({
-                type: z.literal('success'),
-                evidence: z.array(z.string().min(1)).optional().default([]),
-              })
-              .strict(),
-          ]),
+          /** First matching capture against this action's final step response
+           * selects an outcome. A match also supplies the named capture. */
+          branches: z
+            .array(z.object({ when: RequestCaptureSchema, outcome: AuthOutcomeSchema }).strict())
+            .optional(),
+          /** Fallback when no branch matches; its evidence is still required. */
+          outcome: AuthOutcomeSchema,
         })
         .strict(),
     ),
@@ -430,6 +442,10 @@ const AuthConfigSchema = z
   .optional();
 export type AuthConfig = z.infer<typeof AuthConfigSchema>;
 
+export function authActionOutcomes(action: NonNullable<AuthConfig>['actions'][string]) {
+  return [...(action.branches ?? []).map((branch) => branch.outcome), action.outcome];
+}
+
 export function persistedCaptureName(
   config: NonNullable<AuthConfig>,
   credentialName: string,
@@ -538,7 +554,7 @@ export interface StateMissingItem {
  * values, and response content. */
 export interface RequestStageFact {
   requestIndex: number;
-  stage: 'preparation' | 'transform' | 'send';
+  stage: 'preparation' | 'transform' | 'send' | 'capture' | 'repeat' | 'outcome';
   outcome: 'passed' | 'failed' | 'skipped' | 'unavailable';
   /** Final body metadata at this stage. No body bytes are retained. */
   bodyPresent?: boolean;
@@ -547,6 +563,10 @@ export interface RequestStageFact {
   bodyChanged?: boolean;
   /** HTTP status proves transport completed without exposing response content. */
   httpStatus?: number;
+  /** One-based attempt within the declared step; no request or response values. */
+  attempt?: number;
+  stepIndex?: number;
+  transportInvoked?: boolean;
 }
 
 /** Discriminated union returned by every generated tool. */
@@ -582,10 +602,23 @@ export type ToolResult<T = unknown> =
       };
       /** Value-free stage receipts for requests attempted before this failure. */
       requestStageFacts?: RequestStageFact[];
+      /** Exact count plus bounded recent stage facts; retries remain model-authored. */
+      authExecution?: {
+        action: string;
+        stepIndex: number;
+        requestIndex: number;
+        attempts: number;
+        phase: RequestStageFact['stage'];
+        transportInvoked: boolean;
+        responseReceived: boolean;
+        httpStatus?: number;
+        lastFailure?: { error: string; message: string };
+      };
       /** Recording-derived state and generic action progress. Echo this object
        *  unchanged on the next auth call. */
       continuation?: Record<string, unknown>;
       nextAction?: string;
+      resume?: 'automatic';
     };
 
 // ─── Cron config (input to `imprint cron`) ───────────────────────────────────