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.
- package/CHANGELOG.md +22 -0
- package/README.md +278 -16
- package/package.json +2 -2
- package/prompts/audit-agent.md +25 -4
- package/prompts/auth-compile-agent.md +28 -12
- package/prompts/build-planning.md +3 -3
- package/prompts/compile-agent.md +895 -180
- package/prompts/live-verifier-agent.md +10 -3
- package/prompts/master-teach-api-researcher.md +813 -0
- package/prompts/master-teach-baseline-mvp-review.md +217 -0
- package/prompts/master-teach-completion-review.md +188 -0
- package/prompts/master-teach-decision.md +885 -0
- package/prompts/master-teach-focused-planner.md +764 -0
- package/prompts/master-teach-parameter-advisor.md +58 -0
- package/prompts/master-teach-recording-evidence.md +19 -0
- package/prompts/master-teach-refine-plan.md +7 -0
- package/prompts/master-teach-tool-advisor.md +130 -0
- package/prompts/playbook-compilation.md +45 -54
- package/prompts/prereq-builder.md +28 -6
- package/prompts/prereq-planner.md +2 -2
- package/prompts/tool-candidate-detection.md +70 -39
- package/prompts/tool-planning.md +3 -3
- package/src/cli.ts +190 -150
- package/src/imprint/agent.ts +47 -33
- package/src/imprint/api-research-agent.ts +933 -0
- package/src/imprint/audit.ts +49 -2
- package/src/imprint/auth-compile-agent.ts +125 -55
- package/src/imprint/auth-compile-tools.ts +20 -48
- package/src/imprint/auth-verifier.ts +8 -19
- package/src/imprint/backend-ladder.ts +499 -367
- package/src/imprint/body-structure.ts +656 -0
- package/src/imprint/build-plan.ts +33 -323
- package/src/imprint/cdp-browser-fetch.ts +734 -29
- package/src/imprint/cdp-jar-cache.ts +7 -12
- package/src/imprint/claude-cli-compile.ts +276 -320
- package/src/imprint/codex-cli-compile.ts +476 -350
- package/src/imprint/codex-sdk-turn.ts +102 -0
- package/src/imprint/compile-agent-types.ts +49 -10
- package/src/imprint/compile-agent.ts +189 -274
- package/src/imprint/compile-done-sentinel.ts +211 -0
- package/src/imprint/compile-provider-control.ts +401 -0
- package/src/imprint/compile-provider-recovery.ts +142 -0
- package/src/imprint/compile-strategy.ts +5 -0
- package/src/imprint/compile-tools.ts +1695 -3097
- package/src/imprint/compile-verification.ts +9 -1
- package/src/imprint/compile.ts +107 -29
- package/src/imprint/compiler-log.ts +12 -0
- package/src/imprint/compiler-process.ts +440 -0
- package/src/imprint/concurrency.ts +43 -58
- package/src/imprint/credential-extract.ts +1 -88
- package/src/imprint/emit.ts +18 -2
- package/src/imprint/evidence-inspection.ts +55 -0
- package/src/imprint/freeform-redact.ts +34 -234
- package/src/imprint/import-module-fresh.ts +30 -0
- package/src/imprint/live-finesse-runner.ts +299 -0
- package/src/imprint/live-verifier.ts +299 -358
- package/src/imprint/llm.ts +466 -422
- package/src/imprint/log.ts +1 -9
- package/src/imprint/master-teach-agent-contracts.ts +875 -0
- package/src/imprint/master-teach-agents.ts +2850 -0
- package/src/imprint/master-teach-checks.ts +341 -0
- package/src/imprint/master-teach-controller.ts +7159 -0
- package/src/imprint/master-teach-plan.ts +1410 -0
- package/src/imprint/master-teach-prompt-projections.ts +347 -0
- package/src/imprint/master-teach-store.ts +961 -0
- package/src/imprint/mcp-cdp-sessions.ts +60 -0
- package/src/imprint/mcp-compile-server.ts +519 -668
- package/src/imprint/mcp-live-verifier-server.ts +246 -190
- package/src/imprint/mcp-server.ts +46 -57
- package/src/imprint/native-agent-pass.ts +260 -0
- package/src/imprint/native-agent-usage.ts +141 -0
- package/src/imprint/native-teach-agents.ts +495 -0
- package/src/imprint/param-grounding.ts +488 -347
- package/src/imprint/playbook-runner.ts +254 -63
- package/src/imprint/prereq-builder.ts +55 -543
- package/src/imprint/private-file.ts +18 -0
- package/src/imprint/probe-backends.ts +129 -33
- package/src/imprint/provider-retry.ts +501 -0
- package/src/imprint/provider-terminal.ts +214 -0
- package/src/imprint/recording-request.ts +290 -1
- package/src/imprint/recording-verification.ts +444 -0
- package/src/imprint/redact.ts +33 -749
- package/src/imprint/refine-worker.ts +326 -0
- package/src/imprint/refine.ts +241 -0
- package/src/imprint/replay-capture.ts +41 -12
- package/src/imprint/replay-evidence.ts +1007 -0
- package/src/imprint/research-response-evidence.ts +45 -0
- package/src/imprint/runtime.ts +514 -106
- package/src/imprint/sensitive-keys.ts +0 -6
- package/src/imprint/session-merge.ts +103 -7
- package/src/imprint/stealth-fetch.ts +25 -8
- package/src/imprint/stealth-token-cache.ts +16 -16
- package/src/imprint/teach-plan.ts +0 -242
- package/src/imprint/teach-research-memory.ts +229 -0
- package/src/imprint/teach-state.ts +47 -625
- package/src/imprint/teach.ts +12 -3699
- package/src/imprint/tool-candidates.ts +58 -210
- package/src/imprint/tool-loader.ts +3 -0
- package/src/imprint/tool-plan.ts +1 -134
- package/src/imprint/tracing.ts +24 -7
- package/src/imprint/types.ts +68 -4
- 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
|
-
|
|
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
|
-
{
|
|
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
|
|
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:
|
|
157
|
-
timestamp:
|
|
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:
|
|
174
|
-
timestamp:
|
|
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 ||
|
|
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 =
|
|
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;
|