imprint-mcp 0.6.0 → 0.6.2

package/src/imprint/compile-verification.ts

@@ -0,0 +1,187 @@
+import { randomUUID } from 'node:crypto';
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  openSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join as pathJoin } from 'node:path';
+import { loadBackendsCacheStatus } from './backend-cache.ts';
+import { runWorkflowWithLadder } from './backend-ladder.ts';
+import type { CredentialStore } from './runtime.ts';
+import { WorkflowSchema } from './types.ts';
+
+export const LIVE_EVIDENCE_PATH_ENV = 'IMPRINT_LIVE_EVIDENCE_PATH';
+export const LIVE_PREFERRED_BACKEND_ONLY_ENV = 'IMPRINT_LIVE_PREFERRED_BACKEND_ONLY';
+
+type WorkflowParams = Record<string, string | number | boolean>;
+type LadderRun = Awaited<ReturnType<typeof runWorkflowWithLadder>>;
+
+export interface LiveIntegrationEvidence {
+  schemaVersion: 1;
+  kind: 'call';
+  label: string;
+  caseName: string;
+  toolName: string;
+  requestedParams: WorkflowParams;
+  effectiveParams: WorkflowParams;
+  result: LadderRun['result'];
+  usedBackend: LadderRun['usedBackend'];
+  attempts: LadderRun['attempts'];
+  durationMs: number;
+}
+
+function scalarDefaults(parameters: Array<{ name: string; default?: unknown }>): WorkflowParams {
+  const defaults: WorkflowParams = {};
+  for (const parameter of parameters) {
+    const value = parameter.default;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      defaults[parameter.name] = value;
+    }
+  }
+  return defaults;
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function acquireSiteLiveLock(workflowPath: string): Promise<() => void> {
+  const siteDir = dirname(dirname(workflowPath));
+  const lockPath = pathJoin(siteDir, '.imprint-live-verification.lock');
+  const deadline = Date.now() + 10 * 60_000;
+
+  while (Date.now() < deadline) {
+    try {
+      const fd = openSync(lockPath, 'wx');
+      writeFileSync(fd, JSON.stringify({ pid: process.pid, createdAt: Date.now() }));
+      closeSync(fd);
+      return () => {
+        try {
+          unlinkSync(lockPath);
+        } catch {
+          // Best effort: a later acquisition can clean up a stale lock.
+        }
+      };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'EEXIST') throw error;
+      try {
+        const current = JSON.parse(readFileSync(lockPath, 'utf8')) as {
+          pid?: number;
+          createdAt?: number;
+        };
+        const stale =
+          typeof current.pid === 'number'
+            ? !processIsAlive(current.pid)
+            : Date.now() - (current.createdAt ?? 0) > 10 * 60_000;
+        if (stale) {
+          unlinkSync(lockPath);
+          continue;
+        }
+      } catch {
+        try {
+          // Another process can observe the lock between exclusive creation
+          // and the tiny metadata write. Never delete a fresh, partially
+          // written lock; only reap malformed metadata after a long stale age.
+          if (Date.now() - statSync(lockPath).mtimeMs > 10 * 60_000) {
+            unlinkSync(lockPath);
+            continue;
+          }
+        } catch {
+          // Another process may have released/replaced the lock. Retry below.
+        }
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  }
+  throw new Error(`Timed out waiting for same-site live verification lock: ${lockPath}`);
+}
+
+/**
+ * Compile-only wrapper around the backend ladder. Production generated tools do
+ * not use this function. During `imprint teach`, it captures the actual tool
+ * input and parsed result for an independent semantic verifier.
+ */
+export async function runCapturedIntegrationCase(opts: {
+  caseName: string;
+  workflowPath: string;
+  params: WorkflowParams;
+  credentials?: CredentialStore;
+  /** Final semantic verification pins the cache winner so a failed preferred
+   * backend becomes explicit reprobe feedback instead of a hidden ladder walk. */
+  preferredOnlyBackend?: boolean;
+}): Promise<LadderRun> {
+  const workflow = WorkflowSchema.parse(JSON.parse(readFileSync(opts.workflowPath, 'utf8')));
+  const release = await acquireSiteLiveLock(opts.workflowPath);
+  const startedAt = Date.now();
+  let run: LadderRun;
+  try {
+    let forceBackend: LadderRun['usedBackend'] | undefined;
+    if (opts.preferredOnlyBackend || process.env[LIVE_PREFERRED_BACKEND_ONLY_ENV] === '1') {
+      const toolDir = dirname(opts.workflowPath);
+      const status = loadBackendsCacheStatus(
+        workflow.site ?? '',
+        dirname(dirname(toolDir)),
+        toolDir,
+        { warn: false, toolName: workflow.toolName },
+      );
+      forceBackend = status.status === 'ok' ? status.cache.preferredOrder[0] : undefined;
+      if (!forceBackend) {
+        throw new Error(
+          `Live verifier backend is not prepared for ${workflow.toolName}; call prepare_live_backend before running the suite.`,
+        );
+      }
+    }
+    run = await runWorkflowWithLadder({
+      workflowPath: opts.workflowPath,
+      params: opts.params,
+      credentials: opts.credentials,
+      forceBackend,
+    });
+  } finally {
+    release();
+  }
+
+  const evidencePath = process.env[LIVE_EVIDENCE_PATH_ENV];
+  if (evidencePath) {
+    const evidence: LiveIntegrationEvidence = {
+      schemaVersion: 1,
+      kind: 'call',
+      label: `${opts.caseName}:${randomUUID().slice(0, 8)}`,
+      caseName: opts.caseName,
+      toolName: workflow.toolName,
+      requestedParams: opts.params,
+      effectiveParams: { ...scalarDefaults(workflow.parameters), ...opts.params },
+      result: run.result,
+      usedBackend: run.usedBackend,
+      attempts: run.attempts,
+      durationMs: Date.now() - startedAt,
+    };
+    appendFileSync(evidencePath, `${JSON.stringify(evidence)}\n`, { mode: 0o600 });
+  }
+  return run;
+}
+
+export function readLiveIntegrationEvidence(path: string): LiveIntegrationEvidence[] {
+  if (!existsSync(path)) return [];
+  const evidence: LiveIntegrationEvidence[] = [];
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    const parsed = JSON.parse(line) as LiveIntegrationEvidence;
+    if (parsed.schemaVersion !== 1 || parsed.kind !== 'call' || !parsed.label || !parsed.toolName) {
+      throw new Error('invalid live integration evidence record');
+    }
+    evidence.push(parsed);
+  }
+  return evidence;
+}

