@4fu/arbor-environment-dir 0.0.0-stage → 0.1.0

package/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @4fu/arbor-environment-dir - the default `Environment`: one shared `/env`
+ * directory, with a revision per item, validation on install and deltas for
+ * live windows (docs/environment.md).
+ */
+export { BUILTIN_SKILLS, BUILTIN_SKILL_PATH, DirectoryEnvironment, type DirectoryEnvironmentOptions, } from "./directory-environment.ts";
+export { StdioMcpServer, type StdioServerOptions, type ServerFunction } from "./mcp.ts";

package/index.js

@@ -0,0 +1,7 @@
+/**
+ * @4fu/arbor-environment-dir - the default `Environment`: one shared `/env`
+ * directory, with a revision per item, validation on install and deltas for
+ * live windows (docs/environment.md).
+ */
+export { BUILTIN_SKILLS, BUILTIN_SKILL_PATH, DirectoryEnvironment, } from "./directory-environment.js";
+export { StdioMcpServer } from "./mcp.js";

package/mcp.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A minimal MCP client over stdio: one server process, newline-delimited
+ * JSON-RPC 2.0 (docs/environment.md#using-a-skill-or-a-server).
+ *
+ * arbor needs three things from a server - start it, list its functions, call
+ * one - so this is the whole protocol it speaks: `initialize`,
+ * `notifications/initialized`, `tools/list` and `tools/call`. A server that
+ * answers those is usable; anything else an MCP server can do stays with the
+ * model, which reads and reinstalls the server like any environment item.
+ *
+ * A secret is named by the configuration and its value comes from the host, so
+ * a server never holds one and none is written anywhere.
+ */
+import type { FunctionSpec } from "@4fu/arbor-interfaces";
+export interface StdioServerOptions {
+    /** The item's name, which the module and its functions are named after. */
+    name: string;
+    /** The directory the command runs in: the item's own directory. */
+    dir: string;
+    command: string;
+    args?: readonly string[];
+    env?: Record<string, string>;
+    /** The names of the secrets it uses; their values come from `secretOf`. */
+    secrets?: readonly string[];
+    /** Where a secret's value comes from. A configuration names one, never holds it. */
+    secretOf?: (name: string) => string | undefined;
+    timeoutMs?: number;
+}
+/** One function a server lists, in the shape the catalog declares. */
+export interface ServerFunction {
+    name: string;
+    description: string;
+    signature: string;
+}
+export declare class StdioMcpServer {
+    private readonly options;
+    private readonly timeoutMs;
+    private readonly child;
+    private readonly lines;
+    private readonly stderr;
+    private nextId;
+    private readonly waiting;
+    private closed;
+    private constructor();
+    /** Start a server and complete the MCP handshake. */
+    static start(options: StdioServerOptions): Promise<StdioMcpServer>;
+    /** The functions this server lists, in the shape the catalog declares. */
+    functions(): Promise<readonly FunctionSpec[]>;
+    /** Call one function and answer with its text. */
+    call(fn: string, args: Record<string, unknown>): Promise<string>;
+    /** Stop the server. A stopped server is started again on the next call. */
+    close(): Promise<void>;
+    private functionOf;
+    private notify;
+    private request;
+    private send;
+    private answer;
+    /** A server that died leaves no request hanging. */
+    private failAll;
+}

package/mcp.js

@@ -0,0 +1,207 @@
+/**
+ * A minimal MCP client over stdio: one server process, newline-delimited
+ * JSON-RPC 2.0 (docs/environment.md#using-a-skill-or-a-server).
+ *
+ * arbor needs three things from a server - start it, list its functions, call
+ * one - so this is the whole protocol it speaks: `initialize`,
+ * `notifications/initialized`, `tools/list` and `tools/call`. A server that
+ * answers those is usable; anything else an MCP server can do stays with the
+ * model, which reads and reinstalls the server like any environment item.
+ *
+ * A secret is named by the configuration and its value comes from the host, so
+ * a server never holds one and none is written anywhere.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { arborError } from "@4fu/arbor-errors";
+/** The MCP protocol version this client speaks. */
+const PROTOCOL_VERSION = "2024-11-05";
+/** How long one request waits for an answer. */
+const DEFAULT_TIMEOUT_MS = 20000;
+export class StdioMcpServer {
+    options;
+    timeoutMs;
+    child;
+    lines;
+    stderr = [];
+    nextId = 1;
+    waiting = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const secrets = {};
+        for (const name of options.secrets ?? []) {
+            const value = options.secretOf?.(name);
+            if (value !== undefined && value !== "")
+                secrets[name] = value;
+        }
+        this.child = spawn(options.command, [...(options.args ?? [])], {
+            cwd: options.dir,
+            env: { ...process.env, ...(options.env ?? {}), ...secrets },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child.stderr?.on("data", (chunk) => {
+            this.stderr.push(chunk.toString("utf8"));
+            if (this.stderr.length > 50)
+                this.stderr.shift();
+        });
+        this.child.on("error", (error) => this.failAll(error));
+        this.child.on("exit", (code) => this.failAll(new Error(`the server exited with code ${code ?? "null"}`)));
+        this.lines = createInterface({ input: this.child.stdout });
+        this.lines.on("line", (line) => this.answer(line));
+    }
+    /** Start a server and complete the MCP handshake. */
+    static async start(options) {
+        const server = new StdioMcpServer(options);
+        try {
+            await server.request("initialize", {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: { name: "arbor", version: "0.0.0" },
+            });
+            server.notify("notifications/initialized", {});
+            return server;
+        }
+        catch (error) {
+            await server.close();
+            throw error;
+        }
+    }
+    /** The functions this server lists, in the shape the catalog declares. */
+    async functions() {
+        const result = (await this.request("tools/list", {}));
+        const tools = Array.isArray(result.tools) ? result.tools : [];
+        return tools.map((tool) => this.functionOf(tool));
+    }
+    /** Call one function and answer with its text. */
+    async call(fn, args) {
+        const name = fn.startsWith(`${this.options.name}.`) ? fn.slice(this.options.name.length + 1) : fn;
+        const result = (await this.request("tools/call", { name, arguments: args }));
+        if (result.isError === true) {
+            throw arborError({
+                code: "refused",
+                rule: "mcp.call.failed",
+                message: `${this.options.name}.${name} 调用失败`,
+                nextAction: "检查参数后用 tool_describe 核对签名，再调用一次。",
+                details: { server: this.options.name, function: name },
+            });
+        }
+        const content = Array.isArray(result.content) ? result.content : [];
+        return content
+            .map((part) => {
+            const block = part;
+            return block.type === "text" ? (block.text ?? "") : "";
+        })
+            .filter((text) => text !== "")
+            .join("\n");
+    }
+    /** Stop the server. A stopped server is started again on the next call. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.lines.close();
+        this.child.kill("SIGTERM");
+        await new Promise((resolve) => {
+            if (this.child.exitCode !== null || this.child.signalCode !== null) {
+                resolve();
+                return;
+            }
+            this.child.once("exit", () => resolve());
+            setTimeout(() => {
+                this.child.kill("SIGKILL");
+                resolve();
+            }, 2000).unref();
+        });
+    }
+    functionOf(tool) {
+        const spec = tool;
+        const name = spec.name ?? "";
+        const properties = spec.inputSchema?.properties ?? {};
+        const required = new Set(Array.isArray(spec.inputSchema?.required) ? spec.inputSchema?.required : []);
+        const parameters = Object.keys(properties).map((key) => `${key}${required.has(key) ? "" : "?"}`);
+        return {
+            name: `${this.options.name}.${name}`,
+            signature: `${this.options.name}.${name}(${parameters.join(", ")})`,
+            description: spec.description ?? "",
+        };
+    }
+    notify(method, params) {
+        this.send({ jsonrpc: "2.0", method, params });
+    }
+    async request(method, params) {
+        const id = this.nextId;
+        this.nextId += 1;
+        const answer = new Promise((resolve, reject) => {
+            this.waiting.set(id, { resolve, reject });
+            const timer = setTimeout(() => {
+                this.waiting.delete(id);
+                reject(arborError({
+                    code: "unavailable",
+                    rule: "mcp.server.timeout",
+                    message: `MCP 服务器 ${this.options.name} 没有在 ${this.timeoutMs} ms 内回答 ${method}`,
+                    nextAction: "检查服务器是否卡住；修好后用 reload 重新安装它。",
+                    details: { server: this.options.name, method },
+                }));
+            }, this.timeoutMs);
+            timer.unref();
+        });
+        this.send({ jsonrpc: "2.0", id, method, params });
+        return answer;
+    }
+    send(message) {
+        if (this.closed || this.child.stdin?.destroyed === true) {
+            throw arborError({
+                code: "unavailable",
+                rule: "mcp.server.closed",
+                message: `MCP 服务器 ${this.options.name} 已停止`,
+                nextAction: "用 reload 重新安装该服务器。",
+                details: { server: this.options.name },
+            });
+        }
+        this.child.stdin?.write(`${JSON.stringify(message)}\n`);
+    }
+    answer(line) {
+        if (line.trim() === "")
+            return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const pending = message.id === undefined ? undefined : this.waiting.get(message.id);
+        if (pending === undefined)
+            return;
+        this.waiting.delete(message.id);
+        if (message.error !== undefined) {
+            pending.reject(arborError({
+                code: "refused",
+                rule: "mcp.server.error",
+                message: `MCP 服务器 ${this.options.name}：${message.error.message ?? "未知错误"}`,
+                nextAction: "按错误修正服务器或参数后重试。",
+                details: { server: this.options.name },
+            }));
+            return;
+        }
+        pending.resolve(message.result);
+    }
+    /** A server that died leaves no request hanging. */
+    failAll(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const [, pending] of this.waiting) {
+            pending.reject(arborError({
+                code: "unavailable",
+                rule: "mcp.server.died",
+                message: `MCP 服务器 ${this.options.name} 已退出：${error.message}`,
+                nextAction: "查看服务器输出，修好后用 reload 重新安装。",
+                details: { server: this.options.name, stderr: this.stderr.join("") },
+            }));
+        }
+        this.waiting.clear();
+    }
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@4fu/arbor-environment-dir",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The default Environment: skills, MCP servers, services and settings in one shared /env directory, with a revision per item, validation and deltas.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "files": [
+    "directory-environment.d.ts",
+    "directory-environment.js",
+    "index.d.ts",
+    "index.js",
+    "mcp.d.ts",
+    "mcp.js",
+    "skills/arbor-mcp/SKILL.md",
+    "skills/arbor-service/SKILL.md",
+    "skills/arbor-settings/SKILL.md",
+    "skills/arbor-skill/SKILL.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/arbor.git",
+    "directory": "packages/environment-dir"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@4fu/arbor-errors": "0.1.0",
+    "@4fu/arbor-interfaces": "0.1.0"
+  }
+}

