Workflow Worker
Hidden leaf: does one plain work card (research, reading, analysis) as a workflow node and answers with one result document. Never edits ticket fields. Base of the work tiers (`workflow-worker`, `workflow-impl`).
- Model
- Inherited
- Effort
- medium
- Extends
- defaultbuilt-in
- Icon
- terminal
- Color
- blue
- Visibility
- Hidden from the picker
No skills preloaded.
kanban::
ticket:: getkanbanv0.2.4Schema Read one ticket with its comments and activity, its parent, its live subtasks and their progress. The activity is bounded to keep the result small: every comment.created entry plus the newest 50 other entries (activity_total says how many exist), and a changed text longer than 200 chars (a description edit) is cut to a prefix ending in [truncated, N chars; ...]. kanban::activity::list returns the full history and the full text. The id accepts the internal uuid or the human-readable key.
request - idstringrequired
Ticket uuid or human-readable key (KAN-1, case-insensitive).
response - activityobject[]
- actorstringrequired
- atstringrequired
- changesobject[]
- fieldstringrequired
- fromunknownrequired
- tounknownrequired
- comment_idstring
- idstringrequired
- seqinteger· uint64requiredmin 0
- ticket_idstringrequired
- typestringrequired
ticket.created | ticket.updated | ticket.moved | ticket.deleted | ticket.restored | comment.created
- activity_totalinteger· uint64requiredmin 0
Activity entries the ticket has in total; `activity` holds fewer when older non-comment entries were left out (`kanban::activity::list` pages them all).
- assigneestring
Agent profile id.
- childrenobject[]required
Live subtasks by ticket number.
- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
- commentsobject[]
- authorstringrequired
Agent profile id, or `user`.
- bodystringrequired
- created_atstringrequired
- idstringrequired
- parent_idstring
Set for a reply; replies stay one level deep.
- ticket_idstringrequired
- created_atstringrequired
- created_bystring
- deleted_atstring
Set when soft-deleted; the row stays on disk.
- descriptionstring
- idstringrequired
Internal uuid.
- keystringrequired
Human-readable id, e.g. KAN-1.
- labelsstring[]
- orderinteger· uint64min 0
Position inside its column.
- parentany of
The parent, deleted or not; `null` for a ticket that is not a subtask.
any of (2)Variant 1- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
Variant 2valuenull - parent_idstring
Uuid of the parent ticket. One level deep: a parent has no parent.
- pillsobject[]
Small icon-and-text badges another worker pins on the ticket (a due date, a priority, an alarm). Shown on the card and the ticket page.
- iconstringrequired
- textstringrequired
- prioritystringrequired
- progressobjectrequired
Live children in the done column over live children that are not canceled.
- doneinteger· uint64requiredmin 0
- totalinteger· uint64requiredmin 0
- project_idstring
Uuid of the project (several tickets, independent of the release).
- release_idstring
Uuid of the release.
- statusstringrequired
Column id.
- titlestringrequired
- updated_atstringrequired
shell::
execidev0.13.7Schema Run a command in the foreground and return its full output. Put the program in `command` (string) and arguments in `args` (string[]), never argv in `command`. Host-only cwd/env/stdin reject S210 on a sandbox target. Errors return { code, message }; common: S216 host exec error, S300 VM boot failed, S200 in-VM failure.
request - argsstring[]
Arguments, in order (all strings). Omit/null to tokenize `command` shell-words style; pass an array (even empty) to use it verbatim.
- commandstringrequired
Program name (PATH-resolved) or path to an executable, as a string; put arguments in `args`.
- cwdstring
Working directory (host only, S210 on sandbox); jail-confined like shell::fs::* paths (S215 on escape), must be an existing directory.
- envobject
Per-call env values (host only, S210 on sandbox); exec-hijacking keys (PATH, IFS, HOME, LD_*/DYLD_*, …) reject the whole call S210.
- stdinstring
Bytes written to the program's stdin, then EOF (host only, S210 on sandbox); omit to leave stdin at /dev/null.
- targetall of
Where to run the command. Defaults to the host worker; pass `{ kind: "sandbox", sandbox_id }` to forward the call to a microVM.
all of (1)Variant 1one of (2)Variant 1- kindstringrequiredenum host
Variant 2- kindstringrequiredenum sandbox
- sandbox_idstring· uuidrequired
- timeout_msinteger· uint64min 0
Per-call timeout in milliseconds, capped at the configured max; negative or fractional values fall back to the default.
response - duration_msinteger· uint64requiredmin 0
- exit_codeinteger· int32
- stderrstringrequired
- stderr_truncatedbooleanrequired
- stdoutstringrequired
- stdout_truncatedbooleanrequired
- timed_outbooleanrequired
coder::
read-fileidev0.13.7Schema Read a file. stat: true probes size/mtime/total_lines without content; line_from/line_to (1-based, inclusive) read a window of a file of any size; numbered: true prefixes absolute line numbers; paths[] (XOR path) batch-reads. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
request - encodingall of
Content encoding for full reads; `base64` returns the exact file bytes (encoded length is budgeted). C210 with stat/window/numbered.
all of (1)Variant 1one of (2)Variant 1valuestringenum textVariant 2valuestringenum base64 - line_frominteger· uint64min 1
First line (1-based, >= 1) of a windowed read; windows keep files over max_read_bytes readable slice by slice. `path` mode only.
- line_tointeger· uint64min 1
Last line of the window, 1-based inclusive, >= `line_from`; omit to read from `line_from` to EOF. `path` mode only.
- max_output_bytesinteger· uint64min 0
Full-read byte budget (returned bytes, clamped to max_read_bytes); over budget fails C218 naming size/total_lines. C210 with a window.
- numberedboolean
Prefix each line with its absolute 1-based file line number (`N→`), matching coder::update-file line ops; C210 with `stat`. `path` mode only.
- pathstring
Single file to read; XOR with `paths` (C210 if both or neither is set).
- pathsany of[]
Batch of files to read in one call (bare path strings or window objects), processed in order against batch_read_budget_bytes; XOR with `path`.
any of (2)Variant 1valuestringVariant 2- line_frominteger· uint64min 1
First line of the window, 1-based inclusive (>= 1); defaults to 1 when only `line_to` is set.
- line_tointeger· uint64min 1
Last line of the window, 1-based inclusive, >= `line_from`; omit to read to EOF.
- numberedboolean
Prefix this entry's lines with their absolute 1-based line numbers (`N→`); prefix bytes count toward the batch budget.
- pathstringrequired
File to read.
- statboolean
Metadata probe for this entry: size/mode/mtime plus total_lines, content null, no budget consumed; C210 with a window or `numbered`.
- statboolean
Metadata probe: size/mode/mtime plus total_lines/is_utf8, no content; C210 with line_from/line_to/numbered/max_output_bytes.
response - contentstring
File content as a UTF-8 string — the whole file, or just the requested window when `line_from`/`line_to` was given (window lines keep their newline terminators). Binary content is returned with invalid bytes replaced by U+FFFD; request `encoding: "base64"` when exact bytes matter (content is then the file's bytes base64-encoded). **Single-path mode only; null when the request used `paths[]`.**
- is_utf8boolean
Whether `content` survived UTF-8 conversion without losing bytes. Reflects the RETURNED content only: a clean window inside an otherwise-binary file is still `true`. **Single-path mode only; null when the request used `paths[]`.**
- lines_returnedinteger· uint64min 0
Number of lines in `content`. For full reads this equals the file's total line count. **Single-path mode only; null when the request used `paths[]`.**
- modeinteger· uint32min 0
Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644. **Single-path mode only; null when the request used `paths[]`.**
- more_linesboolean
True when the file has content beyond what `content` includes: the window ended before EOF, or the byte budget cut the window short. Always false for full reads. **Single-path mode only; null when the request used `paths[]`.**
- mtimeinteger· int64
Last-modified time as a Unix epoch in seconds. **Single-path mode only; null when the request used `paths[]`.**
- pathstring
Canonical absolute path of the file read (resolved through the jail). **Single-path mode only; null when the request used `paths[]`.**
- resultsobject[]
Per-entry results for a batch `paths[]` request. **Present only when the request used `paths[]`; null in single-path mode.**
- contentstring
File content as a UTF-8 string — the whole file or the requested window. Binary bytes are replaced by U+FFFD (`is_utf8: false`). `null` on failure.
- errorany of
Structured error — present only when `success: false`.
any of (2)Variant 1- codestringrequired
Stable error code, e.g. "C211". See the README error table.
- messagestringrequired
Human/LLM-readable message: problem + actual values + corrective next call.
Variant 2valuenull - is_utf8boolean
Whether `content` survived UTF-8 conversion without losing bytes. `null` on failure.
- lines_returnedinteger· uint64min 0
Number of lines returned in `content`. `null` on failure.
- modeinteger· uint32min 0
Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644. `null` on failure.
- more_linesboolean
`true` when the file has content beyond what `content` includes (window ended before EOF, or byte budget cut the window short). `null` on failure.
- mtimeinteger· int64
Last-modified time as a Unix epoch in seconds. `null` on failure.
- pathstringrequired
Canonical absolute path of the file (resolved through the jail). If resolution failed, this echoes the caller's input verbatim.
- sizeinteger· uint64min 0
Size of the FILE in bytes (from metadata). `null` on failure or when the entry budget was exhausted before the file was opened.
- successbooleanrequired
`true` when the read succeeded (content/metadata fields are populated); `false` when an error occurred (only `error` is set).
- total_linesinteger· uint64min 0
Total lines in the file; present when the stream reached EOF during this entry's read. `null` when not traversed or on failure.
- revisionstring
Opaque identity of the file's exact bytes. Present for complete single-path reads only; pass it as `expected_revision` to `coder::create-file` for a conflict-safe whole-file overwrite.
- sizeinteger· uint64min 0
Size of the FILE in bytes (from metadata) — not the size of `content`; in windowed mode the two differ. **Single-path mode only; null when the request used `paths[]`.**
- total_linesinteger· uint64min 0
Total number of lines in the file. Present only when the read traversed the whole file: always for full reads; for windowed reads only when the stream naturally reached EOF within the byte cap. Never computed by forcing an extra full scan — absent means the file was not fully traversed. **Single-path mode only; null when the request used `paths[]`.**
shell::
exec_bgidev0.13.7Schema Spawn a background job; returns { job_id, argv } immediately. Accepts the shell::exec payload plus optional job_id. Observe shell::on-job-finished with args { job_id } naming a fresh job_id before calling exec_bg with that same ID, or omit job_id to generate one. Duplicate retained IDs reject before execution. Host jobs ignore timeout_ms and use the configured background hard cap; read output with shell::status, list jobs with shell::list. Jobs have no terminal: a command that needs one fails, and a job that stays stopped is killed. Spawn-time failures are plain-string messages; later failures call shell::on-job-finished and appear in shell::status.
request - argsstring[]
Arguments, in order (all strings). Omit/null to tokenize `command` shell-words style; pass an array (even empty) to use it verbatim.
- commandstringrequired
Program name (PATH-resolved) or path to an executable, as a string; put arguments in `args`.
- cwdstring
Working directory (host only, S210 on sandbox); jail-confined like shell::fs::* paths (S215 on escape), must be an existing directory.
- envobject
Per-call env values (host only, S210 on sandbox); exec-hijacking keys (PATH, IFS, HOME, LD_*/DYLD_*, …) reject the whole call S210.
- job_idstringmin 1 chars
Optional non-blank ID for observing shell::on-job-finished before execution. Must be unique among retained jobs in this worker. Omit or pass null to generate a job-UUID automatically.
- stdinstring
Bytes written to the program's stdin, then EOF (host only, S210 on sandbox); omit to leave stdin at /dev/null.
- targetall of
Where to run: the host (default) or { kind: "sandbox", sandbox_id }.
all of (1)Variant 1one of (2)Variant 1- kindstringrequiredenum host
Variant 2- kindstringrequiredenum sandbox
- sandbox_idstring· uuidrequired
- timeout_msinteger· uint64min 0
Per-call timeout in milliseconds; ignored by host background jobs, forwarded to sandbox targets.
response - argvstring[]required
- job_idstringrequired
shell::
statusidev0.13.7Schema Fetch the full record (status, exit_code, timing, output) of a background job by job_id. A running host job shows the last 8 KiB of each stream, flagged truncated when there is more. Errors return { code, message }; common: S211 no such job.
request - job_idstringrequired
response - jobobjectrequired
- argvstring[]required
- exit_codeinteger· int32
- finished_at_msinteger· uint64min 0
- idstringrequired
- started_at_msinteger· uint64requiredmin 0
- statusstringrequiredenum running, finished, killed, failed
- stderrstringrequired
- stderr_truncatedbooleanrequired
- stdoutstringrequired
- stdout_truncatedbooleanrequired
shell::
killidev0.13.7Schema Terminate a running background job by job_id (returned by shell::exec_bg). Errors return { code, message }; common: S211 no such job, S216 kill/signal delivery failure.
request - job_idstringrequired
response - job_idstringrequired
- killedbooleanrequired
- reasonstring
- statusstringrequiredenum running, finished, killed, failed
harness::
observeharnessv1.9.14Schema Observe a function for the current harness session: each time it runs, omit `target` to be notified in this session with what it returned, or name a non-harness `target.function_id` to call with it. Pass the function's `args` when it takes them and `filters` on its `input.<field>` to choose calls. Set `lifecycle.expires_in_ms` on every wake except a timer, to how long the work should take; a one-shot wake without it expires after 10 minutes with a notice. Returns `{ observer_id, once }`; a `note` is advice about the observer, which was created either way. Call-target results are discarded and do not return to this session.
request - actionstring
User-facing text saying what happened, shown with each delivery.
- argsobject
Args for the worker that hosts the function, a JSON object; its description says which it takes: cron `{ "expression" }`, database `{ "db", "table"?, "ops"? }`, `harness::on-timer` `{ "in_ms" }` or `{ "at" }` (epoch ms). Omit for a function that takes none.
- conditionsobject[]
Delivery-time gates, in order; each is an iii function answering `{ decision: "allow" | "skip", payload?, reason? }`.
- configunknown
Passed to the condition function AS its `condition_config`: give its fields (e.g. `id`, `expect`) directly, not wrapped in `condition_config`.
- function_idstringrequired
- filtersobject
Which calls reach this observer, a JSON object of explicit operators on the call's fields: `{ "input.scope": { "$eq": "run" } }`.
- function_idstringrequired
The function to observe: `state::on-changed`, `cron::on-tick`, `harness::on-timer`, `database::on-row-changed`, or any other function. What it returns is the event.
- labelstring
A short human label echoed back in the notification text.
- lifecycleany of
When the observer stops delivering; top-level `once` is the shorthand.
any of (2)Variant 1- expires_in_msinteger· int64
Relative deadline: the observer stops this many milliseconds after it was created (the only deadline form). Set it on every wake except a timer, to how long the work should take: if nothing fires by then, the session is woken with a notice. A one-shot wake without it expires after 10 minutes.
- max_firesinteger· uint64min 0
Lifetime delivery budget; the observer is removed on its Nth delivery.
- onceboolean
Remove the observer after its first delivery (same as top-level `once`).
Variant 2valuenull - namespacestring
Where the function is hosted; omitted: this harness's namespace, then `default`, then Compose's.
- onceboolean
Remove the observer after its first delivery; defaults to true for a wake (no `target`) and `harness::on-timer`, false for a call target and `cron::on-tick`.
- targetany of
The function called with each event: `{ function_id, payload?, event_into? }` — the fixed payload and the JSON pointer where the event is injected into it (default `/event`). Omit it to be notified in this session instead. `harness::spawn` is never a valid target.
any of (2)Variant 1- event_intostring
JSON pointer where the event lands inside the payload (default `/event`).
- function_idstringrequired
- payloadunknown
Payload template; the delivered event is injected into it at `event_into`.
Variant 2valuenull
response - notestring
Advisory only — the observer was CREATED. Says what applied by default or what looks suspicious in its wiring (e.g. a filter naming a key someone already wrote). Read it and act on it if it applies.
- observer_idstringrequired
- oncebooleanrequired
The effective `once` flag applied (after the per-function default).
workflow-result::
submitworkflowv0.3.5Schema Deliver this workflow node's result: call it once with {"result": <the JSON value your node's output schema requires>}. An error names what to fix: call it again. Once it is accepted, end your turn with one short line, not the JSON. The node is finished once the turn ends: submit last. Only a workflow node's own session can call it.
request - caller_session_idstring
Stamped from the calling session by the workflow's pre-call hook; a supplied value is overwritten.
- resultunknownrequired
The node's result: the JSON value its output schema requires.
response - acceptedbooleanrequired
- nodestringrequired
The node uid the result was stored for.
- browser::
dynamic-fetchUnknown - browser::
sessions:: startUnknown - browser::
elementsUnknown - browser::
actUnknown - browser::
sessions:: stopUnknown