@syrkos/filaxis 0.1.0-alpha.12 → 0.1.0-alpha.13

package/dist/agent-toolkit.d.ts

@@ -1,10 +1,13 @@
 /**
- * agent-toolkit.ts — 原生 Agent 工具集（Gemini 试用反馈 #3）
+ * agent-toolkit.ts — 原生 Agent 工具集（Gemini 试用反馈 #3 + 第十季层族）
  *
- * 一行 `createAgentToolkit(stack)` 生成 LLM 工具面（run_command / spawn_and_observe /
- * stop_and_verify）——OpenAI/Anthropic/Vercel AI SDK 通吃的 {tools, handlers} 双层结构：
- * 定义层喂模型，执行层留宿主（桥到任意框架）。语义契约（退出码是数据/终态三态/
- * 就绪握手）由内核承载，宿主零胶水。
+ * 一行 `createAgentToolkit(stack)` 生成 LLM 工具面——OpenAI/Anthropic/Vercel AI SDK
+ * 通吃的 {tools, handlers} 双层结构：定义层喂模型，执行层留宿主（桥到任意框架）。
+ * 语义契约（退出码是数据/终态三态/就绪握手）由内核承载，宿主零胶水。
+ *
+ * 第十季层族：执行类工具带可选 layer 参数（缺省=默认层——最近 push 的命名层；
+ * 未用层族时与旧行为一致，零破坏）；push_ssh/push_into/list_layers/remove_layer
+ * 操作 RuntimeStack 命名层注册表（Paramiko 式句柄寻址——栈/焦点弱化归消费方）。
  */
 import type { RuntimeStack } from "./runtime-stack.js";
 import type { RuntimeDriver } from "./driver.js";
@@ -53,6 +56,7 @@ export interface AgentToolHandlers {
         duration_ms?: number;
         stream?: "stdout" | "stderr" | "both";
         name?: string;
+        layer?: string;
     }): Promise<{
         session_id: string;
         lines: Array<{
@@ -65,6 +69,7 @@ export interface AgentToolHandlers {
         ready_marker?: string;
         error_pattern?: string;
         name?: string;
+        layer?: string;
     }): Promise<{
         session_id: string;
         log_base: string;
@@ -77,6 +82,42 @@ export interface AgentToolHandlers {
         exit_code?: number | null;
         note?: string;
     }>;
+    push_ssh(args: {
+        host: string;
+        port?: number;
+        user?: string;
+        key?: string;
+        jump?: string;
+        name?: string;
+    }): Promise<{
+        layer: string;
+        reused: boolean;
+        reused_from?: string;
+        note?: string;
+    }>;
+    push_into(args: {
+        enter_cmd: string;
+        label?: string;
+        from?: string;
+        name?: string;
+    }): Promise<{
+        layer: string;
+        target?: string;
+    }>;
+    list_layers(args: Record<string, never>): Promise<{
+        text: string;
+        layers: Array<{
+            name: string;
+            driver: string;
+            target?: string;
+        }>;
+    }>;
+    remove_layer(args: {
+        name: string;
+        destroy?: boolean;
+    }): Promise<{
+        removed: string;
+    }>;
 }
 export interface AgentToolkit {
     tools: AgentToolDef[];

package/dist/file-edit.d.ts

@@ -6,10 +6,16 @@
  *
  * 第七季盲测反馈（B2 逐秒拆解）：旧实现一次 editFile = 5 次串行 SSH 往返
  * （stat/read/stat/write/stat），Windows 无 ControlMaster 下放大到 15s+。
- * 本版：合成 **2 次往返**（读+戳 1 次；**远端 CAS 原子写回** 1 次——GPT 并发
- * 安全意见采纳：「最后一次校验与写入放进同一个远端受控操作」——戳比对与写回
- * 在远端一条命令内原子完成，杜绝 A/B 丢失更新）+ 方言适配（stat/base64 三族，
- * 每 driver 缓存一次探测）。大文件（base64>30KB）自动回落旧 5 次路径（fs 层）。
+ * 第七季版合成「读+戳 1 次 + 远端 CAS 原子写回 1 次」——但方言探测（base64
+ * -w 0/-d/-D）是独立往返，SDK 常驻内存下有 dialectCache 掩护，**CLI 每次冷启动
+ * 实为 3 次物理往返**（第十季 B5 轨迹实锤：3×SSH 握手 ≈11.4s 突破宿主 10s 后台
+ * 阈值，多耗 3 轮轮询）。
+ *
+ * 本版（第十季）：**真 2 次往返**——方言探测合成进读往返（① stat/sha 戳 +
+ * base64 -d 探测 + 文件读取一次带回；② CAS 写回用已确定 argv）。编码侧无需
+ * 探测：折行输出由解析侧 \s+ 归一消化（base64 < file 全方言通吃）；解码侧
+ * 不用 `base64 -d || base64 -D` 赌 fallback（GPT 否决：双解码器共用 stdin，
+ * 首个消费后第二个拿不到完整载荷）。大文件（base64>30KB）自动回落 fs 层路径。
  *
  * **仅适用 UTF-8 文本**（readFile 返回 UTF-8 字符串；二进制文件的编辑走
  * readBase64 + 消费方自行改写 + writeFile）。
@@ -31,8 +37,10 @@ export declare class EditConflictError extends Error {
     constructor(message: string);
 }
 /**
- * 受控编辑（合成 2 次往返 + 远端 CAS 原子写回）：
- * ① 读+戳（1 次往返）：`stat 戳; __FXS__; base64 读` —— 拿 (mtime,size)+全文
+ * 受控编辑（真 2 次往返 + 远端 CAS 原子写回）：
+ * ① 读+戳+方言探测（1 次往返）：`stat 戳; sha 戳; __FXS__; base64 -d 探测;
+ *    __FXD__; base64 < file` —— (mtime,size)+全文+解码 argv 一次带回
+ *    （__FXD__ 含下划线不在 base64 字母表——与 __FXS__ 同款防撞）
  * ② 精确替换（本地）：0 命中/多处命中（未开 all）拒绝
  * ③ CAS 原子写回（1 次往返）：远端一条命令内完成「戳比对 + tmp 写 + mv 原子替换 + 新戳回执」
  *    —— 戳不符（他人先写）→ EditConflictError；写后回执新戳

package/dist/index.js

@@ -1182,7 +1182,7 @@ class PtyLink {
   registerFallbackStep() {
     const step = String(this.fallbackSteps.size);
     this.fallbackSteps.add(step);
-    return `; echo __FILAXIS_FB_${this.fallbackNonce}_${step}_$?_$RANDOM`;
+    return `; echo __FILAXIS_FB_${this.fallbackNonce}_${step}_$?_$$`;
   }
   attach(args) {
     this.fallbackNonce = crypto4.randomBytes(16).toString("hex");
@@ -1232,7 +1232,7 @@ ${raw.slice(-1500)}` : `${reason}
     this.fallbackSeen = undefined;
     if (!this.pendingExitFailure)
       await this.waitQuiet();
-    this.send(`stty -echo -ixon cols 500 rows 50; export PS1= PS2=; echo PTYRDY_$RANDOM$RANDOM_$(id -un 2>/dev/null)
+    this.send(`stty -echo -ixon cols 500 rows 50; export PS1= PS2=; echo PTYRDY_$$_$(id -un 2>/dev/null)
 `);
     try {
       await new Promise((resolve, reject) => {
@@ -2612,6 +2612,8 @@ class RuntimeFactory {
 }
 // src/runtime-stack.ts
 import { spawn as spawn5 } from "node:child_process";
+import * as os from "node:os";
+init_ssh_helpers();
 class RuntimeStack {
   static driverCache = new Map;
   events = new EventBus;
@@ -2631,12 +2633,15 @@ class RuntimeStack {
       cwd: d.cwd,
       capabilities: d.capabilities,
       cfg: {
+        pty: c.pty,
+        connParams: c.connParams,
+        sshHops: c.sshHops,
+        enters: enterStepsOf(c).map((s) => s.cmd),
         launchCmd: c.launchCmd,
         runtime: c.runtime,
         shell: c.shell,
         namespace: c.namespace,
-        sshOptions: c.sshOptions,
-        connParams: c.connParams
+        sshOptions: c.sshOptions
       }
     });
   }
@@ -2663,6 +2668,185 @@ class RuntimeStack {
     this.factory.registerDriver(type, f);
     this.featuresCache = null;
   }
+  namedLayers = new Map;
+  activeName;
+  get layers() {
+    return this.namedLayers;
+  }
+  get active() {
+    return this.activeName ? this.namedLayers.get(this.activeName)?.driver : undefined;
+  }
+  get activeLayer() {
+    return this.activeName ? this.namedLayers.get(this.activeName) : undefined;
+  }
+  async addLayer(name, descriptorOrDriver) {
+    this.assertNotDupName(name);
+    if (this.isDriver(descriptorOrDriver)) {
+      const driver = descriptorOrDriver;
+      const handle = { name, descriptor: driver.descriptor, driver };
+      this.namedLayers.set(name, handle);
+      this.activeName = name;
+      return { handle, reused: false };
+    }
+    const descriptor = descriptorOrDriver;
+    const hit = await this.findIdentityHit(descriptor);
+    if (hit) {
+      const reused = hit.terminal || await this.verifyLanding(hit.handle, hopHost(layerPathIdentities(descriptor).at(-1) ?? ""));
+      if (reused) {
+        this.log.info(`[Filaxis] 层 '${name}' 落点已由 '${hit.handle.name}' 持有——幂等复用（不重复建连）`);
+        return { handle: hit.handle, reused: true, reusedFrom: hit.handle.name };
+      }
+      throw new Error(`层名 '${name}' 的落点 identity 命中既有层 '${hit.handle.name}' 的途经节点，且落点校验不符` + `（期望 ${hopHost(layerPathIdentities(descriptor).at(-1) ?? "?")}，实测 ${hit.handle.actualHostname ?? "?"}）` + `（宁重连不错主机）：请检查连接参数后重试`);
+    }
+    const driver = await this.connect(descriptor);
+    const handle = { name, descriptor: driver.descriptor, driver };
+    this.namedLayers.set(name, handle);
+    this.activeName = name;
+    return { handle, reused: false };
+  }
+  async layerInto(from, name, enterCmd, opts = {}) {
+    this.assertNotDupName(name);
+    const src = this.requireLayer(from);
+    const pushInto = src.driver.pushInto;
+    if (typeof pushInto !== "function") {
+      throw new Error(`层 '${from}'（${src.descriptor.driver}）不支持派生进入——需 ssh PTY 形态（pushInto 缺席）`);
+    }
+    const driver = await pushInto.call(src.driver, enterCmd, opts.label ?? enterCmd.slice(0, 30));
+    const handle = { name, descriptor: driver.descriptor, driver };
+    this.namedLayers.set(name, handle);
+    this.activeName = name;
+    return handle;
+  }
+  async sshInto(from, name, target, connParams) {
+    this.assertNotDupName(name);
+    const src = this.requireLayer(from);
+    const hop = connParams ? { host: target, conn: connParams } : target;
+    const hit = await this.findIdentityHopHit(hop);
+    if (hit) {
+      const reused = hit.terminal || await this.verifyLanding(hit.handle, hopHost(hop));
+      if (reused) {
+        this.log.info(`[Filaxis] 层 '${name}' 落点已由 '${hit.handle.name}' 持有——幂等复用（不重复建连）`);
+        return { handle: hit.handle, reused: true, reusedFrom: hit.handle.name };
+      }
+      throw new Error(`层名 '${name}' 的落点 identity 命中既有层 '${hit.handle.name}' 的途经节点，且落点校验不符` + `（期望 ${hopHost(hop)}，实测 ${hit.handle.actualHostname ?? "?"}）——宁重连不错主机：请检查连接参数后重试`);
+    }
+    const pushChild = src.driver.pushChild;
+    if (typeof pushChild !== "function") {
+      throw new Error(`层 '${from}'（${src.descriptor.driver}）不支持链式 ssh 派生——需 ssh PTY 形态（pushChild 缺席）`);
+    }
+    const driver = await pushChild.call(src.driver, hop);
+    const handle = { name, descriptor: driver.descriptor, driver };
+    this.namedLayers.set(name, handle);
+    this.activeName = name;
+    return { handle, reused: false };
+  }
+  layer(name) {
+    return this.requireLayer(name);
+  }
+  setActive(name) {
+    const h = this.requireLayer(name);
+    this.activeName = name;
+    return h;
+  }
+  async removeLayer(name, opts = {}) {
+    const h = this.requireLayer(name);
+    this.namedLayers.delete(name);
+    if (opts.destroy) {
+      RuntimeStack.evictDriver(h.descriptor);
+      await h.driver.destroy().catch(() => {
+        return;
+      });
+    }
+    if (this.activeName === name) {
+      this.activeName = [...this.namedLayers.keys()].at(-1);
+    }
+  }
+  layerText() {
+    if (this.namedLayers.size === 0)
+      return "Filaxis 命名层：（空——addLayer/layerInto 注册）";
+    const lines = [];
+    for (const h of this.namedLayers.values()) {
+      const d = h.driver;
+      const base = h.descriptor.driver === "local" ? `${os.hostname()}[local]` : layerDisplayName(h.descriptor);
+      const state = d.reconnecting === true ? " ↻连中" : d.layerShellGone ? " ⚠退化（内层 shell 已退出，勿在此层执行）" : d.alive === false ? " ⚠死（removeLayer 后按原参数重建）" : "";
+      const user = d.effectiveUser ? ` · ${d.effectiveUser}$` : "";
+      const mark = h.name === this.activeName ? " ◀ 默认" : "";
+      lines.push(`  ${h.name}: ${base}${user}${state}${mark}`);
+    }
+    return ["Filaxis 命名层（工具缺省落【默认层】；显式按名寻址任意层）：", ...lines].join(`
+`);
+  }
+  snapshot() {
+    return {
+      layers: [...this.namedLayers.values()].map((h) => ({ name: h.name, descriptor: h.descriptor })),
+      active: this.activeName
+    };
+  }
+  async restore(snap) {
+    for (const { name, descriptor } of snap.layers) {
+      if (this.namedLayers.has(name))
+        continue;
+      const driver = await this.connect(descriptor);
+      this.namedLayers.set(name, { name, descriptor: driver.descriptor, driver });
+    }
+    if (snap.active && this.namedLayers.has(snap.active))
+      this.activeName = snap.active;
+  }
+  assertNotDupName(name) {
+    if (this.namedLayers.has(name)) {
+      throw new Error(`层名 '${name}' 已占用（既有：${[...this.namedLayers.keys()].join(", ")}）——换名或先 removeLayer`);
+    }
+  }
+  requireLayer(name) {
+    const h = this.namedLayers.get(name);
+    if (!h) {
+      throw new Error(`层 '${name}' 不存在（既有：${[...this.namedLayers.keys()].join(", ") || "空"}）`);
+    }
+    return h;
+  }
+  isDriver(x) {
+    return typeof x.exec === "function";
+  }
+  async findIdentityHit(descriptor) {
+    if (enterStepsOf(descriptor.config ?? {}).length > 0)
+      return;
+    const dest = layerPathIdentities(descriptor).at(-1);
+    if (!dest)
+      return;
+    return this.findIdentityHopHit(dest);
+  }
+  async findIdentityHopHit(dest) {
+    const destId = await resolveSshIdentity(dest);
+    if (!destId || destId.startsWith("unresolved:")) {
+      return;
+    }
+    for (const h of this.namedLayers.values()) {
+      if (enterStepsOf(h.descriptor.config ?? {}).length > 0)
+        continue;
+      const path = layerPathIdentities(h.descriptor);
+      for (let i = 0;i < path.length; i++) {
+        if (await resolveSshIdentity(path[i]) === destId) {
+          return { handle: h, terminal: i === path.length - 1 };
+        }
+      }
+    }
+    return;
+  }
+  async verifyLanding(hit, expectedHost) {
+    if (!expectedHost)
+      return true;
+    const d = hit.driver;
+    if (typeof d.exec !== "function")
+      return true;
+    try {
+      hit.actualHostname ??= ((await d.exec("hostname")).stdout || "").trim().split(`
+`).pop() || "";
+    } catch {
+      return false;
+    }
+    const actual = hit.actualHostname;
+    return Boolean(actual) && (actual.includes(expectedHost) || expectedHost.includes(actual));
+  }
   async features() {
     if (this.featuresCache)
       return this.featuresCache;
@@ -3573,31 +3757,12 @@ var q5 = (s) => `'${s.replace(/'/g, "'\\''")}'`;
 var shellSafe = (s) => !s.includes("'") && !s.includes(`
 `);
 var statCmdOf = (f) => `stat -c '%Y %s' ${f} 2>/dev/null || stat -f '%m %z' ${f} 2>/dev/null`;
-var dialectCache = new Map;
-async function dialectOf(drv) {
-  const key = JSON.stringify(drv.descriptor);
-  const hit = dialectCache.get(key);
-  if (hit)
-    return hit;
-  const probe = await drv.exec("echo FX2=$(printf filaxis | base64 -w 0 2>/dev/null | head -c 8);" + "echo FX3=$(printf ZmlsYXhpcw== | base64 -d 2>/dev/null | head -c 7);" + "echo FX4=$(printf ZmlsYXhpcw== | base64 -D 2>/dev/null | head -c 7)", { timeoutMs: 15000 });
-  const out = probe.stdout || "";
-  const b64Gnu = /FX2=ZmlsYXhp/.test(out);
-  const decD = /FX4=filaxis/.test(out);
-  const d = {
-    statCmd: "",
-    enc: b64Gnu ? "base64 -w 0" : "base64",
-    dec: decD ? "base64 -D" : "base64 -d",
-    shaCmd: `{ sha256sum ${"{f}"} 2>/dev/null || sha256 -q ${"{f}"} 2>/dev/null || openssl dgst -sha256 ${"{f}"} 2>/dev/null | tail -1; } | head -c 12`
-  };
-  dialectCache.set(key, d);
-  return d;
-}
+var shaCmdOf = (f) => `{ sha256sum ${f} 2>/dev/null || sha256 -q ${f} 2>/dev/null || openssl dgst -sha256 ${f} 2>/dev/null | tail -1; } | head -c 12`;
 async function editFile(drv, path, oldStr, newStr, opts = {}) {
-  const dialect = await dialectOf(drv);
   const qp = q5(path);
-  const readCmd = `${statCmdOf(qp)}; ${dialect.shaCmd.replace(/\{f\}/g, qp)}; echo __FXS__; ${dialect.enc} ${qp} 2>/dev/null`;
+  const readCmd = `${statCmdOf(qp)}; ${shaCmdOf(qp)}; echo __FXS__; ` + `printf ZmlsYXhpcw== | base64 -d 2>/dev/null; echo __FXD__; base64 < ${qp} 2>/dev/null`;
   const r = await drv.exec(readCmd, { timeoutMs: 30000 });
-  const [stampPart, b64Part] = (r.stdout || "").split("__FXS__");
+  const [stampPart, restPart] = (r.stdout || "").split("__FXS__");
   const originStampRaw = (stampPart ?? "").trim();
   const originLines = originStampRaw.split(/\n/);
   const statStamp = (originLines[0] ?? "").trim();
@@ -3612,7 +3777,9 @@ async function editFile(drv, path, oldStr, newStr, opts = {}) {
   };
   if (!origin.size || !shaStamp)
     throw new Error(`文件不存在或指纹异常: ${path}（${originStampRaw}）`);
-  const content0 = Buffer.from((b64Part ?? "").replace(/\s+/g, ""), "base64").toString("utf-8");
+  const [decPart, b64Part = ""] = (restPart ?? "").split("__FXD__");
+  const dec = (decPart ?? "").trim() === "filaxis" ? "base64 -d" : "base64 -D";
+  const content0 = Buffer.from(b64Part.replace(/\s+/g, ""), "base64").toString("utf-8");
   const occurrences = content0.split(oldStr).length - 1;
   if (occurrences === 0) {
     throw new Error(`未命中待替换片段（0 处）: ${path}（oldStr 长度 ${oldStr.length}，文件 ${content0.length} 字符）`);
@@ -3625,7 +3792,7 @@ async function editFile(drv, path, oldStr, newStr, opts = {}) {
   if (newB64.length > 30000) {
     return editFileViaFs(drv, path, edited, occurrences);
   }
-  const cmd = `if [ "$(${statCmdOf(qp)})" = "${statStamp}" ] && ` + `[ "$(${dialect.shaCmd.replace(/\{f\}/g, qp)})" = "${shaStamp}" ]; then ` + `printf %s ${q5(newB64)} | ${dialect.dec} > ${qp}.fx-tmp && mv ${qp}.fx-tmp ${qp} && ` + `echo "FX_OK $(stat -c '%Y %s' ${qp} 2>/dev/null || stat -f '%m %z' ${qp} 2>/dev/null)"; ` + `else echo FX_CAS_FAIL; fi`;
+  const cmd = `if [ "$(${statCmdOf(qp)})" = "${statStamp}" ] && ` + `[ "$(${shaCmdOf(qp)})" = "${shaStamp}" ]; then ` + `printf %s ${q5(newB64)} | ${dec} > ${qp}.fx-tmp && mv ${qp}.fx-tmp ${qp} && ` + `echo "FX_OK $(stat -c '%Y %s' ${qp} 2>/dev/null || stat -f '%m %z' ${qp} 2>/dev/null)"; ` + `else echo FX_CAS_FAIL; fi`;
   const cas = await drv.exec(cmd, { timeoutMs: 30000 });
   const out = (cas.stdout || "").trim();
   if (out.startsWith("FX_CAS_FAIL")) {
@@ -3680,7 +3847,8 @@ var TOOL_DEFS = [
         type: "object",
         properties: {
           command: { type: "string", description: "shell 命令" },
-          timeout_ms: { type: "number", description: "超时毫秒（缺省 120000）" }
+          timeout_ms: { type: "number", description: "超时毫秒（缺省 120000）" },
+          layer: { type: "string", description: "目标层名（缺省=默认层——最近 push_ssh/push_into 的层）" }
         },
         required: ["command"]
       }
@@ -3697,7 +3865,8 @@ var TOOL_DEFS = [
           command: { type: "string", description: "长跑命令" },
           ready_marker: { type: "string", description: "就绪标记（如 'listening on'）" },
           error_pattern: { type: "string", description: "错误模式（命中即收摊）" },
-          name: { type: "string", description: "会话名（人读前缀）" }
+          name: { type: "string", description: "会话名（人读前缀）" },
+          layer: { type: "string", description: "目标层名（缺省=默认层）" }
         },
         required: ["command"]
       }
@@ -3725,7 +3894,8 @@ var TOOL_DEFS = [
       parameters: {
         type: "object",
         properties: {
-          path: { type: "string" }
+          path: { type: "string" },
+          layer: { type: "string", description: "目标层名（缺省=默认层）" }
         },
         required: ["path"]
       }
@@ -3742,7 +3912,8 @@ var TOOL_DEFS = [
           path: { type: "string" },
           old: { type: "string", description: "待替换片段（含足够上下文唯一）" },
           new: { type: "string" },
-          all: { type: "boolean", description: "多处命中全替换（缺省报错）" }
+          all: { type: "boolean", description: "多处命中全替换（缺省报错）" },
+          layer: { type: "string", description: "目标层名（缺省=默认层）" }
         },
         required: ["path", "old", "new"]
       }
@@ -3759,22 +3930,87 @@ var TOOL_DEFS = [
           command: { type: "string" },
           duration_ms: { type: "number", description: "观察时长（缺省 8000）" },
           stream: { type: "string", enum: ["stdout", "stderr", "both"], description: "流过滤（缺省 both）" },
-          name: { type: "string" }
+          name: { type: "string" },
+          layer: { type: "string", description: "目标层名（缺省=默认层）" }
         },
         required: ["command"]
       }
     }
+  },
+  {
+    type: "function",
+    function: {
+      name: "push_ssh",
+      description: "建立命名 ssh 层（成为默认层——后续工具缺省落它）。同落点幂等复用（reused=true 返回既有层，" + "不重复建连）+ 落点校验（宁重连不错主机）。跳板传 jump（-J 不占层）。",
+      parameters: {
+        type: "object",
+        properties: {
+          host: { type: "string", description: "目标主机（user@host 或 ssh config 别名）" },
+          port: { type: "number", description: "SSH 端口（非 22 时指定）" },
+          user: { type: "string", description: "登录用户名" },
+          key: { type: "string", description: "私钥文件路径（-i）" },
+          jump: { type: "string", description: "跳板（-J：途径机不占层）" },
+          name: { type: "string", description: "层名（缺省=host；注册表内唯一，显式寻址用）" }
+        },
+        required: ["host"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "push_into",
+      description: "从默认层（或 from 指定层）进入内层 shell（docker exec -i <ctr> sh / kubectl exec 等）——" + "enter 管线全量继承追加（父层 docker→再 su 不丢）。新层成为默认层。需 ssh 层为源。",
+      parameters: {
+        type: "object",
+        properties: {
+          enter_cmd: { type: "string", description: '进入命令，如 "docker exec -i web sh"' },
+          label: { type: "string", description: "层显示标签" },
+          from: { type: "string", description: "源层名（缺省=默认层）" },
+          name: { type: "string", description: "层名（缺省=label）" }
+        },
+        required: ["enter_cmd"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "list_layers",
+      description: "列出全部命名层（链路/状态/有效用户/默认层标记）。死层/退化层有警示标注（removeLayer 后按原参数重建）。",
+      parameters: { type: "object", properties: {}, required: [] }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "remove_layer",
+      description: "移出命名层（缺省连接保留在指纹缓存——再建同层零成本；destroy=true 才真销毁连接）。",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "层名" },
+          destroy: { type: "boolean", description: "真销毁连接（缺省 false=保留可复用）" }
+        },
+        required: ["name"]
+      }
+    }
   }
 ];
 function createAgentToolkit(stack, opts = {}) {
   const layer = opts.driver ? Promise.resolve(opts.driver) : stack.connect(opts.descriptor ?? { driver: "local" });
   const readyTimeoutMs = opts.readyTimeoutMs ?? 15000;
+  const resolveDrv = async (layerName) => {
+    if (layerName)
+      return stack.layer(layerName).driver;
+    return stack.active ?? await layer;
+  };
   return {
     tools: TOOL_DEFS,
     layer,
     handlers: {
-      async run_command({ command, timeout_ms }) {
-        const drv = await layer;
+      async run_command({ command, timeout_ms, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         const r = await drv.exec(command, { timeoutMs: timeout_ms });
         return {
           stdout: r.stdout,
@@ -3783,8 +4019,8 @@ function createAgentToolkit(stack, opts = {}) {
           effective_user: r.effectiveUser
         };
       },
-      async spawn_and_observe({ command, ready_marker, error_pattern, name }) {
-        const drv = await layer;
+      async spawn_and_observe({ command, ready_marker, error_pattern, name, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         const h = await drv.execSession(command, name ? { name } : undefined);
         if (error_pattern) {
           drv.watchSession(h.sessionId, { pattern: error_pattern, once: false, thenStop: true });
@@ -3809,8 +4045,8 @@ function createAgentToolkit(stack, opts = {}) {
         }
         return { session_id: h.sessionId, log_base: h.logBase, note };
       },
-      async read_file({ path }) {
-        const drv = await layer;
+      async read_file({ path, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         if (!drv.fs.stat)
           throw new Error("该层不支持 read_file 的元数据（fs.stat 缺席）");
         const st = await drv.fs.stat(path);
@@ -3819,13 +4055,13 @@ function createAgentToolkit(stack, opts = {}) {
         const content = await drv.fs.readFile(path);
         return { path, content, size: st.size, mtime_ms: st.mtimeMs };
       },
-      async edit_file({ path, old, new: newStr, all }) {
-        const drv = await layer;
+      async edit_file({ path, old, new: newStr, all, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         const r = await editFile(drv, path, old, newStr, { all });
         return { path: r.path, occurrences: r.occurrences, bytes_before: r.bytesBefore, bytes_after: r.bytesAfter };
       },
-      async observe_stream({ command, duration_ms, stream, name }) {
-        const drv = await layer;
+      async observe_stream({ command, duration_ms, stream, name, layer: layerName }) {
+        const drv = await resolveDrv(layerName);
         const h = await drv.execSession(command, name ? { name } : undefined);
         const dur = duration_ms ?? 8000;
         await new Promise((r) => setTimeout(r, dur));
@@ -3837,6 +4073,49 @@ function createAgentToolkit(stack, opts = {}) {
         });
         return { session_id: h.sessionId, lines: filtered };
       },
+      async push_ssh({ host, port, user, key, jump, name }) {
+        const connParams = {};
+        if (port != null)
+          connParams.port = Number(port);
+        if (user)
+          connParams.user = String(user);
+        if (key)
+          connParams.keyFile = String(key);
+        if (jump)
+          connParams.jump = String(jump);
+        const r = await stack.addLayer(name ?? String(host), {
+          driver: "ssh",
+          target: String(host),
+          config: Object.keys(connParams).length ? { connParams } : undefined
+        });
+        return {
+          layer: r.handle.name,
+          reused: r.reused,
+          reused_from: r.reusedFrom,
+          note: r.reused ? "落点已由既有层持有——幂等复用（未重复建连）" : "新层已建并成为默认层"
+        };
+      },
+      async push_into({ enter_cmd, label, from, name }) {
+        const srcName = from ?? stack.activeLayer?.name;
+        if (!srcName)
+          throw new Error("无源层——先 push_ssh 建层，或显式传 from");
+        const h = await stack.layerInto(srcName, name ?? label ?? enter_cmd.slice(0, 30), enter_cmd, { label });
+        return { layer: h.name, target: h.descriptor.target };
+      },
+      async list_layers(_args) {
+        return {
+          text: stack.layerText(),
+          layers: [...stack.layers.values()].map((h) => ({
+            name: h.name,
+            driver: h.descriptor.driver,
+            target: h.descriptor.target
+          }))
+        };
+      },
+      async remove_layer({ name, destroy }) {
+        await stack.removeLayer(name, { destroy });
+        return { removed: name };
+      },
       async stop_and_verify({ session_id }) {
         const drv = await layer;
         const r = await drv.stopSession(session_id);