imprint-mcp 0.7.0 → 0.7.2

package/src/imprint/chromium.ts

@@ -6,12 +6,15 @@ import { type ChildProcess, spawnSync as nodeSpawnSync, spawn } from 'node:child
 import {
   closeSync,
   existsSync,
+  mkdtempSync,
   openSync,
   readFileSync,
   readdirSync,
+  rmSync,
   statSync,
   unlinkSync,
 } from 'node:fs';
+import { rm } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { createServer } from 'node:net';
 import { homedir, tmpdir } from 'node:os';
@@ -26,6 +29,7 @@ import { isDebug } from './log.ts';
  *  Chrome-launch module, a dependency leaf) rather than in backend-ladder so the
  *  ladder→cdp-browser-fetch import does not form a cycle. */
 const chromeProcessPids = new Set<number>();
+const chromeTemporaryProfiles = new Map<number, string>();
 
 /** Register a Chrome PID for exit-time cleanup. Called on launch. */
 export function __registerChromePid(pid: number): void {
@@ -47,8 +51,16 @@ process.on('exit', () => {
   for (const pid of chromeProcessPids) {
     try {
       process.kill(pid, 'SIGKILL');
-    } catch {
-      // Already dead or not owned by this process — ignore.
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ESRCH') continue;
+    }
+    const profile = chromeTemporaryProfiles.get(pid);
+    if (profile) {
+      try {
+        rmSync(profile, { recursive: true, force: true });
+      } catch {
+        // A forced host exit cannot await cleanup; normal close reports errors.
+      }
     }
   }
 });
@@ -556,17 +568,18 @@ async function pickFreePort(): Promise<number> {
   });
 }
 
-async function waitForCdp(port: number, timeoutMs = 10_000): Promise<void> {
+async function waitForCdp(port: number, timeoutMs = 10_000, signal?: AbortSignal): Promise<void> {
   const deadline = Date.now() + timeoutMs;
   let lastError: unknown;
   while (Date.now() < deadline) {
+    signal?.throwIfAborted();
     try {
-      const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+      const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal });
       if (res.ok) return;
     } catch (err) {
       lastError = err;
     }
-    await sleep(100);
+    await sleep(100, undefined, { signal });
   }
   throw new Error(
     `Chromium did not open CDP on port ${port} within ${timeoutMs}ms (${String(lastError)})`,
@@ -578,8 +591,9 @@ export async function launchChromium(opts: LaunchOptions = {}): Promise<Launched
     log: (message) => process.stderr.write(`[imprint] ${message}\n`),
   }).path;
   const port = opts.port ?? (await pickFreePort());
+  const ownsProfile = opts.userDataDir === undefined;
   const userDataDir =
-    opts.userDataDir ?? pathJoin(tmpdir(), `imprint-chrome-${Date.now()}-${process.pid}`);
+    opts.userDataDir ?? mkdtempSync(pathJoin(tmpdir(), `imprint-chrome-${process.pid}-`));
 
   const args = [
     `--remote-debugging-port=${port}`,
@@ -614,38 +628,88 @@ export async function launchChromium(opts: LaunchOptions = {}): Promise<Launched
   let xvfb: XvfbHandle | undefined;
   let display = opts.display ?? process.env.DISPLAY;
   if (process.platform === 'linux' && !opts.headless && !display) {
-    xvfb = await startXvfb();
-    display = xvfb.display;
+    try {
+      xvfb = await startXvfb();
+      display = xvfb.display;
+    } catch (error) {
+      if (ownsProfile) await rm(userDataDir, { recursive: true, force: true });
+      throw error;
+    }
   }
 
-  const child = spawn(exe, args, {
-    stdio: ['ignore', 'ignore', 'pipe'],
-    detached: false,
-    env: display ? { ...process.env, DISPLAY: display } : process.env,
-  });
+  let child: ChildProcess;
+  try {
+    child = spawn(exe, args, {
+      stdio: ['ignore', 'ignore', 'pipe'],
+      detached: false,
+      env: display ? { ...process.env, DISPLAY: display } : process.env,
+    });
+  } catch (error) {
+    await xvfb?.close().catch(() => {});
+    if (ownsProfile) await rm(userDataDir, { recursive: true, force: true });
+    throw error;
+  }
+  if (child.pid !== undefined) {
+    __registerChromePid(child.pid);
+    if (ownsProfile) chromeTemporaryProfiles.set(child.pid, userDataDir);
+  }
 
   // Chromium is noisy — only surface stderr under IMPRINT_DEBUG.
   if (isDebug()) {
     child.stderr?.on('data', (chunk) => process.stderr.write(chunk));
   }
 
-  const ready = waitForCdp(port);
-
-  let closed = false;
-  const close = async (): Promise<void> => {
-    if (closed) return;
-    closed = true;
-    if (child.exitCode === null && child.signalCode === null) {
-      child.kill('SIGTERM');
-      await Promise.race([
-        new Promise<void>((resolve) => child.once('exit', () => resolve())),
-        sleep(2000),
-      ]);
-      if (child.exitCode === null) child.kill('SIGKILL');
-    }
-    // Tear down the virtual display we started for this launch (if any).
-    await xvfb?.close().catch(() => {});
+  const startup = new AbortController();
+  let stopped = false;
+  let spawnError: Error | undefined;
+  const exit = Promise.withResolvers<void>();
+  let closing: Promise<void> | undefined;
+  const close = (): Promise<void> => {
+    closing ??= (async () => {
+      startup.abort(new Error('Chromium closed before CDP became ready'));
+      if (!stopped) {
+        child.kill('SIGTERM');
+        await Promise.race([exit.promise, sleep(2000)]);
+        if (!stopped) {
+          child.kill('SIGKILL');
+          await Promise.race([exit.promise, sleep(2000)]);
+        }
+      }
+      await xvfb?.close().catch(() => {});
+      if (!stopped) throw new Error('Chromium did not exit; preserving its profile');
+      if (ownsProfile) await rm(userDataDir, { recursive: true, force: true });
+      if (child.pid !== undefined) {
+        chromeTemporaryProfiles.delete(child.pid);
+        __unregisterChromePid(child.pid);
+      }
+    })();
+    return closing;
   };
+  child.once('error', (error) => {
+    spawnError = error;
+    if (child.pid === undefined) {
+      stopped = true;
+      exit.resolve();
+    }
+    startup.abort(error);
+  });
+  child.once('exit', () => {
+    stopped = true;
+    if (child.pid !== undefined) __unregisterChromePid(child.pid);
+    exit.resolve();
+    void close().catch((error) => {
+      process.stderr.write(`[imprint] browser cleanup: ${String(error)}\n`);
+    });
+  });
+  const ready = Promise.race([
+    waitForCdp(port, 10_000, startup.signal),
+    exit.promise.then(() => {
+      throw spawnError ?? new Error('Chromium exited before CDP became ready');
+    }),
+  ]).catch(async (error) => {
+    await close();
+    throw error;
+  });
 
   return { process: child, port, userDataDir, ready, close };
 }

package/src/imprint/claude-cli-compile.ts

@@ -85,6 +85,8 @@ const MAX_VERIFICATION_CYCLES = 5;
 /** Data-compile tools exposed to claude-cli. Keep this list in one exported
  * place so tests catch prompt/tool drift before a real teach run does. */
 export const DATA_COMPILE_TOOL_NAMES = [
+  'prompt_user',
+  'authenticate',
   'read_session_summary',
   'search_requests',
   'read_request',

package/src/imprint/codex-cli-compile.ts

@@ -1,5 +1,7 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { randomUUID } from 'node:crypto';
+import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+import { AuthToolPlanSchema } from './auth-plan.ts';
+import { createCompileToolExecutor } from './compile-tool-executor.ts';
 import { currentNativeTeachAgents } from './native-teach-agents.ts';
 import { SHARED_RESEARCH_INSTRUCTIONS } from './teach-research-memory.ts';
 /**
@@ -12,17 +14,14 @@ import { SHARED_RESEARCH_INSTRUCTIONS } from './teach-research-memory.ts';
  */
 
 import type { ChildProcess } from 'node:child_process';
-import {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { isAbsolute as pathIsAbsolute, join as pathJoin } from 'node:path';
 import { type Span, context as otelContext } from '@opentelemetry/api';
-import type { AuthCliCompileMode } from './auth-compile-tools.ts';
+import {
+  AUTH_CHECKPOINT_TOOLS,
+  type AuthCliCompileMode,
+  parseAuthCheckpoint,
+} from './auth-compile-tools.ts';
 import { type SharedModuleManifestEntry, resolvePlanSliceFromFile } from './build-plan.ts';
 import type {
   AuthCheckpoint,
@@ -43,7 +42,7 @@ import {
   watchCompileProviderDeadline,
 } from './compile-provider-control.ts';
 import type { CompileStrategyKind } from './compile-strategy.ts';
-import { recordCompilerHostError } from './compiler-log.ts';
+import { compilerToolFailure, recordCompilerHostError } from './compiler-log.ts';
 import {
   collectOwnedProcess,
   spawnOwnedProcess,
@@ -392,28 +391,30 @@ Use the imprint-compile MCP tools to inspect the session, write artifacts, run t
 
   const family = currentNativeTeachAgents();
   if (family) {
-    const client = new Client({ name: 'imprint-native-compiler', version: '1.0.0' });
-    const providerControl = createCompileProviderControl(runDeadline ?? opts.deadlineMs);
-    const env = Object.fromEntries(
-      Object.entries({ ...process.env, ...providerControl.env }).filter(
-        (entry): entry is [string, string] =>
-          entry[0] !== 'IMPRINT_TEACH_CREDENTIALS' && entry[1] !== undefined,
-      ),
+    const executor = createCompileToolExecutor(
+      {
+        sessionPath: sessionPathAbs,
+        toolDir: opts.absoluteToolDir,
+        site: opts.authMode?.site,
+        authToolPlan: opts.authMode
+          ? AuthToolPlanSchema.parse(JSON.parse(opts.authMode.authPlanJson))
+          : undefined,
+        provider: 'codex-cli',
+        candidate: opts.candidate,
+        sharedContext: opts.sharedContext,
+        buildPlanPath: opts.buildPlanPath,
+        sharedModules: opts.sharedModules,
+        strategyKind: opts.strategyKind,
+        revisionMode: opts.revisionMode,
+        verificationMode: opts.verificationMode,
+        sharedTriageSelection: opts.sharedTriageSelection,
+      },
+      { session: opts.session, signal: opts.signal, runDeadline },
     );
-    const transport = new StdioClientTransport({
-      env,
-      command: bunPath,
-      args: mcpArgs,
-      cwd: opts.absoluteToolDir,
-      stderr: 'pipe',
-    });
     const conversationLogPath = pathJoin(opts.absoluteToolDir, '.compile-log.json');
     const events: unknown[] = existsSync(conversationLogPath)
       ? JSON.parse(readFileSync(conversationLogPath, 'utf8'))
       : [];
-    transport.stderr?.on('data', (chunk) =>
-      appendFileSync(pathJoin(opts.absoluteToolDir, '.native-mcp-stderr.log'), chunk),
-    );
     const sharedResearch = family.sharedResearch
       ? {
           runId: family.sharedResearch.runId,
@@ -428,30 +429,83 @@ Use the imprint-compile MCP tools to inspect the session, write artifacts, run t
       ? `${SHARED_RESEARCH_INSTRUCTIONS}\n${JSON.stringify({ sharedResearch })}\nUse the native shared_research tool with this exchange schema to publish/query findings; do not embed publications in your final compiler summary.\n`
       : '';
     try {
-      await client.connect(transport);
       const response = await family.submit(
-        `${sharedPrompt}${initialPrompt}\n\nNative compiler: use list_assignment_tools and call_assignment_tool for this assignment in place of direct imprint-compile MCP names. All writes and tests must go through those tools. After done, give_up, or an auth checkpoint returns, submit a short summary to the host and stop this turn. Native subagents can assist with independent implementation questions; retain separate workspaces and do not substitute their prose for test evidence.`,
+        `${sharedPrompt}${initialPrompt}\n\nNative compiler: use list_assignment_tools and call_assignment_tool for this assignment in place of direct imprint-compile MCP names. All writes and tests must go through those tools. ${opts.authMode?.executeCheckpoint ? 'Auth host tools execute inline: await each verification, browser operation, human question, or cooldown result and continue this same assignment. Submit a short summary only after done or give_up returns.' : 'After done, give_up, or a recorded auth checkpoint returns, submit a short summary to the host and stop this turn.'} Native subagents can assist with independent implementation questions; retain separate workspaces and do not substitute their prose for test evidence.`,
         {
           // The family already scopes this key to the run. Revision directories
           // change; the public tool's retained compiler conversation must not.
           conversation: `compiler:${opts.candidate?.toolName ?? opts.absoluteToolDir}`,
+          contextRef: opts.authMode?.contextRef,
           signal: opts.signal,
-          call: async (name, args) => {
-            const result =
-              name === '__list'
-                ? await client.listTools()
-                : await client.callTool({ name, arguments: args }, undefined, {
-                    signal: opts.signal,
-                    timeout: MAX_MCP_TOOL_TIMEOUT_SEC * 1000,
-                  });
-            events.push({ timestamp: new Date().toISOString(), name, args, result });
-            writeFileSync(conversationLogPath, JSON.stringify(events), { mode: 0o600 });
-            return result;
+          call: async (name, args, requestSignal) => {
+            const signal = requestSignal ?? opts.signal;
+            const requestId = randomUUID();
+            const started = performance.now();
+            const save = () =>
+              writeFileSync(conversationLogPath, JSON.stringify(events), { mode: 0o600 });
+            events.push({
+              type: 'tool.started',
+              timestamp: new Date().toISOString(),
+              name,
+              requestId,
+            });
+            save();
+            let failure: ReturnType<typeof compilerToolFailure> | undefined;
+            let result: CallToolResult | { tools: Tool[] };
+            try {
+              if (name === '__list') {
+                const listed = { tools: executor.tools };
+                result = opts.authMode?.executeCheckpoint
+                  ? {
+                      ...listed,
+                      tools: listed.tools.map((tool) => {
+                        const checkpoint = AUTH_CHECKPOINT_TOOLS.find(
+                          (definition) => definition.name === tool.name,
+                        );
+                        return checkpoint
+                          ? {
+                              ...tool,
+                              description: `${checkpoint.description} Await the host result and continue in this same assignment.`,
+                            }
+                          : tool;
+                      }),
+                    }
+                  : listed;
+              } else if (
+                opts.authMode?.executeCheckpoint &&
+                AUTH_CHECKPOINT_TOOLS.some((tool) => tool.name === name)
+              ) {
+                const executed = await opts.authMode.executeCheckpoint(
+                  parseAuthCheckpoint(name, args),
+                  signal,
+                );
+                result = {
+                  content: [{ type: 'text', text: executed.result }],
+                  ...(executed.isError ? { isError: true } : {}),
+                };
+              } else {
+                result = await executor.callTool(name, args, signal);
+              }
+              events.push({ timestamp: new Date().toISOString(), name, args, result });
+              return result;
+            } catch (error) {
+              failure = compilerToolFailure(error);
+              throw error;
+            } finally {
+              events.push({
+                type: 'tool.settled',
+                timestamp: new Date().toISOString(),
+                name,
+                requestId,
+                durationMs: performance.now() - started,
+                status: signal?.aborted ? 'cancelled' : failure ? 'threw' : 'returned',
+                ...(failure ? { error: failure } : {}),
+              });
+              save();
+            }
           },
         },
       );
-      const interruption = providerControl.interruption();
-      if (interruption) throw compileProviderInterruptionError(interruption);
       events.push({ type: 'native.completed', ...response });
       writeFileSync(conversationLogPath, JSON.stringify(events), { mode: 0o600 });
       return completedCompileResult(opts, {
@@ -477,8 +531,7 @@ Use the imprint-compile MCP tools to inspect the session, write artifacts, run t
         ),
       });
     } finally {
-      providerControl.dispose();
-      await client.close();
+      await executor.close();
     }
   }
 

package/src/imprint/compile-agent-types.ts

@@ -7,6 +7,7 @@
  */
 
 import type { AgentProgress } from './agent.ts';
+import type { AuthBrowserAction } from './auth-browser-discovery.ts';
 import { type AssignedSharedModule, describeAssignedModules } from './build-plan.ts';
 import type { ProviderInterruptionReason, ProviderReportedError } from './provider-retry.ts';
 import type { SharedCompileContext, ToolCandidate } from './tool-candidates.ts';
@@ -123,12 +124,10 @@ export interface CompileAgentProgress extends AgentProgress {
   };
 }
 
-/** A mid-loop checkpoint the auth compile agent reaches: it calls a checkpoint
- *  tool (which writes a sentinel) and then STOPS its turn. The orchestrator
- *  (teach) performs the action — it owns the live browser session, the TUI, and
- *  the cooldown — then resumes the agent (`claude --resume`) with the result as a
- *  follow-up user message. Site/channel-agnostic. */
+/** A host operation shared by inline native/API tools and CLI checkpoint/resume.
+ * The host owns the browser, prompt references, and declared continuation. */
 export type AuthCheckpoint =
+  | ({ kind: 'interact_verification_browser' } & AuthBrowserAction)
   | {
       kind: 'run_verification';
       action: string;
@@ -144,6 +143,11 @@ export type AuthCheckpoint =
   | { kind: 'prompt_user'; message: string; options?: string[] }
   | { kind: 'wait_for_cooldown'; minutes: number; reason?: string };
 
+export interface AuthCheckpointResult {
+  result: string;
+  isError?: boolean;
+}
+
 export interface CompileAgentResult {
   /** True only if external verification passed. */
   success: boolean;

package/src/imprint/compile-agent.ts

@@ -16,6 +16,7 @@ import {
   giveUpTool,
   runAgentLoop,
 } from './agent.ts';
+import { attachRecordedAuthentication } from './authentication-interaction.ts';
 import { type SharedModuleManifestEntry, resolvePlanSliceFromFile } from './build-plan.ts';
 import { compileViaClaudeCli } from './claude-cli-compile.ts';
 import { compileViaCodexCli } from './codex-cli-compile.ts';
@@ -70,6 +71,12 @@ import {
   minimalSharedTriageSelection,
 } from './triage-selection.ts';
 import { type Session, SessionSchema, WorkflowSchema } from './types.ts';
+import {
+  type OnUserPrompt,
+  UserInteraction,
+  currentUserInteraction,
+  withUserInteraction,
+} from './user-interaction.ts';
 
 export type { CompileAgentProgress } from './compile-agent-types.ts';
 
@@ -105,6 +112,7 @@ function removeEphemeralTests(toolDir: string): void {
 }
 
 interface CompileAgentOptions {
+  onPrompt?: OnUserPrompt;
   /** Path to the recorded session JSON (absolute or relative). */
   sessionPath: string;
   /** Hard wall-clock budget. Default 20 minutes. */
@@ -172,6 +180,11 @@ function formatRevisionMode(enabled: boolean | undefined): string {
 }
 
 export async function compileAgent(opts: CompileAgentOptions): Promise<CompileAgentResult> {
+  if (!currentUserInteraction()) {
+    return await withUserInteraction(new UserInteraction(opts.onPrompt, opts.signal), () =>
+      compileAgent(opts),
+    );
+  }
   const startTime = Date.now();
   // Build-plan fields are bounded proposals for the compile/master agents.
   const { assignedSharedModules } = resolvePlanSliceFromFile(
@@ -192,6 +205,12 @@ export async function compileAgent(opts: CompileAgentOptions): Promise<CompileAg
     'session',
   );
 
+  const extractedAuthValues = Object.fromEntries(
+    extractCredentials(session).replacements.flatMap(({ originalValue, placeholder }) => {
+      const match = /^\$\{credential\.([^}]+)\}$/.exec(placeholder);
+      return match?.[1] ? [[match[1], originalValue]] : [];
+    }),
+  );
   // 2. Auto-redact raw direct-generate inputs. Teach normally supplies an
   // already-redacted focused recording.
   const looksRedacted = JSON.stringify(session).includes('[REDACTED:');
@@ -265,6 +284,7 @@ export async function compileAgent(opts: CompileAgentOptions): Promise<CompileAg
       sharedModules: opts.sharedModules,
       strategyKind: opts.strategyKind,
       revisionMode: opts.revisionMode,
+      signal: opts.signal,
     }),
     doneTool(),
     giveUpTool(),
@@ -289,6 +309,19 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
     opts.deadlineMs ?? Date.now() + (opts.maxDurationMs ?? 20 * 60 * 1000),
   );
 
+  if (!currentUserInteraction()?.hasAuthentication) {
+    currentUserInteraction()?.setRunControl(runDeadline, opts.onDeadlineReached);
+    attachRecordedAuthentication({
+      session,
+      sessionPath: sessionPathAbs,
+      root: pathJoin(absoluteToolDir, '.authentication'),
+      values: { ...extractedAuthValues, ...opts.teachCredentials?.values },
+      llmConfig: opts.llmConfig,
+      runDeadline,
+      report: log,
+    });
+  }
+
   // 8. Instantiate provider (or use injected one for testing).
   //    CLI providers take a different path: they don't implement Anthropic
   //    messageWithTools, so we shell out with the same toolset registered as a