imprint-mcp 0.6.6 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +278 -16
  3. package/package.json +2 -2
  4. package/prompts/audit-agent.md +25 -4
  5. package/prompts/auth-compile-agent.md +28 -12
  6. package/prompts/build-planning.md +3 -3
  7. package/prompts/compile-agent.md +895 -180
  8. package/prompts/live-verifier-agent.md +10 -3
  9. package/prompts/master-teach-api-researcher.md +813 -0
  10. package/prompts/master-teach-baseline-mvp-review.md +217 -0
  11. package/prompts/master-teach-completion-review.md +188 -0
  12. package/prompts/master-teach-decision.md +885 -0
  13. package/prompts/master-teach-focused-planner.md +764 -0
  14. package/prompts/master-teach-parameter-advisor.md +58 -0
  15. package/prompts/master-teach-recording-evidence.md +19 -0
  16. package/prompts/master-teach-refine-plan.md +7 -0
  17. package/prompts/master-teach-tool-advisor.md +130 -0
  18. package/prompts/playbook-compilation.md +45 -54
  19. package/prompts/prereq-builder.md +28 -6
  20. package/prompts/prereq-planner.md +2 -2
  21. package/prompts/tool-candidate-detection.md +70 -39
  22. package/prompts/tool-planning.md +3 -3
  23. package/src/cli.ts +190 -150
  24. package/src/imprint/agent.ts +47 -33
  25. package/src/imprint/api-research-agent.ts +933 -0
  26. package/src/imprint/audit.ts +49 -2
  27. package/src/imprint/auth-compile-agent.ts +125 -55
  28. package/src/imprint/auth-compile-tools.ts +20 -48
  29. package/src/imprint/auth-verifier.ts +8 -19
  30. package/src/imprint/backend-ladder.ts +499 -367
  31. package/src/imprint/body-structure.ts +656 -0
  32. package/src/imprint/build-plan.ts +33 -323
  33. package/src/imprint/cdp-browser-fetch.ts +734 -29
  34. package/src/imprint/cdp-jar-cache.ts +7 -12
  35. package/src/imprint/claude-cli-compile.ts +276 -320
  36. package/src/imprint/codex-cli-compile.ts +476 -350
  37. package/src/imprint/codex-sdk-turn.ts +102 -0
  38. package/src/imprint/compile-agent-types.ts +49 -10
  39. package/src/imprint/compile-agent.ts +189 -274
  40. package/src/imprint/compile-done-sentinel.ts +211 -0
  41. package/src/imprint/compile-provider-control.ts +401 -0
  42. package/src/imprint/compile-provider-recovery.ts +142 -0
  43. package/src/imprint/compile-strategy.ts +5 -0
  44. package/src/imprint/compile-tools.ts +1695 -3097
  45. package/src/imprint/compile-verification.ts +9 -1
  46. package/src/imprint/compile.ts +107 -29
  47. package/src/imprint/compiler-log.ts +12 -0
  48. package/src/imprint/compiler-process.ts +440 -0
  49. package/src/imprint/concurrency.ts +43 -58
  50. package/src/imprint/credential-extract.ts +1 -88
  51. package/src/imprint/emit.ts +18 -2
  52. package/src/imprint/evidence-inspection.ts +55 -0
  53. package/src/imprint/freeform-redact.ts +34 -234
  54. package/src/imprint/import-module-fresh.ts +30 -0
  55. package/src/imprint/live-finesse-runner.ts +299 -0
  56. package/src/imprint/live-verifier.ts +299 -358
  57. package/src/imprint/llm.ts +466 -422
  58. package/src/imprint/log.ts +1 -9
  59. package/src/imprint/master-teach-agent-contracts.ts +875 -0
  60. package/src/imprint/master-teach-agents.ts +2850 -0
  61. package/src/imprint/master-teach-checks.ts +341 -0
  62. package/src/imprint/master-teach-controller.ts +7159 -0
  63. package/src/imprint/master-teach-plan.ts +1410 -0
  64. package/src/imprint/master-teach-prompt-projections.ts +347 -0
  65. package/src/imprint/master-teach-store.ts +961 -0
  66. package/src/imprint/mcp-cdp-sessions.ts +60 -0
  67. package/src/imprint/mcp-compile-server.ts +519 -668
  68. package/src/imprint/mcp-live-verifier-server.ts +246 -190
  69. package/src/imprint/mcp-server.ts +46 -57
  70. package/src/imprint/native-agent-pass.ts +260 -0
  71. package/src/imprint/native-agent-usage.ts +141 -0
  72. package/src/imprint/native-teach-agents.ts +495 -0
  73. package/src/imprint/param-grounding.ts +488 -347
  74. package/src/imprint/playbook-runner.ts +254 -63
  75. package/src/imprint/prereq-builder.ts +55 -543
  76. package/src/imprint/private-file.ts +18 -0
  77. package/src/imprint/probe-backends.ts +129 -33
  78. package/src/imprint/provider-retry.ts +501 -0
  79. package/src/imprint/provider-terminal.ts +214 -0
  80. package/src/imprint/recording-request.ts +290 -1
  81. package/src/imprint/recording-verification.ts +444 -0
  82. package/src/imprint/redact.ts +33 -749
  83. package/src/imprint/refine-worker.ts +326 -0
  84. package/src/imprint/refine.ts +241 -0
  85. package/src/imprint/replay-capture.ts +41 -12
  86. package/src/imprint/replay-evidence.ts +1007 -0
  87. package/src/imprint/research-response-evidence.ts +45 -0
  88. package/src/imprint/runtime.ts +514 -106
  89. package/src/imprint/sensitive-keys.ts +0 -6
  90. package/src/imprint/session-merge.ts +103 -7
  91. package/src/imprint/stealth-fetch.ts +25 -8
  92. package/src/imprint/stealth-token-cache.ts +16 -16
  93. package/src/imprint/teach-plan.ts +0 -242
  94. package/src/imprint/teach-research-memory.ts +229 -0
  95. package/src/imprint/teach-state.ts +47 -625
  96. package/src/imprint/teach.ts +12 -3699
  97. package/src/imprint/tool-candidates.ts +58 -210
  98. package/src/imprint/tool-loader.ts +3 -0
  99. package/src/imprint/tool-plan.ts +1 -134
  100. package/src/imprint/tracing.ts +24 -7
  101. package/src/imprint/types.ts +68 -4
  102. package/src/imprint/endpoint-key.ts +0 -23
