@tpmjs/official-sandbox-shell 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import * as ai from 'ai';
+
+/**
+ * Sandbox Shell Tools for TPMJS Agent Sandbox
+ *
+ * Execute shell commands, read/write files, and list directories
+ * within the stateful sandbox workspace. All paths are resolved
+ * relative to `_sandboxWorkDir` (injected by the sandbox server).
+ *
+ * Runs inside Deno — uses Deno.Command, Deno.readTextFile, etc.
+ */
+interface ShellExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+    truncated: boolean;
+}
+interface ReadFileResult {
+    content: string;
+    path: string;
+    size: number;
+    truncated: boolean;
+}
+interface WriteFileResult {
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+}
+interface FileEntry {
+    name: string;
+    type: 'file' | 'directory' | 'symlink';
+    size: number | null;
+}
+interface ListFilesResult {
+    path: string;
+    entries: FileEntry[];
+    truncated: boolean;
+}
+type ShellExecInput = {
+    command: string;
+    timeout?: number;
+    _sandboxWorkDir?: string;
+};
+declare const shellExec: ai.Tool<ShellExecInput, ShellExecResult>;
+type ReadFileInput = {
+    path: string;
+    _sandboxWorkDir?: string;
+};
+declare const readFile: ai.Tool<ReadFileInput, ReadFileResult>;
+type WriteFileInput = {
+    path: string;
+    content: string;
+    createDirs?: boolean;
+    _sandboxWorkDir?: string;
+};
+declare const writeFile: ai.Tool<WriteFileInput, WriteFileResult>;
+type ListFilesInput = {
+    path?: string;
+    recursive?: boolean;
+    maxDepth?: number;
+    _sandboxWorkDir?: string;
+};
+declare const listFiles: ai.Tool<ListFilesInput, ListFilesResult>;
+declare const _default: {
+    shellExec: ai.Tool<ShellExecInput, ShellExecResult>;
+    readFile: ai.Tool<ReadFileInput, ReadFileResult>;
+    writeFile: ai.Tool<WriteFileInput, WriteFileResult>;
+    listFiles: ai.Tool<ListFilesInput, ListFilesResult>;
+};
+
+export { type FileEntry, type ListFilesResult, type ReadFileResult, type ShellExecResult, type WriteFileResult, _default as default, listFiles, readFile, shellExec, writeFile };

package/dist/index.js

@@ -0,0 +1,329 @@
+// src/index.ts
+import { jsonSchema, tool } from "ai";
+var MAX_STDOUT = 100 * 1024;
+var MAX_READ_SIZE = 500 * 1024;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var MAX_TIMEOUT_MS = 3e5;
+var MAX_LIST_ENTRIES = 1e3;
+var DEFAULT_MAX_DEPTH = 3;
+function resolveSandboxPath(workDir, relativePath) {
+  const cleaned = relativePath.replace(/^\/+/, "");
+  const resolved = `${workDir}/${cleaned}`.replace(/\/+/g, "/");
+  const parts = resolved.split("/");
+  const normalized = [];
+  for (const part of parts) {
+    if (part === "..") {
+      normalized.pop();
+    } else if (part !== "." && part !== "") {
+      normalized.push(part);
+    }
+  }
+  const final = "/" + normalized.join("/");
+  const normalizedWorkDir = "/" + workDir.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (!final.startsWith(normalizedWorkDir)) {
+    throw new Error(`Path escapes sandbox workspace: ${relativePath}`);
+  }
+  return final;
+}
+function truncate(text, maxBytes) {
+  const encoder = new TextEncoder();
+  const bytes = encoder.encode(text);
+  if (bytes.length <= maxBytes) {
+    return { text, truncated: false };
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  return {
+    text: decoder.decode(bytes.slice(0, maxBytes)) + "\n... [truncated]",
+    truncated: true
+  };
+}
+async function collectStream(stream, maxBytes = MAX_STDOUT * 2) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let totalLength = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      totalLength += value.length;
+      if (totalLength > maxBytes) {
+        reader.cancel().catch(() => {
+        });
+        break;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const cappedLength = Math.min(totalLength, maxBytes);
+  const result = new Uint8Array(cappedLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    const copyLen = Math.min(chunk.length, cappedLength - offset);
+    if (copyLen <= 0) break;
+    result.set(chunk.subarray(0, copyLen), offset);
+    offset += copyLen;
+  }
+  return result.subarray(0, offset);
+}
+var shellExec = tool({
+  description: "Execute a shell command in the sandbox workspace. Supports git, npm, and any CLI tools available in the container.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      command: {
+        type: "string",
+        description: "Shell command to execute (passed to sh -c)"
+      },
+      timeout: {
+        type: "number",
+        description: "Timeout in milliseconds (default: 30000, max: 300000)"
+      },
+      _sandboxWorkDir: {
+        type: "string",
+        description: "Injected by sandbox server \u2014 workspace directory"
+      }
+    },
+    required: ["command"],
+    additionalProperties: false
+  }),
+  async execute({ command, timeout, _sandboxWorkDir }) {
+    if (!_sandboxWorkDir) {
+      throw new Error("shellExec requires a sandbox session (_sandboxWorkDir not set)");
+    }
+    const timeoutMs = Math.min(Math.max(timeout ?? DEFAULT_TIMEOUT_MS, 1e3), MAX_TIMEOUT_MS);
+    const startTime = Date.now();
+    const cmd = new Deno.Command("sh", {
+      args: ["-c", command],
+      cwd: _sandboxWorkDir,
+      stdout: "piped",
+      stderr: "piped"
+    });
+    const child = cmd.spawn();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill("SIGTERM");
+        setTimeout(() => {
+          try {
+            child.kill("SIGKILL");
+          } catch {
+          }
+        }, 2e3);
+      } catch {
+      }
+    }, timeoutMs);
+    try {
+      const [stdoutBytes, stderrBytes, status] = await Promise.all([
+        collectStream(child.stdout),
+        collectStream(child.stderr),
+        child.status
+      ]);
+      clearTimeout(timer);
+      const durationMs = Date.now() - startTime;
+      const decoder = new TextDecoder("utf-8", { fatal: false });
+      const stdoutRaw = decoder.decode(stdoutBytes);
+      const stderrRaw = decoder.decode(stderrBytes);
+      const stdout = truncate(stdoutRaw, MAX_STDOUT);
+      const stderr = truncate(stderrRaw, MAX_STDOUT);
+      const result = {
+        stdout: stdout.text,
+        stderr: timedOut ? `[TIMEOUT after ${timeoutMs}ms] ${stderr.text}` : stderr.text,
+        exitCode: timedOut ? 137 : status.code,
+        durationMs,
+        truncated: stdout.truncated || stderr.truncated
+      };
+      return result;
+    } catch (error) {
+      clearTimeout(timer);
+      throw new Error(
+        `Shell execution failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+});
+var readFile = tool({
+  description: "Read a file from the sandbox workspace.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "File path relative to workspace root"
+      },
+      _sandboxWorkDir: {
+        type: "string",
+        description: "Injected by sandbox server \u2014 workspace directory"
+      }
+    },
+    required: ["path"],
+    additionalProperties: false
+  }),
+  async execute({ path: filePath, _sandboxWorkDir }) {
+    if (!_sandboxWorkDir) {
+      throw new Error("readFile requires a sandbox session (_sandboxWorkDir not set)");
+    }
+    const resolved = resolveSandboxPath(_sandboxWorkDir, filePath);
+    try {
+      const realPath = await Deno.realPath(resolved);
+      const normalizedWorkDir = "/" + _sandboxWorkDir.replace(/^\/+/, "").replace(/\/+$/, "");
+      if (!realPath.startsWith(normalizedWorkDir)) {
+        throw new Error(`Path escapes sandbox workspace via symlink: ${filePath}`);
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("escapes sandbox")) {
+        throw error;
+      }
+    }
+    const content = await Deno.readTextFile(resolved);
+    const { text, truncated } = truncate(content, MAX_READ_SIZE);
+    const stat = await Deno.stat(resolved);
+    const result = {
+      content: text,
+      path: filePath,
+      size: stat.size,
+      truncated
+    };
+    return result;
+  }
+});
+var writeFile = tool({
+  description: "Write or create a file in the sandbox workspace.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "File path relative to workspace root"
+      },
+      content: {
+        type: "string",
+        description: "Content to write to the file"
+      },
+      createDirs: {
+        type: "boolean",
+        description: "Create parent directories if they do not exist (default: true)"
+      },
+      _sandboxWorkDir: {
+        type: "string",
+        description: "Injected by sandbox server \u2014 workspace directory"
+      }
+    },
+    required: ["path", "content"],
+    additionalProperties: false
+  }),
+  async execute({ path: filePath, content, createDirs = true, _sandboxWorkDir }) {
+    if (!_sandboxWorkDir) {
+      throw new Error("writeFile requires a sandbox session (_sandboxWorkDir not set)");
+    }
+    const resolved = resolveSandboxPath(_sandboxWorkDir, filePath);
+    if (createDirs) {
+      const parentDir = resolved.substring(0, resolved.lastIndexOf("/"));
+      if (parentDir) {
+        await Deno.mkdir(parentDir, { recursive: true });
+      }
+    }
+    await Deno.writeTextFile(resolved, content);
+    const encoder = new TextEncoder();
+    const bytesWritten = encoder.encode(content).length;
+    const result = {
+      success: true,
+      path: filePath,
+      bytesWritten
+    };
+    return result;
+  }
+});
+var listFiles = tool({
+  description: "List files and directories in the sandbox workspace.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Directory path relative to workspace root (default: root)"
+      },
+      recursive: {
+        type: "boolean",
+        description: "List recursively (default: false)"
+      },
+      maxDepth: {
+        type: "number",
+        description: "Maximum depth for recursive listing (default: 3)"
+      },
+      _sandboxWorkDir: {
+        type: "string",
+        description: "Injected by sandbox server \u2014 workspace directory"
+      }
+    },
+    additionalProperties: false
+  }),
+  async execute({ path: dirPath = ".", recursive = false, maxDepth, _sandboxWorkDir }) {
+    if (!_sandboxWorkDir) {
+      throw new Error("listFiles requires a sandbox session (_sandboxWorkDir not set)");
+    }
+    const effectiveMaxDepth = maxDepth ?? DEFAULT_MAX_DEPTH;
+    const resolved = resolveSandboxPath(_sandboxWorkDir, dirPath);
+    const entries = [];
+    let truncated = false;
+    const normalizedWorkDir = "/" + _sandboxWorkDir.replace(/^\/+/, "").replace(/\/+$/, "");
+    async function walk(dir, depth, prefix) {
+      if (entries.length >= MAX_LIST_ENTRIES) {
+        truncated = true;
+        return;
+      }
+      for await (const entry of Deno.readDir(dir)) {
+        if (entries.length >= MAX_LIST_ENTRIES) {
+          truncated = true;
+          return;
+        }
+        const entryPath = `${dir}/${entry.name}`;
+        const displayName = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isSymlink) {
+          try {
+            const realPath = await Deno.realPath(entryPath);
+            if (!realPath.startsWith(normalizedWorkDir)) {
+              continue;
+            }
+          } catch {
+            continue;
+          }
+        }
+        let size = null;
+        if (entry.isFile) {
+          try {
+            const info = await Deno.stat(entryPath);
+            size = info.size;
+          } catch {
+          }
+        }
+        entries.push({
+          name: displayName,
+          type: entry.isDirectory ? "directory" : entry.isSymlink ? "symlink" : "file",
+          size
+        });
+        if (recursive && entry.isDirectory && depth < effectiveMaxDepth) {
+          await walk(entryPath, depth + 1, displayName);
+        }
+      }
+    }
+    await walk(resolved, 0, "");
+    const result = {
+      path: dirPath,
+      entries,
+      truncated
+    };
+    return result;
+  }
+});
+var index_default = { shellExec, readFile, writeFile, listFiles };
+export {
+  index_default as default,
+  listFiles,
+  readFile,
+  shellExec,
+  writeFile
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Sandbox Shell Tools for TPMJS Agent Sandbox\n *\n * Execute shell commands, read/write files, and list directories\n * within the stateful sandbox workspace. All paths are resolved\n * relative to `_sandboxWorkDir` (injected by the sandbox server).\n *\n * Runs inside Deno — uses Deno.Command, Deno.readTextFile, etc.\n */\n\nimport { jsonSchema, tool } from 'ai';\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\nconst MAX_STDOUT = 100 * 1024; // 100 KB\nconst MAX_READ_SIZE = 500 * 1024; // 500 KB\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst MAX_TIMEOUT_MS = 300_000;\nconst MAX_LIST_ENTRIES = 1_000;\nconst DEFAULT_MAX_DEPTH = 3;\n\n// ---------------------------------------------------------------------------\n// Result types\n// ---------------------------------------------------------------------------\n\nexport interface ShellExecResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  durationMs: number;\n  truncated: boolean;\n}\n\nexport interface ReadFileResult {\n  content: string;\n  path: string;\n  size: number;\n  truncated: boolean;\n}\n\nexport interface WriteFileResult {\n  success: boolean;\n  path: string;\n  bytesWritten: number;\n}\n\nexport interface FileEntry {\n  name: string;\n  type: 'file' | 'directory' | 'symlink';\n  size: number | null;\n}\n\nexport interface ListFilesResult {\n  path: string;\n  entries: FileEntry[];\n  truncated: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction resolveSandboxPath(workDir: string, relativePath: string): string {\n  // Normalize: remove leading slash (paths are relative to workDir)\n  const cleaned = relativePath.replace(/^\\/+/, '');\n\n  // Simple join — Deno runs on Linux so forward slashes only\n  const resolved = `${workDir}/${cleaned}`.replace(/\\/+/g, '/');\n\n  // Security: ensure the resolved path stays inside workDir\n  // Normalize away any .. segments by splitting and resolving\n  const parts = resolved.split('/');\n  const normalized: string[] = [];\n  for (const part of parts) {\n    if (part === '..') {\n      normalized.pop();\n    } else if (part !== '.' && part !== '') {\n      normalized.push(part);\n    }\n  }\n  const final = '/' + normalized.join('/');\n\n  const normalizedWorkDir = '/' + workDir.replace(/^\\/+/, '').replace(/\\/+$/, '');\n  if (!final.startsWith(normalizedWorkDir)) {\n    throw new Error(`Path escapes sandbox workspace: ${relativePath}`);\n  }\n\n  return final;\n}\n\nfunction truncate(text: string, maxBytes: number): { text: string; truncated: boolean } {\n  const encoder = new TextEncoder();\n  const bytes = encoder.encode(text);\n  if (bytes.length <= maxBytes) {\n    return { text, truncated: false };\n  }\n  // Truncate at byte boundary, decode back (may lose partial char)\n  const decoder = new TextDecoder('utf-8', { fatal: false });\n  return {\n    text: decoder.decode(bytes.slice(0, maxBytes)) + '\\n... [truncated]',\n    truncated: true,\n  };\n}\n\nasync function collectStream(\n  stream: ReadableStream<Uint8Array>,\n  maxBytes: number = MAX_STDOUT * 2,\n): Promise<Uint8Array> {\n  const reader = stream.getReader();\n  const chunks: Uint8Array[] = [];\n  let totalLength = 0;\n  try {\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n      chunks.push(value);\n      totalLength += value.length;\n      // Prevent OOM: stop reading if we exceed the limit\n      if (totalLength > maxBytes) {\n        reader.cancel().catch(() => {});\n        break;\n      }\n    }\n  } finally {\n    reader.releaseLock();\n  }\n  const cappedLength = Math.min(totalLength, maxBytes);\n  const result = new Uint8Array(cappedLength);\n  let offset = 0;\n  for (const chunk of chunks) {\n    const copyLen = Math.min(chunk.length, cappedLength - offset);\n    if (copyLen <= 0) break;\n    result.set(chunk.subarray(0, copyLen), offset);\n    offset += copyLen;\n  }\n  return result.subarray(0, offset);\n}\n\n// ---------------------------------------------------------------------------\n// shellExec\n// ---------------------------------------------------------------------------\n\ntype ShellExecInput = {\n  command: string;\n  timeout?: number;\n  _sandboxWorkDir?: string;\n};\n\nexport const shellExec = tool({\n  description:\n    'Execute a shell command in the sandbox workspace. Supports git, npm, and any CLI tools available in the container.',\n  inputSchema: jsonSchema<ShellExecInput>({\n    type: 'object',\n    properties: {\n      command: {\n        type: 'string',\n        description: 'Shell command to execute (passed to sh -c)',\n      },\n      timeout: {\n        type: 'number',\n        description: 'Timeout in milliseconds (default: 30000, max: 300000)',\n      },\n      _sandboxWorkDir: {\n        type: 'string',\n        description: 'Injected by sandbox server — workspace directory',\n      },\n    },\n    required: ['command'],\n    additionalProperties: false,\n  }),\n  async execute({ command, timeout, _sandboxWorkDir }) {\n    if (!_sandboxWorkDir) {\n      throw new Error('shellExec requires a sandbox session (_sandboxWorkDir not set)');\n    }\n\n    const timeoutMs = Math.min(Math.max(timeout ?? DEFAULT_TIMEOUT_MS, 1000), MAX_TIMEOUT_MS);\n    const startTime = Date.now();\n\n    const cmd = new Deno.Command('sh', {\n      args: ['-c', command],\n      cwd: _sandboxWorkDir,\n      stdout: 'piped',\n      stderr: 'piped',\n    });\n\n    const child = cmd.spawn();\n\n    // Timeout handling — kill the process tree if it exceeds the limit\n    let timedOut = false;\n    const timer = setTimeout(() => {\n      timedOut = true;\n      try {\n        // Try SIGTERM first for graceful shutdown\n        child.kill('SIGTERM');\n        // Force kill after 2 seconds if still running\n        setTimeout(() => {\n          try {\n            child.kill('SIGKILL');\n          } catch {\n            // Already exited\n          }\n        }, 2000);\n      } catch {\n        // Process may have already exited\n      }\n    }, timeoutMs);\n\n    try {\n      // Collect stdout and stderr concurrently\n      const [stdoutBytes, stderrBytes, status] = await Promise.all([\n        collectStream(child.stdout),\n        collectStream(child.stderr),\n        child.status,\n      ]);\n\n      clearTimeout(timer);\n      const durationMs = Date.now() - startTime;\n      const decoder = new TextDecoder('utf-8', { fatal: false });\n\n      const stdoutRaw = decoder.decode(stdoutBytes);\n      const stderrRaw = decoder.decode(stderrBytes);\n\n      const stdout = truncate(stdoutRaw, MAX_STDOUT);\n      const stderr = truncate(stderrRaw, MAX_STDOUT);\n\n      const result: ShellExecResult = {\n        stdout: stdout.text,\n        stderr: timedOut ? `[TIMEOUT after ${timeoutMs}ms] ${stderr.text}` : stderr.text,\n        exitCode: timedOut ? 137 : status.code,\n        durationMs,\n        truncated: stdout.truncated || stderr.truncated,\n      };\n\n      return result;\n    } catch (error) {\n      clearTimeout(timer);\n      throw new Error(\n        `Shell execution failed: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  },\n});\n\n// ---------------------------------------------------------------------------\n// readFile\n// ---------------------------------------------------------------------------\n\ntype ReadFileInput = {\n  path: string;\n  _sandboxWorkDir?: string;\n};\n\nexport const readFile = tool({\n  description: 'Read a file from the sandbox workspace.',\n  inputSchema: jsonSchema<ReadFileInput>({\n    type: 'object',\n    properties: {\n      path: {\n        type: 'string',\n        description: 'File path relative to workspace root',\n      },\n      _sandboxWorkDir: {\n        type: 'string',\n        description: 'Injected by sandbox server — workspace directory',\n      },\n    },\n    required: ['path'],\n    additionalProperties: false,\n  }),\n  async execute({ path: filePath, _sandboxWorkDir }) {\n    if (!_sandboxWorkDir) {\n      throw new Error('readFile requires a sandbox session (_sandboxWorkDir not set)');\n    }\n\n    const resolved = resolveSandboxPath(_sandboxWorkDir, filePath);\n\n    // Symlink escape check: verify the real (canonical) path is still in workspace\n    try {\n      const realPath = await Deno.realPath(resolved);\n      const normalizedWorkDir = '/' + _sandboxWorkDir.replace(/^\\/+/, '').replace(/\\/+$/, '');\n      if (!realPath.startsWith(normalizedWorkDir)) {\n        throw new Error(`Path escapes sandbox workspace via symlink: ${filePath}`);\n      }\n    } catch (error) {\n      // Re-throw our own escape error\n      if (error instanceof Error && error.message.includes('escapes sandbox')) {\n        throw error;\n      }\n      // NotFound is fine — stat will fail with a better error below\n    }\n\n    const content = await Deno.readTextFile(resolved);\n\n    const { text, truncated } = truncate(content, MAX_READ_SIZE);\n\n    const stat = await Deno.stat(resolved);\n\n    const result: ReadFileResult = {\n      content: text,\n      path: filePath,\n      size: stat.size,\n      truncated,\n    };\n\n    return result;\n  },\n});\n\n// ---------------------------------------------------------------------------\n// writeFile\n// ---------------------------------------------------------------------------\n\ntype WriteFileInput = {\n  path: string;\n  content: string;\n  createDirs?: boolean;\n  _sandboxWorkDir?: string;\n};\n\nexport const writeFile = tool({\n  description: 'Write or create a file in the sandbox workspace.',\n  inputSchema: jsonSchema<WriteFileInput>({\n    type: 'object',\n    properties: {\n      path: {\n        type: 'string',\n        description: 'File path relative to workspace root',\n      },\n      content: {\n        type: 'string',\n        description: 'Content to write to the file',\n      },\n      createDirs: {\n        type: 'boolean',\n        description: 'Create parent directories if they do not exist (default: true)',\n      },\n      _sandboxWorkDir: {\n        type: 'string',\n        description: 'Injected by sandbox server — workspace directory',\n      },\n    },\n    required: ['path', 'content'],\n    additionalProperties: false,\n  }),\n  async execute({ path: filePath, content, createDirs = true, _sandboxWorkDir }) {\n    if (!_sandboxWorkDir) {\n      throw new Error('writeFile requires a sandbox session (_sandboxWorkDir not set)');\n    }\n\n    const resolved = resolveSandboxPath(_sandboxWorkDir, filePath);\n\n    // Create parent directories if requested\n    if (createDirs) {\n      const parentDir = resolved.substring(0, resolved.lastIndexOf('/'));\n      if (parentDir) {\n        await Deno.mkdir(parentDir, { recursive: true });\n      }\n    }\n\n    await Deno.writeTextFile(resolved, content);\n\n    const encoder = new TextEncoder();\n    const bytesWritten = encoder.encode(content).length;\n\n    const result: WriteFileResult = {\n      success: true,\n      path: filePath,\n      bytesWritten,\n    };\n\n    return result;\n  },\n});\n\n// ---------------------------------------------------------------------------\n// listFiles\n// ---------------------------------------------------------------------------\n\ntype ListFilesInput = {\n  path?: string;\n  recursive?: boolean;\n  maxDepth?: number;\n  _sandboxWorkDir?: string;\n};\n\nexport const listFiles = tool({\n  description: 'List files and directories in the sandbox workspace.',\n  inputSchema: jsonSchema<ListFilesInput>({\n    type: 'object',\n    properties: {\n      path: {\n        type: 'string',\n        description: 'Directory path relative to workspace root (default: root)',\n      },\n      recursive: {\n        type: 'boolean',\n        description: 'List recursively (default: false)',\n      },\n      maxDepth: {\n        type: 'number',\n        description: 'Maximum depth for recursive listing (default: 3)',\n      },\n      _sandboxWorkDir: {\n        type: 'string',\n        description: 'Injected by sandbox server — workspace directory',\n      },\n    },\n    additionalProperties: false,\n  }),\n  async execute({ path: dirPath = '.', recursive = false, maxDepth, _sandboxWorkDir }) {\n    if (!_sandboxWorkDir) {\n      throw new Error('listFiles requires a sandbox session (_sandboxWorkDir not set)');\n    }\n\n    const effectiveMaxDepth = maxDepth ?? DEFAULT_MAX_DEPTH;\n    const resolved = resolveSandboxPath(_sandboxWorkDir, dirPath);\n    const entries: FileEntry[] = [];\n    let truncated = false;\n\n    const normalizedWorkDir = '/' + _sandboxWorkDir.replace(/^\\/+/, '').replace(/\\/+$/, '');\n\n    async function walk(dir: string, depth: number, prefix: string): Promise<void> {\n      if (entries.length >= MAX_LIST_ENTRIES) {\n        truncated = true;\n        return;\n      }\n\n      for await (const entry of Deno.readDir(dir)) {\n        if (entries.length >= MAX_LIST_ENTRIES) {\n          truncated = true;\n          return;\n        }\n\n        const entryPath = `${dir}/${entry.name}`;\n        const displayName = prefix ? `${prefix}/${entry.name}` : entry.name;\n\n        // Skip symlinks that escape the workspace\n        if (entry.isSymlink) {\n          try {\n            const realPath = await Deno.realPath(entryPath);\n            if (!realPath.startsWith(normalizedWorkDir)) {\n              continue; // silently skip symlinks that point outside\n            }\n          } catch {\n            continue; // skip broken symlinks\n          }\n        }\n\n        let size: number | null = null;\n        if (entry.isFile) {\n          try {\n            const info = await Deno.stat(entryPath);\n            size = info.size;\n          } catch {\n            // Permission or race condition — skip size\n          }\n        }\n\n        entries.push({\n          name: displayName,\n          type: entry.isDirectory ? 'directory' : entry.isSymlink ? 'symlink' : 'file',\n          size,\n        });\n\n        if (recursive && entry.isDirectory && depth < effectiveMaxDepth) {\n          await walk(entryPath, depth + 1, displayName);\n        }\n      }\n    }\n\n    await walk(resolved, 0, '');\n\n    const result: ListFilesResult = {\n      path: dirPath,\n      entries,\n      truncated,\n    };\n\n    return result;\n  },\n});\n\n// ---------------------------------------------------------------------------\n// Default export\n// ---------------------------------------------------------------------------\n\nexport default { shellExec, readFile, writeFile, listFiles };\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@tpmjs/official-sandbox-shell",
+  "version": "0.1.0",
+  "description": "Shell execution, file I/O, and directory listing tools for the TPMJS Agent Sandbox",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "sandbox",
+    "shell",
+    "git",
+    "filesystem",
+    "ai",
+    "agent"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit --incremental --tsBuildInfoFile tsconfig.tsbuildinfo",
+    "clean": "rm -rf dist .turbo"
+  },
+  "devDependencies": {
+    "@tpmjs/tsconfig": "workspace:*",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "ai": "6.0.49"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tpmjs/tpmjs.git",
+    "directory": "packages/tools/official/sandbox-shell"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "sandbox",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "shellExec",
+        "description": "Execute a shell command in the sandbox workspace. Supports git, npm, and any CLI tools."
+      },
+      {
+        "name": "readFile",
+        "description": "Read a file from the sandbox workspace."
+      },
+      {
+        "name": "writeFile",
+        "description": "Write or create a file in the sandbox workspace."
+      },
+      {
+        "name": "listFiles",
+        "description": "List files and directories in the sandbox workspace."
+      }
+    ]
+  }
+}