@syrkos/filaxis 0.1.0-alpha.10

package/AGENTS.md

@@ -0,0 +1,46 @@
+# Filaxis 包说明书（给使用方 Agent 读）
+
+> 本文件只描述 `@syrkos/filaxis` 包本身，**不接管宿主仓库规范**——你的项目自有其 AGENTS.md。API 签名与详细参考见版本化文档（本文件不复制签名副本，防漂移）。
+
+## 心智模型（补充：流式观察窗）
+
+- **观察窗（Stream Window）**：远端拉模式流反转为**本地推模式滚动窗**——帧号 per-window 单调递增（断连续编不归零）、peek 三模式全非破坏、多消费者游标互不干扰、stale 窗帧保留重连续编、关窗收割流进程。窗是滚动缓冲不是无限历史（完整历史查落盘日志）。
+
+## 心智模型
+
+- **层（Layer）**：一个可执行环境（本机 / SSH 主机 / 容器 / 持久终端）。`stack.connect(descriptor)` 建立或复用。
+- **会话（Session）**：长跑任务。`spawn` 即返，输出双文件落盘 + 热窗口。
+- **观察流（Stream）**：独立 SSH channel 的真流式 tail——观察是廉价的，连接是稀缺的（自动复用主连接）。
+- **两个身份键，两个职责**：连接拓扑指纹管「复用哪条连接」；环境身份键管「这台环境是什么」（同落点经不同跳板路径=同一环境）。
+
+## 核心不变量（执行语义的宪法）
+
+> **没有经过验证的远端终态，就绝不能推导出执行成功；执行结果未知，也绝不能自动重放非幂等操作。**
+
+三条落地形态：
+
+1. **完成哨兵是唯一凭证**：exec 的退出码只认 `__FILAXIS_META_<nonce>` 尾缀（nonce 完整匹配 + 退出码可解析 + 取尾部出现）。无哨兵（断链/远端 kill -9/abort/信号杀）一律 `reject` 附半截现场，Error 挂 `outcome: "unknown"`——绝不 resolve 伪造退出码。
+2. **Abort ≠ 远端已取消**：abort/超时杀的是本地 ssh 进程，远端进程树状态未核实——`AbortError` 同时挂 `outcome: "unknown"`，上层须按未知处理（核实或上报），严禁直接推导远端已停。
+3. **内核零自动重放**：任何失败/未知路径都不自动重试非幂等命令——重放决策属上层（拿到 `outcome=unknown` 后先核实再决策）。
+4. **PTY 会话是有状态资源**：任务 Promise 的生命周期与 PTY 会话可复用生命周期必须分离——当前命令终态未经可信确认（自己 nonce 的 $? 行或 ^C trap 行），同一条 PTY 不得交给下一条命令（四阶段 RUNNING/INTERRUPTING/DRAINING/IDLE；确认不了就销毁重建，绝不定时强行复用）。
+
+## 防误用契约（用错就是生产事故的六条）
+
+1. **终止即请求、死亡须核实**：`stop()` 返回 `{status: "exited" | "stopped" | "unknown"}`。`unknown`（断线/分区/核实超时）**不是成功也不是失败**——严禁当已清理继续往下走；应重试核实或显式上报。
+2. **退出码是数据**：`exec` 非零退出码**不抛异常**（如实在 `exitCode` 字段）；只有「无法执行」（超时/abort/连接死）才 reject。别把两者混为一谈。
+3. **`ready()` 有窗口语义**：先回溯热窗口再等增量——spawn 与 ready 之间输出的标记不会漏；若报「标记可能已滚出」，查落盘日志，别盲目重试。
+4. **通道语义**：缺省 `channel:"exec"`（stdout/stderr 分离、层上下文拼装）；`channel:"pty"` 继承层内交互状态（su/cd），但 **stderr 混流是终端物理语义**，不是 bug。多跳 PTY 链与交互式二次跳转对 exec 通道**显式拒绝**——这是诚实行为，换 pty 或把途径机收敛为 `-J`。
+5. **跨流顺序**：双文件落盘后的聚合序是**本地到达序**（近似），不承诺进程真实写入序。
+6. **方言适配自动进行**：base64/sha256 按连接探测缓存（OPNsense/Alpine 形态已测）——但你自己的远端脚本原语若依赖 GNU 方言，请同样探测，勿硬编码。
+
+## 环境规格与漂移
+
+探测结果只存蒸馏值（版本/有无/型号）；`upsert` 指纹不一致会标 **stale 且不覆盖**——重探是显式决定。nvidia-smi 驱动不通信的失败文案**不会**被记成 GPU 型号。
+
+## 安全边界
+
+host key 缺省 TOFU（accept-new）；高价值环境请配 `hostKeyPolicy:"strict"` + `knownHostsFile`。凭据只传**路径**；所有渲染与日志永不含密钥内容。高危操作授权属你的策略层，本包不越权预设。
+
+## 能力探测
+
+部署环境缺什么，`await stack.features()` 说了算（`mux/sftp/persistent/transports/stderrSeparated`）——降级不靠猜。

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,10 @@
+Syrkos Filaxis (牵丝)
+Copyright 2026 Corolin (YiCheng Ji) and Syrkos Contributors.
+
+This product includes software developed as part of the Syrkos (漩核) project.
+
+"Syrkos", "漩核", "Filaxis", and "牵丝" are brand names claimed by Corolin (YiCheng Ji).
+
+The Apache License, Version 2.0, does not grant trademark rights except as provided in Section 6 of that license.
+
+All trademark rights, if any, are reserved by their respective owners.

