mirror of
https://github.com/wu736139669/hapi.git
synced 2026-11-22 04:17:05 +00:00
docs: align documentation with current implementation
This commit is contained in:
@@ -140,7 +140,7 @@ Lifecycle:
|
||||
2. On POST success: status → `queued` if the session is currently thinking, else `sent`. On failure: drop the row and restore the composer (or keep it as `failed` with a retry affordance when attachments are involved).
|
||||
3. **Echo**: the hub emits `message-received` carrying the stored row (server `id`, real `seq`, same `localId`). Merging a stored row whose `localId` matches an optimistic row **replaces** the optimistic one, preserving the client-side `status` and any already-known `invokedAt` the server row lacks. Fallback when no `localId` echo matches: drop an optimistic `sent` row when a server user message lands within **10 s** of the same position.
|
||||
4. **`messages-consumed {localIds, invokedAt}`** (SSE): stamp `invokedAt` and flip status to `sent` on matching rows (skip `failed` ones). This is what moves a message out of the queued bar and into the thread at its invocation position.
|
||||
5. **`messages-indeterminate {localIds}`** (SSE): the steer outcome is unknown. Keep `invokedAt: null`, mark `deliveryState:'indeterminate'`, exclude the row from automatic replay, and show explicit Retry/Cancel actions.
|
||||
5. **`messages-indeterminate {localIds}`** (SSE): a native dispatch or queue mutation has an unknown outcome. Keep `invokedAt: null`, mark `deliveryState:'indeterminate'`, and exclude the row from automatic replay. Retry/Cancel are explicit resolution actions and may remain unavailable until the native outcome can be reconciled.
|
||||
6. **`messages-requeued {localIds}`** (SSE): an explicit Retry restored normal queue delivery; clear `deliveryState`.
|
||||
7. **`message-cancelled {messageId, localId?}`** (SSE): remove the row (match either id).
|
||||
|
||||
@@ -152,8 +152,8 @@ After a reconnect whose handshake said `resume: 'gap'` (an `ok` resume replayed
|
||||
|
||||
1. Finish a tail sync.
|
||||
2. Collect candidate `localId`s: user rows with `invokedAt === null`, excluding optimistic rows still `sending`/`failed`.
|
||||
3. `POST /api/sessions/:id/messages/queued-state` with `{"localIds": […]}` (max 1000 per call; batch above that) → `{queuedLocalIds: string[], invokedLocalMessages: [{localId, invokedAt}]}`.
|
||||
4. Apply `invokedLocalMessages` exactly like `messages-consumed`; drop candidates that are in **neither** list (deleted server-side).
|
||||
3. `POST /api/sessions/:id/messages/queued-state` with `{"localIds": […]}` (max 1000 per call; batch above that) → `{queuedLocalIds: string[], indeterminateLocalIds: string[], invokedLocalMessages: [{localId, invokedAt}]}`.
|
||||
4. Apply `invokedLocalMessages` exactly like `messages-consumed`; mark `indeterminateLocalIds` as unresolved delivery. Retain both queued and indeterminate rows; drop only candidates absent from **all three** result groups. An in-flight native dispatch is reported as indeterminate, not as a deleted message.
|
||||
|
||||
---
|
||||
|
||||
@@ -181,14 +181,20 @@ Response `{"ok": true}`. Sending to an inactive session returns `409 {"error":"S
|
||||
|---|---|---|
|
||||
| `{"status":"cancelled","localId":string\|null}` | Row deleted (or already gone). Bumps the epoch. | Remove the row. |
|
||||
| `{"status":"invoked","message":DecryptedMessage}` | Too late — the agent consumed it before the cancel landed. | **Ingest the returned message** as the authoritative row (correct `invokedAt`, status `sent`); do not resurrect the queued snapshot. |
|
||||
| `{"status":"busy","localId":string}` | A live steer is still resolving. | Restore the row as indeterminate; reconcile queued state before allowing Retry/Cancel. |
|
||||
| `{"status":"busy","localId":string}` | Native delivery/removal is unresolved; cancellation cannot be confirmed. | Restore the row as indeterminate; reconcile queued state before allowing Retry/Cancel. |
|
||||
|
||||
Other subscribers learn the same outcome via `message-cancelled` / `messages-consumed` SSE events.
|
||||
|
||||
**Steer a queued message into the current turn**: `POST /api/sessions/:id/messages/:messageId/steer` (Pi sessions) → `SteerQueuedMessageResponseSchema`:
|
||||
**Steer a queued message into the current turn**: `POST /api/sessions/:id/messages/:messageId/steer` → `SteerQueuedMessageResponseSchema`. Unlike the send-time `deliveryMode` option above, this endpoint supports Pi, Codex, and Cursor ACP sessions (`isSteeringSupportedForSession` in `shared/src/modes.ts`). It rejects all scheduled messages, and rejects terminal-controlled sessions unless they advertise `concurrentClients`.
|
||||
|
||||
| Response | Client action |
|
||||
|---|---|
|
||||
| `{"status":"steered","localId"}` | Keep the row queued-side; it is being injected into the live turn. |
|
||||
| `{"status":"invoked","message"}` | Already consumed — ingest the message. |
|
||||
| `{"status":"failed","error","localId":string\|null}` | Surface the error; the row remains queued. |
|
||||
| `{"status":"failed","error","localId":string\|null}` | Surface the error. Do not infer delivery state from this alone; reconcile before retrying when the native outcome is unknown. |
|
||||
|
||||
**Retry indeterminate delivery**: `POST /api/sessions/:id/messages/:messageId/retry`
|
||||
is user-initiated only. `retried` or `already-queued` means normal queue delivery;
|
||||
`invoked` carries the authoritative message; `not-found` means the row is gone.
|
||||
`retry-unavailable` leaves the row unresolved: the hub could not prove that
|
||||
retrying would avoid duplicate work. Reconcile instead of automatically retrying.
|
||||
|
||||
Reference in New Issue
Block a user