Agent: Session waiters
Section titled “Agent: Session waiters”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.
Waiter behavior
Section titled “Waiter behavior”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_sseconds 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.
Response fields
Section titled “Response fields”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.
| Field | Type | Required | Description |
|---|---|---|---|
items | array | Yes, list response only | The session’s waiters, newest first. |
waiter_id | string | Yes | The waiter’s id. It starts with wt_ and contains 16 base64url characters. |
label | string | No | The label the waiter was created with. |
owner | string | Yes | The session that waits, which is the path session. |
target | string | Yes | The session that is watched. |
outcomes | array | Yes | The outcomes the waiter looks for. |
outcomes[].name | string | Yes | The 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[].when | string | No | A judged event description of at most 300 characters. Give exactly one of when and match. |
outcomes[].match | object | No | An exact event definition. Give exactly one of when and match. |
outcomes[].match.kind | string | Yes, when match is present | The event kind: tool_result, tool_call, gate or turn_end. |
outcomes[].match.tool | string | No | The tool’s name, such as bash or write_file. |
outcomes[].match.exit_code | integer | No | The exit status required for a tool_result. |
outcomes[].match.is_error | boolean | No | The error flag required for a tool_result. |
outcomes[].match.text_contains | string | No | Case-sensitive text that the event must contain, at most 200 characters. |
outcomes[].match.outcome | string | No | The required turn_end outcome: completed, failed or cancelled. |
from | string | No | The target turn from which events are read, when one was given. |
state | string | Yes | waiting or done. |
outcome | string | No | The outcome found, or timeout, cancelled, target_closed, interrupted, access_lost or judge_unavailable. |
reason | string | No | A sentence explaining why the waiter ended. |
also_found | array | No | Other outcomes found in the same check, in the order they were given. |
evidence | object | No | The event in which the outcome was found. |
evidence.seq | integer | Yes, when evidence is present | The event’s number in the target’s event list. |
evidence.turn_id | string | No | The target turn containing the event. |
evidence.kind | string | Yes, when evidence is present | The event kind: tool_result, tool_call, gate or turn_end. |
evidence.tool | string | No | The tool’s name. |
evidence.exit_code | integer | No | The command’s observed exit status. |
evidence.is_error | boolean | No | Whether the tool reported an error. |
evidence.excerpt | string | No | The beginning of the event text, with secrets removed. |
evidence.by | string | Yes, when evidence is present | match for an exact outcome or judge for a model finding. A judged finding points at an event but does not prove the outcome. |
evidence.p | number | No | The model’s probability that the events show a judged outcome. |
on_timeout | string | No | The creator’s timeout instruction: continue, stop or ask. The agent keeps it for the creator’s use and does not act on it. |
created_at | string | Yes | The RFC3339 creation time. |
deadline_at | string | Yes | The RFC3339 deadline. |
ended_at | string | No | The RFC3339 end time when the waiter is done. |
elapsed_ms | integer | No | The milliseconds from creation to the end. |
max_checks | integer | Yes | The maximum number of model requests. A retried request counts again. |
checks | integer | Yes | The number of model requests made, including retries. |
items_seen | integer | Yes | The number of target events read. |
gap | boolean | No | Whether some target events may not have been read. |
cost_usd | number | Yes | What the model checks cost in US dollars. |
cost_known | boolean | Yes | Whether the price of every check was reported. |
model | string | No | The model used to check judged outcomes. |
Error responses use the following envelope:
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The stable machine-readable error code. |
message | string | Yes | The human-readable error message. |
details | object | No | Structured details for error codes that carry them. |
List a session’s waiters
Section titled “List a session’s waiters”GET /api/v1/agent/sessions/{id}/waiters
Section titled “GET /api/v1/agent/sessions/{id}/waiters”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
state | query | string | No | Only waiters in this state: waiting or done. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Realm 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. |
realm | query | string | No | Alias 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.
curl --request GET \ 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters?state=waiting'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const waiters = await client.agent.sessions.waiters.list('sess_4b7e2a9c1d6f', { state: 'waiting'});Responses
Section titled “Responses”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 } ]}The request was malformed or carried invalid parameters.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global or a 24-hex id. | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The requested session or resource was not found.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The per-client request rate limit was exceeded.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The agent cannot yet determine which realms the current login may serve.
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
Get a waiter
Section titled “Get a waiter”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
waiter_id | path | string | Yes | The waiter id, such as wt_Qk3xV9aLm2Tz7RfH. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Realm 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. |
realm | query | string | No | Alias 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.
curl --request GET \ 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters/wt_Qk3xV9aLm2Tz7RfH'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const waiter = await client.agent.sessions.waiters.get( 'sess_4b7e2a9c1d6f', 'wt_Qk3xV9aLm2Tz7RfH');Responses
Section titled “Responses”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}The request was malformed or carried invalid parameters.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global or a 24-hex id. | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The waiter does not exist, belongs to another session, or is no longer retained. An unknown session also returns 404.
Media type: application/json
{ "code": "not_found", "message": "waiter not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The waiter does not exist, belongs to another session, or is no longer kept. An unknown session is 404 too. | List the session’s waiters to find a retained one. |
The per-client request rate limit was exceeded.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The agent cannot yet determine which realms the current login may serve.
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
Create a waiter
Section titled “Create a waiter”POST /api/v1/agent/sessions/{id}/waiters
Section titled “POST /api/v1/agent/sessions/{id}/waiters”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id that owns the waiter. |
Idempotency-Key | header | string | No | Optional retry key, 1 to 255 printable ASCII characters. The same key and body answer the waiter it created. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Realm 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. |
realm | query | string | No | Alias of X-Hoody-Realm, read when the header is absent or empty. Use global or a 24-hex realm id. |
Request Body
Section titled “Request Body”| Field | Type | Required | Description |
|---|---|---|---|
target | string | Yes | The live session to watch. It must be in the same realm and cannot be the path session. |
outcomes | array | Yes | 1 to 4 outcomes. The first outcome found ends the waiter. Other outcomes found in the same check are listed in also_found. |
max_s | integer | No | Seconds until the deadline, 10 to 86400. Default: 600. |
from | string | No | A 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_checks | integer | No | The 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_timeout | string | No | Optional 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. |
label | string | No | Optional label, at most 80 characters. |
Each item in outcomes has these fields:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 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. |
when | string | No | A 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. |
match | object | No | An exact event definition. Exactly one of when and match is required. |
The match object has these fields:
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | Yes | The event kind: tool_result, tool_call, gate or turn_end. |
tool | string | No | The tool’s name, such as bash or write_file. |
exit_code | integer | No | For tool_result, the exit status the command must have ended with. A result with no observed exit status never matches. |
is_error | boolean | No | For tool_result, whether the tool reported an error. |
text_contains | string | No | Case-sensitive text that the event must contain, at most 200 characters. |
outcome | string | No | For turn_end, how the turn ended: completed, failed or cancelled. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const waiter = await client.agent.sessions.waiters.create( 'sess_4b7e2a9c1d6f', { 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' }, { idempotencyKey: 'waiter-unit-tests-001' });Responses
Section titled “Responses”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}The waiter was created and is waiting.
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}The request was malformed, carried invalid parameters or contained an unknown body field.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
bad_request | Unknown body field | The body carries a member other than target, outcomes, max_s, from, max_checks, on_timeout and label, including a scope member such as realm or cwd, and nothing was done. | Remove the member; send the scope in the request headers. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global or a 24-hex id. | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The owner session or target session was not found.
Media type: application/json
{ "code": "target_not_found", "message": "the session to watch was not found or is not live"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
target_not_found | Target not found | The session to watch does not exist, is not live, or is in another realm. | Name a live session of the same realm. |
The target session cannot be watched.
Media type: application/json
{ "code": "waiter_unsupported", "message": "a Claude Code session cannot be watched unless the daemon runs its tools: its tool results are not reported as events"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
waiter_unsupported | Session cannot be watched | The target is a headless run, an internal session, or a Claude Code session that runs its own tools rather than Hoody’s, whose tool results are not reported as events. | Watch a session that runs a Hoody model, or a Claude Code session that uses Hoody’s tools. |
The request body exceeds the configured size limit.
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured size limit, which defaults to 8 MiB. | Reduce the request body below the configured limit; split a large payload into smaller requests. |
The waiter is invalid, or the idempotency key was reused for another waiter.
Media type: application/json
{ "code": "waiter_invalid", "message": "outcome \"done\" needs exactly one of when (a sentence to judge) or match (an exact event)"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
waiter_invalid | Waiter invalid | The request is well formed but cannot be a waiter: no outcome, a reserved or repeated name, an outcome with both or neither of when and match, a duration outside 10 to 86400 seconds, a from turn the target does not have, or the path session as its own target. | Fix the field the message names. |
idempotency_key_reused | Idempotency key reused | This session already used the Idempotency-Key for a different waiter. Nothing was created. | Use a new key, or resend the identical request to get the waiter it created. |
Too many waiters are waiting, or the request rate limit was exceeded.
Media type: application/json
{ "code": "waiters_exhausted", "message": "too many waiters are waiting (at most 8 per session, 64 in all); cancel one or wait for one to end"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
waiters_exhausted | Too many waiters | The session already has 8 waiters waiting, or the agent has 64. | Cancel a waiter or wait for one to end. |
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The waiter was not saved, or the agent cannot yet determine which realms the current login may serve.
Media type: application/json
{ "code": "admission_write_failed", "message": "the waiter could not be saved, so nothing is waiting; retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
admission_write_failed | Waiter not saved | The agent could not save the waiter, so nothing is waiting. | Retry with the same Idempotency-Key. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
Cancel a waiter
Section titled “Cancel a waiter”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id that owns the waiter. |
waiter_id | path | string | Yes | The waiter id, such as wt_Qk3xV9aLm2Tz7RfH. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Realm 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. |
realm | query | string | No | Alias 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.
curl --request DELETE \ 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters/wt_Qk3xV9aLm2Tz7RfH'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const waiter = await client.agent.sessions.waiters.cancel( 'sess_4b7e2a9c1d6f', 'wt_Qk3xV9aLm2Tz7RfH');Responses
Section titled “Responses”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}The request was malformed or carried invalid parameters.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header. A route without a realm dimension refuses every realm header, the pinned realm included; on a route that takes a realm, an agent pinned to one realm accepts only that realm. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global or a 24-hex id. | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The waiter does not exist, belongs to another session, or is no longer retained. An unknown session also returns 404.
Media type: application/json
{ "code": "not_found", "message": "waiter not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The waiter does not exist, belongs to another session, or is no longer kept. An unknown session is 404 too. | List the session’s waiters to find a retained one. |
The per-client request rate limit was exceeded.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The agent cannot yet determine which realms the current login may serve.
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |