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
@@ -0,0 +1,326 @@
1
+ /** Runs only in the isolated IMPRINT_HOME created by `imprint refine`. */
2
+ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
3
+ import { basename, join } from 'node:path';
4
+ import { z } from 'zod';
5
+ import { runAudit } from './audit.ts';
6
+ import { runWorkflowWithLadder } from './backend-ladder.ts';
7
+ import { generate } from './compile.ts';
8
+ import { extractCredentials } from './credential-extract.ts';
9
+ import { workflowHasIrreversibleEffect } from './effects.ts';
10
+ import { emit } from './emit.ts';
11
+ import { requestRefinementPlan } from './master-teach-agents.ts';
12
+ import { extractJsonResultPath } from './master-teach-checks.ts';
13
+ import { localSiteDir } from './paths.ts';
14
+ import { RunDeadline } from './provider-retry.ts';
15
+ import {
16
+ type RecordingFixture,
17
+ parseRecordedResponses,
18
+ verifyRecordingEvidence,
19
+ } from './recording-verification.ts';
20
+ import { redactSession } from './redact.ts';
21
+ import { assertRefinementContract, mergeRefinementVerificationPlan } from './refine.ts';
22
+ import { ensureImprintRuntimeLink } from './runtime-link.ts';
23
+ import { shutdownTracing, traced } from './tracing.ts';
24
+ import { SessionSchema, WorkflowSchema } from './types.ts';
25
+
26
+ const Params = z.record(z.union([z.string(), z.number(), z.boolean()]));
27
+ const Plan = z
28
+ .object({
29
+ tools: z
30
+ .array(
31
+ z
32
+ .object({
33
+ name: z.string().regex(/^[a-zA-Z0-9_-]+$/),
34
+ instruction: z.string().min(1),
35
+ parameters: z.array(
36
+ z
37
+ .object({
38
+ name: z.string(),
39
+ type: z.enum(['string', 'number', 'boolean']),
40
+ description: z.string(),
41
+ })
42
+ .strict(),
43
+ ),
44
+ requestSeqs: z.array(z.number().int().nonnegative()).min(1),
45
+ cases: z
46
+ .array(
47
+ z
48
+ .object({
49
+ id: z.string().regex(/^[a-z0-9_-]+$/),
50
+ requestSeqs: z.array(z.number().int().nonnegative()).min(1).optional(),
51
+ recordedParameters: Params,
52
+ liveParameters: Params,
53
+ freshnessChanges: z.string().min(1),
54
+ bindings: z.array(
55
+ z
56
+ .object({
57
+ producerTool: z.string(),
58
+ path: z.string(),
59
+ parameter: z.string(),
60
+ })
61
+ .strict(),
62
+ ),
63
+ })
64
+ .strict(),
65
+ )
66
+ .min(1)
67
+ .max(3),
68
+ })
69
+ .strict(),
70
+ )
71
+ .max(16),
72
+ })
73
+ .strict();
74
+ const Config = z.object({
75
+ site: z.string(),
76
+ tool: z.string(),
77
+ issue: z.string(),
78
+ recordingPath: z.string(),
79
+ runRoot: z.string(),
80
+ stagedHome: z.string(),
81
+ deadlineMs: z.number(),
82
+ provider: z.enum(['codex-cli', 'claude-cli']),
83
+ model: z.string().optional(),
84
+ });
85
+
86
+ async function refineStage(config: z.infer<typeof Config>): Promise<string[]> {
87
+ ensureImprintRuntimeLink(config.stagedHome);
88
+ const runDeadline = new RunDeadline(config.deadlineMs);
89
+ const signal = AbortSignal.timeout(Math.max(1, config.deadlineMs - Date.now()));
90
+ const agent = { provider: config.provider, model: config.model, runDeadline, signal };
91
+ const original = SessionSchema.parse(JSON.parse(readFileSync(config.recordingPath, 'utf8')));
92
+ const { session } = redactSession(original, {
93
+ replacements: extractCredentials(original).replacements,
94
+ });
95
+ const sessionPath = join(config.runRoot, 'recording.redacted.json');
96
+ writeFileSync(sessionPath, JSON.stringify(session));
97
+ const siteDir = localSiteDir(config.site);
98
+ const installed = readdirSync(siteDir)
99
+ .filter((name) => existsSync(join(siteDir, name, 'workflow.json')))
100
+ .map((name) => ({
101
+ name,
102
+ verificationPlan: existsSync(join(siteDir, name, '.verification-plan.json'))
103
+ ? JSON.parse(readFileSync(join(siteDir, name, '.verification-plan.json'), 'utf8'))
104
+ : {},
105
+ workflow: WorkflowSchema.parse(
106
+ JSON.parse(readFileSync(join(siteDir, name, 'workflow.json'), 'utf8')),
107
+ ),
108
+ }));
109
+ const plan = await requestRefinementPlan(
110
+ {
111
+ issue: config.issue,
112
+ target: config.tool,
113
+ installed,
114
+ recordingPath: sessionPath,
115
+ requests: session.requests.map(({ seq, method, url }) => ({ seq, method, url })),
116
+ },
117
+ Plan,
118
+ agent,
119
+ );
120
+ writeFileSync(join(config.runRoot, 'plan.json'), JSON.stringify(plan, null, 2));
121
+ if (!plan.tools.length) throw new Error('Recording does not support the requested refinement');
122
+ if (
123
+ !plan.tools.some(({ name }) => name === config.tool) ||
124
+ new Set(plan.tools.map(({ name }) => name)).size !== plan.tools.length
125
+ )
126
+ throw new Error('Refinement plan must include the target exactly once');
127
+ const outputs = new Map<string, unknown>();
128
+ for (const tool of plan.tools) {
129
+ const before = installed.find(({ name }) => name === tool.name)?.workflow;
130
+ if (!before) throw new Error(`Unknown installed tool ${tool.name}`);
131
+ if (
132
+ before.toolKind === 'authenticate' ||
133
+ before.authConfig ||
134
+ workflowHasIrreversibleEffect(before)
135
+ )
136
+ throw new Error(
137
+ 'Refine currently supports data tools without irreversible effects; authentication programs require teach',
138
+ );
139
+ if (tool.requestSeqs.some((seq) => !session.requests.some((request) => request.seq === seq)))
140
+ throw new Error('Refinement references unavailable recording requests');
141
+ for (const test of tool.cases)
142
+ for (const binding of test.bindings)
143
+ if (!outputs.has(binding.producerTool))
144
+ throw new Error('Refinement dependencies must run producer first');
145
+ const toolDir = join(siteDir, tool.name);
146
+ // Seeded runtime files are available only in this refinement. Fresh teach
147
+ // never enters this path or sees installed artifacts.
148
+ const generated = await generate({
149
+ sessionPath,
150
+ outDir: toolDir,
151
+ llmConfig: { provider: config.provider, model: config.model },
152
+ runDeadline,
153
+ signal,
154
+ keepTest: true,
155
+ revisionMode: true,
156
+ verificationMode: 'master_mvp',
157
+ candidate: {
158
+ toolName: tool.name,
159
+ description: before.intent.description,
160
+ rationale: tool.instruction,
161
+ confidence: 1,
162
+ requestSeqs: tool.requestSeqs,
163
+ representativeSeqs: tool.requestSeqs,
164
+ eventSeqs: [],
165
+ expectedOutput: tool.instruction,
166
+ likelyParams: tool.parameters,
167
+ dependencySeqs: [],
168
+ dependsOnTools: tool.cases.flatMap(({ bindings }) =>
169
+ bindings.map(({ producerTool }) => producerTool),
170
+ ),
171
+ },
172
+ toolPlan: JSON.stringify({
173
+ mode: 'refine',
174
+ issue: config.issue,
175
+ instruction: tool.instruction,
176
+ previousWorkflow: before,
177
+ fixedCases: tool.cases,
178
+ preserveExistingBehavior: true,
179
+ }),
180
+ });
181
+ assertRefinementContract(before, generated.workflow);
182
+ emit({ workflowPath: generated.workflowPath, outDir: toolDir, force: true });
183
+ const fixtures: RecordingFixture[] = [];
184
+ for (const test of tool.cases) {
185
+ const requestSeqs = test.requestSeqs ?? tool.requestSeqs;
186
+ const responses = requestSeqs.map((seq) => {
187
+ const body = session.requests.find((request) => request.seq === seq)?.response?.body;
188
+ if (body === undefined) throw new Error(`Recording response ${seq} is unavailable`);
189
+ try {
190
+ return JSON.parse(body);
191
+ } catch {
192
+ return body;
193
+ }
194
+ });
195
+ fixtures.push({
196
+ id: `${test.id}_recording`,
197
+ origin: 'recording',
198
+ requestSeqs,
199
+ parameters: test.recordedParameters,
200
+ responses,
201
+ recordedRequests: requestSeqs.map((seq) => {
202
+ const request = session.requests.find((request) => request.seq === seq);
203
+ if (!request) throw new Error(`Recording request ${seq} is unavailable`);
204
+ return { seq, method: request.method, url: request.url, body: request.body };
205
+ }),
206
+ actual: await parseRecordedResponses(
207
+ generated.workflowPath,
208
+ generated.workflow,
209
+ responses,
210
+ test.recordedParameters,
211
+ ),
212
+ });
213
+ const parameters = { ...test.liveParameters };
214
+ for (const binding of test.bindings) {
215
+ const value = extractJsonResultPath(outputs.get(binding.producerTool), binding.path);
216
+ if (!value.ok || !['string', 'number', 'boolean'].includes(typeof value.value))
217
+ throw new Error('Fresh producer value is unavailable or not a scalar parameter');
218
+ parameters[binding.parameter] = value.value as string | number | boolean;
219
+ }
220
+ let rawResponses: unknown[] | undefined;
221
+ const live = await runWorkflowWithLadder({
222
+ workflowPath: generated.workflowPath,
223
+ params: parameters,
224
+ signal,
225
+ onRawResponses: (responses) => {
226
+ rawResponses = responses;
227
+ },
228
+ });
229
+ if (!live.result.ok || !rawResponses)
230
+ throw new Error(`Refined live case ${test.id} failed: ${JSON.stringify(live.result)}`);
231
+ if (!outputs.has(tool.name)) outputs.set(tool.name, live.result.data);
232
+ fixtures.push({
233
+ id: `${test.id}_live`,
234
+ origin: 'live',
235
+ requestSeqs,
236
+ parameters,
237
+ responses: rawResponses,
238
+ actual: live.result.data,
239
+ freshnessChanges: test.freshnessChanges,
240
+ });
241
+ }
242
+ const reviewed = await verifyRecordingEvidence({
243
+ operation: {
244
+ name: tool.name,
245
+ description: before.intent.description,
246
+ expectedOutput: tool.instruction,
247
+ },
248
+ fixtures,
249
+ directory: join(config.runRoot, 'verification', tool.name),
250
+ agent,
251
+ });
252
+ if (reviewed.status !== 'passed') throw new Error(reviewed.reason);
253
+ writeFileSync(
254
+ join(toolDir, '.verification-plan.json'),
255
+ JSON.stringify(
256
+ mergeRefinementVerificationPlan(
257
+ installed.find(({ name }) => name === tool.name)?.verificationPlan ?? {},
258
+ {
259
+ recordingPath: sessionPath,
260
+ cases: tool.cases.map((test) => ({
261
+ id: `refine_${basename(config.runRoot)}_${test.id}`,
262
+ parameters: test.liveParameters,
263
+ recordedCall: {
264
+ requestSeqs: test.requestSeqs ?? tool.requestSeqs,
265
+ freshnessChanges: test.freshnessChanges,
266
+ },
267
+ bindings: test.bindings,
268
+ })),
269
+ dependencies: tool.cases.flatMap(({ bindings }) =>
270
+ bindings.map((binding) => ({
271
+ producerTool: binding.producerTool,
272
+ producerResultPath: binding.path,
273
+ consumerParameter: binding.parameter,
274
+ })),
275
+ ),
276
+ },
277
+ ),
278
+ null,
279
+ 2,
280
+ ),
281
+ );
282
+ }
283
+ const audit = await runAudit({
284
+ site: config.site,
285
+ strict: true,
286
+ minScore: 100,
287
+ outPath: join(config.runRoot, 'audit.json'),
288
+ provider: config.provider,
289
+ model: config.model,
290
+ timeoutMs: Math.max(1, config.deadlineMs - Date.now()),
291
+ json: true,
292
+ });
293
+ if (audit.verdict !== 'pass')
294
+ throw new Error(`Staged strict audit ${audit.verdict}; originals preserved`);
295
+ return plan.tools.map(({ name }) => name);
296
+ }
297
+
298
+ if (import.meta.main) {
299
+ const configPath = process.argv[2];
300
+ if (!configPath) throw new Error('Refinement worker requires a configuration path');
301
+ const config = Config.parse(JSON.parse(readFileSync(configPath, 'utf8')));
302
+ try {
303
+ const tools = await traced(
304
+ 'imprint.refine',
305
+ 'AGENT',
306
+ { 'imprint.site': config.site, 'imprint.tool_name': config.tool },
307
+ () => refineStage(config),
308
+ );
309
+ writeFileSync(
310
+ join(config.runRoot, 'result.json'),
311
+ JSON.stringify({ status: 'completed', tools }),
312
+ );
313
+ } catch (error) {
314
+ writeFileSync(
315
+ join(config.runRoot, 'result.json'),
316
+ JSON.stringify({
317
+ status: 'failed',
318
+ tools: [],
319
+ reason: error instanceof Error ? error.message : String(error),
320
+ }),
321
+ );
322
+ process.exitCode = 1;
323
+ } finally {
324
+ await shutdownTracing();
325
+ }
326
+ }
@@ -0,0 +1,241 @@
1
+ /** Targeted, staged refinement of installed tools. Originals change only after verification. */
2
+ import { createHash, randomUUID } from 'node:crypto';
3
+ import {
4
+ cpSync,
5
+ existsSync,
6
+ mkdirSync,
7
+ readFileSync,
8
+ readdirSync,
9
+ renameSync,
10
+ writeFileSync,
11
+ } from 'node:fs';
12
+ import { join, resolve } from 'node:path';
13
+ import { newestRecording } from './cdp-jar-cache.ts';
14
+ import { runOwnedCli } from './compiler-process.ts';
15
+ import type { ProviderName } from './llm.ts';
16
+ import { imprintHomeDir, localSiteDir, localToolDir } from './paths.ts';
17
+ import { SessionSchema, type Workflow, WorkflowSchema } from './types.ts';
18
+
19
+ interface RefineOptions {
20
+ site: string;
21
+ tool: string;
22
+ issue: string;
23
+ fromSession?: string;
24
+ provider: ProviderName;
25
+ model?: string;
26
+ timeoutMs?: number;
27
+ json?: boolean;
28
+ }
29
+ interface RefinementVerificationPlan {
30
+ recordingPath?: string;
31
+ cases?: Array<{ id: string; [key: string]: unknown }>;
32
+ dependencies?: unknown[];
33
+ }
34
+ /** Keep previously passing cases visible to the strict audit after refinement. */
35
+ export function mergeRefinementVerificationPlan(
36
+ previous: RefinementVerificationPlan,
37
+ added: RefinementVerificationPlan,
38
+ ): RefinementVerificationPlan {
39
+ const cases = [
40
+ ...(previous.cases ?? []).map((test) => ({
41
+ recordingPath: previous.recordingPath,
42
+ ...test,
43
+ })),
44
+ ...(added.cases ?? []),
45
+ ];
46
+ if (new Set(cases.map(({ id }) => id)).size !== cases.length)
47
+ throw new Error('Refinement verification case IDs must be unique');
48
+ return {
49
+ ...added,
50
+ cases,
51
+ dependencies: [...(previous.dependencies ?? []), ...(added.dependencies ?? [])],
52
+ };
53
+ }
54
+ export function assertRefinementContract(before: Workflow, after: Workflow): void {
55
+ if (before.site !== after.site || before.toolName !== after.toolName)
56
+ throw new Error('Refinement changed the installed tool identity');
57
+ for (const prior of before.parameters) {
58
+ const next = after.parameters.find(({ name }) => name === prior.name);
59
+ if (
60
+ !next ||
61
+ next.type !== prior.type ||
62
+ (prior.default !== undefined && next.default === undefined)
63
+ )
64
+ throw new Error(`Refinement broke existing parameter ${prior.name}`);
65
+ if (
66
+ prior.choices &&
67
+ next.choices &&
68
+ prior.choices.some((value) => !next.choices?.includes(value))
69
+ )
70
+ throw new Error(`Refinement removed supported values from ${prior.name}`);
71
+ }
72
+ for (const next of after.parameters) {
73
+ if (!before.parameters.some(({ name }) => name === next.name) && next.default === undefined)
74
+ throw new Error(`New parameter ${next.name} must be optional for existing callers`);
75
+ }
76
+ }
77
+ export function refinementArtifactHash(directory: string): string {
78
+ const hash = createHash('sha256');
79
+ const visit = (dir: string, prefix = ''): void => {
80
+ for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
81
+ a.name.localeCompare(b.name),
82
+ )) {
83
+ if (
84
+ entry.name.startsWith('.') ||
85
+ entry.name === 'node_modules' ||
86
+ entry.name === 'backends.json'
87
+ )
88
+ continue;
89
+ const path = join(dir, entry.name);
90
+ const name = `${prefix}${entry.name}`;
91
+ if (entry.isDirectory()) visit(path, `${name}/`);
92
+ else if (entry.isFile()) hash.update(name).update(readFileSync(path));
93
+ }
94
+ };
95
+ visit(directory);
96
+ return hash.digest('hex');
97
+ }
98
+ export function promoteRefinement(input: {
99
+ siteDir: string;
100
+ stagedSiteDir: string;
101
+ runRoot: string;
102
+ runId: string;
103
+ tools: string[];
104
+ originalHashes: Record<string, string>;
105
+ }): void {
106
+ for (const tool of input.tools) {
107
+ if (refinementArtifactHash(join(input.siteDir, tool)) !== input.originalHashes[tool])
108
+ throw new Error(
109
+ `Installed tool ${tool} changed during refinement; staging retained without promotion`,
110
+ );
111
+ }
112
+ const moved: { destination: string; backup: string; tool: string }[] = [];
113
+ try {
114
+ for (const tool of input.tools) {
115
+ const destination = join(input.siteDir, tool);
116
+ const backup = join(input.siteDir, `.refine-backup-${input.runId}-${tool}`);
117
+ renameSync(destination, backup);
118
+ moved.push({ destination, backup, tool });
119
+ cpSync(join(input.stagedSiteDir, tool), destination, { recursive: true, dereference: false });
120
+ }
121
+ } catch (error) {
122
+ const failed = join(input.runRoot, 'failed-promotion');
123
+ mkdirSync(failed, { recursive: true });
124
+ for (const { destination, backup, tool } of moved.reverse()) {
125
+ if (existsSync(destination)) renameSync(destination, join(failed, tool));
126
+ renameSync(backup, destination);
127
+ }
128
+ throw error;
129
+ }
130
+ }
131
+ export async function runRefine(
132
+ opts: RefineOptions,
133
+ ): Promise<{ status: 'completed' | 'failed'; runRoot: string; reason?: string }> {
134
+ const siteDir = localSiteDir(opts.site);
135
+ const target = localToolDir(opts.site, opts.tool);
136
+ if (!opts.issue.trim()) throw new Error('--issue must describe a repair or extension');
137
+ if (!existsSync(join(target, 'workflow.json')))
138
+ throw new Error(`Installed tool ${opts.tool} is unavailable`);
139
+ const recordingPath = opts.fromSession
140
+ ? resolve(opts.fromSession)
141
+ : newestRecording(siteDir)?.path;
142
+ if (!recordingPath) throw new Error('No retained recording found; provide --from-session <path>');
143
+ const recording = SessionSchema.parse(JSON.parse(readFileSync(recordingPath, 'utf8')));
144
+ if (recording.site !== opts.site) throw new Error('Refinement recording belongs to another site');
145
+ const runId = randomUUID();
146
+ const runRoot = join(imprintHomeDir(), '.refine-runs', runId);
147
+ const stagedHome = join(runRoot, 'home');
148
+ const stagedSiteDir = join(stagedHome, opts.site);
149
+ mkdirSync(stagedSiteDir, { recursive: true, mode: 0o700 });
150
+ const originalHashes: Record<string, string> = {};
151
+ for (const entry of readdirSync(siteDir, { withFileTypes: true })) {
152
+ if (
153
+ !entry.isDirectory() ||
154
+ entry.name.startsWith('.') ||
155
+ !existsSync(join(siteDir, entry.name, 'workflow.json'))
156
+ )
157
+ continue;
158
+ originalHashes[entry.name] = refinementArtifactHash(join(siteDir, entry.name));
159
+ cpSync(join(siteDir, entry.name), join(stagedSiteDir, entry.name), {
160
+ recursive: true,
161
+ dereference: false,
162
+ });
163
+ }
164
+ const configPath = join(runRoot, 'input.json');
165
+ const timeoutMs = opts.timeoutMs ?? 30 * 60_000;
166
+ writeFileSync(
167
+ configPath,
168
+ JSON.stringify(
169
+ { ...opts, recordingPath, runRoot, stagedHome, deadlineMs: Date.now() + timeoutMs },
170
+ null,
171
+ 2,
172
+ ),
173
+ );
174
+ let child: Awaited<ReturnType<typeof runOwnedCli>>;
175
+ try {
176
+ child = await runOwnedCli({
177
+ command: process.execPath,
178
+ args: ['run', join(import.meta.dir, 'refine-worker.ts'), configPath],
179
+ cwd: resolve(import.meta.dir, '../..'),
180
+ env: { ...process.env, IMPRINT_HOME: stagedHome },
181
+ signal: AbortSignal.timeout(timeoutMs),
182
+ onStderrChunk: (chunk) => process.stderr.write(chunk),
183
+ });
184
+ } catch (error) {
185
+ const reason = error instanceof Error ? error.message : String(error);
186
+ writeFileSync(
187
+ join(runRoot, 'interrupted.json'),
188
+ JSON.stringify({ reason, at: new Date().toISOString() }),
189
+ );
190
+ return { status: 'failed', runRoot, reason };
191
+ }
192
+ writeFileSync(join(runRoot, 'worker.stdout.log'), child.stdout);
193
+ writeFileSync(join(runRoot, 'worker.stderr.log'), child.stderr);
194
+ const reportPath = join(runRoot, 'result.json');
195
+ const report = existsSync(reportPath)
196
+ ? (JSON.parse(readFileSync(reportPath, 'utf8')) as {
197
+ status: string;
198
+ tools: string[];
199
+ reason?: string;
200
+ })
201
+ : { status: 'failed', tools: [], reason: 'Refinement worker ended without verification' };
202
+ if (child.exitCode !== 0 || report.status !== 'completed')
203
+ return {
204
+ status: 'failed',
205
+ runRoot,
206
+ reason: report.reason ?? 'Verification did not pass; installed tools preserved',
207
+ };
208
+ if (
209
+ !report.tools.length ||
210
+ !report.tools.includes(opts.tool) ||
211
+ report.tools.some((tool) => !Object.hasOwn(originalHashes, tool))
212
+ )
213
+ throw new Error('Refinement returned an invalid replacement set');
214
+ for (const [tool, originalHash] of Object.entries(originalHashes)) {
215
+ if (
216
+ !report.tools.includes(tool) &&
217
+ refinementArtifactHash(join(stagedSiteDir, tool)) !== originalHash
218
+ )
219
+ throw new Error(`Unplanned tool ${tool} changed in staging; originals preserved`);
220
+ }
221
+ for (const tool of report.tools)
222
+ assertRefinementContract(
223
+ WorkflowSchema.parse(JSON.parse(readFileSync(join(siteDir, tool, 'workflow.json'), 'utf8'))),
224
+ WorkflowSchema.parse(
225
+ JSON.parse(readFileSync(join(stagedSiteDir, tool, 'workflow.json'), 'utf8')),
226
+ ),
227
+ );
228
+ promoteRefinement({
229
+ siteDir,
230
+ stagedSiteDir,
231
+ runRoot,
232
+ runId,
233
+ tools: report.tools,
234
+ originalHashes,
235
+ });
236
+ writeFileSync(
237
+ join(runRoot, 'promotion.json'),
238
+ JSON.stringify({ tools: report.tools, completedAt: new Date().toISOString() }),
239
+ );
240
+ return { status: 'completed', runRoot };
241
+ }
@@ -49,6 +49,10 @@ interface RawReplayOptions {
49
49
  session: Session;
50
50
  site: string;
51
51
  headed?: boolean;
52
+ /** Exact values extracted from this recording. They let a redacted event
53
+ * carrying `${credential.NAME}` replay the same user input without turning
54
+ * the placeholder into a failed or skipped interaction. */
55
+ credentials?: Record<string, string>;
52
56
  onProgress?: (current: number, total: number, captured: number) => void;
53
57
  }
