@hasna-internal/kai-session-checkpoint-policy 0.1.1-rc.2

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/session-checkpoint-policy/README.md
+README.md: 01ed3c694967b1a86245d01b9d9f7eecd1193348
+README.zh.md: e2c197c0cc1d942a045c1ea22c1fb257f6e4059d

package/README.md

@@ -0,0 +1,45 @@
+# dsh-session-checkpoint-policy
+
+English | [中文](README.zh.md)
+
+Semantic durability policy for persisted agents. It checkpoints the event-sourced session before a model adapter receives a request, before a top-level tool body may produce an external side effect, and at each `agent/pre-step` boundary so the preceding response and ordered tool results are durable before the next request.
+
+## Plugin (namespace: `session-checkpoint-policy`)
+
+This zero-config function plugin consumes `ctx.sessions`, `ctx.llm`, `ctx.tools`, and the presence of `ctx.sessionPersistence`. Load it beside one persistence backend:
+
+```yaml
+- id: session-persistence
+  name: '@hasna-internal/kai-session-persistence-jsonl'
+
+- id: session-checkpoints
+  name: '@hasna-internal/kai-session-checkpoint-policy'
+```
+
+Persistence and checkpoint scheduling are intentionally separate Cordis plugins. A persistence backend starts bounded background batches for `session/event` appends and makes each requested `session/flush` an immediate quiescence barrier; this policy chooses the request, tool-dispatch, and next-step barriers. Loading a backend without this policy is valid, but a crash may lose events still inside the configured batching window or an outstanding write. First-party persisted apps and runtimes mount both plugins explicitly; a specialized deployment may deliberately omit or replace the policy.
+
+The policy wraps `llm/stream` lazily, so the downstream stream is not constructed until the live session's buffered request events are durable. It wraps `tools/execute` after pre-execute policy and guards; a top-level tool body runs only after its recorded call is durable. If cancellation lands while that flush is pending, the wrapper returns the canonical `ABORTED_BEFORE_DISPATCH` result without entering the tool body. Nested tool dispatches reuse the outer model-visible call's checkpoint. `agent/pre-step` persists the preceding response/result batch before request derivation.
+
+Checkpoint rejection is fail-closed at the model and tool boundaries: neither the adapter nor the top-level tool body runs. A step-boundary rejection fails the turn before another request starts. Concurrent tool checkpoints share the session store's serialized persistence drain and cannot duplicate sequence numbers.
+
+## Model Experience
+
+### Interrupted calls
+
+#### What the model sees
+
+The plugin adds no prompt or tool schema. A hard crash after a tool checkpoint but before its result leaves a durable unmatched call; session recovery supplies the model-visible `TOOL_OUTCOME_UNKNOWN` result owned by `dsh-session`. The message permits retry for read-only or idempotent work and requires state verification or user confirmation for calls that may have side effects.
+
+#### Token effect
+
+Successful checkpoints add no tokens and do not change the request. Recovery adds one short tool-result message to balance the interrupted transcript.
+
+#### KV Cache effect
+
+The repair result is appended after the reusable prefix, so it does not invalidate earlier cache entries.
+
+## Known Limitations and Deferred Work
+
+- The policy durably records execution intent, not generic exactly-once effects. Side-effecting tools should forward `exec.callId` as an idempotency key when their provider supports one.
+- Streaming `assistant/chunk` events have no per-chunk checkpoint. Bounded background batches normally persist them before the next semantic checkpoint, but a hard crash may lose the current in-memory batch or outstanding write.
+- A persisted call without a result cannot prove whether its external effect completed. Recovery therefore records an unknown outcome instead of retrying automatically.

package/README.zh.md

