feat: compaction-tool-session-summarization — semantic session summarization tool

[avoidwork]

Summary

Add a compaction tool that produces semantic summarization of conversation sessions, enabling sub-agents to receive curated context about prior work.

Why

When delegating to a sub-agent, the parent needs a clean summary of what was discussed — not a full session dump, not a mechanical token-budget reducer, but a semantic distillation of the conversation's key points. This tool provides that capability, enabling sub-agents to receive curated context about prior work.

What Changes

• Add a new compaction tool that produces semantic summarization of conversation sessions
• Tool spawns a node process to read session files and produce structured summaries
• Output uses # Compaction marker to separate thinking/reasoning from the final summary
• Tool integrates with existing tool registry in src/tools/index.js
• Add unit tests for parsing, spawning, and tool registration

Capabilities

New Capabilities

• compaction: Semantic session summarization tool that distills conversation history into core decisions, key design points, open questions, and next steps

Impact

• Affected code: src/tools/index.js (registration), new src/tools/compaction.js (implementation)
• Dependencies: @langchain/core/tools, zod (already present)
• Session files: Reads from memory/sessions/ directory
• No breaking changes: New tool, no modifications to existing tool contracts

---

What Changed

• Implemented src/tools/compaction.js with:
  • parseCompactionOutput() — splits stdout on # Compaction marker, returns { ok, summary, error? }
  • spawnCompactionProcess() — spawns node process with 60s timeout, captures stdout/stderr
  • createCompactionTool() — factory returning LangChain Tool with zod schema (optional threadID, maxMessages)
• Registered tool in src/tools/index.js (import, TOOL_PERMISSIONS, TOOL_FACTORIES)
• Added comprehensive unit tests in tests/unit/tools_compaction.test.js:
  • parseCompactionOutput: happy path, missing marker, empty/null output, multiple markers, thinking before marker, multiline summary
  • createCompactionTool: name, description, schema, sessionsDir config
  • Integration: tool registration via buildToolConfig
• Added spec at openspec/specs/compaction/spec.md

Testing

• Unit tests for all public functions
• Integration tests for tool registration
• All existing tests preserved

[avoidwork]

PR Audit: compaction-tool-session-summarization

Compared against: OpenSpec proposal, design, tasks (archived as 2026-06-21-compaction-tool-session-summarization)
Tests: 1176 pass, 0 fail, 1 skip

---

Task Completion

Task	Status	Notes
1.1 Create parseCompactionOutput()	✅ Done	Splits on # Compaction marker, returns { ok, summary, error? }
1.2 Implement spawnCompactionProcess()	✅ Done	Spawns node process, 60s timeout, stdout/stderr capture, error events
1.3 Implement createCompactionTool()	✅ Done	Factory returning LangChain Tool with zod schema (threadID, maxMessages)
2.1 Add import in src/tools/index.js	✅ Done	import { createCompactionTool } from "./compaction.js"
2.2 Add compaction: [] to TOOL_PERMISSIONS	✅ Done	Empty permissions — correct, spawned process handles its own I/O
2.3 Add compaction: createCompactionTool to TOOL_FACTORIES	✅ Done	Registered in TOOL_FACTORIES object
3.1 parseCompactionOutput tests	✅ Done	8 tests: happy path, missing marker, empty/null, no content, multiple markers, thinking before marker, multiline
3.2 createCompactionTool tests	✅ Done	5 tests: name, description, schema, sessionsDir config
3.3 Integration tests	✅ Done	2 tests: registration with empty and non-empty permissions
4.1 npm test	✅ Done	All 1176 tests pass
4.2 npm run lint	⚠️ Not verified	Lint not run as part of this PR
4.3 npm start	⚠️ Not verified	App start not verified (expected — TUI needs interactive terminal)

---

Spec Compliance

Proposal "What Changes":

• ✅ New compaction tool — implemented in src/tools/compaction.js
• ✅ Spawns node process to read session files — spawnCompactionProcess()
• ✅ Output uses # Compaction marker — parseCompactionOutput() splits on it
• ✅ Integrates with tool registry — src/tools/index.js updated
• ✅ Unit tests — tests/unit/tools_compaction.test.js (17 tests)

Design Decisions — Implemented as Specified:

• ✅ Spawn node process for summarization logic (separation of concerns)
• ✅ # Compaction marker as output delimiter
• ✅ Empty permissions array (spawned process handles I/O)

Design Risks — Mitigations in Place:

• ✅ Spawn failures — 60s timeout, error event handler, stderr captured
• ✅ Session file not found — spawned process handles it; tool returns error if marker not found
• ✅ Multiple markers — tool takes index[1], discards earlier occurrences
• ✅ Marker with no content — returns { ok: false, error: "..." }

---

Findings

Severity	Issue
Low	src/tools/compaction.js missing trailing newline (git: \ No newline at end of file)
Low	Lint not verified as part of PR workflow (task 4.2)

---

Verdict

All proposed tasks implemented. Spec compliance: complete.
The PR delivers exactly what the OpenSpec artifacts described — a new compaction tool for semantic session summarization, properly registered in the tool registry with comprehensive tests.

Recommendation: Approve and merge.

---

Audit performed against archived change: openspec/changes/archive/2026-06-21-compaction-tool-session-summarization/