koishi-plugin-ishiki-workspace 0.0.4 → 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.`
@@ -356,6 +358,18 @@ var WorkspaceScheme = class extends import_koishi_plugin_ishiki2.FileScheme {
 // src/sandbox.ts
 var import_node_path4 = __toESM(require("node:path"));
 
+// 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 () {
@@ -394,6 +408,27 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
     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);
@@ -410,6 +445,22 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
     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];
@@ -430,29 +481,31 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
     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 = {
-      dev: 0,
-      ino: 0,
-      mode: Number(value.mode),
-      nlink: value.isDirectory ? 2 : 1,
-      uid: 1000,
-      gid: 1000,
-      rdev: 0,
-      size: size,
-      blksize: 4096,
-      blocks: Math.ceil(size / 512),
-      atime: mtime,
-      mtime: mtime,
-      ctime: mtime,
-      birthtime: mtime,
-      atimeMs: mtime.getTime(),
-      mtimeMs: mtime.getTime(),
-      ctimeMs: mtime.getTime(),
-      birthtimeMs: mtime.getTime()
-    };
+    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; };
@@ -464,7 +517,10 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   function dirent(name, parentPath, value) {
-    var result = { name: String(name), parentPath: String(parentPath), path: String(parentPath) };
+    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; };
@@ -480,7 +536,8 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   function readStats(path, follow) {
-    return bridge('fsStat', follow ? 'stat' : 'lstat', path, [path, !follow]);
+    var target = filePath(path);
+    return bridge('fsStat', follow ? 'stat' : 'lstat', target, [target, !follow]);
   }
 
   function collect(path, relative, options, output) {
@@ -496,10 +553,11 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   function readdir(path, options) {
+    var target = filePath(path);
     if (typeof options === 'string') options = { encoding: options };
     options = options || {};
     var output = [];
-    collect(path, '', { recursive: Boolean(options.recursive), withFileTypes: Boolean(options.withFileTypes) }, 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;
     });
@@ -507,7 +565,7 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   function firstCreated(path) {
-    var text = String(path);
+    var text = String(filePath(path));
     var absolute = text.charAt(0) === '/';
     var parts = text.split('/');
     var current = '';
@@ -526,24 +584,28 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   fs.readFileBuffer = function (path) {
+    var target = filePath(path);
     try {
-      return raw.readFileBuffer(path);
+      return Buffer.from(raw.readFileBuffer(target));
     } catch (error) {
-      throw failure(error, 'open', path);
+      throw failure(error, 'open', target);
     }
   };
   fs.readFileSync = function (path, options) {
+    var target = filePath(path);
     try {
-      return raw.readFileSync(path, options);
+      return raw.readFileSync(target, options);
     } catch (error) {
-      throw failure(error, 'open', path);
+      throw failure(error, 'open', target);
     }
   };
   fs.writeFileSync = function (path, data) {
-    bridge('fsWrite', 'open', path, [path, bytes(data)]);
+    var target = filePath(path);
+    bridge('fsWrite', 'open', target, [target, bytes(data)]);
   };
   fs.appendFileSync = function (path, data) {
-    bridge('fsAppend', 'open', path, [path, bytes(data)]);
+    var target = filePath(path);
+    bridge('fsAppend', 'open', target, [target, bytes(data)]);
   };
   fs.statSync = function (path) {
     return stats(readStats(path, true));
@@ -553,45 +615,83 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   };
   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(path) : undefined;
-    bridge('fsMkdir', 'mkdir', path, [path, recursive]);
+    var created = recursive ? firstCreated(target) : undefined;
+    bridge('fsMkdir', 'mkdir', target, [target, recursive]);
     return created;
   };
   fs.rmSync = function (path, options) {
-    bridge('fsRm', 'rm', path, [path, Boolean(options && options.recursive), Boolean(options && options.force)]);
+    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', path, [path]);
+      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) {
-    bridge('fsSymlink', 'symlink', path, [target, path]);
+    var link = filePath(path);
+    bridge('fsSymlink', 'symlink', link, [filePath(target), link]);
   };
   fs.readlinkSync = function (path) {
-    return bridge('fsReadlink', 'readlink', path, [path]);
+    var target = filePath(path);
+    return bridge('fsReadlink', 'readlink', target, [target]);
   };
   fs.chmodSync = function (path, mode) {
-    bridge('fsChmod', 'chmod', path, [path, Number(mode)]);
+    var target = filePath(path);
+    bridge('fsChmod', 'chmod', target, [target, Number(mode)]);
   };
   fs.realpathSync = function (path) {
-    return bridge('fsRealpath', 'realpath', path, [path]);
+    var target = filePath(path);
+    return bridge('fsRealpath', 'realpath', target, [target]);
   };
   fs.renameSync = function (from, to) {
-    bridge('fsRename', 'rename', from, [from, to], to);
+    var source = filePath(from);
+    var destination = filePath(to);
+    bridge('fsRename', 'rename', source, [source, destination], destination);
   };
-  fs.copyFileSync = function (from, to) {
-    bridge('fsCopy', 'copyfile', from, [from, to], to);
+  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) {
-    bridge('fsRm', 'unlink', path, [path, false, false]);
+    var target = filePath(path);
+    bridge('fsRm', 'unlink', target, [target, false, false]);
   };
   fs.rmdirSync = function (path, options) {
-    bridge('fsRm', 'rmdir', path, [path, Boolean(options && options.recursive), false]);
+    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],
@@ -648,10 +748,11 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
       });
     };
   })(promiseNames[index]);
-  fs.promises.access = function (path) {
+  fs.promises.access = function (path, mode) {
     return new Promise(function (resolve, reject) {
-      if (fs.existsSync(path)) resolve();
-      else reject(failure(new Error("ENOENT: no such file or directory, access '" + path + "'"), 'access', path));
+      Promise.resolve().then(function () {
+        fs.accessSync(path, mode);
+      }).then(resolve, reject);
     });
   };
 
@@ -849,15 +950,14 @@ async function createSandbox(layout, options) {
     network: layout.network ? { dangerouslyAllowFullInternetAccess: true, denyPrivateRanges: true } : void 0,
     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 };
@@ -885,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) {
@@ -961,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;
@@ -1001,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.
@@ -1064,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")
     }),
@@ -1166,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.`
@@ -324,6 +326,18 @@ var WorkspaceScheme = class extends FileScheme {
 // src/sandbox.ts
 import path4 from "node:path";
 
+// 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 () {
@@ -362,6 +376,27 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
     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);
