jishushell 0.4.30 → 0.5.15

package/dist/services/runtime/mcp-shims/drive-shim.js

@@ -0,0 +1,489 @@
+/**
+ * Drive MCP shim — exposes the panel's file + organize API to the
+ * agent inside the OpenClaw container (M1 W1.6).
+ *
+ * Why a shim, not a direct MCP server in panel:
+ *   - Panel and agent run in different processes (and often different
+ *     containers). Stdio MCP is the cheapest contract — the container
+ *     already runs node, and `mcporter.json` already wires shim
+ *     stdio servers via `command/args`.
+ *   - The shim translates JSON-RPC tool calls into HTTP calls back
+ *     to the panel via `host.docker.internal:8090`, authenticated
+ *     with the per-host internal token (`X-Jishushell-Internal-Token`)
+ *     plus the per-instance id (`X-Jishushell-Instance`).
+ *
+ * Tool surface (matches panel REST one-to-one):
+ *   drive_list           → GET    /api/files
+ *   drive_read_preview   → GET    /api/files/preview
+ *   drive_quota          → GET    /api/files/quota
+ *   drive_mkdir          → POST   /api/files/mkdir
+ *   drive_organize_scan  → POST   /api/files/organize/scan
+ *   drive_organize_apply → PUT    /api/files/organize/batches/:id/apply
+ *   drive_organize_revert → POST  /api/files/organize/batches/:id/revert
+ *   drive_search        → GET    /api/files/search
+ *   drive_get_meta      → GET    /api/files/meta
+ *   drive_set_meta      → PUT    /api/files/meta
+ *   drive_reindex       → POST   /api/files/reindex
+ *   drive_resolve_local_path → GET /api/files/resolve  (v0.4 — IM-plugin bridge)
+ *   drive_write_binary  → PUT    /api/files               (v0.4 — base64 body)
+ *
+ * The user-facing chat experience this enables:
+ *   user: "整理一下 inbox 里的发票"
+ *   agent → drive_organize_scan({ path: "inbox" })
+ *   agent → drive_organize_apply({ batch_id, selected_ids: [...] })
+ *   agent: "✅ 整理了 8 张发票到 finance/2026/05/, 30 秒内可撤销"
+ *
+ * Stdio framing: NDJSON JSON-RPC 2.0 (MCP standard). Pure Node
+ * builtins — no npm install needed inside the runtime image.
+ */
+export const DRIVE_MCP_SHIM_VERSION = "0.4.0";
+export const DRIVE_MCP_SHIM_SOURCE = `#!/usr/bin/env node
+// jishushell-drive-shim — generated, do not edit by hand.
+// Source: src/services/runtime/mcp-shims/drive-shim.ts
+import { createInterface } from "node:readline";
+
+// Per-instance values are baked in by the adapter at install time via
+// substituteDriveShimPlaceholders(). OpenClaw scrubs env when spawning MCP
+// subprocesses, so the env-based fallback is unreliable in production —
+// the literal substitution path below is the source of truth. Env vars
+// are kept as a backstop for hand-running the shim during development.
+const PANEL_URL_LIT = "__JS_PANEL_URL__";
+const TOKEN_LIT = "__JS_TOKEN__";
+const INSTANCE_ID_LIT = "__JS_INSTANCE_ID__";
+const PANEL_URL = (PANEL_URL_LIT.startsWith("__JS_") ? (process.env.JISHUSHELL_PANEL_URL || "http://host.docker.internal:8090") : PANEL_URL_LIT).replace(/\\/+$/, "");
+const TOKEN = TOKEN_LIT.startsWith("__JS_") ? (process.env.JISHUSHELL_INTERNAL_TOKEN || "") : TOKEN_LIT;
+const INSTANCE_ID = INSTANCE_ID_LIT.startsWith("__JS_") ? (process.env.JISHUSHELL_INSTANCE_ID || "") : INSTANCE_ID_LIT;
+
+if (!TOKEN || !INSTANCE_ID) {
+  process.stderr.write("[drive-shim] missing JISHUSHELL_INTERNAL_TOKEN or JISHUSHELL_INSTANCE_ID env\\n");
+}
+
+function authedHeaders(extra) {
+  return Object.assign({
+    "X-Jishushell-Internal-Token": TOKEN,
+    "X-Jishushell-Instance": INSTANCE_ID,
+  }, extra || {});
+}
+
+async function panelGet(path, query) {
+  const url = new URL(PANEL_URL + path);
+  for (const [k, v] of Object.entries(query || {})) {
+    if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+  }
+  const res = await fetch(url, { headers: authedHeaders() });
+  const body = await res.text();
+  let parsed;
+  try { parsed = body ? JSON.parse(body) : null; } catch { parsed = body; }
+  return { status: res.status, body: parsed };
+}
+
+async function panelSend(method, path, query, jsonBody) {
+  const url = new URL(PANEL_URL + path);
+  for (const [k, v] of Object.entries(query || {})) {
+    if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+  }
+  const res = await fetch(url, {
+    method,
+    headers: authedHeaders({ "Content-Type": "application/json" }),
+    body: jsonBody !== undefined ? JSON.stringify(jsonBody) : undefined,
+  });
+  const body = await res.text();
+  let parsed;
+  try { parsed = body ? JSON.parse(body) : null; } catch { parsed = body; }
+  return { status: res.status, body: parsed };
+}
+
+async function panelPutBinary(path, query, buf) {
+  const url = new URL(PANEL_URL + path);
+  for (const [k, v] of Object.entries(query || {})) {
+    if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+  }
+  const res = await fetch(url, {
+    method: "PUT",
+    headers: authedHeaders({
+      "Content-Type": "application/octet-stream",
+      "Content-Length": String(buf.length),
+    }),
+    body: buf,
+  });
+  const body = await res.text();
+  let parsed;
+  try { parsed = body ? JSON.parse(body) : null; } catch { parsed = body; }
+  return { status: res.status, body: parsed };
+}
+
+const TOOLS = [
+  {
+    name: "drive_list",
+    description:
+      "List a directory in the user's NAS (~/.jishushell/files/). Returns entries with name, is_dir, size, mtime, mime, etag. These paths are also valid host filesystem paths inside your container — call drive_resolve_local_path to get an absolute path you can hand to native IM channel send_file tools (Feishu / WeChat / ...).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "directory path relative to files/ root; \\"\\" for root" },
+        show_hidden: { type: "boolean" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "drive_read_preview",
+    description:
+      "Read a small text/JSON file preview (up to max_kb KB, default 256). Returns content + truncated flag.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        max_kb: { type: "integer", description: "max kilobytes to read; default 256" },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "drive_quota",
+    description: "Get NAS storage quota: quota_mb, used_mb, available_mb, trash_mb.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "drive_mkdir",
+    description: "Create a new directory in the user's NAS.",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string" } },
+      required: ["path"],
+    },
+  },
+  {
+    name: "drive_organize_scan",
+    description:
+      "Scan a directory and propose organize moves based on user-defined rules. Returns batch.id and suggestions[].",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "subdirectory to scan; default scans the entire root" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "drive_organize_apply",
+    description:
+      "Apply previously-scanned organize suggestions. selected_ids defaults to all suggestions in the batch. Returns report.applied/skipped/failed and an undo window of 30 seconds.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        batch_id: { type: "string" },
+        selected_ids: { type: "array", items: { type: "string" } },
+      },
+      required: ["batch_id"],
+    },
+  },
+  {
+    name: "drive_organize_revert",
+    description:
+      "Revert an applied organize batch. Only valid within the 30-second undo window; returns 410 expired afterwards.",
+    inputSchema: {
+      type: "object",
+      properties: { batch_id: { type: "string" } },
+      required: ["batch_id"],
+    },
+  },
+  {
+    name: "drive_read_full",
+    description:
+      "Read a TEXT file in full (up to 1MB). Use for summarizing PDFs/notes/code; for binary files this returns a hint to use the file URL instead. Always check the truncated flag.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        max_kb: {
+          type: "integer",
+          description: "max kilobytes (default 1024 = 1MB; hard ceiling 4096)",
+        },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "drive_write_text",
+    description:
+      "Write a text file (overwrites if it exists). Use this when the agent generates a report / summary / draft and wants to persist it. Path is files/-relative; agents typically write under agent-data/{instance}/. To then SEND the file via an IM channel, call drive_resolve_local_path on the same path and pass the abs_path to the channel plugin's send_file tool.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        content: { type: "string" },
+      },
+      required: ["path", "content"],
+    },
+  },
+  {
+    name: "drive_move",
+    description:
+      "Move or rename a single file/directory. Both paths are files/-relative. Default does NOT overwrite — pass overwrite=true to replace.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string" },
+        to: { type: "string" },
+        overwrite: { type: "boolean" },
+      },
+      required: ["from", "to"],
+    },
+  },
+  {
+    name: "drive_delete",
+    description:
+      "Soft-delete a file/directory (moves it to .trash/{date}/, recoverable for 30 days). Files-relative path; do not include leading slash.",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string" } },
+      required: ["path"],
+    },
+  },
+  {
+    name: "drive_search",
+    description: "Search indexed file content via FTS5; returns relative paths + snippets + sha256.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "FTS5 query string (supports operators: \\"AND\\", \\"OR\\", quoted phrases)." },
+        limit: { type: "number", description: "Max hits (default 20, max 100).", minimum: 1, maximum: 100 },
+        path: { type: "string", description: "Optional relative-path prefix to scope the search." },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "drive_get_meta",
+    description: "Read the sidecar metadata (tags/summary/links/notes) for a file by sha256 or by path. Returns null if no sidecar exists yet.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sha256: { type: "string", pattern: "^[a-fA-F0-9]{64}$", description: "64-hex content hash." },
+        path: { type: "string", description: "Relative path under the user file root." },
+      },
+      oneOf: [{ required: ["sha256"] }, { required: ["path"] }],
+    },
+  },
+  {
+    name: "drive_set_meta",
+    description: "Write or merge sidecar metadata for a file. payload is free-form JSON; merge=true (default) shallow-merges with the existing sidecar.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sha256: { type: "string", pattern: "^[a-fA-F0-9]{64}$" },
+        payload: { type: "object", description: "Sidecar fields to write. Schema: { tags?: string[], summary?: string, links?: [{path, rel}], agent_notes?: string, ... }." },
+        merge: { type: "boolean", description: "When true (default), shallow-merge with existing sidecar; when false, replace." },
+      },
+      required: ["sha256", "payload"],
+    },
+  },
+  {
+    name: "drive_reindex",
+    description: "Rescan the file tree (or a sub-path) and rebuild FTS5 entries for text/markdown/json/yaml/code files. Explicit trigger only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Optional relative prefix to limit the rescan." },
+      },
+    },
+  },
+  {
+    name: "drive_resolve_local_path",
+    description:
+      "Resolve a files/-relative path to its ABSOLUTE host filesystem path. Use this whenever you need to hand a path to a native IM channel plugin (Feishu / WeChat / Telegram / ... send_file tool) — those plugins read bytes from the local filesystem, not via HTTP. The returned abs_path is valid inside your container (panel binds host==container for files mounts) and on the host (raw_exec / process service managers run the agent natively on the host). Returns { abs_path, exists, is_dir?, size?, mtime?, external_mount?, external_mount_mode? }. Check exists before sending; check external_mount_mode='ro' before trying to overwrite.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "files/-relative path, e.g. \\"reports/q4.pdf\\" or \\"agent-data/<instance>/outbox/summary.pdf\\"." },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "drive_write_binary",
+    description:
+      "Write a binary file (overwrites if it exists). Use this when the agent generates a PDF / image / audio / archive that needs to be persisted or handed to an IM channel for sending. content_base64 is standard base64 of the file bytes (no data: URL prefix). Path is files/-relative; agents typically write under agent-data/{instance}/outbox/ so the file is clearly outbound. After writing, call drive_resolve_local_path on the same path to get the absolute path to pass to the IM channel's send_file tool. Soft cap: 10 MB raw (~13.5 MB base64) per call.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        content_base64: { type: "string", description: "Standard base64 (RFC 4648). No data: URL prefix." },
+      },
+      required: ["path", "content_base64"],
+    },
+  },
+];
+
+async function callTool(name, args) {
+  switch (name) {
+    case "drive_list": {
+      const r = await panelGet("/api/files", { path: args.path || "", show_hidden: args.show_hidden });
+      return r;
+    }
+    case "drive_read_preview": {
+      const r = await panelGet("/api/files/preview", { path: args.path, max_kb: args.max_kb });
+      return r;
+    }
+    case "drive_quota": {
+      return panelGet("/api/files/quota");
+    }
+    case "drive_mkdir": {
+      return panelSend("POST", "/api/files/mkdir", null, { path: args.path });
+    }
+    case "drive_organize_scan": {
+      return panelSend("POST", "/api/files/organize/scan", null, { path: args.path || "" });
+    }
+    case "drive_organize_apply": {
+      // If selected_ids is missing or empty, fetch the batch and apply ALL suggestions.
+      let selected = Array.isArray(args.selected_ids) ? args.selected_ids : null;
+      if (!selected || selected.length === 0) {
+        const got = await panelGet("/api/files/organize/batches/" + encodeURIComponent(args.batch_id));
+        if (got.status === 200 && got.body && Array.isArray(got.body.suggestions)) {
+          selected = got.body.suggestions.map((s) => s.id);
+        } else {
+          return got;
+        }
+      }
+      return panelSend("PUT", "/api/files/organize/batches/" + encodeURIComponent(args.batch_id) + "/apply", null, { selected_ids: selected });
+    }
+    case "drive_organize_revert": {
+      return panelSend("POST", "/api/files/organize/batches/" + encodeURIComponent(args.batch_id) + "/revert", null);
+    }
+    case "drive_read_full": {
+      const ceiling = 4096;
+      const wanted = Math.min(Number.isFinite(+args.max_kb) ? +args.max_kb : 1024, ceiling);
+      return panelGet("/api/files/preview", { path: args.path, max_kb: wanted });
+    }
+    case "drive_write_text": {
+      const text = String(args.content == null ? "" : args.content);
+      const buf = Buffer.from(text, "utf8");
+      return panelPutBinary("/api/files", { path: args.path, overwrite: "true", client_mime: "text/plain" }, buf);
+    }
+    case "drive_move": {
+      const overwrite = args.overwrite === true;
+      return panelSend("POST", "/api/files/move", null, {
+        from: args.from,
+        to: args.to,
+        overwrite,
+      });
+    }
+    case "drive_delete": {
+      return panelSend("DELETE", "/api/files", { path: args.path }, undefined);
+    }
+    case "drive_search": {
+      const qs = new URLSearchParams({ q: args.query });
+      if (args.limit != null) qs.set("limit", String(args.limit));
+      if (args.path) qs.set("path", args.path);
+      return panelGet("/api/files/search?" + qs.toString(), null);
+    }
+    case "drive_get_meta": {
+      const qs = new URLSearchParams();
+      if (args.sha256) qs.set("sha", args.sha256);
+      else if (args.path) qs.set("path", args.path);
+      return panelGet("/api/files/meta?" + qs.toString(), null);
+    }
+    case "drive_set_meta": {
+      const qs = new URLSearchParams({ sha: args.sha256 });
+      if (args.merge === false) qs.set("merge", "false");
+      return panelSend("PUT", "/api/files/meta?" + qs.toString(), null, args.payload);
+    }
+    case "drive_reindex": {
+      const qs = args.path ? "?path=" + encodeURIComponent(args.path) : "";
+      return panelSend("POST", "/api/files/reindex" + qs, null, undefined);
+    }
+    case "drive_resolve_local_path": {
+      return panelGet("/api/files/resolve", { path: args.path });
+    }
+    case "drive_write_binary": {
+      const b64 = String(args.content_base64 == null ? "" : args.content_base64);
+      if (!b64) {
+        return { status: 400, body: { detail: "content_base64 required" } };
+      }
+      let buf;
+      try { buf = Buffer.from(b64, "base64"); } catch (e) {
+        return { status: 400, body: { detail: "content_base64 not valid base64" } };
+      }
+      // Soft cap so MCP stdio framing (NDJSON) stays healthy. Bigger files
+      // should be staged via Filebrowser / WebDAV directly into files/.
+      if (buf.length > 10 * 1024 * 1024) {
+        return { status: 413, body: { detail: "content_base64 exceeds 10MB soft cap; split into smaller writes or stage the file via Filebrowser/WebDAV" } };
+      }
+      return panelPutBinary("/api/files", { path: args.path, overwrite: "true" }, buf);
+    }
+    default:
+      throw new Error("unknown tool: " + name);
+  }
+}
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\\n");
+}
+
+function ok(id, result) { send({ jsonrpc: "2.0", id, result }); }
+function err(id, code, message, data) {
+  send({ jsonrpc: "2.0", id, error: { code, message, data } });
+}
+
+async function dispatch(msg) {
+  if (msg.method === "initialize") {
+    return ok(msg.id, {
+      protocolVersion: "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: { name: "jishushell-drive-shim", version: ${JSON.stringify(DRIVE_MCP_SHIM_VERSION)} },
+    });
+  }
+  if (msg.method === "tools/list") {
+    return ok(msg.id, { tools: TOOLS });
+  }
+  if (msg.method === "tools/call") {
+    const name = msg.params && msg.params.name;
+    const args = (msg.params && msg.params.arguments) || {};
+    try {
+      const r = await callTool(name, args);
+      const text = r.status >= 200 && r.status < 300
+        ? "ok " + r.status + ": " + JSON.stringify(r.body)
+        : "error " + r.status + ": " + JSON.stringify(r.body);
+      return ok(msg.id, {
+        content: [{ type: "text", text: text }],
+        isError: !(r.status >= 200 && r.status < 300),
+      });
+    } catch (e) {
+      return err(msg.id, -32000, "tool execution failed", { error: String(e && e.message || e) });
+    }
+  }
+  if (msg.method === "ping") return ok(msg.id, {});
+  if (msg.method && msg.method.startsWith("notifications/")) return; // no reply
+  if (msg.id !== undefined) err(msg.id, -32601, "method not found: " + msg.method);
+}
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let msg;
+  try { msg = JSON.parse(trimmed); } catch { return; }
+  Promise.resolve(dispatch(msg)).catch((e) => {
+    process.stderr.write("[drive-shim] dispatch crashed: " + (e && e.stack || e) + "\\n");
+  });
+});
+process.stdin.on("end", () => process.exit(0));
+`;
+/**
+ * Bake per-instance values into the shim template. Returns the source to
+ * write to disk. Must be called before writing because OpenClaw scrubs
+ * env when spawning MCP subprocesses, so the env-based fallback in the
+ * template is unreliable in production.
+ *
+ * Placeholders use non-JS-identifier marker `__JS_*__` so they grep cleanly
+ * and never collide with real code paths.
+ */
+export function substituteDriveShimPlaceholders(params) {
+    const escapeStr = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return DRIVE_MCP_SHIM_SOURCE
+        .replace(/__JS_PANEL_URL__/g, escapeStr(params.panelUrl))
+        .replace(/__JS_TOKEN__/g, escapeStr(params.token))
+        .replace(/__JS_INSTANCE_ID__/g, escapeStr(params.instanceId));
+}
+//# sourceMappingURL=drive-shim.js.map

