nodmix 2026.5.25

package/docs/concepts/compaction.md

@@ -0,0 +1,203 @@
+---
+summary: "How Nodmix summarizes long conversations to stay within model limits"
+read_when:
+  - You want to understand auto-compaction and /compact
+  - You are debugging long sessions hitting context limits
+title: "Compaction"
+---
+
+Every model has a context window: the maximum number of tokens it can process. When a conversation approaches that limit, Nodmix **compacts** older messages into a summary so the chat can continue.
+
+## How it works
+
+1. Older conversation turns are summarized into a compact entry.
+2. The summary is saved in the session transcript.
+3. Recent messages are kept intact.
+
+When Nodmix splits history into compaction chunks, it keeps assistant tool calls paired with their matching `toolResult` entries. If a split point lands inside a tool block, Nodmix moves the boundary so the pair stays together and the current unsummarized tail is preserved.
+
+The full conversation history stays on disk. Compaction only changes what the model sees on the next turn.
+
+## Auto-compaction
+
+Auto-compaction is on by default. It runs when the session nears the context limit, or when the model returns a context-overflow error (in which case Nodmix compacts and retries).
+
+You will see:
+
+- `embedded run auto-compaction start` / `complete` in normal Gateway logs.
+- `🧹 Auto-compaction complete` in verbose mode.
+- `/status` showing `🧹 Compactions: <count>`.
+
+<Info>
+Before compacting, Nodmix automatically reminds the agent to save important notes to [memory](/concepts/memory) files. This prevents context loss.
+</Info>
+
+<AccordionGroup>
+  <Accordion title="Recognized overflow signatures">
+    Nodmix detects context overflow from these provider error patterns:
+
+    - `request_too_large`
+    - `context length exceeded`
+    - `input exceeds the maximum number of tokens`
+    - `input token count exceeds the maximum number of input tokens`
+    - `input is too long for the model`
+    - `ollama error: context length exceeded`
+
+  </Accordion>
+</AccordionGroup>
+
+## Manual compaction
+
+Type `/compact` in any chat to force a compaction. Add instructions to guide the summary:
+
+```
+/compact Focus on the API design decisions
+```
+
+When `agents.defaults.compaction.keepRecentTokens` is set, manual compaction honors that Pi cut-point and keeps the recent tail in rebuilt context. Without an explicit keep budget, manual compaction behaves as a hard checkpoint and continues from the new summary alone.
+
+## Configuration
+
+Configure compaction under `agents.defaults.compaction` in your `nodmix.json`. The most common knobs are listed below; for the full reference, see [Session management deep dive](/reference/session-management-compaction).
+
+### Using a different model
+
+By default, compaction uses the agent's primary model. Set `agents.defaults.compaction.model` to delegate summarization to a more capable or specialized model. The override accepts any `provider/model-id` string:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "compaction": {
+        "model": "openrouter/anthropic/claude-sonnet-4-6"
+      }
+    }
+  }
+}
+```
+
+This works with local models too, for example a second Ollama model dedicated to summarization:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "compaction": {
+        "model": "ollama/llama3.1:8b"
+      }
+    }
+  }
+}
+```
+
+When unset, compaction starts with the active session model. If summarization fails with a model-fallback-eligible provider error, Nodmix retries that compaction attempt through the session's existing model fallback chain. The fallback choice is temporary and is not written back to session state. An explicit `agents.defaults.compaction.model` override remains exact and does not inherit the session fallback chain.
+
+### Identifier preservation
+
+Compaction summarization preserves opaque identifiers by default (`identifierPolicy: "strict"`). Override with `identifierPolicy: "off"` to disable, or `identifierPolicy: "custom"` plus `identifierInstructions` for custom guidance.
+
+### Active transcript byte guard
+
+When `agents.defaults.compaction.maxActiveTranscriptBytes` is set, Nodmix triggers normal local compaction before a run if the active JSONL reaches that size. This is useful for long-running sessions where provider-side context management may keep model context healthy while the local transcript keeps growing. It does not split raw JSONL bytes; it asks the normal compaction pipeline to create a semantic summary.
+
+<Warning>
+The byte guard requires `truncateAfterCompaction: true`. Without transcript rotation, the active file would not shrink and the guard remains inactive.
+</Warning>
+
+### Successor transcripts
+
+When `agents.defaults.compaction.truncateAfterCompaction` is enabled, Nodmix does not rewrite the existing transcript in place. It creates a new active successor transcript from the compaction summary, preserved state, and unsummarized tail, then keeps the previous JSONL as the archived checkpoint source.
+Successor transcripts also drop exact duplicate long user turns that arrive
+inside a short retry window, so channel retry storms are not carried into the
+next active transcript after compaction.
+
+Pre-compaction checkpoints are retained only while they stay below Nodmix's
+checkpoint size cap; oversized active transcripts still compact, but Nodmix
+skips the large debug snapshot instead of doubling disk usage.
+
+### Compaction notices
+
+By default, compaction runs silently. Set `notifyUser` to show brief status messages when compaction starts and completes:
+
+```json5
+{
+  agents: {
+    defaults: {
+      compaction: {
+        notifyUser: true,
+      },
+    },
+  },
+}
+```
+
+### Memory flush
+
+Before compaction, Nodmix can run a **silent memory flush** turn to store durable notes to disk. Set `agents.defaults.compaction.memoryFlush.model` when this housekeeping turn should use a local model instead of the active conversation model:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "compaction": {
+        "memoryFlush": {
+          "model": "ollama/qwen3:8b"
+        }
+      }
+    }
+  }
+}
+```
+
+The memory-flush model override is exact and does not inherit the active session fallback chain. See [Memory](/concepts/memory) for details and config.
+
+## Pluggable compaction providers
+
+Plugins can register a custom compaction provider via `registerCompactionProvider()` on the plugin API. When a provider is registered and configured, Nodmix delegates summarization to it instead of the built-in LLM pipeline.
+
+To use a registered provider, set its id in your config:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "compaction": {
+        "provider": "my-provider"
+      }
+    }
+  }
+}
+```
+
+Setting a `provider` automatically forces `mode: "safeguard"`. Providers receive the same compaction instructions and identifier-preservation policy as the built-in path, and Nodmix still preserves recent-turn and split-turn suffix context after provider output.
+
+<Note>
+If the provider fails or returns an empty result, Nodmix falls back to built-in LLM summarization.
+</Note>
+
+## Compaction vs pruning
+
+|                  | Compaction                    | Pruning                          |
+| ---------------- | ----------------------------- | -------------------------------- |
+| **What it does** | Summarizes older conversation | Trims old tool results           |
+| **Saved?**       | Yes (in session transcript)   | No (in-memory only, per request) |
+| **Scope**        | Entire conversation           | Tool results only                |
+
+[Session pruning](/concepts/session-pruning) is a lighter-weight complement that trims tool output without summarizing.
+
+## Troubleshooting
+
+**Compacting too often?** The model's context window may be small, or tool outputs may be large. Try enabling [session pruning](/concepts/session-pruning).
+
+**Context feels stale after compaction?** Use `/compact Focus on <topic>` to guide the summary, or enable the [memory flush](/concepts/memory) so notes survive.
+
+**Need a clean slate?** `/new` starts a fresh session without compacting.
+
+For advanced configuration (reserve tokens, identifier preservation, custom context engines, OpenAI server-side compaction), see the [Session management deep dive](/reference/session-management-compaction).
+
+## Related
+
+- [Session](/concepts/session): session management and lifecycle.
+- [Session pruning](/concepts/session-pruning): trimming tool results.
+- [Context](/concepts/context): how context is built for agent turns.
+- [Hooks](/automation/hooks): compaction lifecycle hooks (`before_compaction`, `after_compaction`).

