@monotykamary/dsh-tool-session-mutations 0.1.0

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/session-query/tool-session-mutations/README.md
+README.md: 2a0e72c40ca5ae9ba579383d2b038f77fad84c3d
+README.zh.md: 0b45bdf98db0a26a3b6066d5a42e81f44929479f

package/README.md

@@ -0,0 +1,36 @@
+# @monotykamary/dsh-tool-session-mutations
+
+English | [中文](README.zh.md)
+
+Bounded model reader over the current Agent's durable file-mutation receipts. The package registers `changes_read`; its pure `./ledger` entry exports the same commit-ordered projection for external automation without evaluating the plugin.
+
+A list call returns summaries after an optional `after_commit_order` cursor. An exact `commit_order` call returns the recorded replacement hunks in UTF-16 pages. Every result states that the ledger covers receipt-aware tools only. It never reads or writes the workspace, and its output is recorded intent rather than unified-patch syntax or repository state.
+
+## Configuration
+
+| Key | Meaning |
+|---|---|
+| `maxListItems` | Required positive integer limiting one summary page. |
+| `maxDiffChars` | Required positive integer limiting mutation text in one detail page. |
+
+## Model Experience
+
+### Mutation-ledger reader
+
+#### What the model sees
+
+The generated [`changes_read` schema](../../../docs/tool-catalog.md#monotykamarydsh-tool-session-mutations) lists direct and nested receipt-aware mutations from the complete current Session, or returns one mutation's path, hashes, and recorded replacement hunks. Results explicitly exclude shell and external changes.
+
+#### Token effect
+
+One fixed schema is present while the plugin is mounted. List pages are capped by `maxListItems`; detail pages are capped by `maxDiffChars` and continue from the returned offset.
+
+#### KV Cache effect
+
+The schema remains prefix-stable while its definition is unchanged. Each called result appends after the reusable prefix like an ordinary tool result.
+
+## Known Limitations and Deferred Work
+
+- **The ledger records instrumented tools, not repository state** — terminal commands, external edits, file modes, and uncommitted Git state are absent.
+- **Hunks are presentation-oriented replacement intent** — callers must read current files before reconciling and cannot apply the output as a patch.
+- **Only a live Agent Session is readable** — persisted sessions must be resumed before the tool can inspect their complete event history.

package/README.zh.md

@@ -0,0 +1,36 @@
+# @monotykamary/dsh-tool-session-mutations
+
+[English](README.md) | 中文
+
+这是对当前 Agent 持久文件修改 receipt 的有界模型读取器。本包注册 `changes_read`；纯 `./ledger` 入口导出同一套按提交顺序排列的投影，供外部自动化使用，且不会执行插件。
+
+列表调用会返回可选 `after_commit_order` cursor 之后的摘要。指定 `commit_order` 的调用会按 UTF-16 页返回已记录的 replacement hunk。每个结果都会说明 ledger 只覆盖 receipt-aware 工具。它永远不读写工作区，输出是已记录意图，而不是 unified-patch 语法或仓库状态。
+
+## 配置
+
+| 键 | 含义 |
+|---|---|
+| `maxListItems` | 必需的正整数，用于限制一页摘要数量。 |
+| `maxDiffChars` | 必需的正整数，用于限制一页详情中的修改文本。 |
+
+## 模型体验
+
+### 修改 ledger 读取器
+
+#### 模型看到的内容
+
+生成的 [`changes_read` schema](../../../docs/tool-catalog.zh.md#monotykamarydsh-tool-session-mutations) 会列出当前完整 Session 中由直接或嵌套 receipt-aware 工具产生的修改，或返回一项修改的路径、hash 与已记录 replacement hunk。结果会明确排除 shell 与外部修改。
+
+#### Token 影响
+
+插件挂载期间会提供一个固定 schema。列表页受 `maxListItems` 限制；详情页受 `maxDiffChars` 限制，并从返回的 offset 继续。
+
+#### KV Cache 影响
+
+只要定义不变，schema 就保持前缀稳定。每次调用结果都像普通工具结果一样追加在可复用前缀之后。
+
+## 已知限制与暂缓事项
+
+- **Ledger 记录接入的工具，而非仓库状态。**Terminal 命令、外部编辑、文件 mode 与未提交 Git 状态均缺席。
+- **Hunk 是面向展示的 replacement intent。**调用方在对账前必须读取当前文件，不能把输出当作 patch 应用。
+- **只能读取 live Agent Session。**持久 Session 必须先恢复，工具才能检查其完整事件历史。

package/lib/index.js

@@ -0,0 +1,165 @@
+import { COVERAGE, boundedText, mutationLedger, renderMutation } from "./ledger.js";
+import z from "@monotykamary/schemastery";
+import { defineTool } from "@monotykamary/dsh-tools";
+//#region lib/types/index.js
+/**
+* Model-facing reader over the current Session's durable file-mutation receipts.
+*
+* @module @monotykamary/dsh-tool-session-mutations
+*/
+/** Cordis plugin name used by Loader diagnostics. */
+const name = "tool-session-mutations";
+/** Service required by the model-facing Consumer. */
+const inject = ["tools"];
+/** Validated mutation-ledger output bounds. */
+const Config = z.object({
+	maxListItems: z.number().step(1).min(1).required(),
+	maxDiffChars: z.number().step(1).min(1).required()
+});
+const itemSchema = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		commitOrder: {
+			type: "integer",
+			required: true
+		},
+		path: {
+			type: "string",
+			required: true
+		},
+		operation: {
+			type: "string",
+			required: true,
+			enum: [
+				"create",
+				"modify",
+				"delete"
+			]
+		},
+		additions: {
+			type: "integer",
+			required: true
+		},
+		deletions: {
+			type: "integer",
+			required: true
+		},
+		beforeSha256: { type: "string" },
+		afterSha256: { type: "string" }
+	}
+};
+/** Register the current-Session `changes_read` tool. */
+function apply(ctx, config) {
+	ctx.tools.register(defineTool({
+		name: "changes_read",
+		description: "Read file changes committed by receipt-aware tools in this Session. Call without commit_order to list changes in durable commit order; call with commit_order to read that change's recorded replacement hunks. Use the returned SHA-256 identities and ordinary file reads to reconcile later workspace divergence. Shell and external changes are outside this ledger.",
+		parameters: {
+			after_commit_order: {
+				type: "integer",
+				description: "List only changes after this commit order."
+			},
+			commit_order: {
+				type: "integer",
+				description: "Read one exact change instead of listing summaries."
+			},
+			offset: {
+				type: "integer",
+				description: "UTF-16 offset for the next page of one exact change; valid only with commit_order."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						enum: ["list", "detail"]
+					},
+					coverage: {
+						type: "string",
+						required: true
+					},
+					items: {
+						type: "array",
+						required: true,
+						items: itemSchema
+					},
+					nextAfterCommitOrder: { type: "integer" },
+					commitOrder: { type: "integer" },
+					text: { type: "string" },
+					offset: { type: "integer" },
+					nextOffset: { type: "integer" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.kind === "list" ? value.items.length === 0 ? `No recorded file mutations. ${value.coverage}` : [
+					`Recorded file mutations (${value.items.length}):`,
+					...value.items.flatMap((item) => [
+						`#${item.commitOrder} ${item.operation} ${item.path} (+${item.additions} -${item.deletions})`,
+						`  before SHA-256: ${item.beforeSha256 ?? "(absent)"}`,
+						`  after SHA-256: ${item.afterSha256 ?? "(absent)"}`
+					]),
+					...value.nextAfterCommitOrder === void 0 ? [] : [`Continue with after_commit_order=${value.nextAfterCommitOrder}.`],
+					value.coverage
+				].join("\n") : [
+					value.text ?? "",
+					...value.nextOffset === void 0 ? [] : [`Continue change #${value.commitOrder} with offset=${value.nextOffset}.`],
+					value.coverage
+				].join("\n")
+			}]
+		},
+		execute(args, exec) {
+			if (exec.agent === void 0) throw new Error("changes_read requires an owning agent session");
+			for (const [key, value] of [
+				["after_commit_order", args.after_commit_order],
+				["commit_order", args.commit_order],
+				["offset", args.offset]
+			]) if (value !== void 0 && value < 0) throw new Error(`changes_read ${key} must be nonnegative`);
+			if (args.commit_order === void 0 && args.offset !== void 0) throw new Error("changes_read offset requires commit_order");
+			if (args.commit_order !== void 0 && args.after_commit_order !== void 0) throw new Error("changes_read commit_order cannot be combined with after_commit_order");
+			const ledger = mutationLedger(exec.agent.session.events);
+			if (args.commit_order === void 0) {
+				const afterCommitOrder = args.after_commit_order;
+				const eligible = afterCommitOrder === void 0 ? ledger : ledger.filter((item) => item.commitOrder > afterCommitOrder);
+				const items = eligible.slice(0, config.maxListItems).map(({ diffs: _diffs, beforeSha256, afterSha256, ...item }) => ({
+					...item,
+					...beforeSha256 === null ? {} : { beforeSha256 },
+					...afterSha256 === null ? {} : { afterSha256 }
+				}));
+				const lastItem = items.at(-1);
+				return Promise.resolve({
+					kind: "list",
+					coverage: COVERAGE,
+					items,
+					...eligible.length > items.length && lastItem !== void 0 ? { nextAfterCommitOrder: lastItem.commitOrder } : {}
+				});
+			}
+			const mutation = ledger.find((item) => item.commitOrder === args.commit_order);
+			if (mutation === void 0) throw new Error(`changes_read cannot find commit order ${args.commit_order}`);
+			const offset = args.offset ?? 0;
+			const rendered = renderMutation(mutation);
+			if (offset > rendered.length) throw new Error(`changes_read offset ${offset} exceeds change length ${rendered.length}`);
+			const page = boundedText(rendered, offset, config.maxDiffChars);
+			return Promise.resolve({
+				kind: "detail",
+				coverage: COVERAGE,
+				items: [],
+				commitOrder: mutation.commitOrder,
+				text: page.text,
+				offset,
+				...page.nextOffset === null ? {} : { nextOffset: page.nextOffset }
+			});
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: args.commit_order === void 0 ? "List file changes" : `Read file change #${args.commit_order}`,
+			kind: "read"
+		})
+	}));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,20 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@monotykamary/dsh-tool-session-mutations`.
+* @module @monotykamary/dsh-tool-session-mutations/invariant
+*/
+const PACKAGE_NAME = "@monotykamary/dsh-tool-session-mutations";
+/** Cordis companion plugin name. */
+const name = "tool-session-mutations-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** No runtime invariant: the read-only Consumer owns no mutable state beyond its effect-owned tool registration. */
+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/ledger.js

@@ -0,0 +1,75 @@
+//#region lib/types/ledger.js
+/** Pure projections for the model-facing mutation-ledger reader. */
+/** Coverage statement returned with every ledger read. */
+const COVERAGE = "Receipt-aware tool mutations only; shell and external changes are not included.";
+function lineCount(text) {
+	if (text === null || text === "") return 0;
+	return (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n").length;
+}
+function toLedgerMutation(mutation) {
+	return {
+		commitOrder: mutation.commitOrder,
+		path: mutation.path,
+		operation: mutation.operation,
+		additions: mutation.diffs.reduce((sum, diff) => sum + lineCount(diff.newText), 0),
+		deletions: mutation.diffs.reduce((sum, diff) => sum + lineCount(diff.oldText), 0),
+		beforeSha256: mutation.beforeSha256,
+		afterSha256: mutation.afterSha256,
+		diffs: mutation.diffs
+	};
+}
+/**
+* Read every direct and nested committed mutation from a Session in commit order.
+* @param events - complete current Session event history.
+* @returns detached ledger entries sorted by their durable commit order.
+*/
+function mutationLedger(events) {
+	const mutations = [];
+	for (const event of events) if (event.type === "tool/result" || event.type === "tool/code-dispatch") mutations.push(...event.data.mutations ?? []);
+	return mutations.sort((a, b) => a.commitOrder - b.commitOrder).map(toLedgerMutation);
+}
+/**
+* Render one mutation's durable intent without claiming unified-patch semantics.
+* @param mutation - committed mutation and its recorded replacement hunks.
+* @returns bounded-reader source text for the selected mutation.
+*/
+function renderMutation(mutation) {
+	const lines = [
+		`Change #${mutation.commitOrder}: ${mutation.operation} ${mutation.path}`,
+		`Before SHA-256: ${mutation.beforeSha256 ?? "(absent)"}`,
+		`After SHA-256: ${mutation.afterSha256 ?? "(absent)"}`
+	];
+	mutation.diffs.forEach((diff, index) => {
+		lines.push(`Hunk ${index + 1}:`);
+		if (diff.oldText !== null) {
+			lines.push("Removed:");
+			lines.push(diff.oldText);
+		}
+		if (diff.newText !== null) {
+			lines.push("Added:");
+			lines.push(diff.newText);
+		}
+	});
+	return lines.join("\n");
+}
+/**
+* Slice text without ending between a UTF-16 surrogate pair.
+* @param text - complete rendered mutation text.
+* @param offset - UTF-16 code-unit offset selected by the caller.
+* @param maxChars - maximum UTF-16 code units in this page.
+* @returns page text and the next offset, or null at the end.
+*/
+function boundedText(text, offset, maxChars) {
+	let end = Math.min(text.length, offset + maxChars);
+	if (end < text.length) {
+		const prior = text.charCodeAt(end - 1);
+		const next = text.charCodeAt(end);
+		if (prior >= 55296 && prior <= 56319 && next >= 56320 && next <= 57343) end--;
+	}
+	return {
+		text: text.slice(offset, end),
+		nextOffset: end < text.length ? end : null
+	};
+}
+//#endregion
+export { COVERAGE, boundedText, mutationLedger, renderMutation };

