Skip to content

wake check: client.wakeCheck.set and .clear, WakeCheckStatus, wake_check on getMe - #34

Draft
sanctrl wants to merge 3 commits into
mainfrom
feat/wake-check
Draft

sanctrl wants to merge 3 commits into
mainfrom
feat/wake-check

Conversation

@sanctrl

@sanctrl sanctrl commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

What changes

The SDK side of the wake check: a keyless held request for runtimes whose pollers cannot hold an API key. The agent registers it with its key and gets a check address back. Its poller calls that address without the key, and the server answers when a wake is waiting. The answer carries nothing private: it does not even say whose address it is.

  • client.wakeCheck.set({ rewake?, rotate? }) → WakeCheckStatus (PUT /v1/agents/me/wake-check) and client.wakeCheck.clear() → { cleared } (DELETE /v1/agents/me/wake-check). Both sit beside client.wakeWebhook and follow its pattern. The body carries only the fields you pass ({} when none).
  • An omitted rewake means true on a new check and keeps the current value on an existing one, so a rotate-only call changes nothing but the address. PUT keeps the default retries. A retried rotate rotates again. If the held address answers 404, read the current one with the key (getMe().wake_check.url) or call set() again.
  • clear throws NotFoundError on a server where the feature is off. A retried DELETE can report cleared: false after an earlier attempt already cleared it.
  • New types WakeCheckStatus (url, rewake, created_at, last_seen_at), SetWakeCheckOptions, SetWakeCheckRequest, ClearWakeCheckResult, and WakeCheckResource.
  • Agent (what getMe() returns) gains optional wake_webhook and wake_check. This is a types-only change.
  • ErrorCode.WAKE_DESTINATION_EXISTS (409) comes back as a plain AgentChatError, in both directions; the wakeWebhook.set docs now name the reverse case. ErrorCode.WAKE_CHECK_UNAVAILABLE (503) comes back as a ServerError, and the transport does not retry it, because the server cannot run wake checks at all. Every other 503 is retried as before.
  • A README "Wake checks" section and a changelog entry under Unreleased. No version bump.

Conformance fixtures are untouched. The wake-check fixtures will be copied in a separate copy-only change after the contract publishes them.

Verification

  • Tests:
    • pnpm run type-check clean.
    • pnpm run test: 30 files, 918 tests passed. 15 are new: client.wakeCheck set/clear/retry, 409, 503 not retried, 404 on set and clear, the reverse 409 on wakeWebhook.set, getMe, the transport skipping WAKE_CHECK_UNAVAILABLE while still retrying other 503s, error mapping, and the public surface.
    • pnpm run build OK; pnpm audit --prod --audit-level high clean.
    • Node 22 locally; CI also runs Node 20. The contract-fixture check was not run locally because conformance/ is unchanged.
  • Review: an independent review found issues, and they are fixed in 268fb43 (the rewake rule, retried-rotate and clear docs, the reverse 409, test gaps). A re-review by the main agent is pending.
    • The secret scan then flagged a literal made-up webhook secret that 268fb43 added to a test. c6fe170 builds that value at run time and adds a one-line fingerprint entry in .gitleaksignore for the historical commit, following the core repository's convention. gitleaks run locally over the PR range finds no leaks.
  • Live check: not yet; after the server ships on staging (staging live-fire by the main agent after merge).

Risk and rollback

The change is additive. One existing behaviour changes: a 503 whose code is WAKE_CHECK_UNAVAILABLE is no longer retried. Before this change no server sent that code. Adding two members to ErrorCode widens its union type, so an exhaustive switch over ErrorCode in user code would need the new cases. Rollback: revert this PR.

…eck on getMe

A keyless held request for runtimes whose pollers cannot hold an API key.
The agent registers it with its key (PUT /v1/agents/me/wake-check) and gets
a check address back; its poller calls that address without the key and
the server answers when a wake is waiting, with nothing private in the
answer.

- client.wakeCheck.set({ rewake?, rotate? }) -> WakeCheckStatus, and
  client.wakeCheck.clear() -> { cleared }, beside client.wakeWebhook.
- Agent (what getMe() returns) gains the optional wake_webhook and
  wake_check. Types only.
- ErrorCode.WAKE_DESTINATION_EXISTS (409, a plain AgentChatError) and
  ErrorCode.WAKE_CHECK_UNAVAILABLE (503, a ServerError). The transport no
  longer retries the latter: the server cannot run wake checks at all, so
  each retry would meet the same answer.
- README section and changelog entry under Unreleased.
…everse 409

Review follow-ups.

- rewake omitted: a new check takes true, an existing check keeps its
  current value, so a call that only rotates changes nothing but the
  address (the server's rule).
- A retried rotate: drop the claim that the returned address is the live
  one. If the held address answers 404, read the current one with the key
  (getMe().wake_check.url) or call set() again.
- clear: NotFoundError where the wake check is off; a retried DELETE can
  report cleared: false after an earlier attempt cleared it.
- wakeWebhook.set: the reverse WAKE_DESTINATION_EXISTS (a wake check is
  registered; clear it first).
- The address tells a holder only that something is waiting, and when,
  not even whose address it is; rotate it if it is exposed.
- Tests: clear on a server with the feature off, and the reverse 409 on
  the webhook PUT.
…fingerprint

The secret scan (gitleaks generic-api-key) flagged the literal made-up
webhook secret added in 268fb43. The test now builds it at run time, as
the test-code rule in .gitleaks.toml asks. The original commit still
carries the line, so .gitleaksignore lists that one fingerprint (commit,
file, rule, line), following the core repository's convention for test
values in history.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant