@hydraharness/harness-compaction 0.1.1-rc.10

package/lib/types/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Compaction vocabulary: the result type and the `compaction/*` session events.
+ * Those declaration-merged events record the lock and summary inputs without entering the surface, so they are not
+ * surface events; a separate replacement `user/message` carries the summary.
+ * Backend packages own configuration and retention policy; see
+ * `.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md`.
+ * @module @hydraharness/harness-compaction/types
+ */
+import type { ContentBlock, TokenUsage } from '@hydraharness/harness-llm';
+import type { CommandId } from '@hydraharness/harness-commands/brand';
+import type { CompactionId } from './brand.ts';
+export type { CompactionId };
+declare module '@hydraharness/harness-session/types' {
+    interface SessionEventMap {
+        /**
+         * Marks the start of a compaction — log-only, holds the lock until
+         * `compaction/end`. A numbered owner is strictly enclosed by that open turn;
+         * `null` identifies a standalone manual transaction between turns.
+         */
+        'compaction/start': {
+            compactionId: CompactionId;
+            sourceCommandId?: CommandId;
+            turn: number | null;
+        };
+        /**
+         * Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
+         * The summary content is in `data.summary`; the actual surface replacement
+         * is performed by the immediately following `user/message` event that
+         * shadows the compacted range. That adjacency is contractual — the
+         * shadowed pricing fields are the replacement's shadow price, so a
+         * consumer may pair a replacement with the metering event directly
+         * before it (`compaction/prune` documents the shared protocol).
+         */
+        'compaction/summary': {
+            compactionId: CompactionId;
+            sourceCommandId?: CommandId;
+            summary: ContentBlock[];
+            shadowedRange: {
+                start: number;
+                end: number;
+            };
+            shadowedSeqs: number[];
+            shadowedTokenCount: number;
+            /** The provider route that wrote the summary. */
+            provider: string;
+            /**
+             * The model that wrote the summary — the summarize call's envelope,
+             * reported by the backend that made the call, logged so the one-shot
+             * request is reconstructable from log + code and "which model wrote
+             * this summary" has a durable answer (the reconstructability Agent Note).
+             */
+            model: string;
+            /** The generation cap the summarize call sent, when one applied. */
+            maxTokens?: number;
+            /** Provider-reported token usage for the summarization request, when emitted. */
+            usage?: TokenUsage;
+        } & ({
+            /** Complete provider output before the backend's safe summary projection. */
+            rawOutput: ContentBlock[];
+            /** Identifies exactly one call through this context's `ctx.llm.stream()`. */
+            llmStreamCall: true;
+        } | {
+            /** Optional complete output from an unmarked template, remote, or other summarizer. */
+            rawOutput?: ContentBlock[];
+            /** An unmarked summary does not identify a call through this context's LLM seam. */
+            llmStreamCall?: never;
+        });
+        /**
+         * Marks the end of a compaction — log-only, releases the lock. Its owner
+         * matches `compaction/start`; `error` records an unsuccessful attempt.
+         */
+        'compaction/end': {
+            compactionId: CompactionId;
+            sourceCommandId?: CommandId;
+            turn: number | null;
+            error?: string;
+        };
+        /**
+         * Shadow price of one model-free prune replacement — log-only, no
+         * surfaceOp. The shared shadow-price protocol: a surface `replace` event
+         * is priced by the metering event immediately before it (`compaction/summary`
+         * for a summarizing compaction, this event for a prune), which states the
+         * heuristic token price of the exact replaced range so a pure consumer
+         * can subtract it without retaining per-node prices. The replacement MUST
+         * be appended synchronously right after this event.
+         */
+        'compaction/prune': {
+            /** The replaced range's first and last surface-node seqs (a surface-position span, like {@link CompactionResult.shadowedRange}). */
+            shadowedRange: {
+                start: number;
+                end: number;
+            };
+            /** The seqs of all shadowed surface nodes, in surface order. */
+            shadowedSeqs: number[];
+            /** Heuristic price of the shadowed content under the token-meter's fixed estimator. */
+            shadowedTokenCount: number;
+        };
+    }
+}
+/** Result of a successful compaction operation. */
+export interface CompactionResult {
+    /** Stable identity shared by this compaction's complete durable lifecycle. */
+    compactionId: CompactionId;
+    /** Human command that initiated this compaction, when it was manual. */
+    sourceCommandId?: CommandId;
+    /** The seq of the appended `compaction/start` event. */
+    startSeq: number;
+    /** The seq of the appended `compaction/summary` event. */
+    summarySeq: number;
+    /** The seq of the appended `compaction/end` event. */
+    endSeq: number;
+    /** The summary content blocks produced by the backend. */
+    summary: ContentBlock[];
+    /**
+     * The surface-boundary pair that was shadowed: the seqs of the first
+     * (`start`) and last (`end`) surface nodes of the replaced range. A
+     * surface-POSITION span, not a numeric seq interval — after a prior replace
+     * lands a fresh high-seq summary node at an older range's position, `start`
+     * can be GREATER than `end`. {@link CompactionResult.shadowedSeqs} is the
+     * authoritative set of shadowed nodes, in surface order.
+     */
+    shadowedRange: {
+        start: number;
+        end: number;
+    };
+    /** The seqs of all shadowed surface nodes, in surface order. */
+    shadowedSeqs: number[];
+    /** Estimated token count of the shadowed content. */
+    shadowedTokenCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,10 @@
+/**
+ * Compaction vocabulary: the result type and the `compaction/*` session events.
+ * Those declaration-merged events record the lock and summary inputs without entering the surface, so they are not
+ * surface events; a separate replacement `user/message` carries the summary.
+ * Backend packages own configuration and retention policy; see
+ * `.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md`.
+ * @module @hydraharness/harness-compaction/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@hydraharness/harness-compaction",
+  "description": "Abstract compaction service seam (ctx.compaction) for the Hydra harness",
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-Harness.git",
+    "directory": "packages/compaction/compaction"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./checkpoint": {
+      "types": "./lib/types/checkpoint.d.ts",
+      "default": "./lib/types/checkpoint.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-commands": "^0.1.1-rc.10",
+    "@hydraharness/harness-session": "^0.1.1-rc.10",
+    "@hydraharness/harness-llm": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-brand": "^0.1.1-rc.10",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-brand": "^0.1.1-rc.10",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/harness-commands": "^0.1.1-rc.10",
+    "@hydraharness/harness-llm": "^0.1.1-rc.10",
+    "@hydraharness/harness-session": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}