package/skills/arbor-mcp/SKILL.md

@@ -0,0 +1,51 @@
+# 接一个 MCP 服务器
+
+MCP 服务器是一种能力：装上之后，它的函数在 `code_exec` 里像一个模块一样调用。插件
+不增加直接工具，能力都是 MCP 服务器。
+
+## 结构
+
+一个 MCP 服务器的配置是一个 JSON 文件，草稿可以是一个文件，也可以是一个带着代码的
+目录：
+
+```json
+{
+  "command": "node",
+  "args": ["server.js"],
+  "secrets": ["MY_TOKEN"]
+}
+```
+
+- `command` 和 `args`：服务器怎么启动。用目录作草稿时，命令在这个目录里运行，所以
+  `server.js` 这样的相对路径可以。
+- `url`：一个已经跑起来的 HTTP 服务器，与 command 二选一。
+- `secrets`：它用到的秘密的名字，只写名字，不写值。值由主机按名字注入。
+
+安装后是 `/env/mcp/<name>.json`（文件草稿）或 `/env/mcp/<name>/<name>.json`（目录草稿）。
+
+## 自测
+
+1. 在本窗口工作区里写好服务器和配置。
+2. 先把它跑起来：`bash node server.js`，看它有没有在等输入、有没有报错。
+3. 用 `tool_search("<name>")` 查它的函数，用 `tool_describe("<name>.<fn>")` 看签名。
+4. 在 `code_exec` 里调用一次，确认返回的是文本。
+
+## 安装
+
+`reload({ install: ["./<name>.json"] })`，或目录草稿 `reload({ install: ["./<name>"] })`。
+
+reload 会真的把服务器启动起来、列出它的函数，通过之后才安装。启动失败或列不出函数时
+调用被拒绝，什么都不改变。
+
+## 修订冲突
+
+草稿是基于某个修订复制的。如果这期间别的窗口装了更新的修订，这次调用会被拒绝，拒绝
+里列出中间的修订。
+
+按此处理：重新复制最新版，把两边的内容合并进草稿，再调用一次 reload。
+
+## 回退
+
+`reload({ remove: ["mcp:<name>"] })` 移除它，它的函数随之不可调用；修订历史用
+`env.history("mcp:<name>")` 查看。移除不改变任何窗口已经拿到的系统提示，对已移除函
+数的调用会被拒绝，并带上移除它的那次变更。