@@ -4,9 +4,9 @@ You are the PLANNER for ONE MCP tool that a second agent will COMPILE from a bro
4
4
 
5
5
  You receive `{ site, url, tool, sharedContext?, planGuidance?, assignedModules, requests }`:
6
6
 
7
- - `tool` — `{ toolName, description, expectedOutput, likelyParams, requestSeqs, dependencySeqs, dependsOnTools }`. The compiled tool must expose these parameters and produce `expectedOutput`. `dependsOnTools` names independently callable setup tools the caller should run first; do not inline or replace them with a broader terminal workflow. `likelyParams` are the detector's best guess — confirm or correct each against the recorded requests.
7
+ - `tool` — `{ toolName, description, expectedOutput, likelyParams, requestSeqs, dependencySeqs, dependsOnTools }`. `likelyParams` and `expectedOutput` are editable detector proposals. Inspect the evidence and recommend the public parameters/output the tool should actually support. `dependsOnTools` names proposed sibling setup tools; verify those boundaries too.
8
8
  - `planGuidance?` — present when a global build plan ran first: `{ parserGuidance, paramChecklist, authRecipe, loadBearingSeqs }` for THIS tool. Treat it as prior guidance and reconcile it with the recorded data; if the recording contradicts it, prefer the recording and say so.
9
- - `assignedModules[]` — verified shared modules this tool MUST import instead of re-implementing: `{ path, kind, importPath, exportSignatures, purpose }`. A `request-transform` module reproduces the site's request signing/construction; a `parser-helper` extracts data from the response. Reference each by its exact `importPath`.
9
+ - `assignedModules[]` — built shared-module proposals available to this tool: `{ path, kind, importPath, exportSignatures, purpose }`. They are not accepted bindings. Inspect the exact evidence and recommend reuse only when the module fits; reference an accepted proposal by its exact `importPath`.
10
10
  - `requests[]` — the recorded requests in scope for this tool: `{ seq, method, url, headers, body, status, mimeType, responsePreview, ... }`. These are the ground truth — decode them, do not guess. `responsePreview` is truncated; note where the full body must be read.
11
11
 
12
12
  ## Output
@@ -29,7 +29,7 @@ For auth/app metadata, distinguish user credentials from public app configuratio
29
29
  The exact location of the result data: the `seq` whose response carries it, the precise JSON path(s) to the array/object, and the per-item fields to extract for `expectedOutput`. If the body is an RPC envelope (anti-XSSI prefix, length-prefixed frames, doubly-encoded JSON strings), give the exact unwrapping steps. If an `assignedModules` `parser-helper` covers this, say to call it by its `importPath` and what it returns.
30
30
 
31
31
  ### Shared modules
32
- The verbatim `importPath` of every module in `assignedModules` the tool must import, each with one line on what it provides. If `assignedModules` is empty, write "none".
32
+ The verbatim `importPath` of each proposed module you recommend reusing, with evidence for why it fits. Name rejected proposals and the reason under Edge cases. If none fit, write "none".
33
33
 
34
34
  ### Edge cases
35
35
  Empty results, optional parameters omitted, pagination, error/zero-result responses, and any value the recording doesn't fully pin down — each with your best-guess resolution so the compiler isn't blocked.
package/src/cli.ts CHANGED
@@ -7,6 +7,7 @@ import { parseArgs } from 'node:util';
7
7
  import { IS_COMPILED_BINARY } from './imprint/is-compiled.ts';
8
8
  import type { ProviderName } from './imprint/llm.ts';
9
9
  import { isDebug } from './imprint/log.ts';
