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
@@ -11,7 +11,6 @@ import { join as pathJoin } from 'node:path';
11
11
  import {
12
12
  type AgentProgress,
13
13
  type AgentResult,
14
- type AgentTool,
15
14
  type OnDeadlineReached,
16
15
  doneTool,
17
16
  giveUpTool,
@@ -23,10 +22,18 @@ import { compileViaCodexCli } from './codex-cli-compile.ts';
23
22
  import {
24
23
  type CompileAgentProgress,
25
24
  type CompileAgentResult,
25
+ type CompileVerificationMode,
26
26
  advanceIncompleteSemanticVerificationRuns,
27
27
  advanceSemanticVerificationCycle,
28
+ formatCandidateContext,
29
+ formatCompileVerificationMode,
30
+ formatToolPlan,
28
31
  } from './compile-agent-types.ts';
29
- import { formatCandidateContext, formatToolPlan } from './compile-agent-types.ts';
32
+ import {
33
+ type CompilerResume,
34
+ runCompileWithProviderRecovery,
35
+ } from './compile-provider-recovery.ts';
36
+ import type { CompileStrategyKind } from './compile-strategy.ts';
30
37
  import {
31
38
  applyIrreversibleVerificationWaiver,
32
39
  applyLiveVerification,
@@ -34,10 +41,9 @@ import {
34
41
  buildCompileTools,
35
42
  externalVerification,
36
43
  } from './compile-tools.ts';
37
- import { type Replacement, extractCredentials } from './credential-extract.ts';
44
+ import { extractCredentials } from './credential-extract.ts';
38
45
  import { workflowHasIrreversibleEffect } from './effects.ts';
39
46
  import {
40
- isInfrastructureOnlyInconclusiveReport,
41
47
  mergeSemanticParamVerification,
42
48
  runLiveSemanticVerification,
43
49
  semanticVerificationFailures,
@@ -53,15 +59,10 @@ import {
53
59
  } from './llm.ts';
54
60
  import { loadJsonFile } from './load-json.ts';
55
61
  import { createLog } from './log.ts';
56
- import {
57
- canAcceptInconclusiveDecision,
58
- compileArtifactFingerprint,
59
- inconclusiveDecisionAtSemanticCap,
60
- } from './mcp-compile-server.ts';
61
62
  import { localSiteDir } from './paths.ts';
62
63
  import { rebindExistingBackendsCacheToWorkflow } from './probe-backends.ts';
63
- import { detectPageMintedHeaders, redactSession } from './redact.ts';
64
- import type { ClassifiedValue } from './session-diff.ts';
64
+ import { type RunDeadlineRef, resolvedRunDeadline } from './provider-retry.ts';
65
+ import { redactSession } from './redact.ts';
65
66
  import type { SharedCompileContext, ToolCandidate } from './tool-candidates.ts';
66
67
  import {
67
68
  type SharedTriageSelection,
@@ -77,31 +78,6 @@ const log = createLog('compile-agent');
77
78
  const REPO_ROOT = pathJoin(import.meta.dir, '..', '..');
78
79
  const PROMPTS_DIR = pathJoin(REPO_ROOT, 'prompts');
79
80
 
80
- function compileDoneTool(): AgentTool {
81
- const tool = doneTool();
82
- return {
83
- ...tool,
84
- description:
85
- 'Call this when compilation is complete. After an infrastructure-only inconclusive live review, call it again on unchanged artifacts with an explicit acceptance decision and reasoning.',
86
- input_schema: {
87
- ...tool.input_schema,
88
- properties: {
89
- ...tool.input_schema.properties,
90
- accept_inconclusive: {
91
- type: 'boolean',
92
- description:
93
- 'Explicitly ship an unchanged deterministic artifact after an infrastructure-only inconclusive live review.',
94
- },
95
- inconclusive_reason: {
96
- type: 'string',
97
- description:
98
- 'Concrete compiler reasoning for accepting the unchanged artifact without a liveVerified stamp.',
99
- },
100
- },
101
- },
102
- };
103
- }
104
-
105
81
  let claudeCliCompiler = compileViaClaudeCli;
106
82
  let codexCliCompiler = compileViaCodexCli;
107
83
 
@@ -121,11 +97,21 @@ export function resolveCompileAgentModel(provider: ProviderName): string {
121
97
  return preferredAgentModel(provider);
122
98
  }
123
99
 
100
+ function removeEphemeralTests(toolDir: string): void {
101
+ for (const name of ['parser.test.ts', 'request.test.ts', 'integration.test.ts']) {
102
+ const path = pathJoin(toolDir, name);
103
+ if (existsSync(path)) unlinkSync(path);
104
+ }
105
+ }
106
+
124
107
  interface CompileAgentOptions {
125
108
  /** Path to the recorded session JSON (absolute or relative). */
126
109
  sessionPath: string;
127
110
  /** Hard wall-clock budget. Default 20 minutes. */
128
111
  maxDurationMs?: number;
112
+ /** Absolute teach-run deadline shared by planning, compile, and verification. */
113
+ deadlineMs?: number;
114
+ runDeadline?: RunDeadlineRef;
129
115
  /** Override LLM config (region, model, project). */
130
116
  llmConfig?: LLMOptions;
131
117
  /** For testing only — inject a pre-configured provider instead of using llmConfig.
@@ -139,20 +125,12 @@ interface CompileAgentOptions {
139
125
  * on disk just confuses `bun test`). Pass true with `--keep-test` to
140
126
  * inspect the agent's test output locally. */
141
127
  keepTest?: boolean;
142
- /** Credential placeholders to inject before redaction. Provided by `imprint
143
- * teach` when the credential-extract pass found a login pair; for direct
144
- * `imprint generate` callers we run extraction inline (best-effort, no
145
- * prompts — values flow into the credential manager only when the user
146
- * goes through the teach flow). */
147
- replacements?: Replacement[];
148
128
  /** Directory where workflow.json/parser.ts/parser.test.ts are written. */
149
129
  outDir?: string;
150
130
  /** Candidate-specific compile scope for multi-tool teach. */
151
131
  candidate?: ToolCandidate;
152
132
  /** Shared auth/helper guidance generated once for a multi-tool teach run. */
153
133
  sharedContext?: SharedCompileContext;
154
- /** Dual-pass value classifications from replay-and-diff. */
155
- classifications?: ClassifiedValue[];
156
134
  /** Credential values extracted during teach, passed to integration tests via env var. */
157
135
  teachCredentials?: { site: string; values: Record<string, string> };
158
136
  /** Absolute path to the multi-tool build plan sidecar (.build-plan.json). */
@@ -161,34 +139,46 @@ interface CompileAgentOptions {
161
139
  sharedModules?: SharedModuleManifestEntry[];
162
140
  /** Called when wall-clock deadline is reached; return ms to extend or null to time out. */
163
141
  onDeadlineReached?: OnDeadlineReached;
164
- /** Per-tool implementation plan (param→field mapping, request construction,
165
- * response parsing, shared-module imports). Injected into the agent's initial
166
- * message so the compile follows it. Generic — not tied to any site. */
142
+ /** Cancels the active provider call, any backoff wait, and its compiler child process. */
143
+ signal?: AbortSignal;
144
+ /** Per-tool implementation plan. Its strategy is master-accepted; focused
145
+ * construction details remain open to evidence-backed repair or rejection. */
167
146
  toolPlan?: string;
147
+ /** Master-accepted execution strategy for this focused compile. */
148
+ strategyKind?: CompileStrategyKind;
168
149
  /** Revise an existing generated artifact, using durable verification feedback
169
150
  * as the starting point instead of rebuilding it from raw capture. */
170
151
  revisionMode?: boolean;
171
152
  /** Shared triage decision propagated into all compile transports. */
172
153
  preTriagedSession?: SharedTriageSelection;
154
+ /** Master-led teaches use a deterministic MVP boundary so dependent tools
155
+ * are not held behind live semantic breadth work. Standalone generation
156
+ * keeps the full verifier by default. */
157
+ verificationMode?: CompileVerificationMode;
158
+ /** Continue the same tool conversation after factual master/verifier feedback. */
159
+ initialResume?: CompilerResume;
160
+ /** Reports the durable provider thread even when the artifact attempt fails. */
161
+ onSessionId?: (sessionId: string) => void;
173
162
  }
174
163
 
175
164
  function formatRevisionMode(enabled: boolean | undefined): string {
176
165
  return enabled
177
166
  ? [
178
- 'REVISION MODE: this is a bounded resume of an existing generated tool, not a from-scratch compile.',
179
- 'Use read_session_summary.revisionContext, then read the listed current artifacts and durable verification feedback before inspecting raw response bodies.',
180
- 'Preserve proven behavior and make the smallest evidence-backed repair or contract reduction.',
167
+ 'REVISION MODE: continue this tool and strategy in its retained compiler conversation; do not restart the investigation from scratch.',
168
+ 'Use read_session_summary.revisionContext, then read any listed compatible artifacts and durable verification feedback before inspecting raw response bodies.',
169
+ 'Use the conversation history plus supplied tool-plan revision guidance, preserve proven behavior when a compatible artifact exists, and make the smallest evidence-backed repair. Let Codex manage context compaction when needed.',
181
170
  ].join(' ')
182
171
  : '';
183
172
  }
184
173
 
185
174
  export async function compileAgent(opts: CompileAgentOptions): Promise<CompileAgentResult> {
186
175
  const startTime = Date.now();
187
- // Resolve the shared modules + token contracts the plan assigned this tool, so
188
- // the in-process verifier can assert modules are imported and require a chained
189
- // test for each producer-sourced token param.
190
- const { assignedSharedModules, tokenParams, tokenParamShapes, emittedTokens, requiredInputs } =
191
- resolvePlanSliceFromFile(opts.buildPlanPath, opts.candidate?.toolName, opts.sharedModules);
176
+ // Build-plan fields are bounded proposals for the compile/master agents.
177
+ const { assignedSharedModules } = resolvePlanSliceFromFile(
178
+ opts.buildPlanPath,
179
+ opts.candidate?.toolName,
180
+ opts.sharedModules,
181
+ );
192
182
 
193
183
  // 1. Load + validate the session
194
184
  let session: Session = loadJsonFile(
@@ -202,30 +192,16 @@ export async function compileAgent(opts: CompileAgentOptions): Promise<CompileAg
202
192
  'session',
203
193
  );
204
194
 
205
- // 2. Auto-redact if not already redacted (preserves any ${credential.X}
206
- // placeholders that teach.ts already injected). When replacements are
207
- // passed in via opts (the teach path), we honor them; otherwise we run
208
- // extraction inline so direct `imprint generate` callers also get
209
- // credential-aware redaction (values are NOT persisted to the keychain
210
- // on this path — that requires going through `imprint teach` or
211
- // `imprint credential set`).
195
+ // 2. Auto-redact raw direct-generate inputs. Teach normally supplies an
196
+ // already-redacted focused recording.
212
197
  const looksRedacted = JSON.stringify(session).includes('[REDACTED:');
213
198
  if (!looksRedacted) {
214
- let replacements = opts.replacements;
215
- if (!replacements) {
216
- const auto = extractCredentials(session);
217
- replacements = auto.replacements;
218
- }
219
- const pageMintedHeaders = detectPageMintedHeaders(session);
220
- const r = redactSession(session, { replacements, keepHeaders: pageMintedHeaders });
221
- session = r.session;
222
- if (r.stats.totalRedactions > 0 || r.stats.placeholdersInjected > 0) {
223
- const freeformNote =
224
- r.stats.freeformRedactions > 0
225
- ? ` (${r.stats.freeformRedactions} free-form finding(s))`
226
- : '';
199
+ const replacements = extractCredentials(session).replacements;
200
+ const redaction = redactSession(session, { replacements });
201
+ session = redaction.session;
202
+ if (redaction.stats.totalRedactions > 0 || redaction.stats.placeholdersInjected > 0) {
227
203
  log(
228
- `redacted ${r.stats.totalRedactions} value(s)${freeformNote} and injected ${r.stats.placeholdersInjected} credential placeholder(s) before sending to LLM`,
204
+ `redacted ${redaction.stats.totalRedactions} value(s) and injected ${redaction.stats.placeholdersInjected} credential placeholder(s) before sending to LLM`,
229
205
  );
230
206
  }
231
207
  }
@@ -238,10 +214,10 @@ export async function compileAgent(opts: CompileAgentOptions): Promise<CompileAg
238
214
 
239
215
  // 3. Determine the generated tool directory.
240
216
  const absoluteToolDir = opts.outDir ?? localSiteDir(session.site);
217
+ mkdirSync(absoluteToolDir, { recursive: true });
241
218
 
242
219
  // 3b. Ensure type dependencies exist so the agent doesn't waste turns
243
220
  // discovering and installing @types/bun + @types/node during the loop.
244
- mkdirSync(absoluteToolDir, { recursive: true });
245
221
  const harnessPkgPath = pathJoin(absoluteToolDir, 'package.json');
246
222
  if (!existsSync(harnessPkgPath)) {
247
223
  writeFileSync(
@@ -284,13 +260,13 @@ export async function compileAgent(opts: CompileAgentOptions): Promise<CompileAg
284
260
  ...buildCompileTools(session, absoluteToolDir, sessionPathAbs, {
285
261
  candidate: opts.candidate,
286
262
  sharedContext: opts.sharedContext,
287
- classifications: opts.classifications,
288
263
  teachCredentials: opts.teachCredentials,
289
264
  buildPlanPath: opts.buildPlanPath,
290
265
  sharedModules: opts.sharedModules,
266
+ strategyKind: opts.strategyKind,
291
267
  revisionMode: opts.revisionMode,
292
268
  }),
293
- compileDoneTool(),
269
+ doneTool(),
294
270
  giveUpTool(),
295
271
  ];
296
272
 
@@ -303,11 +279,15 @@ You will write artifacts into the tool directory.
303
279
  ${formatCandidateContext(opts.candidate, opts.sharedContext, assignedSharedModules)}
304
280
  ${formatToolPlan(opts.toolPlan)}
305
281
  ${formatRevisionMode(opts.revisionMode)}
282
+ ${formatCompileVerificationMode(opts.verificationMode)}
306
283
 
307
284
  Begin by calling read_session_summary to orient yourself, then proceed per the system prompt.`;
308
285
 
309
286
  // 7. Compute deadline
310
- let deadlineMs = Date.now() + (opts.maxDurationMs ?? 20 * 60 * 1000);
287
+ const runDeadline = resolvedRunDeadline(
288
+ opts.runDeadline,
289
+ opts.deadlineMs ?? Date.now() + (opts.maxDurationMs ?? 20 * 60 * 1000),
290
+ );
311
291
 
312
292
  // 8. Instantiate provider (or use injected one for testing).
313
293
  // CLI providers take a different path: they don't implement Anthropic
@@ -318,50 +298,54 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
318
298
  provider = opts.llmProvider;
319
299
  } else {
320
300
  const resolvedProvider = resolveProvider(opts.llmConfig);
321
- if (resolvedProvider.name === 'claude-cli') {
322
- return await claudeCliCompiler({
323
- session,
324
- absoluteToolDir,
325
- sessionPath: opts.sessionPath,
326
- systemPromptPath,
327
- deadlineMs,
328
- onProgress: opts.onProgress,
301
+ if (resolvedProvider.name === 'claude-cli' || resolvedProvider.name === 'codex-cli') {
302
+ const providerName = resolvedProvider.name;
303
+ const compiler = providerName === 'claude-cli' ? claudeCliCompiler : codexCliCompiler;
304
+ const result = await runCompileWithProviderRecovery({
305
+ initialResume: opts.initialResume,
306
+ runDeadline,
307
+ signal: opts.signal,
329
308
  onDeadlineReached: opts.onDeadlineReached,
330
- startTime,
331
- keepTest: opts.keepTest,
332
- candidate: opts.candidate,
333
- sharedContext: opts.sharedContext,
334
- buildPlanPath: opts.buildPlanPath,
335
- sharedModules: opts.sharedModules,
336
- toolPlan: opts.toolPlan,
337
- revisionMode: opts.revisionMode,
338
- model: opts.llmConfig?.model,
339
- sharedTriageSelection: opts.preTriagedSession
340
- ? minimalSharedTriageSelection(opts.preTriagedSession)
341
- : undefined,
342
- });
343
- }
344
- if (resolvedProvider.name === 'codex-cli') {
345
- return await codexCliCompiler({
346
- session,
347
- absoluteToolDir,
348
- sessionPath: opts.sessionPath,
349
- systemPromptPath,
350
- deadlineMs,
351
- onProgress: opts.onProgress,
352
- startTime,
353
- keepTest: opts.keepTest,
354
- candidate: opts.candidate,
355
- sharedContext: opts.sharedContext,
356
- buildPlanPath: opts.buildPlanPath,
357
- sharedModules: opts.sharedModules,
358
- toolPlan: opts.toolPlan,
359
- revisionMode: opts.revisionMode,
360
- model: opts.llmConfig?.model,
361
- sharedTriageSelection: opts.preTriagedSession
362
- ? minimalSharedTriageSelection(opts.preTriagedSession)
363
- : undefined,
309
+ onRetry: ({ attempt, delayMs, sessionId }) =>
310
+ log(
311
+ `${providerName} provider interruption after segment ${attempt}; ` +
312
+ `${sessionId ? `will resume session ${sessionId.slice(0, 8)}` : 'no session started yet'} ` +
313
+ `in ${Math.round(delayMs / 1000)}s`,
314
+ ),
315
+ run: (resume, segmentDeadline) =>
316
+ compiler({
317
+ session,
318
+ absoluteToolDir,
319
+ sessionPath: opts.sessionPath,
320
+ systemPromptPath,
321
+ deadlineMs: segmentDeadline?.deadlineMs ?? runDeadline?.deadlineMs ?? Date.now(),
322
+ runDeadline: segmentDeadline,
323
+ onProgress: opts.onProgress,
324
+ onDeadlineReached: opts.onDeadlineReached,
325
+ signal: opts.signal,
326
+ startTime,
327
+ keepTest: opts.keepTest,
328
+ candidate: opts.candidate,
329
+ sharedContext: opts.sharedContext,
330
+ buildPlanPath: opts.buildPlanPath,
331
+ sharedModules: opts.sharedModules,
332
+ toolPlan: opts.toolPlan,
333
+ strategyKind: opts.strategyKind,
334
+ revisionMode: opts.revisionMode,
335
+ verificationMode: opts.verificationMode,
336
+ resume,
337
+ model: opts.llmConfig?.model,
338
+ sharedTriageSelection: opts.preTriagedSession
339
+ ? minimalSharedTriageSelection(opts.preTriagedSession)
340
+ : undefined,
341
+ }),
364
342
  });
343
+ if (result.sessionId) opts.onSessionId?.(result.sessionId);
344
+ if (!result.success) return result;
345
+ if (!opts.keepTest && opts.verificationMode !== 'master_mvp') {
346
+ removeEphemeralTests(absoluteToolDir);
347
+ }
348
+ return result;
365
349
  }
366
350
  if (!isToolUseProvider(resolvedProvider)) {
367
351
  throw new Error(
@@ -389,14 +373,9 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
389
373
  const MAX_INCOMPLETE_VERIFIER_RUNS = 2;
390
374
  let semanticVerificationCycles = 0;
391
375
  let incompleteVerifierRuns = 0;
392
- let pendingInconclusive:
393
- | {
394
- artifactFingerprint: string;
395
- report: Awaited<ReturnType<typeof runLiveSemanticVerification>>;
396
- }
397
- | undefined;
398
376
  let result: AgentResult | null = null;
399
377
  let currentInitialMessage = initialUserMessage;
378
+ let verificationSemantic: 'approved' | 'not_run' | 'not_applicable' | undefined;
400
379
 
401
380
  while (true) {
402
381
  const currentSemanticCycle = Math.min(semanticVerificationCycles + 1, MAX_VERIFICATION_CYCLES);
@@ -417,7 +396,8 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
417
396
  systemPrompt,
418
397
  initialUserMessage: currentInitialMessage,
419
398
  tools,
420
- deadlineMs,
399
+ deadlineMs: runDeadline?.deadlineMs ?? Date.now(),
400
+ runDeadline,
421
401
  llm: provider,
422
402
  onProgress: wrappedOnProgress,
423
403
  onConversationUpdate: (currentCycleLog) => {
@@ -425,6 +405,7 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
425
405
  writeFileSync(conversationLogPath, JSON.stringify(fullLog, null, 2), 'utf8');
426
406
  },
427
407
  onDeadlineReached: opts.onDeadlineReached,
408
+ signal: opts.signal,
428
409
  });
429
410
 
430
411
  totalTurns += result.turns;
@@ -441,27 +422,22 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
441
422
  }
442
423
 
443
424
  // Perform external verification
444
- const deterministicVerificationStartedAt = Date.now();
445
425
  const { failures, warnings, paramVerification, integrationEvidence } =
446
426
  await externalVerification(absoluteToolDir, session, sessionPathAbs, {
447
427
  expectedToolName: opts.candidate?.toolName,
448
- likelyParams: opts.candidate?.likelyParams,
449
428
  candidateRequestSeqs: opts.candidate?.requestSeqs,
450
429
  // Widen checks to requests this tool depends on (bootstrap/login/etc.).
451
430
  dependencyRequestSeqs: [
452
431
  ...(opts.candidate?.dependencySeqs ?? []),
453
432
  ...(opts.sharedContext?.loginRequestSeqs ?? []),
454
433
  ],
455
- assignedSharedModules,
456
- tokenParams,
457
- tokenParamShapes,
458
- emittedTokens,
459
- requiredInputs,
460
434
  credentialValues: opts.teachCredentials?.values,
461
435
  credentialNames: opts.sharedContext?.credentialNames,
436
+ strategyKind: opts.strategyKind,
462
437
  deferLiveIntegrationToSemanticAgent: true,
438
+ expectedPublicParameters:
439
+ opts.verificationMode === 'master_mvp' ? opts.candidate?.likelyParams : undefined,
463
440
  });
464
- deadlineMs += Date.now() - deterministicVerificationStartedAt;
465
441
 
466
442
  if (warnings.length > 0) {
467
443
  log(`verification warnings (non-blocking):\n${warnings.join('\n')}`);
@@ -473,142 +449,77 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
473
449
  JSON.parse(readFileSync(pathJoin(absoluteToolDir, 'workflow.json'), 'utf8')),
474
450
  );
475
451
  }
476
- if (workflow && workflowHasIrreversibleEffect(workflow)) {
452
+ if (
453
+ failures.length === 0 &&
454
+ workflow &&
455
+ opts.strategyKind === 'playbook_fallback' &&
456
+ opts.verificationMode === 'master_mvp'
457
+ ) {
458
+ verificationSemantic = 'not_run';
459
+ message = result.doneSummary ?? 'Browser artifact contract passed';
460
+ message += '\n\nLive playbook verification is owned by the master.';
461
+ if (warnings.length > 0) message += `\n\nWarnings:\n${warnings.join('\n')}`;
462
+ if (!opts.keepTest) removeEphemeralTests(absoluteToolDir);
463
+ break;
464
+ }
465
+ if (failures.length === 0 && workflow && workflowHasIrreversibleEffect(workflow)) {
477
466
  warnings.push(...applyIrreversibleVerificationWaiver(absoluteToolDir, workflow));
478
- message = result.doneSummary ?? 'Task completed';
479
- message += `\n\nWarnings:\n${warnings.join('\n')}`;
480
- if (!opts.keepTest) {
481
- for (const file of ['parser.test.ts', 'request.test.ts', 'integration.test.ts']) {
482
- const testPath = pathJoin(absoluteToolDir, file);
483
- if (existsSync(testPath)) unlinkSync(testPath);
484
- }
485
- }
467
+ message = `${result.doneSummary ?? 'Task completed'}\n\nLive verification: N/A (irreversible workflow).`;
468
+ if (warnings.length > 0) message += `\n\nWarnings:\n${warnings.join('\n')}`;
469
+ if (!opts.keepTest) removeEphemeralTests(absoluteToolDir);
470
+ verificationSemantic = 'not_applicable';
471
+ break;
472
+ }
473
+
474
+ if (failures.length === 0 && opts.verificationMode === 'master_mvp') {
475
+ verificationSemantic = 'not_run';
476
+ message = result.doneSummary ?? 'Minimum viable artifact completed';
477
+ message += '\n\nIndependent live semantic verification: deferred to the master.';
478
+ if (warnings.length > 0) message += `\n\nWarnings:\n${warnings.join('\n')}`;
486
479
  break;
487
480
  }
488
481
 
489
482
  let semanticReviewCompleted = false;
490
483
  let semanticReviewAttempted = false;
484
+ let paramWarnings: string[] = [];
491
485
  if (failures.length === 0) {
492
- const doneInput = result.doneInput ?? {};
493
- const currentFingerprint = compileArtifactFingerprint(absoluteToolDir);
494
- if (
495
- pendingInconclusive &&
496
- canAcceptInconclusiveDecision({
497
- semanticVerificationCycles,
498
- maxVerificationCycles: MAX_VERIFICATION_CYCLES,
499
- completedReview: pendingInconclusive.report.completedReview,
500
- infrastructureOnly: isInfrastructureOnlyInconclusiveReport(
501
- pendingInconclusive.report.report,
502
- ),
503
- pendingFingerprint: pendingInconclusive.artifactFingerprint,
504
- currentFingerprint,
505
- acceptInconclusive: doneInput.accept_inconclusive === true,
506
- inconclusiveReason:
507
- typeof doneInput.inconclusive_reason === 'string'
508
- ? doneInput.inconclusive_reason
509
- : undefined,
510
- })
511
- ) {
512
- const semantic = pendingInconclusive.report;
513
- const inconclusiveReason = String(doneInput.inconclusive_reason).trim();
514
- applyLiveVerification(absoluteToolDir, {
515
- kind: 'waived-infra',
516
- firstError: inconclusiveReason,
517
- exhaustedBackends: [],
518
- });
519
- const paramWarnings = applyParamVerification(
486
+ semanticReviewAttempted = true;
487
+ const semantic = await runLiveSemanticVerification({
488
+ provider: DEFAULT_VERIFICATION_PROVIDER,
489
+ toolDir: absoluteToolDir,
490
+ evidence: integrationEvidence,
491
+ signal: opts.signal,
492
+ deadlineMs: runDeadline?.deadlineMs,
493
+ runDeadline,
494
+ onDeadlineReached: opts.onDeadlineReached,
495
+ });
496
+ semanticReviewCompleted = semantic.completedReview;
497
+ failures.push(...semanticVerificationFailures(semantic.report));
498
+ if (semantic.report.status === 'approved_with_gaps') {
499
+ warnings.push(
500
+ `independent semantic verification approved with gaps: ${semantic.report.gaps.join('; ')}`,
501
+ );
502
+ }
503
+ if (failures.length === 0) {
504
+ applyLiveVerification(absoluteToolDir, undefined);
505
+ paramWarnings = applyParamVerification(
520
506
  absoluteToolDir,
521
507
  mergeSemanticParamVerification(paramVerification, semantic.report),
522
508
  );
523
509
  rebindExistingBackendsCacheToWorkflow(absoluteToolDir);
524
- warnings.push(
525
- `independent semantic verification was inconclusive: ${semantic.report.summary}`,
526
- `compiler accepted the unchanged artifact without live verification: ${inconclusiveReason}`,
527
- ...paramWarnings,
528
- );
529
- message = result.doneSummary ?? 'Task completed';
530
- message += `\n\nWarnings:\n${warnings.join('\n')}`;
531
- if (!opts.keepTest) {
532
- for (const f of ['parser.test.ts', 'request.test.ts', 'integration.test.ts']) {
533
- const testPath = pathJoin(absoluteToolDir, f);
534
- if (existsSync(testPath)) unlinkSync(testPath);
535
- }
536
- }
537
- break;
538
510
  }
539
-
540
- const capDecision = inconclusiveDecisionAtSemanticCap({
541
- semanticVerificationCycles,
542
- maxVerificationCycles: MAX_VERIFICATION_CYCLES,
543
- pendingFingerprint: pendingInconclusive?.artifactFingerprint,
544
- currentFingerprint,
545
- });
546
- if (capDecision === 'fail-artifact-changed') {
547
- pendingInconclusive = undefined;
548
- failures.push(
549
- 'compile artifacts changed after the final allowed inconclusive semantic review; refusing to run an additional review beyond the semantic cycle cap',
550
- );
551
- } else if (capDecision === 'await-compiler-decision') {
552
- failures.push(
553
- 'semantic review limit reached with an unchanged infrastructure-only inconclusive result; explicitly accept the unverified artifact with reasoning or revise it',
554
- );
555
- } else {
556
- if (pendingInconclusive && pendingInconclusive.artifactFingerprint !== currentFingerprint) {
557
- pendingInconclusive = undefined;
558
- }
559
- const semanticVerificationStartedAt = Date.now();
560
- semanticReviewAttempted = true;
561
- const semantic = await runLiveSemanticVerification({
562
- provider: DEFAULT_VERIFICATION_PROVIDER,
563
- toolDir: absoluteToolDir,
564
- evidence: integrationEvidence,
565
- // Live semantic verification is a distinct phase. Do not inherit a
566
- // nearly exhausted compile-agent deadline.
567
- });
568
- deadlineMs += Date.now() - semanticVerificationStartedAt;
569
- semanticReviewCompleted = semantic.completedReview;
570
- if (semantic.report.status === 'inconclusive') {
571
- pendingInconclusive = {
572
- artifactFingerprint: compileArtifactFingerprint(absoluteToolDir),
573
- report: semantic,
574
- };
575
- } else {
576
- pendingInconclusive = undefined;
577
- }
578
- failures.push(...semanticVerificationFailures(semantic.report));
579
- if (semantic.report.status === 'approved_with_gaps') {
580
- warnings.push(
581
- `independent semantic verification approved with gaps: ${semantic.report.gaps.join('; ')}`,
582
- );
511
+ if (failures.length === 0 && workflow) {
512
+ const allWarnings = [...warnings, ...paramWarnings];
513
+ if (paramWarnings.length > 0) {
514
+ log(`parameter verification:\n${paramWarnings.join('\n')}`);
583
515
  }
584
- if (failures.length === 0) {
585
- // Success (possibly with explicit semantic gaps). Persist per-parameter
586
- // flags and mint liveVerified=true only after independent approval.
587
- applyLiveVerification(absoluteToolDir, undefined);
588
- const paramWarnings = applyParamVerification(
589
- absoluteToolDir,
590
- mergeSemanticParamVerification(paramVerification, semantic.report),
591
- );
592
- // liveVerified/parameter annotations change the hash-strict cache key,
593
- // but not transport capabilities. Rebind the backend already exercised
594
- // by the verifier instead of triggering another probe.
595
- rebindExistingBackendsCacheToWorkflow(absoluteToolDir);
596
- const allWarnings = [...warnings, ...paramWarnings];
597
- if (paramWarnings.length > 0) {
598
- log(`parameter verification:\n${paramWarnings.join('\n')}`);
599
- }
600
- message = result.doneSummary ?? 'Task completed';
601
- if (allWarnings.length > 0) {
602
- message += `\n\nWarnings:\n${allWarnings.join('\n')}`;
603
- }
604
- if (!opts.keepTest) {
605
- for (const f of ['parser.test.ts', 'request.test.ts', 'integration.test.ts']) {
606
- const testPath = pathJoin(absoluteToolDir, f);
607
- if (existsSync(testPath)) unlinkSync(testPath);
608
- }
609
- }
610
- break;
516
+ message = result.doneSummary ?? 'Task completed';
517
+ if (allWarnings.length > 0) {
518
+ message += `\n\nWarnings:\n${allWarnings.join('\n')}`;
611
519
  }
520
+ if (!opts.keepTest) removeEphemeralTests(absoluteToolDir);
521
+ verificationSemantic = 'approved';
522
+ if (failures.length === 0) break;
612
523
  }
613
524
  }
614
525
 
@@ -627,12 +538,7 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
627
538
  message = `Independent semantic verifier failed to complete after ${MAX_INCOMPLETE_VERIFIER_RUNS} bounded runs. Final failures:\n${failures.join('\n')}`;
628
539
  break;
629
540
  }
630
- const awaitingFinalInconclusiveDecision =
631
- semanticVerificationCycles >= MAX_VERIFICATION_CYCLES && pendingInconclusive !== undefined;
632
- if (
633
- semanticVerificationCycles >= MAX_VERIFICATION_CYCLES &&
634
- !awaitingFinalInconclusiveDecision
635
- ) {
541
+ if (semanticVerificationCycles >= MAX_VERIFICATION_CYCLES) {
636
542
  outcome = 'error';
637
543
  message = `Semantic verification failed after ${MAX_VERIFICATION_CYCLES} cycles. Final failures:\n${failures.join('\n')}`;
638
544
  break;
@@ -644,19 +550,15 @@ Begin by calling read_session_summary to orient yourself, then proceed per the s
644
550
  ? 'semantic verifier did not complete a review (semantic cycle limit unchanged)'
645
551
  : 'deterministic verification failed (semantic cycle limit unchanged)';
646
552
  log(`${failurePhase}, resuming agent loop...`);
553
+ const repairFiles =
554
+ opts.strategyKind === 'playbook_fallback'
555
+ ? 'workflow.json and playbook.yaml'
556
+ : 'workflow.json, parser.ts, and parser.test.ts';
647
557
  currentInitialMessage = `You called done but ${failurePhase}:
648
558
 
649
559
  ${failures.map((f) => `- ${f}`).join('\n')}
650
560
 
651
- 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.`;
652
- currentInitialMessage += `\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. Do not use a limitation to hide a broken core tool, and do not keep a known broken or ignored public input.`;
653
- if (pendingInconclusive) {
654
- currentInitialMessage +=
655
- semanticVerificationCycles >= MAX_VERIFICATION_CYCLES &&
656
- pendingInconclusive.report.completedReview
657
- ? '\n\nThe final allowed live semantic review was infrastructure-only inconclusive. Review its evidence and log. If no tool defect is exposed and the unchanged deterministic artifact should ship explicitly unverified, call done again with accept_inconclusive=true and a concrete inconclusive_reason. This does not mint liveVerified.'
658
- : '\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.';
659
- }
561
+ Resume your work. Read the files you wrote (${repairFiles}), fix the issues, re-run the applicable checks, and call done again when fixed.`;
660
562
  }
661
563
 
662
564
  // 10. Final flush of the complete conversation log
@@ -670,6 +572,19 @@ Resume your work. Read the files you wrote (workflow.json, parser.ts, parser.tes
670
572
  return {
671
573
  success: outcome === 'done',
672
574
  outcome,
575
+ ...(outcome === 'done'
576
+ ? {
577
+ verification: {
578
+ mode: opts.verificationMode ?? 'full',
579
+ deterministic: 'passed' as const,
580
+ semantic: verificationSemantic ?? 'approved',
581
+ ...(verificationSemantic === 'approved' &&
582
+ existsSync(pathJoin(absoluteToolDir, '.live-verification.json'))
583
+ ? { reportPath: pathJoin(absoluteToolDir, '.live-verification.json') }
584
+ : {}),
585
+ },
586
+ }
587
+ : {}),
673
588
  workflowPath: existsSync(workflowPath) ? workflowPath : undefined,
674
589
  parserPath: existsSync(parserPath) ? parserPath : undefined,
675
590
  // parserTestPath only set if it survived (--keep-test); otherwise undefined.