package/skills/arbor-service/SKILL.md

@@ -0,0 +1,55 @@
+# 接一个常驻服务
+
+服务是一个跑完本窗口还不结束的应用：webhook 接收、爬虫、机器人、worker。`bash` 的后
+台作业随窗口链结束，所以常驻的必须是服务。
+
+框架负责：崩溃后按退避重启、主机重启后重新起来、它自己的目录、日志、按名字注入秘密。
+你负责：写应用、装依赖、写 `svc.json`、决定什么时候停掉或移除。
+
+## 结构
+
+服务是一个目录，里面有 `svc.json` 和应用文件：
+
+```json
+{
+  "command": "node",
+  "args": ["bot.js"],
+  "ports": [8080],
+  "healthCheck": { "path": "/healthz", "port": 8080, "intervalMs": 500, "timeoutMs": 10000 },
+  "secrets": ["BOT_TOKEN"],
+  "restart": { "maxRetries": 5, "backoffMs": 2000 }
+}
+```
+
+- `command`、`args`：怎么启动，在这个目录里运行。
+- `ports`：它监听的端口，窗口和别的服务可以从主机访问。
+- `healthCheck`：reload 等它通过才安装。按 `intervalMs` 轮询
+  `http://127.0.0.1:<port><path>`，`timeoutMs` 内没有 2xx 就算失败。
+- `secrets`：秘密的名字，只写名字；值由主机按名字注入。
+- `restart`：崩溃后最多重试几次，每次之间等多久。
+
+安装后是 `/env/services/<name>/`，目录归服务所有，没有窗口能结束它或回收它。
+
+## 自测
+
+1. 在本窗口工作区里写好应用和 `svc.json`。
+2. 先直接跑：`bash node bot.js`，确认它起来、监听端口、`/healthz` 有响应。
+3. 用 `curl` 或 `bash` 打一次健康检查路径，确认返回 2xx。
+4. 故意让它退出一次，看重启和日志是否符合预期。
+
+## 安装
+
+`reload({ install: ["./<name>"] })`。
+
+reload 把草稿目录复制一份归服务所有，启动它，等健康检查通过，然后才安装。健康检查不
+通过时调用被拒绝，什么都不改变，日志留在服务日志里。
+
+## 失败是输入
+
+崩溃、重启成环、健康检查不过，都会成为一条目标为 `svc:<name>` 的记录事件，和任何外部
+输入一样被派发。主机不替你修。
+
+## 回退
+
+升级是再一次 `reload({ install: ["./<name>"] })`；回退是安装旧的那一版，修订历史用
+`env.history("svc:<name>")` 查看。`reload({ remove: ["service:<name>"] })` 停掉并移除它。

