@runko/sdk 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @runko/sdk
+
+runko 的主包（门面）：batteries-included，re-export 全部三个子包（`@runko/core` / `@runko/virtual-fs` / `@runko/mini-bash`），5 行上手只装这一个。
+
+> TODO：npm 裸名 `runko` 的发布决策待定——定了之后本 README 与所有示例的 `@runko/sdk` import 同步替换。
+
+## 安装
+
+```sh
+pnpm add @runko/sdk ai        # ai@^7 是 peerDependency，跟随宿主版本
+```
+
+模型层即 Vercel AI SDK：`"provider/model"` Gateway 字符串开箱可用（零 provider 依赖）；要直连某家 provider 就再装对应包（如 `@ai-sdk/anthropic`）。
+
+## 最小用例（产品文档 §4.1 的五行示例）
+
+```ts
+import { defineAgent, createSession, RunkoFS } from "@runko/sdk";
+// 或直连 provider：import { anthropic } from "@ai-sdk/anthropic"; model: anthropic("claude-sonnet-5")
+
+const agent = defineAgent({ model: "anthropic/claude-sonnet-5" });
+const session = createSession(agent, { fs: RunkoFS.fromDirectory("./project") });
+const result = await session.send("把 src/index.ts 里的 var 全部改成 const");
+console.log(result.finalResponse, await session.fs.diff());
+```
+
+全程不写真实磁盘——写入落在 overlay 内存层，`session.fs.diff()` 拿变更，`session.fs.writeBack()` 才落盘（唯一写磁盘的操作，只有宿主可达）。
+
+## 本包相对 @runko/core 的两处默认装配
+
+其余 API 全部原样 re-export（清单见各子包 README）；本包自己只添两个符号：
+
+### `createSession(agent, opts?)`（默认装配版）
+
+与 core 的原始 `createSession` 同名同形状，差异只在默认值：
+
+- **`fs` 缺省时自动注入空 `MemoryFS`**（core 版缺省是"调用即抛指导性错误"的占位 FS）；
+- **文件工具八件套默认全开**（read_file / write_file / edit_file / delete_file / move_file / list_dir / glob / grep，`@runko/virtual-fs` 的 `createFileTools` 自动拼装，readState / file_change 事件通路全接好）；`agent.builtinTools` 数组白名单裁剪、`false` 全关；宿主 `tools` 同名覆盖内置。
+- **`session.fs` 保留传入的具体类型**：`fs: RunkoFS.fromDirectory(...)` 时 `session.fs` 就是 `OverlayFS`，`session.fs.diff()` 无需断言直接编译（三重载泛型）。
+
+需要无装配原语的宿主直接 `import { createSession } from "@runko/core"`，路径未被遮蔽切断。
+
+### `RunkoFS`（类型 + 值命名空间）
+
+- 类型：即 core 的 `RunkoFS` 接口（七方法：readFile / writeFile / rm / mkdir / readdir / stat / glob）。
+- 值：`RunkoFS.fromMemory(files)` → `MemoryFS`；`RunkoFS.fromDirectory(dir, opts?)` → `OverlayFS`（真实目录零拷贝挂载）。
+
+## 常用能力速查（均经本包可达）
+
+| 要做什么 | 用什么 | 定义在 |
+|---|---|---|
+| 声明 agent / 工具 / skill | `defineAgent` / `defineTool` / `defineSkill` | [@runko/core](../core/README.md) |
+| 跑会话、流式事件、审批、序列化恢复 | `createSession` → `send()` / `stream()` / `toJSON()` + `SessionOptions.resume` | @runko/core（本包加默认装配） |
+| 结构化输出 | `session.send<T>(input, { outputSchema })` | @runko/core |
+| 虚拟文件系统 | `RunkoFS.fromMemory` / `RunkoFS.fromDirectory`、`diff()` / `writeBack()` / `snapshot()` | [@runko/virtual-fs](../virtual-fs/README.md) |
+| 纯内存命令执行（bash 工具，零依赖极简档：六命令） | `createSession(agent, { fs, exec: miniBash(fs) })` | [@runko/mini-bash](../mini-bash/README.md) |
+| 全语法档命令执行（bash 工具：`if`/`for`/`while`/`case`/函数） | `createSession(agent, { fs, exec: justBash(fs) })`——**需单独 `pnpm add @runko/just-bash`**，不随本包装入 | [@runko/just-bash](../just-bash/README.md) |
+| 本机命令执行 | `localExec()`（出厂审批 `"always"`；`{ materialize: true, fs }` 物化模式） | @runko/core |
+| eve 布局目录加载 | `loadAgent(dir)` / `loadAgentFromFS(fs, dir)`（`@runko/core/load` 子路径同样可达） | @runko/core |
+
+**bash 分档**：`@runko/mini-bash` 随本包 re-export，开箱可用，定位安全默认/测试演示；`@runko/just-bash`（vercel-labs/just-bash 适配器）因依赖树含 wasm 大件（sql.js、quickjs-emscripten 等）**不进本包依赖**，强制打包违背门面轻量默认——需要全语法档的宿主显式安装该包后按上表用法注入（见 [core-sdk · 技术方案 §4.5b](../../docs/logic/engine/tech/core-sdk.md)）。
+
+可运行示例见 [examples/](../../examples/README.md)（含 [08-just-bash.ts](../../examples/src/08-just-bash.ts)）。