package/src/imprint/compile.ts

@@ -66,6 +66,10 @@ interface CompileOptions {
    *  skips its own triageRequests() LLM call and merges the shared selectedSeqs
    *  with any per-tool preserveSeqs locally. */
   preTriagedSession?: TriageResult;
+  /** Authoritative, post-verification workflow contract. Playbook compilation
+   *  uses this instead of re-inferring the public parameter surface from the
+   *  recording candidate. */
+  workflow?: Workflow;
 }
 
 // ─── generate (workflow.json) ────────────────────────────────────────────────
@@ -93,6 +97,8 @@ interface GenerateOptions extends CompileOptions {
    *  response parsing, shared-module imports). Injected into the agent's initial
    *  message so the compile follows it. */
   toolPlan?: string;
+  /** Bounded teach resume: revise the current artifact from durable feedback. */
+  revisionMode?: boolean;
 }
 
 interface GenerateResult {
@@ -136,6 +142,7 @@ export async function generate(opts: GenerateOptions): Promise<GenerateResult> {
         buildPlanPath: opts.buildPlanPath,
         sharedModules: opts.sharedModules,
         toolPlan: opts.toolPlan,
+        revisionMode: opts.revisionMode,
       });
 
       setSpanAttributes(span, {
@@ -216,6 +223,10 @@ function relocateGeneratedWorkflow(workflowPath: string, workflow: Workflow): st
     '.compile-log.json',
     '.compile-done.json',
     '.compile-give-up.json',
+    '.live-verifier-log.jsonl',
+    '.live-verification-evidence.json',
+    '.live-verification.json',
+    'backends.json',
   ]) {
     const source = pathJoin(sourceDir, artifact);
     if (!existsSync(source)) continue;
@@ -791,10 +802,18 @@ async function compilePlaybookImpl(opts: CompileOptions): Promise<CompilePlayboo
     `compiling playbook from ${session.events.length} events / ${xhrs.length} XHRs / ${session.narration.length} narration lines…`,
   );
 