package/skills/arbor-settings/SKILL.md

@@ -0,0 +1,52 @@
+# 改设置
+
+设置是 `/env/settings.json`，和环境里其他项一样是一个有修订的项。模型可以改关于自己的
+一切：身份、通用规则、judge 模式、阈值、模型分层。两样不能碰：秘密的值，以及框架内置
+的技能。
+
+## 结构
+
+```json
+{
+  "identity": "你是部署在内部集群上的运维 agent。",
+  "generalRules": ["窗口是一次性的。", "发送不是必须的。"],
+  "modelTiers": { "fast": "claude-sonnet-4-5", "deep": "claude-opus-4-5" },
+  "defaultTier": "fast",
+  "window": { "idleSeconds": 300, "contextTokens": 200000, "reserveTokens": 4000 },
+  "snapshot": { "minIntervalMs": 600000 },
+  "workspaces": { "retentionMs": 604800000 },
+  "judge": { "modes": { "route": "on", "notice": "shadow" }, "maxCandidates": 8 },
+  "secrets": ["BOT_TOKEN"]
+}
+```
+
+- `identity`：`<identity>` 一节，为空时不渲染，没有默认句。
+- `generalRules`：`<agent>` 一节的通用规则，一行一条。
+- `modelTiers`、`defaultTier`：每一层映射到后端能跑的一个模型。
+- `window`：空闲秒数、上下文预算、预留 token。
+- `snapshot.minIntervalMs`：系统提示和记忆快照最多多久重建一次。
+- `workspaces.retentionMs`：窗口链最后一个窗口结束后，它的工作区目录再保留多久由主机回收；不设就不回收。
+- `judge.modes`：每个决策是 `on`、`off` 还是 `shadow`。
+- `secrets`：允许使用的秘密的名字，只写名字，不写值。
+
+## 自测
+
+1. `read /env/settings.json` 看当前值。
+2. 在本窗口工作区里改：`cp /env/settings.json .`，再 `edit`。
+3. 用 `env.list` 确认改动落在哪一项上，用 `env.history("set:settings")` 看改过什么。
+
+## 安装
+
+`reload({ install: ["./settings.json"] })`。
+
+身份和通用规则不是变更增量：它们属于系统提示，从下一个快照 epoch 起生效。运行中的窗口
+拿到的还是一次 epoch 冻结的那一版。
+
+## 修订冲突
+
+草稿是基于某个修订复制的。如果这期间别的窗口改过设置，这次调用会被拒绝，拒绝里列出中
+间的修订。重新复制最新版，合并后再调用一次。
+
+## 回退
+
+装回旧的那一版就是重新安装它；修订历史用 `env.history("set:settings")` 查看。

