@stackstackstack/dsh-command-compact 0.1.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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/compaction/command-compact/README.md
+README.md: b5deef6f934395841ae5530fa3c40552854319c4
+README.zh.md: 511da7b34dcaca1a62380a1fea7167aeaac8785a

package/README.md

@@ -0,0 +1,66 @@
+# @stackstackstack/dsh-command-compact
+
+English | [中文](README.zh.md)
+
+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: '@stackstackstack/dsh-commands'
+- id: compaction-basic
+  name: '@stackstackstack/dsh-compaction-basic'
+- id: command-compact
+  name: '@stackstackstack/dsh-command-compact'
+```
+
+The shipped `dsh` 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/README.zh.md

@@ -0,0 +1,66 @@
+# @stackstackstack/dsh-command-compact
+
+[English](README.md) | 中文
+
+通过 [`ctx.compaction`](../compaction/README.md) 提供面向用户的 `/compact` 压缩（compaction）控制。该插件通过 [`ctx.commands`](../../interaction/commands/README.md) 注册一个全局命令，因此组合中的每个命令适配器都能发现并执行它，无需模型轮次。[排队手动压缩 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md)拥有接纳、锁与持久性决策。
+
+## 命令约定
+
+| 输入 | 结果 |
+|---|---|
+| `/compact` | 即使未达到自动压力，也摘要一段有效、平衡的较早范围；独立标记对 flush 后，报告被替换的历史项数量与估算 token 数。 |
+| `/compact`，但没有可压缩历史 | `No compactable history yet.`：不会写入标记，也不会变更 surface。 |
+| `/compact <anything>` | `Usage: /compact (no arguments)`：该命令不接受参数，也不会调用压缩后端。 |
+
+该命令与后端无关，只依赖 `compactNow(agent, signal)`。调用该命令的 agent（智能体）就是操作的确切目标，发起分发的 UI 会通过 seam 转发取消信号。每次完成的调用都会记录执行器所属的纯日志事件对 `command/run` / `command/done`；两者都不进入模型历史。成功时，`command/done.sourceEventSeq` 会指明该事务的 `compaction/summary` 事件，让呈现层无须解析结果文本或假定两行相邻，即可将命令生命周期归并到对应检查点中。
+
+预期的 `ManualCompactionError` 代码会成为稳定的直接错误：
+
+| 代码 | 直接结果 |
+|---|---|
+| `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.` |
+
+busy 结果有意限定在进程范围内：活动的未匹配标记会阻塞，而早于最新 `session/end-seed` 的标记已陈旧，不会阻塞。意外实现故障会拒绝分发。取消仍具有最终决定权；后端会完成必需的闭合／flush 清理，命令内部以 `Compaction cancelled.` 结算，而命令执行器会因取消错误停止等待。插件处置会先注销 `/compact`，再等待所有已开始的处理器结算，因此根级 teardown 不会越过已中止命令的闭合或 flush 边界。
+
+压缩运行期间提交的提示词仍会按 agent 的普通 FIFO 获得接纳，保留相同的身份与唤醒信息。它们仅在压缩的显式持久性检查点和接纳预留释放后启动。空闲注入的上下文不受阻塞：它可以记录在 `compaction/start` 与 `compaction/end` 之间，位置替换会使其在检查点之后保持可见。
+
+## 组合
+
+生产方注入 `commands` 和 `compact`。挂载命令注册表、一个后端与本插件：
+
+```yaml
+- id: commands
+  name: '@stackstackstack/dsh-commands'
+- id: compaction-basic
+  name: '@stackstackstack/dsh-compaction-basic'
+- id: command-compact
+  name: '@stackstackstack/dsh-command-compact'
+```
+
+随附 `dsh` 基础配置将它挂载在 `compaction-basic` 旁，Web 客户端提供命令适配器。未组合命令适配器的自动化接口只保留自动压缩。
+
+## 模型体验
+
+### 用户 `/compact` 控制
+
+#### 模型看到什么
+
+斜杠输入与直接结果绝不会进入模型请求。已获接纳的压缩会另外在独立的 `compaction/* { turn: null }` 标记对内，用后端的 user 角色检查点替换一段较早范围。
+
+#### Token 影响
+
+命令生命周期不会增加模型 token。成功压缩会用一份带框架的摘要替换所选范围，从而减少后续请求；摘要生成本身需要一次辅助请求。
+
+#### KV Cache 影响
+
+命令发现与簿记不会影响缓存。已获接纳的 surface 替换会从第一个被遮蔽的历史 token 起使复用失效。
+
+## 已知限制与暂缓事项
+
+- **仅限空闲状态**：当一个轮次或已获接纳的唤醒提示词拥有优先权时，`/compact` 会报告 `busy`；命令本身不会排队。
+- **不接受范围或策略参数**：无参数形式使各命令适配器的行为保持稳定。显式范围仍由编程接口 `compactRegion()` 处理。
+- **仅限命令适配器**：没有 `ctx.commands` 的接口无法调用该命令，只能依赖自动压力压缩。

package/lib/index.js

@@ -0,0 +1,100 @@
+import { ManualCompactionError } from "@stackstackstack/dsh-compaction";
+//#region lib/types/index.js
+/**
+* Human-facing `/compact` command over the backend-independent compaction seam.
+* @module @stackstackstack/dsh-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 `@stackstackstack/dsh-command-compact`.
+* @module @stackstackstack/dsh-command-compact/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-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 @stackstackstack/dsh-command-compact
+ */
+import type { Context } from '@deepseek-ai/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 `@stackstackstack/dsh-command-compact`.
+ * @module @stackstackstack/dsh-command-compact/invariant
+ */
+import type { Context } from '@deepseek-ai/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,51 @@
+{
+  "name": "@stackstackstack/dsh-command-compact",
+  "description": "Human-facing slash command for explicit session compaction",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-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": {
+    "@stackstackstack/dsh-commands": "^0.1.5",
+    "@stackstackstack/dsh-compaction": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@stackstackstack/dsh-commands": "^0.1.5",
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-compaction": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}