package/README.md

@@ -0,0 +1,61 @@
+# 牵丝 Filaxis
+
+**千里一线，执行有迹。—— Connect · Execute · Observe · Reattach**
+
+面向自动化与 Agent 的远程执行运行时 SDK（Syrkos · 漩核旗下）。TypeScript 编写，Bun 与 Node LTS 双运行时，Windows 与 Linux 同构。
+
+```ts
+import { RuntimeStack } from "@syrkos/filaxis";
+
+const stack = new RuntimeStack();
+const host = await stack.connect({ driver: "ssh", target: "my-server" });
+
+// exec：退出码是数据，失败是异常；stdout/stderr 物理分离
+const r = await host.exec("uname -a", { timeoutMs: 10_000 });
+console.log(r.stdout, r.stderr, r.exitCode, r.effectiveUser);
+
+// 长跑会话：spawn 即返 → 就绪握手 → 双流观察 → watcher → 终态核实
+const cap = await host.execSession("tcpdump -i eth0 -c 100 -w /tmp/x.pcap");
+await host.sessions /* tail / watch / stop——见示例 */;
+
+// 事件（零消息队列依赖——消费方自行接队列/看板）
+stack.events.on("exit", (e) => console.log("session", e.sessionId, "exit", e.exitCode));
+```
+
+## 能力矩阵
+
+| 能力 | 说明 |
+|---|---|
+| 多 Transport 统一语义 | `local` / `ssh` / `tmux` 内置 + `registerDriver()` 开放注册；docker/k8s/teleport 经 launchCmd 接入 |
+| exec 双通道 | 缺省非 PTY 通道（stdout/stderr 物理分离 + 层上下文拼装）；`channel:"pty"` 继承层内交互状态 |
+| 长跑会话生命周期 | spawn 即返、双文件 `.out/.err` 落盘、热窗口、行级 watcher、**终态三态** `exited/stopped/unknown` |
+| ready() 就绪握手 | 回溯匹配热窗口（快输出进程竞态根治）；滚出判定**有据**（evictedCount） |
+| 观察流 | 独立 SSH channel 真流式直推（无轮询）；ControlMaster 复用；注意力衰减回收 |
+| 持久会话 | tmux 后端 terminalId 跨进程 re-attach + cwd 恢复 |
+| 文件传输 | `putFile/getFile` base64 管道分块 + size/sha256 双校验 + **方言适配**（GNU/BSD/busybox——OPNsense/Alpine 不再必错） |
+| 环境规格 | 两段式自发现（语言/GPU/关键包）蒸馏落盘；`matchLayers({needs})` 按需选层；指纹漂移标 stale |
+| 连接治理 | 连接拓扑指纹复用（同拓扑零重建）；3 次退避自动重连；层状态机与退化哨兵 |
+| 安全边界 | host key 策略显式（tofu 缺省/strict+known_hosts）；凭据只传路径永不外泄；渲染永不含密钥内容 |
+
+## 安装与运行时
+
+```bash
+bun add @syrkos/filaxis    # 或 npm install @syrkos/filaxis
+```
+
+- 运行时：Bun ≥1.x / Node LTS（内核统一 `node:` 标准库，零 runtime 专有 API——CI lint 断言）
+- npm 依赖：**零**（`dependencies` 为空是 AC 门禁项，见 `bun run check:boundaries`）
+- 系统依赖按能力分列（`stack.features()` 运行时探测）：`ssh`≥7.3 全功能（`-J`）、`tmux` 仅持久会话（缺席自动降级非持久）、`sftp` 仅传输快路径
+
+## 语义契约要点（使用前必读）
+
+详见包内 [AGENTS.md](./AGENTS.md)——**终止即请求、死亡须核实**（`unknown` 不是失败也不是成功）；退出码非零是数据不是异常；PTY 通道 stderr 混流是终端语义；跨流聚合序为到达序。
+
+## 示例与技能剧本
+
+- [examples/](./examples/)：跨主机诊断 / 长跑观察 / Agent 工具面最小封装（三可运行示例）
+- [docs/skills/](./docs/skills/)：场景操作剧本（给人也给 Agent）
+
+## 许可
+
+[Apache-2.0](./LICENSE) + [NOTICE](./NOTICE)（牵丝 Filaxis / Syrkos · 漩核 品牌归属声明）。

