Agent: Change tokens
Section titled “Agent: Change tokens”The change-token endpoints expose one opaque token for each visible Work list: sessions, todos, workflow_runs, loops, tasks, gates, agents, rules, and memory. Use them to poll or stream changes and re-list only the topics whose token moved, rather than re-listing every topic on every tick.
These endpoints are exposed by a computer’s agent service. Access to a computer’s agent routes is governed by that computer’s proxy permission rules.
Tokens are opaque. Compare them for equality, never parse or order them. The scope value is also opaque and uses 16 hexadecimal characters. Compare scope for equality and re-list every topic when it changes. Tokens are computed from what the caller can see, so work in another realm or of another account never moves a token. Tokens are hints, and the Work lists remain authoritative.
The client loop
Section titled “The client loop”The recommended pattern is:
- Read the tokens with one call to
GET /api/v1/agent/changes, or open the SSE stream. - List the topics you care about using their list endpoints.
- Re-read the tokens later.
- Re-list only the topics whose token moved since step 1. A missing or null token also requires re-listing that topic.
- When
scopechanges between reads, re-list every topic because the tokens belong to a different realm and account than the previous answer.
The JSON read is request-driven: each call returns the tokens as they stand at that moment. One read is shared for 1 s by requests with the same realm and scope headers, so an answer can be up to 1 s old. After the active realm or account switches, the new scope arrives within that second. The SSE stream is the one that re-reads tokens every 2 s, and one read per scope per second is shared by every stream.
GET /api/v1/agent/changes
Section titled “GET /api/v1/agent/changes”Returns {scope, tokens} with one opaque token per topic. Read the response, then list the topics you care about. Later, re-read and re-list only the topics whose token moved, and every topic when scope changes.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Cwd | header | string | No | Per-request working-directory scope: the .hoody project layer, record cwd, or tool and workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request. |
X-Hoody-Realm | header | string | No | Per-request realm selector: global (not tied to a realm) or a 24-hex realm id. The realm query parameter is an alternative. On a session route, it names the realm in which the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. A different realm for an agent pinned to one realm returns 400 realm_scope_unsupported. |
realm | query | string | No | Per-request realm selector and the query alias of X-Hoody-Realm. It is read when the header is absent or empty. The value must be global or a 24-hex realm id. On a session route, it names the realm in which the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. A different realm for an agent pinned to one realm returns 400 realm_scope_unsupported. |
This endpoint accepts no request body.
Response
Section titled “Response”JSON error responses contain code and message, with optional structured details.
Media type: application/json
The change tokens.
{ "scope": "3f9a1c0b7d2e4a65", "tokens": { "sessions": "tok_s_a1b2c3d4e5f6", "todos": "tok_t_b2c3d4e5f6a7", "workflow_runs": "tok_w_c3d4e5f6a7b8", "loops": "tok_l_d4e5f6a7b8c9", "tasks": "tok_k_e5f6a7b8c9d0", "gates": "tok_g_f6a7b8c9d0e1", "agents": "tok_a_a7b8c9d0e1f2", "rules": "tok_r_b8c9d0e1f2a3", "memory": "tok_m_c9d0e1f2a3b4" }}| Field | Type | Description |
|---|---|---|
scope | string, required | Opaque 16-hex-character value naming the realm and account the tokens belong to. It never carries the account itself. Compare it for equality, and re-list every topic when it changes. |
tokens | object, required | Contains one opaque token per readable topic. Compare a token with the one you last saw, and re-list that topic when it differs. Never parse a token. |
tokens.sessions | string | Moves when a visible session is created, closed, renamed, or re-persisted, such as for a model, agent, or cost change. It also moves when the session attaches or detaches, a turn starts, parks on a gate, or ends, a gate starts or stops waiting for a person, or a listSessions row changes because this agent holds or releases the session’s turn slot or closes it. Re-list with listSessions. |
tokens.todos | string | Moves on any change to a visible todo. Re-list with listTodos, and use getTodo for an open todo. |
tokens.workflow_runs | string | Moves when a visible run starts, steps, finishes, is cancelled, or is evicted. Re-list with listWorkflowRuns, and use getWorkflowRun for one run. |
tokens.loops | string | Moves when a visible loop is created, deleted, paused, resumed, fires, finishes, or spends. Countdowns such as next_in_ms and expires_in_ms do not move it. Re-list with listAllLoops. |
tokens.tasks | string | Moves when a helper task of a visible live session starts, makes progress, or ends. Re-list with listTasks for the sessions you show. |
tokens.gates | string | Moves when a gate of a visible live session parks or resolves, including the session’s own confirmation or question and each helper’s gate on a helper_gates session. Re-list with listPendingGates, or use getSessionState for one session’s pending_gate and pending_helper_gates. |
tokens.agents | string | Moves when the realm’s agent list changes, such as after a create, delete, rename, model, tools, turns, or source edit. Re-list with listAgents. |
tokens.rules | string | Moves when a rules layer of a visible live session changes, such as through setHookRules. It also moves when a settings file read by getHookRules changes for the same scope headers, with or without a live session. Re-list with getHookRules, listHooks, or getSessionRulesApplies. |
tokens.memory | string | Moves when the realm’s memory changes, such as after a memory is saved, edited, or deleted, an observation is captured, a project is erased, a consolidation pass is queued, started, or ended, or memory is switched on or off. While the store cannot be reached or memory reads are refused, the token holds until that changes. Re-read with getMemoryStatus, listMemoryProjects, or listMemoryItems. |
unavailable | object | Present only when a topic could not be read. Maps each topic name to its reason. That topic has no token in this answer and must be re-listed. |
Media type: application/json
The request was malformed, a computer header was sent, a realm outside the agent’s pinned realm was requested, or the realm selector was invalid.
{ "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, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "", global, or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
{ "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 …. |
Media type: application/json
The requested realm is not served by this login, or the requested resource does not exist.
{ "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. |
Media type: application/json
The per-client request rate limit was exceeded.
{ "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, so the gateway throttled the request before dispatch. | Honor the Retry-After header and retry, and reduce the request rate. |
Media type: application/json
An unexpected error occurred while handling the request.
{ "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 the error persists, inspect the daemon logs. |
Media type: application/json
The agent cannot yet determine which realms the login may serve, so it refuses realm-scoped requests.
{ "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. GET /api/v1/agent/hoody/auth/status reports restriction "unknown", so the agent refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.changes.get();
await client.agent.changes.get({ cwd: '/home/user/project', configDir: '/home/user/project/.hoody', agentRealm: 'global',});curl -sS "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/changes"With a realm selector and a working-directory scope:
curl -sS "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/changes?realm=67e89abc123def456789abcd" \ -H "X-Hoody-Cwd: /home/user/project"GET /api/v1/agent/changes/stream
Section titled “GET /api/v1/agent/changes/stream”Streams change tokens as Server-Sent Events over getChanges. The stream starts with retry: 5000. Its first event frame is a snapshot carrying {scope, tokens}. After it, a changed frame carrying {topic, token} is sent for each topic whose token moved, and a new snapshot is sent when scope changes.
The stream re-reads tokens every 2 s, and one read per scope per second is shared by every stream.
There are no id: lines. After a reconnect, start again from the new snapshot and re-list the topics that differ from what you hold. Heartbeat comments are sent every 25 s as bare : comment lines. An end frame carrying {reason} closes the stream when the tokens cannot be read, with the reason set to changes unavailable.
The stream counts toward the per-IP stream cap (--http-max-streams-per-ip, default 16). A Frame tab holds this stream, the focused session’s /stream, and a prompt:stream while sending.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Cwd | header | string | No | Per-request working-directory scope: the .hoody project layer, record cwd, or tool and workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request. |
X-Hoody-Realm | header | string | No | Per-request realm selector: global (not tied to a realm) or a 24-hex realm id. The realm query parameter is an alternative. On a session route, it names the realm in which the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. A different realm for an agent pinned to one realm returns 400 realm_scope_unsupported. |
realm | query | string | No | Per-request realm selector and the query alias of X-Hoody-Realm. It is read when the header is absent or empty. The value must be global or a 24-hex realm id. On a session route, it names the realm in which the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. A different realm for an agent pinned to one realm returns 400 realm_scope_unsupported. |
This endpoint accepts no request body.
Response
Section titled “Response”JSON error responses contain code and message, with optional structured details.
Media type: text/event-stream
The body is a sequence of SSE frames separated by blank lines.
retry: 5000
event: snapshotdata: {"scope":"3f9a1c0b7d2e4a65","tokens":{"sessions":"tok_s_a1b2c3d4e5f6","todos":"tok_t_b2c3d4e5f6a7","workflow_runs":"tok_w_c3d4e5f6a7b8","loops":"tok_l_d4e5f6a7b8c9","tasks":"tok_k_e5f6a7b8c9d0","gates":"tok_g_f6a7b8c9d0e1","agents":"tok_a_a7b8c9d0e1f2","rules":"tok_r_b8c9d0e1f2a3","memory":"tok_m_c9d0e1f2a3b4"}}
:
event: changeddata: {"topic":"sessions","token":"tok_s_b3c4d5e6f7a8"}
:
event: changeddata: {"topic":"memory","token":null}
event: snapshotdata: {"scope":"6b4d2e8a1f0c7d93","tokens":{"sessions":"tok_s_c4d5e6f7a8b9","todos":"tok_t_d5e6f7a8b9c0","workflow_runs":"tok_w_e6f7a8b9c0d1","loops":"tok_l_f7a8b9c0d1e2","tasks":"tok_k_a8b9c0d1e2f3","gates":"tok_g_b9c0d1e2f3a4","agents":"tok_a_c0d1e2f3a4b5","rules":"tok_r_d1e2f3a4b5c6"},"unavailable":{"memory":"memory store unavailable"}}
:
event: changeddata: {"topic":"gates","token":"tok_g_e3f4a5b6c7d8"}
event: enddata: {"reason":"changes unavailable"}| Frame | When | Payload |
|---|---|---|
retry | Before the first event frame | retry: 5000. |
snapshot | First frame after connect, and on every scope change | {scope, tokens}, with the same token shape as the JSON read. It may also contain an unavailable map naming each topic that could not be read and its reason. A topic named in unavailable has no token in that snapshot and must be re-listed. Re-list topics whose token differs from what you hold, and re-list every topic if scope changed. |
changed | For each topic whose token moved | {topic, token}. The token is null when the topic becomes unreadable. Re-list the topic when its token changes, and re-list it whenever its token is missing or null. |
| Heartbeat comment | Every 25 s | A bare : comment line. Ignore it. |
end | When the tokens cannot be read | {reason} with reason set to changes unavailable. The stream closes. |
Media type: application/json
The request was malformed, a computer header was sent, a realm outside the agent’s pinned realm was requested, or the realm selector was invalid.
{ "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, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed. It must be "", global, or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
{ "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 …. |
Media type: application/json
The requested realm is not served by this login, or the requested resource does not exist.
{ "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. |
Media type: application/json
The per-client request rate limit was exceeded.
{ "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, so the gateway throttled the request before dispatch. | Honor the Retry-After header and retry, and reduce the request rate. |
Media type: application/json
An unexpected error occurred while handling the request.
{ "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 the error persists, inspect the daemon logs. |
Media type: application/json
The daemon could not service the stream, or it could not determine the login’s realm restriction.
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve. GET /api/v1/agent/hoody/auth/status reports restriction "unknown", so the agent refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.changes.stream();
await client.agent.changes.stream({ cwd: '/home/user/project', configDir: '/home/user/project/.hoody', agentRealm: 'global',});curl -N "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/changes/stream"With a realm selector and a working-directory scope:
curl -N "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/changes/stream?realm=67e89abc123def456789abcd" \ -H "X-Hoody-Cwd: /home/user/project"