package/docs/concepts/context-engine.md

@@ -0,0 +1,306 @@
+---
+summary: "Context engine: pluggable context assembly, compaction, and subagent lifecycle"
+read_when:
+  - You want to understand how Nodmix assembles model context
+  - You are switching between the legacy engine and a plugin engine
+  - You are building a context engine plugin
+title: "Context engine"
+sidebarTitle: "Context engine"
+---
+
+A **context engine** controls how Nodmix builds model context for each run: which messages to include, how to summarize older history, and how to manage context across subagent boundaries.
+
+Nodmix ships with a built-in `legacy` engine and uses it by default - most users never need to change this. Install and select a plugin engine only when you want different assembly, compaction, or cross-session recall behavior.
+
+## Quick start
+
+<Steps>
+  <Step title="Check which engine is active">
+    ```bash
+    nodmix doctor
+    # or inspect config directly:
+    cat ~/.nodmix/nodmix.json | jq '.plugins.slots.contextEngine'
+    ```
+  </Step>
+  <Step title="Install a plugin engine">
+    Context engine plugins are installed like any other Nodmix plugin.
+
+    <Tabs>
+      <Tab title="From npm">
+        ```bash
+        nodmix plugins install @martian-engineering/lossless-claw
+        ```
+      </Tab>
+      <Tab title="From a local path">
+        ```bash
+        nodmix plugins install -l ./my-context-engine
+        ```
+      </Tab>
+    </Tabs>
+
+  </Step>
+  <Step title="Enable and select the engine">
+    ```json5
+    // nodmix.json
+    {
+      plugins: {
+        slots: {
+          contextEngine: "lossless-claw", // must match the plugin's registered engine id
+        },
+        entries: {
+          "lossless-claw": {
+            enabled: true,
+            // Plugin-specific config goes here (see the plugin's docs)
+          },
+        },
+      },
+    }
+    ```
+
+    Restart the gateway after installing and configuring.
+
+  </Step>
+  <Step title="Switch back to legacy (optional)">
+    Set `contextEngine` to `"legacy"` (or remove the key entirely - `"legacy"` is the default).
+  </Step>
+</Steps>
+
+## How it works
+
+Every time Nodmix runs a model prompt, the context engine participates at four lifecycle points:
+
+<AccordionGroup>
+  <Accordion title="1. Ingest">
+    Called when a new message is added to the session. The engine can store or index the message in its own data store.
+  </Accordion>
+  <Accordion title="2. Assemble">
+    Called before each model run. The engine returns an ordered set of messages (and an optional `systemPromptAddition`) that fit within the token budget.
+  </Accordion>
+  <Accordion title="3. Compact">
+    Called when the context window is full, or when the user runs `/compact`. The engine summarizes older history to free space.
+  </Accordion>
+  <Accordion title="4. After turn">
+    Called after a run completes. The engine can persist state, trigger background compaction, or update indexes.
+  </Accordion>
+</AccordionGroup>
+
+For the bundled non-ACP Codex harness, Nodmix applies the same lifecycle by projecting assembled context into Codex developer instructions and the current turn prompt. Codex still owns its native thread history and native compactor.
+
+### Subagent lifecycle (optional)
+
+Nodmix calls two optional subagent lifecycle hooks:
+
+<ParamField path="prepareSubagentSpawn" type="method">
+  Prepare shared context state before a child run starts. The hook receives parent/child session keys, `contextMode` (`isolated` or `fork`), available transcript ids/files, and optional TTL. If it returns a rollback handle, Nodmix calls it when spawn fails after preparation succeeds.
+</ParamField>
+<ParamField path="onSubagentEnded" type="method">
+  Clean up when a subagent session completes or is swept.
+</ParamField>
+
+### System prompt addition
+
+The `assemble` method can return a `systemPromptAddition` string. Nodmix prepends this to the system prompt for the run. This lets engines inject dynamic recall guidance, retrieval instructions, or context-aware hints without requiring static workspace files.
+
+## The legacy engine
+
+The built-in `legacy` engine preserves Nodmix's original behavior:
+
+- **Ingest**: no-op (the session manager handles message persistence directly).
+- **Assemble**: pass-through (the existing sanitize → validate → limit pipeline in the runtime handles context assembly).
+- **Compact**: delegates to the built-in summarization compaction, which creates a single summary of older messages and keeps recent messages intact.
+- **After turn**: no-op.
+
+The legacy engine does not register tools or provide a `systemPromptAddition`.
+
+When no `plugins.slots.contextEngine` is set (or it's set to `"legacy"`), this engine is used automatically.
+
+## Plugin engines
+
+A plugin can register a context engine using the plugin API:
+
+```ts
+import { buildMemorySystemPromptAddition } from "nodmix/plugin-sdk/core";
+
+export default function register(api) {
+  api.registerContextEngine("my-engine", (ctx) => ({
+    info: {
+      id: "my-engine",
+      name: "My Context Engine",
+      ownsCompaction: true,
+    },
+
+    async ingest({ sessionId, message, isHeartbeat }) {
+      // Store the message in your data store
+      return { ingested: true };
+    },
+
+    async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
+      // Return messages that fit the budget
+      return {
+        messages: buildContext(messages, tokenBudget),
+        estimatedTokens: countTokens(messages),
+        systemPromptAddition: buildMemorySystemPromptAddition({
+          availableTools: availableTools ?? new Set(),
+          citationsMode,
+        }),
+      };
+    },
+
+    async compact({ sessionId, force }) {
+      // Summarize older context
+      return { ok: true, compacted: true };
+    },
+  }));
+}
+```
+
+The factory `ctx` includes optional `config`, `agentDir`, and `workspaceDir`
+values so plugins can initialize per-agent or per-workspace state before the
+first lifecycle hook runs.
+
+Then enable it in config:
+
+```json5
+{
+  plugins: {
+    slots: {
+      contextEngine: "my-engine",
+    },
+    entries: {
+      "my-engine": {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+### The ContextEngine interface
+
+Required members:
+
+| Member             | Kind     | Purpose                                                  |
+| ------------------ | -------- | -------------------------------------------------------- |
+| `info`             | Property | Engine id, name, version, and whether it owns compaction |
+| `ingest(params)`   | Method   | Store a single message                                   |
+| `assemble(params)` | Method   | Build context for a model run (returns `AssembleResult`) |
+| `compact(params)`  | Method   | Summarize/reduce context                                 |
+
+`assemble` returns an `AssembleResult` with:
+
+<ParamField path="messages" type="Message[]" required>
+  The ordered messages to send to the model.
+</ParamField>
+<ParamField path="estimatedTokens" type="number" required>
+  The engine's estimate of total tokens in the assembled context. Nodmix uses this for compaction threshold decisions and diagnostic reporting.
+</ParamField>
+<ParamField path="systemPromptAddition" type="string">
+  Prepended to the system prompt.
+</ParamField>
+<ParamField path="promptAuthority" type='"assembled" | "preassembly_may_overflow"'>
+  Controls which token estimate the runner uses for preemptive overflow
+  prechecks. Defaults to `"assembled"`, which means only the assembled
+  prompt's estimate is checked - appropriate for engines that return a
+  windowed, self-contained context. Set to `"preassembly_may_overflow"` only
+  when your assembled view can hide overflow risk in the underlying
+  transcript; the runner then takes the maximum of the assembled estimate
+  and the pre-assembly (unwindowed) session-history estimate when deciding
+  whether to preemptively compact. Either way, the messages you return are
+  still what the model sees - `promptAuthority` only affects the precheck.
+</ParamField>
+
+`compact` returns a `CompactResult`. When compaction rotates the active
+transcript, `result.sessionId` and `result.sessionFile` identify the successor
+session that the next retry or turn must use.
+
+Optional members:
+
+| Member                         | Kind   | Purpose                                                                                                         |
+| ------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------- |
+| `bootstrap(params)`            | Method | Initialize engine state for a session. Called once when the engine first sees a session (e.g., import history). |
+| `ingestBatch(params)`          | Method | Ingest a completed turn as a batch. Called after a run completes, with all messages from that turn at once.     |
+| `afterTurn(params)`            | Method | Post-run lifecycle work (persist state, trigger background compaction).                                         |
+| `prepareSubagentSpawn(params)` | Method | Set up shared state for a child session before it starts.                                                       |
+| `onSubagentEnded(params)`      | Method | Clean up after a subagent ends.                                                                                 |
+| `dispose()`                    | Method | Release resources. Called during gateway shutdown or plugin reload - not per-session.                           |
+
+### ownsCompaction
+
+`ownsCompaction` controls whether Pi's built-in in-attempt auto-compaction stays enabled for the run:
+
+<AccordionGroup>
+  <Accordion title="ownsCompaction: true">
+    The engine owns compaction behavior. Nodmix disables Pi's built-in auto-compaction for that run, and the engine's `compact()` implementation is responsible for `/compact`, overflow recovery compaction, and any proactive compaction it wants to do in `afterTurn()`. Nodmix may still run the pre-prompt overflow safeguard; when it predicts the full transcript will overflow, the recovery path calls the active engine's `compact()` before submitting another prompt.
+  </Accordion>
+  <Accordion title="ownsCompaction: false or unset">
+    Pi's built-in auto-compaction may still run during prompt execution, but the active engine's `compact()` method is still called for `/compact` and overflow recovery.
+  </Accordion>
+</AccordionGroup>
+
+<Warning>
+`ownsCompaction: false` does **not** mean Nodmix automatically falls back to the legacy engine's compaction path.
+</Warning>
+
+That means there are two valid plugin patterns:
+
+<Tabs>
+  <Tab title="Owning mode">
+    Implement your own compaction algorithm and set `ownsCompaction: true`.
+  </Tab>
+  <Tab title="Delegating mode">
+    Set `ownsCompaction: false` and have `compact()` call `delegateCompactionToRuntime(...)` from `nodmix/plugin-sdk/core` to use Nodmix's built-in compaction behavior.
+  </Tab>
+</Tabs>
+
+A no-op `compact()` is unsafe for an active non-owning engine because it disables the normal `/compact` and overflow-recovery compaction path for that engine slot.
+
+## Configuration reference
+
+```json5
+{
+  plugins: {
+    slots: {
+      // Select the active context engine. Default: "legacy".
+      // Set to a plugin id to use a plugin engine.
+      contextEngine: "legacy",
+    },
+  },
+}
+```
+
+<Note>
+The slot is exclusive at run time - only one registered context engine is resolved for a given run or compaction operation. Other enabled `kind: "context-engine"` plugins can still load and run their registration code; `plugins.slots.contextEngine` only selects which registered engine id Nodmix resolves when it needs a context engine.
+</Note>
+
+<Note>
+**Plugin uninstall:** when you uninstall the plugin currently selected as `plugins.slots.contextEngine`, Nodmix resets the slot back to the default (`legacy`). The same reset behavior applies to `plugins.slots.memory`. No manual config edit is required.
+</Note>
+
+## Relationship to compaction and memory
+
+<AccordionGroup>
+  <Accordion title="Compaction">
+    Compaction is one responsibility of the context engine. The legacy engine delegates to Nodmix's built-in summarization. Plugin engines can implement any compaction strategy (DAG summaries, vector retrieval, etc.).
+  </Accordion>
+  <Accordion title="Memory plugins">
+    Memory plugins (`plugins.slots.memory`) are separate from context engines. Memory plugins provide search/retrieval; context engines control what the model sees. They can work together - a context engine might use memory plugin data during assembly. Plugin engines that want the active memory prompt path should prefer `buildMemorySystemPromptAddition(...)` from `nodmix/plugin-sdk/core`, which converts the active memory prompt sections into a ready-to-prepend `systemPromptAddition`. If an engine needs lower-level control, it can still pull raw lines from `nodmix/plugin-sdk/memory-host-core` via `buildActiveMemoryPromptSection(...)`.
+  </Accordion>
+  <Accordion title="Session pruning">
+    Trimming old tool results in-memory still runs regardless of which context engine is active.
+  </Accordion>
+</AccordionGroup>
+
+## Tips
+
+- Use `nodmix doctor` to verify your engine is loading correctly.
+- If switching engines, existing sessions continue with their current history. The new engine takes over for future runs.
+- Engine errors are logged and surfaced in diagnostics. If a plugin engine fails to register or the selected engine id cannot be resolved, Nodmix does not fall back automatically; runs fail until you fix the plugin or switch `plugins.slots.contextEngine` back to `"legacy"`.
+- For development, use `nodmix plugins install -l ./my-engine` to link a local plugin directory without copying.
+
+## Related
+
+- [Compaction](/concepts/compaction) - summarizing long conversations
+- [Context](/concepts/context) - how context is built for agent turns
+- [Plugin Architecture](/plugins/architecture) - registering context engine plugins
+- [Plugin manifest](/plugins/manifest) - plugin manifest fields
+- [Plugins](/tools/plugin) - plugin overview