# Agent: Session waiters **Page:** api/agent/sessions/waiters [Download Raw Markdown](./api/agent/sessions/waiters.md) --- # 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 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`. `Idempotency-Key` is optional. The same key and body on the same session answers the same waiter with `200`. The same key with another body returns `422` and creates nothing. Waiter ids use the prefix `wt_` followed by 16 base64url characters, for example `wt_Qk3xV9aLm2Tz7RfH`. ## 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 ### `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 | 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. ### Usage ```bash curl --request GET \ 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters?state=waiting' ``` ```typescript 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 Returns the session's waiters, newest first. Media type: application/json ```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 ```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 ```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 ```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 ```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 ```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 ```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 ### `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 | 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. ### Usage ```bash curl --request GET \ 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters/wt_Qk3xV9aLm2Tz7RfH' ``` ```typescript 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 Returns the requested waiter. Media type: application/json ```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 ```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 ```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 ```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 ```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 ```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 ```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 ### `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 | 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 | 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`. | Only `target`, `outcomes`, `max_s`, `from`, `max_checks`, `on_timeout` and `label` may appear in the request body. A body member other than these fields, including a scope member such as `realm` or `cwd`, is refused with `bad_request` and nothing is done. Send scope in the request headers. ### Usage ```bash 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" }' ``` ```typescript 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 The same `Idempotency-Key` and body returned the waiter created by the earlier request. Media type: application/json ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ### `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 | 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. ### Usage ```bash curl --request DELETE \ 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess_4b7e2a9c1d6f/waiters/wt_Qk3xV9aLm2Tz7RfH' ``` ```typescript 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 Returns the ended waiter. A waiter that had already ended is returned without changing its outcome. Media type: application/json ```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 ```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 ```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 ```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 ```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 ```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 ```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. |