fix(session): make SessionConfig.compaction match runtime; close #158

Align the public SessionConfig.compaction type and docstring with how
compaction actually behaves. The wiring itself (maybeCompact settings
parameter + Session.#runCompaction passthrough) already landed; this
finishes the remaining items from #158:

- Widen the public type to Partial<CompactionSettings> so { enabled:
  false } and single-field overrides type-check. The stored config
  (session.config.compaction) is also Partial, so the shapes now match.
- Rewrite the docstring: compaction is on by default, opt out with
  { enabled: false }, individual fields fall back to built-in defaults.
- Add a Session-level integration test asserting enabled: false
  actually suppresses compaction when the threshold is crossed.
- Restore the tunable-knobs example in the configuration guide, with
  both opt-out and threshold-override patterns plus when-it-fires notes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: siripr4

docs/src/content/docs/guides/configuration.md

@@ -196,7 +196,32 @@ Thinking can also be overridden per `ask()` — see [API Keys and Providers](/me
 
 ### Context Compaction
 
-When conversations grow long, megasthenes automatically summarizes older messages to stay within the model's context window. Compaction is enabled by default.
+When conversations grow long, megasthenes automatically summarizes older messages to stay within the model's context window. Compaction is enabled by default — set `compaction: { enabled: false }` to opt out, or override individual fields to tune when it fires. Any fields you leave unset fall back to the defaults shown below.
+
+```ts
+// Opt out entirely
+await client.connect({
+  repo: { url: "https://github.com/owner/repo" },
+  model: { provider: "anthropic", id: "claude-sonnet-4-6" },
+  maxIterations: 20,
+  compaction: { enabled: false },
+});
+
+// Tune the thresholds (e.g. for a 1M-context model)
+await client.connect({
+  repo: { url: "https://github.com/owner/repo" },
+  model: { provider: "anthropic", id: "claude-sonnet-4-6" },
+  maxIterations: 20,
+  compaction: {
+    enabled: true,              // default: true
+    contextWindow: 1_000_000,   // default: 200_000 — total usable context
+    reserveTokens: 16_384,      // default: 16_384 — tokens held back for the response
+    keepRecentTokens: 20_000,   // default: 20_000 — recent messages kept unsummarized
+  },
+});
+```
+
+Compaction fires when estimated context tokens exceed `contextWindow - reserveTokens`. The most recent messages totalling roughly `keepRecentTokens` are retained verbatim; everything before that is replaced with an LLM-generated summary. See the [`compaction` event in Handling Responses](/megasthenes/guides/handling-responses/) for how to observe it at runtime.
 
 ### Tracing
 

src/index.ts

@@ -85,8 +85,14 @@ export interface SessionConfig {
 	maxIterations: number;
 	/** Thinking/reasoning configuration. If omitted, thinking is off. */
 	thinking?: ThinkingConfig;
-	/** Context compaction settings. If omitted, compaction is off. */
-	compaction?: CompactionSettings;
+	/**
+	 * Context compaction settings. Compaction is on by default — pass
+	 * `{ enabled: false }` to opt out, or override individual fields
+	 * (`contextWindow`, `reserveTokens`, `keepRecentTokens`) to tune when
+	 * compaction fires. Unset fields fall back to built-in defaults
+	 * (200K context window, 16K reserve, 20K recent-keep).
+	 */
+	compaction?: Partial<CompactionSettings>;
 	/** Prior turns to seed the session with. Restores LLM context from previous conversation. */
 	initialTurns?: TurnResult[];
 	/** Last compaction summary from a prior session. Required for compaction continuity when restoring with initialTurns. */

test/compaction.test.ts

@@ -592,4 +592,26 @@ describe("Session compaction integration", () => {
 
 		expect(events.find((e) => e.type === "compaction")).toBeDefined();
 	});
+
+	test("config.compaction.enabled=false suppresses compaction even when the threshold is crossed", async () => {
+		// Same threshold-crushing settings as the trigger-compaction test above —
+		// if `enabled: false` weren't threaded through, this would compact.
+		const session = new Session(createMockRepo(), {
+			model: {} as Model<Api>,
+			systemPrompt: "You are a test assistant",
+			tools: [],
+			maxIterations: 5,
+			executeTool: async () => "mock",
+			logger: nullLogger,
+			stream: createSessionMockStream(),
+			compaction: { enabled: false, contextWindow: 0, reserveTokens: 0, keepRecentTokens: 1 },
+		});
+
+		const events: StreamEvent[] = [];
+		for await (const ev of session.ask("anything")) {
+			events.push(ev);
+		}
+
+		expect(events.find((e) => e.type === "compaction")).toBeUndefined();
+	});
 });