CodeWords

Read a CodeWords workflow template's source code by its `id`. This is the correct way to open a template. Take the `id` straight from a `search_templates` result — no path construction, no directory guessing. Template source lives at `05-templates/templates/<dir>/<dir>.py`, but you should never need to write that: the tool resolves it for you, including the templates whose directory name differs from their id. Args: template_id: the id from `search_templates` (a path is tolerated and normalised, but the id is canonical). include_readme: also return README.md for the template. Returns: `{template_id, title, path, content, success}` plus `readme` / `readme_path` when `include_readme` is set. Unknown ids return a 404 whose message names `search_templates` and lists close matches.

read_template

Fetch logs for a single CodeWords workflow run, identified by request_id. Args: request_id: the id returned by `run_workflow` (run_async=True), `cancel_workflow`, or `get_workflow_requests`. follow: if True, stream logs until the run completes; if False, return the logs available right now (or up to a 30-second cap). Defaults to True. max_entries: cap on returned entries (1-10000, default 1000). **When to use this tool:** - To monitor progress of an async workflow execution - To debug issues with a workflow run - To get detailed execution information - To track long-running workflows in real-time **Cost-aware polling pattern (PREFERRED for long runs):** Each call re-sends the full set of log entries into chat context unless you pass `since_timestamp`. To avoid re-paying for entries you've already seen, capture `last_timestamp` from each response and pass it as `since_timestamp` on the next call. # initial fetch r1 = get_workflow_logs(request_id="cwr-…", follow=False) # later, only NEW entries: r2 = get_workflow_logs( request_id="cwr-…", follow=False, since_timestamp=r1["last_timestamp"], ) For quick "did anything happen?" checks, use `head_only=True` which returns just metadata (no log bodies). Returns: `{request_id, logs: [{timestamp, level, message, metadata?}], total_entries, is_complete, last_timestamp}`. `is_complete=False` indicates the cap or the time-limit was reached before the run finished; `last_timestamp` is the cursor for incremental polling.

get_workflow_logs

Run a snippet of Python in an isolated CodeWords sandbox (E2B). The sandbox is created per call, has no persistent filesystem, and is destroyed when the call returns. The same runtime is used by deployed CodeWords services, so behaviour matches production. Args: code: Python source to execute. Required for a new run; omit when reconnecting via `execution_id`. execution_id: ID returned by a previous call when status was "running". Used to reconnect to a still-running process and stream new output. Format "sandbox_id:process_id[:stdout_offset:stderr_offset]". dependencies: PyPI packages to install in the sandbox, with pinned versions, e.g. ["httpx==0.28.1"]. The CodeWords client ("codewords-client==0.4.11") is always included. secrets: names of the user's stored secrets to inject as environment variables in the sandbox. The secrets must already exist; values are injected server-side and must never be printed. max_execution_minutes: total runtime budget for the sandbox, 1-60. If a run exceeds ~4.5 minutes, the call returns with status="running" and an `execution_id`. Subsequent calls with that id return only new stdout/stderr since the previous offset, until the run completes or hits `max_execution_minutes`. Returns: `{success, exit_code, stdout, stderr, execution_time, dependencies, secrets_loaded}` on completion, or `{status:"running", execution_id, partial_stdout?, partial_stderr?, elapsed_seconds, remaining_minutes}` while still running. The sandbox runs as your CodeWords account and uses your CodeWords credits.

run_code

Execute one of the user's CodeWords workflows on the CodeWords runtime API (runtime.codewords.ai). The workflow must be a service the current user owns or a published CodeWords platform service. Args: workflow_id: the service id of the workflow to run. inputs: dict of parameters required by the workflow. The shape is defined by the workflow's input schema; resolve it via `view_service_code` or `consult_docs` on the matching template README before calling. path: optional sub-path on the workflow (e.g. "check-connection/ {app_slug}"). Defaults to the workflow's main entrypoint. method: HTTP method (default "POST"). Use "GET" for read-only endpoints such as discovery and connection checks. run_async: if False (default), waits up to `timeout_seconds` and returns the output. If True, returns immediately with a `request_id` for retrieval via `get_workflow_logs` / `get_workflow_output`. timeout_seconds: sync-mode wait, 1-3600 (default 300). is_template: True if the target service is a CodeWords platform template rather than an owned service. debug: when True, sets LOGLEVEL=DEBUG on the workflow run. Constraints: - The synchronous path enforces a ~5 minute client timeout. If the workflow takes longer the connection drops, but the run continues on the sandbox and is billed until completion or until the platform's 30-minute cap. For long-running workflows use `run_async=True` and poll with `get_workflow_output`. Returns: - Sync: `{output, logs, request_id, status, duration_seconds}`. - Async: `{output: null, logs: null, request_id, status:"started", message}`.

run_workflow

Search the CodeWords workflow-template catalog. Supports two modes: - Semantic (preferred): pass `query` with a natural-language description. Uses vector similarity to find matching templates. - Tag-based: pass `tags` with one or more tags to match. Matching is case-insensitive and supports both exact and substring match (e.g. "llm" matches "llm-integration"). `match_mode` controls OR ("any") vs AND ("all") logic. Returns: a `results` array of `{id, title, description, tags, matched_tags, match_types}` and a `summary` with `total_results`, `search_tags`, `match_mode`, and `all_available_tags`.

search_templates

Switch which implementation of a CodeWords service the user owns is the active one. All future requests against the service use the new active implementation immediately. Args: service_id: id of the service. implementation_id: id of an existing implementation of that service (see `list_service_implementations`). Returns: `{success, service_id, service_name, previous_active_implementation_id, new_active_implementation_id}`.

set_active_implementation

Track a task list for the current session. Pass the full updated list each call (the server does not retain state between calls); the response echoes the list back along with status counts so the client can render it. Args: todos: full list of task items. Each item has `content` (the task description), `status` ("pending" | "in_progress" | "completed"), and optional `substeps` (recursive todo items). Returns: `{message, status_summary: {pending, in_progress, completed}, todos: [...]}`.

todo_write

Read the source of a CodeWords service. Args: source: either a CodeWords service id (deployed service the user owns or a public template) or a file URL such as one returned by `edit_service`. The special string "workflow_skeleton" returns the empty service template. implementation_id: optional. With a service id, fetch a specific historical implementation rather than the active one. Ignored when `source` is a URL. show_line_numbers: if True, the returned `service_code` is prefixed with line numbers (and `total_lines` is included). Returns: `{success, source, source_type, service_code, ...}`. For service-id sources, also includes `service_id`, `service_name`, `implementation_id`, `is_active_implementation`, `owner_id`, `is_template`, `code_length`.

view_service_code