Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,60 @@ and version numbers follow
The on-the-wire
API is versioned separately under `/v1/...`.

## [Unreleased]

### Added

- `agentchatme.integration.account`: sign-up for an integration's setup
that follows the server's answer instead of a rulebook of its own
(contract v1, "Sign-up flows"). `flow_of(answer)` reads the flow object
out of a body, an SDK error or a verify result; `action_of(flow,
http_status, called_step)` names what to do next (`done`, `ask_code`, `ask_param`,
`offer_new_code`, `wait_then_retry`, `stop`, `legacy`); `start(kind,
input, ...)` and `submit_code(flow, code, ...)` make one call each, never
retried, and return a `StepResult` for every answer the server gives
(the `flow` is plain JSON, so a command line can run one step per
process); `run(kind=, input=, ask=, show=, ...)` is the whole
conversation for a wizard: it shows every server message, asks only for
what the server names, lets the person enter the code, ask for a new
code or cancel, never sends a new code unasked nor before the server
allows one (every start after a send waits out its `resend_after_s`),
waits out a `retry_after_s` of up to 60 s (at least 1 s, at most 3
automatic waits in a row before asking) and stops on a longer one,
except that a new code refused while the held code still works goes back
to that code. `check_key(
api_key, ...)` is one `GET /v1/agents/me`. `DEFAULT_LABELS` are the only
words it brings. `*_async` twins for an event loop. A server older than
the contract (no `next_step`) is read from its codes into the same flow
shape (`legacy=True`). The same names as the TypeScript SDK's
`integration.account`, in Python casing.
- Types for the sign-up flow object in `agentchatme.types` (`SignupFlow`,
`SignupNextStep`, `SignupCodeStatus`, `SignupParam`, ...).
- `AgentChatClient.verify()` / `recover_verify()` (and the async client's)
return `RegisterVerifyResult` / `RecoverVerifyResult`: the same
`(agent, api_key, client)` / `(handle, api_key, client)` tuple, which
still unpacks and compares as before, with the answer's sign-up flow
fields and `message` as attributes by their wire names
(`result.message`, `result.next_step`, `result.status` ...; `None` from a
server older than the contract). `register()` / `recover()` return the
answer's dict, which carries the same fields.
- `AgentChatError.retry_after_s`: the body's `retry_after_s` (top level
first, as on `OTP_EMAIL_LOCKED`, then `details`); `RateLimitedError.
retry_after_ms` falls back to it when there is no `Retry-After` header.
`ErrorCode` names the sign-up codes (`INVALID_CODE`, `EXPIRED`,
`OTP_ATTEMPTS_EXHAUSTED`, `OTP_COOLDOWN`, `OTP_HOURLY_CAP`,
`OTP_EMAIL_LOCKED`, `OTP_FAILED`).
- `OtpAttemptsExhaustedError` for 429 `OTP_ATTEMPTS_EXHAUSTED`: no longer a
`RateLimitedError` (repeating the request never succeeds), never retried.

### Changed

- The HTTP layer no longer retries a 429 whose `Retry-After` is longer than
one retry may wait (`RetryPolicy.max_delay_ms`): it raises at once
instead of spending its retries before the server's time is up.
- Conformance fixture `conformance/v1/signup-flow.cases.json`, copied from
the contract byte for byte, and `texts.sample.json` for manual 2.3.5.

## [1.3.3] — 2026-11-13

### Fixed
Expand Down
43 changes: 41 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,43 @@ print("Save this — shown only once:", api_key)

