Skip to content

integration.account: the sign-up helper on the server's next step - #27

Merged
sanctrl merged 10 commits into
mainfrom
feat/signup-next-step
Nov 17, 2026
Merged

sanctrl merged 10 commits into
mainfrom
feat/signup-next-step

Conversation

@sanctrl

@sanctrl sanctrl commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

What changes

A sign-up helper for setup wizards and agents, built on the server's new sign-up answers (contract v1 §3.7: every register / recover / rotate-key answer now says the next step).

  • integration.account: flowOf / actionOf (read an answer and decide the client action by the contract's rule), start / submitCode (one step per call, usable across process runs), run (the whole conversation: ask the person, show the server's sentence, follow next_step), checkKey (validate a pasted key). The person can enter a code, ask for a new code, or cancel; a new code is never sent unasked; waits respect the server (retry_after_s, resend_after_s) with a 1 s floor and at most 3 automatic waits in a row; a refused new-code request goes back to the code the person already holds while it is valid. Older servers are read into the same shape (legacy).
  • Results and errors: register / verify / recover / recover_verify results carry the server's flow fields; every error gains retry_after_s; OTP_ATTEMPTS_EXHAUSTED is its own non-retryable error class; the HTTP layer no longer retries a 429 whose Retry-After is longer than its per-try cap.
  • Conformance: conformance/v1/ copied byte-identical from the published contract (53 sign-up cases, manual 2.3.5 texts), matching https://agentchat.me/contract/v1/conformance/manifest.sha256.
  • Additive: no existing API changes shape.

Verification

  • Tests: see the CI run; locally the full suite, type-check, lint and build pass, with every one of the 53 contract cases driven through the helper and scripted conversations (wrong code then right, new code, cancel, waits, held code, recover cooldown, legacy server) on fake time with no network.
  • Review: independent review of the helper as a state machine and of backward compatibility; its findings (recover cooldown, waits before every restart, retry floor, clock skew, held code on any refusal) are fixed on this branch; the TypeScript and Python helpers are kept identical modulo language.
  • Live check: the server side is deployed (sign-up answers verified on production: malformed email → VALIDATION_ERROR with param: email, unknown pending id → EXPIRED with next_step: register, malformed code → param: code); the helper itself is checked end to end in the product lab after release.

Risk and rollback

New module and additive fields only. The one behaviour change for existing callers: a 429 with a long Retry-After now fails at once instead of after several capped retries. Rollback: revert, or stay on the previous release.

…y_after_s on errors, integration.account helper
… fields on verify results by wire name; signup-flow.cases.json conformance
…y, flow fields on client results; amended signup-flow.cases.json; an older server's 429 that names no wait stops
…t after a send, at least 1 s, at most 3 in a row; any 429 on a new code goes back to the held code; OtpAttemptsExhaustedError; no retry of a 429 longer than the per-try cap
…fest.sha256 from the contract (review fixes)
…n and manifest.sha256 from the contract (refined action rule)
@sanctrl
sanctrl enabled auto-merge (squash) November 17, 2026 15:33
@sanctrl
sanctrl merged commit 2894c22 into main Nov 17, 2026
12 checks passed
@sanctrl
sanctrl deleted the feat/signup-next-step branch November 17, 2026 15:35
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