@mycompbox/compbox-cli 1.21.12 → 1.21.15

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.
@@ -20,9 +20,10 @@ import Anthropic from "@anthropic-ai/sdk";
20
20
  import { execFile, spawn, spawnSync } from "node:child_process";
21
21
  import { randomUUID } from "node:crypto";
22
22
  import { mkdirSync } from "node:fs";
23
- import { homedir } from "node:os";
23
+ import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
24
+ import { homedir, tmpdir } from "node:os";
24
25
  import { join } from "node:path";
25
- import { resolveRouting, extractCompletionJson, looksLikeCompletionAttempt, meetsComplianceTarget, buildAuditFeedback, COMPLETION_REPAIR_INSTRUCTION, renderConversationPrompt, runConversationStep, savedContextFromRecord, formatNeedsInputText, parseNeedsInputMarker, stripRunnerOnlyFields, } from "@mycompbox/shared";
26
+ import { resolveRouting, extractCompletionJson, looksLikeCompletionAttempt, meetsComplianceTarget, buildAuditFeedback, COMPLETION_REPAIR_INSTRUCTION, renderConversationPrompt, contentText, runConversationStep, savedContextFromRecord, isConversationChatModel, formatNeedsInputText, parseNeedsInputMarker, stripRunnerOnlyFields, } from "@mycompbox/shared";
26
27
  // Completion parsing lives in @mycompbox/shared so CompBox's server-side
27
28
  // (API-key) interview finishes the same way; re-exported for existing callers.
28
29
  export { extractCompletionJson, looksLikeCompletionAttempt, meetsComplianceTarget, buildAuditFeedback, COMPLETION_REPAIR_INSTRUCTION, };
@@ -34,6 +35,7 @@ import { mergeGuardArgs, withMergeGuardPath } from "./merge-guard.js";
34
35
  import { keyRunArgs, keyRunEnv, parseClaudeJsonResult } from "./key-run.js";
35
36
  import { CANCEL_GRACE_MS, cancelledRunResult, groupSpawnOptions, killGroupOnAbort, killProcessGroupNow, terminateProcessGroup, } from "./process-group.js";
36
37
  import { startProgressWatcher } from "./progress-watcher.js";
38
+ import { parseClaudeStream } from "./claude-stream.js";
37
39
  import { classifyUsageLimit } from "./usage-limit.js";
38
40
  import { defaultCommandRunner, } from "./run-workspace.js";
39
41
  import { createWrapUp } from "./wrap-up.js";
@@ -42,6 +44,44 @@ import { createWrapUp } from "./wrap-up.js";
42
44
  // quality loss. Opus/Sonnet are deliberately NOT used here — pxpipe passes
43
45
  // Opus through uncompressed, defeating the token savings.
44
46
  const ANTHROPIC_MODEL = "claude-fable-5";
47
+ /**
48
+ * Request-conversation models (ENG-390): plain chat turns use the fast model so
49
+ * replies feel instant; turns that write up or improve a saved request (the
50
+ * save/compliance pass and JSON repairs) keep the stronger model.
51
+ */
52
+ export const CHAT_MODEL = "claude-haiku-5-5";
53
+ export const SAVE_MODEL = ANTHROPIC_MODEL;
54
+ /**
55
+ * The model for one AI call in a request conversation step. `chosenChatModel`
56
+ * (the person's pick from the job payload, ENG-390-2) applies to chat turns
57
+ * only; save and repair turns always keep SAVE_MODEL.
58
+ */
59
+ export function modelForTurn(kind, chosenChatModel = null) {
60
+ if (kind !== "chat")
61
+ return SAVE_MODEL;
62
+ return chosenChatModel ?? CHAT_MODEL;
63
+ }
64
+ /**
65
+ * The chat model the person picked for this request conversation, read from
66
+ * the job payload (an object, or the JSON string it is stored as). Only ids in
67
+ * the shared allowlist count; anything else, or no model, returns null so the
68
+ * caller falls back to CHAT_MODEL.
69
+ */
70
+ export function chosenChatModelOf(payload) {
71
+ let p = payload;
72
+ if (typeof p === "string") {
73
+ try {
74
+ p = JSON.parse(p);
75
+ }
76
+ catch {
77
+ return null;
78
+ }
79
+ }
80
+ if (typeof p !== "object" || p === null)
81
+ return null;
82
+ const model = p.model;
83
+ return isConversationChatModel(model) ? model : null;
84
+ }
45
85
  /** Per-turn wall-clock budget for a single `claude -p` child process. */
46
86
  const CLAUDE_CLI_TURN_TIMEOUT_MS = 4 * 60 * 1_000; // 4 minutes: a full write-up can take a while
47
87
  /**
@@ -176,17 +216,197 @@ export function buildApiUserContent(text, imageBlocks) {
176
216
  return [...imageBlocks, { type: "text", text }];
177
217
  }
178
218
  /**
179
- * The `content` to push for a USER turn in API mode: fetches + attaches image
180
- * blocks when the turn has image attachments, otherwise returns the plain text
181
- * unchanged (no fetch, no warning — a turn with no attachments behaves exactly
182
- * as today). `fetchImpl` is injectable for tests.
219
+ * The `content` to push for a USER turn in API mode (ENG-374): images become
220
+ * image blocks, PDFs document blocks, and text documents marker-wrapped text
221
+ * blocks, all ahead of the person's text. A turn with no attachments returns
222
+ * its plain text unchanged (no fetch). An attachment that can't be loaded is
223
+ * skipped with a warning and a note in the text — never a failed turn.
224
+ * `fetchImpl` is injectable for tests.
183
225
  */
