koishi-plugin-ishiki-workspace 0.0.3 → 0.0.5

package/lib/execution-limits.d.ts

@@ -0,0 +1,5 @@
+import type { BashOptions } from "just-bash";
+import type { WorkspaceLayout } from "./shell.js";
+type ExecutionLimits = NonNullable<BashOptions["executionLimits"]>;
+export declare function sandboxExecutionLimits(layout: Pick<WorkspaceLayout, "timeoutMs" | "maxExecutionOutputBytes">): ExecutionLimits;
+export {};

package/lib/index.cjs

@@ -48,7 +48,7 @@ var WorkspaceConfig = import_koishi.Schema.object({
   network: import_koishi.Schema.boolean().description("仅 sandbox 模式：允许沙箱内访问网络；开启时仍拒绝私有地址。native 走宿主机真实网络").default(false),
   javascript: import_koishi.Schema.boolean().description("仅 sandbox 模式：启用 js-exec 命令（QuickJS 里执行 JavaScript / TypeScript）；默认关闭，开它会多一份代码执行面").default(false),
   python: import_koishi.Schema.boolean().description("仅 sandbox 模式：启用 python3 / python 命令（CPython 编译成 WebAssembly）；默认关闭，开它会多一份代码执行面").default(false),
-  skills: import_koishi.Schema.array(import_koishi.Schema.string()).description("额外技能目录，相对 profile 目录解析；与数据根的 skills 目录合并，同名以这里优先").default([]),
+  skills: import_koishi.Schema.array(import_koishi.Schema.string()).description("额外技能目录，相对 profile 目录解析；与内置技能和数据的 skills 目录合并，同名时依次覆盖，以这里优先").default([]),
   mounts: import_koishi.Schema.array(import_koishi.Schema.string()).description("仅 sandbox 模式：宿主目录挂载，写法 `source:target[:ro]`；source 相对 profile 目录解析，省略 :ro 即可读写。native 模式无虚拟路径，不解析").default([])
 });
 
@@ -250,8 +250,9 @@ Use read_file to read a known file, write_file to replace a file, edit_file for
 );
 var SANDBOX_INSTRUCTIONS = new import_koishi_plugin_ishiki.Template(
   `## Workspace
-You read and write files in a per-instance sandbox, not on the host: commands are interpreted by JavaScript, only the mounted paths below exist, and host paths and commands are invisible.
+You read and write files in a per-instance sandbox, not on the host: commands run in just-bash, only the mounted paths below exist, and host paths and commands are invisible.
 The command set is not the host's.
+Runtime details and API gaps are recorded in the bundled sandbox-environment skill; read it before writing JavaScript, TypeScript, Python, SQLite, or network-heavy commands.
 Current working directory: {{ cwd }}
 Mounts:
 - {{ homeMount }}: read-only, this instance's data directory (writes fail)
@@ -269,11 +270,12 @@ Network: {{ network }}
 Command timeout: {{ timeoutMs }} ms; a timeout returns exit code 124.
 Executor output safety limit: {{ maxExecutionOutputBytes }} bytes. Inside codemode you receive the raw output; the runtime handles model-visible previews and archives. Return structured results instead of stringifying or slicing them yourself.
 Shell state does not persist between calls: cd, aliases, functions, and exported variables are not retained. Put a directory change on the same line (cd <dir> && <command>).
+/tmp belongs to this sandbox lifetime. Read a /tmp file only after the same or an earlier successful call created it; a failed or timed-out call may leave nothing behind. Write results that must survive to the workspace or an artifact.
 {% if javascript %}
-js-exec is available: run JavaScript / TypeScript in QuickJS. Some node modules can be required or imported; only files inside the sandbox are accessible.
+js-exec is available: run JavaScript / TypeScript in QuickJS with a partial Node.js module surface. Only files inside the sandbox are accessible.
 {% endif %}
 {% if python %}
-python3 and python are available: CPython compiled to WebAssembly with the full standard library. The first call waits for it to load; reads and writes target this sandbox.
+python3 and python are available: CPython compiled to WebAssembly. Most of the standard library is available, but subprocess and the sqlite3 module are absent. The first call waits for it to load; reads and writes target this sandbox.
 {% endif %}
 You can also read a known file through read's workspace:///<sandbox-path> URL (e.g. workspace:///home/workspace/a.txt): virtual files, persistent directories, and mounts all resolve to the same sandbox file.
 Use read_file to read a known file, write_file to replace a file, edit_file for a small edit, and bash for listing, searching, and pipelines.`
@@ -355,7 +357,408 @@ var WorkspaceScheme = class extends import_koishi_plugin_ishiki2.FileScheme {
 
 // src/sandbox.ts
 var import_node_path4 = __toESM(require("node:path"));
-var import_just_bash = require("just-bash");
+
+// src/execution-limits.ts
+function sandboxExecutionLimits(layout) {
+  return {
+    maxOutputSize: layout.maxExecutionOutputBytes,
+    maxExecutionTimeMs: layout.timeoutMs,
+    maxSqliteTimeoutMs: layout.timeoutMs,
+    maxPythonTimeoutMs: layout.timeoutMs,
+    maxJsTimeoutMs: layout.timeoutMs
+  };
+}
+__name(sandboxExecutionLimits, "sandboxExecutionLimits");
+
+// src/js-bootstrap.ts
+var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
+(function () {
+  var hostKey = Object.getOwnPropertyNames(globalThis).filter(function (name) {
+    return name.indexOf('__jbHost_') === 0;
+  })[0];
+  if (!hostKey) throw new Error('js-exec host bridge is unavailable');
+  var host = globalThis[hostKey];
+  var fs = globalThis.fs;
+  function unwrap(result) {
+    if (!result || result.ok !== true) throw new Error(result && result.error || 'Host operation failed');
+    return result.value;
+  }
+  var raw = {};
+  var names = [
+    'readFileBuffer', 'readFileSync', 'writeFileSync', 'appendFileSync',
+    'statSync', 'lstatSync', 'readdirSync', 'mkdirSync', 'rmSync',
+    'symlinkSync', 'readlinkSync', 'chmodSync', 'realpathSync',
+    'renameSync', 'copyFileSync'
+  ];
+  for (var index = 0; index < names.length; index++) raw[names[index]] = fs[names[index]];
+
+  var errnos = {
+    EPERM: -1,
+    ENOENT: -2,
+    EIO: -5,
+    EACCES: -13,
+    EEXIST: -17,
+    ENOTDIR: -20,
+    EISDIR: -21,
+    EINVAL: -22,
+    ENOSPC: -28,
+    EROFS: -30,
+    ENAMETOOLONG: -36,
+    ENOTEMPTY: -39,
+    ELOOP: -40
+  };
+
+  var constants = {
+    F_OK: 0,
+    R_OK: 4,
+    W_OK: 2,
+    X_OK: 1,
+    COPYFILE_EXCL: 1,
+    COPYFILE_FICLONE: 2,
+    COPYFILE_FICLONE_FORCE: 4,
+    S_IFMT: 61440,
+    S_IFREG: 32768,
+    S_IFDIR: 16384,
+    S_IFLNK: 40960,
+    O_RDONLY: 0,
+    O_WRONLY: 1,
+    O_RDWR: 2,
+    O_CREAT: 64,
+    O_EXCL: 128,
+    O_TRUNC: 512,
+    O_APPEND: 1024
+  };
+
+  function failure(error, syscall, target, destination) {
+    if (!(error instanceof Error)) error = new Error(String(error));
+    var matched = /^([A-Z][A-Z0-9]+):/.exec(error.message);
+    if (matched) {
+      error.code = matched[1];
+      if (errnos[error.code] !== undefined) error.errno = errnos[error.code];
+    }
+    error.syscall = syscall;
+    if (target !== undefined) {
+      error.path = String(target);
+      error.message = error.message.replace(/'[^']*'(?=\s*$)/, "'" + String(target).replace(/'/g, "\\'") + "'");
+    }
+    if (destination !== undefined) error.dest = String(destination);
+    return error;
+  }
+
+  function filePath(value) {
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      typeof value.href !== 'string' ||
+      typeof value.protocol !== 'string'
+    ) return value;
+    if (value.protocol !== 'file:') {
+      throw failure(new Error('ERR_INVALID_URL_SCHEME: The URL must be of scheme file, received ' + value.protocol), 'open', value.href);
+    }
+    if (value.hostname && value.hostname !== 'localhost') {
+      throw failure(new Error('ERR_INVALID_FILE_URL_HOST: File URL host must be "localhost" or empty, received ' + value.hostname), 'open', value.href);
+    }
+    return decodeURIComponent(value.pathname);
+  }
+
+  function bridge(hostName, syscall, target, args, destination) {
+    try {
+      var operation = host[hostName];
+      if (args.length === 1) return unwrap(operation(args[0]));
+      if (args.length === 2) return unwrap(operation(args[0], args[1]));
+      if (args.length === 3) return unwrap(operation(args[0], args[1], args[2]));
+      return unwrap(operation(args[0], args[1], args[2], args[3]));
+    } catch (error) {
+      throw failure(error, syscall, target, destination);
+    }
+  }
+
+  function bytes(value) {
+    if (value && value._data instanceof Uint8Array) return Array.from(value._data);
+    if (value && Array.isArray(value._data)) return value._data.slice();
+    if (Array.isArray(value)) return value.slice();
+    if (value instanceof Uint8Array) return Array.from(value);
+    return String(value);
+  }
+
+  function Stats() {}
+  function Dirent() {}
+
+  function stats(value) {
+    var mtime = value.mtime instanceof Date ? value.mtime : new Date(value.mtime);
+    var size = Number(value.size);
+    var result = Object.create(Stats.prototype);
+    result.dev = 0;
+    result.ino = 0;
+    result.mode = Number(value.mode);
+    result.nlink = value.isDirectory ? 2 : 1;
+    result.uid = 1000;
+    result.gid = 1000;
+    result.rdev = 0;
+    result.size = size;
+    result.blksize = 4096;
+    result.blocks = Math.ceil(size / 512);
+    result.atime = mtime;
+    result.mtime = mtime;
+    result.ctime = mtime;
+    result.birthtime = mtime;
+    result.atimeMs = mtime.getTime();
+    result.mtimeMs = mtime.getTime();
+    result.ctimeMs = mtime.getTime();
+    result.birthtimeMs = mtime.getTime();
+    result.isFile = function () { return value.isFile; };
+    result.isDirectory = function () { return value.isDirectory; };
+    result.isSymbolicLink = function () { return value.isSymbolicLink; };
+    result.isBlockDevice = function () { return false; };
+    result.isCharacterDevice = function () { return false; };
+    result.isFIFO = function () { return false; };
+    result.isSocket = function () { return false; };
+    return result;
+  }
+
+  function dirent(name, parentPath, value) {
+    var result = Object.create(Dirent.prototype);
+    result.name = String(name);
+    result.parentPath = String(parentPath);
+    result.path = String(parentPath);
+    result.isFile = function () { return value.isFile; };
+    result.isDirectory = function () { return value.isDirectory; };
+    result.isSymbolicLink = function () { return value.isSymbolicLink; };
+    result.isBlockDevice = function () { return false; };
+    result.isCharacterDevice = function () { return false; };
+    result.isFIFO = function () { return false; };
+    result.isSocket = function () { return false; };
+    return result;
+  }
+
+  function childPath(parent, name) {
+    return parent.charAt(parent.length - 1) === '/' ? parent + name : parent + '/' + name;
+  }
+
+  function readStats(path, follow) {
+    var target = filePath(path);
+    return bridge('fsStat', follow ? 'stat' : 'lstat', target, [target, !follow]);
+  }
+
+  function collect(path, relative, options, output) {
+    var listing = bridge('fsReaddir', 'scandir', path, [path]);
+    for (var index = 0; index < listing.length; index++) {
+      var name = listing[index];
+      var nested = relative === '' ? name : relative + '/' + name;
+      var full = childPath(path, name);
+      var value = readStats(full, false);
+      output.push(options.withFileTypes ? dirent(name, path, value) : nested);
+      if (options.recursive && value.isDirectory) collect(full, nested, options, output);
+    }
+  }
+
+  function readdir(path, options) {
+    var target = filePath(path);
+    if (typeof options === 'string') options = { encoding: options };
+    options = options || {};
+    var output = [];
+    collect(target, '', { recursive: Boolean(options.recursive), withFileTypes: Boolean(options.withFileTypes) }, output);
+    if (options.encoding === 'buffer') return output.map(function (entry) {
+      return typeof entry === 'string' ? Buffer.from(entry) : entry;
+    });
+    return output;
+  }
+
+  function firstCreated(path) {
+    var text = String(filePath(path));
+    var absolute = text.charAt(0) === '/';
+    var parts = text.split('/');
+    var current = '';
+    var found;
+    for (var index = 0; index < parts.length; index++) {
+      var part = parts[index];
+      if (part === '' || part === '.') continue;
+      if (current === '') current = absolute ? '/' + part : part;
+      else current = childPath(current, part);
+      if (!fs.existsSync(current)) {
+        found = current;
+        break;
+      }
+    }
+    return found;
+  }
+
+  fs.readFileBuffer = function (path) {
+    var target = filePath(path);
+    try {
+      return Buffer.from(raw.readFileBuffer(target));
+    } catch (error) {
+      throw failure(error, 'open', target);
+    }
+  };
+  fs.readFileSync = function (path, options) {
+    var target = filePath(path);
+    try {
+      return raw.readFileSync(target, options);
+    } catch (error) {
+      throw failure(error, 'open', target);
+    }
+  };
+  fs.writeFileSync = function (path, data) {
+    var target = filePath(path);
+    bridge('fsWrite', 'open', target, [target, bytes(data)]);
+  };
+  fs.appendFileSync = function (path, data) {
+    var target = filePath(path);
+    bridge('fsAppend', 'open', target, [target, bytes(data)]);
+  };
+  fs.statSync = function (path) {
+    return stats(readStats(path, true));
+  };
+  fs.lstatSync = function (path) {
+    return stats(readStats(path, false));
+  };
+  fs.readdirSync = readdir;
+  fs.mkdirSync = function (path, options) {
+    var target = filePath(path);
+    var recursive = Boolean(options && typeof options === 'object' && options.recursive);
+    var created = recursive ? firstCreated(target) : undefined;
+    bridge('fsMkdir', 'mkdir', target, [target, recursive]);
+    return created;
+  };
+  fs.rmSync = function (path, options) {
+    var target = filePath(path);
+    bridge('fsRm', 'rm', target, [target, Boolean(options && options.recursive), Boolean(options && options.force)]);
+  };
+  fs.existsSync = function (path) {
+    var target = filePath(path);
+    try {
+      return bridge('fsExists', 'access', target, [target]);
+    } catch (error) {
+      return false;
+    }
+  };
+  fs.accessSync = function (path, mode) {
+    var target = filePath(path);
+    if (!bridge('fsExists', 'access', target, [target])) {
+      throw failure(new Error("ENOENT: no such file or directory, access '" + target + "'"), 'access', target);
+    }
+    var flags = mode === undefined ? 0 : Number(mode);
+    if ((flags & ~7) !== 0) {
+      throw failure(new Error("EINVAL: invalid mode argument, access '" + target + "'"), 'access', target);
+    }
+    if (flags === 0) return;
+    var permissions = stats(readStats(target, true)).mode & 511;
+    var required = 0;
+    if (flags & constants.R_OK) required |= 256;
+    if (flags & constants.W_OK) required |= 128;
+    if (flags & constants.X_OK) required |= 64;
+    if ((permissions & required) !== required) {
+      throw failure(new Error("EACCES: permission denied, access '" + target + "'"), 'access', target);
+    }
+  };
+  fs.symlinkSync = function (target, path) {
+    var link = filePath(path);
+    bridge('fsSymlink', 'symlink', link, [filePath(target), link]);
+  };
+  fs.readlinkSync = function (path) {
+    var target = filePath(path);
+    return bridge('fsReadlink', 'readlink', target, [target]);
+  };
+  fs.chmodSync = function (path, mode) {
+    var target = filePath(path);
+    bridge('fsChmod', 'chmod', target, [target, Number(mode)]);
+  };
+  fs.realpathSync = function (path) {
+    var target = filePath(path);
+    return bridge('fsRealpath', 'realpath', target, [target]);
+  };
+  fs.renameSync = function (from, to) {
+    var source = filePath(from);
+    var destination = filePath(to);
+    bridge('fsRename', 'rename', source, [source, destination], destination);
+  };
+  fs.copyFileSync = function (from, to, mode) {
+    var source = filePath(from);
+    var destination = filePath(to);
+    if ((Number(mode) || 0) & constants.COPYFILE_EXCL && fs.existsSync(destination)) {
+      throw failure(new Error("EEXIST: file already exists, copyfile '" + destination + "'"), 'copyfile', source, destination);
+    }
+    bridge('fsCopy', 'copyfile', source, [source, destination], destination);
+  };
+  fs.unlinkSync = function (path) {
+    var target = filePath(path);
+    bridge('fsRm', 'unlink', target, [target, false, false]);
+  };
+  fs.rmdirSync = function (path, options) {
+    var target = filePath(path);
+    bridge('fsRm', 'rmdir', target, [target, Boolean(options && options.recursive), false]);
+  };
+  fs.constants = constants;
+  fs.Stats = Stats;
+  fs.Dirent = Dirent;
+
+  var callbackNames = [
+    ['readFile', fs.readFileSync],
+    ['writeFile', fs.writeFileSync],
+    ['appendFile', fs.appendFileSync],
+    ['stat', fs.statSync],
+    ['lstat', fs.lstatSync],
+    ['readdir', fs.readdirSync],
+    ['mkdir', fs.mkdirSync],
+    ['rm', fs.rmSync],
+    ['symlink', fs.symlinkSync],
+    ['readlink', fs.readlinkSync],
+    ['chmod', fs.chmodSync],
+    ['realpath', fs.realpathSync],
+    ['rename', fs.renameSync],
+    ['copyFile', fs.copyFileSync],
+    ['unlink', fs.unlinkSync],
+    ['rmdir', fs.rmdirSync]
+  ];
+  function callbackify(name, sync) {
+    fs[name] = function () {
+      var args = Array.prototype.slice.call(arguments);
+      var callback = args.pop();
+      if (typeof callback !== 'function') throw new TypeError('The "cb" argument must be of type function. Received ' + typeof callback);
+      Promise.resolve().then(function () {
+        return sync.apply(fs, args);
+      }).then(function (value) {
+        callback(null, value);
+      }, function (error) {
+        callback(error);
+      });
+    };
+  }
+  for (var index = 0; index < callbackNames.length; index++) callbackify(callbackNames[index][0], callbackNames[index][1]);
+  fs.exists = function (path, callback) {
+    if (typeof callback !== 'function') throw new TypeError('The "cb" argument must be of type function. Received ' + typeof callback);
+    Promise.resolve().then(function () { callback(fs.existsSync(path)); });
+  };
+
+  var promiseNames = [
+    'readFile', 'writeFile', 'appendFile', 'stat', 'lstat', 'readdir',
+    'mkdir', 'rm', 'symlink', 'readlink', 'chmod', 'realpath',
+    'rename', 'copyFile', 'unlink', 'rmdir'
+  ];
+  fs.promises = {};
+  for (var index = 0; index < promiseNames.length; index++) (function (name) {
+    var sync = fs[name + 'Sync'];
+    fs.promises[name] = function () {
+      var args = arguments;
+      return new Promise(function (resolve, reject) {
+        Promise.resolve().then(function () {
+          return sync.apply(fs, args);
+        }).then(resolve, reject);
+      });
+    };
+  })(promiseNames[index]);
+  fs.promises.access = function (path, mode) {
+    return new Promise(function (resolve, reject) {
+      Promise.resolve().then(function () {
+        fs.accessSync(path, mode);
+      }).then(resolve, reject);
+    });
+  };
+
+  globalThis.fs = fs;
+})();
+`;
 
 // src/resource-fs.ts
 var EROFS = /* @__PURE__ */ __name(() => new Error("EROFS: resource mounts are read-only"), "EROFS");
@@ -513,8 +916,9 @@ function traversable(stat2) {
 }
 __name(traversable, "traversable");
 async function createSandbox(layout, options) {
+  const { Bash, InMemoryFs, MountableFs, OverlayFs, ReadWriteFs } = await import("just-bash");
   const { home } = options;
-  class Writable extends import_just_bash.ReadWriteFs {
+  class Writable extends ReadWriteFs {
     static {
       __name(this, "Writable");
     }
@@ -525,36 +929,35 @@ async function createSandbox(layout, options) {
       return traversable(await super.lstat(path7));
     }
   }
-  const homeView = new import_just_bash.MountableFs({
-    base: new import_just_bash.InMemoryFs(),
-    mounts: [{ mountPoint: HOME_MOUNT, filesystem: new import_just_bash.OverlayFs({ root: home, mountPoint: "/", readOnly: true }) }]
+  const homeView = new MountableFs({
+    base: new InMemoryFs(),
+    mounts: [{ mountPoint: HOME_MOUNT, filesystem: new OverlayFs({ root: home, mountPoint: "/", readOnly: true }) }]
   });
-  const fs3 = new import_just_bash.MountableFs({
+  const fs3 = new MountableFs({
     base: homeView,
     mounts: [
       { mountPoint: WORKSPACE_MOUNT, filesystem: new Writable({ root: import_node_path4.default.join(home, "workspace") }) },
       ...options.resources ? [{ mountPoint: ISHIKI_MOUNT, filesystem: new ResourceFs(options.resources) }] : [],
       ...layout.mounts.map((mount) => ({
         mountPoint: mount.target,
-        filesystem: mount.readOnly ? new import_just_bash.OverlayFs({ root: mount.source, mountPoint: "/", readOnly: true }) : new Writable({ root: mount.source })
+        filesystem: mount.readOnly ? new OverlayFs({ root: mount.source, mountPoint: "/", readOnly: true }) : new Writable({ root: mount.source })
       }))
     ]
   });
-  const bash = new import_just_bash.Bash({
+  const bash = new Bash({
     fs: fs3,
     cwd: layout.cwd,
     network: layout.network ? { dangerouslyAllowFullInternetAccess: true, denyPrivateRanges: true } : void 0,
-    javascript: layout.javascript,
+    javascript: layout.javascript ? { bootstrap: JAVASCRIPT_FS_BOOTSTRAP } : false,
     python: layout.python,
-    executionLimits: { maxOutputSize: layout.maxExecutionOutputBytes }
+    executionLimits: sandboxExecutionLimits(layout)
   });
   return {
     ...layout,
     fs: fs3,
     async exec(command, signal) {
-      const timeout = AbortSignal.timeout(layout.timeoutMs);
       try {
-        const result = await bash.exec(command, { signal: signal === void 0 ? timeout : AbortSignal.any([signal, timeout]) });
+        const result = await bash.exec(command, { signal });
         return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };
       } catch (error) {
         return { stdout: "", stderr: `bash: ${error instanceof Error ? error.message : String(error)}`, exitCode: 1 };
@@ -582,8 +985,12 @@ var import_node_path6 = __toESM(require("node:path"));
 // src/skills.ts
 var import_node_fs3 = require("node:fs");
 var import_node_path5 = __toESM(require("node:path"));
+var import_node_url = require("node:url");
 var import_yaml = require("yaml");
+var import_meta = {};
 var NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var moduleDirectory = typeof __dirname === "string" ? __dirname : import_node_path5.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url));
+var BUILTIN_SKILLS_DIRECTORY = import_node_path5.default.resolve(moduleDirectory, "..", "resources", "skills");
 function discoverSkills(roots, logger) {
   const found = /* @__PURE__ */ new Map();
   for (const root of roots) {
@@ -658,7 +1065,10 @@ function defaultShell(configured) {
 __name(defaultShell, "defaultShell");
 function resolveLayout(options) {
   const { config } = options;
-  const skills = discoverSkills([import_node_path6.default.join(options.dataPath, "skills"), ...config.skills.map((dir) => import_node_path6.default.resolve(options.root, dir))], options.logger);
+  const skills = discoverSkills(
+    [BUILTIN_SKILLS_DIRECTORY, import_node_path6.default.join(options.dataPath, "skills"), ...config.skills.map((dir) => import_node_path6.default.resolve(options.root, dir))],
+    options.logger
+  );
   const workspace = import_node_path6.default.join(options.home, "workspace");
   (0, import_node_fs4.mkdirSync)(workspace, { recursive: true });
   const backend = config.backend;
@@ -698,6 +1108,9 @@ Run a bash command inside the sandbox.
 The sandbox is a JavaScript-interpreted virtual environment, not a host shell: only files under the mounts are visible, and the command set is not the host's.
 {% endif %}
 Write paths outside the current working directory in full. cd, aliases, functions, and exported variables do not persist between calls.
+{% if not native %}
+/tmp belongs to the current sandbox lifetime. Read a /tmp file only after the same or an earlier successful call created it; a failed or timed-out call may leave nothing behind. Write results that must survive to the workspace or an artifact.
+{% endif %}
 {% if gitBashPaths %}
 Command text follows git-bash path syntax: /d/work means D:\\work. A path inside a string that only gets handed to another program (a JavaScript string passed to node, a config value) is not converted, so write D:/... there.
 Write scratch files under the working directory rather than /tmp: the shell, a program it starts, and the file tools may resolve /tmp to different folders.
@@ -761,7 +1174,7 @@ function createWorkspaceTools(sandbox) {
 ${output.stdout}`);
         if (output.stderr.length > 0) sections.push(`stderr:
 ${output.stderr}`);
