@hydraharness/harness-command-compact 0.1.1-rc.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @hydraharness/harness-command-compact
+
+Human-facing `/compact` control over [`ctx.compaction`](../compaction/README.md). The plugin registers one global command through [`ctx.commands`](../../interaction/commands/README.md), so every composed command adapter discovers and executes it without a model turn. The [queued manual compaction Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md) owns the admission, lock, and durability decisions.
+
+## Command contract
+
+| Input | Result |
+|---|---|
+| `/compact` | Summarize one useful balanced older span even below automatic pressure, then report the replaced history-item count and estimated tokens after the standalone bracket is flushed. |
+| `/compact` with no compactable history | `No compactable history yet.` — no marker or surface mutation is written. |
+| `/compact <anything>` | `Usage: /compact (no arguments)` — the command takes no arguments and calls no compaction backend. |
+
+The command is backend-independent: it depends only on `compactNow(agent, signal)`. The invoking agent is the exact target, and the dispatching UI's cancellation signal is forwarded through the seam. Every resolved invocation records the executor-owned log-only pair `command/run` / `command/done`; neither event joins model history. On success, `command/done.sourceEventSeq` names the transaction's `compaction/summary` event so a presentation can fold the command lifecycle into its checkpoint without parsing result text or assuming adjacent rows.
+
+Expected `ManualCompactionError` codes become stable direct errors:
+
+| Code | Direct result |
+|---|---|
+| `busy` | `Compaction is unavailable because this process has an active compaction, or the agent is not idle.` |
+| `changed` | `The history selected for compaction changed before it could be replaced. The conversation is unchanged; the attempt is recorded in the session log.` |
+| `summary` | `Compaction could not produce a useful summary. The conversation is unchanged; the attempt is recorded in the session log.` |
+| `commit` | `Compaction did not finish cleanly; some session history may have changed. Inspect the current session state before retrying.` |
+| `persistence` | `Compaction finished, but the session could not be saved.` |
+
+The busy result is intentionally process-scoped: a live unmatched marker blocks, while a marker older than the newest `session/end-seed` is stale and does not. Unexpected implementation failures reject dispatch. Cancellation remains authoritative; the backend completes its required close/flush cleanup, and the command settles internally as `Compaction cancelled.` while the command executor stops waiting with its cancellation error. Plugin disposal first unregisters `/compact`, then drains every handler that already started, so root teardown cannot pass an aborted command's close or flush boundary.
+
+Prompts submitted while compaction runs remain accepted in the agent's ordinary FIFO with the same identity and wakeup facts. They start only after the compaction's explicit durability checkpoint and admission release. Idle injected context is not held: it may be logged between `compaction/start` and `compaction/end`, and positional replacement leaves it visible after the checkpoint.
+
+## Composition
+
+The producer injects `commands` and `compact`. Mount the command registry, one backend, and this plugin:
+
+```yaml
+- id: commands
+  name: '@hydraharness/harness-commands'
+- id: compaction-basic
+  name: '@hydraharness/harness-compaction-basic'
+- id: command-compact
+  name: '@hydraharness/harness-command-compact'
+```
+
+The shipped `hydra` base mounts it beside `compaction-basic`, and the Web client provides the command adapter. Automation surfaces that compose no command adapter keep automatic compaction only.
+
+## Model Experience
+
+### Human `/compact` control
+
+#### What the model sees
+
+The slash input and direct result never enter a model request. An accepted compaction separately replaces an older span with the backend's user-role checkpoint inside a standalone `compaction/* { turn: null }` bracket.
+
+#### Token effect
+
+The command lifecycle adds no model tokens. A successful compaction reduces later requests by replacing the selected span with one framed summary; summarization itself is one auxiliary request.
+
+#### KV Cache effect
+
+Discovery and command bookkeeping do not affect the cache. The accepted surface replacement invalidates reuse from the first shadowed history token.
+
+## Known Limitations and Deferred Work
+
+- **Idle-only** — `/compact` reports `busy` when a turn or already accepted waking prompt has right of way; the command itself is not queued.
+- **No range or policy arguments** — the argument-free form keeps behavior stable across command adapters. Explicit ranges remain the programmatic `compactRegion()` path.
+- **Command adapters only** — surfaces without `ctx.commands` cannot invoke it and rely on automatic pressure compaction.

package/lib/index.js