54
58
 
@@ -57,7 +61,7 @@ const CREDENTIAL_PLACEHOLDER = /^\$\{credential\.([A-Za-z0-9_.-]+)\}$/;
57
61
  /** Resolve only a complete credential placeholder. Embedded or missing
58
62
  * placeholders are rejected so replay never types placeholder text or a partial
59
63
  * secret interpolation into the page. */
60
- export function resolveReplayEventValue(
64
+ function resolveReplayEventValue(
61
65
  value: string,
62
66
  credentials: Record<string, string>,
63
67
  ): string | null {
@@ -69,6 +73,23 @@ export function resolveReplayEventValue(
69
73
  return value.includes('${credential.') ? null : value;
70
74
  }
71
75
 
76
+ export function resolveReplayInputValue(
77
+ value: unknown,
78
+ credentials: Record<string, string>,
79
+ ): string | null {
80
+ return typeof value === 'string' ? resolveReplayEventValue(value, credentials) : null;
81
+ }
82
+
83
+ /** Allocate identity at request time so a later out-of-order response cannot
84
+ * reorder the independently observed execution. */
85
+ export function createReplayRequestIdentityAllocator(
86
+ startTime: number,
87
+ now: () => number = Date.now,
88
+ ): () => { seq: number; timestamp: number } {
89
+ let nextSeq = 0;
90
+ return () => ({ seq: nextSeq++, timestamp: now() - startTime });
91
+ }
92
+
72
93
  /**
73
94
  * Replay the raw DOM events from an original recording in a fresh browser,
74
95
  * capturing all network requests. This is the site-level dual-pass strategy:
@@ -97,19 +118,19 @@ export async function replayRawSession(opts: RawReplayOptions): Promise<ReplayCa
97
118
  }
98
119
 
99
120
  const captured: CapturedReplayRequest[] = [];
100
- let seq = 0;
101
121
  const startTime = Date.now();
122
+ const allocateRequestIdentity = createReplayRequestIdentityAllocator(startTime);
102
123
  try {
103
124
  context = await browser.newContext();
104
125
  const page = await context.newPage();
105
126
  replayLog('browser context + page created');
106
127
 
107
128
  // Inject credentials if available
108
- let credentialValues: Record<string, string> = {};
129
+ let credentialValues: Record<string, string> = { ...opts.credentials };
109
130
  try {
110
131
  const { loadSiteCredentials } = await import('./credential-store.ts');
111
132
  const view = await loadSiteCredentials(opts.site);
112
- credentialValues = view.values;
133
+ credentialValues = { ...view.values, ...opts.credentials };
113
134
  const playwrightCookies = view.cookies
114
135
  .map((c) => ({ name: c.name, value: c.value, domain: c.domain, path: c.path }))
115
136
  .filter((c) => c.name && c.value);
@@ -126,11 +147,19 @@ export async function replayRawSession(opts: RawReplayOptions): Promise<ReplayCa
126
147
  let reqId = 0;
127
148
  const requestMeta = new Map<
128
149
  string,
129
- { method: string; url: string; headers: Record<string, string>; body?: string }
150
+ {
151
+ seq: number;
152
+ timestamp: number;
153
+ method: string;
154
+ url: string;
155
+ headers: Record<string, string>;
156
+ body?: string;
157
+ }
130
158
  >();
131
159
  page.on('request', (req) => {
132
160
  const id = `${reqId++}`;
133
161
  requestMeta.set(id, {
162
+ ...allocateRequestIdentity(),
134
163
  method: req.method(),
135
164
  url: req.url(),
136
165
  headers: req.headers(),
@@ -144,7 +173,7 @@ export async function replayRawSession(opts: RawReplayOptions): Promise<ReplayCa
144
173
  const req = resp.request();
145
174
  const id = (req as unknown as Record<string, string>).__replayCaptureId;
146
175
  const meta = id ? requestMeta.get(id) : undefined;
147
- const currentSeq = seq++;
176
+ const identity = meta ?? allocateRequestIdentity();
148
177
  const method = meta?.method ?? req.method();
149
178
  const url = meta?.url ?? resp.url();
150
179
  const headers = meta?.headers ?? req.headers();
@@ -153,8 +182,8 @@ export async function replayRawSession(opts: RawReplayOptions): Promise<ReplayCa
153
182
  .text()
154
183
  .then((respBody) => {
155
184
  captured.push({
156
- seq: currentSeq,
157
- timestamp: Date.now() - startTime,
185
+ seq: identity.seq,
186
+ timestamp: identity.timestamp,
158
187
  method,
159
188
  url,
160
189
  headers,
@@ -170,8 +199,8 @@ export async function replayRawSession(opts: RawReplayOptions): Promise<ReplayCa
170
199
  })
171
200
  .catch(() => {
172
201
  captured.push({
173
- seq: currentSeq,
174
- timestamp: Date.now() - startTime,
202
+ seq: identity.seq,
203
+ timestamp: identity.timestamp,
175
204
  method,
176
205
  url,
177
206
  headers,
@@ -302,11 +331,11 @@ async function replayEvent(
302
331
 
303
332
  if (event.type === 'input' || event.type === 'change') {
304
333
  const loc = buildLocatorFromEvent(page, d);
305
- if (!loc || !d.value) {
334
+ if (!loc || typeof d.value !== 'string') {
306
335
  replayLog(` skip ${event.type}: no locator or no value`);
307
336
  return;
308
337
  }
309
- const resolvedValue = resolveReplayEventValue(d.value, credentials);
338
+ const resolvedValue = resolveReplayInputValue(d.value, credentials);
310
339
  if (resolvedValue === null) {
311
340
  replayLog(` skip ${event.type}: credential placeholder could not be resolved safely`);
312
341
  return;