-        return { type: "text", value: sections.join("\n\n") };
+        return { type: output.exitCode === 0 ? "text" : "error-text", value: sections.join("\n\n") };
       }, "toModelOutput"),
       execute: /* @__PURE__ */ __name((input, options) => sandbox.exec(input.command, options.abortSignal), "execute")
     }),
@@ -863,22 +1276,22 @@ var WorkspaceExtension = class extends import_koishi_plugin_ishiki4.Extension {
     this.logger.level = config.logLevel;
     this.dataPath = ctx.ishiki.dataPath;
   }
-  [import_koishi2.Service.invoke](config, context) {
+  [import_koishi2.Service.invoke](host, config) {
     const shellOptions = {
       config,
-      home: context.home,
-      root: context.root,
+      home: host.home,
+      root: host.root,
       dataPath: this.dataPath,
       logger: this.logger,
-      resources: context.resources
+      resources: host.resources
     };
     const layout = resolveLayout(shellOptions);
     let shell;
     let tools;
     const box = /* @__PURE__ */ __name(() => shell ??= layout.backend === "native" ? createNativeShell(layout) : createSandbox(layout, shellOptions), "box");
     const disposers = [];
-    disposers.push(context.resources?.attach(new SkillScheme(layout.skills)));
-    disposers.push(context.resources?.attach(new WorkspaceScheme(async () => (await box()).fs)));
+    disposers.push(host.resources?.attach(new SkillScheme(layout.skills)));
+    disposers.push(host.resources?.attach(new WorkspaceScheme(async () => (await box()).fs)));
     return {
       name: "ishiki.workspace",
       extendTools: /* @__PURE__ */ __name(async () => tools ??= createWorkspaceTools(await box()), "extendTools"),

package/lib/index.d.ts

@@ -1,12 +1,12 @@
 import { Schema, Service, type Context } from "koishi";
-import { Extension, type ExtensionContext, type ToolSet } from "koishi-plugin-ishiki";
+import { Extension, type ExtensionHost, type ToolSet } from "koishi-plugin-ishiki";
 import { WorkspaceConfig } from "./config.js";
 declare class WorkspaceExtension extends Extension<WorkspaceConfig> {
     static inject: string[];
     readonly Schema: Schema<WorkspaceConfig>;
     private readonly dataPath;
     constructor(ctx: Context, config: WorkspaceExtension.Config);
-    [Service.invoke](config: WorkspaceConfig, context: ExtensionContext): {
+    [Service.invoke](host: ExtensionHost, config: WorkspaceConfig): {
         name: string;
         extendTools: () => Promise<ToolSet>;
         extendInstructions: () => Promise<string>;

package/lib/index.js

@@ -16,7 +16,7 @@ var WorkspaceConfig = Schema.object({
   network: Schema.boolean().description("仅 sandbox 模式：允许沙箱内访问网络；开启时仍拒绝私有地址。native 走宿主机真实网络").default(false),
   javascript: Schema.boolean().description("仅 sandbox 模式：启用 js-exec 命令（QuickJS 里执行 JavaScript / TypeScript）；默认关闭，开它会多一份代码执行面").default(false),
   python: Schema.boolean().description("仅 sandbox 模式：启用 python3 / python 命令（CPython 编译成 WebAssembly）；默认关闭，开它会多一份代码执行面").default(false),
-  skills: Schema.array(Schema.string()).description("额外技能目录，相对 profile 目录解析；与数据根的 skills 目录合并，同名以这里优先").default([]),
+  skills: Schema.array(Schema.string()).description("额外技能目录，相对 profile 目录解析；与内置技能和数据的 skills 目录合并，同名时依次覆盖，以这里优先").default([]),
   mounts: Schema.array(Schema.string()).description("仅 sandbox 模式：宿主目录挂载，写法 `source:target[:ro]`；source 相对 profile 目录解析，省略 :ro 即可读写。native 模式无虚拟路径，不解析").default([])
 });
 
@@ -218,8 +218,9 @@ Use read_file to read a known file, write_file to replace a file, edit_file for
 );
 var SANDBOX_INSTRUCTIONS = new Template(
   `## Workspace
-You read and write files in a per-instance sandbox, not on the host: commands are interpreted by JavaScript, only the mounted paths below exist, and host paths and commands are invisible.
+You read and write files in a per-instance sandbox, not on the host: commands run in just-bash, only the mounted paths below exist, and host paths and commands are invisible.
 The command set is not the host's.
+Runtime details and API gaps are recorded in the bundled sandbox-environment skill; read it before writing JavaScript, TypeScript, Python, SQLite, or network-heavy commands.
 Current working directory: {{ cwd }}
 Mounts:
 - {{ homeMount }}: read-only, this instance's data directory (writes fail)
@@ -237,11 +238,12 @@ Network: {{ network }}
 Command timeout: {{ timeoutMs }} ms; a timeout returns exit code 124.
 Executor output safety limit: {{ maxExecutionOutputBytes }} bytes. Inside codemode you receive the raw output; the runtime handles model-visible previews and archives. Return structured results instead of stringifying or slicing them yourself.
 Shell state does not persist between calls: cd, aliases, functions, and exported variables are not retained. Put a directory change on the same line (cd <dir> && <command>).
+/tmp belongs to this sandbox lifetime. Read a /tmp file only after the same or an earlier successful call created it; a failed or timed-out call may leave nothing behind. Write results that must survive to the workspace or an artifact.
 {% if javascript %}
-js-exec is available: run JavaScript / TypeScript in QuickJS. Some node modules can be required or imported; only files inside the sandbox are accessible.
+js-exec is available: run JavaScript / TypeScript in QuickJS with a partial Node.js module surface. Only files inside the sandbox are accessible.
 {% endif %}
 {% if python %}
-python3 and python are available: CPython compiled to WebAssembly with the full standard library. The first call waits for it to load; reads and writes target this sandbox.
+python3 and python are available: CPython compiled to WebAssembly. Most of the standard library is available, but subprocess and the sqlite3 module are absent. The first call waits for it to load; reads and writes target this sandbox.
 {% endif %}
 You can also read a known file through read's workspace:///<sandbox-path> URL (e.g. workspace:///home/workspace/a.txt): virtual files, persistent directories, and mounts all resolve to the same sandbox file.
 Use read_file to read a known file, write_file to replace a file, edit_file for a small edit, and bash for listing, searching, and pipelines.`
@@ -323,7 +325,408 @@ var WorkspaceScheme = class extends FileScheme {
 
 // src/sandbox.ts
 import path4 from "node:path";
-import { Bash, InMemoryFs, MountableFs, OverlayFs, ReadWriteFs } from "just-bash";
+
+// src/execution-limits.ts
+function sandboxExecutionLimits(layout) {
+  return {
+    maxOutputSize: layout.maxExecutionOutputBytes,
+    maxExecutionTimeMs: layout.timeoutMs,
+    maxSqliteTimeoutMs: layout.timeoutMs,
+    maxPythonTimeoutMs: layout.timeoutMs,
+    maxJsTimeoutMs: layout.timeoutMs
+  };
+}
+__name(sandboxExecutionLimits, "sandboxExecutionLimits");
+
+// src/js-bootstrap.ts
+var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
+(function () {
+  var hostKey = Object.getOwnPropertyNames(globalThis).filter(function (name) {
+    return name.indexOf('__jbHost_') === 0;
+  })[0];
+  if (!hostKey) throw new Error('js-exec host bridge is unavailable');
+  var host = globalThis[hostKey];
+  var fs = globalThis.fs;
+  function unwrap(result) {
+    if (!result || result.ok !== true) throw new Error(result && result.error || 'Host operation failed');
+    return result.value;
+  }
+  var raw = {};
+  var names = [
+    'readFileBuffer', 'readFileSync', 'writeFileSync', 'appendFileSync',
+    'statSync', 'lstatSync', 'readdirSync', 'mkdirSync', 'rmSync',
+    'symlinkSync', 'readlinkSync', 'chmodSync', 'realpathSync',
+    'renameSync', 'copyFileSync'
+  ];
+  for (var index = 0; index < names.length; index++) raw[names[index]] = fs[names[index]];
+
+  var errnos = {
+    EPERM: -1,
+    ENOENT: -2,
+    EIO: -5,
+    EACCES: -13,
+    EEXIST: -17,
+    ENOTDIR: -20,
+    EISDIR: -21,
+    EINVAL: -22,
+    ENOSPC: -28,
+    EROFS: -30,
+    ENAMETOOLONG: -36,
+    ENOTEMPTY: -39,
+    ELOOP: -40
+  };
+
+  var constants = {
+    F_OK: 0,
+    R_OK: 4,
+    W_OK: 2,
+    X_OK: 1,
+    COPYFILE_EXCL: 1,
+    COPYFILE_FICLONE: 2,
+    COPYFILE_FICLONE_FORCE: 4,
+    S_IFMT: 61440,
+    S_IFREG: 32768,
+    S_IFDIR: 16384,
+    S_IFLNK: 40960,
+    O_RDONLY: 0,
+    O_WRONLY: 1,
+    O_RDWR: 2,
+    O_CREAT: 64,
+    O_EXCL: 128,
+    O_TRUNC: 512,
+    O_APPEND: 1024
+  };
+
+  function failure(error, syscall, target, destination) {
+    if (!(error instanceof Error)) error = new Error(String(error));
+    var matched = /^([A-Z][A-Z0-9]+):/.exec(error.message);
+    if (matched) {
+      error.code = matched[1];
+      if (errnos[error.code] !== undefined) error.errno = errnos[error.code];
+    }
+    error.syscall = syscall;
+    if (target !== undefined) {
+      error.path = String(target);
+      error.message = error.message.replace(/'[^']*'(?=\s*$)/, "'" + String(target).replace(/'/g, "\\'") + "'");
+    }
+    if (destination !== undefined) error.dest = String(destination);
+    return error;
+  }
+
+  function filePath(value) {
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      typeof value.href !== 'string' ||
+      typeof value.protocol !== 'string'
+    ) return value;
+    if (value.protocol !== 'file:') {
+      throw failure(new Error('ERR_INVALID_URL_SCHEME: The URL must be of scheme file, received ' + value.protocol), 'open', value.href);
+    }
+    if (value.hostname && value.hostname !== 'localhost') {
+      throw failure(new Error('ERR_INVALID_FILE_URL_HOST: File URL host must be "localhost" or empty, received ' + value.hostname), 'open', value.href);
+    }
+    return decodeURIComponent(value.pathname);
+  }
+
+  function bridge(hostName, syscall, target, args, destination) {
+    try {
+      var operation = host[hostName];
+      if (args.length === 1) return unwrap(operation(args[0]));
+      if (args.length === 2) return unwrap(operation(args[0], args[1]));
+      if (args.length === 3) return unwrap(operation(args[0], args[1], args[2]));
+      return unwrap(operation(args[0], args[1], args[2], args[3]));
+    } catch (error) {
+      throw failure(error, syscall, target, destination);
+    }
+  }
+
+  function bytes(value) {
+    if (value && value._data instanceof Uint8Array) return Array.from(value._data);
+    if (value && Array.isArray(value._data)) return value._data.slice();
+    if (Array.isArray(value)) return value.slice();
+    if (value instanceof Uint8Array) return Array.from(value);
+    return String(value);
+  }
+
+  function Stats() {}
+  function Dirent() {}
+
+  function stats(value) {
+    var mtime = value.mtime instanceof Date ? value.mtime : new Date(value.mtime);
+    var size = Number(value.size);
+    var result = Object.create(Stats.prototype);
+    result.dev = 0;
+    result.ino = 0;
+    result.mode = Number(value.mode);
+    result.nlink = value.isDirectory ? 2 : 1;
+    result.uid = 1000;
+    result.gid = 1000;
+    result.rdev = 0;
+    result.size = size;
+    result.blksize = 4096;
+    result.blocks = Math.ceil(size / 512);
+    result.atime = mtime;
+    result.mtime = mtime;
+    result.ctime = mtime;
+    result.birthtime = mtime;
+    result.atimeMs = mtime.getTime();
+    result.mtimeMs = mtime.getTime();
+    result.ctimeMs = mtime.getTime();
+    result.birthtimeMs = mtime.getTime();
+    result.isFile = function () { return value.isFile; };
+    result.isDirectory = function () { return value.isDirectory; };
+    result.isSymbolicLink = function () { return value.isSymbolicLink; };
+    result.isBlockDevice = function () { return false; };
+    result.isCharacterDevice = function () { return false; };
+    result.isFIFO = function () { return false; };
+    result.isSocket = function () { return false; };
+    return result;
+  }
+
+  function dirent(name, parentPath, value) {
+    var result = Object.create(Dirent.prototype);
+    result.name = String(name);
+    result.parentPath = String(parentPath);
+    result.path = String(parentPath);
+    result.isFile = function () { return value.isFile; };
+    result.isDirectory = function () { return value.isDirectory; };
+    result.isSymbolicLink = function () { return value.isSymbolicLink; };
+    result.isBlockDevice = function () { return false; };
+    result.isCharacterDevice = function () { return false; };
+    result.isFIFO = function () { return false; };
+    result.isSocket = function () { return false; };
+    return result;
+  }
+
+  function childPath(parent, name) {
+    return parent.charAt(parent.length - 1) === '/' ? parent + name : parent + '/' + name;
+  }
+
+  function readStats(path, follow) {
+    var target = filePath(path);
+    return bridge('fsStat', follow ? 'stat' : 'lstat', target, [target, !follow]);
+  }
+
+  function collect(path, relative, options, output) {
+    var listing = bridge('fsReaddir', 'scandir', path, [path]);
+    for (var index = 0; index < listing.length; index++) {
+      var name = listing[index];
+      var nested = relative === '' ? name : relative + '/' + name;
+      var full = childPath(path, name);
+      var value = readStats(full, false);
+      output.push(options.withFileTypes ? dirent(name, path, value) : nested);
+      if (options.recursive && value.isDirectory) collect(full, nested, options, output);
+    }
+  }
+
+  function readdir(path, options) {
+    var target = filePath(path);
+    if (typeof options === 'string') options = { encoding: options };
+    options = options || {};
+    var output = [];
+    collect(target, '', { recursive: Boolean(options.recursive), withFileTypes: Boolean(options.withFileTypes) }, output);
+    if (options.encoding === 'buffer') return output.map(function (entry) {
+      return typeof entry === 'string' ? Buffer.from(entry) : entry;
+    });
+    return output;
+  }
+
+  function firstCreated(path) {
+    var text = String(filePath(path));
+    var absolute = text.charAt(0) === '/';
+    var parts = text.split('/');
+    var current = '';
+    var found;
+    for (var index = 0; index < parts.length; index++) {
+      var part = parts[index];
+      if (part === '' || part === '.') continue;
+      if (current === '') current = absolute ? '/' + part : part;
+      else current = childPath(current, part);
+      if (!fs.existsSync(current)) {
+        found = current;
+        break;
+      }
+    }
+    return found;
+  }
+
+  fs.readFileBuffer = function (path) {
+    var target = filePath(path);
+    try {
+      return Buffer.from(raw.readFileBuffer(target));
+    } catch (error) {
+      throw failure(error, 'open', target);
+    }
+  };
+  fs.readFileSync = function (path, options) {
+    var target = filePath(path);
+    try {
+      return raw.readFileSync(target, options);
+    } catch (error) {
+      throw failure(error, 'open', target);
+    }
+  };
+  fs.writeFileSync = function (path, data) {
+    var target = filePath(path);
+    bridge('fsWrite', 'open', target, [target, bytes(data)]);
+  };
+  fs.appendFileSync = function (path, data) {
+    var target = filePath(path);
+    bridge('fsAppend', 'open', target, [target, bytes(data)]);
+  };
+  fs.statSync = function (path) {
+    return stats(readStats(path, true));
+  };
+  fs.lstatSync = function (path) {
+    return stats(readStats(path, false));
+  };
+  fs.readdirSync = readdir;
+  fs.mkdirSync = function (path, options) {
+    var target = filePath(path);
+    var recursive = Boolean(options && typeof options === 'object' && options.recursive);
+    var created = recursive ? firstCreated(target) : undefined;
+    bridge('fsMkdir', 'mkdir', target, [target, recursive]);
+    return created;
+  };
+  fs.rmSync = function (path, options) {
+    var target = filePath(path);
+    bridge('fsRm', 'rm', target, [target, Boolean(options && options.recursive), Boolean(options && options.force)]);
+  };
+  fs.existsSync = function (path) {
+    var target = filePath(path);
+    try {
+      return bridge('fsExists', 'access', target, [target]);
+    } catch (error) {
+      return false;
+    }
+  };
+  fs.accessSync = function (path, mode) {
+    var target = filePath(path);
+    if (!bridge('fsExists', 'access', target, [target])) {
+      throw failure(new Error("ENOENT: no such file or directory, access '" + target + "'"), 'access', target);
+    }
+    var flags = mode === undefined ? 0 : Number(mode);
+    if ((flags & ~7) !== 0) {
+      throw failure(new Error("EINVAL: invalid mode argument, access '" + target + "'"), 'access', target);
+    }
+    if (flags === 0) return;
+    var permissions = stats(readStats(target, true)).mode & 511;
+    var required = 0;
+    if (flags & constants.R_OK) required |= 256;
+    if (flags & constants.W_OK) required |= 128;
+    if (flags & constants.X_OK) required |= 64;
+    if ((permissions & required) !== required) {
+      throw failure(new Error("EACCES: permission denied, access '" + target + "'"), 'access', target);
+    }
+  };
+  fs.symlinkSync = function (target, path) {
+    var link = filePath(path);
+    bridge('fsSymlink', 'symlink', link, [filePath(target), link]);
+  };
+  fs.readlinkSync = function (path) {
+    var target = filePath(path);
+    return bridge('fsReadlink', 'readlink', target, [target]);
+  };
+  fs.chmodSync = function (path, mode) {
+    var target = filePath(path);
+    bridge('fsChmod', 'chmod', target, [target, Number(mode)]);
+  };
+  fs.realpathSync = function (path) {
+    var target = filePath(path);
+    return bridge('fsRealpath', 'realpath', target, [target]);
+  };
+  fs.renameSync = function (from, to) {
+    var source = filePath(from);
+    var destination = filePath(to);
+    bridge('fsRename', 'rename', source, [source, destination], destination);
+  };
+  fs.copyFileSync = function (from, to, mode) {
+    var source = filePath(from);
+    var destination = filePath(to);
+    if ((Number(mode) || 0) & constants.COPYFILE_EXCL && fs.existsSync(destination)) {
+      throw failure(new Error("EEXIST: file already exists, copyfile '" + destination + "'"), 'copyfile', source, destination);
+    }
+    bridge('fsCopy', 'copyfile', source, [source, destination], destination);
+  };
+  fs.unlinkSync = function (path) {
+    var target = filePath(path);
+    bridge('fsRm', 'unlink', target, [target, false, false]);
+  };
+  fs.rmdirSync = function (path, options) {
+    var target = filePath(path);
+    bridge('fsRm', 'rmdir', target, [target, Boolean(options && options.recursive), false]);
+  };
+  fs.constants = constants;
+  fs.Stats = Stats;
+  fs.Dirent = Dirent;
+
+  var callbackNames = [
+    ['readFile', fs.readFileSync],
+    ['writeFile', fs.writeFileSync],
+    ['appendFile', fs.appendFileSync],
+    ['stat', fs.statSync],
+    ['lstat', fs.lstatSync],
+    ['readdir', fs.readdirSync],
+    ['mkdir', fs.mkdirSync],
+    ['rm', fs.rmSync],
+    ['symlink', fs.symlinkSync],
+    ['readlink', fs.readlinkSync],
+    ['chmod', fs.chmodSync],
+    ['realpath', fs.realpathSync],
+    ['rename', fs.renameSync],
+    ['copyFile', fs.copyFileSync],
+    ['unlink', fs.unlinkSync],
+    ['rmdir', fs.rmdirSync]
+  ];
+  function callbackify(name, sync) {
+    fs[name] = function () {
+      var args = Array.prototype.slice.call(arguments);
+      var callback = args.pop();
+      if (typeof callback !== 'function') throw new TypeError('The "cb" argument must be of type function. Received ' + typeof callback);
+      Promise.resolve().then(function () {
+        return sync.apply(fs, args);
+      }).then(function (value) {
+        callback(null, value);
+      }, function (error) {
+        callback(error);
+      });
+    };
+  }
+  for (var index = 0; index < callbackNames.length; index++) callbackify(callbackNames[index][0], callbackNames[index][1]);
+  fs.exists = function (path, callback) {
+    if (typeof callback !== 'function') throw new TypeError('The "cb" argument must be of type function. Received ' + typeof callback);
+    Promise.resolve().then(function () { callback(fs.existsSync(path)); });
+  };
+
+  var promiseNames = [
+    'readFile', 'writeFile', 'appendFile', 'stat', 'lstat', 'readdir',
+    'mkdir', 'rm', 'symlink', 'readlink', 'chmod', 'realpath',
+    'rename', 'copyFile', 'unlink', 'rmdir'
+  ];
+  fs.promises = {};
+  for (var index = 0; index < promiseNames.length; index++) (function (name) {
+    var sync = fs[name + 'Sync'];
+    fs.promises[name] = function () {
+      var args = arguments;
+      return new Promise(function (resolve, reject) {
+        Promise.resolve().then(function () {
+          return sync.apply(fs, args);
+        }).then(resolve, reject);
+      });
+    };
+  })(promiseNames[index]);
+  fs.promises.access = function (path, mode) {
+    return new Promise(function (resolve, reject) {
+      Promise.resolve().then(function () {
+        fs.accessSync(path, mode);
+      }).then(resolve, reject);
+    });
+  };
+
+  globalThis.fs = fs;
+})();
+`;
 
 // src/resource-fs.ts
 var EROFS = /* @__PURE__ */ __name(() => new Error("EROFS: resource mounts are read-only"), "EROFS");
@@ -481,6 +884,7 @@ function traversable(stat2) {
 }
 __name(traversable, "traversable");
 async function createSandbox(layout, options) {
+  const { Bash, InMemoryFs, MountableFs, OverlayFs, ReadWriteFs } = await import("just-bash");
   const { home } = options;
   class Writable extends ReadWriteFs {
     static {
@@ -512,17 +916,16 @@ async function createSandbox(layout, options) {
     fs: fs3,
     cwd: layout.cwd,
     network: layout.network ? { dangerouslyAllowFullInternetAccess: true, denyPrivateRanges: true } : void 0,
-    javascript: layout.javascript,
+    javascript: layout.javascript ? { bootstrap: JAVASCRIPT_FS_BOOTSTRAP } : false,
     python: layout.python,
-    executionLimits: { maxOutputSize: layout.maxExecutionOutputBytes }
+    executionLimits: sandboxExecutionLimits(layout)
   });
   return {
     ...layout,
     fs: fs3,
     async exec(command, signal) {
-      const timeout = AbortSignal.timeout(layout.timeoutMs);
       try {
-        const result = await bash.exec(command, { signal: signal === void 0 ? timeout : AbortSignal.any([signal, timeout]) });
+        const result = await bash.exec(command, { signal });
         return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };
       } catch (error) {
         return { stdout: "", stderr: `bash: ${error instanceof Error ? error.message : String(error)}`, exitCode: 1 };
@@ -550,8 +953,11 @@ import path6 from "node:path";
 // src/skills.ts
 import { readdirSync, readFileSync, statSync as statSync2 } from "node:fs";
 import path5 from "node:path";
+import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
 var NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var moduleDirectory = typeof __dirname === "string" ? __dirname : path5.dirname(fileURLToPath(import.meta.url));
+var BUILTIN_SKILLS_DIRECTORY = path5.resolve(moduleDirectory, "..", "resources", "skills");
 function discoverSkills(roots, logger) {
   const found = /* @__PURE__ */ new Map();
   for (const root of roots) {
@@ -626,7 +1032,10 @@ function defaultShell(configured) {
 __name(defaultShell, "defaultShell");
 function resolveLayout(options) {
   const { config } = options;
-  const skills = discoverSkills([path6.join(options.dataPath, "skills"), ...config.skills.map((dir) => path6.resolve(options.root, dir))], options.logger);
+  const skills = discoverSkills(
+    [BUILTIN_SKILLS_DIRECTORY, path6.join(options.dataPath, "skills"), ...config.skills.map((dir) => path6.resolve(options.root, dir))],
+    options.logger
+  );
   const workspace = path6.join(options.home, "workspace");
   mkdirSync2(workspace, { recursive: true });
   const backend = config.backend;
@@ -666,6 +1075,9 @@ Run a bash command inside the sandbox.
 The sandbox is a JavaScript-interpreted virtual environment, not a host shell: only files under the mounts are visible, and the command set is not the host's.
 {% endif %}
 Write paths outside the current working directory in full. cd, aliases, functions, and exported variables do not persist between calls.
+{% if not native %}
+/tmp belongs to the current sandbox lifetime. Read a /tmp file only after the same or an earlier successful call created it; a failed or timed-out call may leave nothing behind. Write results that must survive to the workspace or an artifact.
+{% endif %}
 {% if gitBashPaths %}
 Command text follows git-bash path syntax: /d/work means D:\\work. A path inside a string that only gets handed to another program (a JavaScript string passed to node, a config value) is not converted, so write D:/... there.
 Write scratch files under the working directory rather than /tmp: the shell, a program it starts, and the file tools may resolve /tmp to different folders.
@@ -729,7 +1141,7 @@ function createWorkspaceTools(sandbox) {
 ${output.stdout}`);
         if (output.stderr.length > 0) sections.push(`stderr:
 ${output.stderr}`);
-        return { type: "text", value: sections.join("\n\n") };
+        return { type: output.exitCode === 0 ? "text" : "error-text", value: sections.join("\n\n") };
       }, "toModelOutput"),
       execute: /* @__PURE__ */ __name((input, options) => sandbox.exec(input.command, options.abortSignal), "execute")
     }),
@@ -831,22 +1243,22 @@ var WorkspaceExtension = class extends Extension {
     this.logger.level = config.logLevel;
     this.dataPath = ctx.ishiki.dataPath;
   }
-  [Service.invoke](config, context) {
+  [Service.invoke](host, config) {
     const shellOptions = {
       config,
-      home: context.home,
-      root: context.root,
+      home: host.home,
+      root: host.root,
       dataPath: this.dataPath,
       logger: this.logger,
-      resources: context.resources
+      resources: host.resources
     };
     const layout = resolveLayout(shellOptions);
     let shell;
     let tools;
     const box = /* @__PURE__ */ __name(() => shell ??= layout.backend === "native" ? createNativeShell(layout) : createSandbox(layout, shellOptions), "box");
     const disposers = [];
-    disposers.push(context.resources?.attach(new SkillScheme(layout.skills)));
-    disposers.push(context.resources?.attach(new WorkspaceScheme(async () => (await box()).fs)));
+    disposers.push(host.resources?.attach(new SkillScheme(layout.skills)));
+    disposers.push(host.resources?.attach(new WorkspaceScheme(async () => (await box()).fs)));
     return {
       name: "ishiki.workspace",
       extendTools: /* @__PURE__ */ __name(async () => tools ??= createWorkspaceTools(await box()), "extendTools"),

package/lib/js-bootstrap.d.ts

@@ -0,0 +1,5 @@
+/**
+ * js-exec 的 fs 适配。just-bash 在 guest 中压平了 stat、丢弃了 readdir 选项，
+ * 并把桥接错误变成普通 Error；这里在用户代码加载前补齐 Node 的文件系统约定。
+ */
+export declare const JAVASCRIPT_FS_BOOTSTRAP: string;

package/lib/skills.d.ts

@@ -4,5 +4,6 @@ export interface Skill {
     readonly description: string;
     readonly directory: string;
 }
+export declare const BUILTIN_SKILLS_DIRECTORY: string;
 export declare function discoverSkills(roots: readonly string[], logger: Logger): Skill[];
 export declare function skillCatalog(skills: readonly Skill[], native: boolean): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koishi-plugin-ishiki-workspace",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Workspace tools for Ishiki: sandboxed or native shell, file tools and skills",
   "keywords": [
     "agent",
@@ -21,7 +21,8 @@
     "directory": "packages/workspace"
   },
   "files": [
-    "lib"
+    "lib",
+    "resources"
   ],
   "main": "./lib/index.cjs",
   "module": "./lib/index.js",
@@ -44,11 +45,11 @@
   },
   "devDependencies": {
     "koishi": "^4.18.11",
-    "koishi-plugin-ishiki": ">=0.0.3 <0.1.0"
+    "koishi-plugin-ishiki": ">=0.0.5 <0.1.0"
   },
   "peerDependencies": {
     "koishi": "^4.18.11",
-    "koishi-plugin-ishiki": ">=0.0.3 <0.1.0"
+    "koishi-plugin-ishiki": ">=0.0.5 <0.1.0"
   },
   "koishi": {
     "description": {

package/resources/skills/sandbox-environment/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: sandbox-environment
+description: Use before running or debugging shell commands, JavaScript, TypeScript, Python, SQLite, networking, or file operations in the Ishiki sandbox; it routes work to the supported runtime and records the environment's API gaps.
+---
+
+# Sandbox Environment
+
+The workspace is a just-bash environment with optional QuickJS and WebAssembly Python runtimes. Choose the executor before writing runtime-specific code.
+
+## Choose the executor
+
+- Use the POSIX shell for file discovery, text pipelines, archive commands, and the SQLite command-line tool.
+- Use `js-exec <file>` for JavaScript or TypeScript. The `node` command is a usage notice, so it does not execute scripts.
+- Use `python3` or `python` for Python code. The first invocation waits for the WebAssembly runtime to load.
+
+Read the matching reference before using runtime-specific APIs:
+
+- Shell commands, mounts, SQLite, and networking: [references/shell.md](references/shell.md)
+- JavaScript modules, globals, `fs`, and async callbacks: [references/javascript.md](references/javascript.md)
+- Python modules, subprocesses, and persistence: [references/python.md](references/python.md)
+
+## Shared paths
+
+- `/home` is read-only and contains this instance's data directory.
+- `/home/workspace` is the writable working directory. Put scripts and generated files here.
+- `/home/skills` is read-only. Read a skill, then run only scripts that the task needs.
+
+Each shell call is isolated by the configured timeout. Environment variables, functions, aliases, and the current directory return to their defaults on the next call.

package/resources/skills/sandbox-environment/references/javascript.md

@@ -0,0 +1,44 @@
+# JavaScript Runtime
+
+Run JavaScript and TypeScript with `js-exec <file>`. It uses QuickJS and supports ESM imports, top-level await, TypeScript syntax, `fetch`, and `node:child_process`. The `node` command does not run code.
+
+## Modules and globals
+
+The runtime exposes a partial Node.js surface. These modules are unavailable:
+
+`node:zlib`, `node:crypto`, `node:net`, `node:http`, `node:https`, `node:dns`, `node:tls`, `node:readline`, `node:vm`, `node:v8`, `node:worker_threads`, `node:module`, `node:timers`, `node:tty`, and `node:sqlite3`.
+
+These browser and JavaScript globals are unavailable:
+
+`TextEncoder`, `TextDecoder`, `atob`, `btoa`, `setTimeout`, `setInterval`, `queueMicrotask`, `structuredClone`, `performance`, `WebAssembly`, and `crypto`.
+
+Use the synchronous filesystem API or `fs.promises` for file work. Use `Buffer` for UTF-8 and base64 conversion.
+
+## Filesystem API
+
+The workspace bootstrap supplies common Node `fs` behavior, including:
+
+- `Stats` and `Dirent` instances, `fs.constants`, `fs.accessSync`, and recursive `readdir`
+- callback, promise, and synchronous forms for common file and directory methods
+- file URL path arguments and `Buffer` results from `fs.readFileBuffer`
+- Node-shaped error fields such as `code`, `errno`, `syscall`, `path`, and `dest`
+
+The `node:fs` module loader publishes a fixed set of named exports. Use the default import when accessing bootstrap additions: `import fs from 'node:fs'`. Namespace imports expose the upstream method list, so additions such as `fs.constants`, `fs.Stats`, `fs.Dirent`, and `fs.accessSync` are absent from `import * as fs`.
+
+The sandbox does not expose file descriptors or streams. `openSync`, `readSync`, `writeSync`, `createReadStream`, and `createWriteStream` are absent. `cp`, `truncate`, `utimes`, `mkdtemp`, `watch`, and `opendir` are also absent. Use whole-file reads and writes, or run a shell command for unsupported operations.
+
+## Async callbacks
+
+QuickJS stops when the script's synchronous top level finishes. Keep the script alive with top-level `await` until callback work completes, or use `fs.promises`:
+
+```js
+await new Promise((resolve, reject) => {
+  fs.readFile("/home/workspace/input.txt", "utf8", (error, text) => {
+    if (error) reject(error);
+    else {
+      console.log(text);
+      resolve();
+    }
+  });
+});
+```

package/resources/skills/sandbox-environment/references/python.md

@@ -0,0 +1,14 @@
+# Python Runtime
+
+`python3` and `python` run CPython 3.13 through Emscripten. The first call waits for the runtime to load. Scripts read and write the same sandbox paths as the shell.
+
+## Available modules
+
+Most pure-Python standard library modules are available. Native integration is limited:
+
+- `subprocess` is unavailable.
+- `_sqlite3` and the `sqlite3` module are unavailable.
+- Third-party packages cannot be installed.
+- Long-running threads, sockets, and process management are unavailable.
+
+Use `/home/workspace` for scripts and generated files. For SQLite work, use the shell's `sqlite3` command. To start Python from JavaScript, use `node:child_process`; Python cannot start shell commands or other programs.

package/resources/skills/sandbox-environment/references/shell.md

@@ -0,0 +1,25 @@
+# Shell Runtime
+
+just-bash provides a POSIX-style command set, not a Linux host. Shell state does not persist between calls, and each call runs under the configured timeout.
+
+## Files and processes
+
+- Use `/home/workspace` for writable files.
+- `/home` and `/home/skills` are read-only mounts.
+- Start a process and consume its output in the same call. Background processes do not outlive the call.
+- Use `bash` pipelines for listing, searching, text transforms, and archive work that the JavaScript filesystem bridge does not expose.
+
+## SQLite
+
+The `sqlite3` command is available:
+
+```bash
+sqlite3 /home/workspace/data.db "CREATE TABLE notes (body TEXT); INSERT INTO notes VALUES ('hello');"
+sqlite3 /home/workspace/data.db "SELECT body FROM notes;"
+```
+
+The command does not support dot commands such as `.tables` or `.version`. Pass SQL as the command argument. Python's `sqlite3` module is unavailable, so use this command-line tool for database work.
+
+## Network
+
+When networking is enabled, `curl` and JavaScript `fetch` can reach public addresses. Private and loopback addresses are rejected. Check the task's configured network access before choosing a remote API.