Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Use the session waiter endpoints to let one session wait for named outcomes in another live session of the same realm. This page covers creating, listing, reading, and cancelling waiters. Access to these Kit routes is controlled by the computer’s proxy permission rules.

A waiter belongs to the session identified in the request path. It watches another live session of the same realm, called the target, until one of its named outcomes is found or its deadline passes.

  • Exact outcomes use match. Every specified field must hold, and exact matches are checked on every event.
  • Judged outcomes use when. A model checks the sentence against the target’s tool calls, tool results and questions. The target’s own replies are not evidence. A judged result is a finding, not a proof.
  • A judged outcome is found only when the model is confident and points at one event.
  • Judged checks run a few seconds after new tool results, at most every 5 seconds, and at once when a target turn ends. Each model request, a retried one included, costs a fraction of a cent and counts toward max_checks.
  • The deadline is max_s seconds after creation. When the deadline passes, events already seen receive one last check.
  • The end is announced on the owner session’s stream as event.waiter_done, carrying the waiter.
  • The read window after the end is 24 hours. At most 64 ended waiters are retained, and those older than 24 hours may be removed.
  • A waiter does not survive an agent restart. It then reads the outcome interrupted.

Waiter ids use the prefix wt_ followed by 16 base64url characters, for example wt_Qk3xV9aLm2Tz7RfH.

The list response contains a required items array. Each item uses the waiter fields below. Create, get and cancel return these fields at the top level.

FieldTypeRequiredDescription
itemsarrayYes, list response onlyThe session’s waiters, newest first.
waiter_idstringYesThe waiter’s id. It starts with wt_ and contains 16 base64url characters.
labelstringNoThe label the waiter was created with.
ownerstringYesThe session that waits, which is the path session.
targetstringYesThe session that is watched.
outcomesarrayYesThe outcomes the waiter looks for.
outcomes[].namestringYesThe outcome name: 1 to 32 lowercase letters, digits or _, starting with a letter. The names timeout, cancelled, target_closed, interrupted, access_lost and judge_unavailable are reserved.
outcomes[].whenstringNoA judged event description of at most 300 characters. Give exactly one of when and match.
outcomes[].matchobjectNoAn exact event definition. Give exactly one of when and match.
outcomes[].match.kindstringYes, when match is presentThe event kind: tool_result, tool_call, gate or turn_end.
outcomes[].match.toolstringNoThe tool’s name, such as bash or write_file.
outcomes[].match.exit_codeintegerNoThe exit status required for a tool_result.
outcomes[].match.is_errorbooleanNoThe error flag required for a tool_result.
outcomes[].match.text_containsstringNoCase-sensitive text that the event must contain, at most 200 characters.
outcomes[].match.outcomestringNoThe required turn_end outcome: completed, failed or cancelled.
fromstringNoThe target turn from which events are read, when one was given.
statestringYeswaiting or done.
outcomestringNoThe outcome found, or timeout, cancelled, target_closed, interrupted, access_lost or judge_unavailable.
reasonstringNoA sentence explaining why the waiter ended.
also_foundarrayNoOther outcomes found in the same check, in the order they were given.
evidenceobjectNoThe event in which the outcome was found.
evidence.seqintegerYes, when evidence is presentThe event’s number in the target’s event list.
evidence.turn_idstringNoThe target turn containing the event.
evidence.kindstringYes, when evidence is presentThe event kind: tool_result, tool_call, gate or turn_end.
evidence.toolstringNoThe tool’s name.
evidence.exit_codeintegerNoThe command’s observed exit status.
evidence.is_errorbooleanNoWhether the tool reported an error.
evidence.excerptstringNoThe beginning of the event text, with secrets removed.
evidence.bystringYes, when evidence is presentmatch for an exact outcome or judge for a model finding. A judged finding points at an event but does not prove the outcome.
evidence.pnumberNoThe model’s probability that the events show a judged outcome.
on_timeoutstringNoThe creator’s timeout instruction: continue, stop or ask. The agent keeps it for the creator’s use and does not act on it.
created_atstringYesThe RFC3339 creation time.
deadline_atstringYesThe RFC3339 deadline.
ended_atstringNoThe RFC3339 end time when the waiter is done.
elapsed_msintegerNoThe milliseconds from creation to the end.
max_checksintegerYesThe maximum number of model requests. A retried request counts again.
checksintegerYesThe number of model requests made, including retries.
items_seenintegerYesThe number of target events read.
gapbooleanNoWhether some target events may not have been read.
cost_usdnumberYesWhat the model checks cost in US dollars.
cost_knownbooleanYesWhether the price of every check was reported.
modelstringNoThe model used to check judged outcomes.

