imprint-mcp 0.6.1 → 0.6.3
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/README.md +2 -0
- package/package.json +3 -2
- package/prompts/audit-agent.md +10 -7
- package/prompts/build-planning.md +2 -2
- package/prompts/compile-agent.md +49 -24
- package/prompts/live-verifier-agent.md +114 -0
- package/prompts/playbook-compilation.md +8 -1
- package/src/cli.ts +121 -4
- package/src/imprint/agent.ts +7 -2
- package/src/imprint/audit.ts +430 -39
- package/src/imprint/auth-compile-tools.ts +64 -13
- package/src/imprint/backend-cache.ts +18 -11
- package/src/imprint/backend-ladder.ts +48 -34
- package/src/imprint/cdp-browser-fetch.ts +135 -42
- package/src/imprint/claude-cli-compile.ts +38 -16
- package/src/imprint/codex-cli-compile.ts +120 -21
- package/src/imprint/compile-agent-types.ts +25 -2
- package/src/imprint/compile-agent.ts +238 -36
- package/src/imprint/compile-tools.ts +331 -58
- package/src/imprint/compile-verification.ts +187 -0
- package/src/imprint/compile.ts +71 -2
- package/src/imprint/freeform-redact.ts +27 -6
- package/src/imprint/live-verifier.ts +1826 -0
- package/src/imprint/llm.ts +20 -0
- package/src/imprint/mcp-compile-server.ts +488 -84
- package/src/imprint/mcp-live-verifier-server.ts +359 -0
- package/src/imprint/mcp-server.ts +28 -3
- package/src/imprint/probe-backends.ts +147 -31
- package/src/imprint/runtime.ts +61 -11
- package/src/imprint/teach-state.ts +70 -3
- package/src/imprint/teach.ts +171 -88
- package/src/imprint/types.ts +39 -2
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
* success only after the MCP done() tool writes the verified sentinel.
|
|
8
8
|
*/
|
|
9
9
|
|
|
10
|
-
import { type ChildProcess, spawn } from 'node:child_process';
|
|
10
|
+
import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
|
|
11
11
|
import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
12
12
|
import { isAbsolute as pathIsAbsolute, join as pathJoin } from 'node:path';
|
|
13
13
|
import type { Span } from '@opentelemetry/api';
|
|
@@ -21,7 +21,7 @@ import type {
|
|
|
21
21
|
import { formatCandidateContext, formatToolPlan } from './compile-agent-types.ts';
|
|
22
22
|
import { preferredAgentModel } from './llm.ts';
|
|
23
23
|
import { createLog } from './log.ts';
|
|
24
|
-
import { COMPILE_SENTINELS } from './mcp-compile-server.ts';
|
|
24
|
+
import { COMPILE_SENTINELS, compileDeadlineAfterVerification } from './mcp-compile-server.ts';
|
|
25
25
|
import type { SharedCompileContext, ToolCandidate } from './tool-candidates.ts';
|
|
26
26
|
import {
|
|
27
27
|
endTraceSpan,
|
|
@@ -43,9 +43,14 @@ const REPO_ROOT = pathJoin(import.meta.dir, '..', '..');
|
|
|
43
43
|
const CLI_PATH = pathJoin(REPO_ROOT, 'src', 'cli.ts');
|
|
44
44
|
const MCP_SERVER_NAME = 'imprint-compile';
|
|
45
45
|
const MAX_VERIFICATION_CYCLES = 5;
|
|
46
|
-
const MIN_MCP_TOOL_TIMEOUT_SEC = 300;
|
|
47
46
|
const MAX_MCP_TOOL_TIMEOUT_SEC = 1800;
|
|
48
47
|
|
|
48
|
+
function formatRevisionMode(enabled: boolean | undefined): string {
|
|
49
|
+
return enabled
|
|
50
|
+
? 'REVISION MODE: inspect read_session_summary.revisionContext and the listed existing artifacts/diagnostics first. Preserve proven behavior; repair or honestly narrow only what evidence contradicts.'
|
|
51
|
+
: '';
|
|
52
|
+
}
|
|
53
|
+
|
|
49
54
|
interface CompileViaCodexCliOptions {
|
|
50
55
|
session: Session;
|
|
51
56
|
absoluteToolDir: string;
|
|
@@ -63,6 +68,8 @@ interface CompileViaCodexCliOptions {
|
|
|
63
68
|
sharedModules?: SharedModuleManifestEntry[];
|
|
64
69
|
/** Per-tool implementation plan injected into the agent's initial message. */
|
|
65
70
|
toolPlan?: string;
|
|
71
|
+
/** Revise existing generated artifacts from durable verification feedback. */
|
|
72
|
+
revisionMode?: boolean;
|
|
66
73
|
/** Present → drive an auth compile rather than a data compile. */
|
|
67
74
|
authMode?: AuthCliCompileMode;
|
|
68
75
|
/** Auth segments only: resume the same non-interactive Codex session. */
|
|
@@ -143,6 +150,7 @@ async function compileViaCodexCliImpl(
|
|
|
143
150
|
COMPILE_SENTINELS.done,
|
|
144
151
|
COMPILE_SENTINELS.giveUp,
|
|
145
152
|
COMPILE_SENTINELS.checkpoint,
|
|
153
|
+
COMPILE_SENTINELS.verificationState,
|
|
146
154
|
]) {
|
|
147
155
|
const p = pathJoin(opts.absoluteToolDir, name);
|
|
148
156
|
if (existsSync(p)) {
|
|
@@ -199,10 +207,13 @@ async function compileViaCodexCliImpl(
|
|
|
199
207
|
sessionPathAbs,
|
|
200
208
|
'--tool-dir',
|
|
201
209
|
opts.absoluteToolDir,
|
|
210
|
+
'--provider',
|
|
211
|
+
'codex-cli',
|
|
202
212
|
...(opts.candidate ? ['--candidate-json', JSON.stringify(opts.candidate)] : []),
|
|
203
213
|
...(opts.sharedContext ? ['--shared-context-json', JSON.stringify(opts.sharedContext)] : []),
|
|
204
214
|
...(opts.buildPlanPath ? ['--build-plan-path', opts.buildPlanPath] : []),
|
|
205
215
|
...(opts.sharedModules ? ['--shared-modules-json', JSON.stringify(opts.sharedModules)] : []),
|
|
216
|
+
...(opts.revisionMode ? ['--revision-mode'] : []),
|
|
206
217
|
];
|
|
207
218
|
const { assignedSharedModules } = resolvePlanSliceFromFile(
|
|
208
219
|
opts.buildPlanPath,
|
|
@@ -220,6 +231,7 @@ Tool directory: ${opts.absoluteToolDir}
|
|
|
220
231
|
You will write artifacts into the tool directory.
|
|
221
232
|
${formatCandidateContext(opts.candidate, opts.sharedContext, assignedSharedModules)}
|
|
222
233
|
${formatToolPlan(opts.toolPlan)}
|
|
234
|
+
${formatRevisionMode(opts.revisionMode)}
|
|
223
235
|
|
|
224
236
|
Use the imprint-compile MCP tools to inspect the session, write artifacts, run tests, and call done(). Begin by calling read_session_summary, then proceed per the system instructions.`;
|
|
225
237
|
}
|
|
@@ -227,7 +239,9 @@ Use the imprint-compile MCP tools to inspect the session, write artifacts, run t
|
|
|
227
239
|
const model = opts.model ?? preferredAgentModel('codex-cli');
|
|
228
240
|
const initialTokenCount = resolveTraceTokenCount(null, initialPrompt);
|
|
229
241
|
const captureLlmIo = traceLlmIoEnabled();
|
|
230
|
-
|
|
242
|
+
// done() owns a separately bounded live-verification phase, so its transport
|
|
243
|
+
// timeout cannot be derived from the compiler's remaining reasoning budget.
|
|
244
|
+
const mcpToolTimeoutSec = MAX_MCP_TOOL_TIMEOUT_SEC;
|
|
231
245
|
setSpanAttributes(traceSpan, {
|
|
232
246
|
...llmSpanAttributes({
|
|
233
247
|
provider: 'codex-cli',
|
|
@@ -324,7 +338,20 @@ Use the imprint-compile MCP tools to inspect the session, write artifacts, run t
|
|
|
324
338
|
return finalErrorResult(opts, `failed to send prompt to codex-cli: ${errMsg(err)}`);
|
|
325
339
|
}
|
|
326
340
|
|
|
327
|
-
const
|
|
341
|
+
const terminateOnParentExit = (): void => {
|
|
342
|
+
try {
|
|
343
|
+
signalCodexProcessTree(child, 'SIGTERM');
|
|
344
|
+
} catch {
|
|
345
|
+
// Parent shutdown is best-effort; the OS may already have reaped the child.
|
|
346
|
+
}
|
|
347
|
+
};
|
|
348
|
+
process.once('exit', terminateOnParentExit);
|
|
349
|
+
let result: CompileAgentResult;
|
|
350
|
+
try {
|
|
351
|
+
result = await driveJsonl(child, opts, traceSpan);
|
|
352
|
+
} finally {
|
|
353
|
+
process.removeListener('exit', terminateOnParentExit);
|
|
354
|
+
}
|
|
328
355
|
const hasActualUsage = result.inputTokens > 0 || result.outputTokens > 0;
|
|
329
356
|
const inputTokenCount = resolveTraceTokenCount(
|
|
330
357
|
hasActualUsage ? result.inputTokens : null,
|
|
@@ -350,14 +377,6 @@ Use the imprint-compile MCP tools to inspect the session, write artifacts, run t
|
|
|
350
377
|
return result;
|
|
351
378
|
}
|
|
352
379
|
|
|
353
|
-
function resolveMcpToolTimeoutSec(deadlineMs: number, now = Date.now()): number {
|
|
354
|
-
const remainingSec = Math.ceil(Math.max(0, deadlineMs - now) / 1000);
|
|
355
|
-
return Math.max(
|
|
356
|
-
MIN_MCP_TOOL_TIMEOUT_SEC,
|
|
357
|
-
Math.min(MAX_MCP_TOOL_TIMEOUT_SEC, remainingSec || MIN_MCP_TOOL_TIMEOUT_SEC),
|
|
358
|
-
);
|
|
359
|
-
}
|
|
360
|
-
|
|
361
380
|
function buildAuthCodexInitialPrompt(systemPrompt: string, initialPrompt: string): string {
|
|
362
381
|
return `<system_instructions>
|
|
363
382
|
${systemPrompt}
|
|
@@ -382,6 +401,15 @@ async function driveJsonl(
|
|
|
382
401
|
writeFileSync(conversationLogPath, JSON.stringify(conversationLog, null, 2), 'utf8');
|
|
383
402
|
} catch {}
|
|
384
403
|
};
|
|
404
|
+
let flushLogTimer: ReturnType<typeof setTimeout> | undefined;
|
|
405
|
+
const scheduleLogFlush = (): void => {
|
|
406
|
+
if (flushLogTimer) return;
|
|
407
|
+
flushLogTimer = setTimeout(() => {
|
|
408
|
+
flushLogTimer = undefined;
|
|
409
|
+
flushLog();
|
|
410
|
+
}, 50);
|
|
411
|
+
flushLogTimer.unref?.();
|
|
412
|
+
};
|
|
385
413
|
const rawStdoutChunks: string[] = [];
|
|
386
414
|
const rawStderrChunks: string[] = [];
|
|
387
415
|
let inputTokens = 0;
|
|
@@ -430,13 +458,26 @@ async function driveJsonl(
|
|
|
430
458
|
}, graceMs);
|
|
431
459
|
forceTimer.unref?.();
|
|
432
460
|
};
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
461
|
+
let childExited = false;
|
|
462
|
+
const scheduleDeadlineCheck = (): ReturnType<typeof setTimeout> => {
|
|
463
|
+
const effectiveDeadlineMs = compileDeadlineAfterVerification(
|
|
464
|
+
opts.absoluteToolDir,
|
|
465
|
+
opts.deadlineMs,
|
|
466
|
+
);
|
|
467
|
+
return setTimeout(
|
|
468
|
+
() => {
|
|
469
|
+
if (childExited) return;
|
|
470
|
+
if (Date.now() < compileDeadlineAfterVerification(opts.absoluteToolDir, opts.deadlineMs)) {
|
|
471
|
+
deadlineTimer = scheduleDeadlineCheck();
|
|
472
|
+
return;
|
|
473
|
+
}
|
|
474
|
+
log('wall-clock deadline exceeded, terminating codex');
|
|
475
|
+
terminateChild(5000);
|
|
476
|
+
},
|
|
477
|
+
Math.max(0, effectiveDeadlineMs - Date.now()),
|
|
478
|
+
);
|
|
479
|
+
};
|
|
480
|
+
let deadlineTimer = scheduleDeadlineCheck();
|
|
440
481
|
|
|
441
482
|
let stdoutBuf = '';
|
|
442
483
|
child.stdout?.on('data', (chunk: Buffer) => {
|
|
@@ -459,6 +500,11 @@ async function driveJsonl(
|
|
|
459
500
|
}
|
|
460
501
|
|
|
461
502
|
conversationLog.push(evt);
|
|
503
|
+
// Keep the human-readable compile log current during a long agent turn.
|
|
504
|
+
// Rewriting is throttled so streamed bursts do not cause one full-file
|
|
505
|
+
// write per JSONL event, while a stalled/crashed turn still leaves the
|
|
506
|
+
// latest tool activity visible on disk.
|
|
507
|
+
scheduleLogFlush();
|
|
462
508
|
|
|
463
509
|
if (evt.type === 'thread.started') {
|
|
464
510
|
log(`thread_id=${evt.thread_id ?? '(none)'}`);
|
|
@@ -582,6 +628,7 @@ async function driveJsonl(
|
|
|
582
628
|
finish(-1);
|
|
583
629
|
});
|
|
584
630
|
});
|
|
631
|
+
childExited = true;
|
|
585
632
|
clearTimeout(deadlineTimer);
|
|
586
633
|
if (currentTurnSpan) endTraceSpan(currentTurnSpan);
|
|
587
634
|
for (const span of toolSpans.values()) endTraceSpan(span);
|
|
@@ -597,6 +644,7 @@ async function driveJsonl(
|
|
|
597
644
|
} catch {
|
|
598
645
|
// best effort diagnostics
|
|
599
646
|
}
|
|
647
|
+
if (flushLogTimer) clearTimeout(flushLogTimer);
|
|
600
648
|
flushLog();
|
|
601
649
|
|
|
602
650
|
const verifiedOk =
|
|
@@ -712,7 +760,7 @@ async function driveJsonl(
|
|
|
712
760
|
};
|
|
713
761
|
}
|
|
714
762
|
|
|
715
|
-
if (Date.now() > opts.deadlineMs) {
|
|
763
|
+
if (Date.now() > compileDeadlineAfterVerification(opts.absoluteToolDir, opts.deadlineMs)) {
|
|
716
764
|
return {
|
|
717
765
|
success: false,
|
|
718
766
|
outcome: 'timeout',
|
|
@@ -739,8 +787,59 @@ async function driveJsonl(
|
|
|
739
787
|
};
|
|
740
788
|
}
|
|
741
789
|
|
|
790
|
+
export function collectDescendantPids(
|
|
791
|
+
rows: Array<{ pid: number; ppid: number }>,
|
|
792
|
+
rootPid: number,
|
|
793
|
+
): number[] {
|
|
794
|
+
const childrenByParent = new Map<number, number[]>();
|
|
795
|
+
for (const row of rows) {
|
|
796
|
+
const children = childrenByParent.get(row.ppid) ?? [];
|
|
797
|
+
children.push(row.pid);
|
|
798
|
+
childrenByParent.set(row.ppid, children);
|
|
799
|
+
}
|
|
800
|
+
const descendants: number[] = [];
|
|
801
|
+
const visit = (pid: number): void => {
|
|
802
|
+
for (const childPid of childrenByParent.get(pid) ?? []) {
|
|
803
|
+
visit(childPid);
|
|
804
|
+
descendants.push(childPid);
|
|
805
|
+
}
|
|
806
|
+
};
|
|
807
|
+
visit(rootPid);
|
|
808
|
+
return descendants;
|
|
809
|
+
}
|
|
810
|
+
|
|
811
|
+
function liveDescendantPids(rootPid: number): number[] {
|
|
812
|
+
const ps = spawnSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8' });
|
|
813
|
+
if (ps.status !== 0 || typeof ps.stdout !== 'string') return [];
|
|
814
|
+
const rows = ps.stdout
|
|
815
|
+
.split('\n')
|
|
816
|
+
.map((line) => line.trim().split(/\s+/).map(Number))
|
|
817
|
+
.filter((pair): pair is [number, number] => pair.length === 2 && pair.every(Number.isFinite))
|
|
818
|
+
.map(([pid, ppid]) => ({ pid, ppid }));
|
|
819
|
+
return collectDescendantPids(rows, rootPid);
|
|
820
|
+
}
|
|
821
|
+
|
|
822
|
+
function signalPidOrGroup(pid: number, signal: NodeJS.Signals): void {
|
|
823
|
+
try {
|
|
824
|
+
process.kill(-pid, signal);
|
|
825
|
+
return;
|
|
826
|
+
} catch {
|
|
827
|
+
// The descendant may not lead its own group. Fall back to the process itself.
|
|
828
|
+
}
|
|
829
|
+
try {
|
|
830
|
+
process.kill(pid, signal);
|
|
831
|
+
} catch {
|
|
832
|
+
// already gone
|
|
833
|
+
}
|
|
834
|
+
}
|
|
835
|
+
|
|
742
836
|
function signalCodexProcessTree(child: ChildProcess, signal: NodeJS.Signals): void {
|
|
743
837
|
if (child.pid !== undefined) {
|
|
838
|
+
// Codex-launched MCP servers may create their own process groups. Killing only
|
|
839
|
+
// the detached Codex group leaves those grandchildren running after Ctrl-C,
|
|
840
|
+
// where they can keep compiling and issuing live calls. Snapshot and terminate
|
|
841
|
+
// descendants deepest-first while the parent relationship still exists.
|
|
842
|
+
for (const pid of liveDescendantPids(child.pid)) signalPidOrGroup(pid, signal);
|
|
744
843
|
try {
|
|
745
844
|
process.kill(-child.pid, signal);
|
|
746
845
|
return;
|
|
@@ -10,6 +10,29 @@ import type { AgentProgress } from './agent.ts';
|
|
|
10
10
|
import { type AssignedSharedModule, describeAssignedModules } from './build-plan.ts';
|
|
11
11
|
import type { SharedCompileContext, ToolCandidate } from './tool-candidates.ts';
|
|
12
12
|
|
|
13
|
+
/** Only an independent semantic-verifier result consumes the bounded review
|
|
14
|
+
* budget. Deterministic preflight failures remain deadline-bounded but do not
|
|
15
|
+
* spend a compiler↔reviewer iteration. */
|
|
16
|
+
export function advanceSemanticVerificationCycle(
|
|
17
|
+
current: number,
|
|
18
|
+
semanticReviewCompleted: boolean,
|
|
19
|
+
): number {
|
|
20
|
+
return semanticReviewCompleted ? current + 1 : current;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Bound verifier infrastructure failures separately from semantic review
|
|
24
|
+
* cycles. One verifier invocation already includes its own provider retry; a
|
|
25
|
+
* second failed invocation gives the compiler one chance to react without
|
|
26
|
+
* allowing a missing provider to extend the compile deadline forever. */
|
|
27
|
+
export function advanceIncompleteSemanticVerificationRuns(
|
|
28
|
+
current: number,
|
|
29
|
+
semanticReviewAttempted: boolean,
|
|
30
|
+
semanticReviewCompleted: boolean,
|
|
31
|
+
): number {
|
|
32
|
+
if (semanticReviewCompleted) return 0;
|
|
33
|
+
return semanticReviewAttempted ? current + 1 : current;
|
|
34
|
+
}
|
|
35
|
+
|
|
13
36
|
/** Render a per-tool implementation plan (param→field mapping, request
|
|
14
37
|
* construction, response parsing, shared-module imports, edge cases) into an
|
|
15
38
|
* initial-message section the compile agent must follow. Shared verbatim by the
|
|
@@ -47,8 +70,8 @@ Compile only the selected candidate. Do not create tools for other actions in th
|
|
|
47
70
|
}
|
|
48
71
|
|
|
49
72
|
export interface CompileAgentProgress extends AgentProgress {
|
|
50
|
-
/** 1-based
|
|
51
|
-
*
|
|
73
|
+
/** 1-based semantic-review cycle. Deterministic preflight retries leave this
|
|
74
|
+
* value unchanged. */
|
|
52
75
|
verificationCycle: number;
|
|
53
76
|
/** Verification cap for bounded data-tool compiles; auth is deadline-bounded. */
|
|
54
77
|
maxVerificationCycles?: number;
|