feat: LLM-powered trajectory compaction

[khaliqgant]

Replaces mechanical keyword-based compaction with intelligent LLM summarization.

New src/compact/ module

• provider.ts — OpenAI + Anthropic via raw fetch (no new deps), auto-detect from env
• serializer.ts — Trajectories → LLM-readable text with token budgeting
• prompts.ts — System + user prompts for compaction
• parser.ts — Parse LLM JSON with fallbacks (JSON → code blocks → regex)
• markdown.ts — Generate readable .md summaries
• config.ts — Env vars or .trajectories/config.json

CLI updates

• trail compact uses LLM by default (if API key present)
• --mechanical flag for old behavior
• --focus <areas> for targeted summaries
• --markdown flag for .md output alongside JSON
• --dry-run shows prompt + cost estimate

Output includes

• Narrative summary (what happened, how, why)
• Key decisions with reasoning and impact analysis
• Extracted conventions/patterns for future work
• Synthesized lessons from challenges
• Open questions / unresolved issues

Backwards compatible: falls back to mechanical compaction if no LLM provider configured.

No new npm dependencies.

---

[devin-ai-integration]

Devin Review found 2 potential issues.

View 5 additional findings in Devin Review.

[devin-ai-integration]

🔴 readNumber treats empty/whitespace-only env vars as 0 instead of unset

readNumber("") returns 0 because Number("") === 0 and Number.isFinite(0) === true. This is inconsistent with the sibling readString function at src/compact/config.ts:96-103 which correctly returns undefined for empty strings. When a user clears an env var (e.g., export TRAJECTORIES_LLM_MAX_INPUT_TOKENS=), readNumberEnv returns 0 instead of undefined. Because 0 ?? DEFAULT evaluates to 0 (nullish coalescing does not trigger for 0), this silently overrides the default. The most severe downstream effect: maxInputTokens = 0 causes serializeForLLM to produce an empty string (truncateText(document, 0) returns "" at src/compact/serializer.ts:61), so the LLM receives no trajectory data and generates a useless compaction. Similarly, maxOutputTokens = 0 would be sent as max_tokens: 0 to the LLM API, likely causing an API error.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[khaliqgant]

sdk-autocompact-option — validated end-to-end

BEFORE/AFTER gate PASSED. The feature is a genuine behavior change, not a no-op:

• BEFORE: new TrajectoryClient() + session.done() produces NO compacted file (baseline locked).
• AFTER: new TrajectoryClient({ autoCompact: { mechanical: true } }) + session.done() with TRAJECTORIES_WORKFLOW_ID set automatically produces .trajectories/compacted/workflow-<id>.{json,md}.

Ran via agent-relay run workflows/sdk-autocompact-option.ts with codex impl + claude tests + claude peer review + codex self-review.

[devin-ai-integration]

Devin Review found 1 potential issue.

View 7 additional findings in Devin Review.

[devin-ai-integration]

🔴 Missing error handler on child.stdin in spawnWithStdin causes unhandled EPIPE crash

In spawnWithStdin (src/compact/provider.ts:313-346), stdin data is written to the child process at lines 343-344 but there is no error handler on child.stdin. If the spawned CLI process exits before consuming all stdin data (e.g., immediately fails due to misconfigured args, missing auth, or a crash during startup), Node.js emits an EPIPE error on the stdin writable stream. Without a child.stdin.on('error', ...) handler, this becomes an unhandled error event that crashes the Node.js process with ERR_UNHANDLED_ERROR: Unhandled error. (Error: write EPIPE). The child.on('error', reject) handler at line 332 only catches spawn-level errors (e.g., ENOENT), not errors on individual stdio streams. The child.on('close') handler would correctly reject the promise for the non-zero exit code, but the unhandled stdin error event fires independently and crashes the process before the promise rejection can propagate.

Suggested change

	child.stdin.write(input);
	child.stdin.end();
	child.stdin.on("error", () => {}); // Swallow EPIPE — the close handler covers non-zero exits
	child.stdin.write(input);
	child.stdin.end();

---

Was this helpful? React with 👍 or 👎 to provide feedback.