@qilin-agent/fs 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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,58 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/fs/fs/README.md
+/:
+  en: a94eb1470c498a2c
+  zh: cdd5faa0a8fcb562
+/qilin-agent-fs:
+  en: 36ec08f75c970d6b
+  zh: 1cad13ef88ce2063
+/qilin-agent-fs/summary:
+  en: d86cd3418ce07313
+  zh: e8a6d9e3e530e5ad
+/qilin-agent-fs/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-fs/use-this-package:
+  en: c935aeef50118bbc
+  zh: 218ca6a49545668f
+/qilin-agent-fs/use-this-package/choosing-and-mounting-a-backend:
+  en: 6644d749bb66bd8d
+  zh: 929dcc5cd4ee70ea
+/qilin-agent-fs/use-this-package/what-the-service-lets-you-do:
+  en: 7362a6df4c2f9b60
+  zh: f1120bcaada1037d
+/qilin-agent-fs/understand-the-implementation:
+  en: 7e13d669ecc96d59
+  zh: b5fe7ae65812d926
+/qilin-agent-fs/understand-the-implementation/design-philosophy:
+  en: c4dcad50dc90db2c
+  zh: 54775c7bcdc24d86
+/qilin-agent-fs/understand-the-implementation/source-map:
+  en: 038de0a4127c1ff5
+  zh: 192947b527c3f258
+/qilin-agent-fs/understand-the-implementation/how-a-call-flows:
+  en: 9272eec1c2b30667
+  zh: 1e5c82060097fd1e
+/qilin-agent-fs/understand-the-implementation/the-fs-policy-events:
+  en: 64bb44beb5e68508
+  zh: 306dafa5e3fe39af
+/qilin-agent-fs/understand-the-implementation/invariants:
+  en: 15b98bc9800b6eae
+  zh: 434d9dd05fa1a332
+/qilin-agent-fs/further-exploration:
+  en: bc28a173da8fd4db
+  zh: 9e981417d86b72a5
+/qilin-agent-fs/model-experience:
+  en: cd1c5414ab00174f
+  zh: 6c7ce64b9e618f93
+/qilin-agent-fs/model-experience/kv-cache-effect:
+  en: 40294c1c31b74824
+  zh: 0857e9b4dd363e0a
+/qilin-agent-fs/known-limitations-and-deferred-work:
+  en: be13bf5e7c376d92
+  zh: ff95ba8f51eb4dcc
+/qilin-agent-fs/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+---
+description: "The ctx.fs filesystem service contract for deployments choosing or mounting a filesystem backend and developers implementing one."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/fs
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `qilin-fs` when an application needs consistent filesystem operations across host, confined, or remote execution environments. It lets consumers resolve stable file identities, map shared host files where supported, perform bounded text and byte reads, list directories, watch targets, apply atomic text writes and literal edits, and remove, move, or create directories. Version guards are optional, so a backend works without policy enforcement; callers can supply a guard to reject a mutation after the file changes. Choose `fs-local` or `fs-sandbox` for host execution. Model-facing filesystem tools are provided separately by `qilin-tool-fs`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+You rarely load `qilin-fs` directly: you mount a backend that registers as `ctx.fs`, then either call the service from your own plugin or let the `qilin-tool-fs` tools call it for you. This page serves the two audiences that do touch it — deployments choosing a backend, and developers implementing or consuming the contract.
+
+### Choosing and mounting a backend
+
+Pick [`fs-local`](../fs-local/README.md) for ordinary host files or [`fs-sandbox`](../fs-sandbox/README.md) when a session's mutations must be confined to its workspace and temp roots. Mounting any backend populates `ctx.fs`; swapping backends changes nothing for the policy plugin, the tools, or the tool schemas. A composition that mounts no backend has no `ctx.fs` at all, and the tools fail at registration.
+
+### What the service lets you do
+
+Through `ctx.fs` you can resolve any path to a stable target identity, read a whole text file or stream it in chunks, read raw bytes up to an explicit cap, list one directory level, atomically create or replace a file, apply a literal text edit atomically, remove a file or a directory, move or rename an entry inside one backend, and create a directory (with its missing parents when asked). The version guard on file writes and edits is optional: omit it for unconditional create-or-overwrite, or supply it to fail when the file changed since you last observed it. Read, listing, and mutation failures are typed `FsError`s with stable codes such as `FS_NOT_FOUND`, `FS_STALE_VERSION`, or `FS_AMBIGUOUS_EDIT`, so callers branch on the code, never on message text.
+
+`remove`, `move`, and `createDirectory` keep that vocabulary: an absent target is `FS_NOT_FOUND`, a directory removed without `recursive` while it still holds entries is `FS_NOT_EMPTY`, and a create or a move onto an entry that already exists is `FS_EXISTS`. A backend that cannot perform the move at all — a rename across filesystems, for instance — reports `FS_IO_ERROR` instead of copying the content.
+
+`watch(target, changed, signal)` reports invalidations for one file or a directory's direct entries. It resolves once observation is ready with an asynchronous close function that the caller must await. The signal cancels initialization; unsupported providers reject without polling.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the contract and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The contract is built on one separation and three commitments:
+
+- **Contract over mechanism.** The service names what a storage layer can do — resolve, stat, read, list, watch, write, edit, remove, move, createDirectory — and never how it stores bytes. Backends own target identity, execution-world coordinates, decoding, binary rejection, and atomicity.
+- **Policy stays off the base class.** Observed-state, read-before-edit, and version-guarded mutations are a plugin's job (`qilin-fs-observation-policy`), added by supplying the optional guard — so a sandboxed or remote backend inherits no model-facing observation policy.
+- **`editText` stays on the seam.** Version check, literal match, and atomic rewrite share one critical section, so error attribution and one-wins/one-stale concurrency stay correct; a remote backend may implement it as a native compare-and-edit.
+- **Bounds live at this seam.** `readBytes` requires `maxBytes` and fails with `FS_TOO_LARGE` rather than truncating, so no backend ever buffers an unbounded file. `readByteRange` is bounded by its window instead: a backend transfers at most the requested `length` beyond the prefix it skips, so the caller's cap on `length` is the guard.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Service definition: the abstract `FileSystem` class, the `ctx.fs` declaration, and the `fs/*` event vocabulary |
+| [`src/types.ts`](src/types.ts) | Vocabulary: `FsTarget`/`FsTargetKey`, `FsVersion`, `FsObservation`, `FsWriteIntent`, `FsRemoveOutcome`, `FsMoveOutcome`, `FsError` and its codes |
+
+### How a call flows
+
+Every ordinary operation starts with `resolve(path, { cwd })`, which produces a stable `FsTarget` (an opaque `targetKey` plus a `displayPath` for model/UI output); the same file reached through different paths yields the same key. `processPathFromHostPath(hostPath)` separately maps an absolute host file into this execution world when the backend shares or explicitly maps it, and otherwise returns `undefined`. Reads then go `stat` → `readText`/`streamText`/`readBytes`/`readByteRange`, listings go `listDir` (whose entries report the resolved type plus a `symlink` flag when the listed name itself is a link), and mutations go through one per-target critical section: the optional guard is checked, the new content is applied, and the result is published atomically. A move holds the critical section of both ends, taken in a fixed key order, so two moves touching the same pair of targets serialize instead of deadlocking; the other two take the single lock of the target they touch.
+
+### The `fs/*` policy events
+
+The package declares three events so the emitter (`qilin-tool-fs`) and the policy listener (`qilin-fs-observation-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls: the first listener decides outright and never calls `next()`. `fs/observed` is a fire-and-forget recording event carrying an `FsObservation` — present with a version, or confirmed absent. The events carry only `qilin-fs` vocabulary plus an opaque `object` actor.
+
+### Invariants
+
+- `targetKey` and `version` are branded opaque ids: consumers must not parse or interpret them; only `displayPath` is for model/UI output.
+- Read, listing, and mutation failures are typed `FsError`s with stable codes, never ad-hoc message strings; watch initialization may reject with an ordinary exception.
+- The seam arms no I/O deadline; cancellation is an optional per-primitive `AbortSignal`.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the exhaustive contract to the backends and consumers built on it.
+
+- [Filesystem subsystem](../../../docs/subsystems/filesystem.md) — exhaustive provider contract, policy events, and error taxonomy.
+- [fs-local](../fs-local/README.md) — the host-filesystem backend implementing this contract.
+- [fs-sandbox](../fs-sandbox/README.md) — the sandbox-enforcing backend implementing this contract.
+- [tool-fs](../tool-fs/README.md) — the model-facing tools that consume `ctx.fs`.
+- [fs-observation-policy](../fs-observation-policy/README.md) — the policy plugin that guards mutations through the `fs/*` events.
+- [Capability seams note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) — why the filesystem stack splits into contract, provider, policy, and tools.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through `qilin-tool-fs`, which renders provider text and errors as bounded, retained filesystem tool results.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the contract is a poor fit or needs special operational care. They are current package constraints, not a general filesystem comparison or a task backlog.
+
+- **Text-only mutations by contract** — text reads and both mutations reject binary or non-UTF-8 content with `FS_NOT_TEXT`; `readBytes` and `readByteRange` are the raw-byte primitives, and binary-safe mutations remain deferred.
+- **No copy** — a move stays inside one backend and never copies across filesystems, and `listDir` still lists a single level, with globbing, pagination, and search out of scope ([directory-listing note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)).
+- **No I/O deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive ([fs family stance](../README.md)).
+- **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,129 @@
+---
+description: "`ctx.fs` 文件系统服务约定：面向选择或挂载文件系统后端的部署方，以及实现后端的开发者。"
+kind: "package-reference"
+---
+
+# @qilin-agent/fs
+
+[English](README.md) | 中文
+
+## 概述
+
+应用需要在宿主、受限或远程执行环境中使用一致的文件系统操作时，选择 `qilin-fs`。消费方可以解析稳定的文件身份、在受支持时映射共享宿主文件、执行有界的文本与字节读取、列出目录、监听目标、原子地写入文本及执行字面量编辑，以及删除、移动或新建目录。版本防护是可选的，因此后端无需策略强制也能工作；调用方可以提供防护，在文件变化后拒绝变更。在宿主执行时选择 `fs-local` 或 `fs-sandbox`。面向模型的文件系统工具由 `qilin-tool-fs` 单独提供。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+你很少直接加载 `qilin-fs`：你挂载一个注册为 `ctx.fs` 的后端，然后从自己的插件调用该服务，或让 `qilin-tool-fs` 工具替你调用。本页服务于确实接触它的两类读者——选择后端的部署方，以及实现或消费该约定的开发者。
+
+### 选择并挂载后端
+
+普通宿主文件选择 [`fs-local`](../fs-local/README.zh.md)，会话变更必须限制在工作区与临时根目录内时选择 [`fs-sandbox`](../fs-sandbox/README.zh.md)。挂载任一后端都会填充 `ctx.fs`；更换后端不会改变策略插件、工具或工具 schema。未挂载任何后端的组合就没有 `ctx.fs`，工具会在注册时失败。
+
+### 服务能做什么
+
+通过 `ctx.fs`，你可以把任意路径解析为稳定的目标身份、完整读取或分片流式读取文本文件、按显式上限读取原始字节、列出一层目录、原子地创建或替换文件、原子地应用字面量文本编辑、删除文件或目录、在同一后端内移动或重命名一个条目，以及新建目录（按需连同缺失的父目录）。文件写入与编辑上的版本防护是可选的：省略它即无条件创建或覆盖，提供它则在文件自上次观察以来发生变化时失败。读取、列出与变更操作的失败使用携带稳定错误码（如 `FS_NOT_FOUND`、`FS_STALE_VERSION`、`FS_AMBIGUOUS_EDIT`）的类型化 `FsError`，调用方依据错误码分支，绝不解析消息文本。
+
+`remove`、`move` 与 `createDirectory` 沿用同一套词汇：目标不存在是 `FS_NOT_FOUND`；未带 `recursive` 而目录仍有条目时删除是 `FS_NOT_EMPTY`；新建或移动落在一个已存在的条目上是 `FS_EXISTS`。后端根本无法执行该移动时——例如跨文件系统重命名——报告 `FS_IO_ERROR`，而不是改为复制内容。
+
+`watch(target, changed, signal)` 报告单个文件或目录直接子项的失效通知。观察就绪后，它返回调用方必须等待完成的异步关闭函数。signal 取消初始化；不支持监听的提供方直接拒绝，不使用轮询。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释约定背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+该约定建立在一个分离与三项承诺之上：
+
+- **约定高于机制。** 服务只命名存储层能做什么——解析、stat、读取、列出、监听、写入、编辑、删除、移动、新建目录——绝不规定如何存储字节。后端拥有目标身份、执行世界坐标、解码、二进制拒绝与原子性。
+- **策略不放在基类上。** 已观察状态、编辑前读取与版本防护的变更是插件（`qilin-fs-observation-policy`）的职责，通过提供可选防护来添加——因此沙箱化或远程后端不会继承任何面向模型的观察策略。
+- **`editText` 留在 seam 上。** 版本校验、字面量匹配与原子重写共享同一个临界区，错误归因与一方胜出/一方陈旧的并发语义因此保持正确；远程后端也可以将其实现为原生比较并编辑操作。
+- **界限制在此 seam 上。** `readBytes` 要求 `maxBytes`，并以 `FS_TOO_LARGE` 失败而不是截断，因此任何后端都不会无界缓冲文件。`readByteRange` 则以窗口为界：后端最多传输所请求的 `length` 字节（外加为到达 `offset` 而跳过的前缀），因此由调用方对 `length` 的上限承担防护。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 服务定义：抽象 `FileSystem` 类、`ctx.fs` 声明与 `fs/*` 事件词汇 |
+| [`src/types.ts`](src/types.ts) | 词汇：`FsTarget`/`FsTargetKey`、`FsVersion`、`FsObservation`、`FsWriteIntent`、`FsRemoveOutcome`、`FsMoveOutcome`、`FsError` 及其错误码 |
+
+### 调用流程
+
+每个普通操作都以 `resolve(path, { cwd })` 开始，它产生稳定的 `FsTarget`（不透明 `targetKey` 加用于模型/UI 输出的 `displayPath`）；经不同路径到达同一文件会产生相同 key。`processPathFromHostPath(hostPath)` 在后端共享或显式映射宿主文件时，单独把绝对宿主文件映射进此执行世界，否则返回 `undefined`。读取随后执行 `stat` → `readText`/`streamText`/`readBytes`/`readByteRange`，列出执行 `listDir`（条目报告解析后的类型，名字本身是链接时另带 `symlink` 标志），变更则经过每个目标一个临界区：先检查可选防护，应用新内容，再原子发布结果。移动会同时持有两端的临界区，并按固定的 key 顺序取锁，因此触碰同一对目标的两个移动会串行而不是死锁；另外两个只取自己所触目标的单把锁。
+
+### `fs/*` 策略事件
+
+本包声明三个事件，使发出方（`qilin-tool-fs`）与策略监听器（`qilin-fs-observation-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 与 `fs/edit-intent` 是单槽决策 waterfall（瀑布式事件）：第一个监听器直接决策，绝不调用 `next()`。`fs/observed` 是发后即忘的记录事件，携带 `FsObservation`——存在并带版本，或确认缺失。事件只携带 `qilin-fs` 词汇和一个不透明 `object` 参与者。
+
+### 不变式
+
+- `targetKey` 与 `version` 是带品牌的不透明 id：消费方不得解析或解释它们；只有 `displayPath` 用于模型/UI 输出。
+- 读取、列出与变更操作的失败是携带稳定错误码的类型化 `FsError`，绝不是临时拼写的消息字符串；监听初始化可以用普通异常拒绝。
+- 该 seam 不设 I/O deadline；取消是每个原语上可选的 `AbortSignal`。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从穷尽式约定逐步进入构建于其上的后端与消费方。
+
+- [文件系统子系统](../../../docs/subsystems/filesystem.zh.md)——穷尽式提供方约定、策略事件与错误分类体系。
+- [fs-local](../fs-local/README.zh.md)——实现该约定的宿主文件系统后端。
+- [fs-sandbox](../fs-sandbox/README.zh.md)——实现该约定的沙箱强制后端。
+- [tool-fs](../tool-fs/README.zh.md)——消费 `ctx.fs` 的面向模型工具。
+- [fs-observation-policy](../fs-observation-policy/README.zh.md)——通过 `fs/*` 事件防护变更的策略插件。
+- [能力 seam 笔记](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)——文件系统栈为何拆分为约定、提供方、策略与工具。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过 `qilin-tool-fs` 间接产生影响；该消费方把提供方文本和错误渲染为有界且保留的文件系统工具结果。
+
+#### KV Cache 影响
+
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明该约定何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用文件系统对比或任务积压。
+
+- **变更操作约定只支持文本**：文本读取和两个变更操作都以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；`readBytes` 与 `readByteRange` 是原始字节原语，二进制安全的变更操作仍延期。
+- **没有复制**：移动只在同一后端内进行，绝不跨文件系统复制内容；`listDir` 仍然只列出一层，glob、分页与搜索不在范围内（见[目录列出笔记](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)）。
+- **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见[fs 能力族立场](../README.zh.md)）。
+- **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,98 @@
+import { Service } from "@qilin-agent/kylin";
+import { HarnessError } from "@qilin-agent/llm";
+//#region lib/types/types.js
+/**
+* Vocabulary for the filesystem Service Definition (`ctx.fs`): the opaque target/version
+* identities, the metadata `stat` returns, the write-intent and outcome shapes, the
+* literal-edit request/outcome, and the typed error taxonomy.
+* @module @qilin-agent/fs/types
+*/
+/**
+* Brand a string as an {@link FsTargetKey}. For backend use only — a consumer
+* never manufactures a key, it receives one from `resolve()`.
+* @param key - the backend's raw key string (the local backend passes a realpath).
+* @returns the same string, branded; no validation is performed.
+*/
+function FsTargetKey(key) {
+	return key;
+}
+/**
+* Brand a string as an {@link FsVersion}. For backend use only — a consumer
+* never manufactures a version, it receives one from `stat`/write/edit outcomes.
+* @param v - the backend's raw version string.
+* @returns the same string, branded; no validation is performed.
+*/
+function FsVersion(v) {
+	return v;
+}
+/**
+* Typed filesystem error. Extends {@link HarnessError} so it carries a stable
+* {@link FsErrorCode} and chains `cause`. `qilin-fs` owns this vocabulary so
+* backends and the policy layer raise the same codes instead of each inventing
+* message strings.
+*/
+var FsError = class extends HarnessError {
+	code;
+	constructor(message, code, options) {
+		super(message, code, options);
+		this.code = code;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Filesystem Service Definition for one execution world. Backends own stable target
+* identity, process paths and file URIs, containment, text reads, decoding,
+* binary rejection, and atomic mutations. Read windows and
+* observed-state policy stay in consumer and policy plugins; `editText`
+* remains here so version check, literal match, and rewrite share one critical
+* section.
+* @module @qilin-agent/fs
+*/
+/**
+* Abstract filesystem provider. Targets must preserve identity across aliases;
+* reads expose regular UTF-8 text or typed errors, listings are stable and
+* content-free, and mutations are atomic. Optional guards add stale protection
+* without changing the unguarded provider contract.
+*/
+var FileSystem = class extends Service {
+	constructor(ctx) {
+		super(ctx, "fs");
+	}
+	/**
+	* Observe one file or a directory's direct entries in this provider's execution world.
+	* @param target - resolved file or directory, including an absent path to observe for creation.
+	* @param changed - invalidation callback; errors can be reported during or after initialization.
+	* @param signal - cancels watcher initialization; the caller closes an initialized watcher.
+	* @returns a promise resolving once observation is active, with an asynchronous close function.
+	* @throws when the provider does not support watching or cannot initialize the watcher.
+	*/
+	watch(target, changed, signal) {
+		signal.throwIfAborted();
+		return Promise.reject(new FsError("Filesystem watching is not supported by this provider.", "FS_IO_ERROR"));
+	}
+	/**
+	* The sandbox mode this backend enforces on mutations BY DEFAULT, or
+	* `undefined` when it does not confine at all — the capability fact the tool
+	* layer reads to advertise the escalation fields honestly (mirrors
+	* `ShellExecutor.sandboxMode`). The base class and the bare local backend
+	* report `undefined`; a sandboxing backend (`@qilin-agent/fs-sandbox`)
+	* overrides it with the deployment default. A session override may make the
+	* effective mode narrower or wider, so strict escalation widening is checked
+	* per call rather than encoded in this default-relative fact.
+	* @returns the configured default mode of a sandboxing backend; `undefined`
+	*   for a backend that never confines.
+	*/
+	get sandboxMode() {}
+	/**
+	* Map an absolute path from the harness host into this filesystem's
+	* execution world when both paths identify the same file. The base provider
+	* exposes no mapping; host-backed or explicitly shared backends override it.
+	* @param hostPath - absolute path in the harness host filesystem.
+	* @returns the process path for the same file, or undefined when this
+	*   execution world cannot read that host file.
+	*/
+	processPathFromHostPath(hostPath) {}
+};
+//#endregion
+export { FileSystem, FileSystem as default, FsError, FsTargetKey, FsVersion };

package/lib/types/index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Filesystem Service Definition for one execution world. Backends own stable target
+ * identity, process paths and file URIs, containment, text reads, decoding,
+ * binary rejection, and atomic mutations. Read windows and
+ * observed-state policy stay in consumer and policy plugins; `editText`
+ * remains here so version check, literal match, and rewrite share one critical
+ * section.
+ * @module @qilin-agent/fs
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import type { SandboxExecutionPolicy, SandboxMode } from '@qilin-agent/sandbox';
+import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsObservation, FsMoveOutcome, FsRemoveOutcome, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from './types.ts';
+export { FsError, FsTargetKey, FsVersion, } from './types.ts';
+export type { FsEditOutcome, FsEditRequest, FsDirEntry, FsErrorCode, FsInfo, FsMoveOutcome, FsObservation, FsPathInfo, FsRemoveOutcome, FsTarget, FsWriteIntent, FsWriteOutcome, } from './types.ts';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        fs: FileSystem;
+    }
+    interface Events {
+        /**
+         * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+         * `next()` yields the bare provider's unconditional write; the first listener
+         * that returns an intent owns the decision rather than composing with peers.
+         * @param target - the resolved target about to be written.
+         * @param actor - the opaque tool-execution context the decider keys off.
+         * @mode waterfall
+         */
+        'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>;
+        /**
+         * Single-slot decision for the next {@link FileSystem.editText}. Calling
+         * `next()` yields an unconditional edit; the first returned guard wins.
+         * @param target - the resolved target about to be edited.
+         * @param actor - the opaque tool-execution context the decider keys off.
+         * @mode waterfall
+         */
+        'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => {
+            version: FsVersion;
+        } | undefined | Promise<{
+            version: FsVersion;
+        } | undefined>): Promise<{
+            version: FsVersion;
+        } | undefined>;
+        /**
+         * Record an authoritative positive or negative observation. Listeners must
+         * be synchronous recorders: throws fail the tool call and returned promises
+         * are not awaited.
+         * @param target - the target whose presence or absence was observed.
+         * @param observation - present with its version, or confirmed absent.
+         * @param actor - the observing tool-execution context; undefined records nothing useful.
+         * @mode emit
+         */
+        'fs/observed'(target: FsTarget, observation: FsObservation, actor: object | undefined): void;
+    }
+}
+/**
+ * Abstract filesystem provider. Targets must preserve identity across aliases;
+ * reads expose regular UTF-8 text or typed errors, listings are stable and
+ * content-free, and mutations are atomic. Optional guards add stale protection
+ * without changing the unguarded provider contract.
+ */
+export declare abstract class FileSystem extends Service {
+    constructor(ctx: Context);
+    /**
+     * Observe one file or a directory's direct entries in this provider's execution world.
+     * @param target - resolved file or directory, including an absent path to observe for creation.
+     * @param changed - invalidation callback; errors can be reported during or after initialization.
+     * @param signal - cancels watcher initialization; the caller closes an initialized watcher.
+     * @returns a promise resolving once observation is active, with an asynchronous close function.
+     * @throws when the provider does not support watching or cannot initialize the watcher.
+     */
+    watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
+    /**
+     * The sandbox mode this backend enforces on mutations BY DEFAULT, or
+     * `undefined` when it does not confine at all — the capability fact the tool
+     * layer reads to advertise the escalation fields honestly (mirrors
+     * `ShellExecutor.sandboxMode`). The base class and the bare local backend
+     * report `undefined`; a sandboxing backend (`@qilin-agent/fs-sandbox`)
+     * overrides it with the deployment default. A session override may make the
+     * effective mode narrower or wider, so strict escalation widening is checked
+     * per call rather than encoded in this default-relative fact.
+     * @returns the configured default mode of a sandboxing backend; `undefined`
+     *   for a backend that never confines.
+     */
+    get sandboxMode(): SandboxMode | undefined;
+    /**
+     * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+     * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+     * async even though the local backend only normalizes + realpaths.
+     *
+     * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
+     * @param opts - optional cwd override and cancellation signal.
+     * @returns the stable target; the same file yields the same `targetKey`.
+     */
+    abstract resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    /**
+     * Return the canonical absolute path a subprocess in this filesystem's
+     * execution world can open. The path is deliberately separate from
+     * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+     * capability, but must continue treating the target key as opaque.
+     * @param target - the resolved target whose process path is required.
+     * @returns an absolute path in the backend's execution world.
+     */
+    abstract processPath(target: FsTarget): string;
+    /**
+     * Map an absolute path from the harness host into this filesystem's
+     * execution world when both paths identify the same file. The base provider
+     * exposes no mapping; host-backed or explicitly shared backends override it.
+     * @param hostPath - absolute path in the harness host filesystem.
+     * @returns the process path for the same file, or undefined when this
+     *   execution world cannot read that host file.
+     */
+    processPathFromHostPath(hostPath: string): string | undefined;
+    /**
+     * Return the canonical `file:` URI for a target in this filesystem's
+     * execution world. Backends own URI encoding because the host platform may
+     * differ from the execution platform.
+     * @param target - the resolved target to encode.
+     * @returns the target's canonical file URI.
+     */
+    abstract fileUrl(target: FsTarget): string;
+    /**
+     * Test canonical containment without exposing or parsing backend target
+     * keys. Both targets must come from this provider.
+     * @param parent - canonical directory target.
+     * @param child - canonical candidate target.
+     * @returns true when `child` is `parent` or a descendant of it.
+     */
+    abstract contains(parent: FsTarget, child: FsTarget): boolean;
+    /**
+     * Return target metadata, or `undefined` when the target does not exist.
+     * @param target - the resolved target to stat.
+     * @param signal - aborts the metadata round-trip.
+     * @returns metadata only, never content; undefined for an absent target.
+     */
+    abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
+    /**
+     * Return path metadata without following the final path component when it is a
+     * symbolic link. This is intentionally path-shaped, not target-shaped:
+     * {@link resolve} follows symlinks to produce the stable identity used by
+     * normal reads/writes, while `lstat` lets a consumer reject the path itself
+     * before that follow happens.
+     *
+     * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+     * absent.
+     * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+     * @param opts - `cwd` overrides the backend's default base for relative paths.
+     * @param signal - aborts the metadata round-trip.
+     * @returns metadata only, never content; undefined for an absent path.
+     */
+    abstract lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
+    /**
+     * Read the whole regular text file as a single decoded string.
+     * @param target - the resolved target to read.
+     * @param signal - aborts the read.
+     * @returns the full decoded UTF-8 content.
+     */
+    abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    /**
+     * Stream the whole regular text file as decoded text chunks (same text
+     * semantics as {@link readText}, for large files). The backend owns
+     * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
+     * touches raw bytes.
+     * @param target - the resolved target to read.
+     * @param signal - aborts the stream, including between chunks.
+     * @returns the chunk iterable, decoded and validated like {@link readText}.
+     */
+    abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
+    /**
+     * Read the whole regular file as raw bytes with no decoding or binary
+     * rejection. The bound lives at this seam so a backend can never buffer an
+     * unbounded file: a target known or discovered to exceed `maxBytes` fails
+     * with `FS_TOO_LARGE` instead of returning a truncated result.
+     * @param target - the resolved target to read.
+     * @param signal - aborts the read.
+     * @param maxBytes - inclusive byte cap on the complete content.
+     * @returns the full raw content, at most `maxBytes` long.
+     */
+    abstract readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
+    /**
+     * Read one byte window of the regular file as raw bytes with no decoding or
+     * binary rejection: the bytes at `[offset, offset + length)`, shorter when
+     * the file ends inside the window and empty when `offset` lies at or past
+     * its end. The window is the bound here, not the file: a backend transfers
+     * at most `length` bytes of content beyond the prefix it skips to reach
+     * `offset` and never buffers the whole file, so the caller's cap on `length`
+     * is the guard against unbounded buffering.
+     * @param target - the resolved target to read.
+     * @param range - `offset`, the 0-based first byte, and `length`, the largest byte count; both non-negative integers.
+     * @param signal - aborts the read.
+     * @returns the window's bytes, at most `length` long.
+     */
+    abstract readByteRange(target: FsTarget, range: {
+        offset: number;
+        length: number;
+    }, signal?: AbortSignal): Promise<Uint8Array>;
+    /**
+     * List direct children of a directory in stable name order. Returns resolved
+     * child targets plus cheap metadata only; never reads file contents.
+     * @param target - the resolved directory target.
+     * @param signal - aborts the listing.
+     * @returns one entry per direct child, in stable name order.
+     */
+    abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
+    /**
+     * Atomically create or replace UTF-8 text. `expected` guards intent and
+     * staleness; omission allows unconditional overwrite.
+     * @param target - the resolved target to write.
+     * @param content - the full new file content.
+     * @param expected - the write intent guarding the write; omit for unconditional.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root this write
+     *   runs under; a sandboxing backend fences the write by it, the bare backend
+     *   ignores it. Omit to leave the backend its own default.
+     * @returns the outcome, including the version the write produced.
+     */
+    abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsWriteOutcome>;
+    /**
+     * Atomically create or replace raw bytes. Same intent and staleness
+     * contract as {@link writeText}; the bytes are published as-is, so the
+     * caller owns the content encoding.
+     * @param target - the resolved target to write.
+     * @param content - the full new file content as raw bytes.
+     * @param expected - the write intent guarding the write; omit for unconditional.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root this write
+     *   runs under; a sandboxing backend fences the write by it, the bare backend
+     *   ignores it. Omit to leave the backend its own default.
+     * @returns the outcome, including the version the write produced.
+     */
+    abstract writeBytes(target: FsTarget, content: Uint8Array, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsWriteOutcome>;
+    /**
+     * Atomically edit literal text. When supplied, the version guard is checked
+     * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+     * the current content without a freshness precondition.
+     * @param target - the resolved target to edit.
+     * @param edit - the literal search/replace request.
+     * @param expected - the version guard; omit for an unconditional edit.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root this edit runs
+     *   under; a sandboxing backend fences the edit by it, the bare backend
+     *   ignores it. Omit to leave the backend its own default.
+     * @returns the outcome, including the version the edit produced.
+     */
+    abstract editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsEditOutcome>;
+    /**
+     * Remove one file or directory. The operation acts on the target's stable
+     * identity, so a path reached through a final symbolic link removes what that
+     * link resolves to, exactly as {@link writeText} writes through it.
+     * @param target - the resolved target to remove.
+     * @param opts - `recursive` removes a directory with all its contents; when
+     *   false, a non-empty directory fails with `FS_NOT_EMPTY`.
+     * @param signal - aborts before the removal takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root this removal
+     *   runs under; a sandboxing backend fences the removal by it, the bare
+     *   backend ignores it. Omit to leave the backend its own default.
+     * @returns whether a directory was removed; an absent target fails with `FS_NOT_FOUND`.
+     * @throws {FsError} with `FS_NOT_FOUND` for an absent target, `FS_NOT_EMPTY`
+     *   for a non-empty directory removed without `recursive`, `FS_PERMISSION_DENIED`
+     *   when the execution world refuses the removal, or `FS_IO_ERROR` for any
+     *   other backend failure.
+     */
+    abstract remove(target: FsTarget, opts: {
+        recursive: boolean;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsRemoveOutcome>;
+    /**
+     * Move or rename within one backend's execution world. A move never crosses
+     * backends: both targets must come from this provider, and a backend that
+     * cannot move a target (for example across filesystems) fails with `FS_IO_ERROR`
+     * rather than copying. Like the other mutations, the operation acts on each
+     * target's stable identity.
+     * @param from - the resolved source target.
+     * @param to - the resolved destination target; its parent directory must exist.
+     * @param opts - `overwrite` replaces an existing file at the destination; with
+     *   false an existing destination fails with `FS_EXISTS`, and a non-empty
+     *   destination directory always fails with `FS_NOT_EMPTY`.
+     * @param signal - aborts before the move takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root this move runs
+     *   under; a sandboxing backend fences both ends by it, the bare backend
+     *   ignores it. Omit to leave the backend its own default.
+     * @returns the destination's observed version when the backend can report one,
+     *   and whether an existing target was replaced.
+     * @throws {FsError} with `FS_NOT_FOUND` for an absent source or destination
+     *   parent, `FS_EXISTS` for an existing destination moved onto without
+     *   `overwrite`, `FS_NOT_EMPTY` for a non-empty destination directory,
+     *   `FS_PERMISSION_DENIED` when the execution world refuses the move, or
+     *   `FS_IO_ERROR` for any other backend failure.
+     */
+    abstract move(from: FsTarget, to: FsTarget, opts: {
+        overwrite: boolean;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsMoveOutcome>;
+    /**
+     * Create one directory. The operation acts on the target's stable identity and
+     * creates nothing outside the backend's own execution world.
+     * @param target - the resolved directory target to create.
+     * @param opts - `recursive` also creates missing parent directories; when
+     *   false, a missing parent fails with `FS_NOT_FOUND`. Either way an existing
+     *   directory is not an error only when `recursive` is true.
+     * @param signal - aborts before the directory is created.
+     * @param sandboxPolicy - the per-call mode and workspace root this creation
+     *   runs under; a sandboxing backend fences it by it, the bare backend ignores
+     *   it. Omit to leave the backend its own default.
+     * @returns nothing; the caller observes the new directory through `stat`/`listDir`.
+     * @throws {FsError} with `FS_EXISTS` for an existing entry the call would not
+     *   accept, `FS_NOT_FOUND` for a missing parent without `recursive`,
+     *   `FS_PERMISSION_DENIED` when the execution world refuses the creation, or
+     *   `FS_IO_ERROR` for any other backend failure.
+     */
+    abstract createDirectory(target: FsTarget, opts: {
+        recursive: boolean;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<void>;
+}
+export default FileSystem;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Vocabulary for the filesystem Service Definition (`ctx.fs`): the opaque target/version
+ * identities, the metadata `stat` returns, the write-intent and outcome shapes, the
+ * literal-edit request/outcome, and the typed error taxonomy.
+ * @module @qilin-agent/fs/types
+ */
+import { HarnessError } from '@qilin-agent/llm';
+import type { Branded } from '@qilin-agent/brand';
+/**
+ * Opaque key for stale guards and target lookup. The local backend uses a
+ * realpath-like string; a remote backend might use a workspace URI or file id.
+ * Consumers MUST NOT parse it or assume it is a local absolute path.
+ */
+export type FsTargetKey = Branded<'FsTargetKey'>;
+/**
+ * Brand a string as an {@link FsTargetKey}. For backend use only — a consumer
+ * never manufactures a key, it receives one from `resolve()`.
+ * @param key - the backend's raw key string (the local backend passes a realpath).
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function FsTargetKey(key: string): FsTargetKey;
+/**
+ * Opaque file-version token — the freshness token a write/edit guards against.
+ * The local backend derives it from high-resolution stat identity and freshness
+ * fields; a remote backend might use a revision id. The policy layer records it
+ * for stale checks; consumers may display related metadata but MUST NOT
+ * interpret this token.
+ */
+export type FsVersion = Branded<'FsVersion'>;
+/**
+ * Brand a string as an {@link FsVersion}. For backend use only — a consumer
+ * never manufactures a version, it receives one from `stat`/write/edit outcomes.
+ * @param v - the backend's raw version string.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function FsVersion(v: string): FsVersion;
+/**
+ * One authoritative observation of a target. A present observation carries the
+ * version used by guarded replacement; an absent observation authorizes only a
+ * guarded create, never an edit.
+ */
+export type FsObservation = {
+    readonly kind: 'present';
+    readonly version: FsVersion;
+} | {
+    readonly kind: 'absent';
+};
+/**
+ * A path resolved by a backend into a stable identity. `resolve()` produces
+ * this; every other operation takes it.
+ */
+export interface FsTarget {
+    /** Opaque key for stale guards and target lookup. */
+    targetKey: FsTargetKey;
+    /**
+     * Path for model/UI-facing output. May be a local absolute path,
+     * workspace-relative path, or remote URI depending on the backend.
+     */
+    displayPath: string;
+}
+/**
+ * Metadata about a target — what {@link FileSystem.stat} returns. Lets the
+ * policy layer reject directories/special files before reading and choose
+ * `readText` vs `streamText` from `size` without probing by failure. `version`
+ * is the freshness token. `undefined` from `stat` means the target is absent.
+ */
+export interface FsInfo {
+    /** Opaque freshness token of the target right now. */
+    version: FsVersion;
+    /** Whether the target is a regular file, a directory, or something else. */
+    type: 'file' | 'directory' | 'other';
+    /** Byte size of a regular file, when the backend can report it. */
+    size?: number;
+}
+/**
+ * Metadata about a path without following the final path component when it is a
+ * symbolic link. Unlike {@link FsInfo}, this path-level probe can report
+ * `symlink` so consumers with trust-boundary rules can reject repository-owned
+ * links before resolving a target.
+ */
+export interface FsPathInfo {
+    /** Opaque freshness token of the path entry right now. */
+    version: FsVersion;
+    /** Whether the path entry is a regular file, directory, symlink, or other. */
+    type: 'file' | 'directory' | 'symlink' | 'other';
+    /** Byte size of the path entry, when the backend can report it. */
+    size?: number;
+}
+/**
+ * One direct child returned by {@link FileSystem.listDir}. Listing returns
+ * metadata and resolved targets only; it must not read file contents.
+ */
+export interface FsDirEntry {
+    /** Basename of the child inside the listed directory. */
+    name: string;
+    /** Whether the child is a regular file, a directory, or something else. */
+    type: 'file' | 'directory' | 'other';
+    /** Resolved child target for follow-up operations. */
+    target: FsTarget;
+    /** Opaque freshness token when the backend can report metadata cheaply. */
+    version?: FsVersion;
+    /** Byte size of a regular file, when the backend can report it. */
+    size?: number;
+    /** Present when the listed name itself is a symbolic link; `type` still names what it resolves to. */
+    symlink?: boolean;
+}
+/**
+ * Guarded write intent. `createIfAbsent` rejects an existing target with
+ * `FS_NOT_OBSERVED`; `replaceIfVersion` rejects absence or mismatch with
+ * `FS_STALE_VERSION`. Omitting the intent from `writeText` means unconditional
+ * create-or-overwrite, not a third union arm.
+ */
+export type FsWriteIntent = {
+    kind: 'createIfAbsent';
+} | {
+    kind: 'replaceIfVersion';
+    version: FsVersion;
+};
+/** Outcome of a full-file write. */
+export interface FsWriteOutcome {
+    /** Whether the write created a new file or replaced an existing one. */
+    operation: 'create' | 'update';
+    /** Opaque version of the file after the write. */
+    version: FsVersion;
+    /**
+     * The file's content BEFORE the write, or `null` when the file did not exist
+     * (a create) or the backend declined a contextual basis (for example, a
+     * binary/non-UTF-8 prior file or either overwrite side reaching its exclusive limit).
+     * LF-normalized storage text (the diff basis), never a diff — a consumer
+     * computes the result-time contextual diff from `before`/`after` when
+     * `before` is present, else falls back to a whole-file diff.
+     */
+    before: string | null;
+    /** The file's content AFTER the write, LF-normalized to share `before`'s diff basis; `null` for a raw-bytes write (no text basis). */
+    after: string | null;
+}
+/** A literal-replacement edit request. */
+export interface FsEditRequest {
+    /** Literal non-empty text to replace. Must match exactly (after line-ending normalization). */
+    oldString: string;
+    /** Literal replacement text. An empty string deletes the matched text. */
+    newString: string;
+    /** Replace every match instead of requiring exactly one. */
+    replaceAll: boolean;
+}
+/** Outcome of a literal edit. */
+export interface FsEditOutcome {
+    /** Opaque version of the file after the edit. */
+    version: FsVersion;
+    /**
+     * The file's content BEFORE the edit. Raw storage text (LF-normalized by the
+     * backend), never a diff — a consumer computes the result-time contextual diff
+     * (the applied hunk with context) from `before`/`after`.
+     */
+    before: string;
+    /** The file's content AFTER the edit. */
+    after: string;
+}
+/** Outcome of a delete. */
+export interface FsRemoveOutcome {
+    /** Whether the removed target was a directory rather than a file or other entry. */
+    directory: boolean;
+}
+/** Outcome of a move or rename inside one backend. */
+export interface FsMoveOutcome {
+    /**
+     * Opaque version of the target after the move, when the backend can observe
+     * the destination. Omitted when it cannot (a backend that only relays the
+     * move reports no version rather than a fabricated one).
+     */
+    version?: FsVersion;
+    /** Whether a target already existed at the destination and the move replaced it. */
+    replaced: boolean;
+}
+/**
+ * Stable, machine-routable codes for filesystem failures. Carried on
+ * {@link FsError}; the tool registry exposes `{ name, code }` on `isError`
+ * results so retry/permission/UI layers can branch without parsing messages.
+ */
+export type FsErrorCode = 'FS_NOT_FOUND' | 'FS_NOT_DIRECTORY' | 'FS_NOT_TEXT' | 'FS_NOT_REGULAR_FILE' | 'FS_NOT_EMPTY' | 'FS_EXISTS' | 'FS_TOO_LARGE' | 'FS_PERMISSION_DENIED' | 'FS_SANDBOX_DENIED' | 'FS_IO_ERROR' | 'FS_STALE_VERSION' | 'FS_NOT_OBSERVED' | 'FS_AMBIGUOUS_EDIT' | 'FS_EDIT_NOT_FOUND' | 'FS_ABORTED';
+/**
+ * Typed filesystem error. Extends {@link HarnessError} so it carries a stable
+ * {@link FsErrorCode} and chains `cause`. `qilin-fs` owns this vocabulary so
+ * backends and the policy layer raise the same codes instead of each inventing
+ * message strings.
+ */
+export declare class FsError extends HarnessError {
+    readonly code: FsErrorCode;
+    constructor(message: string, code: FsErrorCode, options?: ErrorOptions);
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@qilin-agent/fs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Abstract filesystem capability seam (ctx.fs) for the QiLin — vocabulary types, the FileSystem service (text IO + optional version-guarded atomic mutations), and the fs/* policy event vocabulary",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/fs/fs"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/brand": "3.1.4",
+    "@qilin-agent/sandbox": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/brand": "3.1.4",
+    "@qilin-agent/sandbox": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }