@tpmjs/tools-sprites-exec 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import * as ai from 'ai';
+
+/**
+ * Sprites Exec Tool for TPMJS
+ * Executes a command inside a sprite and returns the output.
+ * Supports stdin input for interactive commands.
+ *
+ * @requires SPRITES_TOKEN environment variable
+ */
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    duration: number;
+}
+type SpritesExecInput = {
+    name: string;
+    cmd: string;
+    stdin?: string;
+    timeoutMs?: number;
+};
+declare const spritesExecTool: ai.Tool<SpritesExecInput, ExecResult>;
+
+export { type ExecResult, spritesExecTool as default, spritesExecTool };

package/dist/index.js

@@ -0,0 +1,108 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var SPRITES_API_BASE = "https://api.sprites.dev/v1";
+function getSpritesToken() {
+  const token = process.env.SPRITES_TOKEN;
+  if (!token) {
+    throw new Error(
+      "SPRITES_TOKEN environment variable is required. Get your token from https://sprites.dev"
+    );
+  }
+  return token;
+}
+var spritesExecTool = tool({
+  description: "Execute a command inside a sprite and return the output. Supports stdin input for interactive commands. Returns exit code, stdout, stderr, and execution duration.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: "Name of the sprite to execute command in"
+      },
+      cmd: {
+        type: "string",
+        description: "Command to execute (e.g., 'ls -la', 'python script.py')"
+      },
+      stdin: {
+        type: "string",
+        description: "Optional stdin input to pass to the command"
+      },
+      timeoutMs: {
+        type: "number",
+        description: "Execution timeout in milliseconds (default: 60000)"
+      }
+    },
+    required: ["name", "cmd"],
+    additionalProperties: false
+  }),
+  async execute({ name, cmd, stdin, timeoutMs }) {
+    if (!name || typeof name !== "string") {
+      throw new Error("Sprite name is required and must be a string");
+    }
+    if (!cmd || typeof cmd !== "string") {
+      throw new Error("Command is required and must be a string");
+    }
+    const token = getSpritesToken();
+    const timeout = timeoutMs || 6e4;
+    const startTime = Date.now();
+    let response;
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+      const body = { cmd };
+      if (stdin) {
+        body.stdin = stdin;
+      }
+      response = await fetch(`${SPRITES_API_BASE}/sprites/${encodeURIComponent(name)}/exec`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          "User-Agent": "TPMJS/1.0"
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new Error(
+            `Command execution in sprite "${name}" timed out after ${timeout}ms`
+          );
+        }
+        throw new Error(`Failed to execute command in sprite "${name}": ${error.message}`);
+      }
+      throw new Error(`Failed to execute command in sprite "${name}": Unknown network error`);
+    }
+    const duration = Date.now() - startTime;
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new Error(`Sprite "${name}" not found`);
+      }
+      if (response.status === 401) {
+        throw new Error("Invalid SPRITES_TOKEN. Check your API token at https://sprites.dev");
+      }
+      const errorText = await response.text().catch(() => "Unknown error");
+      throw new Error(
+        `Failed to execute command in sprite "${name}": HTTP ${response.status} - ${errorText}`
+      );
+    }
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new Error("Failed to parse response from Sprites API");
+    }
+    return {
+      exitCode: data.exitCode ?? data.exit_code ?? 0,
+      stdout: data.stdout || "",
+      stderr: data.stderr || "",
+      duration: data.duration || duration
+    };
+  }
+});
+var index_default = spritesExecTool;
+
+export { index_default as default, spritesExecTool };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tpmjs/tools-sprites-exec",
+  "version": "0.1.0",
+  "description": "Execute a command inside a sprite and return the output with exit code",
+  "type": "module",
+  "keywords": ["tpmjs", "sprites", "sandbox", "code-execution", "ai"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "devDependencies": {
+    "@tpmjs/tsconfig": "workspace:*",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/tpmjs.git",
+    "directory": "packages/tools/official/sprites-exec"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "sandbox",
+    "frameworks": ["vercel-ai"],
+    "tools": [{
+      "name": "spritesExecTool",
+      "description": "Execute a command inside a sprite and return the output with exit code",
+      "parameters": [
+        { "name": "name", "type": "string", "description": "Name of the sprite to execute command in", "required": true },
+        { "name": "cmd", "type": "string", "description": "Command to execute", "required": true },
+        { "name": "stdin", "type": "string", "description": "Optional stdin input", "required": false },
+        { "name": "timeoutMs", "type": "number", "description": "Execution timeout in milliseconds", "required": false }
+      ],
+      "returns": {
+        "type": "ExecResult",
+        "description": "Command output with exitCode, stdout, stderr, and duration"
+      }
+    }]
+  },
+  "dependencies": { "ai": "6.0.23" }
+}