@@ -378,6 +413,22 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
     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];
@@ -398,29 +449,31 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
     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 = {
-      dev: 0,
-      ino: 0,
-      mode: Number(value.mode),
-      nlink: value.isDirectory ? 2 : 1,
-      uid: 1000,
-      gid: 1000,
-      rdev: 0,
-      size: size,
-      blksize: 4096,
-      blocks: Math.ceil(size / 512),
-      atime: mtime,
-      mtime: mtime,
-      ctime: mtime,
-      birthtime: mtime,
-      atimeMs: mtime.getTime(),
-      mtimeMs: mtime.getTime(),
-      ctimeMs: mtime.getTime(),
-      birthtimeMs: mtime.getTime()
-    };
+    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; };
@@ -432,7 +485,10 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   function dirent(name, parentPath, value) {
-    var result = { name: String(name), parentPath: String(parentPath), path: String(parentPath) };
+    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; };
@@ -448,7 +504,8 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   function readStats(path, follow) {
-    return bridge('fsStat', follow ? 'stat' : 'lstat', path, [path, !follow]);
+    var target = filePath(path);
+    return bridge('fsStat', follow ? 'stat' : 'lstat', target, [target, !follow]);
   }
 
   function collect(path, relative, options, output) {
@@ -464,10 +521,11 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   function readdir(path, options) {
+    var target = filePath(path);
     if (typeof options === 'string') options = { encoding: options };
     options = options || {};
     var output = [];
-    collect(path, '', { recursive: Boolean(options.recursive), withFileTypes: Boolean(options.withFileTypes) }, 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;
     });
@@ -475,7 +533,7 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   function firstCreated(path) {
-    var text = String(path);
+    var text = String(filePath(path));
     var absolute = text.charAt(0) === '/';
     var parts = text.split('/');
     var current = '';
@@ -494,24 +552,28 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   }
 
   fs.readFileBuffer = function (path) {
+    var target = filePath(path);
     try {
-      return raw.readFileBuffer(path);
+      return Buffer.from(raw.readFileBuffer(target));
     } catch (error) {
-      throw failure(error, 'open', path);
+      throw failure(error, 'open', target);
     }
   };
   fs.readFileSync = function (path, options) {
+    var target = filePath(path);
     try {
-      return raw.readFileSync(path, options);
+      return raw.readFileSync(target, options);
     } catch (error) {
-      throw failure(error, 'open', path);
+      throw failure(error, 'open', target);
     }
   };
   fs.writeFileSync = function (path, data) {
-    bridge('fsWrite', 'open', path, [path, bytes(data)]);
+    var target = filePath(path);
+    bridge('fsWrite', 'open', target, [target, bytes(data)]);
   };
   fs.appendFileSync = function (path, data) {
-    bridge('fsAppend', 'open', path, [path, bytes(data)]);
+    var target = filePath(path);
+    bridge('fsAppend', 'open', target, [target, bytes(data)]);
   };
   fs.statSync = function (path) {
     return stats(readStats(path, true));
@@ -521,45 +583,83 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
   };
   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(path) : undefined;
-    bridge('fsMkdir', 'mkdir', path, [path, recursive]);
+    var created = recursive ? firstCreated(target) : undefined;
+    bridge('fsMkdir', 'mkdir', target, [target, recursive]);
     return created;
   };
   fs.rmSync = function (path, options) {
-    bridge('fsRm', 'rm', path, [path, Boolean(options && options.recursive), Boolean(options && options.force)]);
+    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', path, [path]);
+      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) {
-    bridge('fsSymlink', 'symlink', path, [target, path]);
+    var link = filePath(path);
+    bridge('fsSymlink', 'symlink', link, [filePath(target), link]);
   };
   fs.readlinkSync = function (path) {
-    return bridge('fsReadlink', 'readlink', path, [path]);
+    var target = filePath(path);
+    return bridge('fsReadlink', 'readlink', target, [target]);
   };
   fs.chmodSync = function (path, mode) {
-    bridge('fsChmod', 'chmod', path, [path, Number(mode)]);
+    var target = filePath(path);
+    bridge('fsChmod', 'chmod', target, [target, Number(mode)]);
   };
   fs.realpathSync = function (path) {
-    return bridge('fsRealpath', 'realpath', path, [path]);
+    var target = filePath(path);
+    return bridge('fsRealpath', 'realpath', target, [target]);
   };
   fs.renameSync = function (from, to) {
-    bridge('fsRename', 'rename', from, [from, to], to);
+    var source = filePath(from);
+    var destination = filePath(to);
+    bridge('fsRename', 'rename', source, [source, destination], destination);
   };