184
226
  export async function apiUserTurnContent(turn, warn = defaultWarn, fetchImpl = fetch) {
185
- const selected = selectImageAttachments(turn.attachments);
186
- if (selected.length === 0)
227
+ const all = turn.attachments ?? [];
228
+ if (all.length === 0)
187
229
  return turn.content;
188
- const blocks = await fetchImageBlocks(selected, warn, fetchImpl);
189
- return buildApiUserContent(turn.content, blocks);
230
+ const { fetched } = await fetchAttachments(selectAttachments(all, warn), warn, fetchImpl);
231
+ const text = appendMissingAttachmentNote(turn.content, all.length - fetched.length);
232
+ if (fetched.length === 0)
233
+ return text;
234
+ return [
235
+ ...fetched.map((f, i) => attachmentBlock(f, i + 1)),
236
+ { type: "text", text },
237
+ ];
238
+ }
239
+ // ---------------------------------------------------------------------
240
+ // ENG-374: documents (PDF + text) alongside images, for both runtimes.
241
+ // API mode sends them inline as content blocks; subscription mode writes them
242
+ // to a temp folder (materializeAttachments) and lets `claude -p` Read them.
243
+ // ---------------------------------------------------------------------
244
+ const PDF_MEDIA_TYPE = "application/pdf";
245
+ const TEXT_DOCUMENT_MEDIA_TYPES = [
246
+ "text/plain",
247
+ "text/csv",
248
+ "text/markdown",
249
+ "application/json",
250
+ ];
251
+ /** Max attachments (any kind) fed to the model per turn. */
252
+ const MAX_ATTACHMENTS_PER_TURN = 8;
253
+ /** Max cumulative attachment bytes per turn (declared and fetched). */
254
+ const MAX_ATTACHMENT_BYTES_PER_TURN = 32 * 1024 * 1024; // 32 MB
255
+ function baseMime(mime) {
256
+ return (mime.split(";")[0] ?? "").trim().toLowerCase();
257
+ }
258
+ /** What kind of attachment a MIME type is, or null when the model can't use it. Pure. */
259
+ export function attachmentKind(mime) {
260
+ if (isSupportedImageMediaType(mime))
261
+ return "image";
262
+ const base = baseMime(mime);
263
+ if (base === PDF_MEDIA_TYPE)
264
+ return "pdf";
265
+ if (TEXT_DOCUMENT_MEDIA_TYPES.includes(base))
266
+ return "text";
267
+ return null;
268
+ }
269
+ /**
270
+ * The attachments worth fetching for a turn: usable kinds only, capped by
271
+ * count and cumulative declared bytes. Anything dropped is warned about.
272
+ */
273
+ export function selectAttachments(attachments, warn = defaultWarn) {
274
+ if (!attachments || attachments.length === 0)
275
+ return [];
276
+ const selected = [];
277
+ let declaredBytes = 0;
278
+ for (const att of attachments) {
279
+ if (attachmentKind(att.mimeType) === null) {
280
+ warn(`Skipping attachment ${att.id}: unsupported type ${att.mimeType}.`);
281
+ continue;
282
+ }
283
+ if (selected.length >= MAX_ATTACHMENTS_PER_TURN) {
284
+ warn(`Skipping attachment ${att.id}: more than ${String(MAX_ATTACHMENTS_PER_TURN)} on one message.`);
285
+ continue;
286
+ }
287
+ const size = typeof att.sizeBytes === "number" && att.sizeBytes > 0 ? att.sizeBytes : 0;
288
+ if (declaredBytes + size > MAX_ATTACHMENT_BYTES_PER_TURN) {
289
+ warn(`Skipping attachment ${att.id}: exceeds the per-message size budget.`);
290
+ continue;
291
+ }
292
+ declaredBytes += size;
293
+ selected.push(att);
294
+ }
295
+ return selected;
296
+ }
297
+ /**
298
+ * Download already-selected attachments. A broken, unreachable, empty or
299
+ * over-budget one is skipped with a warning and reported in `failed` — never
300
+ * thrown.
301
+ */
302
+ export async function fetchAttachments(attachments, warn = defaultWarn, fetchImpl = fetch) {
303
+ const fetched = [];
304
+ const failed = [];
305
+ let totalBytes = 0;
306
+ for (const att of attachments) {
307
+ const kind = attachmentKind(att.mimeType);
308
+ if (!kind) {
309
+ failed.push(att);
310
+ continue;
311
+ }
312
+ try {
313
+ const res = await fetchImpl(att.signedUrl);
314
+ if (!res.ok)
315
+ throw new Error(`fetch failed (HTTP ${String(res.status)})`);
316
+ const bytes = Buffer.from(await res.arrayBuffer());
317
+ if (bytes.byteLength === 0)
318
+ throw new Error("empty response body");
319
+ if (totalBytes + bytes.byteLength > MAX_ATTACHMENT_BYTES_PER_TURN) {
320
+ throw new Error("exceeds the per-message size budget");
321
+ }
322
+ totalBytes += bytes.byteLength;
323
+ fetched.push({ attachment: att, kind, bytes });
324
+ }
325
+ catch (error) {
326
+ const message = error instanceof Error ? error.message : "unknown error";
327
+ warn(`Skipping attachment ${att.id}: ${message}.`);
328
+ failed.push(att);
329
+ }
330
+ }
331
+ return { fetched, failed };
332
+ }
333
+ /** The API content block for one fetched attachment (`n` numbers it for the text markers). Pure. */
334
+ export function attachmentBlock(f, n) {
335
+ if (f.kind === "image") {
336
+ const mediaType = normalizeImageMediaType(f.attachment.mimeType) ?? "image/png";
337
+ return {
338
+ type: "image",
339
+ source: { type: "base64", media_type: mediaType, data: f.bytes.toString("base64") },
340
+ };
341
+ }
342
+ if (f.kind === "pdf") {
343
+ return {
344
+ type: "document",
345
+ source: { type: "base64", media_type: PDF_MEDIA_TYPE, data: f.bytes.toString("base64") },
346
+ };
347
+ }
348
+ const label = `attachment ${String(n)} (${baseMime(f.attachment.mimeType)})`;
349
+ return {
350
+ type: "text",
351
+ text: `<<<BEGIN ${label}>>>\n${f.bytes.toString("utf8")}\n<<<END ${label}>>>`,
352
+ };
353
+ }
354
+ /** Adds a note that `count` attachments couldn't be loaded; unchanged when 0. Pure. */
355
+ export function appendMissingAttachmentNote(text, count) {
356
+ if (count <= 0)
357
+ return text;
358
+ const noun = count === 1 ? "attachment" : "attachments";
359
+ const note = `[${String(count)} ${noun} could not be loaded and ${count === 1 ? "is" : "are"} not shown]`;
360
+ return text.trim().length > 0 ? `${text}\n\n${note}` : note;
361
+ }
362
+ const EXTENSION_BY_MIME = {
363
+ "image/png": "png",
364
+ "image/jpeg": "jpg",
365
+ "image/gif": "gif",
366
+ "image/webp": "webp",
367
+ "application/pdf": "pdf",
368
+ "text/plain": "txt",
369
+ "text/csv": "csv",
370
+ "text/markdown": "md",
371
+ "application/json": "json",
372
+ };
373
+ /**
374
+ * Download a turn's attachments into `dir` (created if missing) under
375
+ * generated names (`attachment-1.png`, ...) — never the uploader's filename.
376
+ * Failures are warned about and counted in `failed`, never thrown. The caller
377
+ * owns `dir` and removes it.
378
+ */
379
+ export async function materializeAttachments(dir, attachments, fetchImpl = fetch, warn = defaultWarn) {
380
+ const all = attachments ?? [];
381
+ if (all.length === 0)
382
+ return { files: [], failed: 0 };
383
+ const { fetched } = await fetchAttachments(selectAttachments(all, warn), warn, fetchImpl);
384
+ const files = [];
385
+ if (fetched.length > 0)
386
+ await mkdir(dir, { recursive: true });
387
+ for (const f of fetched) {
388
+ const mimeType = baseMime(f.attachment.mimeType);
389
+ const path = join(dir, `attachment-${String(files.length + 1)}.${EXTENSION_BY_MIME[mimeType] ?? "bin"}`);
390
+ try {
391
+ await writeFile(path, f.bytes);
392
+ files.push({ path, mimeType });
393
+ }
394
+ catch (error) {
395
+ const message = error instanceof Error ? error.message : "unknown error";
396
+ warn(`Skipping attachment ${f.attachment.id}: could not save it (${message}).`);
397
+ }
398
+ }
399
+ return { files, failed: all.length - files.length };
400
+ }
401
+ /** Subscription-mode turn text: the person's text plus the attached files' paths. Pure. */
402
+ export function appendAttachmentPaths(text, files, failed) {
403
+ let out = text;
404
+ if (files.length > 0) {
405
+ const list = files.map((f) => `- ${f.path} (${f.mimeType})`).join("\n");
406
+ const note = `[Attached files — open them with the Read tool:\n${list}]`;
407
+ out = out.trim().length > 0 ? `${out}\n\n${note}` : note;
408
+ }
409
+ return appendMissingAttachmentNote(out, failed);
190
410
  }
