> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# code execution

> Execute JavaScript code in a sandboxed environment with MCP tool access

**Server path:** `/code-execution` | **Type:** Embedded | **PCID required:** No

## Tools

| Tool                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`code-execution_execute`](#code-execution_execute) | Execute JavaScript code in a sandboxed VM with access to MCP tools and file helpers.<br />Available globals:<br />- callTool(serverPath, toolName, toolArgs) — Call a configured MCP tool via HTTP. DO NOT pass PCID — connection is auto-injected from selection context.<br />- codeExec.createArtifact(filename, content, fileType) — Create a file (uploads to platform, returns \{ success, id, url, filename, mimeType, size }). Supported types: csv, txt, json, html, xml, js, ts, md, py. This is a simplified file helper — for full artifact features, use the agent's write\_artifact tool.<br />- codeExec.readArtifact(identifier) — Read a file by ID, filename, or URL (returns \{ success, content, size, filename, mimeType }). This is a simplified reader — for advanced features (search, pagination, smartGrepQuery), use the agent's read\_artifact tool after code execution returns.<br />- console.log/error/warn(...args) — Captured to logs array returned in the response.<br />- setTimeout/setInterval/clearTimeout/clearInterval — Standard timer functions (cleaned up after execution).<br />EXAMPLES:<br />// Call MCP tools (DO NOT pass PCID - connection is auto-injected from selection context):<br />const emails = await callTool("gmail", "gmail\_search\_emails", \{<br />query: "is:unread"<br />});<br />// Create output files:<br />const csv = emails.map(e => `$&#123;e.from&#125;,$&#123;e.subject&#125;`).join('\n');<br />await codeExec.createArtifact('emails.csv', csv, 'csv');<br />// Read an artifact from the conversation:<br />const data = await codeExec.readArtifact('file\_abc123');<br />console.log(data.content);<br />// Return result to agent:<br />return \{ count: emails.length };<br />LARGE RESULTS: If the returned value serializes to >200 bytes, an artifact is created automatically and the response includes an artifactId with a truncated preview. The agent can use read\_artifact to access the full result.<br />IMPORTANT — NO UNBOUNDED LOOPS:<br />- NEVER write while(true), while(hasMore), or open-ended loops that call callTool() repeatedly. Each callTool() is an HTTP round-trip and loops will timeout.<br />- If a tool doesn't have a pagination parameter (e.g. "page"), do NOT attempt manual pagination — you will get the same page repeatedly.<br />- If you need more data than one API call returns, return what you have and tell the user the tool's page limit was reached.<br />- Bounded loops (e.g. for(let i=0; i\<items.length; i++)) over local data are fine.<br />- Be suspicious of round numbers (30, 50, 100) — they usually mean you hit a perPage limit, not the actual total.<br />Default timeout: 10 minutes (max 15 minutes). |

***

## code-execution\_execute

Execute JavaScript code in a sandboxed VM with access to MCP tools and file helpers.

Available globals:

* callTool(serverPath, toolName, toolArgs) — Call a configured MCP tool via HTTP. DO NOT pass PCID — connection is auto-injected from selection context.
* codeExec.createArtifact(filename, content, fileType) — Create a file (uploads to platform, returns \{ success, id, url, filename, mimeType, size }). Supported types: csv, txt, json, html, xml, js, ts, md, py. This is a simplified file helper — for full artifact features, use the agent's write\_artifact tool.
* codeExec.readArtifact(identifier) — Read a file by ID, filename, or URL (returns \{ success, content, size, filename, mimeType }). This is a simplified reader — for advanced features (search, pagination, smartGrepQuery), use the agent's read\_artifact tool after code execution returns.
* console.log/error/warn(...args) — Captured to logs array returned in the response.
* setTimeout/setInterval/clearTimeout/clearInterval — Standard timer functions (cleaned up after execution).

EXAMPLES:

// Call MCP tools (DO NOT pass PCID - connection is auto-injected from selection context):
const emails = await callTool("gmail", "gmail\_search\_emails", \{
query: "is:unread"
});

// Create output files:
const csv = emails.map(e => `$&#123;e.from&#125;,$&#123;e.subject&#125;`).join('\n');
await codeExec.createArtifact('emails.csv', csv, 'csv');

// Read an artifact from the conversation:
const data = await codeExec.readArtifact('file\_abc123');
console.log(data.content);

// Return result to agent:
return \{ count: emails.length };

LARGE RESULTS: If the returned value serializes to >200 bytes, an artifact is created automatically and the response includes an artifactId with a truncated preview. The agent can use read\_artifact to access the full result.

IMPORTANT — NO UNBOUNDED LOOPS:

* NEVER write while(true), while(hasMore), or open-ended loops that call callTool() repeatedly. Each callTool() is an HTTP round-trip and loops will timeout.
* If a tool doesn't have a pagination parameter (e.g. "page"), do NOT attempt manual pagination — you will get the same page repeatedly.
* If you need more data than one API call returns, return what you have and tell the user the tool's page limit was reached.
* Bounded loops (e.g. for(let i=0; i\<items.length; i++)) over local data are fine.
* Be suspicious of round numbers (30, 50, 100) — they usually mean you hit a perPage limit, not the actual total.

Default timeout: 10 minutes (max 15 minutes).

**Parameters:**

| Parameter              | Type   | Required | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`                 | string | Yes      | —        | JavaScript code to execute in the sandbox.<br />The code runs in an async context — use await for async operations.<br />Return a value to send it back to the agent.<br />Example:<br />const collections = await callTool("datastore-unstructured", "datastore-unstructured\_list\_collections", \{});<br />const csv = collections.collections.map(c => c.name).join('\n');<br />await codeExec.createArtifact('collections.csv', csv, 'csv');<br />return \{ count: collections.collections.length };<br /> |
| `timeout`              | number | No       | `600000` | Timeout in milliseconds (default: 600000 = 10 minutes, min: 1000 = 1 second, max: 900000 = 15 minutes)                                                                                                                                                                                                                                                                                                                                                                                                          |
| `connectionSelections` | any    | No       | —        | Optional mapping of service key to PCID for callTool() connection injection. Use this when the user has multiple connections for the same service and you need to select a specific one. Keys are service names (e.g., "gmail", "slack"), values are PCIDs obtained from capabilities\_discover. When omitted, connections are auto-selected (first connection per service). Code should NOT contain PCIDs — pass them here instead so code remains portable across users.                                      |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "JavaScript code to execute in the sandbox.\n\nThe code runs in an async context — use await for async operations.\nReturn a value to send it back to the agent.\n\nExample:\nconst collections = await callTool(\"datastore-unstructured\", \"datastore-unstructured_list_collections\", {});\nconst csv = collections.collections.map(c => c.name).join('\\n');\nawait codeExec.createArtifact('collections.csv', csv, 'csv');\nreturn { count: collections.collections.length };\n"
      },
      "timeout": {
        "type": "number",
        "default": 600000,
        "description": "Timeout in milliseconds (default: 600000 = 10 minutes, min: 1000 = 1 second, max: 900000 = 15 minutes)"
      },
      "connectionSelections": {
        "type": "effects",
        "description": "Optional mapping of service key to PCID for callTool() connection injection. Use this when the user has multiple connections for the same service and you need to select a specific one. Keys are service names (e.g., \"gmail\", \"slack\"), values are PCIDs obtained from capabilities_discover. When omitted, connections are auto-selected (first connection per service). Code should NOT contain PCIDs — pass them here instead so code remains portable across users."
      }
    },
    "required": [
      "code"
    ]
  }
  ```
</Expandable>