package/bin/filaxis.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env bun
+/**
+ * filaxis CLI — 极简宿主形态（第六季盲测摩擦点 ①：SDK 需要 bun -e 手拼几十行 TS——
+ * Agent 先跟宿主 Shell 引号搏斗。CLI 一行替代：filaxis exec|cat|edit|observe）
+ *
+ * 零依赖手写 argv。远端目标统一 --host（ssh）；缺省 local。
+ */
+import { RuntimeStack, LocalRuntimeDriver, SshPtyDriver, editFile, discoverLayer } from "../src/index.js";
+import type { RuntimeDriver } from "../src/driver.js";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+function parseOpts(argv: string[]): {
+    host?: string; user?: string; port?: number; key?: string;
+    timeout?: number; duration?: number; stream?: string; all?: boolean;
+    positional: string[];
+} {
+    const o: ReturnType<typeof parseOpts> = { positional: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i]!;
+        if (a === "--") continue; // 命令分隔符（可省）
+        switch (a) {
+            case "--host": o.host = argv[++i]; break;
+            case "--user": o.user = argv[++i]; break;
+            case "--port": o.port = parseInt(argv[++i]!, 10); break;
+            case "--key": o.key = argv[++i]; break;
+            case "--timeout": o.timeout = parseInt(argv[++i]!, 10); break;
+            case "--duration": o.duration = parseInt(argv[++i]!, 10); break;
+            case "--stream": o.stream = argv[++i]; break;
+            case "--all": o.all = true; break;
+            default: o.positional.push(a);
+        }
+    }
+    return o;
+}
+
+async function driverFor(opts: ReturnType<typeof parseOpts>): Promise<RuntimeDriver> {
+    if (opts.host) {
+        return new SshPtyDriver({
+            driver: "ssh", target: opts.host,
+            config: { connParams: { user: opts.user, port: opts.port, keyFile: opts.key } },
+        });
+    }
+    return new LocalRuntimeDriver();
+}
+
+async function main() {
+    const o = parseOpts(args.slice(1));
+    const drv = await driverFor(o);
+    try {
+        switch (cmd) {
+            case "exec": {
+                const r = await drv.exec(o.positional.join(" "), { timeoutMs: o.timeout ?? 120_000 });
+                process.stdout.write(r.stdout);
+                if (r.stderr) process.stderr.write(r.stderr);
+                console.error(`\n[exit=${r.exitCode} user=${r.effectiveUser ?? "?"}]`);
+                process.exit(r.exitCode);
+                break;
+            }
+            case "cat": {
+                const [p] = o.positional;
+                if (!p) throw new Error("用法: filaxis cat [--host ...] <path>");
+                process.stdout.write(await drv.fs.readFile(p));
+                break;
+            }
+            case "edit": {
+                const [p, old, newStr] = o.positional;
+                if (!p || old === undefined || newStr === undefined) {
+                    throw new Error("用法: filaxis edit [--host ...] <path> <old> <new> [--all]");
+                }
+                const r = await editFile(drv, p, old, newStr, { all: o.all });
+                console.log(`edited: ${r.path} 替换 ${r.occurrences} 处，${r.bytesBefore}B → ${r.bytesAfter}B`);
+                break;
+            }
+            case "observe": {
+                const h = await drv.execSession(o.positional.join(" "), { name: "cli-observe" });
+                await new Promise((r) => setTimeout(r, o.duration ?? 8000));
+                const lines = (drv as unknown as {
+                    sessions?: { tailLines?: (id: string, n?: number) => Array<{ stream: string; text: string }> };
+                }).sessions?.tailLines?.(h.sessionId, 500)
+                    ?? (await drv.tailSession(h.sessionId, 500)).map((t) => ({ stream: "stdout", text: t }));
+                const filtered = (o.stream && o.stream !== "both") ? lines.filter((l) => l.stream === o.stream) : lines;
+                for (const l of filtered) console.log(`[${l.stream}] ${l.text}`);
+                await drv.stopSession(h.sessionId).catch(() => undefined);
+                break;
+            }
+            case "probe": {
+                const r = await discoverLayer(drv, { skipStage2: false });
+                console.log(JSON.stringify({ key: r.key, spec: r.spec, note: r.probeNote }, null, 2));
+                break;
+            }
+            default:
+                console.error(`filaxis CLI — 千里一线，执行有迹
+用法:
+  filaxis exec    [--host u@h [--port N] [--key F]] [--timeout MS] -- <command>
+  filaxis cat     [--host ...] <path>
+  filaxis edit    [--host ...] <path> <old> <new> [--all]   # 受控编辑（TOCTOU 锁+精确替换）
+  filaxis observe [--host ...] [--stream stderr|stdout|both] [--duration MS] -- <command>
+  filaxis probe   [--host ...]                                     # 两段式环境探测
+缺省 --host 为 local。`);
+                process.exit(cmd ? 1 : 0);
+        }
+    } finally {
+        await drv.destroy().catch(() => undefined);
+    }
+}
+
+void main().catch((err) => {
+    console.error(`[filaxis] ${(err as Error).message}`);
+    process.exit(1);
+});

