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.
@@ -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
- const mcpToolTimeoutSec = resolveMcpToolTimeoutSec(opts.deadlineMs);
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 result = await driveJsonl(child, opts, traceSpan);
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
- const deadlineTimer = setTimeout(
434
- () => {
435
- log('wall-clock deadline exceeded, terminating codex');
436
- terminateChild(5000);
437
- },
438
- Math.max(0, opts.deadlineMs - Date.now()),
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 verification cycle. Cycle 1 is the initial agent run. Subsequent cycles
51
- * happen when the agent claims done() but external verification fails. */
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;