+  const workflowContract = opts.workflow
+    ? {
+        toolName: opts.workflow.toolName,
+        parameters: opts.workflow.parameters,
+        limitations: opts.workflow.limitations ?? [],
+      }
+    : undefined;
   const slimmed = {
     site: session.site,
     url: compactUrlForLlm(session.url),
     candidate: opts.candidate,
+    workflowContract,
     sharedContext: opts.sharedContext,
     narration: session.narration,
     events: session.events,
@@ -812,6 +831,10 @@ async function compilePlaybookImpl(opts: CompileOptions): Promise<CompilePlayboo
     opts.candidate
       ? `\n\nCandidate scope:\nCompile only this candidate: ${JSON.stringify(opts.candidate, null, 2)}\nShared context: ${JSON.stringify(opts.sharedContext ?? {}, null, 2)}\nThe playbook toolName and parameters must match the selected candidate/workflow, not any other action in the recording.\n`
       : ''
+  }${
+    workflowContract
+      ? `\n\nAuthoritative verified workflow contract:\n${JSON.stringify(workflowContract, null, 2)}\nThis contract supersedes candidate likelyParams and raw recording branches. Use exactly these public parameters. Never resurrect an omitted parameter or reference it in a step. When a limitation omits a recorded branch, leave that branch out of the playbook and retain the limitation in notes if useful.\n`
+      : ''
   }`;
 
   const llm = resolveProvider(opts.llmConfig ?? {});
@@ -825,13 +848,21 @@ async function compilePlaybookImpl(opts: CompileOptions): Promise<CompilePlayboo
   for (let attempt = 0; attempt < 2; attempt++) {
     try {
       playbook = parsePlaybook(stripCodeFences(lastResult.text).trim());
+      if (opts.workflow) {
+        const contractFailures = playbookWorkflowContractFailures(playbook, opts.workflow);
+        if (contractFailures.length > 0) {
+          throw new Error(
+            `playbook conflicts with the authoritative verified workflow contract:\n- ${contractFailures.join('\n- ')}`,
+          );
+        }
+      }
       lastErr = undefined;
       break;
     } catch (err) {
       lastErr = err;
       if (attempt === 0) {
-        log('playbook YAML failed to parse, retrying with error feedback…');
-        const fixPrompt = `Your previous output was invalid YAML. The parser error was:\n\n${err instanceof Error ? err.message : String(err)}\n\nFix the YAML and return the corrected playbook. Output ONLY valid YAML, no prose.`;
+        log('playbook failed validation, retrying with error feedback…');
+        const fixPrompt = `Your previous playbook was invalid. The validation error was:\n\n${err instanceof Error ? err.message : String(err)}\n\nReason about the verified workflow contract, fix the YAML, and return the corrected playbook. Output ONLY valid YAML, no prose.`;
         lastResult = await llm.analyze(systemPrompt, `${JSON.stringify(slimmed)}\n\n${fixPrompt}`);
         llmInputTokens = addNullable(llmInputTokens, lastResult.inputTokens);
         llmOutputTokens = addNullable(llmOutputTokens, lastResult.outputTokens);
@@ -868,6 +899,44 @@ async function compilePlaybookImpl(opts: CompileOptions): Promise<CompilePlayboo
   };
 }
 
+/**
+ * Check only the compatibility boundary required for API→playbook fallback.
+ * The playbook agent remains free to choose DOM actions and locators, but it
+ * cannot change the verified public tool surface or depend on hidden inputs.
+ */
+export function playbookWorkflowContractFailures(playbook: Playbook, workflow: Workflow): string[] {
+  const failures: string[] = [];
+  if (playbook.toolName !== workflow.toolName) {
+    failures.push(
+      `toolName ${JSON.stringify(playbook.toolName)} must equal ${JSON.stringify(workflow.toolName)}`,
+    );
+  }
+
+  const workflowNames = new Set(workflow.parameters.map((parameter) => parameter.name));
+  const playbookNames = new Set(playbook.parameters.map((parameter) => parameter.name));
+  const missing = [...workflowNames].filter((name) => !playbookNames.has(name)).sort();
+  const unexpected = [...playbookNames].filter((name) => !workflowNames.has(name)).sort();
+  if (missing.length > 0) {
+    failures.push(`missing public parameter(s): ${missing.join(', ')}`);
+  }
+  if (unexpected.length > 0) {
+    failures.push(`unexpected parameter(s): ${unexpected.join(', ')}`);
+  }
+
+  const hiddenReferences = new Set<string>();
+  const executableText = JSON.stringify({ steps: playbook.steps, result: playbook.result });
+  for (const match of executableText.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g)) {
+    const name = match[1];
+    if (name && !workflowNames.has(name)) hiddenReferences.add(name);
+  }
+  if (hiddenReferences.size > 0) {
+    failures.push(
+      `step/result references hidden parameter(s): ${[...hiddenReferences].sort().join(', ')}`,
+    );
+  }
+  return failures;
+}
+
 function addNullable(a: number | null, b: number | null): number | null {
   if (a === null && b === null) return null;
   return (a ?? 0) + (b ?? 0);

package/src/imprint/credential-store.ts

@@ -120,12 +120,8 @@ class KeyringBackend implements CredentialBackend {
 
   async getSecret(site: string, name: string): Promise<string | null> {
     const entry = new this.Entry(SERVICE_NAME, this.accountFor(site, name));
-    try {
-      const v = entry.getPassword();
-      return typeof v === 'string' && v.length > 0 ? v : null;
-    } catch {
-      return null;
-    }
+    const v = entry.getPassword();
+    return typeof v === 'string' && v.length > 0 ? v : null;
   }
 
   async setSecret(site: string, name: string, value: string): Promise<void> {
@@ -135,11 +131,7 @@ class KeyringBackend implements CredentialBackend {
 
   async deleteSecret(site: string, name: string): Promise<void> {
     const entry = new this.Entry(SERVICE_NAME, this.accountFor(site, name));
-    try {
-      entry.deletePassword();
-    } catch {
-      // Already absent — fine.
-    }
+    entry.deletePassword();
   }
 
   async listSecrets(site: string): Promise<string[]> {
@@ -157,23 +149,15 @@ class KeyringBackend implements CredentialBackend {
 
   async getCookies(site: string): Promise<CookieRecord[]> {
     const entry = new this.Entry(SERVICE_NAME, this.cookieAccount(site));
-    try {
-      const v = entry.getPassword();
-      if (typeof v !== 'string' || v.length === 0) return [];
-      return JSON.parse(v) as CookieRecord[];
-    } catch {
-      return [];
-    }
+    const v = entry.getPassword();
+    if (typeof v !== 'string' || v.length === 0) return [];
+    return JSON.parse(v) as CookieRecord[];
   }
 
   async setCookies(site: string, cookies: CookieRecord[]): Promise<void> {
     const entry = new this.Entry(SERVICE_NAME, this.cookieAccount(site));
     if (cookies.length === 0) {
-      try {
-        entry.deletePassword();
-      } catch {
-        /* ignore */
-      }
+      entry.deletePassword();
       return;
     }
     entry.setPassword(JSON.stringify(cookies));
@@ -181,23 +165,15 @@ class KeyringBackend implements CredentialBackend {
 
   async getStorage(site: string): Promise<StorageRecord[]> {
     const entry = new this.Entry(SERVICE_NAME, this.storageAccount(site));
-    try {
-      const v = entry.getPassword();
-      if (typeof v !== 'string' || v.length === 0) return [];
-      return JSON.parse(v) as StorageRecord[];
-    } catch {
-      return [];
-    }
+    const v = entry.getPassword();
+    if (typeof v !== 'string' || v.length === 0) return [];
+    return JSON.parse(v) as StorageRecord[];
   }
 
   async setStorage(site: string, storage: StorageRecord[]): Promise<void> {
     const entry = new this.Entry(SERVICE_NAME, this.storageAccount(site));
     if (storage.length === 0) {
-      try {
-        entry.deletePassword();
-      } catch {
-        /* ignore */
-      }
+      entry.deletePassword();
       return;
     }
     entry.setPassword(JSON.stringify(storage));
@@ -713,19 +689,56 @@ export async function saveSiteCookies(site: string, cookies: CookieRecord[]): Pr
   await backend.setCookies(site, cookies);
 }
 
-/** Convenience wrapper to persist browser storage (localStorage/sessionStorage)
- *  after a successful auth tool run, so a later stateless `submit_otp` call can
- *  rehydrate the same session state. Delegates to the backend's optional
- *  setStorage; no-ops on backends that don't support storage. */
+/** Persist browser storage through the active credential backend. */
 export async function saveSiteStorage(site: string, storage: StorageRecord[]): Promise<void> {
   const backend = await getCredentialBackend();
   await backend.setStorage?.(site, storage);
 }
 
-/** Persist a single durable secret value (e.g. a bearer/access token captured
- *  from a completed login via authConfig.sessionCapture) so data tools reuse it
- *  as `${credential.NAME}` without re-running auth. */
-export async function saveSiteSecret(site: string, name: string, value: string): Promise<void> {
+/** Replace the durable auth material as one logical commit. Backends such as
+ * the OS keyring do not expose transactions, so restore the complete prior
+ * snapshot if any write fails rather than leaving mixed-session state. */
+export async function commitSiteAuthState(
+  site: string,
+  cookies: CookieRecord[],
+  secrets: Record<string, string>,
+): Promise<void> {
   const backend = await getCredentialBackend();
-  await backend.setSecret(site, name, value);
+  const previousCookies = await backend.getCookies(site);
+  const previousSecrets = new Map<string, string | null>();
+  for (const name of Object.keys(secrets)) {
+    previousSecrets.set(name, await backend.getSecret(site, name));
+  }
+
+  try {
+    await backend.setCookies(site, cookies);
+    for (const [name, value] of Object.entries(secrets)) {
+      await backend.setSecret(site, name, value);
+    }
+  } catch (err) {
+    const rollbackFailures: string[] = [];
+    try {
+      await backend.setCookies(site, previousCookies);
+    } catch (rollbackErr) {
+      rollbackFailures.push(
+        `cookies: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
+      );
+    }
+    for (const [name, value] of previousSecrets) {
+      try {
+        if (value === null) await backend.deleteSecret(site, name);
+        else await backend.setSecret(site, name, value);
+      } catch (rollbackErr) {
+        rollbackFailures.push(
+          `${name}: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
+        );
+      }
+    }
+    const original = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      rollbackFailures.length > 0
+        ? `${original}; rollback also failed for ${rollbackFailures.join(', ')}`
+        : original,
+    );
+  }
 }

package/src/imprint/emit.ts

@@ -107,6 +107,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import {
   executeWorkflow,
+  type BrowserNavigationTransport,
   type CredentialStore,
 } from 'imprint/runtime';
 import type { ToolResult, Workflow } from 'imprint/types';
@@ -119,7 +120,7 @@ ${paramTypeFields}
 
 export async function ${camelCase(workflow.toolName)}(
   ${workflow.parameters.length === 0 ? '_input' : 'input'}: ${pascalCase(workflow.toolName)}Input,
-  opts: { credentials?: CredentialStore; fetchImpl?: typeof fetch; initialState?: Record<string, unknown> } = {},
+  opts: { credentials?: CredentialStore; fetchImpl?: typeof fetch; browser?: BrowserNavigationTransport; initialState?: Record<string, unknown> } = {},
 ): Promise<ToolResult> {
   const __dirname = dirname(fileURLToPath(import.meta.url));
   const params: Record<string, string | number | boolean> = {
@@ -131,6 +132,7 @@ ${defaultsBlock && requiredCopies ? requiredCopies : ''}
     params,
     credentials: opts.credentials,
     fetchImpl: opts.fetchImpl,
+    browser: opts.browser,
     initialState: opts.initialState,
     workflowPath: join(__dirname, 'workflow.json'),
   });

package/src/imprint/freeform-redact.ts

@@ -123,6 +123,14 @@ const PROTECTED_PATTERNS = [
   /\b[0-9a-f]{40}\b/gi,
 ];
 
+// UUIDs and 40-hex identifiers are normally protected from generic secret
+// heuristics because they are common, benign IDs in recorded payloads. When
+// the same shapes occur immediately in an authentication context, however,
+// that context is the useful signal: redact only the value while continuing to
+// preserve identical bare IDs elsewhere.
+const CONTEXTUAL_PROTECTED_SECRET_RE =
+  /(\b(?:authorization|proxy-authorization)\b["']?\s*[:=]\s*["']?(?:bearer\s+)?|\bbearer\s+|\b(?:oauth(?:2)?(?:[_ -]?access)?[_ -]?token|access[_ -]?token)\b["']?\s*[:=]\s*["']?)([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[0-9a-f]{40})(?=["'\s,;&)}\]]|$)/gi;
+
 const REDACTOR = createRedactum({
   policies: FREEFORM_POLICIES,
   replacement: () => '[REDACTED]',
@@ -145,24 +153,37 @@ export function redactFreeformText(text: string): FreeformRedaction {
     return { redacted: text, redactionsCount: 0 };
   }
 
-  const protectedRanges = collectProtectedRanges(text);
+  let contextualRedactions = 0;
+  const contextuallyRedacted = text.replace(
+    CONTEXTUAL_PROTECTED_SECRET_RE,
+    (_match, prefix: string) => {
+      contextualRedactions++;
+      return `${prefix}[REDACTED]`;
+    },
+  );
+
+  const protectedRanges = collectProtectedRanges(contextuallyRedacted);
   if (protectedRanges.length === 0) {
-    return redactUnprotectedText(text);
+    const result = redactUnprotectedText(contextuallyRedacted);
+    return {
+      redacted: result.redacted,
+      redactionsCount: contextualRedactions + result.redactionsCount,
+    };
   }
 
   let redacted = '';
   let cursor = 0;
-  let redactionsCount = 0;
+  let redactionsCount = contextualRedactions;
   for (const range of protectedRanges) {
-    const segment = text.slice(cursor, range.start);
+    const segment = contextuallyRedacted.slice(cursor, range.start);
     const segmentResult = redactUnprotectedText(segment);
     redacted += segmentResult.redacted;
     redactionsCount += segmentResult.redactionsCount;
-    redacted += text.slice(range.start, range.end);
+    redacted += contextuallyRedacted.slice(range.start, range.end);
     cursor = range.end;
   }
 
-  const tail = redactUnprotectedText(text.slice(cursor));
+  const tail = redactUnprotectedText(contextuallyRedacted.slice(cursor));
   redacted += tail.redacted;
   redactionsCount += tail.redactionsCount;