Threads and Execution API

Last validated: 2026-05-14

This page documents thread lifecycle APIs: create, inspect, list, watch, resume, and cancel behavior.

1) Thread RPC Matrix

2) CreateThread Arguments and Semantics

Request fields:

• script_name (required): target script.
• version: 0 uses active version.
• input_json: JSON payload string.
• execution_mode: LOCAL or CLOUD (accepted by contract).
• timeout: timeout override string such as "5m".
• metadata{}: arbitrary key-value labels.
• callback_url: webhook URL.
• load_env: resolve effective env for run.

Use cases:

• Trigger production runs from scheduler/orchestrator.
• Launch ad-hoc troubleshooting threads.
• Run with metadata for downstream auditing.

Current runtime caveat:

• execution_mode, timeout, and callback_url are accepted but not fully enforced by current scheduler path.

3) GetThread and ListThreads

GetThread

Response fields are optimized for live progress views:

• status, error
• current_step_path, current_step_name, total_steps
• created_at_ms, started_at_ms, finished_at_ms

Caveat:

• execution_mode in responses is currently mapped to cloud representation in runtime.

ListThreads

Request fields:

• page_size, page_token
• status_filter
• script_name_filter

Use cases:

• Build execution history pages.
• Find recent failed threads by script.

4) ResumeThread for Human-in-the-Loop

Request fields:

• thread_id (required)
• step_input_override_json (optional)

Use cases:

• Continue paused ask flows after user input.
• Recover from recoverable failures requiring corrected values.

Validation behavior:

• Type constraints are enforced.
• Option list constraints are enforced.
• Retry and expiry checks are enforced.

5) Watch APIs

WatchThread

Intended events:

• thread started/completed/failed/cancelled
• step started/completed/failed
• yielded values

Current behavior notes:

• Replay + live stream from ordered event consumer.
• Stream closes on terminal thread state.
• Several event categories are not forwarded in current mapping (ThreadPaused, decision/LLM/pipe internals).

WatchStep

Intended events:

• snapshot
• decision
• done
• step failed

Current behavior notes:

• Emits decision/done/failed for exact step_path.
• Initial snapshot event is not emitted in current runtime.

6) Example Calls

gRPC CreateThread + GetThread

# Create thread
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{
    "script_name":"invoice-parser",
    "version":0,
    "input_json":"{\"invoice_id\":\"INV-42\"}",
    "load_env":true,
    "metadata":{"source":"scheduler","ticket":"INC-1402"}
  }' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/CreateThread
 
# Inspect thread
grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"thread_id":"thr_abc123"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/GetThread

gRPC watch thread stream

grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"thread_id":"thr_abc123"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/WatchThread

HTTP contract example (gateway deployment)

curl -sS "https://api.dev.dodil.io:443/v1/scriptum/threads/thr_abc123" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID"

7) Client Recommendations

• Capture and persist thread_id immediately after creation.
• Use watch stream for UX progress; fallback to polling with GetThread if stream fails.
• Treat paused as a first-class terminal-like state requiring explicit resume flow.
• For mission-critical automations, validate input and env dependencies before thread creation.