package/dist/services/runtime/mcp-shims/drive-shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive-shim.js","sourceRoot":"","sources":["../../../../src/services/runtime/mcp-shims/drive-shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAE9C,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8DA0YyB,IAAI,CAAC,SAAS,CAAC,sBAAsB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCnG,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,+BAA+B,CAC7C,MAA+D;IAE/D,MAAM,SAAS,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC/E,OAAO,qBAAqB;SACzB,OAAO,CAAC,mBAAmB,EAAE,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;SACxD,OAAO,CAAC,eAAe,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;SACjD,OAAO,CAAC,qBAAqB,EAAE,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/services/runtime/types.d.ts

@@ -55,6 +55,37 @@ export interface RuntimeSpec {
     ports?: RuntimePortSpec[];
     volumes?: RuntimeVolumeSpec[];
     health?: RuntimeHealthSpec | null;
+    /**
+     * Per-instance mounts of subtrees from `~/.jishushell/files/`.
+     *
+     * Each entry exposes one user file-tree subdirectory inside the
+     * container under a stable alias, optionally read-only.
+     *
+     * - Docker mode: enforced by Linux mount options (ro is real)
+     * - raw_exec / process mode: configuration only — the agent runs as
+     *   the panel user and can ignore the ro flag (see vision G8)
+     *
+     * The structural defaults and built-in `agent-data/{id}` mount are
+     * applied by `services/instance-manager.ts` at create time.
+     */
+    fileMounts?: FileMount[];
+}
+/**
+ * One subtree of `~/.jishushell/files/` exposed to a single instance.
+ *
+ * - `path` is files/-relative; validated by path-safety
+ * - `mode` is the mount mode (ro/rw)
+ * - `alias` controls how the mount appears inside the container's
+ *   workspace:
+ *     - non-empty string → workspace/{alias} symlink to this subtree
+ *     - "" or null      → workspace IS this subtree (root mount;
+ *                         exclusive — at most one per instance)
+ *     - undefined       → defaults to basename(path)
+ */
+export interface FileMount {
+    path: string;
+    mode: "ro" | "rw";
+    alias?: string | null;
 }
 export interface CapabilityProfile {
     gateway: {