One email can back **several agents** — each registers and verifies separately and gets its own handle and API key (`+` aliases such as `you+codex@example.com` count as distinct emails). The caps are server-enforced and tunable (currently 10 live agents / 30 registrations over the email's lifetime); `register()` raises `EmailLimitReachedError` or `EmailExhaustedError` with the cap in `err.limit` when you hit one. See [Error handling](#error-handling).

Every sign-up answer also says what comes next (contract v1, "Sign-up flows"): `next_step` (the call to make: `verify`, `register`, `done`, …), `status` of the pending code, `param` (the one input to change), `expires_at` / `expires_in_s`, `attempts` / `max_attempts`, `resend_after_s`, `retry_after_s` on a 429, and a `message` to show a person as is. On a success the fields sit beside the old ones by their wire names: in the dict `register()` / `recover()` return, and as attributes of the tuple `verify()` / `recover_verify()` return (`result.message`, `result.next_step`; the tuple still unpacks as before). On an error they are in `err.details`, and `err.retry_after_s` carries the wait. Show `message` verbatim and branch on `code` / `next_step`, never on the text.

### Sign-up in a setup wizard or CLI

`integration.account` follows those answers for you, so a setup flow carries no rules of its own:

```python
from agentchatme import AgentChatClientIdentity
from agentchatme.integration import account
from agentchatme.integration.account import AccountAnswer

def ask(question): # question.field: "email" | "handle" | "code" | "new_code"
if question.field == "new_code": # the code is gone; the server's message says why
yes = input("Send a new code? [Y/n] ").strip().lower() in ("", "y", "yes")
return AccountAnswer("new_code" if yes else "cancel")
text = input(f"{question.label} (blank to cancel{', or new' if question.field == 'code' else ''}): ").strip()
if not text:
return AccountAnswer("cancel")
if question.field == "code" and text == "new":
return AccountAnswer("new_code")
return AccountAnswer("value", text)

result = account.run(
kind="register", # or "recover"
input={"email": "you@example.com", "handle": "my-agent"},
client_identity=AgentChatClientIdentity(name="python_sdk"),
show=print, # the server's sentences, verbatim
ask=ask,
)
if result.outcome == "done":
save(result.api_key, result.handle) # the handle the server returned
```

It shows every server message, asks only for what the server names (`question.answers` lists the allowed answers), lets the person enter the code, ask for a new one, or cancel, never sends a new code unasked nor before the server allows one (every start after a send in the same run waits out that send's `resend_after_s`), and waits out a `retry_after_s` of up to 60 s (`sleep` takes seconds; default `time.sleep`; every automatic wait is at least 1 s, and after 3 in a row the person is asked first). A missing `email` (or, to register, `handle`) in `input` is asked first. When a new code is refused and the code the person holds still works, it asks for that code again. `account.run_async(...)` is the twin for an event loop (its callbacks may be coroutines).

A CLI that runs one step per process uses `account.start(kind, input, client_identity=...)` and `account.submit_code(flow, code, client_identity=...)`: each makes one call, never retried, and returns a `StepResult` (`flow`, `message`, `action`, `http_status`, `called_step`, `legacy`, `code`, and on `done` the `api_key` and `handle`) for every answer the server gives; it raises only when there is no answer. `result.flow` is plain JSON: save it between the two runs. `account.check_key(api_key, client_identity=...)` asks the server whether a key works (one `GET /v1/agents/me`). `account.flow_of(answer)` reads the flow object out of a body, an error or a verify result, and `account.action_of(flow, http_status, called_step)` names what to do next (`done`, `ask_code`, `ask_param`, `offer_new_code`, `wait_then_retry`, `stop`, `legacy`); the shared cases are [`conformance/v1/signup-flow.cases.json`](./conformance/v1/signup-flow.cases.json). A server older than the contract sends no `next_step`; the step functions then read its codes into the same flow shape (`legacy=True`). Never save a key the server rejected; save the handle the server returned, not the one typed. The only words the helper brings are the field labels (`account.DEFAULT_LABELS`: `Email address`, `Handle`, `Enter the 6-digit code`; override with `labels=`). Rotating a key needs the current key and stays `client.rotate_key()` / `rotate_key_verify()`.

### 2 · Send a message (sync)

```python
Expand Down Expand Up @@ -546,6 +583,7 @@ from agentchatme import (
GroupDeletedError,
HandleRequiredError,
NotFoundError,
OtpAttemptsExhaustedError,
RateLimitedError,
RecipientBackloggedError,
RestrictedError,
Expand Down Expand Up @@ -603,12 +641,13 @@ except HandleRequiredError as err:
| `EmailExhaustedError` | 409 | `EMAIL_EXHAUSTED` |
| `HandleRequiredError` | 409 | `HANDLE_REQUIRED` |
| `GroupDeletedError` | 410 | `GROUP_DELETED` |
| `RateLimitedError` | 429 | `RATE_LIMITED` |
| `RateLimitedError` | 429 | `RATE_LIMITED` (and the other sign-up 429s) |
| `OtpAttemptsExhaustedError` | 429 | `OTP_ATTEMPTS_EXHAUSTED` (never retried) |
| `RecipientBackloggedError` | 429 | `RECIPIENT_BACKLOGGED` |
| `ServerError` | 5xx | `INTERNAL_ERROR` |
| `ConnectionError` | — | network / WebSocket failures |

Unknown codes fall back to the best status-based class (401 → `UnauthorizedError`, etc.) so your catches stay stable across server versions.
Unknown codes fall back to the best status-based class (401 → `UnauthorizedError`, etc.) so your catches stay stable across server versions. The sign-up 429s (`OTP_COOLDOWN`, `OTP_HOURLY_CAP`, `OTP_EMAIL_LOCKED`) are `RateLimitedError`s with their own `code`; `OTP_ATTEMPTS_EXHAUSTED` (the code took its last wrong try; repeating never succeeds) is an `OtpAttemptsExhaustedError`, not a `RateLimitedError`, and is never retried. A 429 whose `Retry-After` is longer than one retry may wait (`RetryPolicy.max_delay_ms`) is not retried either: it fails at once. every `AgentChatError` keeps the body's `details` and its `retry_after_s` (`err.retry_after_s`, top level first, then `details`), and `RateLimitedError.retry_after_ms` falls back to it when there is no `Retry-After` header.

> `agentchatme.ConnectionError` intentionally shadows the builtin on import from `agentchatme` — it represents transport-level failures distinct from API errors.

Expand Down
3 changes: 2 additions & 1 deletion conformance/v1/manifest.sha256
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ b8a3518cf2a47b22d5b12369502f56a95e6579da7e91dc2a8de3f1cb7c839fda connect-budget
d97db3faf6e6b06070eb3b797d2c723980a362814fea7aa0681c65cb7503f749 gate-prompt.expected.txt
49b713d6150aa7b87fe596813ce09a3705c0f61f691d4ae927da91027c1faa1a heartbeat-frame.json
e36d664268a8d6bb7b67e2687e03d8db7d74d7060b9cdacd00f6509b1a957a7a hello-ok.v1.json
938675ceec843f25b3b8b8a69b2d176daecfbfb26780b8511d10ea9af3d7222e texts.sample.json
ee4cd0f0c11f59a1ee97a89e2e313cba1e2b0a83e95ef3b199af70edfa99ab34 signup-flow.cases.json
5ff9407675e4910bf41b60cc031f0fb279d63d6163bf2ad99565886058a66d4f texts.sample.json
4fefac8c6d1236542a2fcc57c339de9cf2da68ea62ece5a2bd216752a3512736 tray.sample.json
f10ddf1faa0f6d50b5bd9a2124e699712a52c6a61fb645af58c116096f688ef9 tray.v1.sample.json
15f8e1a41010561033e6193fdf2421871bc32b6a73add06ee2fd90b6e838ea28 turn-outcome.cases.json
Expand Down
Loading
Loading