package/dist/agent-toolkit.d.ts

@@ -0,0 +1,99 @@
+/**
+ * agent-toolkit.ts — 原生 Agent 工具集（Gemini 试用反馈 #3）
+ *
+ * 一行 `createAgentToolkit(stack)` 生成 LLM 工具面（run_command / spawn_and_observe /
+ * stop_and_verify）——OpenAI/Anthropic/Vercel AI SDK 通吃的 {tools, handlers} 双层结构：
+ * 定义层喂模型，执行层留宿主（桥到任意框架）。语义契约（退出码是数据/终态三态/
+ * 就绪握手）由内核承载，宿主零胶水。
+ */
+import type { RuntimeStack } from "./runtime-stack.js";
+import type { RuntimeDriver } from "./driver.js";
+export interface AgentToolDef {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface AgentToolHandlers {
+    run_command(args: {
+        command: string;
+        timeout_ms?: number;
+        layer?: string;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exit_code: number;
+        effective_user?: string;
+    }>;
+    read_file(args: {
+        path: string;
+        layer?: string;
+    }): Promise<{
+        path: string;
+        content: string;
+        size: number;
+        mtime_ms: number;
+    }>;
+    edit_file(args: {
+        path: string;
+        old: string;
+        new: string;
+        all?: boolean;
+        layer?: string;
+    }): Promise<{
+        path: string;
+        occurrences: number;
+        bytes_before: number;
+        bytes_after: number;
+    }>;
+    observe_stream(args: {
+        command: string;
+        duration_ms?: number;
+        stream?: "stdout" | "stderr" | "both";
+        name?: string;
+    }): Promise<{
+        session_id: string;
+        lines: Array<{
+            stream: string;
+            text: string;
+        }>;
+    }>;
+    spawn_and_observe(args: {
+        command: string;
+        ready_marker?: string;
+        error_pattern?: string;
+        name?: string;
+    }): Promise<{
+        session_id: string;
+        log_base: string;
+        note?: string;
+    }>;
+    stop_and_verify(args: {
+        session_id: string;
+    }): Promise<{
+        status: "exited" | "stopped" | "unknown";
+        exit_code?: number | null;
+        note?: string;
+    }>;
+}
+export interface AgentToolkit {
+    tools: AgentToolDef[];
+    handlers: AgentToolHandlers;
+    /** 工具面绑定的层（缺省 local；远端层经 stack.connect 后传入重绑） */
+    readonly layer: Promise<RuntimeDriver>;
+}
+export interface AgentToolkitOptions {
+    /** 层描述符（缺省 local）；也可直接传已连接的 driver */
+    descriptor?: {
+        driver: string;
+        target?: string;
+        config?: Record<string, unknown>;
+    };
+    driver?: RuntimeDriver;
+    /** 就绪握手与 watcher 轮询的超时上限 */
+    readyTimeoutMs?: number;
+}
+/** 生成 Agent 工具集（定义层 + 执行层；宿主桥接到任意 LLM 框架） */
+export declare function createAgentToolkit(stack: RuntimeStack, opts?: AgentToolkitOptions): AgentToolkit;

package/dist/dialect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * dialect.ts — 远端命令方言适配层（FEAT-14：GNU · BSD · busybox 三族原语探测与渲染）
+ *
+ * 动机（生产实锤）：`base64 -w 0` 为纯 GNU 方言——FreeBSD/OPNsense 的 base64
+ * 不认 `-w`（BSD 用 `-b`，解码历史差异 `-d`/`-D`）；sha256 工具 Linux=sha256sum /
+ * FreeBSD=/sbin/sha256 -q / 精简容器=busybox 或 openssl dgst。目标环境
+ * （OPNsense/Alpine）不探测必错。探测结果**按连接缓存**（探测键由调用方持有）。
+ */
+import type { ExecResult } from "./driver.js";
+export type DialectFamily = "gnu" | "bsd" | "busybox" | "openssl-fallback" | "unknown";
+/** 一套已探测的远端原语（渲染为 argv 前缀，拼接数据参数后执行） */
+export interface RemoteDialect {
+    family: DialectFamily;
+    /** 编码（无换行输出）：["base64","-w","0"]（GNU）/ ["base64"]（BSD·默认不折行） */
+    base64Encode: string[];
+    /** 解码：GNU ["base64","-d"] / BSD ["base64","-D"] */
+    base64Decode: string[];
+    /** sha256 摘要：["sha256sum"] / ["sha256","-q"] / busybox ["sha256sum"] / openssl ["openssl","dgst","-sha256"] */
+    sha256: string[];
+}
+export type ExecFn = (command: string) => Promise<Pick<ExecResult, "stdout" | "exitCode">>;
+/** 探测失败时的兜底：全部原语标记不可用（显式，不静默用错方言） */
+export declare const NULL_DIALECT: RemoteDialect;
+/** 探测远端方言（每命令独立判定；缺原语=该族标记跳过，非报错） */
+export declare function probeDialect(exec: ExecFn): Promise<RemoteDialect>;
+/** 按连接缓存：探测键（调用方用连接身份）→ 方言 */
+export declare class DialectCache {
+    private cache;
+    get(probeKey: string, exec: ExecFn, force?: boolean): Promise<RemoteDialect>;
+    invalidate(probeKey?: string): void;
+}