@@ -0,0 +1,100 @@
+import { ManualCompactionError } from "@hydraharness/harness-compaction";
+//#region lib/types/index.js
+/**
+* Human-facing `/compact` command over the backend-independent compaction seam.
+* @module @hydraharness/harness-command-compact
+*/
+const name = "command-compact";
+const inject = ["commands", "compaction"];
+const USAGE = "Usage: /compact (no arguments)";
+/** Fail loudly if a locally closed union gains an unhandled member. */
+/* v8 ignore start -- closed-union backstop is unreachable without violating the TypeScript contract */
+function assertNever(value) {
+	throw new TypeError(`unknown manual compaction error code: ${String(value)}`);
+}
+/* v8 ignore stop */
+/** Convert expected capability failures into concise human-only outcomes. */
+function expectedFailure(error) {
+	switch (error.code) {
+		case "busy": return {
+			kind: "error",
+			text: "Compaction is unavailable because this process has an active compaction, or the agent is not idle."
+		};
+		case "cancelled": return {
+			kind: "error",
+			text: "Compaction cancelled."
+		};
+		case "changed": return {
+			kind: "error",
+			text: "The history selected for compaction changed before it could be replaced. The conversation is unchanged; the attempt is recorded in the session log."
+		};
+		case "summary": return {
+			kind: "error",
+			text: "Compaction could not produce a useful summary. The conversation is unchanged; the attempt is recorded in the session log."
+		};
+		case "commit": return {
+			kind: "error",
+			text: "Compaction did not finish cleanly; some session history may have changed. Inspect the current session state before retrying."
+		};
+		case "persistence": return {
+			kind: "error",
+			text: "Compaction finished, but the session could not be saved."
+		};
+		/* v8 ignore next 2 -- ManualCompactionErrorCode is closed and every member is handled above */
+		default: return assertNever(error.code);
+	}
+}
+/** Execute one argument-free manual compaction request. */
+async function executeCompact(ctx, invocation) {
+	if (invocation.rawInput.trim().length > 0) return {
+		kind: "error",
+		text: USAGE
+	};
+	try {
+		const result = await ctx.compaction.compactNow(invocation.agent, invocation.signal, invocation.commandId);
+		if (result === null) return {
+			kind: "success",
+			text: "No compactable history yet."
+		};
+		return {
+			kind: "success",
+			text: `Compacted ${result.shadowedSeqs.length} history items (~${result.shadowedTokenCount} tokens).`,
+			sourceEventSeq: result.summarySeq
+		};
+	} catch (error) {
+		if (invocation.signal.aborted) return {
+			kind: "error",
+			text: "Compaction cancelled."
+		};
+		if (error instanceof ManualCompactionError) return expectedFailure(error);
+		throw error;
+	}
+}
+/**
+* Register `/compact` for every composed human-command adapter.
+* @param ctx - context carrying the command registry and the compaction seam.
+*/
+function apply(ctx) {
+	const active = /* @__PURE__ */ new Set();
+	const handler = (invocation) => {
+		const operation = executeCompact(ctx, invocation);
+		active.add(operation);
+		const retire = () => {
+			active.delete(operation);
+		};
+		operation.then(retire, retire);
+		return operation;
+	};
+	ctx.effect(function* () {
+		yield async () => {
+			await Promise.allSettled(active);
+		};
+		yield ctx.commands.register({
+			name: "compact",
+			description: "Compact older conversation history",
+			handler
+		});
+	}, "command-compact lifecycle");
+}
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-command-compact`.
+* @module @hydraharness/harness-command-compact/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-command-compact";
+/** Cordis companion plugin name. */
+const name = "command-compact-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this command adapter owns no state or event stream; the compaction seam owns
+* the balanced durable transaction and the command registry owns registration and dispatch lifecycle.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Human-facing `/compact` command over the backend-independent compaction seam.
+ * @module @hydraharness/harness-command-compact
+ */
+import type { Context } from '@hydraharness/cordis';
+export declare const name = "command-compact";
+export declare const inject: string[];
+/**
+ * Register `/compact` for every composed human-command adapter.
+ * @param ctx - context carrying the command registry and the compaction seam.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-command-compact`.
+ * @module @hydraharness/harness-command-compact/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "command-compact-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@hydraharness/harness-command-compact",
+  "description": "Human-facing slash command for explicit session compaction",
+  "hydra": {
+    "plugin": {
+      "application": "Use /compact to summarize a long conversation and reduce its active model context."
+    }
+  },
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/compaction/command-compact"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-commands": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-compaction": "^0.1.1-rc.5"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis-plugin-include": "^1.0.7",
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-agent": "^0.1.1-rc.5",
+    "@hydraharness/harness-compaction": "^0.1.1-rc.5",
+    "@hydraharness/harness-commands": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-llm": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-session": "^0.1.1-rc.5"
+  }
+}