package/dist/index.cjs

@@ -0,0 +1,131 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _runko_core = require("@runko/core");
+let _runko_virtual_fs = require("@runko/virtual-fs");
+//#region src/fs.ts
+/**
+* `RunkoFS` 值命名空间（docs/tech/core-sdk.md §4.4 原文字面调用形态：`RunkoFS.fromMemory(...)`/
+* `RunkoFS.fromDirectory(...)`）。P2-1 施工时把工厂拆成 `@runko/virtual-fs` 的
+* 独立函数 `fromMemory`/`fromDirectory`——因为 `RunkoFS` 本身已经是 `@runko/core`
+* 导出的**接口类型**名，interface（跨包）与值命名空间没法通过声明合并凑到一起
+* （合并只在单个模块内生效，且合并双方都必须是"本地声明"，见下）；tech-spec
+* §4.4 原文把这层"重新拼回值命名空间"的工作留给门面（P7）评审，这里落地。
+*
+* 类型 `RunkoFS`（下方 `type RunkoFS = CoreRunkoFS`，与 core 的接口结构完全一致）
+* 与值 `RunkoFS`（下方 `const RunkoFS`，两个工厂方法）分属 TypeScript 类型/值两个
+* 独立命名空间，同名共存不冲突——与 core 自己的 `Skill`（`interface Skill` +
+* `const Skill`，同一个模块内共存，P5-1 已验证的先例）是同一手法，唯一区别是这里
+* 两半来自不同的包，在门面 `fs.ts` 首次汇合。
+*
+* 类型这里必须重新声明为**本地** `type RunkoFS = CoreRunkoFS`，不能写
+* `export type { RunkoFS } from "@runko/core"` 原样透传——后者是一条"再导出"
+* 语句而非本地类型声明，与下面的本地 `const RunkoFS` 搭配会被 tsc 判为
+* "Cannot redeclare exported variable 'RunkoFS'"（TS2323）；只有类型别名与值
+* 两者都是货真价实的本地声明时才能合法合并。同理，`index.ts` 汇总本文件时也
+* 必须用具名 re-export（`export { RunkoFS } from "./fs.js"`）而非 `export *`——
+* 否则会与 `export * from "@runko/core"` 带入的 `RunkoFS` 类型撞成两个 `export *`
+* 源导出同名成员的"ambiguous"错误（TS2308，与类型/值是否同一命名空间无关，
+* tsc 按导出名字符串判定冲突）。两处结论均以最小复现验证过，详见工单汇报。
+*/
+const RunkoFS = {
+	fromMemory: _runko_virtual_fs.fromMemory,
+	fromDirectory: _runko_virtual_fs.fromDirectory
+};
+//#endregion
+//#region src/session.ts
+/** 八件套的全部工具名，按 docs/tech/builtin-tools.md §1.1–§1.8 的声明顺序列出。 */
+const ALL_FILE_TOOL_NAMES = [
+	"read-file",
+	"write-file",
+	"edit-file",
+	"delete-file",
+	"move-file",
+	"list-dir",
+	"glob",
+	"grep"
+];
+/**
+* `agent.builtinTools` 对文件工具八件套的过滤（docs/tech/builtin-tools.md §3）：
+* `false` 全关；`undefined`（未配置）默认全开；数组按白名单交集（数组里
+* 出现的 `update-plan`/其他非文件工具名对这里无意义，交集自然把它们滤掉——
+* `update-plan` 的开关逻辑仍由 core 自己的 `isUpdatePlanEnabled` 负责，两条
+* 过滤各自独立、互不影响）。
+*/
+function resolveEnabledFileToolNames(builtinTools) {
+	if (builtinTools === false) return [];
+	if (builtinTools === void 0) return ALL_FILE_TOOL_NAMES;
+	const requested = new Set(builtinTools);
+	return ALL_FILE_TOOL_NAMES.filter((name) => requested.has(name));
+}
+/**
+* 预构造 `readState`/`derivedData` store 并拼出过滤后的文件工具八件套——
+* 沿用 core `session.ts` 文件头记录的宿主装配姿态（`createFileTools({ readState,
+* onFileChange })`，`onFileChange` 把 `FileChange[]` 逐条转发进
+* `derivedData.recordFileChange`），只是这里由 sdk 在 `createSession(...)` 内部
+* 自动完成，宿主不需要再手写这段拼装（P4-2 集成测试里手写的那段，正是这里的
+* 落地位置）。
+*/
+function buildDefaultFileTools(agent, readState, derivedData) {
+	const enabledNames = resolveEnabledFileToolNames(agent.builtinTools);
+	if (enabledNames.length === 0) return {};
+	const allFileTools = (0, _runko_virtual_fs.createFileTools)({
+		readState,
+		onFileChange: (changes) => {
+			for (const change of changes) derivedData.recordFileChange(change);
+		}
+	});
+	const enabled = {};
+	for (const name of enabledNames) enabled[name] = allFileTools[name];
+	return enabled;
+}
+/** `fs`/`workspace` 都未提供时才注入默认 `MemoryFS`——两者任一存在都原样透传给 core 自行解析（含互斥校验与 exec 派生）。 */
+function withDefaultFs(opts) {
+	if (opts.fs !== void 0 || opts.workspace !== void 0) return opts;
+	return {
+		...opts,
+		fs: new _runko_virtual_fs.MemoryFS()
+	};
+}
+function createSession(agent, opts = {}) {
+	const readState = opts.readState ?? (0, _runko_core.createSessionReadState)();
+	const derivedData = opts.derivedData ?? (0, _runko_core.createDerivedDataCollector)();
+	const tools = {
+		...buildDefaultFileTools(agent, readState, derivedData),
+		...agent.tools ?? {}
+	};
+	return (0, _runko_core.createSession)({
+		...agent,
+		tools
+	}, withDefaultFs({
+		...opts,
+		readState,
+		derivedData
+	}));
+}
+//#endregion
+exports.RunkoFS = RunkoFS;
+exports.createSession = createSession;
+Object.keys(_runko_core).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return _runko_core[k];
+		}
+	});
+});
+Object.keys(_runko_virtual_fs).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return _runko_virtual_fs[k];
+		}
+	});
+});
+var _runko_mini_bash = require("@runko/mini-bash");
+Object.keys(_runko_mini_bash).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return _runko_mini_bash[k];
+		}
+	});
+});

