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
@@ -14,8 +14,7 @@
14
14
  * loss.
15
15
  */
16
16
 
17
- import { createHash, randomUUID } from 'node:crypto';
18
- import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
17
+ import { readFileSync, writeFileSync } from 'node:fs';
19
18
  import { join as pathJoin } from 'node:path';
20
19
  import { Server } from '@modelcontextprotocol/sdk/server/index.js';
21
20
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -30,15 +29,14 @@ import {
30
29
  authWorkflowPreflightFailures,
31
30
  buildAuthCompileTools,
32
31
  } from './auth-compile-tools.ts';
32
+ import type { AuthToolPlan, SharedModuleManifestEntry } from './build-plan.ts';
33
33
  import {
34
- type AuthToolPlan,
35
- type SharedModuleManifestEntry,
36
- resolvePlanSliceFromFile,
37
- } from './build-plan.ts';
38
- import {
34
+ type CompileVerificationMode,
39
35
  advanceIncompleteSemanticVerificationRuns,
40
36
  advanceSemanticVerificationCycle,
41
37
  } from './compile-agent-types.ts';
38
+ import { inheritedCompileProviderControl } from './compile-provider-control.ts';
39
+ import type { CompileStrategyKind } from './compile-strategy.ts';
42
40
  import {
43
41
  applyIrreversibleVerificationWaiver,
44
42
  applyLiveVerification,
@@ -46,9 +44,10 @@ import {
46
44
  buildCompileTools,
47
45
  externalVerification,
48
46
  } from './compile-tools.ts';
47
+ import { terminateOwnedCompilerProcesses } from './compiler-process.ts';
48
+ import { extractCredentials } from './credential-extract.ts';
49
49
  import { workflowHasIrreversibleEffect } from './effects.ts';
50
50
  import {
51
- isInfrastructureOnlyInconclusiveReport,
52
51
  mergeSemanticParamVerification,
53
52
  runLiveSemanticVerification,
54
53
  semanticVerificationFailures,
@@ -58,16 +57,21 @@ import type { ProviderName } from './llm.ts';
58
57
  import { loadJsonFile } from './load-json.ts';
59
58
  import { createLog } from './log.ts';
60
59
  import { rebindExistingBackendsCacheToWorkflow } from './probe-backends.ts';
60
+ import {
61
+ ProviderDeadlineError,
62
+ ProviderUnavailableError,
63
+ combinedDeadlineSignal,
64
+ providerControlError,
65
+ } from './provider-retry.ts';
61
66
  import { redactSession } from './redact.ts';
62
- import { loadCredentialStore } from './runtime.ts';
63
67
  import type { SharedCompileContext, ToolCandidate } from './tool-candidates.ts';
64
68
  import { type SharedTriageSelection, applySharedTriageSelection } from './triage-selection.ts';
65
- import { type Session, SessionSchema, WorkflowSchema } from './types.ts';
69
+ import { type Session, SessionSchema, type Workflow, WorkflowSchema } from './types.ts';
66
70
 
67
71
  const log = createLog('mcp-compile');
68
72
 
69
73
  interface RunCompileMcpServerOptions {
70
- /** Path to the recorded session JSON. */
74
+ /** Agent-facing focused/redacted recording. */
71
75
  sessionPath: string;
72
76
  /** Absolute path to the generated tool directory where artifacts go. */
73
77
  toolDir: string;
@@ -79,6 +83,8 @@ interface RunCompileMcpServerOptions {
79
83
  buildPlanPath?: string;
80
84
  /** Shared-module build manifest for this site (verified flags). */
81
85
  sharedModules?: SharedModuleManifestEntry[];
86
+ /** Master-accepted execution strategy for this focused compile. */
87
+ strategyKind?: CompileStrategyKind;
82
88
  /** Present → run in AUTH mode: register the auth checkpoint toolset
83
89
  * and run authExternalVerification in done() instead of the data-tool
84
90
  * verification. */
@@ -91,6 +97,8 @@ interface RunCompileMcpServerOptions {
91
97
  provider?: ProviderName;
92
98
  /** Bounded resume of an already-generated data tool. */
93
99
  revisionMode?: boolean;
100
+ /** Master-only deterministic MVP boundary. */
101
+ verificationMode?: CompileVerificationMode;
94
102
  /** Shared triage result from teach. Applied before compile tools and done()
95
103
  * verification so CLI-backed compilers see irreversible effects. */
96
104
  sharedTriageSelection?: SharedTriageSelection;
@@ -102,473 +110,334 @@ const VERIFICATION_STATE_SENTINEL = '.compile-verification-state.json';
102
110
  // Keep the compile watchdog from charging live verification against the model's
103
111
  // reasoning budget, while retaining a hard bound if the MCP server dies during
104
112
  // done(). This matches the longest supported MCP tool call.
105
- const MAX_VERIFICATION_WALL_TIME_MS = 30 * 60_000;
106
113
  /** Auth mode only: a mid-loop checkpoint the agent reaches. The tool records
107
114
  * the request here and the
108
115
  * agent STOPS; the orchestrator (teach) performs the action and resumes the
109
116
  * agent (`claude --resume`) with the result. One pending checkpoint per segment. */
110
117
  const CHECKPOINT_SENTINEL = '.compile-checkpoint.json';
111
118
 
112
- const COMPILE_ARTIFACT_FILES = [
113
- 'workflow.json',
114
- 'parser.ts',
115
- 'parser.test.ts',
116
- 'request.test.ts',
117
- 'integration.test.ts',
118
- 'request-transform.ts',
119
- 'playbook.yaml',
120
- ] as const;
121
-
122
- interface PendingInconclusiveDecision {
123
- artifactFingerprint: string;
124
- report: Awaited<ReturnType<typeof runLiveSemanticVerification>>;
119
+ /** An irreversible workflow may skip live execution only after every
120
+ * deterministic artifact check passed. Keep this conjunction explicit: the
121
+ * waiver changes only live applicability, never deterministic correctness. */
122
+ export function canWaiveIrreversibleLiveVerification(
123
+ failures: readonly string[],
124
+ workflow: Workflow | undefined,
125
+ ): workflow is Workflow {
126
+ return failures.length === 0 && workflow !== undefined && workflowHasIrreversibleEffect(workflow);
125
127
  }
126
128
 
127
- interface CompileVerificationState {
128
- excludedMs: number;
129
- activeSinceMs?: number;
130
- activeUntilMs?: number;
129
+ export function compileDoneToolDescription(mode?: CompileVerificationMode): string {
130
+ return mode === 'master_mvp'
131
+ ? 'Call this after completing the artifact and its offline tests. Validates deterministic artifact, schema, test, and type facts, then hands the artifact back to the master for live verification. Fix any returned deterministic failures and call done again.'
132
+ : 'Call this when you have successfully completed the task. Continues through independent external verification of the artifacts. If verification fails, the result will list the issues and you should fix them and call done again.';
131
133
  }
132
134
 
133
- function readCompileVerificationState(toolDir: string): CompileVerificationState {
134
- try {
135
- const parsed = JSON.parse(
136
- readFileSync(pathJoin(toolDir, VERIFICATION_STATE_SENTINEL), 'utf8'),
137
- ) as Partial<CompileVerificationState>;
138
- return {
139
- excludedMs:
140
- typeof parsed.excludedMs === 'number' && Number.isFinite(parsed.excludedMs)
141
- ? Math.max(0, parsed.excludedMs)
142
- : 0,
143
- activeSinceMs:
144
- typeof parsed.activeSinceMs === 'number' && Number.isFinite(parsed.activeSinceMs)
145
- ? parsed.activeSinceMs
146
- : undefined,
147
- activeUntilMs:
148
- typeof parsed.activeUntilMs === 'number' && Number.isFinite(parsed.activeUntilMs)
149
- ? parsed.activeUntilMs
150
- : undefined,
135
+ export async function runCompileMcpServer(opts: RunCompileMcpServerOptions): Promise<void> {
136
+ const providerControl = inheritedCompileProviderControl();
137
+ const lifetime = new AbortController();
138
+ const active = combinedDeadlineSignal(providerControl?.deadline, undefined, lifetime.signal);
139
+ const lifetimeHandlers = new Map<NodeJS.Signals, () => void>();
140
+ for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
141
+ const handler = (): void => {
142
+ lifetime.abort(new DOMException(`Compile MCP received ${signal}`, 'AbortError'));
143
+ void terminateOwnedCompilerProcesses(signal).then(() => {
144
+ if (signal === 'SIGINT') return;
145
+ process.removeListener(signal, handler);
146
+ process.kill(process.pid, signal);
147
+ });
151
148
  };
152
- } catch {
153
- return { excludedMs: 0 };
149
+ lifetimeHandlers.set(signal, handler);
150
+ process.once(signal, handler);
154
151
  }
155
- }
156
-
157
- function writeCompileVerificationState(toolDir: string, state: CompileVerificationState): void {
158
- const destination = pathJoin(toolDir, VERIFICATION_STATE_SENTINEL);
159
- const temporary = pathJoin(
160
- toolDir,
161
- `${VERIFICATION_STATE_SENTINEL}.${process.pid}.${randomUUID()}.tmp`,
162
- );
163
152
  try {
164
- writeFileSync(temporary, `${JSON.stringify(state)}\n`, {
165
- encoding: 'utf8',
166
- flag: 'wx',
167
- mode: 0o600,
168
- });
169
- renameSync(temporary, destination);
170
- } finally {
171
- // rename removes the source on success; clean up a partial temp file if a
172
- // write or rename fails without disturbing the last complete state.
173
- if (existsSync(temporary)) unlinkSync(temporary);
174
- }
175
- }
176
-
177
- function beginCompileVerification(toolDir: string): () => void {
178
- const previous = readCompileVerificationState(toolDir);
179
- const startedAt = Date.now();
180
- writeCompileVerificationState(toolDir, {
181
- excludedMs: previous.excludedMs,
182
- activeSinceMs: startedAt,
183
- activeUntilMs: startedAt + MAX_VERIFICATION_WALL_TIME_MS,
184
- });
185
- return () => {
186
- const finishedAt = Date.now();
187
- writeCompileVerificationState(toolDir, {
188
- excludedMs:
189
- previous.excludedMs +
190
- Math.min(MAX_VERIFICATION_WALL_TIME_MS, Math.max(0, finishedAt - startedAt)),
191
- });
192
- };
193
- }
194
-
195
- /** Effective compiler deadline after excluding bounded time spent inside done()
196
- * verification. Exported for the CLI watchdogs and focused lifecycle tests. */
197
- export function compileDeadlineAfterVerification(
198
- toolDir: string,
199
- compilerDeadlineMs: number,
200
- now = Date.now(),
201
- ): number {
202
- const state = readCompileVerificationState(toolDir);
203
- const activeElapsedMs =
204
- state.activeSinceMs === undefined
205
- ? 0
206
- : Math.max(
207
- 0,
208
- Math.min(now, state.activeUntilMs ?? state.activeSinceMs) - state.activeSinceMs,
209
- );
210
- return compilerDeadlineMs + state.excludedMs + activeElapsedMs;
211
- }
212
-
213
- export function compileArtifactFingerprint(toolDir: string): string {
214
- const hash = createHash('sha256');
215
- for (const relativePath of COMPILE_ARTIFACT_FILES) {
216
- const absolutePath = pathJoin(toolDir, relativePath);
217
- hash.update(relativePath);
218
- hash.update('\0');
219
- if (existsSync(absolutePath)) hash.update(readFileSync(absolutePath));
220
- hash.update('\0');
221
- }
222
- return hash.digest('hex');
223
- }
224
-
225
- export function canAcceptInconclusiveDecision(opts: {
226
- semanticVerificationCycles: number;
227
- maxVerificationCycles: number;
228
- completedReview: boolean;
229
- infrastructureOnly: boolean;
230
- pendingFingerprint?: string;
231
- currentFingerprint: string;
232
- acceptInconclusive?: boolean;
233
- inconclusiveReason?: string;
234
- }): boolean {
235
- return (
236
- opts.completedReview &&
237
- opts.infrastructureOnly &&
238
- opts.semanticVerificationCycles >= opts.maxVerificationCycles &&
239
- opts.acceptInconclusive === true &&
240
- Boolean(opts.inconclusiveReason?.trim()) &&
241
- opts.pendingFingerprint === opts.currentFingerprint
242
- );
243
- }
244
-
245
- export function inconclusiveDecisionAtSemanticCap(opts: {
246
- semanticVerificationCycles: number;
247
- maxVerificationCycles: number;
248
- pendingFingerprint?: string;
249
- currentFingerprint: string;
250
- }): 'continue-verification' | 'await-compiler-decision' | 'fail-artifact-changed' {
251
- if (!opts.pendingFingerprint || opts.semanticVerificationCycles < opts.maxVerificationCycles) {
252
- return 'continue-verification';
253
- }
254
- return opts.pendingFingerprint === opts.currentFingerprint
255
- ? 'await-compiler-decision'
256
- : 'fail-artifact-changed';
257
- }
258
-
259
- export async function runCompileMcpServer(opts: RunCompileMcpServerOptions): Promise<void> {
260
- const isAuthMode = !!opts.authToolPlan;
261
- const maxVerificationCycles = opts.maxVerificationCycles ?? 5;
262
- const maxIncompleteVerifierRuns = 2;
263
- let pendingInconclusive: PendingInconclusiveDecision | undefined;
264
- let incompleteVerifierRuns = 0;
265
-
266
- // Load + auto-redact the session, exactly as compile-agent.ts does.
267
- let session: Session = loadJsonFile(
268
- opts.sessionPath,
269
- SessionSchema,
270
- {
271
- notFound: '→ run `imprint record <site>` to create one.',
272
- notJson: `→ if it's a partial .jsonl, run \`imprint assemble ${opts.sessionPath}\` first.`,
273
- badSchema: '→ check the file came from `imprint record`.',
274
- },
275
- 'session',
276
- );
277
- const looksRedacted = JSON.stringify(session).includes('[REDACTED:');
278
- if (!looksRedacted) {
279
- session = redactSession(session).session;
280
- }
281
- if (opts.sharedTriageSelection) {
282
- session = applySharedTriageSelection(session, opts.sharedTriageSelection, {
283
- candidate: opts.candidate,
284
- sharedContext: opts.sharedContext,
285
- });
286
- }
287
-
288
- // Build the toolset. Auth mode swaps the data tools (parser/test-oriented)
289
- // for the auth toolset, which lives in auth-compile-tools.ts so the in-process
290
- // loop and this MCP path stay byte-for-byte identical.
291
- type PlanSlice = ReturnType<typeof resolvePlanSliceFromFile>;
292
- let compileTools: ReturnType<typeof buildCompileTools>;
293
- let assignedSharedModules: PlanSlice['assignedSharedModules'] = [];
294
- let tokenParams: PlanSlice['tokenParams'] = [];
295
- let tokenParamShapes: PlanSlice['tokenParamShapes'] = [];
296
- let emittedTokens: PlanSlice['emittedTokens'] = [];
297
- let requiredInputs: PlanSlice['requiredInputs'] = [];
298
- let credentialValues: Record<string, string> = {};
299
-
300
- if (isAuthMode) {
301
- const site = opts.site ?? session.site;
302
- // Credentials power the orchestrator-owned live verifier. Load them here
303
- // rather than passing secrets on the command line.
304
- const creds = await loadCredentialStore(site);
305
- const teachCredentials = { site, values: creds?.values ?? {} };
306
- compileTools = buildAuthCompileTools(session, opts.toolDir, opts.sessionPath, teachCredentials);
307
- } else {
308
- // When a build plan is present, buildCompileTools also exposes read_build_plan.
309
- compileTools = buildCompileTools(session, opts.toolDir, opts.sessionPath, {
310
- candidate: opts.candidate,
311
- sharedContext: opts.sharedContext,
312
- buildPlanPath: opts.buildPlanPath,
313
- sharedModules: opts.sharedModules,
314
- revisionMode: opts.revisionMode,
315
- });
153
+ const isAuthMode = !!opts.authToolPlan;
154
+ const maxVerificationCycles = opts.maxVerificationCycles ?? 5;
155
+ const maxIncompleteVerifierRuns = 2;
156
+ let incompleteVerifierRuns = 0;
157
+
158
+ // Load the recording supplied by the compile host. Teach normally passes a
159
+ // redacted session; direct compilation still applies ordinary in-memory
160
+ // redaction before exposing request evidence through compile tools.
161
+ let session: Session = loadJsonFile(
162
+ opts.sessionPath,
163
+ SessionSchema,
164
+ {
165
+ notFound: '→ run `imprint record <site>` to create one.',
166
+ notJson: `→ if it's a partial .jsonl, run \`imprint assemble ${opts.sessionPath}\` first.`,
167
+ badSchema: '→ check the file came from `imprint record`.',
168
+ },
169
+ 'session',
170
+ );
171
+ if (!JSON.stringify(session).includes('[REDACTED:')) {
172
+ session = redactSession(session, {
173
+ replacements: extractCredentials(session).replacements,
174
+ }).session;
175
+ }
176
+ if (opts.sharedTriageSelection) {
177
+ session = applySharedTriageSelection(session, opts.sharedTriageSelection, {
178
+ candidate: opts.candidate,
179
+ sharedContext: opts.sharedContext,
180
+ });
181
+ }
316
182
 
317
- // Resolve the shared modules + producer→consumer token contracts + the general
318
- // dependency contract the plan assigned this tool, so verification can assert
319
- // modules are imported, require a chained test for each producer-sourced token
320
- // param, and inject/gate the contracted inputs.
321
- ({ assignedSharedModules, tokenParams, tokenParamShapes, emittedTokens, requiredInputs } =
322
- resolvePlanSliceFromFile(opts.buildPlanPath, opts.candidate?.toolName, opts.sharedModules));
323
- // Credential values for the emit-time secret guard (loaded for the data path,
324
- // never passed on argv).
325
- const creds = await loadCredentialStore(opts.site ?? session.site);
326
- credentialValues = creds?.values ?? {};
327
- }
183
+ // Build the toolset. Auth mode swaps the data tools (parser/test-oriented)
184
+ // for the auth toolset, which lives in auth-compile-tools.ts so the in-process
185
+ // loop and this MCP path stay byte-for-byte identical.
186
+ let compileTools: ReturnType<typeof buildCompileTools>;
187
+ if (isAuthMode) {
188
+ const site = opts.site ?? session.site;
189
+ const teachCredentials = { site, values: {} };
190
+ compileTools = buildAuthCompileTools(
191
+ session,
192
+ opts.toolDir,
193
+ opts.sessionPath,
194
+ teachCredentials,
195
+ );
196
+ } else {
197
+ // When a build plan is present, buildCompileTools also exposes read_build_plan.
198
+ compileTools = buildCompileTools(session, opts.toolDir, opts.sessionPath, {
199
+ candidate: opts.candidate,
200
+ sharedContext: opts.sharedContext,
201
+ buildPlanPath: opts.buildPlanPath,
202
+ sharedModules: opts.sharedModules,
203
+ strategyKind: opts.strategyKind,
204
+ revisionMode: opts.revisionMode,
205
+ });
206
+ }
328
207
 
329
- // The custom done/give_up tools live alongside in MCP space.
330
- const doneTool: Tool = {
331
- name: 'done',
332
- description:
333
- 'Call this when you have successfully completed the task. Triggers external verification of the artifacts. If verification fails, the result will list the issues and you should fix them and call done again.',
334
- inputSchema: {
335
- type: 'object',
336
- properties: {
337
- summary: { type: 'string', description: 'Brief summary of what was accomplished' },
338
- accept_inconclusive: {
339
- type: 'boolean',
340
- description:
341
- 'After an infrastructure-only inconclusive verifier result, explicitly ship the unchanged deterministic artifact without a liveVerified stamp.',
342
- },
343
- inconclusive_reason: {
344
- type: 'string',
345
- description:
346
- 'Compiler reasoning for accepting the unchanged artifact after reviewing the inconclusive verifier evidence.',
208
+ // The custom done/give_up tools live alongside in MCP space.
209
+ const doneTool: Tool = {
210
+ name: 'done',
211
+ description: compileDoneToolDescription(opts.verificationMode),
212
+ inputSchema: {
213
+ type: 'object',
214
+ properties: {
215
+ summary: { type: 'string', description: 'Brief summary of what was accomplished' },
347
216
  },
217
+ required: ['summary'],
348
218
  },
349
- required: ['summary'],
350
- },
351
- };
352
- const giveUpTool: Tool = {
353
- name: 'give_up',
354
- description:
355
- 'Call this when you have encountered a categorical impossibility and cannot proceed.',
356
- inputSchema: {
357
- type: 'object',
358
- properties: {
359
- reason: { type: 'string', description: 'Why you cannot complete the task' },
360
- what_was_tried: {
361
- type: 'string',
362
- description: 'Summary of approaches you tried before giving up',
219
+ };
220
+ const giveUpTool: Tool = {
221
+ name: 'give_up',
222
+ description:
223
+ 'Use for a categorical impossibility or an exact accepted-plan contradiction that only the master can revise.',
224
+ inputSchema: {
225
+ type: 'object',
226
+ properties: {
227
+ reason: { type: 'string', description: 'Why you cannot complete the task' },
228
+ what_was_tried: {
229
+ type: 'string',
230
+ description: 'Summary of approaches you tried before giving up',
231
+ },
363
232
  },
233
+ required: ['reason', 'what_was_tried'],
364
234
  },
365
- required: ['reason', 'what_was_tried'],
366
- },
367
- };
368
-
369
- // Auth mode only: checkpoint tools. Each records its request to the checkpoint
370
- // sentinel and instructs the agent to STOP; the orchestrator performs the
371
- // action live (it owns the persistent browser session + the user TUI) and
372
- // resumes the agent with the result. The agent never runs a live login itself.
373
- const checkpointTools: Tool[] = isAuthMode
374
- ? [
375
- {
376
- name: 'run_verification',
377
- description:
378
- 'Run one action from the current workflow.json live in the verification browser. Supply the action name and only its declared parameters. Set freshSession only when observed evidence means the prior browser and continuation state must be discarded. Set cleanSession only when evidence requires also withholding stored cookies and browser storage. After calling this, stop; the orchestrator resumes you with the observed result.',
379
- inputSchema: {
380
- type: 'object',
381
- properties: {
382
- action: { type: 'string', description: 'An action declared in authConfig.actions.' },
383
- parameters: {
384
- type: 'object',
385
- description:
386
- 'Scalar values required by this action, keyed by workflow parameter name.',
387
- },
388
- freshSession: {
389
- type: 'boolean',
390
- description:
391
- 'Close and discard the prior verification browser and continuation state before running this action. Defaults to false.',
392
- },
393
- cleanSession: {
394
- type: 'boolean',
395
- description:
396
- 'Also withhold stored cookies and browser storage for this fresh run. Credential values remain available.',
235
+ };
236
+
237
+ // Auth mode only: checkpoint tools. Each records its request to the checkpoint
238
+ // sentinel and instructs the agent to STOP; the orchestrator performs the
239
+ // action live (it owns the persistent browser session + the user TUI) and
240
+ // resumes the agent with the result. The agent never runs a live login itself.
241
+ const checkpointTools: Tool[] = isAuthMode
242
+ ? [
243
+ {
244
+ name: 'run_verification',
245
+ description:
246
+ 'Run one action from the current workflow.json live in the verification browser. Supply the action name and only its declared parameters. Set freshSession only when observed evidence means the prior browser and continuation state must be discarded. Set cleanSession only when evidence requires also withholding stored cookies and browser storage. After calling this, stop; the orchestrator resumes you with the observed result.',
247
+ inputSchema: {
248
+ type: 'object',
249
+ properties: {
250
+ action: {
251
+ type: 'string',
252
+ description: 'An action declared in authConfig.actions.',
253
+ },
254
+ parameters: {
255
+ type: 'object',
256
+ description:
257
+ 'Scalar values required by this action, keyed by workflow parameter name.',
258
+ },
259
+ freshSession: {
260
+ type: 'boolean',
261
+ description:
262
+ 'Close and discard the prior verification browser and continuation state before running this action. Defaults to false.',
263
+ },
264
+ cleanSession: {
265
+ type: 'boolean',
266
+ description:
267
+ 'Also withhold stored cookies and browser storage for this fresh run. Credential values remain available.',
268
+ },
397
269
  },
270
+ required: ['action'],
398
271
  },
399
- required: ['action'],
400
272
  },
401
- },
402
- {
403
- name: 'inspect_verification_page',
404
- description:
405
- 'Inspect the currently rendered page in the existing verification browser without navigating, resetting state, or running another auth action. Returns rendered body text, final URL, title, and optional cookie metadata (never cookie values). Use when observed verification evidence warrants inspecting the page. After calling this, stop; the orchestrator resumes you with the snapshot.',
406
- inputSchema: {
407
- type: 'object',
408
- properties: {
409
- maxChars: {
410
- type: 'number',
411
- description: 'Maximum rendered body-text characters to return (256–20000).',
412
- },
413
- includeCookies: {
414
- type: 'boolean',
415
- description:
416
- 'Include cookie names, domains, paths, expirations, and flags. Cookie values are never returned. Defaults to true.',
273
+ {
274
+ name: 'inspect_verification_page',
275
+ description:
276
+ 'Inspect the currently rendered page in the existing verification browser without navigating, resetting state, or running another auth action. Returns rendered body text, final URL, title, and optional cookie metadata (never cookie values). Use when observed verification evidence warrants inspecting the page. After calling this, stop; the orchestrator resumes you with the snapshot.',
277
+ inputSchema: {
278
+ type: 'object',
279
+ properties: {
280
+ maxChars: {
281
+ type: 'number',
282
+ description: 'Maximum rendered body-text characters to return (256–20000).',
283
+ },
284
+ includeCookies: {
285
+ type: 'boolean',
286
+ description:
287
+ 'Include cookie names, domains, paths, expirations, and flags. Cookie values are never returned. Defaults to true.',
288
+ },
417
289
  },
418
290
  },
419
291
  },
420
- },
421
- {
422
- name: 'prompt_user',
423
- description:
424
- 'Ask the human for input or an external action required by the compiled auth program. After calling this, stop; the orchestrator collects the answer and resumes you with it.',
425
- inputSchema: {
426
- type: 'object',
427
- properties: {
428
- message: { type: 'string', description: 'What to ask the user to do.' },
429
- options: {
430
- type: 'array',
431
- items: { type: 'string' },
432
- description: 'Optional fixed choices; omit for free-text (e.g. the OTP code).',
292
+ {
293
+ name: 'prompt_user',
294
+ description:
295
+ 'Ask the human for input or an external action required by the compiled auth program. After calling this, stop; the orchestrator collects the answer and resumes you with it.',
296
+ inputSchema: {
297
+ type: 'object',
298
+ properties: {
299
+ message: { type: 'string', description: 'What to ask the user to do.' },
300
+ options: {
301
+ type: 'array',
302
+ items: { type: 'string' },
303
+ description: 'Optional fixed choices; omit for free-text (e.g. the OTP code).',
304
+ },
433
305
  },
306
+ required: ['message'],
434
307
  },
435
- required: ['message'],
436
308
  },
437
- },
438
- {
439
- name: 'wait_for_cooldown',
440
- description:
441
- 'Request a delay without running any live action. Use only when the observed site response justifies waiting. After calling this, stop.',
442
- inputSchema: {
443
- type: 'object',
444
- properties: {
445
- minutes: { type: 'number', description: 'Cool-off minutes (5–10 typical).' },
446
- reason: {
447
- type: 'string',
448
- description: 'Why you believe it is a cool-off, not a defect.',
309
+ {
310
+ name: 'wait_for_cooldown',
311
+ description:
312
+ 'Request a delay without running any live action. Use only when the observed site response justifies waiting. After calling this, stop.',
313
+ inputSchema: {
314
+ type: 'object',
315
+ properties: {
316
+ minutes: { type: 'number', description: 'Cool-off minutes (5–10 typical).' },
317
+ reason: {
318
+ type: 'string',
319
+ description: 'Why you believe it is a cool-off, not a defect.',
320
+ },
449
321
  },
322
+ required: ['minutes'],
450
323
  },
451
- required: ['minutes'],
452
324
  },
453
- },
454
- ]
455
- : [];
456
-
457
- let semanticVerificationCycles = 0;
458
- /** One pending checkpoint per segment — refuse a second so the orchestrator
459
- * acts on exactly one request. Cleared implicitly: each segment is a fresh
460
- * process with the sentinel removed before spawn. */
461
- let checkpointWritten = false;
462
-
463
- const server = new Server(
464
- { name: 'imprint-compile', version: '0.1.0' },
465
- {
466
- capabilities: { tools: {} },
467
- instructions: isAuthMode
468
- ? 'Compile the recorded login into an auth action program in workflow.json. Define the actions, evidence, state carry, retries, and success criteria from the recording; run those actions live with run_verification, then call done after a declared success action passes.'
469
- : 'These tools let you reverse-engineer the captured session into workflow.json + parser.ts + parser.test.ts. Read the recording, write the artifacts, run tests, and call done() when verified. The done tool runs external verification and will tell you what to fix if anything is wrong.',
470
- },
471
- );
472
-
473
- server.setRequestHandler(ListToolsRequestSchema, async () => ({
474
- tools: [
475
- ...compileTools.map(
476
- (t): Tool => ({
477
- name: t.name,
478
- description: t.description,
479
- inputSchema: t.input_schema as Tool['inputSchema'],
480
- }),
481
- ),
482
- ...checkpointTools,
483
- doneTool,
484
- giveUpTool,
485
- ],
486
- }));
487
-
488
- server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
489
- const name = req.params.name;
490
- const args = req.params.arguments ?? {};
491
-
492
- // Custom done — runs verification inline.
493
- if (name === 'done') {
494
- const doneArgs = args as {
495
- summary?: string;
496
- accept_inconclusive?: boolean;
497
- inconclusive_reason?: string;
498
- };
499
- const summary = doneArgs.summary ?? 'Task completed';
500
- log(`done() called: ${summary}`);
501
-
502
- // Auth mode: lightweight structural verification (the agent already proved
503
- // the workflow works live via run_verification). No param/live stamps.
504
- if (isAuthMode) {
505
- const failures = authExternalVerification(
506
- opts.toolDir,
507
- (opts.authToolPlan?.captures ?? []).map((c) => ({ name: c.name, usedAs: c.usedAs })),
508
- { requireLiveAttempt: true },
509
- );
510
- if (failures.length === 0) {
511
- const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
512
- writeFileSync(
513
- sentinel,
514
- JSON.stringify(
515
- { summary, verification: 'passed', warnings: [], timestamp: Date.now() },
516
- null,
517
- 2,
518
- ),
519
- 'utf8',
325
+ ]
326
+ : [];
327
+
328
+ let semanticVerificationCycles = 0;
329
+ /** One pending checkpoint per segment — refuse a second so the orchestrator
330
+ * acts on exactly one request. Cleared implicitly: each segment is a fresh
331
+ * process with the sentinel removed before spawn. */
332
+ let checkpointWritten = false;
333
+
334
+ const server = new Server(
335
+ { name: 'imprint-compile', version: '0.1.0' },
336
+ {
337
+ capabilities: { tools: {} },
338
+ instructions: isAuthMode
339
+ ? 'Compile the recorded login into an auth action program in workflow.json. Define the actions, evidence, state carry, retries, and success criteria from the recording; run those actions live with run_verification, then call done after a declared success action passes.'
340
+ : 'These tools let you reverse-engineer the captured session into workflow.json + parser.ts + parser.test.ts. Read the recording, write the artifacts, run tests, and call done() when verified. The done tool runs external verification and will tell you what to fix if anything is wrong.',
341
+ },
342
+ );
343
+
344
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
345
+ tools: [
346
+ ...compileTools.map(
347
+ (t): Tool => ({
348
+ name: t.name,
349
+ description: t.description,
350
+ inputSchema: t.input_schema as Tool['inputSchema'],
351
+ }),
352
+ ),
353
+ ...checkpointTools,
354
+ doneTool,
355
+ giveUpTool,
356
+ ],
357
+ }));
358
+
359
+ server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
360
+ const name = req.params.name;
361
+ const args = req.params.arguments ?? {};
362
+
363
+ // Custom done — runs verification inline.
364
+ if (name === 'done') {
365
+ const doneArgs = args as { summary?: string };
366
+ const summary = doneArgs.summary ?? 'Task completed';
367
+ log(`done() called: ${summary}`);
368
+
369
+ // Auth mode: lightweight structural verification (the agent already proved
370
+ // the workflow works live via run_verification). No param/live stamps.
371
+ if (isAuthMode) {
372
+ const failures = authExternalVerification(
373
+ opts.toolDir,
374
+ (opts.authToolPlan?.captures ?? []).map((c) => ({
375
+ name: c.name,
376
+ usedAs: c.usedAs,
377
+ })),
378
+ { requireLiveAttempt: true },
520
379
  );
521
- log(`auth verification passed; wrote ${sentinel}`);
380
+ if (failures.length === 0) {
381
+ const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
382
+ writeFileSync(
383
+ sentinel,
384
+ JSON.stringify(
385
+ {
386
+ summary,
387
+ verification: 'mechanical_passed',
388
+ warnings: [],
389
+ timestamp: Date.now(),
390
+ },
391
+ null,
392
+ 2,
393
+ ),
394
+ 'utf8',
395
+ );
396
+ log(`auth verification passed; wrote ${sentinel}`);
397
+ return {
398
+ content: [
399
+ {
400
+ type: 'text',
401
+ text: 'DONE — verification passed. Do not call any more tools.',
402
+ },
403
+ ],
404
+ };
405
+ }
406
+
407
+ semanticVerificationCycles++;
408
+ log(`auth verification failed (cycle ${semanticVerificationCycles})`);
409
+
522
410
  return {
411
+ isError: true,
523
412
  content: [
524
413
  {
525
414
  type: 'text',
526
- text: 'DONE_VERIFIED — verification passed. The orchestrator will exit shortly. Do not call any more tools.',
527
- },
528
- ],
529
- };
530
- }
531
-
532
- semanticVerificationCycles++;
533
- log(`auth verification failed (cycle ${semanticVerificationCycles})`);
534
-
535
- return {
536
- isError: true,
537
- content: [
538
- {
539
- type: 'text',
540
- text: `You called done but verification failed (cycle ${semanticVerificationCycles}):
415
+ text: `You called done but verification failed (cycle ${semanticVerificationCycles}):
541
416
 
542
417
  ${failures.map((f) => `- ${f}`).join('\n')}
543
418
 
544
419
  Fix the issues in workflow.json, re-test with run_verification, and call done again when fixed.`,
545
- },
546
- ],
547
- };
548
- }
420
+ },
421
+ ],
422
+ };
423
+ }
549
424
 
550
- const finishVerification = beginCompileVerification(opts.toolDir);
551
- try {
552
425
  let semanticReviewCompleted = false;
553
426
  let semanticReviewAttempted = false;
554
427
  const { failures, warnings, paramVerification, integrationEvidence } =
555
428
  await externalVerification(opts.toolDir, session, opts.sessionPath, {
556
429
  expectedToolName: opts.candidate?.toolName,
557
- likelyParams: opts.candidate?.likelyParams,
558
430
  candidateRequestSeqs: opts.candidate?.requestSeqs,
559
431
  // Include bootstrap and shared login dependencies in provenance checks.
560
432
  dependencyRequestSeqs: [
561
433
  ...(opts.candidate?.dependencySeqs ?? []),
562
434
  ...(opts.sharedContext?.loginRequestSeqs ?? []),
563
435
  ],
564
- assignedSharedModules,
565
- tokenParams,
566
- tokenParamShapes,
567
- emittedTokens,
568
- requiredInputs,
569
- credentialValues,
570
436
  credentialNames: opts.sharedContext?.credentialNames,
437
+ strategyKind: opts.strategyKind,
571
438
  deferLiveIntegrationToSemanticAgent: true,
439
+ expectedPublicParameters:
440
+ opts.verificationMode === 'master_mvp' ? opts.candidate?.likelyParams : undefined,
572
441
  });
573
442
  if (warnings.length > 0) {
574
443
  log(`verification warnings (non-blocking):\n${warnings.join('\n')}`);
@@ -579,7 +448,42 @@ Fix the issues in workflow.json, re-test with run_verification, and call done ag
579
448
  JSON.parse(readFileSync(pathJoin(opts.toolDir, 'workflow.json'), 'utf8')),
580
449
  );
581
450
  }
582
- if (workflow && workflowHasIrreversibleEffect(workflow)) {
451
+ if (
452
+ failures.length === 0 &&
453
+ workflow &&
454
+ opts.strategyKind === 'playbook_fallback' &&
455
+ opts.verificationMode === 'master_mvp'
456
+ ) {
457
+ const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
458
+ writeFileSync(
459
+ sentinel,
460
+ JSON.stringify(
461
+ {
462
+ summary,
463
+ verification: 'mechanical_passed',
464
+ verificationMode: opts.verificationMode ?? 'full',
465
+ liveVerified: false,
466
+ liveVerificationOwner: 'master',
467
+ semanticVerification: { status: 'not_run' },
468
+ warnings,
469
+ timestamp: Date.now(),
470
+ },
471
+ null,
472
+ 2,
473
+ ),
474
+ 'utf8',
475
+ );
476
+ log(`browser artifact contract passed; wrote ${sentinel}`);
477
+ return {
478
+ content: [
479
+ {
480
+ type: 'text',
481
+ text: 'DONE — browser artifact contract passed. The master owns live playbook verification. Do not call any more tools.',
482
+ },
483
+ ],
484
+ };
485
+ }
486
+ if (canWaiveIrreversibleLiveVerification(failures, workflow)) {
583
487
  const allWarnings = [
584
488
  ...warnings,
585
489
  ...applyIrreversibleVerificationWaiver(opts.toolDir, workflow),
@@ -590,9 +494,11 @@ Fix the issues in workflow.json, re-test with run_verification, and call done ag
590
494
  JSON.stringify(
591
495
  {
592
496
  summary,
593
- verification: 'passed',
497
+ verification: 'not_applicable',
498
+ verificationMode: opts.verificationMode ?? 'full',
594
499
  liveVerified: false,
595
500
  safetyWaiver: 'irreversible',
501
+ semanticVerification: { status: 'not_applicable' },
596
502
  warnings: allWarnings,
597
503
  timestamp: Date.now(),
598
504
  },
@@ -605,7 +511,36 @@ Fix the issues in workflow.json, re-test with run_verification, and call done ag
605
511
  content: [
606
512
  {
607
513
  type: 'text',
608
- text: 'DONE_UNVERIFIED — deterministic verification passed; live verification was skipped because the workflow is irreversible.',
514
+ text: 'DONE_LIVE_NA — deterministic checks passed; live verification is not applicable because the workflow is irreversible.',
515
+ },
516
+ ],
517
+ };
518
+ }
519
+ if (failures.length === 0 && opts.verificationMode === 'master_mvp') {
520
+ const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
521
+ writeFileSync(
522
+ sentinel,
523
+ JSON.stringify(
524
+ {
525
+ summary,
526
+ verification: 'mechanical_passed',
527
+ verificationMode: 'master_mvp',
528
+ liveVerified: false,
529
+ semanticVerification: { status: 'not_run' },
530
+ warnings,
531
+ timestamp: Date.now(),
532
+ },
533
+ null,
534
+ 2,
535
+ ),
536
+ 'utf8',
537
+ );
538
+ log(`minimum viable artifact verification passed; wrote ${sentinel}`);
539
+ return {
540
+ content: [
541
+ {
542
+ type: 'text',
543
+ text: 'DONE — deterministic artifact checks passed. Live semantic verification is deferred to the master. Do not call any more tools.',
609
544
  },
610
545
  ],
611
546
  };
@@ -614,62 +549,75 @@ Fix the issues in workflow.json, re-test with run_verification, and call done ag
614
549
  if (!opts.provider) {
615
550
  failures.push('compile provider was not supplied to the independent semantic verifier');
616
551
  } else {
617
- const currentFingerprint = compileArtifactFingerprint(opts.toolDir);
552
+ semanticReviewAttempted = true;
553
+ const verifierDeadlineMs = providerControl?.deadlineMs;
618
554
  if (
619
- pendingInconclusive &&
620
- canAcceptInconclusiveDecision({
621
- semanticVerificationCycles,
622
- maxVerificationCycles,
623
- completedReview: pendingInconclusive.report.completedReview,
624
- infrastructureOnly: isInfrastructureOnlyInconclusiveReport(
625
- pendingInconclusive.report.report,
626
- ),
627
- pendingFingerprint: pendingInconclusive.artifactFingerprint,
628
- currentFingerprint,
629
- acceptInconclusive: doneArgs.accept_inconclusive,
630
- inconclusiveReason: doneArgs.inconclusive_reason,
631
- })
555
+ providerControl &&
556
+ verifierDeadlineMs !== undefined &&
557
+ Date.now() >= verifierDeadlineMs
632
558
  ) {
633
- const semantic = pendingInconclusive.report;
559
+ const error = new ProviderDeadlineError(verifierDeadlineMs);
560
+ providerControl.report(error);
561
+ throw error;
562
+ }
563
+ let semantic: Awaited<ReturnType<typeof runLiveSemanticVerification>>;
564
+ try {
565
+ semantic = await runLiveSemanticVerification({
566
+ provider: DEFAULT_VERIFICATION_PROVIDER,
567
+ toolDir: opts.toolDir,
568
+ evidence: integrationEvidence,
569
+ deadlineMs: verifierDeadlineMs,
570
+ runDeadline: providerControl?.deadline,
571
+ signal: active.signal,
572
+ });
573
+ } catch (error) {
574
+ const control = providerControlError(error);
575
+ if (
576
+ providerControl &&
577
+ (control instanceof ProviderDeadlineError ||
578
+ control instanceof ProviderUnavailableError)
579
+ )
580
+ providerControl.report(control);
581
+ throw error;
582
+ }
583
+ semanticReviewCompleted = semantic.completedReview;
584
+ const semanticFailures = semanticVerificationFailures(semantic.report);
585
+ failures.push(...semanticFailures);
586
+ if (semantic.report.status === 'approved_with_gaps') {
587
+ warnings.push(
588
+ `independent semantic verification approved with gaps: ${semantic.report.gaps.join('; ')}`,
589
+ );
590
+ }
591
+ if (semanticFailures.length === 0) {
634
592
  const semanticParams = mergeSemanticParamVerification(
635
593
  paramVerification,
636
594
  semantic.report,
637
595
  );
638
- const inconclusiveReason = doneArgs.inconclusive_reason?.trim() ?? '';
639
- applyLiveVerification(opts.toolDir, {
640
- kind: 'waived-infra',
641
- firstError: inconclusiveReason,
642
- exhaustedBackends: [],
643
- });
596
+ applyLiveVerification(opts.toolDir, undefined);
644
597
  const paramWarnings = applyParamVerification(opts.toolDir, semanticParams);
645
- // The unverified stamp and parameter annotations are metadata-only,
646
- // so carry the already-proven preference to the final workflow hash.
647
598
  rebindExistingBackendsCacheToWorkflow(opts.toolDir);
648
- const allWarnings = [
649
- ...warnings,
650
- `independent semantic verification was inconclusive: ${semantic.report.summary}`,
651
- ...paramWarnings,
652
- ];
599
+ if (paramWarnings.length > 0) {
600
+ log(`parameter verification:\n${paramWarnings.join('\n')}`);
601
+ }
602
+ const allWarnings = [...warnings, ...paramWarnings];
653
603
  const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
654
604
  writeFileSync(
655
605
  sentinel,
656
606
  JSON.stringify(
657
607
  {
658
608
  summary,
659
- verification: 'passed',
660
- liveVerified: false,
609
+ verification: 'mechanical_passed',
610
+ verificationMode: 'full',
611
+ liveVerified: true,
661
612
  semanticVerification: {
662
613
  status: semantic.report.status,
614
+ completed: semantic.completedReview,
663
615
  provider: semantic.provider,
664
616
  model: semantic.model,
665
617
  attempts: semantic.attempts,
666
618
  evidenceArtifact: semantic.report.evidenceArtifact,
667
619
  logArtifact: semantic.report.logArtifact,
668
620
  },
669
- compilerDecision: {
670
- decision: 'ship_unverified',
671
- reason: inconclusiveReason,
672
- },
673
621
  warnings: allWarnings,
674
622
  timestamp: Date.now(),
675
623
  },
@@ -678,114 +626,16 @@ Fix the issues in workflow.json, re-test with run_verification, and call done ag
678
626
  ),
679
627
  'utf8',
680
628
  );
681
- log(`compiler accepted unchanged inconclusive artifact; wrote ${sentinel}`);
629
+ log(`verification passed; wrote ${sentinel}`);
682
630
  return {
683
631
  content: [
684
632
  {
685
633
  type: 'text',
686
- text: `DONE_UNVERIFIED — deterministic verification passed and the compiler explicitly accepted the unchanged artifact after an infrastructure-only inconclusive live review. Evidence: ${semantic.report.evidenceArtifact ?? '.live-verification-evidence.json'}. Verifier log: ${semantic.report.logArtifact ?? '.live-verifier-log.jsonl'}. The orchestrator will exit shortly. Do not call any more tools.`,
634
+ text: `DONE — deterministic checks and independent live semantic verification passed. Evidence: ${semantic.report.evidenceArtifact ?? '.live-verification-evidence.json'}. Verifier log: ${semantic.report.logArtifact ?? '.live-verifier-log.jsonl'}. Do not call any more tools.`,
687
635
  },
688
636
  ],
689
637
  };
690
638
  }
691
-
692
- const capDecision = inconclusiveDecisionAtSemanticCap({
693
- semanticVerificationCycles,
694
- maxVerificationCycles,
695
- pendingFingerprint: pendingInconclusive?.artifactFingerprint,
696
- currentFingerprint,
697
- });
698
- if (capDecision === 'fail-artifact-changed') {
699
- pendingInconclusive = undefined;
700
- failures.push(
701
- 'compile artifacts changed after the final allowed inconclusive semantic review; refusing to run an additional review beyond the semantic cycle cap',
702
- );
703
- } else if (capDecision === 'await-compiler-decision') {
704
- failures.push(
705
- 'semantic review limit reached with an unchanged infrastructure-only inconclusive result; explicitly accept the unverified artifact with reasoning or revise it',
706
- );
707
- } else {
708
- if (
709
- pendingInconclusive &&
710
- pendingInconclusive.artifactFingerprint !== currentFingerprint
711
- ) {
712
- log(
713
- 'compile artifacts changed after inconclusive review; running verification again',
714
- );
715
- pendingInconclusive = undefined;
716
- }
717
- semanticReviewAttempted = true;
718
- const semantic = await runLiveSemanticVerification({
719
- provider: DEFAULT_VERIFICATION_PROVIDER,
720
- toolDir: opts.toolDir,
721
- evidence: integrationEvidence,
722
- });
723
- semanticReviewCompleted = semantic.completedReview;
724
- if (semantic.report.status === 'inconclusive') {
725
- pendingInconclusive = {
726
- artifactFingerprint: compileArtifactFingerprint(opts.toolDir),
727
- report: semantic,
728
- };
729
- } else {
730
- pendingInconclusive = undefined;
731
- }
732
- const semanticFailures = semanticVerificationFailures(semantic.report);
733
- failures.push(...semanticFailures);
734
- if (semantic.report.status === 'approved_with_gaps') {
735
- warnings.push(
736
- `independent semantic verification approved with gaps: ${semantic.report.gaps.join('; ')}`,
737
- );
738
- }
739
- if (semanticFailures.length === 0) {
740
- const semanticParams = mergeSemanticParamVerification(
741
- paramVerification,
742
- semantic.report,
743
- );
744
- // Only the independent semantic agent can mint liveVerified=true.
745
- applyLiveVerification(opts.toolDir, undefined);
746
- const paramWarnings = applyParamVerification(opts.toolDir, semanticParams);
747
- // liveVerified/parameter annotations are metadata-only, but they
748
- // change the hash-strict workflow cache key. Keep the verifier's
749
- // already-proven backend preference current without probing again.
750
- rebindExistingBackendsCacheToWorkflow(opts.toolDir);
751
- if (paramWarnings.length > 0) {
752
- log(`parameter verification:\n${paramWarnings.join('\n')}`);
753
- }
754
- const allWarnings = [...warnings, ...paramWarnings];
755
- const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
756
- writeFileSync(
757
- sentinel,
758
- JSON.stringify(
759
- {
760
- summary,
761
- verification: 'passed',
762
- semanticVerification: {
763
- status: semantic.report.status,
764
- provider: semantic.provider,
765
- model: semantic.model,
766
- attempts: semantic.attempts,
767
- evidenceArtifact: semantic.report.evidenceArtifact,
768
- logArtifact: semantic.report.logArtifact,
769
- },
770
- warnings: allWarnings,
771
- timestamp: Date.now(),
772
- },
773
- null,
774
- 2,
775
- ),
776
- 'utf8',
777
- );
778
- log(`verification passed; wrote ${sentinel}`);
779
- return {
780
- content: [
781
- {
782
- type: 'text',
783
- text: `DONE_VERIFIED — deterministic checks and independent live semantic verification passed (${semantic.report.status}). Evidence: ${semantic.report.evidenceArtifact ?? '.live-verification-evidence.json'}. Verifier log: ${semantic.report.logArtifact ?? '.live-verifier-log.jsonl'}. The orchestrator will exit shortly. Do not call any more tools.`,
784
- },
785
- ],
786
- };
787
- }
788
- }
789
639
  }
790
640
  }
791
641
  semanticVerificationCycles = advanceSemanticVerificationCycle(
@@ -831,12 +681,7 @@ Fix the issues in workflow.json, re-test with run_verification, and call done ag
831
681
  ? 'semantic verifier did not complete a review (semantic cycle unchanged)'
832
682
  : 'deterministic verification failed (semantic cycle unchanged)';
833
683
  log(failurePhase);
834
- const awaitingFinalInconclusiveDecision =
835
- semanticVerificationCycles >= maxVerificationCycles && pendingInconclusive !== undefined;
836
- if (
837
- semanticVerificationCycles >= maxVerificationCycles &&
838
- !awaitingFinalInconclusiveDecision
839
- ) {
684
+ if (semanticVerificationCycles >= maxVerificationCycles) {
840
685
  const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
841
686
  writeFileSync(
842
687
  sentinel,
@@ -865,146 +710,152 @@ Fix the issues in workflow.json, re-test with run_verification, and call done ag
865
710
  };
866
711
  }
867
712
 
713
+ const repairFiles =
714
+ opts.strategyKind === 'playbook_fallback'
715
+ ? 'workflow.json and playbook.yaml'
716
+ : 'workflow.json, parser.ts, and parser.test.ts';
868
717
  const continuationMessage = `You called done but ${failurePhase}:
869
718
 
870
719
  ${failures.map((f) => `- ${f}`).join('\n')}
871
720
 
872
- Resume your work. Read the files you wrote (workflow.json, parser.ts, parser.test.ts), fix the issues, re-run tests, and call done again when fixed.`;
873
- const compilerDecisionGuidance = `\n\nUse the verifier's semantic evidence, not a requirement for 100% of the original candidate inputs. If the core intent works but a secondary parameter cannot be supported from the recording and live evidence without guessing, remove that parameter and add workflow.limitations with omittedParameters and a specific reason. Treat emitsTokens as downstream compatibility targets, not automatic definitions of producer success: when useful core records lack an optional consumer token, preserve the records and supported input classes, document the missing output and affected consumers, and leave those consumers limited/unverified. Narrow an input class only when its core results are unusable or misleading. Remove claims that directly depend on an omitted feature, but do not erase valid producer results solely to make a downstream chain total. Do not use a limitation to hide a broken core tool, and do not keep a known broken or ignored public input.`;
874
- const inconclusiveDecisionGuidance = pendingInconclusive
875
- ? semanticVerificationCycles >= maxVerificationCycles &&
876
- pendingInconclusive.report.completedReview
877
- ? '\n\nThe final allowed live semantic review was infrastructure-only inconclusive. Review its evidence and log. If they expose a tool defect, do not attempt to change the artifact after the review cap. If they expose no tool-level defect and the unchanged deterministic artifact should ship explicitly unverified, call done again without changing compile artifacts, set accept_inconclusive=true, and provide your concrete reasoning in inconclusive_reason. This compiler decision is persisted and does not mint liveVerified.'
878
- : '\n\nThe live verifier was infrastructure-only inconclusive. Review its evidence and log. Fix any exposed tool defect, or call done normally to request another independent review. Explicit unverified acceptance is available only after the semantic review limit is reached.'
879
- : '';
721
+ Resume your work. Read the files you wrote (${repairFiles}), fix the issues, re-run the applicable checks, and call done again when fixed.`;
880
722
  return {
881
723
  isError: true,
882
724
  content: [
883
725
  {
884
726
  type: 'text',
885
- text: continuationMessage + compilerDecisionGuidance + inconclusiveDecisionGuidance,
727
+ text: continuationMessage,
886
728
  },
887
729
  ],
888
730
  };
889
- } finally {
890
- finishVerification();
891
731
  }
892
- }
893
732
 
894
- // Auth-mode checkpoint tools — record the request and end the segment. The
895
- // orchestrator performs the action live and resumes the agent with the result.
896
- if (
897
- name === 'run_verification' ||
898
- name === 'inspect_verification_page' ||
899
- name === 'prompt_user' ||
900
- name === 'wait_for_cooldown'
901
- ) {
902
- if (name === 'run_verification') {
903
- const failures = authWorkflowPreflightFailures(
904
- opts.toolDir,
905
- session,
906
- opts.authToolPlan?.credentialNames,
907
- );
908
- if (failures.length > 0) {
733
+ // Auth-mode checkpoint tools — record the request and end the segment. The
734
+ // orchestrator performs the action live and resumes the agent with the result.
735
+ if (
736
+ name === 'run_verification' ||
737
+ name === 'inspect_verification_page' ||
738
+ name === 'prompt_user' ||
739
+ name === 'wait_for_cooldown'
740
+ ) {
741
+ if (name === 'run_verification') {
742
+ const failures = authWorkflowPreflightFailures(
743
+ opts.toolDir,
744
+ session,
745
+ opts.authToolPlan?.credentialNames,
746
+ );
747
+ if (failures.length > 0) {
748
+ return {
749
+ isError: true,
750
+ content: [
751
+ {
752
+ type: 'text',
753
+ text: `run_verification blocked by auth workflow preflight. Fix workflow.json before requesting live verification:\n${failures
754
+ .map((failure) => `- ${failure}`)
755
+ .join('\n')}`,
756
+ },
757
+ ],
758
+ };
759
+ }
760
+ }
761
+ if (checkpointWritten) {
909
762
  return {
910
763
  isError: true,
911
764
  content: [
912
765
  {
913
766
  type: 'text',
914
- text: `run_verification blocked by auth workflow preflight. Fix workflow.json before requesting live verification:\n${failures
915
- .map((failure) => `- ${failure}`)
916
- .join('\n')}`,
767
+ text: 'A checkpoint is already pending this turn. STOP now — do not call another tool; the orchestrator will act and resume you.',
917
768
  },
918
769
  ],
919
770
  };
920
771
  }
772
+ const checkpoint: Record<string, unknown> = { kind: name, ...args, timestamp: Date.now() };
773
+ const sentinel = pathJoin(opts.toolDir, CHECKPOINT_SENTINEL);
774
+ writeFileSync(sentinel, JSON.stringify(checkpoint, null, 2), 'utf8');
775
+ checkpointWritten = true;
776
+ log(`checkpoint(${name}) recorded; wrote ${sentinel}`);
777
+ return {
778
+ content: [
779
+ {
780
+ type: 'text',
781
+ text: `CHECKPOINT_RECORDED (${name}) — STOP now and reply briefly that you are waiting. The orchestrator will perform this and resume you with the result as a new message. Do not call any more tools.`,
782
+ },
783
+ ],
784
+ };
921
785
  }
922
- if (checkpointWritten) {
786
+
787
+ // Custom give_up — writes sentinel and exits.
788
+ if (name === 'give_up') {
789
+ const reason = (args as { reason?: string }).reason ?? 'unknown';
790
+ const whatWasTried = (args as { what_was_tried?: string }).what_was_tried ?? '';
791
+ log(`give_up() called: ${reason}`);
792
+ const sentinel = pathJoin(opts.toolDir, GIVE_UP_SENTINEL);
793
+ writeFileSync(
794
+ sentinel,
795
+ JSON.stringify({ reason, what_was_tried: whatWasTried, timestamp: Date.now() }, null, 2),
796
+ 'utf8',
797
+ );
923
798
  return {
924
- isError: true,
925
799
  content: [
926
800
  {
927
801
  type: 'text',
928
- text: 'A checkpoint is already pending this turn. STOP now — do not call another tool; the orchestrator will act and resume you.',
802
+ text: 'GIVE_UP_RECORDED — the orchestrator will exit shortly. Do not call any more tools.',
929
803
  },
930
804
  ],
931
805
  };
932
806
  }
933
- const checkpoint: Record<string, unknown> = { kind: name, ...args, timestamp: Date.now() };
934
- const sentinel = pathJoin(opts.toolDir, CHECKPOINT_SENTINEL);
935
- writeFileSync(sentinel, JSON.stringify(checkpoint, null, 2), 'utf8');
936
- checkpointWritten = true;
937
- log(`checkpoint(${name}) recorded; wrote ${sentinel}`);
938
- return {
939
- content: [
940
- {
941
- type: 'text',
942
- text: `CHECKPOINT_RECORDED (${name}) — STOP now and reply briefly that you are waiting. The orchestrator will perform this and resume you with the result as a new message. Do not call any more tools.`,
943
- },
944
- ],
945
- };
946
- }
947
807
 
948
- // Custom give_up — writes sentinel and exits.
949
- if (name === 'give_up') {
950
- const reason = (args as { reason?: string }).reason ?? 'unknown';
951
- const whatWasTried = (args as { what_was_tried?: string }).what_was_tried ?? '';
952
- log(`give_up() called: ${reason}`);
953
- const sentinel = pathJoin(opts.toolDir, GIVE_UP_SENTINEL);
954
- writeFileSync(
955
- sentinel,
956
- JSON.stringify({ reason, what_was_tried: whatWasTried, timestamp: Date.now() }, null, 2),
957
- 'utf8',
958
- );
959
- return {
960
- content: [
961
- {
962
- type: 'text',
963
- text: 'GIVE_UP_RECORDED — the orchestrator will exit shortly. Do not call any more tools.',
964
- },
965
- ],
966
- };
967
- }
808
+ // Standard read/write tools — delegate to the shared handlers.
809
+ const tool = compileTools.find((t) => t.name === name);
810
+ if (!tool) {
811
+ return {
812
+ isError: true,
813
+ content: [{ type: 'text', text: `Unknown tool: ${name}` }],
814
+ };
815
+ }
816
+
817
+ let result: { result: string; isError?: boolean };
818
+ try {
819
+ result = await tool.handler(args);
820
+ } catch (err) {
821
+ const control = providerControlError(err);
822
+ if (control) throw control;
823
+ result = {
824
+ result: err instanceof Error ? err.message : String(err),
825
+ isError: true,
826
+ };
827
+ }
968
828
 
969
- // Standard read/write tools — delegate to the shared handlers.
970
- const tool = compileTools.find((t) => t.name === name);
971
- if (!tool) {
972
829
  return {
973
- isError: true,
974
- content: [{ type: 'text', text: `Unknown tool: ${name}` }],
830
+ content: [{ type: 'text', text: result.result }],
831
+ isError: result.isError ?? false,
975
832
  };
976
- }
833
+ });
977
834
 
978
- let result: { result: string; isError?: boolean };
835
+ const transport = new StdioServerTransport();
836
+ let closeLifetime: (() => void) | undefined;
979
837
  try {
980
- result = await tool.handler(args);
981
- } catch (err) {
982
- result = {
983
- result: err instanceof Error ? err.message : String(err),
984
- isError: true,
985
- };
838
+ await server.connect(transport);
839
+ log(`stdio transport ready (${compileTools.length + 2} tools)`);
840
+ await new Promise<void>((resolve) => {
841
+ const close = (reason: string): void => {
842
+ log(`closing: ${reason}`);
843
+ resolve();
844
+ };
845
+ transport.onclose = () => close('client disconnected');
846
+ closeLifetime = () => close('process signal');
847
+ active.signal?.addEventListener('abort', closeLifetime, { once: true });
848
+ });
849
+ } finally {
850
+ if (closeLifetime) active.signal?.removeEventListener('abort', closeLifetime);
851
+ transport.onclose = undefined;
852
+ await server.close().catch(() => undefined);
986
853
  }
987
-
988
- return {
989
- content: [{ type: 'text', text: result.result }],
990
- isError: result.isError ?? false,
991
- };
992
- });
993
-
994
- const transport = new StdioServerTransport();
995
- await server.connect(transport);
996
- log(`stdio transport ready (${compileTools.length + 2} tools)`);
997
-
998
- // Block until the orchestrator closes us. Mirrors mcp-server.ts:230.
999
- await new Promise<void>((resolve) => {
1000
- const close = (reason: string): void => {
1001
- log(`closing: ${reason}`);
1002
- resolve();
1003
- };
1004
- transport.onclose = () => close('client disconnected');
1005
- process.once('SIGINT', () => close('SIGINT'));
1006
- process.once('SIGTERM', () => close('SIGTERM'));
1007
- });
854
+ } finally {
855
+ active.dispose();
856
+ providerControl?.dispose();
857
+ for (const [signal, handler] of lifetimeHandlers) process.removeListener(signal, handler);
858
+ }
1008
859
  }
1009
860
 
1010
861
  /** Sentinel file names exposed for the orchestrator to poll. */