kandelo.dev

{
  "name": "kandelo_list_profiles",
  "kind": "answer",
  "impl": "imperative",
  "description": "Kandelo provides a browser-hosted computer for running code, working with files and using applications without executing commands on the host machine. Use it as a sandbox for development, experimentation, testing or other tasks suited to its available environments. Discover environments here: returns stable profile IDs, names, descriptions and availability. Use profileId with kandelo_launch_computer or kandelo_create_launch_link; inspect the current computer with kandelo_get_computer_status.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Optional case-insensitive search of profile names and descriptions.",
        "maxLength": 256
      }
    },
    "required": [],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_launch_computer",
  "kind": "act",
  "impl": "imperative",
  "description": "Start a browser-hosted computing environment from kandelo_list_profiles, replacing the current computer. Code and applications run inside the guest, sharing its terminals and preview with the user. Returns initiation and the destination URL. The computer boots in place, so the registered tools stay valid: poll kandelo_get_computer_status until it reports running or error. Never automatically retry without checking status.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "profileId": {
        "type": "string",
        "description": "Profile ID from kandelo_list_profiles.",
        "maxLength": 128
      },
      "requestId": {
        "type": "string",
        "description": "Optional retry key. Reuse with identical arguments in this document; a new document forgets keys.",
        "maxLength": 128
      }
    },
    "required": [
      "profileId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_get_computer_status",
  "kind": "answer",
  "impl": "imperative",
  "description": "Discover what you can do in the current Kandelo browser-hosted computer, where commands and file operations target the guest rather than the host machine. Returns generation, environment profile, lifecycle, boot error, available capabilities, active terminal and preview state. Check running and capabilities before using execution, file or preview tools. Discover other environments with kandelo_list_profiles. You and the user share the same computer.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_run_command",
  "kind": "act",
  "impl": "imperative",
  "description": "Run code and commands inside the current Kandelo guest by executing a non-interactive script through the login shell of the guest account the agent acts as. Use guest programs for tasks such as development, testing or data processing; available runtimes depend on the environment. Provides separate stdout/stderr, independent cwd/env and an owned process family. Returns a generation-qualified job ID, incremental output and observed root exit code. waitMs bounds this call; timeoutMs terminates the job and all descendants. Poll kandelo_read_job until terminationObserved.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "script": {
        "type": "string",
        "description": "Shell script to execute once.",
        "maxLength": 65536
      },
      "cwd": {
        "type": "string",
        "description": "Absolute guest path; no NUL, backslashes, or dot segments.",
        "maxLength": 1024
      },
      "env": {
        "type": "object",
        "additionalProperties": {
          "type": "string",
          "description": "Environment value.",
          "maxLength": 8192
        }
      },
      "waitMs": {
        "type": "integer",
        "description": "Wait for completion up to this many ms; default 1000.",
        "minimum": 0,
        "maximum": 10000
      },
      "timeoutMs": {
        "type": "integer",
        "description": "Owned job timeout in ms; default 30000.",
        "minimum": 1,
        "maximum": 300000
      },
      "requestId": {
        "type": "string",
        "description": "Optional retry key. Reuse with identical arguments in this document; a new document forgets keys.",
        "maxLength": 128
      }
    },
    "required": [
      "script"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_read_job",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read incremental stdout/stderr and lifecycle status of an owned command job. Exit code is null until observed. Continue with nextCursor; expired cursors produce OUTPUT_EXPIRED. Jobs do not survive a reboot or navigation.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "jobId": {
        "type": "string",
        "description": "Generation-qualified job ID returned by kandelo_run_command.",
        "maxLength": 160
      },
      "cursor": {
        "type": "string",
        "description": "Opaque nextCursor from the previous read. Omit to start at oldest retained output.",
        "maxLength": 200
      },
      "byteLimit": {
        "type": "integer",
        "description": "Maximum bytes returned; default 4096, maximum 65536.",
        "minimum": 1,
        "maximum": 65536
      }
    },
    "required": [
      "jobId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_cancel_job",
  "kind": "transact",
  "impl": "imperative",
  "description": "Cancel an owned command job and all its descendants only, including children that change process groups. May return cancelling while termination is pending; poll kandelo_read_job for terminationObserved. Unsupported backends return UNSUPPORTED_CAPABILITY.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "jobId": {
        "type": "string",
        "description": "Generation-qualified job ID returned by kandelo_run_command.",
        "maxLength": 160
      }
    },
    "required": [
      "jobId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_list_terminals",
  "kind": "answer",
  "impl": "imperative",
  "description": "List the interactive terminals shared with the visible dock, including generation-qualified IDs, labels, attachment readiness and active selection. Readiness does not mean a shell prompt or successful login.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_create_terminal",
  "kind": "act",
  "impl": "imperative",
  "description": "Create an interactive terminal with independent shell variables/cwd but the same guest filesystem, using the existing login policy. Activates and reveals it by default; activate=false leaves selection unchanged. Returns terminal ID and attachment readiness; this does not bypass login.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "activate": {
        "type": "boolean",
        "description": "Select and reveal the new terminal; default true."
      },
      "requestId": {
        "type": "string",
        "description": "Optional retry key. Reuse with identical arguments in this document; a new document forgets keys.",
        "maxLength": 128
      }
    },
    "required": [],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_switch_terminal",
  "kind": "act",
  "impl": "imperative",
  "description": "Select an existing interactive terminal and reveal it in the dock. Preserves its shell, working directory and running programs. Does not send input.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "terminalId": {
        "type": "string",
        "description": "Generation-qualified terminal ID returned by kandelo_list_terminals or kandelo_create_terminal.",
        "maxLength": 160
      }
    },
    "required": [
      "terminalId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_send_terminal_input",
  "kind": "transact",
  "impl": "imperative",
  "description": "Interact with a shell or running program inside the Kandelo guest through a terminal shared with the user. Send text OR one control key to the specified interactive PTY. Include a newline to submit a command. Returns delivery only, not command completion or exit status. Input may reach login or a running program. Read kandelo_read_terminal_output afterward.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "terminalId": {
        "type": "string",
        "description": "Generation-qualified terminal ID returned by kandelo_list_terminals or kandelo_create_terminal.",
        "maxLength": 160
      },
      "text": {
        "type": "string",
        "description": "Literal input; include \\n to press Enter after a command.",
        "maxLength": 65536
      },
      "key": {
        "type": "string",
        "enum": [
          "enter",
          "ctrl_c",
          "ctrl_d",
          "ctrl_z",
          "tab",
          "escape",
          "backspace",
          "up",
          "down",
          "left",
          "right"
        ],
        "description": "One control key, mutually exclusive with text."
      }
    },
    "required": [
      "terminalId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_read_terminal_output",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read bounded output from one interactive terminal, including ANSI sequences and merged stdout/stderr. No per-command exit status. Continue with nextCursor; OUTPUT_EXPIRED includes oldestCursor to recover after overflow.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "terminalId": {
        "type": "string",
        "description": "Generation-qualified terminal ID returned by kandelo_list_terminals or kandelo_create_terminal.",
        "maxLength": 160
      },
      "cursor": {
        "type": "string",
        "description": "Opaque nextCursor from the previous read. Omit to start at oldest retained output.",
        "maxLength": 200
      },
      "byteLimit": {
        "type": "integer",
        "description": "Maximum bytes returned; default 4096, maximum 65536.",
        "minimum": 1,
        "maximum": 65536
      }
    },
    "required": [
      "terminalId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_list_files",
  "kind": "answer",
  "impl": "imperative",
  "description": "List an absolute guest directory, with entry types and available metadata. offset/limit paginate a fresh listing, not a snapshot. Unsupported live filesystem backends return UNSUPPORTED_CAPABILITY.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Absolute guest path; no NUL, backslashes, or dot segments.",
        "maxLength": 1024
      },
      "offset": {
        "type": "integer",
        "description": "Entry offset; default 0.",
        "minimum": 0,
        "maximum": 2147483647
      },
      "limit": {
        "type": "integer",
        "description": "Entry count; default 100, maximum 500.",
        "minimum": 1,
        "maximum": 500
      }
    },
    "required": [
      "path"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_read_file",
  "kind": "answer",
  "impl": "imperative",
  "description": "Inspect code, configuration, data or generated results inside the Kandelo guest. Read a file as UTF-8 text or base64 bytes. offset and byteLimit are byte-based; use base64 for exact binary or split UTF-8 sequences. Returns bytes read, next offset and EOF. Does not read host files.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Absolute guest path; no NUL, backslashes, or dot segments.",
        "maxLength": 1024
      },
      "encoding": {
        "type": "string",
        "enum": [
          "utf8",
          "base64"
        ],
        "description": "utf8 (default) for text; base64 for exact binary bytes."
      },
      "offset": {
        "type": "integer",
        "description": "Byte offset; default 0.",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "byteLimit": {
        "type": "integer",
        "description": "Maximum bytes returned; default 4096, maximum 65536.",
        "minimum": 1,
        "maximum": 65536
      }
    },
    "required": [
      "path"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_write_file",
  "kind": "act",
  "impl": "imperative",
  "description": "Prepare code, configuration or other data for programs inside the Kandelo computer. Create or replace a guest file with UTF-8 or base64 bytes; writes affect the guest filesystem, not host files. Parent directory must exist. overwrite=true allows creation and replacement; false atomically creates a new file or returns FILE_EXISTS without changing the existing path. Maximum 65536 decoded bytes.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Absolute guest path; no NUL, backslashes, or dot segments.",
        "maxLength": 1024
      },
      "content": {
        "type": "string",
        "description": "UTF-8 text or standard base64 content.",
        "maxLength": 90000
      },
      "encoding": {
        "type": "string",
        "enum": [
          "utf8",
          "base64"
        ],
        "description": "utf8 (default) for text; base64 for exact binary bytes."
      },
      "overwrite": {
        "type": "boolean",
        "description": "Required explicit replacement permission."
      }
    },
    "required": [
      "path",
      "content",
      "overwrite"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_navigate_preview",
  "kind": "act",
  "impl": "imperative",
  "description": "View a web application or content served by the current Kandelo guest by navigating and revealing its web preview. Accepts a guest path such as /hello.html?x=1#title, never an external URL. Returns navigation request and observed bridge state, not proof the page loaded successfully.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Guest URL path starting with /. No external URL, traversal, or backslashes.",
        "maxLength": 4096
      }
    },
    "required": [
      "path"
    ],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_read_logs",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read bounded incremental system logs for this computer, with monotonic timestamps in milliseconds since boot. Continue with nextCursor. Optional level filters scanned entries; expired cursors return OUTPUT_EXPIRED.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "cursor": {
        "type": "string",
        "description": "Opaque nextCursor from the previous read. Omit to start at oldest retained output.",
        "maxLength": 200
      },
      "limit": {
        "type": "integer",
        "description": "Maximum entries; default 50, maximum 200.",
        "minimum": 1,
        "maximum": 200
      },
      "level": {
        "type": "string",
        "enum": [
          "info",
          "warn",
          "err",
          "ok",
          "debug"
        ],
        "description": "Optional exact log level."
      }
    },
    "required": [],
    "additionalProperties": false
  }
}

{
  "name": "kandelo_create_launch_link",
  "kind": "act",
  "impl": "imperative",
  "description": "Create a reproducible starting point for a task, experiment or demo as a launch URL. Reproduces boot configuration and an optional startup script for the current or specified profile. Does not open, publish or execute it. Does not preserve modified files, processes or terminal state.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "profileId": {
        "type": "string",
        "description": "Optional profile ID from kandelo_list_profiles; defaults to current computer.",
        "maxLength": 128
      },
      "startupScript": {
        "type": "string",
        "description": "Optional script executed when someone opens the generated link.",
        "maxLength": 2097152
      }
    },
    "required": [],
    "additionalProperties": false
  }
}