feat: authored-history-write consumer side (Worldtree #347) — v0.19.6
Consumer side of Worldtree's #347 authored-history-write (the SillyTavern first-message primitive), shipped via direct in-session TDD: - write_authored_history (POST /sessions/{id}/history): v1 author=assistant, effects=none, per-session idempotency; body server-pinned (AuthoredWriteRequest extra=forbid) so null effects/claimed_original_at are omitted; 200 replay / 201 fresh both return the AuthoredTurnResponse dict. - AuthoredHistoryUnavailable: the hide-existence 404 (feature-absent / ungranted / session-absent, indistinguishable by design — INV-347-1) raised DISTINCT from SessionApiFailed so callers branch feature-absent and never capability-probe. - get_session_messages (GET /sessions/{id}/messages): un-deferred as the seed read-back — confirms a seed renders as a normal role=assistant turn (model-invisible provenance). - --seed-first-message probe: create session -> seed -> read-back; a 404 reports a benign feature-absent result (exit 0), never a capability-probe. Contract #2 amended (2 FNs, validated OK). 19 new tests (12 wrapper + 7 cli), suite 601 green. Coverage-map re-converged: REST 19/41 (the #347 route + the messages read-back close the one gap the 2.3.0 re-vendor opened). Live-proof pending the session.history.write grant (requested infra-ops).
This commit is contained in:
@@ -372,3 +372,99 @@ TESTS:
|
||||
happy [happy]: 204 → None; body == {"pad":[...]} verbatim
|
||||
non_204 [error]: 422 → SessionApiFailed(422)
|
||||
```
|
||||
|
||||
## Amendment 2026-07-06 — authored-history write (#347, v1 coverage-audit re-open)
|
||||
|
||||
Worldtree shipped #347 (authored-history-write) as OpenAPI 2.3.0: a new
|
||||
`POST /sessions/{session_id}/history` primitive that writes ONE model-visible
|
||||
turn into a session's ledger AS the bound agent, WITHOUT a generation and
|
||||
WITHOUT lived-turn side effects (the SillyTavern "first message"). The re-vendor
|
||||
(2.2.0→2.3.0, pin `879cefe`) re-opened the v1 coverage-audit with this one new
|
||||
in-scope REST path-group; this amendment closes it on the consumer side and also
|
||||
un-defers `GET /sessions/{id}/messages` (previously §Out of scope) as the seed's
|
||||
read-back.
|
||||
|
||||
**Hide-existence (server INV-347-1) — the load-bearing consumer contract.** The
|
||||
`session.history.write` grant is checked FIRST — an ungranted caller (or a
|
||||
non-owner, or an unknown session) gets a 404 **byte-identical** to a genuine
|
||||
`session_not_found`, never a 403/409/422 that would reveal the feature exists.
|
||||
The consumer MUST honor this: treat 404 as **feature-absent**, fall back (a
|
||||
production consumer to a model-generated greeting), and NEVER capability-probe to
|
||||
tell feature-absent from ungranted from session-absent. The wrapper encodes it by
|
||||
raising a DISTINCT `AuthoredHistoryUnavailable` on 404 (NOT `SessionApiFailed`),
|
||||
so a caller branches feature-absent without inspecting a status code.
|
||||
|
||||
**Request body — v1-minimal, wire-pinned by the server.** The frozen OpenAPI 2.3.0
|
||||
exports an empty request schema, but the server pins `AuthoredWriteRequest`
|
||||
(`extra="forbid"`): `{author, content, idempotency_key, effects?,
|
||||
claimed_original_at?}`. v1: `author="assistant"` (only value), `content` (UTF-8,
|
||||
server-bounded at `authored_content_max_bytes`=8192), `idempotency_key` (REQUIRED,
|
||||
per-session dedup), `effects` omitted (== "none"; only value). Because
|
||||
`extra="forbid"`, the wrapper omits `effects`/`claimed_original_at` when None
|
||||
(never sends null). Success is 201 (fresh) OR 200 (idempotent replay,
|
||||
byte-identical body); both return the `AuthoredTurnResponse` `{author,
|
||||
content_chars, injected_at, phase, seq, session_id, turn_id}` verbatim (provenance
|
||||
is audit-only, NEVER on this body — INV-347-7).
|
||||
|
||||
**Assistant-first provider constraint (deferred, inert for the probe).** A
|
||||
create-time first-message makes the assistant seq-0 (assistant-first history);
|
||||
Anthropic-family providers 400 the *next generation*, vLLM/openai_compat tolerate
|
||||
it. The `--seed-first-message` probe seeds but does NOT generate, so the
|
||||
constraint is inert for the probe — a real consumer that then generates must bind
|
||||
an assistant-first-tolerant provider.
|
||||
|
||||
```contract
|
||||
FN write_authored_history(client: httpx.AsyncClient, session_id: str, *, content: str, idempotency_key: str, author: str = "assistant", effects: str | None = None, claimed_original_at: str | None = None) -> dict[str, Any]
|
||||
BRIEF: POST /sessions/{session_id}/history — the #347 authored-history-write primitive (write one model-visible turn as the bound agent, no generation, no side effects). Body {author, content, idempotency_key} + "effects"/"claimed_original_at" only when non-None (server AuthoredWriteRequest is extra="forbid"). Success 200 (replay) or 201 (fresh) → AuthoredTurnResponse dict verbatim. 404 → AuthoredHistoryUnavailable (hide-existence: feature-absent/ungranted/session-absent, indistinguishable by design — consumer falls back, never probes). Any other non-2xx → SessionApiFailed.
|
||||
PRE: [PRE-001 hard] client is not None -- assert client is not None
|
||||
PRE: [PRE-002 hard] session_id is a non-empty str -- assert session_id and isinstance(session_id, str)
|
||||
PRE: [PRE-003 hard] content is a non-empty str -- assert content and isinstance(content, str)
|
||||
PRE: [PRE-004 hard] idempotency_key is a non-empty str -- assert idempotency_key and isinstance(idempotency_key, str)
|
||||
PRE: [PRE-005 hard] author is a non-empty str -- assert author and isinstance(author, str)
|
||||
POST: [POST-001 side_effect] exactly one POST to /sessions/{session_id}/history; body == {"author": author, "content": content, "idempotency_key": idempotency_key} plus "effects" iff effects is not None plus "claimed_original_at" iff claimed_original_at is not None (no null-valued keys — extra="forbid")
|
||||
POST: [POST-002 return_value] on 200 or 201 returns resp.json() unmodified
|
||||
ERROR_ROUTING:
|
||||
HTTP 404 (hide-existence session_not_found):
|
||||
local_handling: raise AuthoredHistoryUnavailable(session_id=session_id)
|
||||
flow_control: abort
|
||||
state_recovery: caller treats as feature-absent; fall back to a model-generated greeting; NEVER capability-probe (INV-347-1)
|
||||
HTTP other non-2xx (incl. 409 generation_active, 422 content_too_long/validation_failed, 401 auth_revoked, 410 session_retired):
|
||||
local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
|
||||
flow_control: abort
|
||||
state_recovery: none (409 retryable; 422 caller bug/oversize)
|
||||
STEPS:
|
||||
1. [setup, flexibility=prescriptive] assert PRE-001..PRE-005
|
||||
2. [sequential, flexibility=prescriptive] body = {"author": author, "content": content, "idempotency_key": idempotency_key}; IF effects is not None: body["effects"] = effects; IF claimed_original_at is not None: body["claimed_original_at"] = claimed_original_at
|
||||
3. [sequential, flexibility=prescriptive] resp = await client.post(f"/sessions/{session_id}/history", json=body)
|
||||
tool: { destructive: false, idempotent: true, read_only: false, open_world: false }
|
||||
4. [branch, flexibility=prescriptive] IF resp.status_code in (200, 201): RETURN resp.json(); ELIF resp.status_code == 404: RAISE AuthoredHistoryUnavailable(session_id=session_id); ELSE RAISE SessionApiFailed(status=resp.status_code, body=resp.content)
|
||||
TESTS:
|
||||
happy_fresh_201 [happy,tracer]: 201 {author:"assistant", seq:0, phase:"seeded", turn_id, content_chars, session_id, injected_at} → dict verbatim; outbound body == {"author":"assistant","content":<c>,"idempotency_key":<k>} exactly (no effects/claimed_original_at keys)
|
||||
happy_replay_200 [happy]: 200 (same-key replay, byte-identical body) → dict verbatim
|
||||
body_includes_effects [trace]: effects="none" → outbound body has "effects":"none"; claimed_original_at="2020-01-01T00:00:00Z" → body has that key too
|
||||
hide_existence_404 [error]: 404 {error_code:"session_not_found"} → raises AuthoredHistoryUnavailable(session_id=<arg>), NOT SessionApiFailed
|
||||
generation_active_409 [error]: 409 {error_code:"generation_active"} → SessionApiFailed(status=409)
|
||||
content_too_long_422 [error]: 422 {error_code:"content_too_long"} → SessionApiFailed(status=422)
|
||||
empty_content [adversarial]: content="" → AssertionError; no HTTP issued
|
||||
empty_idempotency_key [adversarial]: idempotency_key="" → AssertionError; no HTTP issued
|
||||
empty_session_id [adversarial]: session_id="" → AssertionError; no HTTP issued
|
||||
|
||||
FN get_session_messages(client: httpx.AsyncClient, session_id: str) -> dict[str, Any]
|
||||
BRIEF: GET /sessions/{session_id}/messages — the session's message history (spec §GET /sessions/{id}/messages), un-deferred as the #347 probe's read-back so a seeded turn can be confirmed to render as a normal role=assistant message (model-invisible provenance — a seed is indistinguishable from a lived turn on read). Returns {session_id, items:[{seq, role, content, ...}], next_cursor} verbatim. Owner-scoped; any non-200 → SessionApiFailed. v1 reads the server default page (no pagination params — the probe reads a fresh 1-message session; add limit/cursor when a caller needs scrollback).
|
||||
PRE: [PRE-001 hard] client is not None -- assert client is not None
|
||||
PRE: [PRE-002 hard] session_id is a non-empty str -- assert session_id and isinstance(session_id, str)
|
||||
POST: [POST-001 return_value] on 200 returns resp.json() unmodified
|
||||
ERROR_ROUTING:
|
||||
HTTP non-200 (incl. 404 session_not_found cross-owner/unknown):
|
||||
local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
|
||||
flow_control: abort
|
||||
state_recovery: none
|
||||
STEPS:
|
||||
1. [setup, flexibility=prescriptive] assert PRE-001, PRE-002
|
||||
2. [sequential, flexibility=prescriptive] resp = await client.get(f"/sessions/{session_id}/messages")
|
||||
3. [branch, flexibility=prescriptive] IF resp.status_code == 200: RETURN resp.json(); ELSE RAISE SessionApiFailed
|
||||
TESTS:
|
||||
happy [happy]: 200 {session_id, items:[{seq:0, role:"assistant", content:"…"}], next_cursor:null} → dict verbatim
|
||||
not_found_404 [error]: 404 → SessionApiFailed(status=404)
|
||||
empty_session_id [adversarial]: "" → AssertionError; no HTTP issued
|
||||
```
|
||||
|
||||
+17
-11
@@ -19,7 +19,7 @@ anchors against the frozen machine-readable artifacts, NOT the prose markdown:
|
||||
|
||||
| Worldtree v1 surface | Frozen anchor | Ratatoskr role |
|
||||
|---|---|---|
|
||||
| Conversation REST API | OpenAPI `info.version` **2.2.0** (`Worldtree/docs/conversation-api-openapi.json`, sha `dbdf4e24…`) — **40 path×method groups** | **client** (debug TUI / web) |
|
||||
| Conversation REST API | OpenAPI `info.version` **2.3.0** (`Worldtree/docs/conversation-api-openapi.json`, sha `36148179…`) — **41 path×method groups** (2.3.0 added `POST /sessions/{id}/history`, #347) | **client** (debug TUI / web) |
|
||||
| Conversation SSE events | `conversation-api-sse-events.schema.json` (sha `9deeebf4…`) — **11 discriminated event types** | **client** |
|
||||
| Bifrost wire (consumer protocol) | wire **v0.6** STABLE/FROZEN (`bifrost==1.0.0`) — memory + affect planes | **provider** (Worldtree dispatches into us) |
|
||||
|
||||
@@ -48,7 +48,7 @@ resolved (§ Surface 1, scope-resolution table).
|
||||
|
||||
| Surface | Points | ✅ covered-live | ⬜ gap (in-scope) | 🚫 excluded-by-design |
|
||||
|---|---|---|---|---|
|
||||
| REST (OpenAPI 2.2.0, path groups) | 40 | 17 | 0 | 23 |
|
||||
| REST (OpenAPI 2.3.0, path groups) | 41 | 19 | 0 | 22 |
|
||||
| SSE events | 11 | 11 | 0 | 0 |
|
||||
| Bifrost provider planes | 8 verbs | 8 | 0 | (10 gated verbs deferred) |
|
||||
|
||||
@@ -61,7 +61,7 @@ sub-gap).
|
||||
|
||||
---
|
||||
|
||||
## Surface 1 — Conversation REST API (OpenAPI 2.2.0)
|
||||
## Surface 1 — Conversation REST API (OpenAPI 2.3.0)
|
||||
|
||||
### Covered — client path (ratatoskr's core identity)
|
||||
|
||||
@@ -69,6 +69,8 @@ sub-gap).
|
||||
|---|---|---|---|
|
||||
| `POST /sessions` | ✅ | `sessions.py:307` → `cli.py:482`,`tui.py:1508`,`web/server.py:155` | + `end_user_id`, `bifrost` binding; 404→AgentNotFound, 502→BifrostHandshakeFailed |
|
||||
| `POST /sessions/{id}/messages` (turn stream, SSE) | ✅ | `sse_client.py:484` `stream_turn` → cli/tui/web | the primary surface; 409→AgentNotAvailable, 503→TurnLaunchUnavailable (b2 #331) |
|
||||
| `POST /sessions/{id}/history` (authored-history-write, #347) | ✅ | `sessions.py:583` `write_authored_history` → `cli.py:758` `--seed-first-message` | v1: author=assistant, effects=none, per-session idempotency; 404→AuthoredHistoryUnavailable (hide-existence: feature-absent, never probe); 409/422 mapped. **Live-proof pending** the `session.history.write` grant (requested infra-ops 2026-07-06) — ungranted returns the hide-404, so the probe exercises the feature-absent fallback until granted (Tier-2 precedent: ✅ code-complete + graceful-degrade) |
|
||||
| `GET /sessions/{id}/messages` (history) | ✅ | `sessions.py:635` `get_session_messages` → `cli.py:758` `--seed-first-message` read-back | un-deferred as the #347 seed read-back — confirms model-invisible provenance (a seed reads back as a normal `role=assistant` turn) |
|
||||
| `POST /sessions/{id}/turns/{turn_id}/cancel` | ✅ | `sse_client.py:581` → cli/tui/web | two-stage Ctrl-C; 404/409 mapped |
|
||||
| `GET /agents` | ✅ | `sessions.py:341` → `tui.py:1472`,`web/server.py:100` | Tier-1 roster; merged with local index |
|
||||
| `GET /agents/{id}/persona_state` | ✅ | `sessions.py:384` → `tui.py:1132`,`web/server.py:386` | persona hydrate; 404/403 mapped |
|
||||
@@ -96,16 +98,21 @@ on the same path is an unwired frontier item — see frontier Tier 1):
|
||||
- `GET /agents/{id}` — consumer-agent lookup (`GET /agents/<owner>:<name>` with
|
||||
the owner key) is **manual-curl-only**, not in code.
|
||||
|
||||
### In-scope gaps — CONVERGED (zero remaining, 2026-07-01)
|
||||
### In-scope gaps — CONVERGED (re-closed 2026-07-06 after the #347 re-open)
|
||||
|
||||
**Every in-scope REST I/O point is now covered.** The frontier that opened this
|
||||
audit (the design-brief §5 observability panes + the presenter-wiring sub-gaps +
|
||||
the Tier-2 tail) is fully closed:
|
||||
**Every in-scope REST I/O point is covered.** The audit first converged
|
||||
2026-07-01; Worldtree's #347 (authored-history-write, OpenAPI 2.3.0) then added
|
||||
one new in-scope path-group, re-opening the audit with a single gap — now closed
|
||||
(`v0.19.6`). The original frontier (design-brief §5 observability panes +
|
||||
presenter-wiring sub-gaps + Tier-2 tail) remains fully closed:
|
||||
|
||||
- Session picker + SSE-resume — wired (`v0.18.5`–`.7`).
|
||||
- Persona · Tools · BifrostState · AdminEvents panes — all built + live (`v0.18.x`–`v0.19.0`).
|
||||
- Transient-characters CRUD + persona-state write — consumed via `--characters` /
|
||||
`--set-persona-pad` (`v0.19.1`).
|
||||
- Authored-history-write (#347) + messages read-back — `write_authored_history` +
|
||||
`get_session_messages` via `--seed-first-message` (`v0.19.6`; live-proof pending
|
||||
the `session.history.write` grant).
|
||||
|
||||
The only remaining not-consumed in-scope method is `GET /agents/{id}` (consumer-
|
||||
agent lookup, manual-curl-only) — a sub-method on an already-✅ path group, not a
|
||||
@@ -116,7 +123,6 @@ path-group gap. Everything else is covered or excluded-by-design below.
|
||||
| Endpoint(s) | Status | Rationale (design-brief / memory) |
|
||||
|---|---|---|
|
||||
| `PATCH /sessions/{id}` · `DELETE /sessions/{id}` | 🚫 | §4: rename/delete happen outside the tool (`sessions_cli.py`) |
|
||||
| `GET /sessions/{id}/messages` (history) | 🚫 | §6: single-session live transcript, no history fetch |
|
||||
| `GET /sessions/{id}` | 🚫 | session detail — identity is footer-visible, no detail view |
|
||||
| `GET /sessions/{id}/tool-events` | 🚫 | §5: tool calls observed **inline from SSE** `tool_start`/`tool_result`; persisted-events endpoint is opt-in only |
|
||||
| `GET /admin/sessions/{id}/tools` | 🚫 | **covered-by-alternative** — the owner-scoped `GET /sessions/{id}/tools` (✅) serves the Tools inventory; this admin variant is only for cross-user operator debug, out of the single-session focus (§6) |
|
||||
@@ -204,10 +210,10 @@ starts exercising them.
|
||||
|
||||
---
|
||||
|
||||
## Convergence frontier (the v1 to-do) — CLOSED 2026-07-01
|
||||
## Convergence frontier (the v1 to-do) — CLOSED 2026-07-01, re-closed 2026-07-06 (#347)
|
||||
|
||||
**Every in-scope I/O point is covered.** The frontier is empty: REST 17/40 ✅
|
||||
with **zero in-scope gaps** (the other 23 REST path-groups are excluded-by-design),
|
||||
**Every in-scope I/O point is covered.** The frontier is empty: REST 19/41 ✅
|
||||
with **zero in-scope gaps** (the other 22 REST path-groups are excluded-by-design),
|
||||
SSE 11/11, Bifrost provider planes 8/8. v1 convergence (per scope A: "every
|
||||
frozen I/O point classified, zero unaccounted") is **met** — ratatoskr cuts v1
|
||||
when Worldtree tags 1.0. The arc, for the record:
|
||||
|
||||
Reference in New Issue
Block a user