191
411
  /**
192
412
  * Subscription-mode (A4) degradation: append an explicit `[N image(s)
@@ -319,26 +539,60 @@ function claudeCliSessionCwd() {
319
539
  * `--resume`, not by resending a transcript — cheaper and matches how a
320
540
  * human would use the CLI.
321
541
  */
322
- function runClaudeCliTurn(prompt, opts) {
542
+ /**
543
+ * ENG-374: the tool flags for an interview turn. No tools at all, unless an
544
+ * attachments folder is given — then only Read, pre-approved for that folder
545
+ * alone (`//` marks an absolute path in a permission rule). Pure.
546
+ */
547
+ export function claudeToolArgs(attachmentsDir) {
548
+ if (!attachmentsDir)
549
+ return ["--tools", ""];
550
+ return [
551
+ "--tools",
552
+ "Read",
553
+ "--add-dir",
554
+ attachmentsDir,
555
+ "--allowedTools",
556
+ `Read(/${attachmentsDir}/**)`,
557
+ ];
558
+ }
559
+ /**
560
+ * ENG-387: true when claude's stderr says it does not know
561
+ * `--include-partial-messages` (an older CLI), as opposed to any other failure.
562
+ */
563
+ function rejectsPartialMessagesFlag(stderr) {
564
+ return (stderr.includes("--include-partial-messages") &&
565
+ /unknown|unrecognized|invalid|unexpected|not supported/i.test(stderr));
566
+ }
567
+ export function runClaudeCliTurn(prompt, opts) {
323
568
  return new Promise((resolve, reject) => {
324
569
  const model = opts.model === undefined ? ANTHROPIC_MODEL : opts.model;
325
- const args = [
326
- "-p",
327
- prompt,
328
- ...(model ? ["--model", model] : []),
329
- "--output-format",
330
- "json",
331
- "--tools",
332
- "",
333
- "--permission-mode",
334
- "dontAsk",
335
- "--safe-mode",
336
- "--system-prompt",
337
- opts.systemPrompt,
338
- ];
339
- if (opts.resumeSessionId) {
340
- args.push("--resume", opts.resumeSessionId);
341
- }
570
+ const onText = opts.onText;
571
+ const streaming = typeof onText === "function";
572
+ // ENG-387: `withPartial` adds --include-partial-messages (token deltas).
573
+ // An older claude CLI that rejects the flag gets one retry without it
574
+ // (whole assistant messages still stream as deltas) — see the close handler.
575
+ const buildArgs = (withPartial) => {
576
+ const args = [
577
+ "-p",
578
+ prompt,
579
+ ...(model ? ["--model", model] : []),
580
+ "--output-format",
581
+ ...(streaming
582
+ ? ["stream-json", "--verbose", ...(withPartial ? ["--include-partial-messages"] : [])]
583
+ : ["json"]),
584
+ ...claudeToolArgs(opts.attachmentsDir),
585
+ "--permission-mode",
586
+ "dontAsk",
587
+ "--safe-mode",
588
+ "--system-prompt",
589
+ opts.systemPrompt,
590
+ ];
591
+ if (opts.resumeSessionId) {
592
+ args.push("--resume", opts.resumeSessionId);
593
+ }
594
+ return args;
595
+ };
342
596
  // ENG-135: resolve `claude` to an absolute path using the login-shell PATH
343
597
  // + well-known install dirs. A launchd/GUI-spawned daemon inherits a PATH
344
598
  // that often lacks ~/.local/bin, so a bare-name spawn fails "not found on
@@ -350,67 +604,118 @@ function runClaudeCliTurn(prompt, opts) {
350
604
  // otherwise. Layered on top (ENG-135): augment PATH with the login-shell +
351
605
  // well-known dirs so the child (and any helpers it spawns) can be located.
352
606
  const pxpipeEnv = claudeSpawnEnv(process.env, opts.routing);
353
- const child = spawn(command, args, {
354
- cwd: claudeCliSessionCwd(),
355
- stdio: ["ignore", "pipe", "pipe"],
356
- env: { ...pxpipeEnv, PATH: claudeChildEnvPath(pxpipeEnv.PATH) },
357
- });
358
- let stdout = "";
359
- let stderr = "";
360
- let settled = false;
361
- const timer = setTimeout(() => {
362
- if (settled)
363
- return;
364
- settled = true;
365
- child.kill("SIGKILL");
366
- reject(new Error(`claude CLI timed out after ${String(CLAUDE_CLI_TURN_TIMEOUT_MS / 1000)}s`));
367
- }, CLAUDE_CLI_TURN_TIMEOUT_MS);
368
- child.stdout.on("data", (chunk) => {
369
- stdout += chunk.toString("utf-8");
370
- });
371
- child.stderr.on("data", (chunk) => {
372
- stderr += chunk.toString("utf-8");
373
- });
374
- child.on("error", (error) => {
375
- if (settled)
376
- return;
377
- settled = true;
378
- clearTimeout(timer);
379
- if (error.code === "ENOENT") {
380
- // ENG-135: actionable message naming every location that was searched.
381
- reject(new Error(claudeNotFoundMessage()));
382
- return;
383
- }
384
- reject(error);
385
- });
386
- child.on("close", (code) => {
387
- if (settled)
388
- return;
389
- settled = true;
390
- clearTimeout(timer);
391
- if (code !== 0) {
392
- reject(new Error(stderr.trim() || `claude CLI exited with code ${String(code ?? "null")}`));
393
- return;
394
- }
395
- let parsed;
396
- try {
397
- parsed = JSON.parse(stdout);
398
- }
399
- catch {
400
- reject(new Error(`claude CLI returned non-JSON output: ${stdout.slice(0, 500)}`));
401
- return;
402
- }
403
- const shaped = parsed;
404
- if (shaped.is_error) {
405
- reject(new Error(shaped.result ?? "claude CLI reported an error"));
406
- return;
407
- }
408
- if (typeof shaped.result !== "string" || typeof shaped.session_id !== "string") {
409
- reject(new Error("claude CLI returned an unexpected JSON shape (missing result/session_id)."));
410
- return;
411
- }
412
- resolve({ text: shaped.result, sessionId: shaped.session_id });
413
- });
607
+ const attempt = (withPartial) => {
608
+ const child = spawn(command, buildArgs(withPartial), {
609
+ cwd: claudeCliSessionCwd(),
610
+ stdio: ["ignore", "pipe", "pipe"],
611
+ env: { ...pxpipeEnv, PATH: claudeChildEnvPath(pxpipeEnv.PATH) },
612
+ });
613
+ let stdout = "";
614
+ let stderr = "";
615
+ let settled = false;
616
+ let sawStdout = false;
617
+ const stream = streaming ? parseClaudeStream() : null;
618
+ const emit = (deltas) => {
619
+ if (!onText || settled)
620
+ return;
621
+ for (const delta of deltas) {
622
+ try {
623
+ onText(delta);
624
+ }
625
+ catch {
626
+ // A failing listener must not break the turn itself.
627
+ }
628
+ }
629
+ };
630
+ const timer = setTimeout(() => {
631
+ if (settled)
632
+ return;
633
+ settled = true;
634
+ child.kill("SIGKILL");
635
+ reject(new Error(`claude CLI timed out after ${String(CLAUDE_CLI_TURN_TIMEOUT_MS / 1000)}s`));
636
+ }, CLAUDE_CLI_TURN_TIMEOUT_MS);
637
+ child.stdout.on("data", (chunk) => {
638
+ if (chunk.length > 0)
639
+ sawStdout = true;
640
+ if (stream) {
641
+ emit(stream.push(chunk));
642
+ return;
643
+ }
644
+ stdout += chunk.toString("utf-8");
645
+ });
646
+ child.stderr.on("data", (chunk) => {
647
+ stderr += chunk.toString("utf-8");
648
+ });
649
+ child.on("error", (error) => {
650
+ if (settled)
651
+ return;
652
+ settled = true;
653
+ clearTimeout(timer);
654
+ if (error.code === "ENOENT") {
655
+ // ENG-135: actionable message naming every location that was searched.
656
+ reject(new Error(claudeNotFoundMessage()));
657
+ return;
658
+ }
659
+ reject(error);
660
+ });
661
+ child.on("close", (code) => {
662
+ if (settled)
663
+ return;
664
+ if (stream) {
665
+ // Flush the trailing line before settling so its deltas still reach onText.
666
+ const { deltas, result } = stream.finish();
667
+ emit(deltas);
668
+ settled = true;
669
+ clearTimeout(timer);
670
+ if (code !== 0) {
671
+ // ENG-387: the CLI rejected --include-partial-messages before
672
+ // producing any output → retry once without it. Nothing reached
673
+ // onText yet, so the retry cannot duplicate deltas.
674
+ if (withPartial && !sawStdout && rejectsPartialMessagesFlag(stderr)) {
675
+ attempt(false);
676
+ return;
677
+ }
678
+ reject(new Error(stderr.trim() || `claude CLI exited with code ${String(code ?? "null")}`));
679
+ return;
680
+ }
681
+ if (result.isError) {
682
+ reject(new Error(result.text || "claude CLI reported an error"));
683
+ return;
684
+ }
685
+ if (!result.done || result.sessionId === null) {
686
+ reject(new Error("claude CLI stream ended without a result event (missing result/session_id)."));
687
+ return;
688
+ }
689
+ resolve({ text: result.text, sessionId: result.sessionId });
690
+ return;
691
+ }
692
+ settled = true;
693
+ clearTimeout(timer);
694
+ if (code !== 0) {
695
+ reject(new Error(stderr.trim() || `claude CLI exited with code ${String(code ?? "null")}`));
696
+ return;
697
+ }
698
+ let parsed;
699
+ try {
700
+ parsed = JSON.parse(stdout);
701
+ }
702
+ catch {
703
+ reject(new Error(`claude CLI returned non-JSON output: ${stdout.slice(0, 500)}`));
704
+ return;
705
+ }
706
+ const shaped = parsed;
707
+ if (shaped.is_error) {
708
+ reject(new Error(shaped.result ?? "claude CLI reported an error"));
709
+ return;
710
+ }
711
+ if (typeof shaped.result !== "string" || typeof shaped.session_id !== "string") {
712
+ reject(new Error("claude CLI returned an unexpected JSON shape (missing result/session_id)."));
713
+ return;
714
+ }
715
+ resolve({ text: shaped.result, sessionId: shaped.session_id });
716
+ });
717
+ };
718
+ attempt(streaming);
414
719
  });
415
720
  }
416
721
  // ---------------------------------------------------------------------
@@ -444,6 +749,41 @@ export function needsDefaultModel(error) {
444
749
  const message = error instanceof Error ? error.message : String(error);
445
750
  return /requires usage credits|switch to another model|model.*not available|not have access to/i.test(message);
446
751
  }
752
+ const MAX_CONVERSATION_SESSIONS = 50;
753
+ const conversationSessions = new Map();
754
+ function rememberConversationSession(jobId, session) {
755
+ conversationSessions.delete(jobId);
756
+ conversationSessions.set(jobId, session);
757
+ while (conversationSessions.size > MAX_CONVERSATION_SESSIONS) {
758
+ const oldest = conversationSessions.keys().next().value;
759
+ if (oldest === undefined)
760
+ break;
761
+ conversationSessions.delete(oldest);
762
+ }
763
+ }
764
+ /** Test hook: forget every remembered conversation session. */
765
+ export function resetConversationSessions() {
766
+ conversationSessions.clear();
767
+ }
768
+ /** A comparable fingerprint of one message as the AI saw it. */
769
+ export function sessionMessageKey(m) {
770
+ return `${m.role}\u0000${contentText(m.content)}`;
771
+ }
772
+ /**
773
+ * True when `next` starts with everything the session already saw and adds at
774
+ * least one new message; anything else (an edited or shortened history) means
775
+ * the session no longer matches and the turn must run fresh.
776
+ */
777
+ export function extendsSession(seen, next) {
778
+ if (next.length <= seen.length)
779
+ return false;
780
+ return seen.every((key, i) => next[i] === key);
781
+ }
782
+ /** The prompt for a resumed turn: only the messages the session hasn't seen. */
783
+ export function renderResumePrompt(fresh) {
784
+ const lines = fresh.map((m) => `${m.role === "assistant" ? "You" : "Them"}: ${contentText(m.content)}`);
785
+ return `${lines.join("\n\n")}\n\nWrite your next reply to them.`;
786
+ }
447
787
  function savedRequestIdOf(job) {
448
788
  const result = job.result;
449
789
  if (typeof result?.epicRequestId === "string")
@@ -473,54 +813,157 @@ export async function invokeEpicRequestStep(job, ctx) {
473
813
  }
474
814
  }
475
815
  async function takeConversationStep(job, ctx) {
816
+ // ENG-392: the clock starts as soon as the daemon picks the step up.
817
+ const timer = startTurnTimer();
476
818
  const routing = await resolveRouting();
477
819
  const requestId = savedRequestIdOf(job);
478
820
  const discussed = requestId !== null && parseSeedPayload(job.payload)?.targetEpicRequestId === requestId;
479
821
  const saved = requestId
480
822
  ? await loadSavedRequest(ctx.apiBaseUrl, ctx.userApiToken, requestId, discussed)
481
823
  : null;
482
- const turns = job.turns.map((t) => ({
483
- role: t.role,
484
- content: t.role === "user"
485
- ? appendAttachmentNote(t.content, imageAttachmentCount(t.attachments))
486
- : t.content,
487
- }));
488
824
  const anthropic = ctx.anthropicApiKey
489
825
  ? new Anthropic(anthropicClientOptions(ctx.anthropicApiKey, routing))
490
826
  : null;
491
- let cliModel = ANTHROPIC_MODEL;
827
+ // ENG-374: subscription mode reads attachments from a temp folder that only
828
+ // lives for this step; it's created lazily and always removed below.
829
+ const hasAttachments = job.turns.some((t) => t.role === "user" && (t.attachments?.length ?? 0) > 0);
830
+ const attachmentsDir = !anthropic && hasAttachments
831
+ ? await realpath(await mkdtemp(join(tmpdir(), "compbox-attachments-")))
832
+ : undefined;
833
+ try {
834
+ return await converseWithAttachments(job, ctx, {
835
+ routing,
836
+ saved,
837
+ anthropic,
838
+ attachmentsDir,
839
+ timer,
840
+ });
841
+ }
842
+ finally {
843
+ if (attachmentsDir)
844
+ await rm(attachmentsDir, { recursive: true, force: true });
845
+ }
846
+ }
847
+ export function startTurnTimer(now = () => performance.now()) {
848
+ const startedAt = now();
849
+ let firstTextAt = null;
850
+ const elapsed = (at) => Math.max(0, Math.round(at - startedAt));
851
+ return {
852
+ markFirstText() {
853
+ firstTextAt ??= now();
854
+ },
855
+ finish(model) {
856
+ const metrics = {
857
+ firstTokenMs: firstTextAt === null ? null : elapsed(firstTextAt),
858
+ totalMs: elapsed(now()),
859
+ };
860
+ if (model)
861
+ metrics.model = model;
862
+ return metrics;
863
+ },
864
+ };
865
+ }
866
+ async function converseWithAttachments(job, ctx, step) {
867
+ const { routing, saved, anthropic, attachmentsDir } = step;
868
+ const timer = step.timer ?? startTurnTimer();
869
+ // ENG-392: the model that produced the last reply; null → the sign-in default.
870
+ let replyModel = null;
871
+ let usedFiles = false;
872
+ const turns = [];
873
+ for (const [index, t] of job.turns.entries()) {
874
+ if (t.role !== "user") {
875
+ turns.push({ role: t.role, content: t.content });
876
+ }
877
+ else if (anthropic) {
878
+ turns.push({ role: t.role, content: await apiUserTurnContent(t) });
879
+ }
880
+ else if (attachmentsDir && (t.attachments?.length ?? 0) > 0) {
881
+ const { files, failed } = await materializeAttachments(join(attachmentsDir, `turn-${String(index + 1)}`), t.attachments);
882
+ if (files.length > 0)
883
+ usedFiles = true;
884
+ turns.push({ role: t.role, content: appendAttachmentPaths(t.content, files, failed) });
885
+ }
886
+ else {
887
+ turns.push({ role: t.role, content: t.content });
888
+ }
889
+ }
890
+ const readDir = usedFiles ? attachmentsDir : undefined;
891
+ // Once the person's plan rejects a chosen model, use their default for the rest of the step.
892
+ let useDefaultModel = false;
893
+ const chosenChatModel = chosenChatModelOf(job.payload);
492
894
  const outcome = await runConversationStep({ turns, saved }, {
493
- reply: async (system, messages) => {
895
+ reply: async (system, messages, kind) => {
896
+ const model = modelForTurn(kind, chosenChatModel);
494
897
  if (anthropic) {
495
898
  const response = await anthropic.messages.create({
496
- model: ANTHROPIC_MODEL,
899
+ model,
497
900
  max_tokens: 4096,
498
901
  system,
499
902
  messages,
500
903
  });
501
904
  const text = response.content.find((b) => b.type === "text");
502
- return text?.type === "text" ? text.text : "";
905
+ const reply = text?.type === "text" ? text.text : "";
906
+ replyModel = response.model || model;
907
+ if (reply)
908
+ timer.markFirstText();
909
+ return reply;
503
910
  }
504
- const prompt = renderConversationPrompt(messages);
505
- try {
506
- return (await runClaudeCliTurn(prompt, {
507
- systemPrompt: system,
508
- resumeSessionId: undefined,
509
- routing,
510
- model: cliModel,
511
- })).text;
911
+ // ENG-391: a later turn resumes this job's claude session and sends
912
+ // only what's new; if that fails, forget the session and run once
913
+ // fresh with the whole transcript.
914
+ const sent = messages.map(sessionMessageKey);
915
+ const runFresh = async () => {
916
+ const prompt = renderConversationPrompt(messages);
917
+ try {
918
+ return await runClaudeCliTurn(prompt, {
919
+ systemPrompt: system,
920
+ resumeSessionId: undefined,
921
+ routing,
922
+ model: useDefaultModel ? null : model,
923
+ attachmentsDir: readDir,
924
+ });
925
+ }
926
+ catch (error) {
927
+ if (useDefaultModel || !needsDefaultModel(error))
928
+ throw error;
929
+ useDefaultModel = true;
930
+ return await runClaudeCliTurn(prompt, {
931
+ systemPrompt: system,
932
+ resumeSessionId: undefined,
933
+ routing,
934
+ model: null,
935
+ attachmentsDir: readDir,
936
+ });
937
+ }
938
+ };
939
+ const session = conversationSessions.get(job.id);
940
+ let turn = null;
941
+ if (session && extendsSession(session.sent, sent)) {
942
+ try {
943
+ turn = await runClaudeCliTurn(renderResumePrompt(messages.slice(session.sent.length)), {
944
+ systemPrompt: system,
945
+ resumeSessionId: session.sessionId,
946
+ routing,
947
+ model: useDefaultModel ? null : model,
948
+ attachmentsDir: readDir,
949
+ });
950
+ }
951
+ catch {
952
+ turn = null;
953
+ }
512
954
  }
513
- catch (error) {
514
- if (cliModel === null || !needsDefaultModel(error))
515
- throw error;
516
- cliModel = null;
517
- return (await runClaudeCliTurn(prompt, {
518
- systemPrompt: system,
519
- resumeSessionId: undefined,
520
- routing,
521
- model: null,
522
- })).text;
955
+ if (!turn) {
956
+ conversationSessions.delete(job.id);
957
+ turn = await runFresh();
523
958
  }
959
+ rememberConversationSession(job.id, {
960
+ sessionId: turn.sessionId,
961
+ sent: [...sent, sessionMessageKey({ role: "assistant", content: turn.text })],
962
+ });
963
+ replyModel = useDefaultModel ? null : model;
964
+ if (turn.text)
965
+ timer.markFirstText();
966
+ return turn.text;
524
967
  },
525
968
  save: async (existingId, draft) => {
526
969
  const submitted = await submitAndScore(ctx, existingId, draft);
@@ -530,7 +973,7 @@ async function takeConversationStep(job, ctx) {
530
973
  if (outcome.kind === "saved") {
531
974
  await ctx.mailboxClient.markRequestSaved(ctx.machineToken, job.id, outcome.saved.id);
532
975
  }
533
- await ctx.mailboxClient.postTurn(ctx.machineToken, job.id, outcome.text);
976
+ await ctx.mailboxClient.postTurn(ctx.machineToken, job.id, outcome.text, timer.finish(replyModel));
534
977
  return { status: "yield" };
535
978
  }
536
979
  // ---------------------------------------------------------------------
@@ -1483,9 +1926,14 @@ export function buildOrchestratorArgs(epicId, sessionId, ownerReply, baseBranch,
1483
1926
  return [
1484
1927
  "-p",
1485
1928
  `@orchestrator execute epic ${epicId} --non-interactive` +
1486
- (ownerReply ? `\n\n${freshRunReplyContext(ownerReply)}` : "") +
1929
+ (ownerReply || extra?.replyAttachmentsNote
1930
+ ? `\n\n${freshRunReplyContext(ownerReply ?? "", extra?.replyAttachmentsNote)}`
1931
+ : "") +
1932
+ (extra?.followUp ? `\n\n${followUpContext(extra.followUp)}` : "") +
1487
1933
  (extra?.ownerNote ? `\n\n${ownerNoteContext(extra.ownerNote)}` : "") +
1488
- (extra?.deferred && extra.deferred.length > 0 ? `\n\n${deferredFeaturesText(extra.deferred)}` : ""),
1934
+ (extra?.deferred && extra.deferred.length > 0
1935
+ ? `\n\n${deferredFeaturesText(extra.deferred)}`
1936
+ : ""),
1489
1937
  // A known session id lets the runner resume this same conversation when
1490
1938
  // the agent ends its turn early (see buildOrchestratorContinueArgs).
1491
1939
  ...(sessionId ? ["--session-id", sessionId] : []),
@@ -1535,6 +1983,19 @@ export function deferredFeaturesText(deferred) {
1535
1983
  export function ownerNoteContext(note) {
1536
1984
  return ["The owner restarted this build with this note:", quoteOwnerReply(note)].join("\n\n");
1537
1985
  }
1986
+ /**
1987
+ * ENG-366: the owner's follow-up to a finished build, appended after the
1988
+ * @orchestrator command. Quoted as owner text (a request, not instructions
1989
+ * that override the agent's rules).
1990
+ */
1991
+ export function followUpContext(message) {
1992
+ return [
1993
+ "This epic's build already finished. Its owner sent this follow-up:",
1994
+ quoteOwnerReply(message, "a follow-up to the finished build"),
1995
+ "Act on it against the epic's blueprint: change features, tasks or code as needed, and report what you changed. " +
1996
+ "If it is unclear, ask with a single COMPBOX_NEEDS_INPUT marker.",
1997
+ ].join("\n\n");
1998
+ }
1538
1999
  /** Claude CLI args that resume the orchestrator's session with {@link orchestratorContinuePrompt}. */
1539
2000
  export function buildOrchestratorContinueArgs(sessionId, prompt, baseBranch, fastMode) {
1540
2001
  return [
@@ -1552,6 +2013,30 @@ export function buildOrchestratorContinueArgs(sessionId, prompt, baseBranch, fas
1552
2013
  ...fastModeArgs(fastMode),
1553
2014
  ];
1554
2015
  }
2016
+ /** The well-formed entries of a claimed job's `resume.attachments` (ENG-375). Pure. */
2017
+ function parseReplyAttachments(raw) {
2018
+ if (!Array.isArray(raw))
2019
+ return [];
2020
+ const out = [];
2021
+ for (const item of raw) {
2022
+ if (typeof item !== "object" || item === null)
2023
+ continue;
2024
+ const a = item;
2025
+ if (typeof a.id !== "string" ||
2026
+ typeof a.mimeType !== "string" ||
2027
+ typeof a.signedUrl !== "string")
2028
+ continue;
2029
+ if (a.signedUrl.trim() === "")
2030
+ continue;
2031
+ out.push({
2032
+ id: a.id,
2033
+ mimeType: a.mimeType,
2034
+ sizeBytes: typeof a.sizeBytes === "number" && Number.isFinite(a.sizeBytes) ? a.sizeBytes : 0,
2035
+ signedUrl: a.signedUrl,
2036
+ });
2037
+ }
2038
+ return out;
2039
+ }
1555
2040
  /** Most of the owner's reply that is handed to the agent. */
1556
2041
  export const MAX_REPLY_CHARS = 8_000;
1557
2042
  const REPLY_OPEN = "<<<OWNER_REPLY";
@@ -1566,17 +2051,35 @@ export function parseReplyResume(job) {
1566
2051
  if (typeof raw !== "object" || raw === null)
1567
2052
  return null;
1568
2053
  const r = raw;
1569
- if (typeof r.reply !== "string" || r.reply.trim() === "")
2054
+ if (typeof r.reply !== "string")
2055
+ return null;
2056
+ const attachments = parseReplyAttachments(r.attachments);
2057
+ // A reply may be attachments only (ENG-375); with neither there's nothing to resume with.
2058
+ if (r.reply.trim() === "" && attachments.length === 0)
1570
2059
  return null;
1571
2060
  const str = (v) => (typeof v === "string" && v.trim() !== "" ? v : null);
1572
- const result = typeof job.result === "object" && job.result !== null ? job.result : {};
2061
+ const result = typeof job.result === "object" && job.result !== null
2062
+ ? job.result
2063
+ : {};
1573
2064
  return {
1574
2065
  sessionId: str(r.sessionId),
1575
2066
  runDir: str(r.runDir),
1576
2067
  reply: r.reply,
1577
2068
  branch: str(result.branch),
2069
+ attachments,
1578
2070
  };
1579
2071
  }
2072
+ /**
2073
+ * The runner's note listing the reply's attachments as saved files (ENG-375),
2074
+ * or "" when there are none. Kept OUTSIDE the quoted reply: the paths come
2075
+ * from the runner, not the owner. Pure.
2076
+ */
2077
+ export function replyAttachmentsNote(files, failed) {
2078
+ if (files.length === 0 && failed <= 0)
2079
+ return "";
2080
+ const head = "The owner attached files to the reply.";
2081
+ return appendAttachmentPaths(head, files, failed);
2082
+ }
1580
2083
  /** The reply as a clearly delimited, untrusted quote the agent can't mistake for instructions. */
1581
2084
  export function quoteOwnerReply(reply, kind = "an answer to your question") {
1582
2085
  // Strip the markers until none is left: one pass can re-form a marker
@@ -1614,10 +2117,11 @@ export function ownerNotePrompt(epicId, notes, deferred = []) {
1614
2117
  ].join("\n\n");
1615
2118
  }
1616
2119
  /** The prompt that resumes a paused orchestrator session with the owner's reply. */
1617
- export function replyResumePrompt(epicId, reply) {
2120
+ export function replyResumePrompt(epicId, reply, attachmentsNote = "") {
1618
2121
  return [
1619
2122
  `The owner answered your question:`,
1620
2123
  quoteOwnerReply(reply),
2124
+ ...(attachmentsNote ? [attachmentsNote] : []),
1621
2125
  `Continue executing epic ${epicId} in non-interactive mode from where you stopped.`,
1622
2126
  "If the answer is not enough, ask again with a single COMPBOX_NEEDS_INPUT marker.",
1623
2127
  ].join("\n\n");
@@ -1634,10 +2138,11 @@ export function buildReplyResumeArgs(sessionId, prompt, baseBranch, fastMode) {
1634
2138
  * orchestrator run gets the owner's reply. Appended after the @orchestrator
1635
2139
  * command so the agent routing (which keys on the prompt's start) still works.
1636
2140
  */
1637
- export function freshRunReplyContext(reply) {
2141
+ export function freshRunReplyContext(reply, attachmentsNote = "") {
1638
2142
  return [
1639
2143
  "This build stopped earlier to ask its owner a question. The owner answered:",
1640
2144
  quoteOwnerReply(reply),
2145
+ ...(attachmentsNote ? [attachmentsNote] : []),
1641
2146
  "Use the answer where the earlier run stopped. If it is not enough, ask again with a single COMPBOX_NEEDS_INPUT marker.",
1642
2147
  ].join("\n\n");
1643
2148
  }
@@ -1720,7 +2225,7 @@ export function mergePullRequestsRequest(prs) {
1720
2225
  question: `${count} your review and merge before the build can continue.`,
1721
2226
  why: "The rest of the build builds on this work, so continuing now would redo it or conflict with it.",
1722
2227
  steps: prs.map((pr, i) => `${String(i + 1)}. Merge #${String(pr.number)}${pr.title ? ` ${pr.title}` : ""}: ${pr.htmlUrl}`),
1723
- afterAnswer: "The build continues by itself once they're merged. You can also press \"All merged — continue\".",
2228
+ afterAnswer: 'The build continues by itself once they\'re merged. You can also press "All merged — continue".',
1724
2229
  kind: "merge_prs",
1725
2230
  prNumbers: prs.map((pr) => pr.number),
1726
2231
  };
@@ -1984,6 +2489,22 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
1984
2489
  const runDir = workspace?.dir ?? projectDir;
1985
2490
  if (workspace)
1986
2491
  deps.activeRunDirs?.add(workspace.dir);
2492
+ // ENG-375: the reply's attachments are saved to a temp folder outside the
2493
+ // run copy (so they're never committed) and listed in the prompt for the
2494
+ // agent to Read. Removed when the run ends.
2495
+ let replyAttachmentsDir;
2496
+ let attachmentsNote = "";
2497
+ const replyAttachments = resume?.attachments ?? [];
2498
+ if (replyAttachments.length > 0) {
2499
+ try {
2500
+ replyAttachmentsDir = await realpath(await mkdtemp(join(tmpdir(), "compbox-reply-attachments-")));
2501
+ const { files, failed } = await materializeAttachments(replyAttachmentsDir, replyAttachments, deps.fetchImpl ?? fetch);
2502
+ attachmentsNote = replyAttachmentsNote(files, failed);
2503
+ }
2504
+ catch {
2505
+ attachmentsNote = replyAttachmentsNote([], replyAttachments.length);
2506
+ }
2507
+ }
1987
2508
  const routing = await resolveRoutingImpl();
1988
2509
  const command = resolveClaudeBinary() ?? "claude";
1989
2510
  // A fix run is one focused change, so only a build gets a resumable session.
@@ -1992,10 +2513,12 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
1992
2513
  const runArgs = ctx.fix
1993
2514
  ? buildFixArgs(ctx.fix, workspace?.baseBranch, ctx.fastMode)
1994
2515
  : resumeSessionId && resume
1995
- ? buildReplyResumeArgs(resumeSessionId, replyResumePrompt(ctx.epicId, resume.reply), workspace?.baseBranch, ctx.fastMode)
2516
+ ? buildReplyResumeArgs(resumeSessionId, replyResumePrompt(ctx.epicId, resume.reply, attachmentsNote), workspace?.baseBranch, ctx.fastMode)
1996
2517
  : buildOrchestratorArgs(ctx.epicId, sessionId, resume?.reply, workspace?.baseBranch, ctx.fastMode, {
1997
2518
  ...(ctx.ownerNote && { ownerNote: ctx.ownerNote }),
1998
2519
  ...(ctx.deferredFeatures && { deferred: ctx.deferredFeatures }),
2520
+ ...(ctx.followUp && { followUp: ctx.followUp }),
2521
+ ...(attachmentsNote && { replyAttachmentsNote: attachmentsNote }),
1999
2522
  });
2000
2523
  const args = ctx.keyRun ? keyRunArgs(runArgs) : runArgs;
2001
2524
  // pxpipe (ENG-136): inject ANTHROPIC_BASE_URL when routed. COMPBOX_NONINTERACTIVE
@@ -2272,7 +2795,10 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
2272
2795
  /** One run, then a resume of the same session for each note the owner sent during it. */
2273
2796
  const runDeliveringNotes = async (runArgsNow, budgetMs) => {
2274
2797
  let result = await runOnce(runArgsNow, budgetMs);
2275
- while (sessionId && pendingNotes.length > 0 && !ctx.signal?.aborted && deadline - Date.now() > 60_000) {
2798
+ while (sessionId &&
2799
+ pendingNotes.length > 0 &&
2800
+ !ctx.signal?.aborted &&
2801
+ deadline - Date.now() > 60_000) {
2276
2802
  const notes = pendingNotes.splice(0);
2277
2803
  try {
2278
2804
  await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, `Got your note. Stopped the agent's current step and passed the note on; the build carries on from here.`);
@@ -2298,7 +2824,9 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
2298
2824
  (async () => {
2299
2825
  try {
2300
2826
  const job = await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, `The orchestrator finished. Checking epic ${ctx.epicId}'s progress in CompBox…`);
2301
- return job.progress ? { ...job.progress, waitingPullRequests: job.waitingPullRequests ?? [] } : null;
2827
+ return job.progress
2828
+ ? { ...job.progress, waitingPullRequests: job.waitingPullRequests ?? [] }
2829
+ : null;
2302
2830
  }
2303
2831
  catch {
2304
2832
  return null;
@@ -2370,7 +2898,9 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
2370
2898
  ...outcome.result,
2371
2899
  fastMode: { requested: true, used: fastModeUsed },
2372
2900
  ...(fastModeUsed === false
2373
- ? { fastModeNote: "Fast mode was requested but isn't available on this computer's Claude account, so the run used standard speed." }
2901
+ ? {
2902
+ fastModeNote: "Fast mode was requested but isn't available on this computer's Claude account, so the run used standard speed.",
2903
+ }
2374
2904
  : {}),
2375
2905
  };
2376
2906
  }
@@ -2476,6 +3006,8 @@ export async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
2476
3006
  }
2477
3007
  if (workspace)
2478
3008
  deps.activeRunDirs?.delete(workspace.dir);
3009
+ if (replyAttachmentsDir)
3010
+ await rm(replyAttachmentsDir, { recursive: true, force: true }).catch(() => undefined);
2479
3011
  // ENG-352: where the run's time went, for the run page's breakdown.
2480
3012
  const timings = buildJobTimings({
2481
3013
  install: workspace?.install,