@agimon-ai/doompi-autocompact 0.0.1-alpha.8 → 0.0.1-alpha.80

package/README.md

@@ -1,36 +1,121 @@
 # @agimon-ai/doompi-autocompact
 
-Staged checkpoint steering and iterative context compaction for Doompi.
+Staged checkpoint summarization and iterative context compaction for DoomPi.
 
-Compaction runs on a three-pass ladder in a worker thread, so the session never blocks on
-it. It reads the live plan, task graph, and team snapshot and commits them next to the
-summary as authoritative, rather than leaving coordination state to be reconstructed from
-prose.
+Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).
 
-Part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi), a coding agent that loads
-only the skills and tools you name. This package is composed by Doompi and is not usually
-installed on its own.
+Instead of waiting for one final summary near the context limit, Autocompact creates up to three
+asynchronous checkpoints and combines each checkpoint with subsequent messages.
+
+> **Alpha:** thresholds and compaction steering may change between releases.
+
+## Requirements
+
+- Node.js 22.19.0 or newer
+- Pi 0.85.0
+- Authentication for the model selected for summarization
 
 ## Install
 
+`doompi init` and `dpi init` include Autocompact in `default.packages` in `.doom/modes.yaml`.
+Remove it or move it to a named layer to change which major modes load it. Pi discovers its sole
+extension entry through `package.json.pi.extensions`. For direct Pi installation:
+
 ```bash
-npm install @agimon-ai/doompi-autocompact
+pi install npm:@agimon-ai/doompi-autocompact
+```
+
+The extension entry is `@agimon-ai/doompi-autocompact/extensions/pi`.
+
+## Checkpoint ladder
+
+The standard adapter uses thresholds around 50%, 75%, and 95% of the usable context window,
+subject to token caps and Pi's native-compaction clamp:
+
+1. create an initial compact summary;
+2. combine it with later messages and allow the model to decide whether compaction is ready;
+3. combine again and force compaction on the final pass.
+
+## Per-model token checkpoints
+
+Ratios scale with the window, which is usually what you want. On a very large window they can
+also mean the first checkpoint waits far longer than you would like: half of a one-million-token
+window is 500,000 tokens. `modes.autocompact.overrides` pins individual passes to an absolute
+token count for the models you name, and leaves every other model on the ratio ladder.
+
+```yaml
+modes:
+  autocompact:
+    overrides:
+      - model: 'claude-opus-4-[6-9]'
+        tokens:
+          pass1: 75000
+          pass2: 150000
+          pass3: 200000
 ```
 
-## How it loads
+- Entries are tried in file order and the first match wins. A model matching nothing behaves
+  exactly as it does without this key.
+- `model` is a glob supporting `*` and character classes such as `[6-9]`. A pattern containing
+  `/` is matched against `provider/id`, anything else against the bare model id, because the
+  wildcard does not cross the separator. Matching ignores case.
+- The lower of the ratio and the token count wins, so an override can only bring a checkpoint
+  forward, never push one past the point Pi compacts natively.
+- Counts are compared against total context usage, not against growth since the last compaction.
+- A count at or below the current cycle's baseline is ignored and the pass falls back to its
+  ratio. Without that, a compaction landing above the count would satisfy the pass as soon as
+  the next cycle opened and re-fire it every turn.
+- A pass never fires before the one before it. A list that puts a later pass lower is raised to
+  match, the same way a ratio below the previous pass is.
+- A repository config replaces the global list whole rather than merging entry by entry.
+- These keys are not on the cockpit settings page; edit `.doom/config.yaml` directly.
+  Summarization runs asynchronously in the background, on the session's own provider, so a model
+  registered by a Pi provider extension summarizes through that extension. Checkpoints are
+  persisted as hidden session entries and used for later steering.
 
-Doompi loads this unconditionally. It is core, not a layer, so it does not appear in
-`.doom/modes.yaml`: making it optional would only create broken configurations.
+DoomPi uses the configured planning subagent model and thinking level when available, then falls
+back to the active Pi model. Standalone Pi without DoomPi planning configuration uses the active
+model. Each checkpoint can therefore make another provider request, consume quota, and require the
+credentials for the selected model. Provider errors or missing authentication affect checkpoint
+generation rather than granting a free local summary.
 
-Extension entry: `@agimon-ai/doompi-autocompact/extensions/pi`
+## Coordination state
 
-## Entry points
+Autocompact does not own `@agimon-ai/doompi-task` or `@agimon-ai/doompi-team` persistence. The
+standard adapter reads best-effort snapshots from those packages when available, while Task's
+`tasks.json` and Team's run and intercom state remain owned by their respective packages. Missing
+snapshot data is reported as unavailable and must not be inferred from an Autocompact summary.
 
-| Import                                        |
-| --------------------------------------------- |
-| `@agimon-ai/doompi-autocompact`               |
-| `@agimon-ai/doompi-autocompact/extensions/pi` |
+## Public API
+
+```ts
+import { installAutocompactRuntime, thresholdTokens } from '@agimon-ai/doompi-autocompact';
+import type { AutocompactPass } from '@agimon-ai/doompi-autocompact';
+```
+
+Normal Pi activation should use the discovered `extensions/pi` entry. Host integrations can call
+`installAutocompactRuntime` to install package resources into the shared runner-scoped Cordis host.
+The extension entry manages its plugin lifecycle and releases the host lease when the Pi session
+shuts down. `thresholdTokens` exposes the threshold policy for hosts that need to preview or test
+checkpoint boundaries.
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
 
 ## License
 
 MIT
+
+## Extension lifecycle and source layout
+
+`extensions/pi.ts` declares the Autocompact runtime's optional services, typed events, and `onStop` cleanup. Shutdown cancels checkpoint generation and awaits pending work before releasing telemetry and runtime state. Session-tree changes retain their existing generation cancellation behavior. The runtime and policy live in `services/<name>/`, with constants and shared types in dedicated roots.
+
+The direct server entry declares validated configuration resources and a native-fallback status activity from `controllers/serverAutocompact.ts`. The web entry declares settings sections. Flat `exports/` publishes reusable capabilities without forwarding extension entry points.

package/dist/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = (0, require("@agimon-ai/doompi-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,gDAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/doompi-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}