Protocol Verbs

Task cards

Task cards: part of the Protocol Verbs of TUIOS.

This page is one part of docs/protocol-verbs.md of the tuios repository. The Protocol Verbs page lists every part.

add-task Added in v0.12.0

Add a task card to a session: one unit of work, with a title, the prompt for the pane that takes it, and a stage. The card is kept by the daemon and saved with the session, so it survives the pane that added it and a restart. Who added it (by) comes from the connection.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
titlestringyesOne line that says what the card is, at most 200 bytes. Control characters are dropped.
promptstringWhat the pane that takes the card is to do, at most 16 KiB.
stagestringtodoThe stage it starts in. One of todo, plan, doing, verify, review, shipped or done.
projectstringThe repository the card is for, by its origin URL. It then shows on that repository's board in every session and on linked machines, and a pane on another machine can claim it with host. Omit for a card of the session only.
harnessstringThe agent the card is for, such as claude-code. Pull dispatch gives it only to that agent. Omit for any agent.
ask_firstboolfalseThe card waits for a person to start it: dispatch never gives it to an agent.
machinestringWhere the card's agent starts: any for the machine place-agent picks, or a linked machine's name. Omit for this machine.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
Result fieldTypeDescription
idstringThe card.
sessionstringIts session.
titlestringIts title.
previewstringThe first line of its prompt, at most 80 characters.
stagestringIts stage. One of todo, plan, doing, verify, review, shipped or done.
stage_atintWhen it entered the stage, Unix nanoseconds.
holderobjectThe pane that holds it: window, name, harness, state (read from the pane now) and held_at. Null when no pane holds it.
bystringWho added it: human, shell, the adding pane's window id, link:HOST or plugin:ID.
atintWhen it was added, Unix nanoseconds.
blockedobjectreason, by and at when the card is blocked, else null.
fanobjectfan and fan_id, for a card added in a fan's session.
attachment_countintHow many attachments the card has. Absent for none.
{"id":1,"verb":"add-task","params":{"session":"work","title":"make the backoff jitter configurable","prompt":"Read api/retry.go and add a jitter option, with a test."}}

attach-task Added in v0.13.1