10
+ import type { FreshTeachTerminalResult } from './imprint/master-teach-controller.ts';
10
11
  import { shutdownTracing, traced } from './imprint/tracing.ts';
11
12
  import { VERSION } from './imprint/version.ts';
12
13
 
@@ -40,43 +41,26 @@ export function parseDuration(dur: string): number | null {
40
41
  return num;
41
42
  }
42
43
 
43
- export type TeachSelectionMode =
44
- | 'tool'
45
- | 'primary'
46
- | 'all-explicit'
47
- | 'all-default'
48
- | 'interactive-default-all';
49
-
50
- /** Pure CLI selection-mode resolver shared by validation and telemetry. */
51
- export function resolveTeachSelectionMode(opts: {
52
- tool?: string;
53
- primaryTool?: boolean;
54
- allTools?: boolean;
55
- noInteractive?: boolean;
56
- }): { mode: TeachSelectionMode; error?: string } {
57
- if (opts.tool && opts.allTools) {
58
- return { mode: 'tool', error: 'error: --tool cannot be combined with --all-tools' };
59
- }
60
- if (opts.tool && opts.primaryTool) {
61
- return { mode: 'tool', error: 'error: --tool cannot be combined with --primary-tool' };
62
- }
63
- if (opts.allTools && opts.primaryTool) {
64
- return {
65
- mode: 'primary',
66
- error: 'error: --all-tools cannot be combined with --primary-tool',
67
- };
68
- }
69
- return {
70
- mode: opts.tool
71
- ? 'tool'
72
- : opts.primaryTool
73
- ? 'primary'
74
- : opts.allTools
75
- ? 'all-explicit'
76
- : opts.noInteractive
77
- ? 'all-default'
78
- : 'interactive-default-all',
79
- };
44
+ export function formatFreshTeachSummary(
45
+ result: Pick<FreshTeachTerminalResult, 'status' | 'readyTools' | 'nonReadyTools' | 'runRoot'>,
46
+ ): string {
47
+ const nonReadyLabel =
48
+ result.status === 'cancelled' || result.status === 'provider_unavailable'
49
+ ? 'unfinished'
50
+ : result.status === 'partial'
51
+ ? 'unresolved'
52
+ : result.status === 'blocked'
53
+ ? 'blocked'
54
+ : result.status === 'failed'
55
+ ? 'not ready'
56
+ : 'failed';
57
+ return `[imprint] teach ${result.status}: ${result.readyTools} ready, ${result.nonReadyTools} ${nonReadyLabel} — ${result.runRoot}`;
58
+ }
59
+
60
+ export function freshTeachExitCode(status: FreshTeachTerminalResult['status']): number {
61
+ if (status === 'completed') return 0;
62
+ if (status === 'cancelled') return 130;
63
+ return 1;
80
64
  }
81
65
 
82
66
  const HELP = `imprint v${VERSION} — teach an AI agent to use any website. Once.
@@ -88,7 +72,7 @@ USAGE
88
72
  CAPTURE
89
73
  record <site> Drive a workflow in Chromium, capture session.
90
74
  teach <site> Record + compile + emit in one flow. <site> is a label you pick.
91
- redact <session.json> Scrub credentials + PII before LLM analysis.
75
+ redact <session.json> Replace known login credentials only; not share-safe.
92
76
 
93
77
  COMPILE
94
78
  generate <session> Session → workflow.json (API replay).
@@ -149,72 +133,60 @@ export const VERB_HELP: Record<string, VerbHelp> = {
149
133
  },
150
134
  teach: {
151
135
  summary:
152
- 'Record a workflow, compile both artifacts, emit the tool, and connect to your AI platform — all in one interactive flow. Supports resuming incomplete runs and multiple workflows per site.',
136
+ 'Record or load a session, then let the master discover, plan, compile, verify, and emit every supported tool.',
153
137
  usage: [
154
- 'imprint teach <site> [--url <url>] [--from-session <path>] [--persist-profile] [--no-interactive] [--primary-tool | --all-tools] [--tool <toolName>] [--provider <name>] [--model <name>] [--timeout <duration>] [--keep-test] [--skip-replay] [--from-step <step>] [--to-step <step>] [--only <step>]',
138
+ 'imprint teach <site> [--url <url>] [--from-session <path> ...] [--from-candidates <run-id>] [--guidance <text>] [--persist-profile] [--no-interactive] [--agent codex] [--provider <name>] [--model <name>] [--timeout <duration> | --unbounded] [--keep-test]',
155
139
  ],
156
140
  flags: [
157
141
  { name: '--url <url>', description: 'Starting URL (else about:blank).' },
158
142
  {
159
143
  name: '--from-session <path>',
160
- description: 'Skip recording; use an existing session file to compile from.',
144
+ description:
145
+ 'Use one exact recording. Repeat the flag to explicitly combine selected recordings. Without it, the newest raw recording is used.',
161
146
  },
162
- { name: '--persist-profile', description: 'Reuse a stable Chrome profile for this site.' },
163
147
  {
164
- name: '--no-interactive',
165
- description: 'Run without prompts; compile all detected tools by default.',
148
+ name: '--from-candidates <run-id>',
149
+ description:
150
+ 'Reuse only candidate selection from an earlier run of this same recording; planning and compilation start fresh.',
166
151
  },
167
152
  {
168
- name: '--all-tools',
169
- description: 'Explicitly compile all detected tools (the default).',
153
+ name: '--guidance <text>',
154
+ description:
155
+ 'Give the master explicit human scope or priorities. This guides agent decisions and is not recording evidence.',
170
156
  },
157
+ { name: '--persist-profile', description: 'Reuse a stable Chrome profile for this site.' },
171
158
  {
172
- name: '--primary-tool',
173
- description: 'Compile only the primary detected tool and its upstream dependencies.',
159
+ name: '--no-interactive',
160
+ description: 'Run without prompts. Every tool in the master plan is still built.',
174
161
  },
175
162
  {
176
- name: '--tool <toolName>',
163
+ name: '--agent codex',
177
164
  description:
178
- 'With --from-step/--only, resume exactly one persisted tool from the retained recording.',
165
+ 'Select the master-agent flow explicitly and default every teaching agent to codex-cli. This never narrows the tool set; --provider still overrides it.',
179
166
  },
180
167
  {
181
168
  name: '--provider <name>',
182
169
  description:
183
- 'Compile-agent provider: anthropic-api, claude-cli, codex-cli (auto-detected if omitted).',
170
+ 'Teaching-agent provider: anthropic-api, claude-cli, codex-cli (auto-detected if omitted).',
184
171
  },
185
172
  {
186
173
  name: '--model <name>',
187
174
  description:
188
- 'Override the compile-agent model (e.g. claude-sonnet-4-6). Default is prompted interactively or auto-selected per provider.',
175
+ 'Override the teaching-agent model (e.g. claude-sonnet-4-6). Otherwise the provider default is used.',
189
176
  },
190
177
  {
191
178
  name: '--timeout <duration>',
192
- description: 'Per-tool compile timeout. Accepts 20m, 1h, 300s, or plain ms. Default 20m.',
179
+ description: 'Foreground teach deadline. Accepts 20m, 12h, 300s, or plain ms. Default 12h.',
193
180
  },
194
181
  {
195
- name: '--keep-test',
196
- description:
197
- 'Retain the agent-generated parser.test.ts and request.test.ts after compile (debug). Default deletes them; parser tests read the gitignored redacted session via $IMPRINT_SESSION_PATH and are not portable. Also settable via IMPRINT_KEEP_TEST=1.',
198
- },
199
- {
200
- name: '--skip-replay',
201
- description:
202
- "Skip the replay-and-diff stage. Faster, but the compile agent won't be able to distinguish browser-minted values from constants, which may reduce workflow accuracy. By default, the preceding effect-aware triage suppresses replay entirely when the recording contains an irreversible request.",
203
- },
204
- {
205
- name: '--from-step <step>',
206
- description:
207
- 'Resume a prior run starting at <step> (record, redact, triage, replay-and-diff, detect-candidates, plan-prereqs, generate, compile-playbook, emit, register). Only allowed if a prior run reached/crossed that point — earlier phase outputs are reused. Not combinable with --from-session.',
208
- },
209
- {
210
- name: '--to-step <step>',
182
+ name: '--unbounded',
211
183
  description:
212
- 'Stop after <step> instead of running to the end. Combine with --from-step (or --from-session) to run a window of phases. Note: the per-tool compile (generate→compile-playbook→emit) is atomic, so a --to-step inside it runs the whole compile and stops before register.',
184
+ 'Run teach without a whole-run deadline; individual action timeouts and cancellation remain.',
213
185
  },
214
186
  {
215
- name: '--only <step>',
187
+ name: '--keep-test',
216
188
  description:
217
- 'Run a single phase: shorthand for --from-step <step> --to-step <step> (not combinable with either). For a compile phase the whole atomic compile unit runs (see --to-step).',
189
+ 'Retain the agent-generated parser.test.ts and request.test.ts after compile (debug). Default deletes them; parser tests read the gitignored redacted session via $IMPRINT_SESSION_PATH and are not portable. Also settable via IMPRINT_KEEP_TEST=1.',
218
190
  },
219
191
  ],
220
192
  example: 'imprint teach google-flights --url https://flights.google.com',
@@ -235,7 +207,7 @@ export const VERB_HELP: Record<string, VerbHelp> = {
235
207
  example: 'imprint check ~/.imprint/acmecorp/sessions/2026-05-03T22-00-00Z.json',
236
208
  },
237
209
  redact: {
238
- summary: 'Scrub credentials + PII; write <session>.redacted.json.',
210
+ summary: 'Replace known login values; other sensitive data remains in <session>.redacted.json.',
239
211
  usage: ['imprint redact <session.json> [--keep-header <name>]…'],
240
212
  flags: [
241
213
  {
@@ -246,6 +218,28 @@ export const VERB_HELP: Record<string, VerbHelp> = {
246
218
  ],
247
219
  example: 'imprint redact ~/.imprint/acmecorp/sessions/<ts>.json',
248
220
  },
221
+ refine: {
222
+ summary: 'Repair or extend installed tools using a recording, with staged verification.',
223
+ usage: [
224
+ 'imprint refine <site> --tool <name> --issue <text> [--from-session <path>] [--provider <name>] [--model <name>] [--timeout <duration>] [--json]',
225
+ ],
226
+ flags: [
227
+ { name: '--tool <name>', description: 'Installed tool to repair or extend (required).' },
228
+ { name: '--issue <text>', description: 'Defect or requested extension (required).' },
229
+ {
230
+ name: '--from-session <path>',
231
+ description: 'Recording evidence; otherwise use the newest retained recording.',
232
+ },
233
+ { name: '--provider <name>', description: 'codex-cli or claude-cli.' },
234
+ { name: '--model <name>', description: 'Override the selected provider model.' },
235
+ {
236
+ name: '--timeout <duration>',
237
+ description: 'Shared refinement and audit deadline (default 30m).',
238
+ },
239
+ { name: '--json', description: 'Print the result and evidence directory as JSON.' },
240
+ ],
241
+ example: 'imprint refine my-site --tool search --issue "Repair missing result entries"',
242
+ },
249
243
  generate: {
250
244
  summary: 'LLM-compile a session into workflow.json (API replay artifact).',
251
245
  usage: [
@@ -466,9 +460,13 @@ export const VERB_HELP: Record<string, VerbHelp> = {
466
460
  summary:
467
461
  "Drive a headless agent against a site's MCP tools, exercise each one, and compute a deterministic accuracy score. Verdicts come from the agent; the score is computed by imprint.",
468
462
  usage: [
469
- 'imprint audit <site> [--min-score <n>] [--out <path>] [--model <name>] [--timeout <duration>] [--json]',
463
+ 'imprint audit <site> [--strict] [--min-score <n>] [--out <path>] [--model <name>] [--timeout <duration>] [--json]',
470
464
  ],
471
465
  flags: [
466
+ {
467
+ name: '--strict',
468
+ description: 'Require zero broken calls or parameters and complete verified coverage.',
469
+ },
472
470
  {
473
471
  name: '--min-score <n>',
474
472
  description: 'Pass threshold as a percentage of gradeable invocations (default 95).',
@@ -739,14 +737,14 @@ async function main(argv: string[]): Promise<number> {
739
737
  case 'redact': {
740
738
  const sessionPath = requirePositional(argv, 'redact', 'a <session.json> argument');
741
739
  if (sessionPath === null) return 2;
742
- const { values } = parseArgs({
740
+ parseArgs({
743
741
  args: argv.slice(2),
744
742
  options: { 'keep-header': { type: 'string', multiple: true } },
745
743
  allowPositionals: false,
746
744
  });
747
- const { writeFileSync } = await import('node:fs');
748
745
  const { SessionSchema } = await import('./imprint/types.ts');
749
746
  const { redactSession } = await import('./imprint/redact.ts');
747
+ const { writePrivateFile } = await import('./imprint/private-file.ts');
750
748
  const { loadJsonFile } = await import('./imprint/load-json.ts');
751
749
  let session: ReturnType<typeof SessionSchema.parse>;
752
750
  try {
@@ -764,16 +762,10 @@ async function main(argv: string[]): Promise<number> {
764
762
  console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
765
763
  return 2;
766
764
  }
767
- const keepHeaders = values['keep-header'] ?? [];
768
- // `imprint redact` produces a file to SHARE (bug reports, fixtures), so it
769
- // applies the strongest scrub including sensitive headers — unlike the
770
- // compile path, which keeps headers visible to the agent by default.
771
- const { session: scrubbed, stats } = redactSession(session, {
772
- keepHeaders,
773
- redactSensitiveHeaders: true,
774
- });
765
+ // --keep-header remains accepted for CLI compatibility; all headers are kept.
766
+ const { session: scrubbed, stats } = redactSession(session);
775
767
  const outPath = sessionPath.replace(/\.json$/, '.redacted.json');
776
- writeFileSync(outPath, `${JSON.stringify(scrubbed, null, 2)}\n`, 'utf8');
768
+ writePrivateFile(outPath, `${JSON.stringify(scrubbed, null, 2)}\n`);
777
769
  console.log(`[imprint] redacted → ${outPath}`);
778
770
  const freeformNote =
779
771
  stats.freeformRedactions > 0
@@ -782,9 +774,9 @@ async function main(argv: string[]): Promise<number> {
782
774
  console.log(
783
775
  `[imprint] ${stats.totalRedactions} value${stats.totalRedactions === 1 ? '' : 's'} replaced across ${stats.requestsRedacted} request${stats.requestsRedacted === 1 ? '' : 's'} and ${stats.cookiesRedacted} cookie${stats.cookiesRedacted === 1 ? '' : 's'}${freeformNote}`,
784
776
  );
785
- if (keepHeaders.length > 0) {
786
- console.log(`[imprint] kept (not redacted): ${keepHeaders.join(', ')}`);
787
- }
777
+ console.log(
778
+ '[imprint] Only login credentials are replaced. Cookies, tokens and personal data remain; this file is not safe to share.',
779
+ );
788
780
  for (const w of stats.warnings) {
789
781
  console.log(`[imprint] ⚠ ${w}`);
790
782
  }
@@ -1191,6 +1183,7 @@ async function main(argv: string[]): Promise<number> {
1191
1183
  args: argv.slice(2),
1192
1184
  options: {
1193
1185
  'min-score': { type: 'string' },
1186
+ strict: { type: 'boolean' },
1194
1187
  out: { type: 'string' },
1195
1188
  provider: { type: 'string' },
1196
1189
  model: { type: 'string' },
@@ -1244,6 +1237,7 @@ async function main(argv: string[]): Promise<number> {
1244
1237
  runAudit({
1245
1238
  site,
1246
1239
  minScore,
1240
+ strict: values.strict,
1247
1241
  outPath,
1248
1242
  provider,
1249
1243
  model: values.model,
@@ -1443,6 +1437,58 @@ async function main(argv: string[]): Promise<number> {
1443
1437
  return 1;
1444
1438
  }
1445
1439
 
1440
+ case 'refine': {
1441
+ const site = requirePositional(argv, 'refine', 'a <site> argument');
1442
+ if (site === null) return 2;
1443
+ const { values } = parseArgs({
1444
+ args: argv.slice(2),
1445
+ options: {
1446
+ tool: { type: 'string' },
1447
+ issue: { type: 'string' },
1448
+ 'from-session': { type: 'string' },
1449
+ provider: { type: 'string' },
1450
+ model: { type: 'string' },
1451
+ timeout: { type: 'string' },
1452
+ json: { type: 'boolean' },
1453
+ },
1454
+ allowPositionals: false,
1455
+ });
1456
+ if (!values.tool || !values.issue?.trim()) {
1457
+ console.error('error: refine requires --tool and --issue');
1458
+ return 2;
1459
+ }
1460
+ const { detectTeachProvider } = await import('./imprint/llm.ts');
1461
+ const provider = values.provider ?? detectTeachProvider();
1462
+ if (provider !== 'codex-cli' && provider !== 'claude-cli') {
1463
+ console.error(
1464
+ 'error: refine requires codex-cli or claude-cli for staged independent audit',
1465
+ );
1466
+ return 2;
1467
+ }
1468
+ const timeoutMs = values.timeout ? parseDuration(values.timeout) : undefined;
1469
+ if (values.timeout && (timeoutMs === null || timeoutMs === undefined || timeoutMs <= 0)) {
1470
+ console.error('error: invalid --timeout');
1471
+ return 2;
1472
+ }
1473
+ const { runRefine } = await import('./imprint/refine.ts');
1474
+ const result = await runRefine({
1475
+ site,
1476
+ tool: values.tool,
1477
+ issue: values.issue,
1478
+ fromSession: values['from-session'],
1479
+ provider,
1480
+ model: values.model,
1481
+ timeoutMs: timeoutMs ?? undefined,
1482
+ json: values.json,
1483
+ });
1484
+ console.log(
1485
+ values.json
1486
+ ? JSON.stringify(result)
1487
+ : `[imprint] refine ${result.status}: ${result.reason ?? 'verified replacements installed'}\nEvidence: ${result.runRoot}`,
1488
+ );
1489
+ return result.status === 'completed' ? 0 : 1;
1490
+ }
1491
+
1446
1492
  case 'teach': {
1447
1493
  const rawSite = argv[1];
1448
1494
  let site: string | undefined;
@@ -1460,66 +1506,29 @@ async function main(argv: string[]): Promise<number> {
1460
1506
  args: argv.slice(rawSite ? 2 : 1),
1461
1507
  options: {
1462
1508
  url: { type: 'string' },
1463
- 'from-session': { type: 'string' },
1509
+ 'from-session': { type: 'string', multiple: true },
1510
+ 'from-candidates': { type: 'string' },
1511
+ guidance: { type: 'string' },
1464
1512
  'persist-profile': { type: 'boolean' },
1465
1513
  'no-interactive': { type: 'boolean' },
1466
- 'all-tools': { type: 'boolean' },
1467
- 'primary-tool': { type: 'boolean' },
1468
- tool: { type: 'string' },
1514
+ agent: { type: 'string' },
1469
1515
  provider: { type: 'string' },
1470
1516
  model: { type: 'string' },
1471
1517
  timeout: { type: 'string' },
1518
+ unbounded: { type: 'boolean' },
1472
1519
  'keep-test': { type: 'boolean' },
1473
- 'skip-replay': { type: 'boolean' },
1474
- 'from-step': { type: 'string' },
1475
- 'to-step': { type: 'string' },
1476
- only: { type: 'string' },
1477
1520
  },
1478
1521
  allowPositionals: false,
1479
1522
  });
1480
1523
 
1481
- // ── Phase-window flags: run only specific steps of the teach chain ──
1482
- // `--only X` = `--from-step X --to-step X`. resolveTeachPhaseWindow validates
1483
- // step names against the canonical list and the flag combinations (ordering,
1484
- // mutual exclusion with --from-session, and --to-step ≥ redact when
1485
- // --from-session enters the chain at redact), returning the resolved window
1486
- // or the exact error message to print. Extracted for unit-testing.
1487
- const { resolveTeachPhaseWindow, validateToolScopedResumeStep } = await import(
1488
- './imprint/teach-state.ts'
1489
- );
1490
- const phaseWindow = resolveTeachPhaseWindow(values);
1491
- if ('error' in phaseWindow) {
1492
- console.error(phaseWindow.error);
1493
- return 2;
1494
- }
1495
- const fromStepArg = phaseWindow.fromStep;
1496
- const toStepArg = phaseWindow.toStep;
1497
-
1498
- if (values.tool && !fromStepArg) {
1499
- console.error('error: --tool requires --from-step or --only');
1500
- return 2;
1501
- }
1502
- if (values.tool) {
1503
- const toolWindowError = validateToolScopedResumeStep(fromStepArg);
1504
- if (toolWindowError) {
1505
- console.error(toolWindowError);
1506
- return 2;
1507
- }
1508
- }
1509
- const selection = resolveTeachSelectionMode({
1510
- tool: values.tool,
1511
- primaryTool: values['primary-tool'],
1512
- allTools: values['all-tools'],
1513
- noInteractive: values['no-interactive'],
1514
- });
1515
- if (selection.error) {
1516
- console.error(selection.error);
1524
+ if (values.agent && values.agent !== 'codex') {
1525
+ console.error('error: --agent currently accepts only "codex"');
1517
1526
  return 2;
1518
1527
  }
1519
1528
 
1520
- if (!site && values['no-interactive']) {
1529
+ if (!site) {
1521
1530
  console.error(
1522
- 'error: `imprint teach` requires a <site> argument in --no-interactive mode.\n <site> is a label you choose — it names the output folder under ~/.imprint/.\n\n example: imprint teach google-flights --url https://flights.google.com\n→ run `imprint teach --help` for usage.',
1531
+ 'error: `imprint teach` requires a <site> argument.\n <site> is a label you choose — it names the output folder under ~/.imprint/.\n\n example: imprint teach google-flights --url https://flights.google.com\n→ run `imprint teach --help` for usage.',
1523
1532
  );
1524
1533
  return 2;
1525
1534
  }
@@ -1535,6 +1544,10 @@ async function main(argv: string[]): Promise<number> {
1535
1544
  }
1536
1545
 
1537
1546
  let teachTimeoutMs: number | undefined;
1547
+ if (values.unbounded && values.timeout) {
1548
+ console.error('error: --unbounded and --timeout cannot be combined');
1549
+ return 2;
1550
+ }
1538
1551
  if (values.timeout) {
1539
1552
  teachTimeoutMs = parseDuration(values.timeout) ?? undefined;
1540
1553
  if (teachTimeoutMs === undefined) {
@@ -1548,51 +1561,57 @@ async function main(argv: string[]): Promise<number> {
1548
1561
  const ctrl = new AbortController();
1549
1562
  const onSigint = (): void => ctrl.abort();
1550
1563
  process.once('SIGINT', onSigint);
1551
- const teachSelectionMode = selection.mode;
1552
1564
 
1553
1565
  try {
1554
1566
  const { teach } = await import('./imprint/teach.ts');
1555
- await traced(
1567
+ const result = await traced(
1556
1568
  'cli.teach',
1557
1569
  'AGENT',
1558
1570
  {
1559
1571
  'imprint.site': site,
1560
1572
  'imprint.url': values.url,
1561
- 'imprint.from_session': values['from-session'],
1562
- 'imprint.provider': values.provider ?? 'auto',
1573
+ 'imprint.from_session': values['from-session']?.join(','),
1574
+ 'imprint.from_candidates': values['from-candidates'],
1575
+ 'imprint.user_guidance': values.guidance,
1576
+ 'imprint.provider':
1577
+ values.provider ?? (values.agent === 'codex' ? 'codex-cli' : 'auto'),
1563
1578
  'imprint.model': values.model ?? 'auto',
1564
1579
  'imprint.timeout_ms': teachTimeoutMs ?? 'default',
1565
- 'imprint.all_tools':
1566
- teachSelectionMode === 'all-explicit' || teachSelectionMode === 'all-default',
1567
- 'imprint.selection_mode': teachSelectionMode,
1568
- 'imprint.primary_tool': values['primary-tool'] ?? false,
1569
- 'imprint.tool': values.tool,
1580
+ 'imprint.unbounded': values.unbounded ?? false,
1581
+ 'imprint.agent': values.agent ?? 'master',
1570
1582
  'imprint.no_interactive': values['no-interactive'] ?? false,
1571
- 'imprint.skip_replay': values['skip-replay'] ?? false,
1572
1583
  },
1573
1584
  () =>
1574
1585
  teach({
1575
1586
  site,
1576
1587
  url: values.url,
1577
1588
  fromSession: values['from-session'],
1589
+ fromCandidates: values['from-candidates'],
1590
+ userGuidance: values.guidance,
1578
1591
  persistProfile: values['persist-profile'],
1579
1592
  signal: ctrl.signal,
1580
1593
  noInteractive: values['no-interactive'],
1581
1594
  provider: values.provider as ProviderName | undefined,
1582
1595
  model: values.model,
1583
1596
  maxDurationMs: teachTimeoutMs,
1597
+ unbounded: values.unbounded,
1584
1598
  keepTest: values['keep-test'] || process.env.IMPRINT_KEEP_TEST === '1',
1585
- primaryTool: values['primary-tool'],
1586
- tool: values.tool,
1587
- skipReplay: values['skip-replay'],
1588
- fromStep: fromStepArg,
1589
- toStep: toStepArg,
1599
+ agent: values.agent === 'codex' ? 'codex' : undefined,
1600
+ onProgress: (message) => console.error(`[imprint teach] ${message}`),
1590
1601
  }),
1591
1602
  );
1603
+ const summary = formatFreshTeachSummary(result);
1604
+ if (result.status === 'completed' || result.status === 'partial') {
1605
+ console.log(summary);
1606
+ console.log(`[imprint] ${result.message}`);
1607
+ } else {
1608
+ console.error(summary);
1609
+ console.error(`[imprint] ${result.message}`);
1610
+ }
1611
+ return freshTeachExitCode(result.status);
1592
1612
  } finally {
1593
1613
  process.removeListener('SIGINT', onSigint);
1594
1614
  }
1595
- return 0;
1596
1615
  }
1597
1616
 
1598
1617
  case 'credential': {
@@ -1618,8 +1637,10 @@ async function main(argv: string[]): Promise<number> {
1618
1637
  'shared-context-json': { type: 'string' },
1619
1638
  'build-plan-path': { type: 'string' },
1620
1639
  'shared-modules-json': { type: 'string' },
1640
+ 'strategy-kind': { type: 'string' },
1621
1641
  'auth-plan-json': { type: 'string' },
1622
1642
  'revision-mode': { type: 'boolean' },
1643
+ 'verification-mode': { type: 'string' },
1623
1644
  provider: { type: 'string' },
1624
1645
  site: { type: 'string' },
1625
1646
  'shared-triage-json': { type: 'string' },
@@ -1641,6 +1662,7 @@ async function main(argv: string[]): Promise<number> {
1641
1662
  './imprint/build-plan.ts'
1642
1663
  );
1643
1664
  const { SharedTriageSelectionSchema } = await import('./imprint/triage-selection.ts');
1665
+ const { CompileStrategyKindSchema } = await import('./imprint/compile-strategy.ts');
1644
1666
  const candidate = values['candidate-json']
1645
1667
  ? ToolCandidateSchema.parse(JSON.parse(values['candidate-json']))
1646
1668
  : undefined;
@@ -1656,6 +1678,18 @@ async function main(argv: string[]): Promise<number> {
1656
1678
  const sharedTriageSelection = values['shared-triage-json']
1657
1679
  ? SharedTriageSelectionSchema.parse(JSON.parse(values['shared-triage-json']))
1658
1680
  : undefined;
1681
+ const strategyKind = values['strategy-kind']
1682
+ ? CompileStrategyKindSchema.parse(values['strategy-kind'])
1683
+ : undefined;
1684
+ const verificationMode = values['verification-mode'];
1685
+ if (
1686
+ verificationMode !== undefined &&
1687
+ verificationMode !== 'full' &&
1688
+ verificationMode !== 'master_mvp'
1689
+ ) {
1690
+ console.error('error: __mcp-compile-server --verification-mode must be full or master_mvp');
1691
+ return 2;
1692
+ }
1659
1693
  await runCompileMcpServer({
1660
1694
  sessionPath: values['session-path'],
1661
1695
  toolDir,
@@ -1663,8 +1697,10 @@ async function main(argv: string[]): Promise<number> {
1663
1697
  sharedContext,
1664
1698
  buildPlanPath: values['build-plan-path'],
1665
1699
  sharedModules,
1700
+ strategyKind,
1666
1701
  authToolPlan: authToolPlan ?? undefined,
1667
1702
  revisionMode: values['revision-mode'],
1703
+ verificationMode,
1668
1704
  provider: values.provider as
1669
1705
  | 'anthropic-api'
1670
1706
  | 'claude-cli'
@@ -1836,6 +1872,10 @@ if (import.meta.main) {
1836
1872
  process.exit(code);
1837
1873
  })
1838
1874
  .catch(async (err) => {
1875
+ if (err instanceof DOMException && err.name === 'AbortError') {
1876
+ await shutdownTracing();
1877
+ process.exit(130);
1878
+ }
1839
1879
  console.error('imprint: fatal:', err instanceof Error ? err.message : String(err));
1840
1880
  if (isDebug()) {
1841
1881
  console.error(err);