package/skills/arbor-skill/SKILL.md

@@ -0,0 +1,43 @@
+# 写一个技能
+
+技能是一份过程说明：模型按需读取它，按它的步骤做。一个技能是一个目录，里面有
+SKILL.md，以及它用到的脚本和文件。
+
+## 结构
+
+安装后的位置是 `/env/skills/<name>/`，name 用小写字母、数字和连字符。
+
+SKILL.md 的第一行是一级标题，第二段是这一行说明：它做什么、什么时候用。系统提示
+和每次环境变更只用这一行，所以写清楚做什么，不写怎么做。
+
+正文按步骤写：每步一个动作，带上要调用的工具或命令。不要写背景说明，不要重复框架
+的规则，那些在系统提示里。
+
+技能自带的脚本用 `bash` 从 `/env/skills/<name>/` 运行，用的是本窗口自己的权限。
+
+## 自测
+
+1. 在本窗口工作区里写好：`write SKILL.md` 和脚本。
+2. 读一遍自己写的：`read SKILL.md`。
+3. 跑一遍脚本：`bash ./run.sh`，确认它在这个目录里能跑完。
+4. 看第二段是不是一句话能说完的说明；不是就改短。
+
+## 安装
+
+`reload({ install: ["./<name>"] })`。
+
+install 指向工作区里的草稿目录。reload 校验结构、整体替换、记录一个环境修订，并把
+变更广播给所有运行中的窗口。
+
+## 修订冲突
+
+草稿是基于某个修订复制的。如果这期间别的窗口装了更新的修订，这次调用会被拒绝，拒绝
+里列出中间的修订。
+
+按此处理：`cp -r /env/skills/<name> .` 重新复制最新版，把两边的内容合并进草稿，再
+调用一次 reload。
+
+## 回退
+
+`reload({ remove: ["skill:<name>"] })` 移除它。装回旧版就是重新安装那一版；修订历史用
+`env.history("sk:<name>")` 查看。