package/lib/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Model-facing reader over the current Session's durable file-mutation receipts.
+ *
+ * @module @monotykamary/dsh-tool-session-mutations
+ */
+import type { Context } from '@monotykamary/cordis';
+import z from '@monotykamary/schemastery';
+/** Cordis plugin name used by Loader diagnostics. */
+export declare const name = "tool-session-mutations";
+/** Service required by the model-facing Consumer. */
+export declare const inject: string[];
+/** Deployment-owned output bounds for the mutation-ledger reader. */
+export interface Config {
+    /** Maximum summaries returned by one list call. */
+    maxListItems: number;
+    /** Maximum UTF-16 code units of mutation text returned by one detail page. */
+    maxDiffChars: number;
+}
+/** Validated mutation-ledger output bounds. */
+export declare const Config: z<Config>;
+/** Register the current-Session `changes_read` tool. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@monotykamary/dsh-tool-session-mutations`.
+ * @module @monotykamary/dsh-tool-session-mutations/invariant
+ */
+import type { Context } from '@monotykamary/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-session-mutations-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/lib/types/ledger.d.ts

@@ -0,0 +1,50 @@
+/** Pure projections for the model-facing mutation-ledger reader. */
+import type { FileMutation, SessionEvent } from '@monotykamary/dsh-session';
+/** Coverage statement returned with every ledger read. */
+export declare const COVERAGE = "Receipt-aware tool mutations only; shell and external changes are not included.";
+/** Compact mutation summary used by list pages. */
+export interface MutationSummary {
+    /** Durable Session-wide mutation order. */
+    commitOrder: number;
+    /** Provider display path recorded by the mutating tool. */
+    path: string;
+    /** Committed file operation. */
+    operation: FileMutation['operation'];
+    /** Added receipt lines across all recorded hunks. */
+    additions: number;
+    /** Removed receipt lines across all recorded hunks. */
+    deletions: number;
+    /** Complete prior-content identity, or null for creation. */
+    beforeSha256: string | null;
+    /** Complete resulting-content identity, or null for deletion. */
+    afterSha256: string | null;
+}
+/** One globally ordered mutation with its durable replacement hunks. */
+export interface LedgerMutation extends MutationSummary {
+    /** Ordered replacement hunks recorded by the tool. */
+    diffs: FileMutation['diffs'];
+}
+/**
+ * Read every direct and nested committed mutation from a Session in commit order.
+ * @param events - complete current Session event history.
+ * @returns detached ledger entries sorted by their durable commit order.
+ */
+export declare function mutationLedger(events: readonly SessionEvent[]): LedgerMutation[];
+/**
+ * Render one mutation's durable intent without claiming unified-patch semantics.
+ * @param mutation - committed mutation and its recorded replacement hunks.
+ * @returns bounded-reader source text for the selected mutation.
+ */
+export declare function renderMutation(mutation: LedgerMutation): string;
+/**
+ * Slice text without ending between a UTF-16 surrogate pair.
+ * @param text - complete rendered mutation text.
+ * @param offset - UTF-16 code-unit offset selected by the caller.
+ * @param maxChars - maximum UTF-16 code units in this page.
+ * @returns page text and the next offset, or null at the end.
+ */
+export declare function boundedText(text: string, offset: number, maxChars: number): {
+    text: string;
+    nextOffset: number | null;
+};
+//# sourceMappingURL=ledger.d.ts.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@monotykamary/dsh-tool-session-mutations",
+  "description": "Bounded model reader over durable file-mutation receipts in the current Session",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session-query/tool-session-mutations"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./ledger": {
+      "types": "./lib/types/ledger.d.ts",
+      "default": "./lib/ledger.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/ledger.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@monotykamary/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@monotykamary/dsh-invariants": "^0.1.0",
+    "@monotykamary/dsh-session": "^0.1.0",
+    "@monotykamary/cordis": "^4.0.1",
+    "@monotykamary/dsh-tools": "^0.1.0"
+  },
+  "devDependencies": {
+    "@monotykamary/dsh-invariants": "^0.1.0",
+    "@monotykamary/dsh-system-prompt": "^0.1.0",
+    "@monotykamary/dsh-session": "^0.1.0",
+    "@monotykamary/dsh-llm": "^0.1.0",
+    "@monotykamary/dsh-tools": "^0.1.0",
+    "@monotykamary/cordis": "^4.0.1"
+  }
+}