package/dist/index.d.cts

@@ -0,0 +1,26 @@
+import { AgentDefinition, RunkoExec, RunkoFS as RunkoFS$1, Session as Session$1, SessionOptions } from "@runko/core";
+import { MemoryFS, fromDirectory, fromMemory } from "@runko/virtual-fs";
+export * from "@runko/core";
+export * from "@runko/virtual-fs";
+export * from "@runko/mini-bash";
+//#region src/fs.d.ts
+type RunkoFS = RunkoFS$1;
+declare const RunkoFS: {
+  fromMemory: typeof fromMemory;
+  fromDirectory: typeof fromDirectory;
+};
+//#endregion
+//#region src/session.d.ts
+/** sdk 门面版 `Session`：与 core 的原始 `Session` 完全一致，只是 `fs` 保留调用方传入的具体类型。 */
+type Session<F extends RunkoFS$1 = RunkoFS$1> = Omit<Session$1, "fs"> & {
+  readonly fs: F;
+};
+declare function createSession<F extends RunkoFS$1>(agent: AgentDefinition, opts: Omit<SessionOptions, "fs" | "workspace"> & {
+  fs: F;
+}): Session<F>;
+declare function createSession<W extends RunkoFS$1 & RunkoExec>(agent: AgentDefinition, opts: Omit<SessionOptions, "fs" | "workspace"> & {
+  workspace: W;
+}): Session<W>;
+declare function createSession(agent: AgentDefinition, opts?: SessionOptions): Session<MemoryFS>;
+//#endregion
+export { RunkoFS, type Session, createSession };

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { AgentDefinition, RunkoExec, RunkoFS as RunkoFS$1, Session as Session$1, SessionOptions } from "@runko/core";
+import { MemoryFS, fromDirectory, fromMemory } from "@runko/virtual-fs";
+export * from "@runko/core";
+export * from "@runko/virtual-fs";
+export * from "@runko/mini-bash";
+//#region src/fs.d.ts
+type RunkoFS = RunkoFS$1;
+declare const RunkoFS: {
+  fromMemory: typeof fromMemory;
+  fromDirectory: typeof fromDirectory;
+};
+//#endregion
+//#region src/session.d.ts
+/** sdk 门面版 `Session`：与 core 的原始 `Session` 完全一致，只是 `fs` 保留调用方传入的具体类型。 */
+type Session<F extends RunkoFS$1 = RunkoFS$1> = Omit<Session$1, "fs"> & {
+  readonly fs: F;
+};
+declare function createSession<F extends RunkoFS$1>(agent: AgentDefinition, opts: Omit<SessionOptions, "fs" | "workspace"> & {
+  fs: F;
+}): Session<F>;
+declare function createSession<W extends RunkoFS$1 & RunkoExec>(agent: AgentDefinition, opts: Omit<SessionOptions, "fs" | "workspace"> & {
+  workspace: W;
+}): Session<W>;
+declare function createSession(agent: AgentDefinition, opts?: SessionOptions): Session<MemoryFS>;
+//#endregion
+export { RunkoFS, type Session, createSession };