-  fs.copyFileSync = function (from, to) {
-    bridge('fsCopy', 'copyfile', from, [from, to], to);
+  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) {
-    bridge('fsRm', 'unlink', path, [path, false, false]);
+    var target = filePath(path);
+    bridge('fsRm', 'unlink', target, [target, false, false]);
   };
   fs.rmdirSync = function (path, options) {
-    bridge('fsRm', 'rmdir', path, [path, Boolean(options && options.recursive), false]);
+    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],
@@ -616,10 +716,11 @@ var JAVASCRIPT_FS_BOOTSTRAP = String.raw`
       });
     };
   })(promiseNames[index]);
-  fs.promises.access = function (path) {
+  fs.promises.access = function (path, mode) {
     return new Promise(function (resolve, reject) {
-      if (fs.existsSync(path)) resolve();
-      else reject(failure(new Error("ENOENT: no such file or directory, access '" + path + "'"), 'access', path));
+      Promise.resolve().then(function () {
+        fs.accessSync(path, mode);
+      }).then(resolve, reject);
     });
   };
 
@@ -817,15 +918,14 @@ async function createSandbox(layout, options) {
     network: layout.network ? { dangerouslyAllowFullInternetAccess: true, denyPrivateRanges: true } : void 0,
     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 };
@@ -853,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) {
@@ -929,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;
@@ -969,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.
@@ -1032,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")
     }),
@@ -1134,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/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.4",
+  "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.4 <0.1.0"
+    "koishi-plugin-ishiki": ">=0.0.5 <0.1.0"
   },
   "peerDependencies": {
     "koishi": "^4.18.11",
-    "koishi-plugin-ishiki": ">=0.0.4 <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.