Error responses use the following envelope:

FieldTypeRequiredDescription
codestringYesThe stable machine-readable error code.
messagestringYesThe human-readable error message.
detailsobjectNoStructured details for error codes that carry them.

Lists the session’s retained waiters, newest first. Ended waiters may be removed when retention is enforced: at most 64 ended waiters are retained, and those older than 24 hours may be removed. Use state=waiting or state=done to narrow the list. A closed session’s waiters remain listed while the current login can read the session.

X-Hoody-Cwd and X-Hoody-Config-Dir are not read because the path session supplies both.

NameInTypeRequiredDescription
idpathstringYesThe session id.
statequerystringNoOnly waiters in this state: waiting or done.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. This route does not read it because the path session supplies the working directory. The value must be UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. This route does not read it because the path session supplies the configuration directory. The value must be UTF-8.
X-Hoody-RealmheaderstringNoRealm selector: global or a 24-hex realm id. It selects the realm used to look up the session. A session in another realm or an inaccessible realm returns not_found.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. Use global or a 24-hex realm id.

This endpoint accepts no request body.

Terminal window
curl --request GET \
'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters?state=waiting'

Returns the session’s waiters, newest first.

Media type: application/json

{
"items": [
{
"waiter_id": "wt_Qk3xV9aLm2Tz7RfH",
"label": "Wait for unit tests",
"owner": "sess_4b7e2a9c1d6f",
"target": "sess_8c1f7d2e9a6b",
"outcomes": [
{
"name": "passed",
"when": "the unit tests pass"
},
{
"name": "failed",
"match": {
"kind": "turn_end",
"outcome": "failed"
}
}
],
"from": "turn_7d2a1c9e4b6f",
"state": "waiting",
"on_timeout": "continue",
"created_at": "2026-10-07T10:15:00Z",
"deadline_at": "2026-10-07T10:30:00Z",
"max_checks": 20,
"checks": 0,
"items_seen": 0,
"gap": false,
"cost_usd": 0,
"cost_known": true
}
]
}

GET /api/v1/agent/sessions/{id}/waiters/{waiter_id}

Section titled “GET /api/v1/agent/sessions/{id}/waiters/{waiter_id}”

Returns one waiter owned by the path session. A waiter belonging to another session, or one that is no longer retained, returns 404.

X-Hoody-Cwd and X-Hoody-Config-Dir are not read because the path session supplies both.

NameInTypeRequiredDescription
idpathstringYesThe session id.
waiter_idpathstringYesThe waiter id, such as wt_Qk3xV9aLm2Tz7RfH.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. This route does not read it because the path session supplies the working directory. The value must be UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. This route does not read it because the path session supplies the configuration directory. The value must be UTF-8.
X-Hoody-RealmheaderstringNoRealm selector: global or a 24-hex realm id. It selects the realm used to look up the session. A session in another realm or an inaccessible realm returns not_found.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. Use global or a 24-hex realm id.

This endpoint accepts no request body.

Terminal window
curl --request GET \
'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters/wt_Qk3xV9aLm2Tz7RfH'

Returns the requested waiter.