Put a file or a link on a task card. The caller sends the file's bytes; the daemon never reads a path. A file is stored once by its sha256 and goes when no card names it. The kind is read from the content, then the name. The limits are [tasks] attachment_max_mib, attachments_per_card and attachment_session_mib. A pane changes the attachments of the card it holds, and of the card it finished while that card waits in verify or review; admin, the person, a shell, a link and a plugin change any card's.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
namestringThe name the card shows it by, at most 120 bytes; control and invisible characters are dropped. Required with content; a pull request link defaults to PR #N, another link to its host and path.
contentstringThe file, base64 encoded. Pass one of content, files, link, screenshot and capture.
files[]objectSeveral files at once, each name and content (base64): one change and one history entry. All of them fit one request line (12 MiB in base64).
linkstringAn http or https address. A GitHub pull request's address is kind pr.
notestringA line about it, at most 500 bytes.
replaceboolfalsePut it in the place of the attachment with the same name. Without it a name in use with other bytes is refused; the same name with the same bytes is left as it is, so a retry succeeds.
screenshotobjectwindow (a pane of the card's session), scrollback and lines: the daemon takes a PNG of the pane and attaches it, named after the pane. A pane that calls needs the read grant.
captureobjectwindow, scrollback and lines (default 2000): the daemon takes the pane's text and attaches it. A pane that calls needs the read grant.
hoststringThe machine that owns the card, for a project card from the pane that holds it there. The attach is passed on over the link; a picture or a text is taken here first. At most 3 MiB crosses.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
remote_windowstringOver the link only: the window on the calling machine that holds the card. Its daemon sends it; the holder's machine is the link's peer.
remote_namestringOver the link only: how that window reads on its machine.
remote_harnessstringOver the link only: the agent that window runs.
Result fieldTypeDescription
attachmentobjectname, kind (image, markdown, mermaid, diff, text, link, pr, file), media_type, size, hash, url (a link), note, by and at.
attachments[]objectEvery attachment the call named, as the card holds it now.
unchanged[]stringThe names the card held with the same bytes already, left as they were.
taskobjectThe card's row after the attach.
{"id":1,"verb":"attach-task","params":{"session":"work","id":"t1","name":"after.png","content":"iVBORw0KGgo=","note":"the fixed layout"}}
{"id":1,"verb":"attach-task","params":{"session":"work","id":"t1","link":"https://github.com/o/r/pull/12"}}

block-task Added in v0.12.0

Mark a task card stuck, saying what it waits on, or with clear lift the mark. A blocked card keeps its holder and its stage, and claim-task next skips it. To let a card go, use release-task. A pane changes only the card it holds unless it holds admin; the person, a shell, a link and a plugin change any card.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
reasonstringWhat the card waits on, at most 500 bytes. Required without clear.
clearboolfalseLift the block. Not with reason.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
Result fieldTypeDescription
idstringThe card.
sessionstringIts session.
titlestringIts title.
previewstringThe first line of its prompt, at most 80 characters.
stagestringIts stage. One of todo, plan, doing, verify, review, shipped or done.
stage_atintWhen it entered the stage, Unix nanoseconds.
holderobjectThe pane that holds it: window, name, harness, state (read from the pane now) and held_at. Null when no pane holds it.
bystringWho added it: human, shell, the adding pane's window id, link:HOST or plugin:ID.
atintWhen it was added, Unix nanoseconds.
blockedobjectreason, by and at when the card is blocked, else null.
fanobjectfan and fan_id, for a card added in a fan's session.
attachment_countintHow many attachments the card has. Absent for none.
{"id":1,"verb":"block-task","params":{"session":"work","id":"t1","reason":"waiting on the staging API key"}}
{"id":1,"verb":"block-task","params":{"session":"work","id":"t1","clear":true}}

claim-task Added in v0.12.0

Take a task card for a pane: the card id, or with next the oldest card no pane holds that is not blocked or done, and that no fan of another session works on (fan with task). A card in todo or plan moves to doing. The pick and the take are one step, so two panes claiming next at once take two cards. A pane claims only for itself unless it holds admin; outside a pane, name the window. The card is released when its pane closes, its agent leaves the pane, or the daemon restarts.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringThe card to take. Not with next.
nextboolfalseTake the oldest open card no pane holds and that is not ask_first. Not with id. With none to take, the call fails with no_task.
windowstringThe pane that takes the card, by id or name. From a pane, omit it to claim for that pane. Required outside a pane.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
hoststringThe machine that owns the card, for a project card claimed, released or finished from the pane that works on it here. The call is passed on over the link for this pane.
remote_windowstringOver the link only: the window on the calling machine that holds the card. Its daemon sends it; the holder's machine is the link's peer.
remote_namestringOver the link only: how that window reads on its machine.
remote_harnessstringOver the link only: the agent that window runs.
Result fieldTypeDescription
idstringThe card.
sessionstringIts session.
titlestringIts title.
previewstringThe first line of its prompt, at most 80 characters.
stagestringIts stage. One of todo, plan, doing, verify, review, shipped or done.
stage_atintWhen it entered the stage, Unix nanoseconds.
holderobjectThe pane that holds it: window, name, harness, state (read from the pane now) and held_at. Null when no pane holds it.
bystringWho added it: human, shell, the adding pane's window id, link:HOST or plugin:ID.
atintWhen it was added, Unix nanoseconds.
blockedobjectreason, by and at when the card is blocked, else null.
fanobjectfan and fan_id, for a card added in a fan's session.
attachment_countintHow many attachments the card has. Absent for none.
{"id":1,"verb":"claim-task","params":{"session":"work","next":true,"window":"build"}}
{"id":1,"verb":"claim-task","params":{"session":"work","id":"t1","window":"build"}}

detach-task Added in v0.13.1

Take an attachment off a task card. Its file goes when no card names it. A pane changes the attachments of the card it holds, and of the card it finished while that card waits in verify or review; admin, the person, a shell, a link and a plugin change any card's.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
namestringyesThe attachment's name on the card.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
remote_windowstringOver the link only: the window on the calling machine that holds the card. Its daemon sends it; the holder's machine is the link's peer.
remote_namestringOver the link only: how that window reads on its machine.
remote_harnessstringOver the link only: the agent that window runs.
Result fieldTypeDescription
idstringThe card.
sessionstringIts session.
titlestringIts title.
previewstringThe first line of its prompt, at most 80 characters.
stagestringIts stage. One of todo, plan, doing, verify, review, shipped or done.
stage_atintWhen it entered the stage, Unix nanoseconds.
holderobjectThe pane that holds it: window, name, harness, state (read from the pane now) and held_at. Null when no pane holds it.
bystringWho added it: human, shell, the adding pane's window id, link:HOST or plugin:ID.
atintWhen it was added, Unix nanoseconds.
blockedobjectreason, by and at when the card is blocked, else null.
fanobjectfan and fan_id, for a card added in a fan's session.
attachment_countintHow many attachments the card has. Absent for none.
{"id":1,"verb":"detach-task","params":{"session":"work","id":"t1","name":"after.png"}}

finish-task Added in v0.12.0

Mark a task card done. Its holder lets it go and its block, if any, is lifted. Finishing a card that is done already changes nothing. A pane changes only the card it holds unless it holds admin; the person, a shell, a link and a plugin change any card.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
hoststringThe machine that owns the card, for a project card claimed, released or finished from the pane that works on it here. The call is passed on over the link for this pane.
remote_windowstringOver the link only: the window on the calling machine that holds the card. Its daemon sends it; the holder's machine is the link's peer.
remote_namestringOver the link only: how that window reads on its machine.
remote_harnessstringOver the link only: the agent that window runs.
Result fieldTypeDescription
idstringThe card.
sessionstringIts session.
titlestringIts title.
previewstringThe first line of its prompt, at most 80 characters.
stagestringIts stage. One of todo, plan, doing, verify, review, shipped or done.
stage_atintWhen it entered the stage, Unix nanoseconds.
holderobjectThe pane that holds it: window, name, harness, state (read from the pane now) and held_at. Null when no pane holds it.
bystringWho added it: human, shell, the adding pane's window id, link:HOST or plugin:ID.
atintWhen it was added, Unix nanoseconds.
blockedobjectreason, by and at when the card is blocked, else null.
fanobjectfan and fan_id, for a card added in a fan's session.
attachment_countintHow many attachments the card has. Absent for none.
{"id":1,"verb":"finish-task","params":{"session":"work","id":"t1"}}

get-task Added in v0.12.0

Read one task card whole: its row, its prompt and its history.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
Result fieldTypeDescription
idstringThe card.
sessionstringIts session.
titlestringIts title.
previewstringThe first line of its prompt, at most 80 characters.
stagestringIts stage. One of todo, plan, doing, verify, review, shipped or done.
stage_atintWhen it entered the stage, Unix nanoseconds.
holderobjectThe pane that holds it: window, name, harness, state (read from the pane now) and held_at. Null when no pane holds it.
bystringWho added it: human, shell, the adding pane's window id, link:HOST or plugin:ID.
atintWhen it was added, Unix nanoseconds.
blockedobjectreason, by and at when the card is blocked, else null.
fanobjectfan and fan_id, for a card added in a fan's session.
attachment_countintHow many attachments the card has. Absent for none.
promptstringThe prompt, as added.
attachments[]objectThe files and links on the card, in the order they were added: name, kind, media_type, size, hash, url (a link), note, by and at. get-task-attachment reads one.
history[]objectEvery change, oldest first, at most 100 (the first is kept): action (added, claimed, finished, staged, blocked, unblocked, released, attached, detached), by, at, stage, holder and reason. A release the daemon made has by tuios and reason pane closed, agent left or restart. A stage the daemon moved on its own ([tasks] auto_stage) has by tuios and a reason naming the fact: plan held for approval, agent working, fan check started, fan check failed in every attempt, or the pull request opened, merged or closed.
{"id":1,"verb":"get-task","params":{"session":"work","id":"t1"}}

get-task-attachment Added in v0.13.1

Read one attachment of a task card, with the file's bytes for a file.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
namestringyesThe attachment's name on the card.
Result fieldTypeDescription
attachmentobjectname, kind (image, markdown, mermaid, diff, text, link, pr, file), media_type, size, hash, url (a link), note, by and at.
contentstringThe file, base64 encoded. Absent for a link.
probjectFor a pr link: number, url, state (open, merged or closed), title and checks (pass, fail or pending, with passed, failed and pending), read through gh at most once a minute.
pr_errorstringFor a pr link gh could not read: why, such as gh not installed or not logged in.
{"id":1,"verb":"get-task-attachment","params":{"session":"work","id":"t1","name":"after.png"}}

get-task-dispatch Added in v0.13.1

Read the task dispatch settings: each board's mode (manual or pull) and the switches that stop dispatch (pause, quiet hours, a board stopped after 3 failures in a row, a usage limit).

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
projectstringThe project board, by origin URL. Omit for the session's own cards.
Result fieldTypeDescription
pausedboolTrue while dispatch is paused.
paused_bystringWho paused it.
stoppedstringWhy all dispatch stopped on its own, such as usage limit. Empty when it did not.
quietstringThe quiet hours, local time, such as 22:00-07:00.
quiet_nowboolTrue inside the quiet hours.
boards[]objectThe boards with a mode or a stop: board, project or session, mode, failures (dispatched cards in a row that did not finish), stopped, verify and verify_timeout.
capintAuto's agents at once, in total.
machine_capintAuto's agents at once on one machine.
runningintAuto's agents now.
boardobjectThe board the call named, also when it is manual. An auto board adds preset, running, waiting and note.
{"id":1,"verb":"get-task-dispatch","params":{"project":"git@github.com:acme/api.git"}}

list-tasks Added in v0.12.0

List a session's task cards, oldest first.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
stagestringOnly the cards in this stage. One of todo, plan, doing, verify, review, shipped or done.
holderstringOnly the cards this window holds, by id or name.
openboolfalseLeave out the cards that are done.
projectstringList one repository's cards, by origin URL, from every session. Takes no session or holder.
hostsboolfalseWith project, or with all_sessions: also ask each linked machine for its own cards of the project, or for all its project cards. Rows from another machine carry host; machines that did not answer are in hosts_down.
all_sessionsboolfalseList the cards of every session on the daemon, in session name order. Takes no session or holder.
Result fieldTypeDescription
sessionstringThe session listed. Absent with all_sessions.
all_sessionsboolTrue when every session was listed. Each row names its session.
tasks[]objectOne row per card: id, session, title, preview (the first line of the prompt, at most 80 characters), stage, stage_at (Unix nanoseconds), holder (window, name, harness, state, held_at, read from the pane now; null when no pane holds it), by (human, shell, the adding pane's window id, link:HOST or plugin:ID), at, blocked (reason, by, at; null when not blocked) and fan (fan, fan_id) for a card added in a fan.
{"id":1,"verb":"list-tasks","params":{"session":"work","open":true}}
{"id":1,"verb":"list-tasks","params":{"all_sessions":true}}

release-task Added in v0.12.0

Let a task card go without finishing it. It keeps its stage, and another pane can claim it. A pane changes only the card it holds unless it holds admin; the person, a shell, a link and a plugin change any card.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
hoststringThe machine that owns the card, for a project card claimed, released or finished from the pane that works on it here. The call is passed on over the link for this pane.
remote_windowstringOver the link only: the window on the calling machine that holds the card. Its daemon sends it; the holder's machine is the link's peer.
remote_namestringOver the link only: how that window reads on its machine.
remote_harnessstringOver the link only: the agent that window runs.
Result fieldTypeDescription
idstringThe card.
sessionstringIts session.
titlestringIts title.
previewstringThe first line of its prompt, at most 80 characters.
stagestringIts stage. One of todo, plan, doing, verify, review, shipped or done.
stage_atintWhen it entered the stage, Unix nanoseconds.
holderobjectThe pane that holds it: window, name, harness, state (read from the pane now) and held_at. Null when no pane holds it.
bystringWho added it: human, shell, the adding pane's window id, link:HOST or plugin:ID.
atintWhen it was added, Unix nanoseconds.
blockedobjectreason, by and at when the card is blocked, else null.
fanobjectfan and fan_id, for a card added in a fan's session.
attachment_countintHow many attachments the card has. Absent for none.
{"id":1,"verb":"release-task","params":{"session":"work","id":"t1"}}

remove-task Added in v0.12.0

Remove a task card and its history. A pane needs the admin grant; the person and a shell remove any card.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
Result fieldTypeDescription
idstringThe card removed.
{"id":1,"verb":"remove-task","params":{"session":"work","id":"t1"}}

set-task-stage Added in v0.12.0

Move a task card to a stage by hand. The daemon also moves cards on its own ([tasks] auto_stage), only from the stages each fact moves a card from, so a card put in another stage by hand stays there. A move to done is a finish: the holder lets the card go, its block is lifted, and task-finished is sent. A move to the stage the card is in changes nothing. A pane changes only the card it holds unless it holds admin; the person, a shell, a link and a plugin change any card.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
idstringyesThe card, such as t1.
stagestringyesThe stage to move the card to. One of todo, plan, doing, verify, review, shipped or done.
human_noncestringThe attached client's nonce, to act as the person (by human). One that does not verify is refused with not_human.
Result fieldTypeDescription
idstringThe card.
sessionstringIts session.
titlestringIts title.
previewstringThe first line of its prompt, at most 80 characters.
stagestringIts stage. One of todo, plan, doing, verify, review, shipped or done.
stage_atintWhen it entered the stage, Unix nanoseconds.
holderobjectThe pane that holds it: window, name, harness, state (read from the pane now) and held_at. Null when no pane holds it.
bystringWho added it: human, shell, the adding pane's window id, link:HOST or plugin:ID.
atintWhen it was added, Unix nanoseconds.
blockedobjectreason, by and at when the card is blocked, else null.
fanobjectfan and fan_id, for a card added in a fan's session.
attachment_countintHow many attachments the card has. Absent for none.
{"id":1,"verb":"set-task-stage","params":{"session":"work","id":"t1","stage":"review"}}

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page