@hasna-internal/kai-spill 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/spill/spill/README.md
+README.md: f36dccfa1e6f1f21e80c0b0aa97ee150a0f5fd45
+README.zh.md: 64f0a99bd1cdb10af2bbe0007de802d8ce658b7a

package/README.md

@@ -0,0 +1,42 @@
+# @hasna-internal/kai-spill
+
+English | [中文](README.zh.md)
+
+The **`SpillStore`** (`ctx.spillStore`) defines WHAT a spill backend does — persist a tool's oversized text and return a model-facing locator plus retrieval guidance — without saying HOW.
+
+This package is one third of the spill capability, split so each concern evolves (and swaps) independently:
+
+| Package | Role |
+|---|---|
+| `@hasna-internal/kai-spill` (this) | Service Definition: abstract service + vocabulary types |
+| `@hasna-internal/kai-spill-local` | Service Provider: private session-scoped files on the host filesystem |
+| `@hasna-internal/kai-spill-policy` | Consumer: the tool-result policy that spills oversized final results |
+
+The split mirrors the shell/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI, a database key, or a backend-specific retrieval tool) implements this Service Definition without touching the policy plugin.
+
+## Service API (`ctx.spillStore`)
+
+| Member | Semantics |
+|---|---|
+| `saveText(input)` | Persist `input.content` verbatim; resolves with a `SpillRef` (opaque locator, exact bytes written, and retrieval hint). **Rejects on a real storage failure** (permissions, ENOSPC, backend unavailable) — the caller decides how to degrade. |
+
+Storage is grouped by the request's `owner` session as a save-time namespace; the backend chooses its own private representation and may derive names from — never trust as a path — the caller's `suggestedName`. The seam owns storage only: NO retention policy (that is [`@hasna-internal/kai-output-retention`](../../util/output-retention)), NO tool-result replacement (that is `@hasna-internal/kai-spill-policy`), NO retrieval/search API (the backend's `retrievalHint` tells the model what to do with the locator).
+
+## Vocabulary
+
+`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (locator, bytes, retrievalHint) is the result. `SpillLocator` is [branded](../../util/brand) and rendered to the model as an opaque string — a local path for `dsh-spill-local`, but a future backend may return a URI, key, or command token without changing policy/tool consumers. `SpillOwner.sessionId` is the save-time storage namespace: forked sessions inherit existing locators from the seeded log without copying or re-owning them, and new spills after the fork use the child session id. `SpillSource` records the producing `toolName`, `callId`, and `label` for backend naming and inspection, not access control. See `src/types.ts` for the full contracts.
+
+See the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the design rationale, including why creation belongs to the runtime spill seam rather than the model-facing `write` tool.
+
+## Model Experience
+
+Indirectly, through spill consumers that render a backend locator and retrieval guidance.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **The seam has no retrieval or deletion API** — consumers can only render the backend's locator and guidance; lifecycle and access semantics remain backend-specific.
+- **Storage is not access control** — `SpillOwner` namespaces writes but does not authorize reads of a locator; each backend and retrieval consumer must enforce its own boundary.

package/README.zh.md

@@ -0,0 +1,42 @@
+# @hasna-internal/kai-spill
+
+[English](README.md) | 中文
+
+**`SpillStore`**（`ctx.spillStore`）定义 spill 后端做什么，即持久化某个工具过大的文本，并返回面向模型的定位信息与取回指引；它不规定如何实现。
+
+该包是 spill 能力的三个组成部分之一。拆分后，各项关注点可独立演进和替换：
+
+| 包 | 职责 |
+|---|---|
+| `@hasna-internal/kai-spill`（本包） | Service Definition：抽象服务与词汇类型 |
+| `@hasna-internal/kai-spill-local` | Service Provider：位于宿主文件系统中的私有会话级文件 |
+| `@hasna-internal/kai-spill-policy` | Consumer：对过大最终结果执行 spill 的工具结果策略 |
+
+这种拆分方式与 shell/fs seam 相同。未来的远程或虚拟后端（例如 `spill://…` URI、数据库键或后端专用取回工具）可实现此 Service Definition，无需修改策略插件。
+
+## 服务 API（`ctx.spillStore`）
+
+| 成员 | 语义 |
+|---|---|
+| `saveText(input)` | 逐字保存 `input.content`；成功时返回 `SpillRef`（不透明定位信息、写入的精确字节数和取回指引）。**发生真实存储故障时，调用会以拒绝状态结束**（权限、ENOSPC、后端不可用）；由调用方决定如何降级。 |
+
+存储操作以请求的 `owner` 会话作为保存时命名空间进行分组；后端自行选择私有表示，并可以从调用方的 `suggestedName` 派生名称，但绝不能将其当作可信路径。该 seam 只负责存储：不提供保留策略（由 [`@hasna-internal/kai-output-retention`](../../util/output-retention) 负责），不替换工具结果（由 `@hasna-internal/kai-spill-policy` 负责），也不提供取回/搜索 API（后端的 `retrievalHint` 会告诉模型如何使用定位信息）。
+
+## 词汇
+
+`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource` 记录产生该 spill 的 `toolName`、`callId` 和 `label`，供后端命名和检查使用，不用于访问控制。完整约定见 `src/types.ts`。
+
+设计原理见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
+
+## 模型体验
+
+通过渲染后端定位信息和取回指引的 spill 消费方间接影响模型。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **该 seam 没有取回或删除 API**：消费方只能渲染后端的定位信息与指引；生命周期和访问语义仍由后端自行决定。
+- **存储不等于访问控制**：`SpillOwner` 会区分写入命名空间，但不会授予通过定位信息读取内容的权限；每个后端和取回消费方都必须自行强制执行访问边界。

package/lib/index.js

@@ -0,0 +1,58 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/types.js
+/**
+* Vocabulary for the spill storage Service Definition. Types only — the abstract service
+* lives in `./index.ts`, implementations in sibling packages
+* (`@hasna-internal/kai-spill-local` first).
+*
+* @module @hasna-internal/kai-spill/types
+*/
+/**
+* Brand a string as a {@link SpillLocator}.
+*
+* @param locator The backend-produced locator string to brand.
+* @returns The branded spill locator.
+*/
+function SpillLocator(locator) {
+	return locator;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the spill storage capability seam (`ctx.spillStore`): an abstract service defining WHAT a
+* spill backend does — persist a tool's oversized text and return a model-facing
+* locator plus retrieval guidance — without saying HOW. Implementations
+* subclass {@link SpillStore} and register as the `spillStore` service;
+* `@hasna-internal/kai-spill-local` (host filesystem) is the first.
+*
+* The Service Definition is deliberately minimal: `saveText` and nothing else. It owns NO
+* retention policy (that is `@hasna-internal/kai-output-retention`), NO tool-result
+* replacement (that is `@hasna-internal/kai-spill-policy`), and NO retrieval or
+* search API. The backend supplies the locator and retrieval hint appropriate
+* for its storage substrate.
+*
+* @module @hasna-internal/kai-spill
+*/
+/**
+* Abstract spill storage service. Subclass, implement {@link saveText}, and load
+* the subclass as a plugin — it registers as `ctx.spillStore` (one
+* implementation per context; loading a second throws, cordis' standard
+* duplicate-service behavior).
+*
+* Semantics every implementation must honor:
+* - {@link saveText} persists the FULL `content` verbatim and returns an opaque
+*   locator, exact byte length, and model-facing retrieval guidance.
+* - Storage is scoped by the request's {@link SaveTextSpill.owner} session; the
+*   backend chooses a private (not world-readable) location and a collision-free
+*   name derived from — never equal to — the caller's `suggestedName`.
+* - `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend
+*   unavailable); the caller decides how to degrade (the spill policy treats a
+*   rejection as best-effort and keeps the inline result).
+*/
+var SpillStore = class extends Service {
+	constructor(ctx) {
+		super(ctx, "spillStore");
+	}
+};
+//#endregion
+export { SpillLocator, SpillStore, SpillStore as default };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-spill`.
+* @module @hasna-internal/kai-spill/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-spill";
+/** Cordis companion plugin name. */
+const name = "spill-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+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,51 @@
+/**
+ * Service Definition for the spill storage capability seam (`ctx.spillStore`): an abstract service defining WHAT a
+ * spill backend does — persist a tool's oversized text and return a model-facing
+ * locator plus retrieval guidance — without saying HOW. Implementations
+ * subclass {@link SpillStore} and register as the `spillStore` service;
+ * `@hasna-internal/kai-spill-local` (host filesystem) is the first.
+ *
+ * The Service Definition is deliberately minimal: `saveText` and nothing else. It owns NO
+ * retention policy (that is `@hasna-internal/kai-output-retention`), NO tool-result
+ * replacement (that is `@hasna-internal/kai-spill-policy`), and NO retrieval or
+ * search API. The backend supplies the locator and retrieval hint appropriate
+ * for its storage substrate.
+ *
+ * @module @hasna-internal/kai-spill
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { SaveTextSpill, SpillRef } from './types.ts';
+export { SpillLocator } from './types.ts';
+export type { SaveTextSpill, SpillOwner, SpillRef, SpillSource } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        spillStore: SpillStore;
+    }
+}
+/**
+ * Abstract spill storage service. Subclass, implement {@link saveText}, and load
+ * the subclass as a plugin — it registers as `ctx.spillStore` (one
+ * implementation per context; loading a second throws, cordis' standard
+ * duplicate-service behavior).
+ *
+ * Semantics every implementation must honor:
+ * - {@link saveText} persists the FULL `content` verbatim and returns an opaque
+ *   locator, exact byte length, and model-facing retrieval guidance.
+ * - Storage is scoped by the request's {@link SaveTextSpill.owner} session; the
+ *   backend chooses a private (not world-readable) location and a collision-free
+ *   name derived from — never equal to — the caller's `suggestedName`.
+ * - `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend
+ *   unavailable); the caller decides how to degrade (the spill policy treats a
+ *   rejection as best-effort and keeps the inline result).
+ */
+export declare abstract class SpillStore extends Service {
+    constructor(ctx: Context);
+    /**
+     * Persist `input.content` to a session-scoped spill artifact.
+     * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
+     * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
+     */
+    abstract saveText(input: SaveTextSpill): Promise<SpillRef>;
+}
+export default SpillStore;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-spill`.
+ * @module @hasna-internal/kai-spill/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "spill-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/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Vocabulary for the spill storage Service Definition. Types only — the abstract service
+ * lives in `./index.ts`, implementations in sibling packages
+ * (`@hasna-internal/kai-spill-local` first).
+ *
+ * @module @hasna-internal/kai-spill/types
+ */
+import type { Branded } from '@hasna-internal/kai-brand';
+import type { CallId } from '@hasna-internal/kai-llm';
+import type { SessionId } from '@hasna-internal/kai-session';
+/**
+ * Opaque model-facing handle for one spilled artifact. A local backend may use a
+ * filesystem path; a remote or database backend may use a URI or key. Consumers
+ * render it with {@link SpillRef.retrievalHint}, but do not parse it.
+ */
+export type SpillLocator = Branded<'SpillLocator'>;
+/**
+ * Brand a string as a {@link SpillLocator}.
+ *
+ * @param locator The backend-produced locator string to brand.
+ * @returns The branded spill locator.
+ */
+export declare function SpillLocator(locator: string): SpillLocator;
+/**
+ * Save-time storage namespace for a spilled artifact. The session id lets a
+ * backend group storage under the producing session, but the returned
+ * {@link SpillLocator} is the model-facing handle. Forked sessions inherit
+ * locators already present in the seeded log; those artifacts are not copied or
+ * re-owned, and spills produced after the fork use the child session id.
+ */
+export interface SpillOwner {
+    sessionId: SessionId;
+}
+/**
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
+ * filename and inspection. Not interpreted for access control; purely
+ * descriptive.
+ */
+export interface SpillSource {
+    /** The tool whose result was spilled (e.g. `web_fetch`). */
+    toolName: string;
+    /** The model-issued call id the result belongs to. */
+    callId: CallId;
+    /** A short human label for the artifact (e.g. `result`). */
+    label: string;
+}
+/** One request to persist text to a spill artifact. */
+export interface SaveTextSpill {
+    owner: SpillOwner;
+    source: SpillSource;
+    /**
+     * A caller-suggested base name (e.g. `web_fetch.txt`). The backend sanitizes
+     * it to a single safe path segment before use — it is a hint, never a path.
+     */
+    suggestedName: string;
+    /** The full text to persist (UTF-8). */
+    content: string;
+}
+/** A saved spill artifact: its locator, byte length, and backend-specific retrieval guidance. */
+export interface SpillRef {
+    locator: SpillLocator;
+    bytes: number;
+    retrievalHint: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hasna-internal/kai-spill",
+  "description": "Abstract spill storage seam (ctx.spillStore) for the DeepSeek Harness — save oversized tool text and return a retrieval locator",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/spill/spill"
+  },
+  "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-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2"
+  }
+}