package/dist/index.js

@@ -0,0 +1,107 @@
+import { createDerivedDataCollector, createSession as createSession$1, createSessionReadState } from "@runko/core";
+import { MemoryFS, createFileTools, fromDirectory, fromMemory } from "@runko/virtual-fs";
+export * from "@runko/core";
+export * from "@runko/virtual-fs";
+export * from "@runko/mini-bash";
+//#region src/fs.ts
+/**
+* `RunkoFS` 值命名空间（docs/tech/core-sdk.md §4.4 原文字面调用形态：`RunkoFS.fromMemory(...)`/
+* `RunkoFS.fromDirectory(...)`）。P2-1 施工时把工厂拆成 `@runko/virtual-fs` 的
+* 独立函数 `fromMemory`/`fromDirectory`——因为 `RunkoFS` 本身已经是 `@runko/core`
+* 导出的**接口类型**名，interface（跨包）与值命名空间没法通过声明合并凑到一起
+* （合并只在单个模块内生效，且合并双方都必须是"本地声明"，见下）；tech-spec
+* §4.4 原文把这层"重新拼回值命名空间"的工作留给门面（P7）评审，这里落地。
+*
+* 类型 `RunkoFS`（下方 `type RunkoFS = CoreRunkoFS`，与 core 的接口结构完全一致）
+* 与值 `RunkoFS`（下方 `const RunkoFS`，两个工厂方法）分属 TypeScript 类型/值两个
+* 独立命名空间，同名共存不冲突——与 core 自己的 `Skill`（`interface Skill` +
+* `const Skill`，同一个模块内共存，P5-1 已验证的先例）是同一手法，唯一区别是这里
+* 两半来自不同的包，在门面 `fs.ts` 首次汇合。
+*
+* 类型这里必须重新声明为**本地** `type RunkoFS = CoreRunkoFS`，不能写
+* `export type { RunkoFS } from "@runko/core"` 原样透传——后者是一条"再导出"
+* 语句而非本地类型声明，与下面的本地 `const RunkoFS` 搭配会被 tsc 判为
+* "Cannot redeclare exported variable 'RunkoFS'"（TS2323）；只有类型别名与值
+* 两者都是货真价实的本地声明时才能合法合并。同理，`index.ts` 汇总本文件时也
+* 必须用具名 re-export（`export { RunkoFS } from "./fs.js"`）而非 `export *`——
+* 否则会与 `export * from "@runko/core"` 带入的 `RunkoFS` 类型撞成两个 `export *`
+* 源导出同名成员的"ambiguous"错误（TS2308，与类型/值是否同一命名空间无关，
+* tsc 按导出名字符串判定冲突）。两处结论均以最小复现验证过，详见工单汇报。
+*/
+const RunkoFS = {
+	fromMemory,
+	fromDirectory
+};
+//#endregion
+//#region src/session.ts
+/** 八件套的全部工具名，按 docs/tech/builtin-tools.md §1.1–§1.8 的声明顺序列出。 */
+const ALL_FILE_TOOL_NAMES = [
+	"read-file",
+	"write-file",
+	"edit-file",
+	"delete-file",
+	"move-file",
+	"list-dir",
+	"glob",
+	"grep"
+];
+/**
+* `agent.builtinTools` 对文件工具八件套的过滤（docs/tech/builtin-tools.md §3）：
+* `false` 全关；`undefined`（未配置）默认全开；数组按白名单交集（数组里
+* 出现的 `update-plan`/其他非文件工具名对这里无意义，交集自然把它们滤掉——
+* `update-plan` 的开关逻辑仍由 core 自己的 `isUpdatePlanEnabled` 负责，两条
+* 过滤各自独立、互不影响）。
+*/
+function resolveEnabledFileToolNames(builtinTools) {
+	if (builtinTools === false) return [];
+	if (builtinTools === void 0) return ALL_FILE_TOOL_NAMES;
+	const requested = new Set(builtinTools);
+	return ALL_FILE_TOOL_NAMES.filter((name) => requested.has(name));
+}
+/**
+* 预构造 `readState`/`derivedData` store 并拼出过滤后的文件工具八件套——
+* 沿用 core `session.ts` 文件头记录的宿主装配姿态（`createFileTools({ readState,
+* onFileChange })`，`onFileChange` 把 `FileChange[]` 逐条转发进
+* `derivedData.recordFileChange`），只是这里由 sdk 在 `createSession(...)` 内部
+* 自动完成，宿主不需要再手写这段拼装（P4-2 集成测试里手写的那段，正是这里的
+* 落地位置）。
+*/
+function buildDefaultFileTools(agent, readState, derivedData) {
+	const enabledNames = resolveEnabledFileToolNames(agent.builtinTools);
+	if (enabledNames.length === 0) return {};
+	const allFileTools = createFileTools({
+		readState,
+		onFileChange: (changes) => {
+			for (const change of changes) derivedData.recordFileChange(change);
+		}
+	});
+	const enabled = {};
+	for (const name of enabledNames) enabled[name] = allFileTools[name];
+	return enabled;
+}
+/** `fs`/`workspace` 都未提供时才注入默认 `MemoryFS`——两者任一存在都原样透传给 core 自行解析（含互斥校验与 exec 派生）。 */
+function withDefaultFs(opts) {
+	if (opts.fs !== void 0 || opts.workspace !== void 0) return opts;
+	return {
+		...opts,
+		fs: new MemoryFS()
+	};
+}
+function createSession(agent, opts = {}) {
+	const readState = opts.readState ?? createSessionReadState();
+	const derivedData = opts.derivedData ?? createDerivedDataCollector();
+	const tools = {
+		...buildDefaultFileTools(agent, readState, derivedData),
+		...agent.tools ?? {}
+	};
+	return createSession$1({
+		...agent,
+		tools
+	}, withDefaultFs({
+		...opts,
+		readState,
+		derivedData
+	}));
+}
+//#endregion
+export { RunkoFS, createSession };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@runko/sdk",
+  "version": "0.1.0",
+  "description": "runko 主包（门面）：re-export core + virtual-fs（+ mini-bash），batteries-included",
+  "type": "module",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@runko/core": "^0.1.0",
+    "@runko/virtual-fs": "^0.1.0",
+    "@runko/mini-bash": "^0.1.0"
+  },
+  "peerDependencies": {
+    "ai": "^7"
+  },
+  "devDependencies": {
+    "@ai-sdk/deepseek": "^3.0.7",
+    "@types/node": "^24.13.3",
+    "ai": "^7.0.20",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run"
+  }
+}