Media type: application/json

{
"waiter_id": "wt_Qk3xV9aLm2Tz7RfH",
"label": "Wait for unit tests",
"owner": "sess_4b7e2a9c1d6f",
"target": "sess_8c1f7d2e9a6b",
"outcomes": [
{
"name": "passed",
"when": "the unit tests pass"
},
{
"name": "failed",
"match": {
"kind": "turn_end",
"outcome": "failed"
}
}
],
"from": "turn_7d2a1c9e4b6f",
"state": "done",
"outcome": "failed",
"reason": "The target turn ended with status failed.",
"evidence": {
"seq": 42,
"turn_id": "turn_7d2a1c9e4b6f",
"kind": "turn_end",
"by": "match"
},
"on_timeout": "continue",
"created_at": "2026-10-07T10:15:00Z",
"deadline_at": "2026-10-07T10:30:00Z",
"ended_at": "2026-10-07T10:16:02Z",
"elapsed_ms": 62000,
"max_checks": 20,
"checks": 0,
"items_seen": 8,
"gap": false,
"cost_usd": 0,
"cost_known": true
}

Creates a waiter owned by the path session. It watches another live session of the same realm until one of the named outcomes shows in the target’s work or the deadline passes.

Exact outcomes use match and are checked on every event. Judged outcomes use when, and a model checks the sentence against the target’s tool calls, tool results and questions. The target’s own replies are not evidence. A judged result is a finding, not a proof.

The end is announced on the path session’s stream as event.waiter_done, carrying the waiter. X-Hoody-Cwd and X-Hoody-Config-Dir are not read because the path session supplies both.

NameInTypeRequiredDescription
idpathstringYesThe session id that owns the waiter.
Idempotency-KeyheaderstringNoOptional retry key, 1 to 255 printable ASCII characters. The same key and body answer the waiter it created.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. This route does not read it because the path session supplies the working directory. The value must be UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. This route does not read it because the path session supplies the configuration directory. The value must be UTF-8.
X-Hoody-RealmheaderstringNoRealm selector: global or a 24-hex realm id. It selects the realm used to look up the session. A session in another realm or an inaccessible realm returns not_found.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. Use global or a 24-hex realm id.
FieldTypeRequiredDescription
targetstringYesThe live session to watch. It must be in the same realm and cannot be the path session.
outcomesarrayYes1 to 4 outcomes. The first outcome found ends the waiter. Other outcomes found in the same check are listed in also_found.
max_sintegerNoSeconds until the deadline, 10 to 86400. Default: 600.
fromstringNoA target turn id. The target’s events are read from that turn’s start, including a turn that was sent but has not started. Without it, only events after creation are read.
max_checksintegerNoThe maximum number of model requests, 1 to 60. A retried request counts again. Default: 20. When the checks are spent, only exact outcomes and the deadline remain.
on_timeoutstringNoOptional note for the creator about what to do at the deadline: continue, stop or ask. It is kept on the waiter and is not acted on.
labelstringNoOptional label, at most 80 characters.

Each item in outcomes has these fields:

FieldTypeRequiredDescription
namestringYes1 to 32 lowercase letters, digits or _, starting with a letter. The names timeout, cancelled, target_closed, interrupted, access_lost and judge_unavailable are reserved.
whenstringNoA sentence describing one event to look for, at most 300 characters. It is judged by a model against the target’s tool calls, tool results and questions. The target’s replies are not evidence. Counting, times and and or or conditions are not judged reliably. Exactly one of when and match is required.
matchobjectNoAn exact event definition. Exactly one of when and match is required.

The match object has these fields:

FieldTypeRequiredDescription
kindstringYesThe event kind: tool_result, tool_call, gate or turn_end.
toolstringNoThe tool’s name, such as bash or write_file.
exit_codeintegerNoFor tool_result, the exit status the command must have ended with. A result with no observed exit status never matches.
is_errorbooleanNoFor tool_result, whether the tool reported an error.
text_containsstringNoCase-sensitive text that the event must contain, at most 200 characters.
outcomestringNoFor turn_end, how the turn ended: completed, failed or cancelled.
Terminal window
curl --request POST \
'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: waiter-unit-tests-001' \
--data '{
"target": "sess_8c1f7d2e9a6b",
"outcomes": [
{
"name": "passed",
"when": "the unit tests pass"
},
{
"name": "failed",
"match": {
"kind": "turn_end",
"outcome": "failed"
}
}
],
"max_s": 900,
"from": "turn_7d2a1c9e4b6f",
"max_checks": 20,
"on_timeout": "continue",
"label": "Wait for unit tests"
}'

The same Idempotency-Key and body returned the waiter created by the earlier request.

Media type: application/json

{
"waiter_id": "wt_Qk3xV9aLm2Tz7RfH",
"label": "Wait for unit tests",
"owner": "sess_4b7e2a9c1d6f",
"target": "sess_8c1f7d2e9a6b",
"outcomes": [
{
"name": "passed",
"when": "the unit tests pass"
},
{
"name": "failed",
"match": {
"kind": "turn_end",
"outcome": "failed"
}
}
],
"from": "turn_7d2a1c9e4b6f",
"state": "waiting",
"on_timeout": "continue",
"created_at": "2026-10-07T10:15:00Z",
"deadline_at": "2026-10-07T10:30:00Z",
"max_checks": 20,
"checks": 0,
"items_seen": 0,
"gap": false,
"cost_usd": 0,
"cost_known": true
}

DELETE /api/v1/agent/sessions/{id}/waiters/{waiter_id}

Section titled “DELETE /api/v1/agent/sessions/{id}/waiters/{waiter_id}”

Ends a waiting waiter with the outcome cancelled. The owner session’s stream then receives event.waiter_done. A waiter that has already ended is returned as it is.

X-Hoody-Cwd and X-Hoody-Config-Dir are not read because the path session supplies both.

NameInTypeRequiredDescription
idpathstringYesThe session id that owns the waiter.
waiter_idpathstringYesThe waiter id, such as wt_Qk3xV9aLm2Tz7RfH.
X-Hoody-CwdheaderstringNoPer-request working-directory scope. This route does not read it because the path session supplies the working directory. The value must be UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. This route does not read it because the path session supplies the configuration directory. The value must be UTF-8.
X-Hoody-RealmheaderstringNoRealm selector: global or a 24-hex realm id. It selects the realm used to look up the session. A session in another realm or an inaccessible realm returns not_found.
realmquerystringNoAlias of X-Hoody-Realm, read when the header is absent or empty. Use global or a 24-hex realm id.

This endpoint accepts no request body.

Terminal window
curl --request DELETE \
'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters/wt_Qk3xV9aLm2Tz7RfH'

Returns the ended waiter. A waiter that had already ended is returned without changing its outcome.

Media type: application/json

{
"waiter_id": "wt_Qk3xV9aLm2Tz7RfH",
"label": "Wait for unit tests",
"owner": "sess_4b7e2a9c1d6f",
"target": "sess_8c1f7d2e9a6b",
"outcomes": [
{
"name": "passed",
"when": "the unit tests pass"
},
{
"name": "failed",
"match": {
"kind": "turn_end",
"outcome": "failed"
}
}
],
"from": "turn_7d2a1c9e4b6f",
"state": "done",
"outcome": "cancelled",
"reason": "Cancelled by request.",
"on_timeout": "continue",
"created_at": "2026-10-07T10:15:00Z",
"deadline_at": "2026-10-07T10:30:00Z",
"ended_at": "2026-10-07T10:17:00Z",
"elapsed_ms": 120000,
"max_checks": 20,
"checks": 0,
"items_seen": 8,
"gap": false,
"cost_usd": 0,
"cost_known": true
}