@@ -0,0 +1,45 @@
+# dsh-session-checkpoint-policy
+
+[English](README.md) | 中文
+
+已持久化的 agent（智能体）的语义持久性策略。它会在模型适配器收到请求前、顶层工具正文可产生外部副作用前，以及每个 `agent/pre-step` 边界为事件溯源会话创建检查点，使前一响应与有序工具结果在下一个请求前已持久化。
+
+## 插件（命名空间：`session-checkpoint-policy`）
+
+该零配置函数插件消费 `ctx.sessions`、`ctx.llm`、`ctx.tools` 以及 `ctx.sessionPersistence` 的存在性。将其与一个持久化后端一起加载：
+
+```yaml
+- id: session-persistence
+  name: '@hasna-internal/kai-session-persistence-jsonl'
+
+- id: session-checkpoints
+  name: '@hasna-internal/kai-session-checkpoint-policy'
+```
+
+持久化与检查点调度刻意拆分为独立 Cordis 插件。持久化后端会为追加的 `session/event` 启动有界后台批次，并把每个已请求的 `session/flush` 变成即时完全停稳屏障；该策略选择请求、工具分派和下一步骤屏障。不带此策略加载后端是有效的，但崩溃可能丢失仍位于已配置批处理窗口内的事件，或尚未完成的写入。第一方持久化应用和运行时显式挂载两个插件；专用部署可以刻意省略或替换策略。
+
+策略延迟包装 `llm/stream`，因此下游流只会在活动会话中缓冲的请求事件已持久化后构造。它在预执行策略和防护机制之后包装 `tools/execute`；只有在已记录调用已持久化后，顶层工具正文才会运行。如果取消在 flush 等待期间到达，包装层会返回规范的 `ABORTED_BEFORE_DISPATCH` 结果，不进入工具正文。嵌套工具分派重用外层模型可见调用的检查点。`agent/pre-step` 在派生请求前持久化前一响应/结果批次。
+
+在模型和工具边界，检查点被拒绝时会按失败即阻止原则处理：适配器和顶层工具正文都不运行。步骤边界处的检查点被拒绝会在另一个请求开始前使轮次失败。并发工具检查点共享会话存储的串行持久化排空流程，不会产生重复的序列号。
+
+## 模型体验
+
+### 中断调用
+
+#### 模型看到的内容
+
+插件不添加提示词或工具 schema。工具检查点后、结果前的硬崩溃会留下持久的未匹配调用；会话恢复会提供模型可见的 `TOOL_OUTCOME_UNKNOWN` 结果，该结果由 `dsh-session` 负责。该消息允许重试只读或幂等工作，并要求对可能有副作用的调用验证状态或请求用户确认。
+
+#### Token 影响
+
+成功检查点不添加 token，也不改变请求。恢复会添加一条短工具结果消息，以平衡中断的 transcript（文本记录）。
+
+#### KV Cache 影响
+
+修复结果追加在可重用前缀之后，因此不会使较早的缓存条目失效。
+
+## 已知限制与暂缓事项
+
+- 该策略以持久方式记录执行意图，而非为通用副作用提供恰好一次保证。当提供方支持时，有副作用的工具应将 `exec.callId` 作为幂等键转发。
+- 流式 `assistant/chunk` 事件没有逐分片检查点。有界后台批次通常会在下一个语义检查点之前将其持久化，但硬崩溃可能丢失当前内存批次或尚未完成的写入。
+- 已持久化的调用没有结果时，无法证明其外部副作用是否完成。因此，恢复会记录未知结果，而不是自动重试。

package/lib/index.js

