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
@@ -8,6 +8,7 @@ import {
8
8
  ListToolsRequestSchema,
9
9
  type Tool,
10
10
  } from '@modelcontextprotocol/sdk/types.js';
11
+ import { inheritedCompileProviderControl } from './compile-provider-control.ts';
11
12
  import {
12
13
  type LiveIntegrationEvidence,
13
14
  runCapturedIntegrationCase,
@@ -21,6 +22,7 @@ import {
21
22
  LiveVerificationReportSchema,
22
23
  appendLiveVerifierLog,
23
24
  assertReportCoversWorkflowParameters,
25
+ backendPreparationFailureObservation,
24
26
  effectiveParamsForEvidence,
25
27
  hasSuiteReceiptForSession,
26
28
  persistLiveVerificationEvidence,
@@ -29,6 +31,13 @@ import {
29
31
  runLiveAuthRefreshToolCall,
30
32
  runLiveIntegrationSuite,
31
33
  } from './live-verifier.ts';
34
+ import {
35
+ ProviderDeadlineError,
36
+ ProviderUnavailableError,
37
+ combinedDeadlineSignal,
38
+ providerControlError,
39
+ resolvedRunDeadline,
40
+ } from './provider-retry.ts';
32
41
  import { buildZodValidator } from './tool-loader.ts';
33
42
  import { WorkflowSchema } from './types.ts';
34
43
 
@@ -71,7 +80,7 @@ const RUN_TOOL: Tool = {
71
80
  const PREPARE_BACKEND_TOOL: Tool = {
72
81
  name: 'prepare_live_backend',
73
82
  description:
74
- 'Reuse the preferred backend and probe only when no valid preference exists. Set forceReprobe only after a transport, network, or browser-infrastructure failure from that backend; never reprobe for empty, incorrect, or otherwise semantic output failures.',
83
+ 'Reuse the preferred backend and probe only when no valid preference exists. Set forceReprobe only after a transport, network, or browser-infrastructure failure from that backend; never reprobe for empty, incorrect, or otherwise semantic output failures. On failure, requestStageFacts report value-free preparation, transform, and send outcomes for each attempted request.',
75
84
  inputSchema: {
76
85
  type: 'object',
77
86
  properties: {
@@ -173,216 +182,263 @@ export async function runLiveVerifierMcpServer(opts: {
173
182
  }
174
183
  const validator = buildZodValidator(workflow.parameters);
175
184
  const configuredDeadline = Number(process.env.IMPRINT_LIVE_VERIFIER_DEADLINE_MS);
176
- const deadlineMs = Number.isFinite(configuredDeadline) ? configuredDeadline : undefined;
185
+ const inheritedControl = inheritedCompileProviderControl();
186
+ const runDeadline =
187
+ inheritedControl?.deadline ??
188
+ resolvedRunDeadline(
189
+ undefined,
190
+ Number.isFinite(configuredDeadline) ? configuredDeadline : undefined,
191
+ );
192
+ const lifetime = new AbortController();
193
+ const active = combinedDeadlineSignal(runDeadline, undefined, lifetime.signal);
194
+ const processHandlers = new Map<NodeJS.Signals, () => void>();
195
+ for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
196
+ const handler = (): void =>
197
+ lifetime.abort(new DOMException(`Live verifier MCP received ${signal}`, 'AbortError'));
198
+ processHandlers.set(signal, handler);
199
+ process.once(signal, handler);
200
+ }
177
201
  let authSession: LiveVerificationAuthSession | undefined;
178
- let submitted = false;
179
- const backendPreparation: {
180
- current?: {
181
- promise: Promise<Awaited<ReturnType<typeof prepareLiveVerificationBackend>>>;
182
- forceReprobe: boolean;
202
+ try {
203
+ const rethrowProviderControl = (error: unknown): void => {
204
+ const control = providerControlError(active.signal?.aborted ? active.signal.reason : error);
205
+ if (!control) return;
206
+ if (control instanceof ProviderDeadlineError || control instanceof ProviderUnavailableError) {
207
+ inheritedControl?.report(control);
208
+ }
209
+ throw control;
183
210
  };
184
- } = {};
185
- const evidencePath = pathJoin(dirname(opts.reportPath), LIVE_VERIFICATION_EVIDENCE_FILE);
186
- let targetedCallSequence = readPersistedLiveVerificationEvidence(evidencePath).reduce(
187
- (highest, item) => {
188
- const match = /^targeted-call-(\d+)$/.exec(item.label);
189
- return match ? Math.max(highest, Number(match[1])) : highest;
190
- },
191
- 0,
192
- );
193
- const hasSuiteReceipt = (): boolean => hasSuiteReceiptForSession(evidencePath, opts.sessionLabel);
194
-
195
- const server = new Server(
196
- { name: 'imprint-live-verifier', version: '1.0.0' },
197
- { capabilities: { tools: {} } },
198
- );
199
- server.setRequestHandler(ListToolsRequestSchema, async () => ({
200
- tools: [REFRESH_AUTH_TOOL, PREPARE_BACKEND_TOOL, RUN_SUITE_TOOL, RUN_TOOL, SUBMIT_TOOL],
201
- }));
202
- server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
203
- if (request.params.name === 'refresh_auth_session') {
204
- const result = await runLiveAuthRefreshToolCall(authSession, request.params.arguments, {
205
- workflowPath: opts.workflowPath,
206
- logPath: opts.logPath,
207
- attempt: opts.attempt,
208
- sessionLabel: opts.sessionLabel,
209
- deadlineMs,
210
- });
211
- authSession = result.session;
212
- return result.error
213
- ? errorResult(result.error)
214
- : { content: [{ type: 'text', text: JSON.stringify(result.observation) }] };
215
- }
216
- if (request.params.name === 'prepare_live_backend') {
217
- const input = request.params.arguments as {
218
- params?: unknown;
219
- reason?: unknown;
220
- forceReprobe?: unknown;
211
+ let submitted = false;
212
+ const backendPreparation: {
213
+ current?: {
214
+ promise: Promise<Awaited<ReturnType<typeof prepareLiveVerificationBackend>>>;
215
+ forceReprobe: boolean;
221
216
  };
222
- if (typeof input.reason !== 'string' || !input.reason.trim()) {
223
- return errorResult('reason must explain the backend preparation or reprobe');
224
- }
225
- const parsed = validator.safeParse(input.params ?? {});
226
- if (!parsed.success) return errorResult(`invalid tool params: ${parsed.error.message}`);
227
- try {
228
- const forceReprobe = input.forceReprobe === true;
229
- const preparation = joinBackendPreparation(backendPreparation, forceReprobe, () =>
230
- prepareLiveVerificationBackend({
217
+ } = {};
218
+ const evidencePath = pathJoin(dirname(opts.reportPath), LIVE_VERIFICATION_EVIDENCE_FILE);
219
+ let targetedCallSequence = readPersistedLiveVerificationEvidence(evidencePath).reduce(
220
+ (highest, item) => {
221
+ const match = /^targeted-call-(\d+)$/.exec(item.label);
222
+ return match ? Math.max(highest, Number(match[1])) : highest;
223
+ },
224
+ 0,
225
+ );
226
+ const hasSuiteReceipt = (): boolean =>
227
+ hasSuiteReceiptForSession(evidencePath, opts.sessionLabel);
228
+
229
+ const server = new Server(
230
+ { name: 'imprint-live-verifier', version: '1.0.0' },
231
+ { capabilities: { tools: {} } },
232
+ );
233
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
234
+ tools: [REFRESH_AUTH_TOOL, PREPARE_BACKEND_TOOL, RUN_SUITE_TOOL, RUN_TOOL, SUBMIT_TOOL],
235
+ }));
236
+ server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
237
+ if (request.params.name === 'refresh_auth_session') {
238
+ try {
239
+ const result = await runLiveAuthRefreshToolCall(authSession, request.params.arguments, {
231
240
  workflowPath: opts.workflowPath,
232
- params: parsed.data as Record<string, string | number | boolean>,
233
- reason: input.reason as string,
234
- forceReprobe,
235
241
  logPath: opts.logPath,
236
242
  attempt: opts.attempt,
237
- }),
238
- );
239
- if (preparation.joined) {
240
- appendLiveVerifierLog(opts.logPath, {
241
- type: 'backend.prepare.joined',
243
+ sessionLabel: opts.sessionLabel,
244
+ deadlineMs: runDeadline?.deadlineMs,
245
+ runDeadline,
246
+ signal: active.signal,
247
+ });
248
+ authSession = result.session;
249
+ return result.error
250
+ ? errorResult(result.error)
251
+ : { content: [{ type: 'text', text: JSON.stringify(result.observation) }] };
252
+ } catch (error) {
253
+ rethrowProviderControl(error);
254
+ throw error;
255
+ }
256
+ }
257
+ if (request.params.name === 'prepare_live_backend') {
258
+ const input = request.params.arguments as {
259
+ params?: unknown;
260
+ reason?: unknown;
261
+ forceReprobe?: unknown;
262
+ };
263
+ if (typeof input.reason !== 'string' || !input.reason.trim()) {
264
+ return errorResult('reason must explain the backend preparation or reprobe');
265
+ }
266
+ const parsed = validator.safeParse(input.params ?? {});
267
+ if (!parsed.success) return errorResult(`invalid tool params: ${parsed.error.message}`);
268
+ try {
269
+ const forceReprobe = input.forceReprobe === true;
270
+ const preparation = joinBackendPreparation(backendPreparation, forceReprobe, () =>
271
+ prepareLiveVerificationBackend({
272
+ workflowPath: opts.workflowPath,
273
+ params: parsed.data as Record<string, string | number | boolean>,
274
+ reason: input.reason as string,
275
+ forceReprobe,
276
+ logPath: opts.logPath,
277
+ attempt: opts.attempt,
278
+ signal: active.signal,
279
+ }),
280
+ );
281
+ if (preparation.joined) {
282
+ appendLiveVerifierLog(opts.logPath, {
283
+ type: 'backend.prepare.joined',
284
+ attempt: opts.attempt,
285
+ reason: input.reason,
286
+ forceReprobe: input.forceReprobe === true,
287
+ });
288
+ }
289
+ const result = await preparation.promise;
290
+ return { content: [{ type: 'text', text: JSON.stringify(result) }] };
291
+ } catch (error) {
292
+ rethrowProviderControl(error);
293
+ return errorResult(JSON.stringify(backendPreparationFailureObservation(error)));
294
+ }
295
+ }
296
+ if (request.params.name === 'run_live_integration_suite') {
297
+ const input = request.params.arguments as { reason?: unknown };
298
+ try {
299
+ const suite = await runLiveIntegrationSuite({
300
+ toolDir: dirname(opts.workflowPath),
301
+ logPath: opts.logPath,
242
302
  attempt: opts.attempt,
243
- reason: input.reason,
244
- forceReprobe: input.forceReprobe === true,
303
+ reason: typeof input.reason === 'string' ? input.reason : undefined,
304
+ sessionLabel: opts.sessionLabel,
305
+ signal: active.signal,
245
306
  });
307
+ return { content: [{ type: 'text', text: JSON.stringify(suite) }] };
308
+ } catch (error) {
309
+ rethrowProviderControl(error);
310
+ return errorResult(error instanceof Error ? error.message : String(error));
246
311
  }
247
- const result = await preparation.promise;
248
- return { content: [{ type: 'text', text: JSON.stringify(result) }] };
249
- } catch (error) {
250
- return errorResult(error instanceof Error ? error.message : String(error));
251
312
  }
252
- }
253
- if (request.params.name === 'run_live_integration_suite') {
254
- const input = request.params.arguments as { reason?: unknown };
255
- try {
256
- const suite = await runLiveIntegrationSuite({
257
- toolDir: dirname(opts.workflowPath),
258
- logPath: opts.logPath,
313
+ if (request.params.name === 'run_live_integration_test') {
314
+ if (!hasSuiteReceipt())
315
+ return errorResult('run the final integration suite before a targeted call');
316
+ const input = request.params.arguments as { params?: unknown; reason?: unknown };
317
+ if (typeof input.reason !== 'string' || !input.reason.trim()) {
318
+ return errorResult('reason must explain the unresolved semantic question');
319
+ }
320
+ const parsed = validator.safeParse(input.params ?? {});
321
+ if (!parsed.success) return errorResult(`invalid tool params: ${parsed.error.message}`);
322
+ const label = `targeted-call-${++targetedCallSequence}`;
323
+ const startedAt = Date.now();
324
+ appendLiveVerifierLog(opts.logPath, {
325
+ type: 'targeted-call.started',
259
326
  attempt: opts.attempt,
260
- reason: typeof input.reason === 'string' ? input.reason : undefined,
261
- sessionLabel: opts.sessionLabel,
327
+ label,
328
+ reason: input.reason,
329
+ params: parsed.data,
262
330
  });
263
- return { content: [{ type: 'text', text: JSON.stringify(suite) }] };
264
- } catch (error) {
265
- return errorResult(error instanceof Error ? error.message : String(error));
266
- }
267
- }
268
- if (request.params.name === 'run_live_integration_test') {
269
- if (!hasSuiteReceipt())
270
- return errorResult('run the final integration suite before a targeted call');
271
- const input = request.params.arguments as { params?: unknown; reason?: unknown };
272
- if (typeof input.reason !== 'string' || !input.reason.trim()) {
273
- return errorResult('reason must explain the unresolved semantic question');
274
- }
275
- const parsed = validator.safeParse(input.params ?? {});
276
- if (!parsed.success) return errorResult(`invalid tool params: ${parsed.error.message}`);
277
- const label = `targeted-call-${++targetedCallSequence}`;
278
- const startedAt = Date.now();
279
- appendLiveVerifierLog(opts.logPath, {
280
- type: 'targeted-call.started',
281
- attempt: opts.attempt,
282
- label,
283
- reason: input.reason,
284
- params: parsed.data,
285
- });
286
- let run: Awaited<ReturnType<typeof runCapturedIntegrationCase>>;
287
- try {
288
- run = await runCapturedIntegrationCase({
331
+ let run: Awaited<ReturnType<typeof runCapturedIntegrationCase>>;
332
+ try {
333
+ run = await runCapturedIntegrationCase({
334
+ caseName: label,
335
+ workflowPath: opts.workflowPath,
336
+ params: parsed.data as Record<string, string | number | boolean>,
337
+ preferredOnlyBackend: true,
338
+ deadlineMs: runDeadline?.deadlineMs,
339
+ signal: active.signal,
340
+ });
341
+ } catch (error) {
342
+ rethrowProviderControl(error);
343
+ const message = error instanceof Error ? error.message : String(error);
344
+ appendLiveVerifierLog(opts.logPath, {
345
+ type: 'targeted-call.failed',
346
+ attempt: opts.attempt,
347
+ label,
348
+ error: message,
349
+ });
350
+ return errorResult(message);
351
+ }
352
+ const supplemental: LiveIntegrationEvidence = {
353
+ schemaVersion: 1 as const,
354
+ kind: 'call',
355
+ label,
289
356
  caseName: label,
290
- workflowPath: opts.workflowPath,
291
- params: parsed.data as Record<string, string | number | boolean>,
292
- preferredOnlyBackend: true,
293
- });
294
- } catch (error) {
295
- const message = error instanceof Error ? error.message : String(error);
357
+ toolName: workflow.toolName,
358
+ requestedParams: parsed.data as Record<string, string | number | boolean>,
359
+ effectiveParams: effectiveParamsForEvidence(
360
+ workflow.parameters,
361
+ parsed.data as Record<string, string | number | boolean>,
362
+ ),
363
+ result: run.result,
364
+ usedBackend: run.usedBackend,
365
+ attempts: run.attempts,
366
+ durationMs: Date.now() - startedAt,
367
+ };
368
+ persistLiveVerificationEvidence(evidencePath, [supplemental]);
296
369
  appendLiveVerifierLog(opts.logPath, {
297
- type: 'targeted-call.failed',
370
+ type: 'targeted-call.completed',
298
371
  attempt: opts.attempt,
299
- label,
300
- error: message,
372
+ record: supplemental,
301
373
  });
302
- return errorResult(message);
303
- }
304
- const supplemental: LiveIntegrationEvidence = {
305
- schemaVersion: 1 as const,
306
- kind: 'call',
307
- label,
308
- caseName: label,
309
- toolName: workflow.toolName,
310
- requestedParams: parsed.data as Record<string, string | number | boolean>,
311
- effectiveParams: effectiveParamsForEvidence(
312
- workflow.parameters,
313
- parsed.data as Record<string, string | number | boolean>,
314
- ),
315
- result: run.result,
316
- usedBackend: run.usedBackend,
317
- attempts: run.attempts,
318
- durationMs: Date.now() - startedAt,
319
- };
320
- persistLiveVerificationEvidence(evidencePath, [supplemental]);
321
- appendLiveVerifierLog(opts.logPath, {
322
- type: 'targeted-call.completed',
323
- attempt: opts.attempt,
324
- record: supplemental,
325
- });
326
- return {
327
- content: [
328
- {
329
- type: 'text',
330
- text: JSON.stringify({
331
- label: supplemental.label,
332
- toolName: workflow.toolName,
333
- requestedParams: parsed.data,
334
- result: run.result,
335
- usedBackend: run.usedBackend,
336
- attempts: run.attempts,
337
- }),
338
- },
339
- ],
340
- };
341
- }
342
- if (request.params.name === 'submit_verification_report') {
343
- if (submitted) return errorResult('verification report was already submitted');
344
- const parsed = LiveVerificationReportSchema.safeParse(request.params.arguments);
345
- if (!parsed.success)
346
- return errorResult(`invalid verification report: ${parsed.error.message}`);
347
- if (!hasSuiteReceipt()) {
348
- return errorResult('run the final integration suite before submitting');
374
+ return {
375
+ content: [
376
+ {
377
+ type: 'text',
378
+ text: JSON.stringify({
379
+ label: supplemental.label,
380
+ toolName: workflow.toolName,
381
+ requestedParams: parsed.data,
382
+ result: run.result,
383
+ usedBackend: run.usedBackend,
384
+ attempts: run.attempts,
385
+ }),
386
+ },
387
+ ],
388
+ };
349
389
  }
350
- try {
351
- assertReportCoversWorkflowParameters(parsed.data, workflow.parameters);
352
- } catch (error) {
353
- return errorResult(error instanceof Error ? error.message : String(error));
390
+ if (request.params.name === 'submit_verification_report') {
391
+ if (submitted) return errorResult('verification report was already submitted');
392
+ const parsed = LiveVerificationReportSchema.safeParse(request.params.arguments);
393
+ if (!parsed.success)
394
+ return errorResult(`invalid verification report: ${parsed.error.message}`);
395
+ if (!hasSuiteReceipt()) {
396
+ return errorResult('run the final integration suite before submitting');
397
+ }
398
+ try {
399
+ assertReportCoversWorkflowParameters(parsed.data, workflow.parameters);
400
+ } catch (error) {
401
+ return errorResult(error instanceof Error ? error.message : String(error));
402
+ }
403
+ submitted = true;
404
+ appendLiveVerifierLog(opts.logPath, {
405
+ type: 'report.submitted',
406
+ attempt: opts.attempt,
407
+ report: parsed.data,
408
+ });
409
+ writeFileSync(opts.reportPath, `${JSON.stringify(parsed.data, null, 2)}\n`, {
410
+ encoding: 'utf8',
411
+ mode: 0o600,
412
+ });
413
+ return {
414
+ content: [{ type: 'text', text: 'Report accepted. End the verification session now.' }],
415
+ };
354
416
  }
355
- submitted = true;
356
- appendLiveVerifierLog(opts.logPath, {
357
- type: 'report.submitted',
358
- attempt: opts.attempt,
359
- report: parsed.data,
360
- });
361
- writeFileSync(opts.reportPath, `${JSON.stringify(parsed.data, null, 2)}\n`, {
362
- encoding: 'utf8',
363
- mode: 0o600,
417
+ return errorResult(`unknown tool: ${request.params.name}`);
418
+ });
419
+ const transport = new StdioServerTransport();
420
+ let closeLifetime: (() => void) | undefined;
421
+ try {
422
+ await server.connect(transport);
423
+
424
+ // Server.connect() resolves after initialization; it does not own the
425
+ // process lifetime. Keep stdio alive until the verifier disconnects, just
426
+ // like the compile MCP server does, or Codex can lose the server during its
427
+ // initialize handshake.
428
+ await new Promise<void>((resolve) => {
429
+ closeLifetime = resolve;
430
+ transport.onclose = closeLifetime;
431
+ active.signal?.addEventListener('abort', closeLifetime, { once: true });
364
432
  });
365
- return {
366
- content: [{ type: 'text', text: 'Report accepted. End the verification session now.' }],
367
- };
433
+ } finally {
434
+ if (closeLifetime) active.signal?.removeEventListener('abort', closeLifetime);
435
+ transport.onclose = undefined;
436
+ await server.close().catch(() => undefined);
368
437
  }
369
- return errorResult(`unknown tool: ${request.params.name}`);
370
- });
371
- const transport = new StdioServerTransport();
372
- await server.connect(transport);
373
-
374
- // Server.connect() resolves after initialization; it does not own the
375
- // process lifetime. Keep stdio alive until the verifier disconnects, just
376
- // like the compile MCP server does, or Codex can lose the server during its
377
- // initialize handshake.
378
- try {
379
- await new Promise<void>((resolve) => {
380
- const close = (): void => resolve();
381
- transport.onclose = close;
382
- process.once('SIGINT', close);
383
- process.once('SIGTERM', close);
384
- });
385
438
  } finally {
439
+ active.dispose();
440
+ inheritedControl?.dispose();
441
+ for (const [signal, handler] of processHandlers) process.removeListener(signal, handler);
386
442
  await authSession?.close();
387
443
  }
388
444
  }
@@ -17,10 +17,10 @@ import {
17
17
  ListToolsRequestSchema,
18
18
  type Tool,
19
19
  } from '@modelcontextprotocol/sdk/types.js';
20
- import { resolveLadder, runWithLadder } from './backend-ladder.ts';
21
- import type { CdpBrowserFetch } from './cdp-browser-fetch.ts';
20
+ import { type BackendAttemptFact, resolveLadder, runWithLadder } from './backend-ladder.ts';
22
21
  import { TimeoutError, withTimeoutCleanup } from './concurrency.ts';
23
22
  import { createLog } from './log.ts';
23
+ import { McpCdpSessions } from './mcp-cdp-sessions.ts';
24
24
  import { imprintHomeDir } from './paths.ts';
25
25
  import { loadBackendsCacheStatus, persistRuntimeBackendsCache } from './probe-backends.ts';
26
26
  import { checkSiteCredentialsReady } from './runtime.ts';
@@ -221,26 +221,18 @@ function buildServer(
221
221
  // Per-site stealth-fetch cache so the ~12s bootstrap runs once per site.
222
222
  const stealthCache = new Map<string, StealthFetch>();
223
223
 
224
- // Per-site CDP browser pool: cdp-replay stores its live Chrome here after
225
- // the first successful call so subsequent calls reuse it (~2-5s vs ~33s).
226
- const cdpPool = new Map<string, CdpBrowserFetch>();
227
- const cdpIdleTimers = new Map<string, ReturnType<typeof setTimeout>>();
224
+ const cdpSessions = new McpCdpSessions();
225
+ const cdpPool = cdpSessions.pool;
228
226
  const authContinuations = new AuthContinuationStore();
229
- const CDP_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
230
227
 
231
228
  // Per-tool memo of the winning backend for THIS server session. After the
232
229
  // first call discovers the right rung, later calls skip the doomed early ones
233
- // (e.g. southwest's ~80s fetch-bootstrap FORBIDDEN before cdp-replay wins). Its
234
- // lifetime is tied to `cdpPool`: the memoized cdp-replay is only cheap while
235
- // its Chrome is pooled, so a site's memo is evicted when that pool entry is
236
- // idle-closed (below) — otherwise the next call would start at a now-cold
237
- // cdp-replay and re-pay the ~33s relaunch.
238
- const winnerCache = new Map<string, ConcreteBackend>();
239
-
240
- // Browser-backed rungs share per-site state (CDP page/session, stealth token,
241
- // winner memo, and backend cache). Parallel MCP calls can race that state and
242
- // make Google Flights return fast empty result sets. Keep same-site execution
243
- // sequential while allowing unrelated sites to proceed independently.
230
+ // Its lifetime follows that tool's CDP sessions: idle/timeout cleanup clears
231
+ // only the affected tool's memo.
232
+ const winnerCache = cdpSessions.winners;
233
+
234
+ // Keep same-site calls sequential so concurrent calls cannot race a tool's
235
+ // browser, winner memo, or backend cache. Unrelated sites remain independent.
244
236
  const siteExecutionQueues = new Map<string, Promise<void>>();
245
237
 
246
238
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -316,10 +308,13 @@ function buildServer(
316
308
  }
317
309
 
318
310
  const ladder = resolveLadder('auto', tool.preferredOrder);
311
+ cdpSessions.beginCall(tool.site, tool.workflow.toolName);
312
+ const execution = new AbortController();
319
313
  const run = runWithLadder(ladder, tool, args, assetRoot, stealthCache, {
320
314
  cdpPool,
321
315
  winnerCache,
322
316
  initialState,
317
+ signal: execution.signal,
323
318
  });
324
319
  const auditDeadlineMs = auditToolDeadlineMs();
325
320
  let result: ToolResult;
@@ -332,14 +327,8 @@ function buildServer(
332
327
  auditDeadlineMs,
333
328
  `${tool.workflow.toolName} audit MCP call`,
334
329
  () => {
335
- const cf = cdpPool.get(tool.site);
336
- if (cf) {
337
- cdpPool.delete(tool.site);
338
- cf.close().catch(() => {});
339
- }
340
- for (const key of winnerCache.keys()) {
341
- if (key.startsWith(`${tool.site}:`)) winnerCache.delete(key);
342
- }
330
+ execution.abort();
331
+ void cdpSessions.closeTool(tool.site, tool.workflow.toolName);
343
332
  },
344
333
  )
345
334
  : await run;
@@ -355,27 +344,8 @@ function buildServer(
355
344
  error: 'NETWORK',
356
345
  message: `${tool.workflow.toolName} exceeded the audit MCP internal deadline after ${Math.round((auditDeadlineMs ?? 0) / 1000)}s`,
357
346
  };
358
- }
359
- // Reset the idle timer for this site's pooled Chrome.
360
- if (result.ok && usedBackend === 'cdp-replay' && cdpPool.has(tool.site)) {
361
- const prev = cdpIdleTimers.get(tool.site);
362
- if (prev) clearTimeout(prev);
363
- const timer = setTimeout(() => {
364
- const cf = cdpPool.get(tool.site);
365
- if (cf) {
366
- log(`closing idle CDP session for ${tool.site}`);
367
- cf.close().catch(() => {});
368
- cdpPool.delete(tool.site);
369
- cdpIdleTimers.delete(tool.site);
370
- // Drop this site's winner memo too: a memoized cdp-replay would now
371
- // point at a closed Chrome and re-pay the cold relaunch.
372
- for (const key of winnerCache.keys()) {
373
- if (key.startsWith(`${tool.site}:`)) winnerCache.delete(key);
374
- }
375
- }
376
- }, CDP_IDLE_TIMEOUT_MS);
377
- timer.unref();
378
- cdpIdleTimers.set(tool.site, timer);
347
+ } finally {
348
+ cdpSessions.finishCall(tool.site, tool.workflow.toolName);
379
349
  }
380
350
  if (!result.ok) {
381
351
  const continuationToken =
@@ -387,7 +357,7 @@ function buildServer(
387
357
  state: result.continuation,
388
358
  })
389
359
  : undefined;
390
- const text = formatToolError(result, continuationToken);
360
+ const text = formatToolError(result, continuationToken, attempts);
391
361
  return {
392
362
  isError: true,
393
363
  content: [{ type: 'text', text: `${text}\n(backend: ${usedBackend})` }],
@@ -417,23 +387,17 @@ function buildServer(
417
387
  });
418
388
 
419
389
  async function closeCdpPool(): Promise<void> {
420
- for (const [site, cf] of cdpPool) {
421
- log(`shutdown: closing CDP session for ${site}`);
422
- await cf.close().catch(() => {});
423
- }
424
- cdpPool.clear();
425
- for (const timer of cdpIdleTimers.values()) clearTimeout(timer);
426
- cdpIdleTimers.clear();
427
- winnerCache.clear();
390
+ await cdpSessions.closeAll();
428
391
  authContinuations.clear();
429
392
  }
430
393
 
431
394
  return { server, closeCdpPool };
432
395
  }
433
396
 
434
- function formatToolError(
397
+ export function formatToolError(
435
398
  result: Extract<ToolResult, { ok: false }>,
436
399
  continuationToken?: string,
400
+ attempts: readonly BackendAttemptFact[] = [],
437
401
  ): string {
438
402
  const lines = [`[${result.error}] ${result.message}`];
439
403
  if (result.error === 'STATE_MISSING' && result.missing?.length) {
@@ -446,6 +410,31 @@ function formatToolError(
446
410
  if (result.nextAction) lines.push(` nextAction: ${result.nextAction}`);
447
411
  if (continuationToken) lines.push(` continuation: ${JSON.stringify(continuationToken)}`);
448
412
  if (result.remediation) lines.push(` → ${result.remediation}`);
413
+ if (result.pageDiagnostic) {
414
+ const page = result.pageDiagnostic;
415
+ lines.push(
416
+ `Rendered page observed after a failed browser call (possibly before fallback; not the requested API response): ${JSON.stringify(
417
+ {
418
+ url: page.url.slice(0, 300),
419
+ title: page.title.slice(0, 300),
420
+ bodyText: page.bodyText.slice(0, 3_000),
421
+ truncated:
422
+ page.truncated ||
423
+ page.url.length > 300 ||
424
+ page.title.length > 300 ||
425
+ page.bodyText.length > 3_000,
426
+ },
427
+ )}`,
428
+ );
429
+ }
430
+ if (attempts.length > 0) {
431
+ lines.push('Backend attempts:');
432
+ for (const attempt of attempts) {
433
+ lines.push(
434
+ ` - ${attempt.backend}: ${attempt.outcome} in ${attempt.durationMs}ms — ${attempt.detail}`,
435
+ );
436
+ }
437
+ }
449
438
  return lines.join('\n');
450
439
  }
451
440