@@ -0,0 +1,78 @@
+import { TOOL_ABORTED_BEFORE_DISPATCH } from "@hasna-internal/kai-tools";
+//#region lib/types/index.js
+/**
+* Semantic durability checkpoints for model requests, top-level tool dispatch,
+* and completed agent steps.
+* @module @hasna-internal/kai-session-checkpoint-policy
+*/
+/** Cordis plugin name used by Loader diagnostics. */
+const name = "session-checkpoint-policy";
+/** Services whose request, tool, session, and persistence boundaries this policy joins. */
+const inject = [
+	"llm",
+	"sessionPersistence",
+	"sessions",
+	"tools"
+];
+/**
+* Delay construction of the downstream model stream until the complete logged
+* request prefix is durable. A checkpoint rejection prevents adapter dispatch.
+*
+* @param ctx - plugin context that owns the session store.
+* @param session - live session named by the model request.
+* @param next - downstream `llm/stream` chain.
+* @returns a stream that checkpoints before requesting its first chunk.
+*/
+function afterCheckpoint(ctx, session, next) {
+	return (async function* () {
+		await ctx.sessions.flush(session);
+		yield* next();
+	})();
+}
+/** Materialize the canonical result for a call cancelled before tool dispatch. */
+function abortedBeforeDispatchResult() {
+	return {
+		content: [{
+			type: "text",
+			text: "Error: tool call aborted before dispatch"
+		}],
+		isError: true,
+		error: {
+			message: "tool call aborted before dispatch",
+			info: {
+				name: "AbortError",
+				code: TOOL_ABORTED_BEFORE_DISPATCH
+			}
+		}
+	};
+}
+/**
+* Install semantic checkpoint listeners. Loop-built model calls checkpoint the
+* logged request before adapter dispatch; top-level tool calls checkpoint their
+* recorded call before the tool body; the next request boundary checkpoints
+* the preceding response/result batch. Nested tool dispatches reuse the durable outer call.
+*
+* Checkpoint failures are fail-closed at the model and tool side-effect
+* boundaries: the downstream adapter or tool body is not invoked.
+*
+* @param ctx - plugin context that owns the listeners.
+*/
+function apply(ctx) {
+	ctx.on("llm/stream", (options, next) => {
+		if (options.sessionId === void 0) return next();
+		const session = ctx.sessions.get(options.sessionId);
+		return session === void 0 ? next() : afterCheckpoint(ctx, session, next);
+	});
+	ctx.on("tools/execute", async (exec, next) => {
+		if (exec.agent === void 0 || exec.parent !== void 0) return next();
+		await ctx.sessions.flush(exec.agent.session);
+		if (exec.signal.aborted) return abortedBeforeDispatchResult();
+		return next();
+	});
+	ctx.on("agent/pre-step", async ({ agent }, next) => {
+		await ctx.sessions.flush(agent.session);
+		return next();
+	});
+}
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-session-checkpoint-policy`.
+* @module @hasna-internal/kai-session-checkpoint-policy/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-session-checkpoint-policy";
+/** Cordis companion plugin name. */
+const name = "session-checkpoint-policy-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: checkpoint ordering is enforced at the intercepted waterfall and
+* persistence seams; this stateless policy owns no independent mutable relation.
+*/
+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,23 @@
+/**
+ * Semantic durability checkpoints for model requests, top-level tool dispatch,
+ * and completed agent steps.
+ * @module @hasna-internal/kai-session-checkpoint-policy
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis plugin name used by Loader diagnostics. */
+export declare const name = "session-checkpoint-policy";
+/** Services whose request, tool, session, and persistence boundaries this policy joins. */
+export declare const inject: string[];
+/**
+ * Install semantic checkpoint listeners. Loop-built model calls checkpoint the
+ * logged request before adapter dispatch; top-level tool calls checkpoint their
+ * recorded call before the tool body; the next request boundary checkpoints
+ * the preceding response/result batch. Nested tool dispatches reuse the durable outer call.
+ *
+ * Checkpoint failures are fail-closed at the model and tool side-effect
+ * boundaries: the downstream adapter or tool body is not invoked.
+ *
+ * @param ctx - plugin context that owns the listeners.
+ */
+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 `@hasna-internal/kai-session-checkpoint-policy`.
+ * @module @hasna-internal/kai-session-checkpoint-policy/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-checkpoint-policy-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,57 @@
+{
+  "name": "@hasna-internal/kai-session-checkpoint-policy",
+  "description": "Semantic session durability checkpoints before model requests and tool side effects",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-checkpoint-policy"
+  },
+  "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": {
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session-persistence": "^0.1.1-rc.2",
+    "@hasna-internal/kai-tools": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-agent-loop": "^0.1.1-rc.2",
+    "@hasna-internal/kai-agent-loop-testkit": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session-persistence": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session-persistence-jsonl": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-tools": "^0.1.1-rc.2",
+    "@hasna-internal/kai-system-prompt": "^0.1.1-rc.2"
+  }
+}