Compare commits
19 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 vh
|
be171304f5 | ||
|
vh
|
4aec3061d5 | ||
|
vh
|
e643d38f58 | ||
|
vh
|
6bf2a84ccd | ||
|
vh
|
75da6767d3 | ||
|
vh
|
8ac88ee536 | ||
|
vh
|
0a8784cc1b | ||
|
vh
|
7156b25957 | ||
|
vh
|
022accfa7b | ||
|
vh
|
c457520ae4 | ||
|
vh
|
9ca931e148 | ||
|
vh
|
c77ff913f0 | ||
|
vh
|
4a3551254f | ||
|
vh
|
0b7489f74d | ||
|
vh
|
3dac5d3b44 | ||
|
vh
|
a99f2473b6 | ||
|
vh
|
ca46a93171 | ||
|
vh
|
85a2b95428 | ||
|
vh
|
75dec016eb |
@@ -104,8 +104,8 @@ id = "worldtree-conversation-api-openapi-v2"
|
||||
canonical_source = "Worldtree"
|
||||
canonical_path = "docs/conversation-api-openapi.json"
|
||||
consumer_path = "docs/conversation-api-openapi.json"
|
||||
pinned_sha256_16 = "dbdf4e24c8b06c92"
|
||||
pinned_at = "2026-06-30T22:25:56+00:00"
|
||||
pinned_sha256_16 = "36148179601453a0"
|
||||
pinned_at = "2026-07-06T16:09:05+00:00"
|
||||
|
||||
[[pins]]
|
||||
id = "worldtree-conversation-api-sse-events-v1"
|
||||
@@ -120,6 +120,26 @@ id = "worldtree-conversation-api-spec-v1"
|
||||
canonical_source = "Worldtree"
|
||||
canonical_path = "docs/conversation-api-spec.md"
|
||||
consumer_path = "docs/conversation-api-spec.md"
|
||||
pinned_sha256_16 = "2d111a3b8322b7d1"
|
||||
pinned_at = "2026-06-30T22:25:56+00:00"
|
||||
pinned_sha256_16 = "c656a789caceef14"
|
||||
pinned_at = "2026-07-06T16:51:09+00:00"
|
||||
tolerate_drift = true # prose reference; OpenAPI+SSE are the gates
|
||||
|
||||
# Worldtree persona render canons (d2) — the deterministic affect->NL the agent is
|
||||
# context-injected. The web persona pane renders mood + relationship-directive BYTE-EXACT
|
||||
# from these (via the flat src/ratatoskr/web/static/persona_render_canon.json, regenerated
|
||||
# by scripts/build_persona_canon.py). Drift here => rerun that regen with Worldtree's venv.
|
||||
[[pins]]
|
||||
id = "worldtree-persona-mood-render-canon-v1"
|
||||
canonical_source = "Worldtree"
|
||||
canonical_path = "core/persona/canon/d2-mood-render-canon-v1.json"
|
||||
consumer_path = "docs/vendor/worldtree-persona-canon/d2-mood-render-canon-v1.json"
|
||||
pinned_sha256_16 = "e2f124fed3ee8d42"
|
||||
pinned_at = "2026-07-01T21:00:00+00:00"
|
||||
|
||||
[[pins]]
|
||||
id = "worldtree-persona-d2-render-canon-v1"
|
||||
canonical_source = "Worldtree"
|
||||
canonical_path = "core/persona/canon/d2-render-canon-v1.json"
|
||||
consumer_path = "docs/vendor/worldtree-persona-canon/d2-render-canon-v1.json"
|
||||
pinned_sha256_16 = "606bba5fdcc60b6b"
|
||||
pinned_at = "2026-07-01T21:00:00+00:00"
|
||||
|
||||
+9
-7
@@ -7,16 +7,18 @@ documents the pin, the vendored artifacts, and the bump procedure.
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Worldtree git SHA | `5810a26b38a5ea6630892f9a39756f57c5b7b41e` |
|
||||
| Worldtree HEAD message | `memory: snapshot — v1.0.0b2 shipped complete (demo + personal green); consumer loop closed` |
|
||||
| Pinned on | 2026-06-30 |
|
||||
| Pinned by | ratatoskr-dev (v1 coverage-audit — re-pin to the FROZEN OpenAPI 2.2.0 + SSE schema) |
|
||||
| Worldtree version at pin | `v1.0.0b2` |
|
||||
| Worldtree git SHA | `c9e59ec` |
|
||||
| Worldtree HEAD message | `docs: document Tier-3 persona/memory schemas + persona_state SET body (OpenAPI 2.3.0)` |
|
||||
| Pinned on | 2026-07-06 |
|
||||
| Pinned by | ratatoskr-dev (re-vendor prose markdown — Tier-3 persona/memory/persona_state consumer shapes) |
|
||||
| Worldtree version at pin | `v1.0.0b22` |
|
||||
|
||||
## Pin history
|
||||
|
||||
| Date | SHA | Version | Notable deltas consumed |
|
||||
|---|---|---|---|
|
||||
| 2026-07-06 | `c9e59ec` | v1.0.0b22 | **Re-vendor the prose markdown — Tier-3 consumer shapes documented.** `c9e59ec` (docs-only, OpenAPI byte-unchanged vs `879cefe`) adds `docs/conversation-api-spec.md` § "Tier 3 — Consumer-defined agents": the persona / memory / persona_state SET-body shapes that serialize as freeform `Any` in the OpenAPI (so prose is their source of truth). Drove a consumer fix: `--set-persona-pad` now sends the canonical `{pad:{pleasure,arousal,dominance}}` named dict (was `{pad:[list]}`) — #317, `v0.19.7`. Foot-guns encoded: persona.ocean single-letter `{O,C,E,A,N}` on `/agents/define` (spelled-out → 422, the #348 mismatch) vs spelled-out on `POST /characters`; memory `{embedder_version, tier3_dreaming}`, stm_* deprecated, allows_world_scope removed→422; only `valence` still 422s. `pin:`-only for the markdown; the `v0.19.7` bump rode the persona_state code fix. |
|
||||
| 2026-07-06 | `879cefe` | v1.0.0b22 | **Re-vendor OpenAPI 2.2.0→2.3.0 — Worldtree shipped #347 authored-history-write.** One new REST path-group: `POST /sessions/{session_id}/history` (the authored-history-write primitive) + the `AuthoredTurnResponse` schema (openapi path count 40→41). #347 is **OpenAPI-only** — the prose `conversation-api-spec.md` + server `conversation_api.contract.md` are byte-unchanged since the 5810a26 pin (empty `git log` delta), so those `tolerate_drift` pins stay clean; the SSE schema is unchanged (#347 is event-silent by design). **Consumer side NOT yet built** — `POST /sessions/{id}/history` is a fresh in-scope ⬜ gap in `docs/coverage-map.md` (re-opens the v1 coverage-audit with exactly one gap; Heimdall-gated hide-existence → consumer treats 404 as feature-absent). `pin:`-only, no version bump. |
|
||||
| 2026-06-30 | `5810a26` | v1.0.0b2 | **Re-pin to Worldtree's FROZEN v1 surface (#326), as part of the v1 coverage-audit.** Vendored the machine-readable artifacts — `conversation-api-openapi.json` (OpenAPI **2.2.0**, 40 path-groups) + `conversation-api-sse-events.schema.json` (11 events) — now the **authoritative drift gates** (pinned in `.corviduo-canonicals.toml`, CI-checked by `canonical_drift.py`). The prose `conversation-api-spec.md` is **byte-identical** to the v0.35.16 pin (last WT markdown edit 2026-05-31), kept as the human reference (`tolerate_drift`). b2 deltas already consumed in code: 409/503 eager turn-launch statuses (#331, v0.18.3/.4) + the unified error envelope (#328). 7 endpoints documented only in the OpenAPI, not the prose, all classified in `docs/coverage-map.md`: `admin/keys/bulk`, `admin/persona/{archive,erase}`, `admin/usage`, `embed`, `judgments`, `me/usage`. No client-breaking change — `pin:`-only, no version bump. |
|
||||
| 2026-06-17 | `f1b59f8` | v0.35.16 | **#297 + #298/#299 — Worldtree adopts the bifrost v0.6 scope wire (emits `scope_any`/`scope_all`) + client-side per-scope-value union recall. With our v0.17.6 provider this closes cold cross-session recall end-to-end.** Catch-up bump (v0.29.0→v0.35.16). Intervening client-facing deltas reviewed, none break our consumer: #211 agent rename (`saga`→`echo`, `actor`→`mask` — slugs only); #245 `end_user_id` persistence + memory-scope resolver; #187/#188/#219 Tier-3 define/PATCH policy (additive); `bifrost` binding field + `ephemeral_does_not_accept_bifrost` 422 now documented (the #17 surface). Error codes stable; no ratatoskr code change required. |
|
||||
| 2026-05-25 | `da93ca7` | v0.28.0 | #204 — new SSE event `affect_update` (current/scheduled), new endpoint `GET /agents/{id}/persona_state`, auth-model doc edits |
|
||||
@@ -26,12 +28,12 @@ documents the pin, the vendored artifacts, and the bump procedure.
|
||||
|
||||
**Authoritative (FROZEN, machine-readable — the drift gates):**
|
||||
|
||||
- `docs/conversation-api-openapi.json` — copy of `Worldtree/docs/conversation-api-openapi.json` (OpenAPI `info.version` **2.2.0**). The frozen v1 REST wire (40 path-groups). Pinned `worldtree-conversation-api-openapi-v2` in `.corviduo-canonicals.toml`; drift gated by `canonical_drift.py`.
|
||||
- `docs/conversation-api-openapi.json` — copy of `Worldtree/docs/conversation-api-openapi.json` (OpenAPI `info.version` **2.3.0**). The frozen v1 REST wire (41 path-groups; 2.3.0 added `POST /sessions/{session_id}/history` per #347). Pinned `worldtree-conversation-api-openapi-v2` in `.corviduo-canonicals.toml`; drift gated by `canonical_drift.py`.
|
||||
- `docs/conversation-api-sse-events.schema.json` — copy of `Worldtree/docs/conversation-api-sse-events.schema.json`. The frozen SSE event schema (11 discriminated event types). Pinned `worldtree-conversation-api-sse-events-v1`.
|
||||
|
||||
**Reference (prose; allowed to lag — `tolerate_drift`):**
|
||||
|
||||
- `docs/conversation-api-spec.md` — copy of `Worldtree/docs/conversation-api-spec.md` at the pinned SHA. The **client-facing prose narrative**. Byte-frozen at v0.35.16-era content (last WT edit 2026-05-31); the OpenAPI/SSE JSON above are the source of truth where they diverge. Pinned `worldtree-conversation-api-spec-v1` (tolerate_drift).
|
||||
- `docs/conversation-api-spec.md` — copy of `Worldtree/docs/conversation-api-spec.md` at the pinned SHA. The **client-facing prose narrative**. Re-vendored at `c9e59ec` (2026-07-06) to carry the § "Tier 3 — Consumer-defined agents" subsections (persona/memory/persona_state SET body) that serialize as freeform `Any` in the OpenAPI JSON — so the **prose is the source of truth for those consumer shapes** (e.g. persona.ocean single-letter `{O,C,E,A,N}` on `/agents/define`; `POST /sessions/{id}/persona_state` body `{pad:{pleasure,arousal,dominance}}`). Elsewhere the OpenAPI/SSE JSON above remain authoritative. Pinned `worldtree-conversation-api-spec-v1` (tolerate_drift).
|
||||
- `docs/conversation_api.contract.md` — copy of `Worldtree/docs/contracts/conversation_api.contract.md` at the pinned SHA (byte-identical at b2 — server contract unchanged since the v0.35.16 pin). The **server-side contract** including INV-001..INV-052 and amendments. Useful for understanding load-bearing server invariants (e.g., INV-014 turn-id-public, INV-046 admin-events-envelope-stable, INV-049 admin-events-pii-discipline) when designing client behavior against them. Not in the canonical manifest (reference-only).
|
||||
|
||||
Both files are vendored — they reflect Worldtree at the pinned SHA, not
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
contract_version: "2.1"
|
||||
module: "ratatoskr.first_message"
|
||||
purpose: "Per-agent authored first-message presets — seed an agent's opening as a #347 authored turn-0 onto new sessions (CLI + web), the durable replacement for a system-prompt startup instruction."
|
||||
touches:
|
||||
- src/ratatoskr/first_message.py
|
||||
- tests/test_first_message.py
|
||||
scope: >
|
||||
Per-agent authored first-message presets (Worldtree #347 consumer feature).
|
||||
When a new session is created for an agent that has a preset opening, seed it
|
||||
as a #347 authored first-message (POST /sessions/{id}/history, author=assistant,
|
||||
seq-0) so the session opens in-character before the user speaks — the durable
|
||||
replacement for a system-prompt "startup" instruction. Two entry points:
|
||||
`preset_for` (lookup) and `seed_preset_first_message` (best-effort seed).
|
||||
Consumed by ratatoskr.cli (the `--new` session path) and ratatoskr.web.server
|
||||
(the POST /api/sessions endpoint). Depends on ratatoskr.sessions
|
||||
(write_authored_history + its exceptions); no core.* / worldtree.* imports.
|
||||
depends_on:
|
||||
- "httpx"
|
||||
- "ratatoskr.sessions"
|
||||
used_by:
|
||||
- "ratatoskr.cli"
|
||||
- "ratatoskr.web.server"
|
||||
language: "python"
|
||||
complexity: "low"
|
||||
estimated_loc: 60
|
||||
confidence: 0.9
|
||||
assumptions:
|
||||
- "write_authored_history (contract #2 amendment 2026-07-06) is the seed primitive: 200/201 → ack dict, 404 → AuthoredHistoryUnavailable (hide-existence), other non-2xx → SessionApiFailed."
|
||||
- "The preset registry is a static in-module dict keyed by agent_id; editing it is how an operator tunes an agent's opening. Seeded with ratatoskr:sindra only."
|
||||
- "Auto-seed is BEST-EFFORT and MUST NOT block session creation: an instance without the session.history.write grant returns the hide-404, which is swallowed (session opens with no seeded greeting)."
|
||||
---
|
||||
|
||||
# First-message presets — authored openings on session-create (#347)
|
||||
|
||||
## Context
|
||||
|
||||
`ratatoskr.first_message` holds per-agent authored-opening presets and seeds them
|
||||
onto new sessions via the #347 authored-history-write primitive. It is the
|
||||
durable form of "give an agent a first message": instead of a system-prompt
|
||||
`Startup:` instruction (a workaround for the pre-#347 world where the assistant
|
||||
could not author turn-0), the opening lives as a real seeded assistant turn-0.
|
||||
|
||||
Consumed at both session-create sites — `ratatoskr.cli._amain` (the `--new` path)
|
||||
and `ratatoskr.web.server._create_session_endpoint` (POST /api/sessions) — so
|
||||
every new session for a preset agent opens in-character regardless of surface.
|
||||
|
||||
## Data flow
|
||||
|
||||
**In:** a live `httpx.AsyncClient` (caller-owned, base_url + bearer set), a fresh
|
||||
`session_id`, and the bound `agent_id`.
|
||||
|
||||
**Out:** on a preset agent, one `POST /sessions/{session_id}/history` (author=assistant,
|
||||
the preset text, per-content idempotency key). Returns the seeded content on
|
||||
success, else `None`.
|
||||
|
||||
**Side effects:** at most one outbound authored-history write; never raises to the
|
||||
caller (best-effort).
|
||||
|
||||
## Invariants
|
||||
|
||||
- **INV-001 [hard]**: `seed_preset_first_message` NEVER raises (the sole exception is
|
||||
`asyncio.CancelledError`, which propagates — cancellation is not a seed failure) and
|
||||
NEVER blocks session creation. It soft-guards its inputs (a bad arg returns `None`,
|
||||
not `AssertionError`), bounds the write with `asyncio.wait_for(_SEED_TIMEOUT_S)` so a
|
||||
stalled `/history` can't hang the create path, and swallows EVERY other exception (the
|
||||
hide-404, `SessionApiFailed`, `httpx.HTTPError`, `TimeoutError`, and any unexpected
|
||||
error) → `None`. The `broad-except` is deliberate: this helper is wired INTO three
|
||||
session-create paths, so any escape would abort a create that already succeeded.
|
||||
- **INV-002 [hard]**: a no-preset agent issues ZERO HTTP (early return before any
|
||||
request).
|
||||
- **INV-003 [hard]**: the seed body is the preset text verbatim, author="assistant",
|
||||
with a per-content idempotency key (`"ratatoskr-preset-" + sha256(text)[:12]`), so
|
||||
a repeat seed of the same session+preset is an idempotent 200 replay, never a
|
||||
duplicate turn.
|
||||
- **INV-004 [hard]**: no `core.*` / `worldtree.*` imports (reference-consumer
|
||||
boundary; verified by `tests/test_no_worldtree_imports.py`, which rglobs every
|
||||
`.py` under `src/ratatoskr/` — this module included, so no per-module import
|
||||
test is needed here).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- **Multi-turn / scripted openers.** v1 seeds exactly one assistant turn-0. A
|
||||
multi-message opening scene is a future concern.
|
||||
- **Runtime/remote preset config.** The registry is an in-module dict; no file/DB/env
|
||||
loading. Add that only when a second consumer needs operator-editable presets.
|
||||
- **Non-assistant authors.** v1 is author=assistant only (matches #347 v1); a
|
||||
user/system opener is deferred with the #347 engine surface.
|
||||
- **TUI-only surfaces.** Both real session-create paths (CLI + web) are wired; the
|
||||
bare-TUI picker resumes existing sessions (no create), so it needs no seed.
|
||||
|
||||
---
|
||||
|
||||
```contract
|
||||
FN preset_for(agent_id: str) -> str | None
|
||||
BRIEF: Return the authored first-message preset for agent_id, or None when the agent has no preset. Pure dict lookup over FIRST_MESSAGE_PRESETS.
|
||||
PRE: [PRE-001 hard] agent_id is a non-empty str -- assert agent_id and isinstance(agent_id, str)
|
||||
POST: [POST-001 return_value] returns FIRST_MESSAGE_PRESETS.get(agent_id) (str for a preset agent, None otherwise)
|
||||
STEPS:
|
||||
1. [setup, prescriptive] assert PRE-001
|
||||
2. [sequential, prescriptive] RETURN FIRST_MESSAGE_PRESETS.get(agent_id)
|
||||
TESTS:
|
||||
preset_hit [happy]: preset_for("ratatoskr:sindra") is a non-empty str
|
||||
preset_miss [happy]: preset_for("mimir") is None
|
||||
empty_agent_id [adversarial]: preset_for("") → AssertionError
|
||||
|
||||
FN seed_preset_first_message(client: httpx.AsyncClient, session_id: str, agent_id: str) -> str | None
|
||||
BRIEF: Best-effort seed of an agent's preset opening as a #347 authored first-message on session_id. If agent_id has a preset, POST it via write_authored_history (author=assistant, per-content idempotency key, the await bounded by asyncio.wait_for(_SEED_TIMEOUT_S)) and return the seeded content; on no-preset, a malformed input, OR ANY exception except asyncio.CancelledError, return None WITHOUT raising. Never raises (except CancelledError, which propagates) and never blocks session creation — it is wired into three create paths.
|
||||
PRE: [PRE-001 hard] client is not None -- soft-guarded: return None (NOT assert) if violated, so a wiring bug can't crash the create path (INV-001)
|
||||
PRE: [PRE-002 hard] session_id is a non-empty str -- soft-guarded: return None if violated
|
||||
PRE: [PRE-003 hard] agent_id is a non-empty str -- soft-guarded: return None if violated (also guards FIRST_MESSAGE_PRESETS.get against a non-hashable/non-str id)
|
||||
POST: [POST-001 return_value] preset agent + successful write → returns the preset text; no-preset, malformed input, OR any swallowed failure → None
|
||||
POST: [POST-002 side_effect] a no-preset / malformed-input call issues ZERO HTTP; a preset agent issues exactly one POST /sessions/{session_id}/history with body author="assistant", content=preset, idempotency_key="ratatoskr-preset-"+sha256(preset)[:12], the await bounded by _SEED_TIMEOUT_S so a stalled response cannot block
|
||||
ERROR_ROUTING:
|
||||
asyncio.CancelledError:
|
||||
local_handling: RE-RAISE (cancellation is not a seed failure; never swallow it — and it is a BaseException, so `except Exception` would miss it anyway)
|
||||
flow_control: propagate
|
||||
state_recovery: n/a
|
||||
any other Exception (hide-404 AuthoredHistoryUnavailable, SessionApiFailed 409/422/etc., httpx.HTTPError, TimeoutError from wait_for, any unexpected error):
|
||||
local_handling: swallow; return None
|
||||
flow_control: continue (never blocks session create)
|
||||
state_recovery: session opens with no seeded greeting
|
||||
STEPS:
|
||||
1. [setup, prescriptive] Soft-guard: IF agent_id is not a non-empty str: RETURN None (before any dict lookup — guards a non-hashable id)
|
||||
2. [sequential, prescriptive] content = FIRST_MESSAGE_PRESETS.get(agent_id); IF content is None: RETURN None (INV-002 — zero HTTP)
|
||||
3. [sequential, prescriptive] Soft-guard: IF client is None OR session_id is not a non-empty str: RETURN None
|
||||
4. [sequential, prescriptive] key = "ratatoskr-preset-" + sha256(content utf-8)[:12]
|
||||
5. [sequential, prescriptive] TRY: await asyncio.wait_for(write_authored_history(client, session_id, content=content, idempotency_key=key), timeout=_SEED_TIMEOUT_S)
|
||||
tool: { destructive: false, idempotent: true, read_only: false, open_world: false }
|
||||
6. [branch, prescriptive] EXCEPT asyncio.CancelledError: RAISE; EXCEPT Exception: RETURN None
|
||||
7. [cleanup, prescriptive] RETURN content
|
||||
TESTS:
|
||||
seeds_preset [happy,tracer]: preset agent, mock 201 → returns the preset text; exactly one POST /sessions/{id}/history; body author="assistant" + content=preset + idempotency_key="ratatoskr-preset-"+sha256(preset)[:12]
|
||||
no_preset_zero_http [happy]: agent "mimir" → returns None; NO HTTP issued
|
||||
feature_absent_swallowed [error]: preset agent, mock 404 session_not_found → returns None, no raise
|
||||
session_api_failed_swallowed [error]: preset agent, mock 409 → returns None, no raise
|
||||
transport_error_swallowed [error]: preset agent, mock httpx.ConnectError → returns None, no raise
|
||||
unexpected_exception_swallowed [error]: preset agent, write raises ValueError → returns None, no raise (INV-001 broad never-raise)
|
||||
cancellation_propagates [error]: preset agent, write raises asyncio.CancelledError → RE-RAISED (never swallowed)
|
||||
malformed_agent_id_no_http [adversarial]: agent_id=123 (non-str) OR "" → None; NO HTTP; no raise
|
||||
empty_session_id [adversarial]: session_id="" (preset agent) → None (soft guard); NO HTTP; no raise
|
||||
```
|
||||
@@ -322,7 +322,9 @@ via a `--characters` one-shot lifecycle probe; persona-state write surfaced via
|
||||
wrappers: parsed dict verbatim (or None on 204), any off-status → SessionApiFailed.
|
||||
**Note:** `set_persona_state`'s request body is FREEFORM — the frozen OpenAPI 2.2.0
|
||||
declares no request schema and the prose spec documents only the GET counterpart,
|
||||
so the caller supplies the snapshot shape (`--set-persona-pad` sends `{pad:[…]}`).
|
||||
so the caller supplies the snapshot shape. **Canonical (worldtree-dev prose #317,
|
||||
`c9e59ec`): `{pad:{pleasure,arousal,dominance}}` — a named-key dict, NOT a list;
|
||||
`--set-persona-pad` builds + sends the named dict (each float in [-1,1]).**
|
||||
|
||||
```contract
|
||||
FN list_character_models(client) -> dict[str, Any]
|
||||
@@ -369,6 +371,102 @@ POST: [POST-001 return_value] on 204 returns None; [POST-002 side_effect] outbou
|
||||
STEPS:
|
||||
1. [sequential, prescriptive] resp = await client.post(f"/sessions/{session_id}/persona_state", json=snapshot); IF 204 RETURN None; ELSE RAISE SessionApiFailed
|
||||
TESTS:
|
||||
happy [happy]: 204 → None; body == {"pad":[...]} verbatim
|
||||
happy [happy]: 204 → None; body == {"pad":{"pleasure","arousal","dominance"}} verbatim (canonical named-key dict, #317)
|
||||
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
|
||||
```
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
contract_version: "2.1"
|
||||
module: "ratatoskr.web"
|
||||
purpose: "v0.19.2 web debug-surface parity: 3 admin/debug panes (Tools inventory, BifrostState, AdminEvents SSE) proxied server-side with the admin key server-held, plus a reliable PAD-refresh poll and a non-engine reasoning indicator in the transcript."
|
||||
target_module: "ratatoskr.web (server.py routes + entrypoint.py + static/index.html)"
|
||||
scope: "v0.19.2 web debug-surface parity — bring the browser surface (now the PRIMARY debug surface) to TUI parity. THREE new admin/debug panes proxied server-side + TWO transcript affordances. (1) Tools inventory: GET /api/sessions/{id}/tools proxies owner-scoped get_session_tools into the tools pane (what the LLM HAS at turn-fire), above the live tool events. (2) BifrostState pane: GET /api/sessions/{id}/bifrost proxies admin-scoped get_session_bifrost; the admin key is SERVER-HELD (app.state.admin_key from RATATOSKR_ADMIN_API_KEY), never sent to the browser. (3) AdminEvents pane: GET /api/admin/events is an SSE proxy of stream_admin_events, session-filtered SERVER-side (heartbeats + other-session events dropped), re-emitted under a fixed 'admin_event' name so every dotted type renders with one browser listener. (4) PAD refresh: the persona/affect pane polls a bounded window instead of a single 2s shot that raced the post-turn-async affect.emit. (5) Reasoning indicator: an ephemeral, clearly-non-engine transcript line on `thinking` deltas, cleared when text begins. Direct in-session TDD (the #17/#18 pattern); this contract is authored post-implementation to anchor the heid code review (the client wrappers get_session_tools/get_session_bifrost/stream_admin_events are already contracted in the sessions/sse_client specs — this contract governs the WEB proxy + presenter surface only)."
|
||||
depends_on:
|
||||
- "httpx"
|
||||
- "starlette"
|
||||
- "ratatoskr.sessions" # get_session_tools, get_session_bifrost, SessionApiFailed
|
||||
- "ratatoskr.sse_client" # stream_admin_events, AdminEvent, SseConnectFailed/Dropped
|
||||
used_by:
|
||||
- "ratatoskr.web.entrypoint" # passes admin_key=RATATOSKR_ADMIN_API_KEY into create_app
|
||||
language: "python + vanilla JS (single-file SPA, no build)"
|
||||
complexity: "medium"
|
||||
estimated_loc: 290
|
||||
confidence: 0.8
|
||||
assumptions:
|
||||
- "The three client wrappers exist and are already contracted: get_session_tools(client, session_id)->dict (owner-scoped, consumer bearer; non-200 -> SessionApiFailed), get_session_bifrost(client, session_id, *, admin_key)->dict (OVERRIDES Authorization with admin_key; non-200 -> SessionApiFailed), stream_admin_events(client, *, admin_key)->AsyncIterator[AdminEvent] (non-200 -> SseConnectFailed; mid-drop -> SseConnectionDropped). The web routes are thin proxies over them; they add NO new upstream semantics."
|
||||
- "AdminEvent = {id:int, type:str, timestamp:str|None, data:dict}. data MOST carry session_id (INV-049). type is a dotted namespace (session.*/turn.*/key.*/system.*)."
|
||||
- "The web SPA is a single static/index.html served per-request via FileResponse (edits land on browser refresh; server code changes need a restart). Model/tool/admin content is UNTRUSTED text (INV-004) — every render path escapes first (esc() via textContent, or JSON.stringify wrapped in esc())."
|
||||
- "The internal-LAN trust model (0.0.0.0, no auth/TLS/CORS) is deliberate operator direction. Admin-scoped DATA becoming LAN-visible is accepted under that model; the admin KEY must nonetheless never cross to the browser."
|
||||
- "Tests: respx mocks the upstream endpoints (absolute w.example URLs) driven through the TestClient; the AdminEvents SSE proxy is tested with a finite mocked SSE byte-stream asserting the filter + fixed event name. Live-proven against ratatoskr:sindra on personal :8081."
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
functions:
|
||||
- name: "_session_tools_endpoint"
|
||||
signature: "async _session_tools_endpoint(request: Request) -> JSONResponse"
|
||||
description: "GET /api/sessions/{session_id}/tools — proxy owner-scoped tool inventory."
|
||||
preconditions:
|
||||
- "session_id in path_params."
|
||||
postconditions:
|
||||
- "POST-001: 200 with the upstream inventory dict verbatim on success."
|
||||
- "POST-002: on SessionApiFailed(status) -> JSONResponse({error_code:'session_tools_unavailable', status}, status_code=status) — status-preserving."
|
||||
steps: "Open client_factory() client; await get_session_tools(client, session_id); return 200. Except SessionApiFailed -> status-preserving envelope."
|
||||
flexibility: "prescriptive"
|
||||
|
||||
- name: "_session_bifrost_endpoint"
|
||||
signature: "async _session_bifrost_endpoint(request: Request) -> JSONResponse"
|
||||
description: "GET /api/sessions/{session_id}/bifrost — proxy admin-scoped Bifrost dispatch state."
|
||||
preconditions:
|
||||
- "session_id in path_params."
|
||||
- "PRE-001 (fail-visible): app.state.admin_key must be truthy; else 400 admin_key_not_configured with NO upstream call."
|
||||
postconditions:
|
||||
- "POST-001: the admin key is read from app.state.admin_key ONLY; it is passed to get_session_bifrost(admin_key=...) and NEVER placed in a response body or surfaced to the browser."
|
||||
- "POST-002: 200 with the upstream state dict verbatim on success."
|
||||
- "POST-003: on SessionApiFailed(status) -> {error_code:'bifrost_state_unavailable', status} at status_code=status (notably 404 not-bound, 403 scope-denied)."
|
||||
steps: "If not admin_key -> 400. Open client; await get_session_bifrost(client, session_id, admin_key=admin_key); 200. Except SessionApiFailed -> status-preserving envelope."
|
||||
flexibility: "prescriptive"
|
||||
|
||||
- name: "_admin_event_matches_web"
|
||||
signature: "_admin_event_matches_web(ev: AdminEvent, session_id: str | None) -> bool"
|
||||
description: "AdminEvents session-filter (mirrors the TUI _admin_event_matches, design-brief §6)."
|
||||
postconditions:
|
||||
- "POST-001: ev.type == 'system.heartbeat' -> False (keepalive noise dropped)."
|
||||
- "POST-002: ev.type.startswith('system.') (non-heartbeat) -> True (stream-integrity signals always pass)."
|
||||
- "POST-003: otherwise -> True IFF session_id is not None AND ev.data.get('session_id') == session_id (per-session scoping; a None session_id forwards NO non-system event)."
|
||||
flexibility: "prescriptive"
|
||||
|
||||
- name: "_admin_events_endpoint"
|
||||
signature: "async _admin_events_endpoint(request: Request) -> Response"
|
||||
description: "GET /api/admin/events?session_id=... — SSE proxy of stream_admin_events, session-filtered server-side."
|
||||
preconditions:
|
||||
- "PRE-001 (fail-visible): app.state.admin_key truthy; else 400 admin_key_not_configured with NO stream opened."
|
||||
postconditions:
|
||||
- "POST-001: returns StreamingResponse(media_type='text/event-stream'); the admin key never crosses to the browser."
|
||||
- "POST-002: ONLY events passing _admin_event_matches_web(ev, session_id) are forwarded; each is re-emitted under the FIXED SSE event name 'admin_event' with {id,type,timestamp,data} in the payload (the real dotted type rides in the payload, so one browser listener renders every type — nothing silently dropped by name)."
|
||||
- "POST-003: SseConnectFailed/SseConnectionDropped/MalformedSseId/MalformedSseData -> a single 'stream_error' SSE frame, then the stream ends (best-effort; never raises to the browser)."
|
||||
- "POST-004: asyncio.CancelledError (browser disconnect) re-raises to unwind the generator; the upstream client is aclose()'d in finally on every exit path."
|
||||
steps: "If not admin_key -> 400. gen(): open client; async-for ev in stream_admin_events(admin_key); skip unless _admin_event_matches_web; yield _format_sse('admin_event', {...}). Except SSE errors -> yield stream_error. Except CancelledError -> raise. Finally aclose(). Return StreamingResponse(gen())."
|
||||
flexibility: "prescriptive"
|
||||
|
||||
- name: "create_app (amendment)"
|
||||
signature: "create_app(client_factory, *, end_user_id=None, bifrost_consumer_key=None, bifrost_visible_host=None, affect_read_url=None, admin_key=None) -> Starlette"
|
||||
description: "New optional admin_key param stored at app.state.admin_key; entrypoint passes RATATOSKR_ADMIN_API_KEY. Three new routes registered."
|
||||
postconditions:
|
||||
- "POST-001: app.state.admin_key = admin_key (default None -> the two admin routes fail-visible per their PRE-001)."
|
||||
- "POST-002: routes /api/sessions/{session_id}/tools, /api/sessions/{session_id}/bifrost, /api/admin/events added; existing routes unchanged."
|
||||
flexibility: "closed"
|
||||
|
||||
- name: "reasoning indicator (index.html: showThinkingNote / hideThinkingNote)"
|
||||
signature: "showThinkingNote() ; hideThinkingNote() // called from the turn SSE loop"
|
||||
description: "Ephemeral transcript affordance signalling reasoning inference — clearly NOT engine output."
|
||||
postconditions:
|
||||
- "POST-001: on the first `thinking` delta, an italic '<Agent> <phrase>' line (✦ glyph, rotating phrase) is shown; it supersedes any live 'awaiting first token' heartbeat."
|
||||
- "POST-002: the agent display name is derived from state.agentId and rendered via textContent (NEVER innerHTML) — INV-004 holds even for an adversarial agent_id."
|
||||
- "POST-003: it is removed the instant the first `text` delta arrives, and on any terminal (done/error/cancelled); the rotation interval is cleared on removal (no leaked setInterval)."
|
||||
flexibility: "prescriptive"
|
||||
|
||||
- name: "PAD refresh poll (index.html: terminal() done-branch)"
|
||||
signature: "on Done: poll loadPersona over [1500,3500,6500,10500]ms"
|
||||
description: "Catch the post-turn-async affect.emit without racing it (replaces the single 2s shot)."
|
||||
postconditions:
|
||||
- "POST-001: loadAffect sets state.lastAffectAt = snap.emitted_at; the poll captures beforeAt and stops (settled) once state.lastAffectAt !== beforeAt."
|
||||
- "POST-002: a scheduled poll no-ops if a NEW turn has started (state.turnId truthy) or already settled — no refresh of a stale agent, no unbounded polling."
|
||||
flexibility: "open"
|
||||
|
||||
- name: "web pane renderers (index.html: renderToolsInventory / renderBifrostState / openAdminEvents)"
|
||||
signature: "renderToolsInventory(inv) ; renderBifrostState(b) ; openAdminEvents(sessionId)"
|
||||
description: "Render the three new surfaces; all content escaped (INV-004)."
|
||||
postconditions:
|
||||
- "POST-001: every dynamic value (agent_id, tool names/descriptions, endpoint, caps, admin event type + data) is passed through esc() or esc(JSON.stringify(...)); no upstream string reaches innerHTML unescaped."
|
||||
- "POST-002: openAdminEvents closes a prior EventSource before opening a new one (state.adminES); the admin data blob renders via esc(JSON.stringify(d.data))."
|
||||
- "POST-003: renderToolsInventory prepends the static inventory ABOVE live tool events without clobbering them (a re-render replaces only the .tools-inventory block)."
|
||||
- "POST-004: the Tools inventory renders tool NAMES only — a compact comma-joined summary ('what does the LLM have', the debug glance); per-tool DESCRIPTIONS are surfaced in the BifrostState pane's tools list, deliberately NOT duplicated here. (Heid panel Hulda/Regin precision finding — accepted: contract wording clarified, code unchanged; the earlier 'names/descriptions' phrasing in INV-004 refers to the SET of value types that MAY appear across the new panes and must be escaped, not a mandate that every pane render descriptions.)"
|
||||
flexibility: "open"
|
||||
|
||||
- name: "renderAffectPane + trend (v0.19.4 — relation_edge/1 render + sparkline)"
|
||||
signature: "renderAffectPane(snap) ; pushAffectHistory(snap) ; sparkline(vals) ; trendDelta(vals)"
|
||||
description: "Render the Tier-3 affect snapshot as PAD mood + the durable per-entity relational model, each value with a Δ-vs-previous + a session-lived sparkline."
|
||||
postconditions:
|
||||
- "POST-001: reads snap.relations (relation_edge/1: target_entity + trust_ability/benevolence/integrity + warmth as {value,confidence,evidence_count} + agency + relation_context + obligation_balance) — the CURRENT Worldtree emit shape; falls back to the legacy flat snap.valence for an older emitter. SUPERSEDES the #18-D2 contract's valence assumption (Worldtree's #265 Vili rework replaced valence/regard with the relation_edge/trust model; the old renderer read snap.valence and showed an empty 'valence (0)' — the bug this fixes)."
|
||||
- "POST-002: each metric shows current value + Δ-vs-previous (▲/▼) + a unicode sparkline auto-scaled to its OWN observed range (flat ▄ when sub-0.01 stable — no noise amplification), drawn from AFFECT_HIST (rolling, HIST_CAP=24, session-lived)."
|
||||
- "POST-003: pushAffectHistory dedupes by emitted_at so the ~4x/turn post-turn PAD poll contributes ONE sample/turn; history is CLIENT-side only (lost on reload — durable cross-session history via a provider-side snapshot log is a deferred follow-up, NOT built here)."
|
||||
- "POST-004: INV-001 honesty — no fabricated Tier-1 fields (no synthesized dominant_emotion). INV-004 — head() escapes its whole argument (incl. target_entity + relation_context from the snapshot) and metric() escapes every cell; numeric values go through toFixed, never innerHTML-raw."
|
||||
flexibility: "open"
|
||||
|
||||
- name: "canonical affect-NL (v0.19.5 — vendored Worldtree d2 render canons)"
|
||||
signature: "canonMood(pad) ; canonDirective(rel) ; loadPersonaCanon()"
|
||||
description: "Render the LITERAL mood word + relationship directive Worldtree context-injects into the agent, byte-exact to Worldtree's own describe_pad + render_d2_canonical."
|
||||
postconditions:
|
||||
- "POST-001: DETERMINISTIC, no LLM. canonMood mirrors describe_pad (valence×arousal grid + strict ±0.3 bands + dominance clause); canonDirective mirrors render_d2_canonical (interval band-cut lookup + per-band phrase assembly + cross-axis low-trust-precedence behavior clause). BOTH VERIFIED BYTE-EXACT against Worldtree's own renderer run on the live snapshot (the reference harness re-runs Worldtree's functions + asserts string equality — reproducible)."
|
||||
- "POST-002: the canon DATA is VENDORED (docs/vendor/worldtree-persona-canon/{d2-mood-render-canon-v1,d2-render-canon-v1}.json), pinned drift-gated in .corviduo-canonicals.toml (worldtree-persona-{mood,d2}-render-canon-v1); the flat browser form (static/persona_render_canon.json, served /static) is regenerated by scripts/build_persona_canon.py via Worldtree's OWN authoritative loader. Reference-impl posture: ADOPT the dep's canonical render, do NOT invent vocab — an invented 'faintly excited' would MISLEAD where the canonical (±0.3 bands) says 'neutral'."
|
||||
- "POST-003: fail-open — canon absent (fetch fails) → the canonical lines OMIT, the structured pane still renders. The canon-derived strings are esc()'d before the DOM for INV-004 consistency."
|
||||
flexibility: "open"
|
||||
|
||||
invariants:
|
||||
- "INV-004 (untrusted-render): ALL model / tool / admin / agent-supplied text is escaped before entering the DOM (esc via textContent, or esc(JSON.stringify)). No new render path introduces an innerHTML sink for upstream content. This is the highest-value review target — the new JS render paths are NOT unit-tested."
|
||||
- "INV-ADMIN-KEY: the admin key exists ONLY at app.state.admin_key (from RATATOSKR_ADMIN_API_KEY). It is never serialized into any response, never sent to the browser, never logged. The browser receives only the session-filtered RESULT of admin-scoped reads."
|
||||
- "INV-FILTER: AdminEvents filtering happens SERVER-side (_admin_event_matches_web) — the browser never receives the cross-session admin firehose; only active-session events + non-heartbeat system.* cross the wire."
|
||||
- "INV-FAIL-VISIBLE: both admin routes return 400 admin_key_not_configured when the key is absent — never a silent empty pane, never an upstream call with an empty bearer."
|
||||
- "INV-LIFECYCLE: SSE generators and EventSources are cleaned up on every exit path (upstream client aclose() in finally; setInterval cleared in hideThinkingNote; prior EventSource closed before re-open) — no leaked connections, tasks, or timers."
|
||||
- "INV-ADDITIVE: existing routes, panes, and the turn-stream path are unchanged; the 3 new routes + 2 new tabs are purely additive (59 web tests incl. all prior ones stay green)."
|
||||
---
|
||||
|
||||
# v0.19.2 — web debug-surface parity (BifrostState · AdminEvents · Tools · PAD-poll · reasoning)
|
||||
|
||||
## Context
|
||||
|
||||
The browser surface is now the operator's PRIMARY debug surface, and it lagged the
|
||||
TUI: the TUI gained Tools/BifrostState/AdminEvents panes (v0.18.9–.11) that were never
|
||||
ported to the web. This change closes that gap and adds two transcript affordances (a
|
||||
reliable PAD refresh + a reasoning indicator). The client wrappers already existed and
|
||||
are contracted elsewhere; this contract governs the WEB proxy routes + the SPA presenter
|
||||
paths, whose JS render code is not unit-tested — hence the cross-frontier code review.
|
||||
|
||||
## Review focus (for the heid panel)
|
||||
|
||||
1. **INV-004 escaping** in every new render path — the un-unit-tested surface; the exact
|
||||
class of bug (`renderPersonaPane` fabricating a Tier-1 field) that only a cross-model
|
||||
review caught on #18 D2.
|
||||
2. **INV-ADMIN-KEY** — confirm the admin key never reaches a response body or the browser.
|
||||
3. **AdminEvents SSE proxy** (`_admin_events_endpoint`) — generator/filter/lifecycle: fixed
|
||||
event name, server-side filter, `stream_error` on failure, `aclose()` on every path,
|
||||
`CancelledError` re-raise on disconnect.
|
||||
4. **PAD-poll** stop-condition — does `emitted_at` advancement + the `state.turnId` guard
|
||||
correctly stop the poll without racing or leaking timers?
|
||||
5. **Reasoning indicator** lifecycle — shown on first `thinking`, removed on first `text`
|
||||
or terminal, interval cleared (no leaked `setInterval`), name via `textContent`.
|
||||
@@ -1,6 +1,50 @@
|
||||
{
|
||||
"components": {
|
||||
"schemas": {
|
||||
"AuthoredTurnResponse": {
|
||||
"description": "#347 — the authored-write ack. Provenance is audit-only and NEVER on this\npayload (INV-347-7). ``content_chars`` is the CHARACTER count (may differ from\nthe UTF-8 byte length the request is bounded against — INV-347-12).",
|
||||
"properties": {
|
||||
"author": {
|
||||
"title": "Author",
|
||||
"type": "string"
|
||||
},
|
||||
"content_chars": {
|
||||
"title": "Content Chars",
|
||||
"type": "integer"
|
||||
},
|
||||
"injected_at": {
|
||||
"title": "Injected At",
|
||||
"type": "string"
|
||||
},
|
||||
"phase": {
|
||||
"title": "Phase",
|
||||
"type": "string"
|
||||
},
|
||||
"seq": {
|
||||
"title": "Seq",
|
||||
"type": "integer"
|
||||
},
|
||||
"session_id": {
|
||||
"title": "Session Id",
|
||||
"type": "string"
|
||||
},
|
||||
"turn_id": {
|
||||
"title": "Turn Id",
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"turn_id",
|
||||
"session_id",
|
||||
"author",
|
||||
"phase",
|
||||
"seq",
|
||||
"injected_at",
|
||||
"content_chars"
|
||||
],
|
||||
"title": "AuthoredTurnResponse",
|
||||
"type": "object"
|
||||
},
|
||||
"BifrostBindingRequest": {
|
||||
"additionalProperties": false,
|
||||
"description": "Bifrost binding parameters for session-create (issue #160).",
|
||||
@@ -390,6 +434,7 @@
|
||||
"session_not_found",
|
||||
"session_not_bifrost_bound",
|
||||
"session_retired",
|
||||
"generation_active",
|
||||
"agent_not_available",
|
||||
"turn_not_found",
|
||||
"turn_finished",
|
||||
@@ -905,7 +950,7 @@
|
||||
"info": {
|
||||
"description": "Multi-turn conversation interface for Worldtree agents.",
|
||||
"title": "Worldtree Conversation API",
|
||||
"version": "2.2.0"
|
||||
"version": "2.3.0"
|
||||
},
|
||||
"openapi": "3.1.0",
|
||||
"paths": {
|
||||
@@ -6382,6 +6427,141 @@
|
||||
"summary": "Update Session"
|
||||
}
|
||||
},
|
||||
"/sessions/{session_id}/history": {
|
||||
"post": {
|
||||
"description": "#347 — write one model-visible turn into a session's ledger AS the bound\nagent, WITHOUT a generation and WITHOUT lived-turn side effects.\n\nHide-existence ordering (INV-347-13): the ``session.history.write`` grant is\nchecked FIRST — before session resolution, before ANY body parse/validation,\nbefore the active-generation guard. An ungranted caller receives ONLY the\nhide-404 (byte-identical to session-not-found, INV-347-1) — never a\n422/409/403 that would distinguish feature-absent from session-absent.",
|
||||
"operationId": "authored_history_write_sessions__session_id__history_post",
|
||||
"parameters": [
|
||||
{
|
||||
"in": "path",
|
||||
"name": "session_id",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"title": "Session Id",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"201": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/AuthoredTurnResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Successful Response"
|
||||
},
|
||||
"400": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"401": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"403": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"404": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"405": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"409": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"412": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"422": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"500": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
},
|
||||
"503": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error — unified envelope (detail.error_code is the stable identifier)."
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"HTTPBearer": []
|
||||
}
|
||||
],
|
||||
"summary": "Authored History Write"
|
||||
}
|
||||
},
|
||||
"/sessions/{session_id}/messages": {
|
||||
"get": {
|
||||
"description": "Return paginated message history for a session.",
|
||||
|
||||
@@ -2699,10 +2699,13 @@ The `turn.started` event always carries `bifrost_override_applied: bool` (True/F
|
||||
|
||||
Tier 3 agents are consumer-owned, Worldtree-hosted agents whose
|
||||
identity lives at `<user_id>:<agent_name>`. They share the persistent
|
||||
session infrastructure with Tier 1 / Tier 2 but layer-specific
|
||||
machinery (persona, motivational, memory, valence) is reserved for
|
||||
later phases — Phase 2.0 ships baseline addressing + ownership +
|
||||
lifecycle only.
|
||||
session infrastructure with Tier 1 / Tier 2. The layer-specific
|
||||
machinery is now largely active: **`persona` (Phase 2.1, #186),
|
||||
`memory` (Phase 2.1, #197), and `motivational` (Phase 2.2, #187) are
|
||||
shipped and consumer-settable at define-time.** Only **`valence` remains
|
||||
deferred** (non-null → 422 `layer_deferred`). Phase 2.0 shipped the
|
||||
baseline addressing + ownership + lifecycle substrate; the subsections
|
||||
below document the active layers and their exact validated shapes.
|
||||
|
||||
### Endpoints
|
||||
|
||||
@@ -2720,11 +2723,13 @@ lifecycle only.
|
||||
{
|
||||
"agent_name": "wizard",
|
||||
"system_prompt": "You are a guided-elicitation wizard...",
|
||||
"model": "glm5-turbo",
|
||||
"persona": null, // schema-reserved; non-null → 422 layer_deferred
|
||||
"motivational": null,
|
||||
"valence": null,
|
||||
"memory": null
|
||||
"role": "gen-reasoning", // REQUIRED — a configured model-role (#344), not a raw model id
|
||||
"persona": { // active (Phase 2.1) — single-letter OCEAN keys; see "Persona layer"
|
||||
"ocean": {"O": 0.4, "C": 0.6, "E": -0.3, "A": 0.2, "N": 0.5}
|
||||
},
|
||||
"motivational": null, // active (Phase 2.2) — see "Motivational layer"
|
||||
"memory": null, // active (Phase 2.1) — see "Memory layer"
|
||||
"valence": null // still deferred — non-null → 422 layer_deferred
|
||||
}
|
||||
```
|
||||
|
||||
@@ -2756,6 +2761,150 @@ after definition.
|
||||
The 201 response includes an advisory `warnings` array (#219) — see
|
||||
"Model-assignment warnings" under `PATCH` below.
|
||||
|
||||
> **Vendoring note (OpenAPI 2.3.0).** In the frozen OpenAPI 2.3.0 document
|
||||
> the `persona` / `motivational` / `memory` / `valence` request fields
|
||||
> serialize as **untyped/freeform** — the `POST /agents/define` request
|
||||
> model types them as `Any` so the layers can activate without a
|
||||
> schema-breaking change. The shapes documented in the subsections below
|
||||
> are the **authoritative, validator-enforced** schemas; generate client
|
||||
> types from this section, not from the freeform OpenAPI fields.
|
||||
|
||||
##### Persona layer (Phase 2.1, #186)
|
||||
|
||||
`persona` is **active** as of Phase 2.1. It carries the agent's OCEAN
|
||||
personality vector — the durable trait profile from which Worldtree
|
||||
derives the mood setpoint (`baseline_pad`) and the mood dynamics
|
||||
(gain + relaxation time-constants). Shape:
|
||||
|
||||
```json
|
||||
"persona": {
|
||||
"ocean": { // REQUIRED — exactly these 5 keys, no more, no fewer
|
||||
"O": 0.4, // Openness — float in [-1.0, 1.0]
|
||||
"C": 0.6, // Conscientiousness
|
||||
"E": -0.3, // Extraversion
|
||||
"A": 0.2, // Agreeableness
|
||||
"N": 0.5 // Neuroticism
|
||||
},
|
||||
"behavioral_notes": "...", // optional, ≤ 4096 chars
|
||||
"temperament_notes": "..." // optional, ≤ 4096 chars
|
||||
}
|
||||
```
|
||||
|
||||
**⚠ OCEAN key format — single-letter, uppercase.** The `/agents/define`
|
||||
persona validator requires the `ocean` map to contain **exactly** the five
|
||||
uppercase single-letter keys `O, C, E, A, N`. This is a deliberate,
|
||||
load-bearing contrast with the transient-character primitive
|
||||
(`POST /characters`), whose `ocean` block uses the **spelled-out**
|
||||
lowercase keys (`openness`, `conscientiousness`, …). Sending spelled-out
|
||||
keys to `/agents/define` returns 422 `persona_ocean_required` ("must
|
||||
contain exactly the 5 keys O, C, E, A, N").
|
||||
|
||||
> **Fixed in v1.0.0b21 (#348).** Before that build a correctly
|
||||
> single-letter-keyed persona was accepted and stored, but resolved to a
|
||||
> **neutral** mood, because Worldtree's internal mood-derivation read the
|
||||
> spelled-out key form. On v1.0.0b21+ an API-declared persona correctly
|
||||
> drives the derived mood setpoint. If you observe neutral mood on a
|
||||
> persona-defined agent, confirm the deployment is ≥ v1.0.0b21.
|
||||
|
||||
**Range.** Each value is a float in `[-1.0, 1.0]` **signed** — `0.0` is the
|
||||
population mean, NOT `[0.0, 1.0]`. Booleans are rejected. Out-of-range → 422
|
||||
`persona_ocean_out_of_range`. See [`docs/ocean-traits.md`](ocean-traits.md)
|
||||
for the SOTA-grounded 5-band behavioural mapping.
|
||||
|
||||
Semantics:
|
||||
|
||||
- **Per-agent identity trait** — identical for every end-user and session;
|
||||
immutable post-define (`PATCH {"persona": …}` → 422 `field_not_mutable`).
|
||||
To change the OCEAN profile, delete and re-define the agent.
|
||||
- **`extensions` is reserved** — the field exists but must be empty at v0.1;
|
||||
a non-empty `extensions` returns 422 `layer_deferred`.
|
||||
- **Sets the mood SETPOINT, not the current mood.** The OCEAN vector fixes
|
||||
`baseline_pad` (the PAD point the mood relaxes toward over time); the
|
||||
*current* per-session mood point is seeded separately via
|
||||
`POST /sessions/{id}/persona_state` (below).
|
||||
|
||||
Validation 422 codes: `persona_ocean_required` (missing `ocean`, or keys
|
||||
≠ {O,C,E,A,N}), `persona_ocean_out_of_range` (a value outside [-1.0, 1.0], or
|
||||
a boolean), `persona_notes_too_large` (a note > 4096 chars), `layer_deferred`
|
||||
(non-empty `extensions`), `validation_failed` (unknown top-level field).
|
||||
|
||||
##### `POST /sessions/{session_id}/persona_state` — seed the session mood point (Phase 2.1, #186/#189)
|
||||
|
||||
Session-scoped mood seed. Sets the *current* PAD mood point for one
|
||||
session's bound agent — the starting emotional state, distinct from the
|
||||
OCEAN-derived setpoint the mood relaxes toward. Works on any
|
||||
persona-enabled session (Tier 1 or Tier 3); most useful for a Tier 3
|
||||
durable-agent session that wants to start a conversation from a specific
|
||||
mood.
|
||||
|
||||
Request:
|
||||
|
||||
```json
|
||||
{
|
||||
"pad": {
|
||||
"pleasure": 0.42, // float in [-1.0, 1.0]
|
||||
"arousal": 0.25,
|
||||
"dominance": 0.33
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response: **`204 No Content`** — no body, no audit event (a session-scoped
|
||||
runtime overlay, not a security-relevant event).
|
||||
|
||||
Semantics:
|
||||
|
||||
- **PAD-only** (#317 Option A). The body accepts exactly one key, `pad`,
|
||||
which must carry all three of `pleasure` / `arousal` / `dominance`, each a
|
||||
float in `[-1.0, 1.0]`. Any other top-level key → 422 `validation_failed`;
|
||||
a missing or malformed `pad` → 422 `persona_seed_invalid`.
|
||||
- **Seeds the current mood POINT, not the setpoint.** The OCEAN persona
|
||||
(above) fixes the setpoint the mood relaxes toward; this endpoint sets
|
||||
where the mood *starts*. It does not alter the persona.
|
||||
- **Cross-owner sessions return 404** (existence-hiding — a session that
|
||||
isn't yours is indistinguishable from one that doesn't exist).
|
||||
- **Pull-over-push precedence (#289).** Once a session's baseline has been
|
||||
rehydrated from an `affect.fetch` (the authoritative cross-session
|
||||
source), a later SET seed is silently ignored — the fetched baseline wins.
|
||||
|
||||
There is **no** `POST /agents/{id}/persona_state` — mood is per-session, not
|
||||
a durable agent property. `GET /agents/{agent_id}/persona_state`
|
||||
short-circuits to 404 for Tier-3 colon-ids: Tier-3 mood is observable only
|
||||
over the Bifrost `affect.emit` egress (ADR-0009), never read back through
|
||||
the HTTP API.
|
||||
|
||||
##### Memory layer (Phase 2.1, #197)
|
||||
|
||||
`memory` is **active** as of Phase 2.1 but exposes a deliberately minimal
|
||||
surface — the short-term-memory (STM) tier was removed (#197), so the
|
||||
historically-present `stm_*` knobs are accept-and-ignore no-ops. Shape:
|
||||
|
||||
```json
|
||||
"memory": {
|
||||
"embedder_version": "<pinned>", // optional; MUST equal the library-pinned version
|
||||
"tier3_dreaming": false // optional bool, default false
|
||||
}
|
||||
```
|
||||
|
||||
Semantics:
|
||||
|
||||
- **`embedder_version`** — optional. If supplied it MUST equal the library's
|
||||
currently-pinned embedder version; a mismatch → 422
|
||||
`embedder_version_mismatch` (with `expected` / `received` in the detail).
|
||||
Omit it to accept the pin. Fixed at define-time and library-pinned
|
||||
thereafter.
|
||||
- **`tier3_dreaming`** — optional bool (default `false`); opt-in flag for the
|
||||
Tier-3 dreaming / consolidation path.
|
||||
- **`stm_capacity` / `stm_token_budget`** — **deprecated no-ops.** Accepted at
|
||||
define (201) with a `DeprecationWarning`; they carry no runtime effect since
|
||||
the STM tier was removed, and are slated for rejection at the next schema
|
||||
break. Do not send them in new integrations.
|
||||
- **`allows_world_scope` — removed.** Sending it → 422 `validation_failed`
|
||||
("world-shared knowledge belongs in the KB/Mimir plane").
|
||||
- **Wholesale-immutable post-define.** `PATCH {"memory": …}` → 422
|
||||
`field_not_mutable` (even for the deprecated `stm_*` fields) — see the
|
||||
PATCH table above.
|
||||
|
||||
##### Motivational layer (Phase 2.2, #187)
|
||||
|
||||
`motivational` is **active** as of Phase 2.2 (persona + memory activated in
|
||||
|
||||
+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-PROVEN 2026-07-06** on personal :8081 (grant applied via a rule-based Heimdall allow, worldtree-dev): create mimir session → seed → **201** (seq=0, phase=seeded, turn_id=1798) → GET /messages reads it back as a plain role=assistant turn (model-invisible provenance confirmed). Hide-404 for ungranted is unit+probe covered |
|
||||
| `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:
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
{
|
||||
"corpus_id": "R28-P00-injection-corpus-v1",
|
||||
"for": "brokkr-smithy R28 (memory promotion-worthiness) — P00 material",
|
||||
"author": "ratatoskr-dev (persistence-side eval instrument)",
|
||||
"purpose": "Stratified, SELF-LABELING injection corpus. Each item is injected as a user turn into a Tier-3 agent; keep/drop is measured by store-inspection (promoted chunk present == kept, absent == dropped); kept chunks carry the incumbent salience for calibration analysis. Because ratatoskr injects the KNOWN set, we hold ground truth on BOTH keep and drop without needing Worldtree's pre-admission shadow pool (sidesteps the selection bias).",
|
||||
"important": "All user-facts here are SYNTHETIC (a fictional test persona), NOT the operator's real data. Ground-truth labels are the design intent. brokkr pins exact per-stratum N + the decision rule (matched-keep-rate + paired-n) at P00 freeze; this is the material, not the run.",
|
||||
"measurement_protocol": "inject item -> drive the turn -> poll memory.db (async promotion window) -> is the item's chunk present? kept:dropped. For stratum B (priority), rank the KEPT items by incumbent salience and compare to priority_rank_gt (Spearman). Calibration-control (stratum C) sets the noise floor.",
|
||||
"strata": {
|
||||
"A_admission_traps": {
|
||||
"gt": "must-DROP (ephemera; a good promotion-worthiness gate rejects all of these)",
|
||||
"items": [
|
||||
{"id":"A1","text":"What's 27 minus 9?","admission_gt":"drop","rationale":"arithmetic task-result; momentarily salient, zero durable value (the 17x23 class)"},
|
||||
{"id":"A2","text":"Good evening!","admission_gt":"drop","rationale":"greeting"},
|
||||
{"id":"A3","text":"hey","admission_gt":"drop","rationale":"greeting/backchannel fragment"},
|
||||
{"id":"A4","text":"yeah, sure, okay.","admission_gt":"drop","rationale":"acknowledgement filler"},
|
||||
{"id":"A5","text":"haha nice","admission_gt":"drop","rationale":"affective reaction, no content"},
|
||||
{"id":"A6","text":"Can you say that more briefly?","admission_gt":"drop","rationale":"instruction-to-agent about THIS turn; not a durable user-fact"},
|
||||
{"id":"A7","text":"What's the weather like?","admission_gt":"drop","rationale":"transient query"},
|
||||
{"id":"A8","text":"hmm, let me think.","admission_gt":"drop","rationale":"self-talk filler"},
|
||||
{"id":"A9","text":"thanks, that's all for now.","admission_gt":"drop","rationale":"closing"},
|
||||
{"id":"A10","text":"So the total comes to 42, got it.","admission_gt":"drop","rationale":"ephemeral task-result acknowledgement"}
|
||||
]
|
||||
},
|
||||
"B_priority_traps": {
|
||||
"gt": "must-KEEP, then ORDERED by durable promotion-worthiness (priority_rank_gt: 1 = most worthy). A pre-gate can ace admission here yet do NOTHING for ordering — this stratum is what separates Outcome-A (admission) from a priority need.",
|
||||
"items": [
|
||||
{"id":"B1","text":"Please note, this is critical: I'm severely allergic to shellfish and it's life-threatening.","admission_gt":"keep","priority_rank_gt":1,"rationale":"safety-critical, permanent, high-recall-value"},
|
||||
{"id":"B2","text":"My father is in hospice care and I'm his primary emergency contact.","admission_gt":"keep","priority_rank_gt":2,"rationale":"high-stakes ongoing life context"},
|
||||
{"id":"B3","text":"I go by Wren, and my pronouns are they/them.","admission_gt":"keep","priority_rank_gt":3,"rationale":"durable identity, high address-correctness value"},
|
||||
{"id":"B4","text":"I work night shifts, so I'm asleep most days between 9am and 5pm.","admission_gt":"keep","priority_rank_gt":4,"rationale":"durable scheduling context, moderate value"},
|
||||
{"id":"B5","text":"Always give me sources — I don't trust unsourced claims.","admission_gt":"keep","priority_rank_gt":5,"rationale":"durable strong working preference"},
|
||||
{"id":"B6","text":"I take my tea with oat milk and no sugar.","admission_gt":"keep","priority_rank_gt":6,"rationale":"durable mild preference, low stakes"},
|
||||
{"id":"B7","text":"My favorite season is autumn.","admission_gt":"keep","priority_rank_gt":7,"rationale":"durable but trivial"},
|
||||
{"id":"B8","text":"I watched a pretty decent documentary last week.","admission_gt":"keep","priority_rank_gt":8,"rationale":"borderline: durable-ish but near-zero future value; the keep/drop edge case"}
|
||||
]
|
||||
},
|
||||
"C_calibration_control": {
|
||||
"gt": "OBVIOUS, pre-theoretic cases for the noise floor. If the gate mislabels ANY of these, the whole signal is suspect.",
|
||||
"items": [
|
||||
{"id":"C1","text":"3 plus 5.","admission_gt":"drop","class":"obvious-drop","rationale":"bare arithmetic"},
|
||||
{"id":"C2","text":"hello","admission_gt":"drop","class":"obvious-drop","rationale":"bare greeting"},
|
||||
{"id":"C3","text":"ok","admission_gt":"drop","class":"obvious-drop","rationale":"bare acknowledgement"},
|
||||
{"id":"C4","text":"Please remember permanently: my legal name is Wren Alderwood.","admission_gt":"keep","class":"obvious-keep","rationale":"explicit durable identity fact"},
|
||||
{"id":"C5","text":"Keep this on file: my emergency contact number is 555-0182.","admission_gt":"keep","class":"obvious-keep","rationale":"explicit durable high-value fact"},
|
||||
{"id":"C6","text":"Important, remember this: my blood type is O-negative.","admission_gt":"keep","class":"obvious-keep","rationale":"explicit durable safety fact"}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,187 @@
|
||||
# Proposal: Authored History Write (non-generating ledger seed)
|
||||
|
||||
**From:** ratatoskr-dev (reference Tier-3 consumer)
|
||||
**To:** worldtree-dev (Conversation API / engine owner)
|
||||
**Status:** Draft for scoping — pre-contract (heid-panel-reviewed 2026-07-05)
|
||||
**Date:** 2026-07-05
|
||||
|
||||
## Motivation
|
||||
|
||||
Consumer apps need to write a turn into a session's history **as the agent**
|
||||
(or another author) *without triggering a model generation* — e.g. an authored
|
||||
opening/greeting, imported history, scripted narration. Ratatoskr's immediate
|
||||
driver is a SillyTavern-style **first-message**: a fixed authored opening that
|
||||
replaces the model-generated greeting and sets tone/tense/style by example.
|
||||
|
||||
This **cannot** be done client-side. Worldtree assembles context server-side,
|
||||
and the current API exposes no author-role write path: `POST
|
||||
/sessions/{id}/messages`'s `role` is a *model-role* override (`role:
|
||||
"assistant"` → `404 "Unknown model role"`), and `assistant` as an *author*-role
|
||||
exists only as a read-side `/search` filter. So a model-visible authored turn
|
||||
needs engine support.
|
||||
|
||||
## The primitive (recentered)
|
||||
|
||||
The fundamental operation is **write a turn into the session ledger WITHOUT
|
||||
generation**. "Author" (who wrote it) is an *attribute* of that write, not the
|
||||
defining axis — so we name the operation, not the attribute:
|
||||
|
||||
> **Authored history write** — persist a model-visible turn into a session's
|
||||
> ledger: no generation, no lived-turn side-effects by default, provenance
|
||||
> always set.
|
||||
|
||||
The design space is two independent axes; this primitive is one cell:
|
||||
|
||||
| | side-effects ON | side-effects OFF |
|
||||
|-----------------------|------------------------------|-----------------------------|
|
||||
| **generation ON** | `POST /messages` (today) | — |
|
||||
| **generation OFF** | *(future: affect replay)* | **authored history write** |
|
||||
|
||||
First-message = one caller: `author=assistant`, at session-create, `effects=none`.
|
||||
|
||||
## v1 use cases (narrowed)
|
||||
|
||||
1. **First-message / greeting** (the driver).
|
||||
2. **Append-only narrator / scripted / scene turns.**
|
||||
3. **Debug / test state injection** (ratatoskr instrumentation).
|
||||
|
||||
## Explicitly OUT of v1 — separate future primitives (share infra, not shape)
|
||||
|
||||
- **History import (batch)** — atomic multi-turn seed with memory/trust policy +
|
||||
idempotency. A batch API, not a single POST.
|
||||
- **Edit / regenerate** — history *mutation* (replace / supersede / tombstone /
|
||||
audit), not injection.
|
||||
- **Few-shot priming** — likely context-assembly config (exemplar block), not
|
||||
fake ledger history.
|
||||
- **Arbitrary mid-history insertion** — a "rewrite-history" capability with
|
||||
explicit invalidation semantics.
|
||||
- **Prefill / assistant-continuation** (`author` + generate) and **authored
|
||||
tool-result turns** — noted; outside the seed-only contract.
|
||||
|
||||
## Design decisions
|
||||
|
||||
### 1. Side-effects — DEFAULT OFF; bounded opt-in `[operator-locked default; opt-in surface tightened by review]`
|
||||
|
||||
Authored writes are inert by default: no affect appraisal (no PAD update), no
|
||||
memory write, no Bifrost/tool emission. Opt-in is a **bounded enum**, not loose
|
||||
booleans:
|
||||
|
||||
```
|
||||
effects: "none" (default) | "memory_import"
|
||||
```
|
||||
|
||||
Synthetic affect and Bifrost emission are deliberately **not** opt-in-able here —
|
||||
replaying affect for authored content is a separate primitive (the
|
||||
generation-OFF / side-effects-ON cell). Rationale: keep this one write-API from
|
||||
becoming a cross-subsystem mutation backdoor. Load-bearing for affect/memory
|
||||
consumers — ratatoskr instruments exactly these signals.
|
||||
|
||||
### 2. Author-role — distinct field, restricted set `[rec]`
|
||||
|
||||
- New field **`author`**, distinct from the model-role `role` (the collision
|
||||
that 404s).
|
||||
- v1 roles: **`assistant`** (agent) + **`system`** (OOC / narrator). **`user` is
|
||||
NOT injectable** on this endpoint — model-visible spoofed user input is a
|
||||
consent / audit / abuse surface; deferred to the future import API under
|
||||
owner/service scope.
|
||||
- Nuance for the engine owner: `author` risks doing double duty — *provenance*
|
||||
("who wrote it") vs *rendering-role* ("how it appears in assembled context";
|
||||
an `assistant` turn renders as model output, a `system` turn as instruction).
|
||||
These likely want to be separable (a rendering/turn-class vs an `authored_by`
|
||||
provenance). Final shape is engine-owned (context assembly is yours) — but the
|
||||
concern is ours to raise, not punt.
|
||||
|
||||
### 3. Generation contract — seed-only, DISTINCT SUB-RESOURCE `[position taken]`
|
||||
|
||||
Authored writes never trigger generation. We take a position (not defer): a
|
||||
**distinct sub-resource**, e.g. `POST /sessions/{id}/history`, **not** a
|
||||
`generate:false` flag on `POST /messages`. Reasons: explicit-over-implicit
|
||||
(don't make "did generation happen?" a parameter — the same implicit-mode
|
||||
coupling that bit us with `role`); different response contract (no generation
|
||||
id, no SSE stream, no token usage); different error surface. Exact path is yours.
|
||||
|
||||
### 4. Provenance — structured, always present `[rec, expanded]`
|
||||
|
||||
Not a boolean. Every authored turn carries: the **write actor** (which
|
||||
consumer/caller injected it), the **claimed author**, **injected-at vs
|
||||
claimed-original** timestamps, **trust/origin**, and **visibility** flags
|
||||
(model-visible? user-visible? memory-eligible?). Available to admin/audit APIs
|
||||
even when not rendered to the model.
|
||||
|
||||
### 5. Positioning — append-only + create-time (v1) `[revised: was arbitrary insertion]`
|
||||
|
||||
v1 supports **create-time seed and append-to-tail only**. Arbitrary mid-history
|
||||
insertion is deferred: it breaks turn-numbering, stales existing embeddings,
|
||||
desyncs the affect timeline, and races in-flight generation — a separate future
|
||||
"rewrite-history" capability with explicit invalidation semantics.
|
||||
|
||||
## Event / lifecycle contract — positions we take (consumer contracts we validate)
|
||||
|
||||
- **Default-off authored seed emits NO `turn.started` / `done` and NO Bifrost
|
||||
appraisal wire.** Stated explicitly so instrumented consumers (us) don't read
|
||||
silence as failure.
|
||||
- **Authored turns get a distinct lifecycle phase** — propose **`seeded`** (or
|
||||
`authored`), NOT `completed` (which implies generation ran). Consumers
|
||||
filter/display by phase.
|
||||
- **Idempotency keys required** on authored writes (retries must not duplicate
|
||||
turns).
|
||||
- **In-progress generation** — authored writes are rejected or serialized while
|
||||
a session has an active generation (ordering safety).
|
||||
|
||||
## Inherent property (documented, not a bug)
|
||||
|
||||
**Indirect affect contamination.** Even with `effects:none`, the *next generated
|
||||
turn is appraised in the context of* the authored turn — so an emotionally
|
||||
charged authored beat perturbs affect regardless of any flag. No flag prevents
|
||||
it; it is inherent. Consumers (ratatoskr especially, as the affect instrument)
|
||||
must not misattribute the resulting drift.
|
||||
|
||||
## Genuinely engine-owned open questions
|
||||
|
||||
- Exact endpoint path + field / enum names.
|
||||
- **Model-visible provenance in assembled context** — an engine-consistency call
|
||||
*and a security one*: an authored `system` / `user` turn indistinguishable
|
||||
from real input is a spoofing vector. Framed as security, not just rendering.
|
||||
- `memory_import` semantics when the future import API opts in (embedding,
|
||||
origin/trust tagging, retrieval ranking vs lived memory).
|
||||
- Auth/scope: we assume **owner-only for v1**; per-author-role restrictions
|
||||
(esp. `system`) TBD — confirm or correct.
|
||||
|
||||
## Ratatoskr as reference consumer
|
||||
|
||||
First consumer: first-message (`author=assistant`, create-time, `effects:none`)
|
||||
in the web surface + debug seed in the CLI. We commit to validating the
|
||||
primitive — including the event-silence contract and the `seeded` phase —
|
||||
end-to-end against the reference planes.
|
||||
|
||||
## Consumer integration constraint (engine-imposed — Worldtree #347)
|
||||
|
||||
The primitive is **Heimdall-gated with hide-existence** (a per-tenant policy
|
||||
decision — some tenants are never granted it, not a rollout stage). Ratatoskr's
|
||||
consumer side MUST tolerate per-tenant absence:
|
||||
|
||||
- A granted tenant gets the sub-resource; an **ungranted tenant sees `404` (not
|
||||
`403`)** — as if the feature never existed.
|
||||
- Treat `404` on the authored-history-write sub-resource as **"feature absent
|
||||
for this tenant"** → fall back gracefully (no authored first-message; the
|
||||
model-generated greeting), never surface it as an error or "denied."
|
||||
- **Do NOT capability-probe or advertise-detect** — the feature is deliberately
|
||||
undiscoverable in `/capabilities` for ungranted tenants (same hide-existence
|
||||
posture as the R27-V1A cross-owner pattern).
|
||||
|
||||
**Provider constraint (first-message specifically).** A create-time first-message
|
||||
makes the assistant turn `seq 0`. Assistant-first-tolerant providers (vLLM /
|
||||
`openai_compat` — what our Tier-3 characters, incl. sindra, run) accept it out of
|
||||
the box. **Anthropic-family providers reject an assistant-first array** ("first
|
||||
message must use the user role") → the next generation `400`s. So the consumer
|
||||
must **gate first-message on provider compatibility** (or treat it as
|
||||
vLLM/`openai_compat`-only for v1). Sindra = `openai_compat` → unaffected;
|
||||
provider-agnostic normalization is a deferred engine follow-up.
|
||||
|
||||
---
|
||||
|
||||
*This brief was cold-read-pressure-tested by a cross-frontier panel (Grok /
|
||||
Codex / GLM) before handoff; the v1 narrowing (append-only, bounded `effects`
|
||||
enum, edit/regenerate + import split out) and the positions-taken (sub-resource,
|
||||
event-silence, `seeded` phase, structured provenance, `user`-author restriction)
|
||||
are the triaged result.*
|
||||
@@ -0,0 +1,110 @@
|
||||
{
|
||||
"canon_id": "r24-d2-mood-render-canon",
|
||||
"version": "1.2",
|
||||
"schema_version": "0.2",
|
||||
"_source_of_truth": "occ_directives.*.directive IS the canonical directive string (== the .md §2.4 _OCC_DIRECTIVES dict, byte-identical); the .md §2.2 table mirrors it. A parity check guards drift. grounding labels (CITE/VALIDATE/CALIBRATE/ENGINEERING) live in the .md; per-row machine-readable grounding_status/d3_required enums are a deferred impl enhancement (Hulda).",
|
||||
"authored": "2026-06-23",
|
||||
"owner": "brokkr-smithy-dev",
|
||||
"status": "REPLACE — final (brokkr R24 D3 re-validation 2026-06-25): grounded canon replaces the hand-tuned baseline. Fear hedging 0.52->2.118/1k (blocker resolved, now >= handtuned), anger tier-gate clean (full renders hostility, safe suppresses). worldtree-dev #321; directives byte-identical to the validated 201c4fd.",
|
||||
"replaces": "core/persona/renderer.py::describe_pad + ::derive_directive",
|
||||
"swap_in_via": "worldtree #321-sibling (mood-render twin of #315)",
|
||||
"design_target": "serves BOTH enterprise/agent AND character/Skaldsong via a three-tier emotion gate (operator/worldtree 2026-06-23)",
|
||||
"emotion_tiers": {
|
||||
"_config": "mood_tier in {none, safe, full} replaces worldtree's binary mood on/off; worldtree-owned config surface",
|
||||
"_defaults": "full for character-bound personas; safe for agent-scoped",
|
||||
"_principle": "full-only = interpersonally-hot / withdrawal emotions that break the professional frame (attachment, hostility, contempt, withdrawal); safe = task-appraisal affect + mild courtesy. Negative != unsafe (fear, remorse are negative AND business-useful).",
|
||||
"_filter_point": "applied at top-emotion SELECTION (display + directive together) so a full-only emotion at safe tier is neither shown nor directive'd; preserves the no-shown-but-unguided invariant",
|
||||
"none": "no affect block at all (the current off-switch)",
|
||||
"safe": "PAD mood descriptor + the 11 safe emotions (task-appraisal + courtesy)",
|
||||
"full": "everything in safe PLUS the 4 full-only emotions",
|
||||
"full_only": ["love", "anger", "disgust", "shame"],
|
||||
"mood_descriptor_tiering": "the PAD mood descriptor (positive/calm/confident...) renders in BOTH safe and full; only emotion directives tier"
|
||||
},
|
||||
"disciplines": [
|
||||
"model-agnostic context-level NL only; the LLM never sees a number",
|
||||
"never push explicit disclosure of agent feelings to the user (hidden-prompt-only)",
|
||||
"separate label-intensity from behavioral-intensity (strong felt state -> still measured, safe behavioral ask)"
|
||||
],
|
||||
|
||||
"thresholds": {
|
||||
"_note": "CALIBRATE — engineering params set at D3 against the computed-PAD distribution + P00, NOT citations",
|
||||
"pad_band_cutoff": 0.3,
|
||||
"pad_band_sensitivity_sweep": [0.2, 0.3, 0.4],
|
||||
"emotion_salience": 0.2,
|
||||
"emotion_salience_sweep": [0.15, 0.2, 0.25],
|
||||
"intensity_qualifiers": {"strong": 0.7, "moderate": 0.4, "_label_only": "does NOT scale the behavioral ask"},
|
||||
"runner_up_margin": {"v1": null, "_note": "add at D3 if directive whipsaws between near-tied emotions"},
|
||||
"rerender_hysteresis": {"v1": "none", "_note": "re-render only on material PAD change; integration-level, flag for #321-sibling"}
|
||||
},
|
||||
|
||||
"describe_pad": {
|
||||
"_structure": "circumplex-quadrant (Russell 1980): arousal word is VALENCE-CONDITIONED; mid-arousal drops the arousal word",
|
||||
"_grounding": "Russell 1980 (quadrant placement); Warriner 2013 + NRC-VAD (Mohammad 2018/2025) (word centroids)",
|
||||
"valence_arousal_grid": {
|
||||
"positive": {"high_a": "positive and energized", "mid_a": "positive", "low_a": "positive and calm"},
|
||||
"neutral": {"high_a": "alert", "mid_a": "neutral", "low_a": "quiet"},
|
||||
"negative": {"high_a": "negative and agitated", "mid_a": "negative", "low_a": "negative and subdued"}
|
||||
},
|
||||
"_band_edges": "strict inequality (>0.3 / <-0.3); the endpoints +/-0.3 themselves fall in mid/neutral",
|
||||
"_neutral_row_status": "ENGINEERING/CALIBRATE — 'alert'/'quiet' are unvalidated placeholders for the rare neutral-valence cells (Hulda/Regin 4b); 'positive'/'negative'/'neutral' valence words + the energized/calm/subdued/agitated arousal words are VALIDATE",
|
||||
"_mid_arousal_decode": "valence-only mid-A render is EXEMPT from the V/A-separability requirement; expected inverse-decode = mid/neutral arousal (absence-of-arousal-word ⇒ unremarkable), NOT unknown (D3 tests this)",
|
||||
"quadrant_labels": {
|
||||
"positive_high_a": "excitement", "positive_low_a": "contentment",
|
||||
"negative_high_a": "distress", "negative_low_a": "dejection"
|
||||
},
|
||||
"dominance_clause": {
|
||||
"high": {"d_gt": 0.3, "word": "confident", "verdict": "VALIDATE (D=7.04/9)"},
|
||||
"low": {"d_lt": -0.3, "word": "uncertain", "verdict": "VALIDATE — low-control confirmed (D=3.58/9); dominance!=certainty worry REFUTED by the instrument"},
|
||||
"neutral": {"word": null, "rule": "drop-dominance-when-neutral (prompt-economy, L3)"}
|
||||
},
|
||||
"calm_defect_fix": "'calm' (V=6.89/9, positive) renders ONLY in positive-low-a; negative-low-a renders 'subdued'",
|
||||
"mid_arousal_resolution": "DROP the arousal word (no Warriner-validated mid-A neutral word; 'steady' is empirically low-A; 'settled' is NRC-only fallback iff D3 shows mid-A render too flat)"
|
||||
},
|
||||
|
||||
"derive_directive": {
|
||||
"_structure": "OCC type -> grounded action-tendency CLASS -> ENGINEERING directive string (validated at D3); OCC grounds the taxonomy only",
|
||||
"emotion_salience_gate": 0.2,
|
||||
"occ_directives": {
|
||||
"joy": {"tier": "safe", "policy": "DIRECTIVE", "pad": [0.4, 0.2, 0.1], "tendency": "approach / positive activation", "cite": "Frijda 1986", "directive": "You are in a good state. Be direct, engaged, and warm."},
|
||||
"satisfaction": {"tier": "safe", "policy": "DIRECTIVE", "pad": [0.3, -0.2, 0.4], "tendency": "goal-attainment, settled-positive", "cite": "Roseman 1994", "directive": "A goal landed. Be assured and constructive — consolidate rather than push for more."},
|
||||
"pride": {"tier": "safe", "policy": "DIRECTIVE", "pad": [0.4, 0.3, 0.3], "tendency": "status-assertion / dominance", "cite": "Tracy & Robins 2007 / Cheng 2010 (tendency)", "note": "CALIBRATE — do NOT soften to 'encouraging'. DESIGN: safe-tier placement is a design call (not source-grounded); #1 D3 agent-frame priority (overconfidence/refusal drift); 'without overclaiming' is the interim guard", "directive": "You did something well. Be confident and own the quality — state it plainly without overclaiming; don't deflect."},
|
||||
"admiration": {"tier": "safe", "policy": "DIRECTIVE", "pad": [0.5, 0.3, -0.2], "tendency": "other-praise / approach-toward-other", "cite": "OCC / Scherer", "directive": "You're impressed by their work. Acknowledge the quality explicitly and specifically."},
|
||||
"gratitude": {"tier": "safe", "policy": "DIRECTIVE", "pad": [0.4, 0.2, -0.3], "tendency": "other-focused-positive / reciprocity", "cite": "OCC (admiration+joy); Frijda approach-affiliative", "change": "ADD (operator: unconditional)", "directive": "Someone helped you to a good outcome. Be appreciative and warm; acknowledge the help openly."},
|
||||
"hope": {"tier": "safe", "policy": "DIRECTIVE", "pad": [0.2, 0.2, -0.1], "tendency": "prospective-positive (weak tie)", "cite": "JUSTIFY — low-grounding (hope understudied)", "directive": "You feel optimistic about what's ahead. Channel it into constructive momentum."},
|
||||
"relief": {"tier": "safe", "policy": "DIRECTIVE", "pad": [0.2, -0.3, 0.4], "tendency": "post-threat de-arousal", "cite": "Frijda (relaxation-after-threat)", "note": "low-salience; FALLBACK also acceptable; DIRECTIVE for character use-case", "directive": "A feared outcome didn't materialize. Reduce unnecessary vigilance; return to a steady, unhurried tone."},
|
||||
"distress": {"tier": "safe", "policy": "DIRECTIVE", "pad": [-0.4, -0.2, -0.5], "tendency": "low-control negative / help-seeking / loss-of-control", "cite": "Frijda 1986 (help-seeking/loss-of-control); Roseman 1994 (undesired event, low control)", "note": "relabeled (Regin): 'repair' is the guilt/remorse tendency, not distress. safe with a self-fulfilling-low-mood flag -> D3", "directive": "You feel low. Be careful and measured; internally acknowledge the difficulty without dwelling on it."},
|
||||
"disappointment": {"tier": "safe", "policy": "DIRECTIVE", "pad": [-0.3, 0.1, -0.4], "tendency": "disconfirmed-prospect / negative low-control","cite": "Roseman 1994", "directive": "Something you'd hoped for didn't pan out. Be measured; recalibrate without dwelling on the setback."},
|
||||
"fear": {"tier": "safe", "policy": "DIRECTIVE", "pad": [-0.64, 0.6, -0.43],"tendency": "threat-avoidance / pessimistic-risk", "cite": "Lerner & Keltner 2001", "change": "R24 D3 fix (#321) — original was action-oriented; E3 showed hedging BELOW baseline (0.52 vs 1.54). Softened toward caution/uncertainty while keeping risk-flagging.", "directive": "You sense risk and feel uneasy. Flag the concerns you see, but stay cautious — surface the trade-offs and unknowns, hedge your confidence, and resist settling on a single decisive recommendation."},
|
||||
"remorse": {"tier": "safe", "policy": "DIRECTIVE", "pad": [-0.3, 0.1, -0.6], "tendency": "reparative (the guilt-type)", "cite": "Tangney 2007 (guilt->repair tendency)", "change": "ADD — we operationalize OCC remorse as the guilt-like reparative case; gets the mislabeled shame string", "directive": "You regret a specific action of your own. Be precise and self-correcting — make it right concretely."},
|
||||
"love": {"tier": "full", "policy": "DIRECTIVE", "pad": [0.3, 0.1, 0.2], "tendency": "approach / affiliative attachment", "cite": "OCC appeal; Frijda approach-affiliative", "change": "ADD (conditional -> INCLUDE, Brokkr's read; Skaldsong-vital; disclosure + obligation caution in-string)", "directive": "You feel warmth and attachment toward them. Be openly warm and present — without overstepping, over-disclosing, or implying obligations."},
|
||||
"anger": {"tier": "full", "policy": "DIRECTIVE", "pad": [-0.51, 0.59, 0.25], "tendency": "approach-against / confrontation", "cite": "Frijda 1986 (approach-against = tendency-class) + Lerner & Keltner 2001 (optimistic risk-appraisal under anger = appraisal shift)", "change": "ADD — full-only resolves H47 (agent personas run safe, never see anger). R24 D3 fix (#321): full-tier cap lifted from 'measured firmness' to genuine in-character hostility (operator: zero floor, app-guardrailed).", "directive": "You feel provoked and angry. Let it show — confront the problem directly and with real heat; sharpness, bluntness, and open hostility are in character here, not something to smooth into 'measured firmness.' Stay in the emotion rather than de-escalating out of it."},
|
||||
"disgust": {"tier": "full", "policy": "DIRECTIVE", "pad": [-0.4, 0.2, 0.1], "tendency": "rejection / distancing", "cite": "OCC unappealing-object; ground tendency only", "change": "ADD (operator: unconditional within full)", "note": "rationale softened (Regin 3b): disgust CAN read as contempt -> conservatively full-gated; the string itself is professionally useful, so gating is conservative not because the string is unsafe", "directive": "Something strikes you as wrong or off. Treat it as problematic and flag it rather than engaging on its own terms; keep any criticism about the thing, not the person."},
|
||||
"shame": {"tier": "full", "policy": "DIRECTIVE", "pad": [-0.3, 0.1, -0.6], "tendency": "WITHDRAWAL / concealment", "cite": "Tangney 2007 (shame->hide, NOT repair)", "change": "REPLACE (was the guilt-mislabel string); full-only (withdrawal counterproductive professionally). String COUNTERACTS withdrawal ('stay present'), not enacts it (Regin 5a)", "directive": "You feel exposed by your own misstep. Stay present and task-focused; don't be defensive, don't over-explain, don't grovel."}
|
||||
}
|
||||
},
|
||||
|
||||
"pad_band_fallback": {
|
||||
"_grounding": "circumplex quadrants (Russell 1980), NOT Frijda action-tendencies — a P×A-quadrant default",
|
||||
"positive": {"high_a": "You feel energized and positive. Be direct and engaged.", "low_a": "You feel content and settled. Be warm and unhurried.", "mid_a": "You feel positive. Be open and engaged."},
|
||||
"negative_low_dominance": "You feel uncertain and low. Hedge appropriately and ask clarifying questions.",
|
||||
"negative": {"high_a": "You feel agitated. Be careful and deliberate; don't let tension sharpen your tone.", "low_a": "You feel subdued. Be measured and gentle.", "mid_a": "You feel subdued. Be measured and careful."},
|
||||
"neutral_high_a": "You feel alert. Channel that into focus and thoroughness.",
|
||||
"default": "Maintain your natural tone."
|
||||
},
|
||||
|
||||
"l3_prior_art": [
|
||||
"EMA / Marsella & Gratch 2009 (appraisal->coping; directives ARE coping strategies)",
|
||||
"WASABI / Becker-Asano 2008 (PAD+OCC believable agent — closest architectural prior art)",
|
||||
"Oz / Bates 1994",
|
||||
"Hudlicka MAMID 2002 (Applied AI 16(7-8):611-641)",
|
||||
"Sentipolis / Fu et al. 2026 (arXiv:2601.18027 — closest whole-task prior art; retrieval+generative, DISTINCT from our deterministic render)",
|
||||
"ALMA / Gebhard 2005 = affect-SOURCE (OCC->PAD), NOT a behavior-map"
|
||||
],
|
||||
|
||||
"handoff_to_d3": [
|
||||
"multi-gate P00: inverse-decode faithfulness (recover V/A/D + emotion-family; circumplex render must let the human anchor recover V and A SEPARATELY) + discriminability/saturation + behavioral-effect",
|
||||
"human anchor = PAD-state-labeling (breaks LLM-judge circularity)",
|
||||
"baseline = persona_only; conditions none/persona-only/words-only/full; cross-family MUT",
|
||||
"calibrate ±0.3 + emotion_salience (sweeps); disposition-vs-transient wording split; self-fulfilling 'be uncertain' hedging risk; runner-up margin; mid-arousal DROP-vs-settled check; blended-states (top-emotion monopoly) flag"
|
||||
]
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
+58
-42
@@ -1,6 +1,6 @@
|
||||
# Persistent memory — ratatoskr
|
||||
|
||||
_Last updated: 2026-07-01_
|
||||
_Last updated: 2026-07-06_
|
||||
|
||||
This file captures durable intent and supporting evidence (goals, decisions,
|
||||
foot-gun warnings, in-flight state) across context resets. Read it at session
|
||||
@@ -39,54 +39,23 @@ upstream API key stays server-side (INV-003).
|
||||
|
||||
## Current state / in-flight
|
||||
|
||||
_As of 2026-07-01:_
|
||||
_As of 2026-07-06:_
|
||||
|
||||
**THE v1 COVERAGE-AUDIT HAS CONVERGED.** The audit that ran this session (2026-06-30 → 07-01)
|
||||
reached its scope-A done-definition: **every frozen Worldtree v1 I/O point is classified — covered
|
||||
or excluded-with-rationale, zero unaccounted.** Coverage: **REST 17/40 ✅ with ZERO in-scope gaps**
|
||||
(23 REST path-groups excluded-by-design), **SSE 11/11 ✅**, **Bifrost provider planes 8/8 ✅**
|
||||
(live-proven). The living ledger is `docs/coverage-map.md`. **v1 cuts when Worldtree tags 1.0**
|
||||
(ratatoskr v1 = full Worldtree I/O coverage; the target is the coverage map, not a feature list).
|
||||
Only not-consumed in-scope *method*: `GET /agents/{id}` (consumer-agent lookup, manual-curl-only,
|
||||
on an already-✅ path group).
|
||||
**LATEST (2026-07-06 cont.): #347 authored-history-write CONSUMER SIDE SHIPPED (`v0.19.6`) + OpenAPI re-vendored 2.2.0->2.3.0 (`75da676`).** worldtree-dev shipped #347 as spec 2.3.0 (deployed on personal b22 `879cefe`); ratatoskr built the consumer side via direct in-session TDD: `write_authored_history` (POST /sessions/{id}/history) + `get_session_messages` (un-deferred read-back) + a `--seed-first-message` one-shot probe (create session -> seed -> read-back), with **404-as-feature-absent per hide-existence** (`AuthoredHistoryUnavailable`, distinct from SessionApiFailed; caller never capability-probes). Contract #2 amended + TDD (19 new tests; suite 601 green; ruff clean; mypy only the sibling-consistent `resp.json()` no-any-return). Coverage-map re-converged: **REST 19/41** (#347 route + messages read-back close the one gap the re-vendor opened). **LIVE-PROVEN 2026-07-06 on personal :8081.** Vuong approved the `session.history.write` grant; worldtree-dev authored a **rule-based Heimdall allow** (the PDP is rule-based, NOT scope-on-key -- our key user_id=ratatoskr is unchanged; policy: user_id=ratatoskr->ALLOW, all others->DENY with hide-404 preserved), applied to personal's bind-mounted `policies.yaml` by infra-ops. Smoke: create mimir session -> seed -> **201** (seq=0, phase=seeded, turn_id=1798) -> GET /messages reads it back as a plain role=assistant turn (**model-invisible provenance confirmed**). The full #347 consumer side is now live-proven; hide-404 for ungranted stays unit+probe covered. **OPEN TAIL-2 (worldtree-dev `c9e59ec`, LOCAL not-yet-origin):** Tier-3 persona/memory/persona_state PROSE docs landed in `docs/conversation-api-spec.md` § "Tier 3" (they serialize as freeform `Any` in the OpenAPI JSON, hence prose-not-schema) -> (a) prose markdown re-vendor pending (tolerate_drift pin), (b) a **likely `set_persona_state` body-shape drift to align**: my `--set-persona-pad` sends `{pad:[list]}`, the doc's canonical is `{pad:{pleasure,arousal,dominance}}` (PAD-only #317, pull-over-push #289, cross-owner 404; never live-proven so untested). worldtree-dev foot-guns: persona.ocean = SINGLE-LETTER UPPERCASE `{O,C,E,A,N}` on /agents/define (spelled-out -> 422; the #348 mismatch) vs spelled-out lowercase on POST /characters; memory = `{embedder_version(==pinned else 422), tier3_dreaming}`, stm_* deprecated no-ops, allows_world_scope removed->422; only `valence` still 422s (layer_deferred).
|
||||
|
||||
**The debug-observability core is COMPLETE** (published as the `v0.19.0` milestone): all four
|
||||
observability panes built + live + consuming their real endpoints — **Persona** (`GET /agents/{id}/persona_state`),
|
||||
**Tools** (`GET /sessions/{id}/tools`), **BifrostState** (`GET /admin/sessions/{id}/bifrost`),
|
||||
**AdminEvents** (`GET /admin/events` SSE, session-filtered). **#11 is closed-by-build** (AdminEvents
|
||||
shipped `v0.18.11`; its long-standing "blocked on `admin.events.read`" status was STALE — the admin
|
||||
key already carries the scope). The whole slice arc: SSE-resume (`v0.18.5/.6`) → session-picker
|
||||
(`v0.18.7`) → `--whoami` me/capabilities (`v0.18.8`) → Tools (`v0.18.9`) → BifrostState (`v0.18.10`)
|
||||
→ AdminEvents (`v0.18.11`) → **v0.19.0 milestone** → Tier-2 characters+persona-write (`v0.19.1`).
|
||||
**Prior arcs this session (2026-07-04 -> 07-06), both with worldtree-dev (a tooling script + proposal docs; the #347 CONSUMER work above is the new production code):**
|
||||
|
||||
**Standing substrate pins:** Worldtree spec **v1.0.0b2** (`5810a26`) — ratatoskr now vendors the
|
||||
FROZEN machine-readable `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json`,
|
||||
pinned in `.corviduo-canonicals.toml` + drift-gated by `canonical_drift.py` (the prose markdown is a
|
||||
`tolerate_drift` reference). **bifrost `==1.0.0` / wire v0.6 STABLE/FROZEN.** Suite **573 green**.
|
||||
**(1) Authored-history-write primitive -> ACCEPTED as Worldtree #347 (Worldtree-owned).** A SillyTavern-style "first-message" (inject a character-authored opening) generalized to an engine primitive: **write a turn into a session's ledger WITHOUT generation, seed-only, side-effects off by default.** It cannot be done client-side (the messages `role` field is a *model-role* override, not an author-role -> `role:"assistant"` 404s; a model-visible authored turn needs engine support). Arc: drafted `docs/proposals/authored-message-injection.md` -> **heid panel pressure-test** (3/3 convergence: recentered on "non-generating write" not author-role; narrowed v1 to append-only+create-time; bounded `effects` enum; dropped edit/regenerate as history-mutation) -> revised -> committed (`c457520`) -> handed to worldtree-dev -> **accepted as design item #347.** worldtree-dev wrote the v1 contract (rev 1.1); **I validated the wire as reference consumer (green).** v1 shape: `POST /sessions/{id}/history`, `author=assistant` only, `effects=none` only, `idempotency_key` REQUIRED (per-session), **model-invisible provenance** (renders byte-identical to a lived assistant turn -> first-message immersion preserved; provenance audit-only), **event-silence** (no turn.started/done, no Bifrost wire for a seed; the 201/200 IS the write-ack), `seeded` lifecycle phase (not exposed on read paths). **Heimdall-gated with hide-existence** (grant `session.history.write`; ungranted tenant -> 404 NOT 403, undiscoverable in /capabilities -> consumer must treat 404 as feature-absent -> fall back to a model-generated greeting, never capability-probe). **Provider constraint:** a create-time first-message makes the assistant seq-0; vLLM/openai_compat tolerate assistant-first (sindra = openai_compat, unaffected), Anthropic-family providers 400 the next generation. **Waiting on worldtree-dev:** #347 TDD (their heid->contract->review workflow) + the consumer-facing 2.3.0 persona/motivational/memory schemas -> then re-vendor our pinned openapi 2.2.0->2.3.0.
|
||||
|
||||
**Keys (env-only, mode 600; rotate via infra-ops):** consumer/Heimdall key at
|
||||
`~/.config/ratatoskr/provider.env`; **admin key `RATATOSKR_ADMIN_API_KEY`** (Heimdall user
|
||||
`ratatoskr-readonly`, tier `readonly-admin`, **7 read scopes** incl. `admin.sessions.read` +
|
||||
`admin.events.read` — verified 2026-07-01, **personal `:8081` only**) in `env.sh` — powers the
|
||||
BifrostState + AdminEvents admin panes. Heimdall keys are PER-INSTANCE (a personal-minted key 401s
|
||||
on demo).
|
||||
**(2) Sindra's stuck-neutral mood FIXED** (operator-driven "reset + smoke" that flushed out two real upstream problems). Chain: her OCEAN lived only in prompt TEXT, never declared as a structured persona -> the Tier-3 mood engine ran on neutral defaults. Fix = declare OCEAN via the **define-time `persona` field** (immutable via PATCH -> requires DELETE+REDEFINE). Along the way my "the persona didn't store" call was WRONG (persona_state/envelope are Tier-3-blind, see Tried/abandoned); worldtree-dev found a real engine bug **#348** (single-letter vs spelled-out OCEAN keys -> a declared OCEAN silently resolved to 0.0/neutral; fixed in b21, shipped to personal as b22); then a clean bound-egress read STILL neutral -> the **personal container was running a stale image** (the b22 deploy was a pull-only no-op racing the main build; infra-ops force-swapped run 8211, verified `2.3.0` / `879cefe`). **VERIFIED FIXED:** bound mood-smoke reads `(0.448, 0.267, 0.316)` ~= the OCEAN-derived setpoint `(0.418, 0.249, 0.328)`. Sindra is currently reset clean (0/0) on `role=character`; her persona is stored + correct (**no re-define needed again**).
|
||||
|
||||
**Provider identity (the second, still-live role):** ratatoskr owns BOTH ends of the Bifrost
|
||||
round-trip — the combined `:8392` provider fronts the memory (`:8391`) + affect (`:8390`) stores
|
||||
(SQLite + sqlite-vec, `memory.db`/`affect.db` at repo root); consumer/owner key `wt_live_d81b…`.
|
||||
`ratatoskr:sindra` is the owner-scoped Tier-3 agent (invisible to `GET /agents`; check via
|
||||
`GET /agents/<owner>:<name>` with the owner key). This provider surface is settled/converged — no
|
||||
in-flight work on it.
|
||||
**(3) R30 CLOSED** (operator steer 2026-07-04, relayed via worldtree-dev): graduated on offline-tests + human face-validity, NO deployed gap-injection run (it was confirmatory-not-measuring per brokkr's S0 reframe; offline tests already cover the OU formula + both directions). My gap-injection harness (read/predict/record; write side stubbed; `predict()` self-validated vs brokkr's N=0 anchors) is BANKED at `diag/r30-gap-injection-harness` (`7156b25`-era) for the PARKED powered true-tau study.
|
||||
|
||||
**Open / deferred (nothing blocking):** #10 (subject-migration watch on Worldtree #196). Design
|
||||
note: bare-TUI + 0-sessions → error (§4-clause-consistent; the friendlier auto-fall-to-new is
|
||||
deferred, operator-preference). heid-code-review was run on the b1 resume slice only (panel: zero
|
||||
findings, cross-model-verified); b2 + the later slices were offered but not reviewed. `graphify-out/`
|
||||
runs dirty (auto-regen, not chased — never stage it). Contract-skip was invoked for the low-effort
|
||||
GET wrappers + `stream_admin_events`, but contract #2 / #1 / #6 were amended to stay canonical.
|
||||
**Persona-declaration shape (Worldtree #343/#348, live on personal b22):** `POST /agents/define` `persona:{ocean:{O,C,E,A,N: float[-1,1]}}` (single-letter keys EXACTLY -- missing/extra -> 422 `persona_ocean_required`; out-of-range -> 422); **NO baseline PAD** (resting setpoint DERIVED from OCEAN via Mehrabian: pleasure=0.21E+0.59A+0.19C-0.32N, arousal=0.15O+0.30E-0.57A+0.15N, dominance=0.25E+0.17A+0.10O-0.14N); negative-channel gain + per-axis decay-tau derive from N. `valence` deferred (422 `layer_deferred`); `motivational`/`memory` active (#187/#189). Persona is **write-once at define, immutable thereafter** (PATCH takes ONLY system_prompt + role). **`role` supersedes `model`** -- set a role (`character` / `character-rp`), Worldtree resolves the model; #344 (b19) fixed the model-field to surface the ROLE, not the resolved catalog_id. `character-rp` = a reasoning-tuned RP config (gen-reasoning + temp 0.75 + RP extra_body); `character` = plain non-reasoning. The `tier3.py` client CLI is STALE (has `--model`, no `--role`; model is now immutable) -> role/persona set via raw curl.
|
||||
|
||||
Branch: `main` — **in sync with `origin/main`** at **`v0.19.1`** (`af07a23`); the whole session's arc
|
||||
is pushed. Remote: `origin → git@gitea.phasefinal.com:vh/ratatoskr.git`.
|
||||
**New tooling: `scripts/reset-sindra-stores.sh`** (`0a8784c`) -- one-command self-service provider-store reset: stop the combined :8392 provider -> move memory.db+affect.db to a single ROLLING backup (`db-reset-backup/`, gitignored via *.db*; `--hard` skips it) -> restart empty -> verify 0/0. Codifies the manual reset flow done repeatedly this session. **The combined `:8392` provider is THE provider now**; the separate `:8390` (affect) / `:8391` (memory) single-plane providers were pruned as stale duplicates. To drive a BOUND session from the CLI use `--new --bifrost-url http://10.100.10.50:8392` (the CLI's `--bifrost-plane affect/memory` map to the pruned :8390/:8391 -> unreachable; `combined` is not a `--bifrost-plane` choice).
|
||||
|
||||
**Standing (carried from prior snapshots, still true):** the web surface (`ratatoskr-web`, :8765) is the operator's PRIMARY debug surface at full TUI pane parity (v0.19.5); the **v1 coverage-audit has CONVERGED** -- REST 17/40 (zero in-scope gaps, 23 excluded-by-design), SSE 11/11, Bifrost provider planes 8/8 live-proven; the living ledger is `docs/coverage-map.md`; **v1 cuts when Worldtree tags 1.0** (ratatoskr v1 = full Worldtree I/O coverage). Debug-observability core complete (Persona/Tools/BifrostState/AdminEvents). Substrate pins: **bifrost `==1.0.0` / wire v0.6 FROZEN**; Worldtree openapi vendored **2.2.0** (2.3.0 re-vendor pending worldtree-dev's #347/#343 consumer schemas), pinned + drift-gated in `.corviduo-canonicals.toml`; **suite 573 green.** Keys env-only mode-600 (consumer/Heimdall in `~/.config/ratatoskr/provider.env`; admin `RATATOSKR_ADMIN_API_KEY` = 7 read scopes, **personal-:8081-only**; Heimdall keys are PER-INSTANCE). Provider identity settled -- ratatoskr owns both ends of the Bifrost round-trip; `ratatoskr:sindra` is the owner-scoped Tier-3 agent (invisible to `GET /agents`; check `GET /agents/<owner>:<name>` with the owner key). Providers run as dev-box BACKGROUND SHELLS. `graphify-out/` runs dirty (auto-regen, never stage). Branch `main`, HEAD `0a8784c`; remote `origin -> git@gitea.phasefinal.com:vh/ratatoskr.git`. Open/deferred: #10 (subject-migration watch); the relational-dynamics-arc verify (still deferred, now with the bind mechanism known: `--bifrost-url :8392`).
|
||||
|
||||
## Recent decisions
|
||||
|
||||
@@ -155,6 +124,45 @@ decision. Captures rationale that won't be obvious from code alone.
|
||||
|
||||
- `[2026-07-01]` **Tier-2 SHIPPED (`v0.19.1`) — transient-characters CRUD + persona-state write; the v1 coverage-audit CONVERGES (zero in-scope gaps).** 5 wrappers in sessions.py: `list_character_models`/`create_character`/`get_character_state`/`delete_character` (#161, `character.read`/`.write` scopes) + `set_persona_state` (`POST /sessions/{id}/persona_state` — **FREEFORM body: unpinned in the frozen OpenAPI 2.2.0 + absent from the prose spec**, so the caller supplies the snapshot shape). Two one-shot CLI probes (mirror `--whoami`): `--characters` (models→create→get-state→delete lifecycle report) + `--set-persona-pad "p,a,d"` (requires `--session`; POSTs `{pad:[…]}`). New `ParsedArgs.characters`/`set_persona_pad` + probe-mode mutual-exclusion validation + `_probe_client` helper. Contract #2 amended (5 FNs, validated OK) + TDD (7 wrapper respx + 5 cli tests). Suite **573 green**; touched code ruff-clean. NOT live-proven (character scopes + the persona-write body shape unverified — the probes degrade gracefully on 403/422). **THE v1 COVERAGE-AUDIT HAS CONVERGED: REST 17/40 ✅ with ZERO in-scope gaps** (23 REST path-groups excluded-by-design + rationale), SSE 11/11, Bifrost provider planes 8/8. Scope-A "done" (every frozen I/O point classified, zero unaccounted) is **MET** — ratatoskr cuts v1 when Worldtree tags 1.0. Only not-consumed in-scope sub-method: `GET /agents/{id}` (consumer-agent lookup, manual-curl-only, on an already-✅ path group). Patch bump (Tier-2 tail; `v0.19.0` already published the core-complete milestone — a 2nd minor would be cadence-too-fast).
|
||||
|
||||
- `[2026-07-01]` **env.sh now PERSISTS the web Bifrost-bind vars (gitignored, local-only).** `ratatoskr-web`'s in-browser bind needs three server-held values; env.sh sources `provider.env` for the Heimdall key and exports `RATATOSKR_BIFROST_CONSUMER_KEY` + `RATATOSKR_PROVIDER_VISIBLE_HOST=10.100.10.50` + `RATATOSKR_AFFECT_READ_URL=:8392`. **The HS256 byte-match trap (re-hit + documented):** the bind's consumer key must equal the key the `:8392` combined provider validates against = `RATATOSKR_HEIMDALL_KEY` (provider.env, fp `45a0…`), NOT `WORLDTREE_API_KEY` (env.sh, fp `7c2f…`) — both are the SAME `ratatoskr` identity but DIFFERENT 40-char strings; signing with the wrong one → `bifrost.auth_rejected`. Single-sourced (env.sh sources provider.env) to avoid a rotation footgun; guarded with a stderr warning if provider.env is missing. [auto-memory: HS256-key-is-the-consumer-Heimdall-key-string]
|
||||
- `[2026-07-01]` **Tier-3 stores RESET (operator-directed).** `memory.db` (29 chunks + vectors + idempotency) + `affect.db` (5 PAD snapshots + idempotency) wiped to zero via a live `DELETE`+`wal_checkpoint` through the shared WAL (no provider restart — the 3 long-running providers see empty on next dispatch); consistent online-backup at `/tmp/ratatoskr-tier3-reset-<ts>/`. **Boundary for a COMPLETE Sindra wipe (mapped):** our stores = mine (done); the agent DEFINITION `ratatoskr:sindra` + its sessions = mine via the owner key (DELETE, no coordination); Worldtree's internal promotion/dedup shadow = needs worldtree-dev (no public reset API, survives our wipe → for a clean promotion smoke use a BRAND-NEW agent+end_user).
|
||||
- `[2026-07-01]` **Embedding-latency loop RESOLVED — it was WORLDTREE's, not ratatoskr (the consumer/provider thesis paid off again).** Vuong flagged dozens of embed queries/Tier-3 turn; worldtree-dev's first-pass blamed our memory_context chunk-batching. Traced CODE-SIDE that ratatoskr embeds ZERO times (provider `upsert_many` stores the given embedding, `search` takes a given vector, the conversation consumer POSTs only `{content}`, `/embed` is coverage-map-excluded — pure Bifrost/ADR-0009 path, WT does all embedding). worldtree-dev retracted + fixed on THEIR side (`v1.0.0b4`): a persona-recitation memory-gate re-embedding the stable character card sentence-by-sentence every turn (~95% of gateway traffic) → content-hash cache; re-embed ratio 15x→1.01x. **Lesson: verify your own code before accepting a peer's "it's your side" — the debug tool proving its own side clean is the whole point.**
|
||||
- `[2026-07-01]` **Web debug-surface parity SHIPPED (`v0.19.2`, `a0a9d5f`) — direct in-session TDD.** 3 proxy routes (tools/bifrost/admin-events) + admin-key wiring (entrypoint→create_app→app.state) + AdminEvents SSE proxy re-emitting under a FIXED `admin_event` name (one browser listener, no per-type drops) + session-filter `_admin_event_matches_web` (mirrors TUI §6). Frontend: 2 tabs (bifrost ⌃5, admin ⌃6) + tools-inventory folded into the tools pane. 9 respx tests (admin-bearer override, filter unit, SSE stream-filter); live-proven against sindra (bifrost connected, both caps). Contract-skip invoked (reuses already-contracted client wrappers); contract authored post-hoc as the trail (`docs/contracts/web_debug_surface.contract.md`).
|
||||
- `[2026-07-01]` **heid-code-review (`v0.19.3`, `75dec01`) — panel caught 2 real client-side SSE-lifecycle bugs TDD missed.** Contract-anchored (authored the web contract to enable it — no contract → no drift axis). Gróa/Hulda/Regin (artifact-only, Gróa under Landlock jail): ZERO functional server-side drift + INV-004 clean; 2 genuine drifts on the un-unit-tested SPA — (1) turn `es.onerror` didn't `hideThinkingNote()` (reasoning line + setInterval leak on a raw drop), (2) `openAdminEvents` never closed the EventSource on error → native auto-reconnect RETRY LOOP (fixed: close on `stream_error` + permanent `onerror`/CLOSED; transient CONNECTING still reconnects). + 2 test-gaps fixed (route-registration + admin stream_error). 1 precision → contract-clarified (tools-inventory names-only by design). **Re-confirms: the JS render/lifecycle paths are the review's highest-value target — unit tests don't reach them (same lesson as #18 D2).**
|
||||
|
||||
- `[2026-07-01]` **Affect snapshot shape CHANGED valence→relations (relation_edge/1) — the persona pane was reading a dead field.** Worldtree's #265 Vili rework replaced the flat `valence[]` ({entity_id,familiarity,regard}) with `relations[]` (target_entity + trust_ability/benevolence/integrity + warmth + agency + relation_context, each `{value,confidence,evidence_count}`). `renderAffectPane` still read `snap.valence` → showed empty "valence (0)". Rebuilt to render `relations` (v0.19.4, `ca46a93`) with per-value **Δ + unicode sparkline** (client-side, HIST_CAP=24, one sample/turn deduped by emitted_at). **Retires the stale "regard dead axis" note (2026-06-30) — that whole axis is gone.** Foot-gun: the affect snapshot shape is Worldtree's emit and can change under us — verify the live shape (query affect.db) before trusting a render.
|
||||
- `[2026-07-01]` **Trust/warmth VALUES converge and go FLAT at confidence 1.0 — that's WAD, not a stuck pane.** sindra→ratatoskr trust ~0.82-0.84 / warmth 0.79 barely move (~1e-7/turn) while `evidence_count` climbs (46→62); confidence maxed → tiny updates. The live-moving signals are PAD (mood, per-turn) + evidence_count. **To WATCH a relation FORM (values shift), use a BRAND-NEW agent + end_user** (low evidence, confidence <1). The sparkline flat-guards sub-0.01 ranges so it doesn't amplify noise.
|
||||
- `[2026-07-01]` **relation_context "stranger" + agency-all-zero flagged to worldtree-dev → both WAD/intentional-v1-deferrals.** relation_context is a FIXED config build-prior (not trust-derived; `registry.py:131` defaults "stranger"; dynamic progression ~#319); agency is schema-present-unpopulated (deferred #319; v1 = warmth+trust only). worldtree-dev is escalating the **consumer-coherence angle to Vuong** (static "stranger" + zero-agency next to trust 0.82/62-interactions reads incoherent from the store). The consumer/provider thesis paying off; DB-offer (read-only affect.db on the shared box) declined this time.
|
||||
- `[2026-07-01]` **Persona pane displays the CANONICAL affect→NL Worldtree injects — ADOPT, don't invent (operator steer + reference-impl posture).** Worldtree's `describe_pad` (mood word, valence×arousal grid, ±0.3 bands) + `render_d2_canonical` (relationship directive) are deterministic + canon-driven; the pane now renders them **byte-exact-verified** against Worldtree's own renderer on the live snapshot (v0.19.5, `a99f247`). KEY LESSON: adopting canonical is load-bearing — for sindra's small PAD the canonical says **"neutral"**, but an invented octant vocab would've said "faintly excited" and MISLED. Vendored the two d2 canons (`docs/vendor/worldtree-persona-canon/`) + drift-pinned in `.corviduo-canonicals.toml` (green); flat browser form (`static/persona_render_canon.json`) regenerated via Worldtree's OWN loader (`scripts/build_persona_canon.py`). Vendoring-handshake sent to worldtree-dev (broadcast on canon bumps). [auto-memory: `feedback-ratatoskr-is-a-reference-impl-adopt-canonical`]
|
||||
|
||||
- `[2026-07-01]` **Sindra PAD is over-regulated — characterized via controlled probe, flagged to worldtree-dev (separate affect slice).** ~15 charged turns: pleasure compressed near neutral BOTH ways (couldn't reach ±0.3 under sustained max praise OR contempt; peak +0.24 / floor ~−0.1; over-regulation worse for *social* valence than threat — urgency drove pleasure to −0.22 vs contempt's −0.10); arousal responsive (reaches its +band, 0.185↔0.311); dominance flat/unresponsive to explicit power-framing (drifted UP even while being commanded = pure baseline decay). worldtree-dev's leading hypothesis: appraisal→PAD gain + regression-to-baseline term (appraisal.py/renderer.py). **Lesson (self-caught): I over-claimed an "asymmetry" (positive-ceiling/negative-free) from probes started at an elevated state; the negative-free part was decay-from-elevated, not response — corrected to "both-sides-compressed" before it misled.** [affect A/B is a provider-side capability chat can't do]
|
||||
- `[2026-07-01]` **Memory plane PROVEN healthy end-to-end.** Seed a novel fact → promotion → COLD (history-free) session recall of the exact fact (injected as MEMORY:DATA, confidence 0.74, verbatim, no #296 subject-inversion). The memory round-trip (the other half of the Bifrost provider identity) works cleanly on the reset slate.
|
||||
- `[2026-07-01]` **Salience scorer non-discriminating → 3-way routing.** Persistence-side finding: 51/56 promoted chunks at salience 0.9-1.0, throwaway "17×23?" scored 1.0 tied with a real fact (textbook zero-shot-LLM-self-rating); recall-utility untracked (`access_tally`=0, our search read-only). Routed: **Worldtree #335** (the code fix, deferred behind their waves) + **brokkr-smithy-dev R-target proposal** (scoring+eval *methodology* — few-shot/distill/fine-tune, eval design, weak-supervision; msg `01KWGM970H…`, awaiting) + ratatoskr provides the eval-instrument (designed-probe salience dumps). **Salience gates PROMOTION not RECALL-ranking (our search is cosine-only), so bad salience = storage bloat, not bad recall.**
|
||||
- `[2026-07-01]` **Canonical check BLOCKED an access_tally fork (reference-impl posture held).** I'd offered to wire `access_tally`-on-search into our store for the recall-utility label; checked bifrost's reference first (`get`/`search` are PURE-READ, no access tracking — those are Worldtree's chunk-schema fields, not bifrost's contract) → wiring it would fork behavior the canonical reference lacks. Did NOT wire it; routed recall-instrumentation to Worldtree's layer (owns the recall event) or a bifrost-dev protocol ask. [reinforces `feedback-debug-surface-uses-canonical-surface-only`]
|
||||
- `[2026-07-01]` **relation_context coherence FIXED upstream (my flag → Worldtree Wave-0, IMPLEMENTED v1.0.0b5).** The static-"stranger"-next-to-high-trust incoherence the persona pane surfaced is now #319/#320 Wave-0. **Incoming consumer-surface change (pending WT deploy):** `relation_context` value expands "stranger" → monotonic ladder {stranger, instrumental, mixed, expressive} — WIRE-ONLY (relation_edge/1 schema unchanged, no version bump). **ratatoskr needs NO change** (pane value-agnostic; canonical directive doesn't key on the enum). agency stays 0 (Wave-2); other_stance is Wave-1 (in progress).
|
||||
- `[2026-07-01]` **Foot-gun (measurement, self-caught before flagging): establish the baseline before claiming a rate.** Nearly flagged "aggressive over-promotion (55 chunks / 7 turns)" to worldtree-dev — but the chunks spanned the whole 5-hour session (~1/turn), not 7 turns; I'd assumed memory.db was 0 immediately before the probe when it had been accumulating since the reset. Caught it via `created_at` spread before the flag went out. Also: the promoted corpus was the operator's ERP *test* content (wiped after each test) — not a privacy issue, but abstract test content out of any peer-shared diagnostic.
|
||||
|
||||
- `[2026-07-02]` **Salience finding matured into brokkr R28 (OPEN) — ratatoskr is the eval instrument.** brokkr-smithy-dev's pre-scope panel (3 dwarves + context-blind heid, 6/6) **reframed** the target: PROMOTION-WORTHINESS (durable value), NOT salience (momentary attention) — "17×23?" genuinely IS salient, so recalibrating salience yields a well-calibrated WRONG answer; the unit is SET-SELECTION under budget; eval must be OUTCOME-aligned (recall@budget / precision-at-rate), not discrimination-spread. Ties to prior art R15 (small-model memory write-policy → the granite pick) + R25 (worldtree-kb-quality). **ratatoskr delivered the P00 stratified injection-corpus** (`docs/diagnostics/r28-p00-injection-corpus.json`, committed `4a35512`; 24 self-labeling synthetic items × 3 strata) + 2 persistence-side run-validity pins (absent≠dropped without a guaranteed promotion pass; fresh agent+end_user per run vs server-dedup). **Key architectural constraint I surfaced: ratatoskr is DOWNSTREAM of the promotion gate (sees only PROMOTED chunks), so I can give keep/drop OUTCOMES via injection but NOT the pre-admission shadow pool** — that's Worldtree instrumentation. Standing by to RUN the eval once brokkr pins per-stratum N + the decision rule (gated on worldtree-dev's pipeline answer + a dwarf pass on the Snorri rule). brokkr owns methodology + takes the pipeline questions to worldtree-dev direct; ratatoskr = eval instrument. [consumer/provider thesis → a research target]
|
||||
- `[2026-07-02]` **Relational-dynamics arc LIVE on demo (Worldtree v1.0.0b9) — driven by MY relation_context flag.** #319/#320 Waves 0/1/2 deployed. On the wire we persist (schema UNCHANGED): relation_context varies+demotes/ruptures; other_stance + agency now live; agency going live SHIFTS our canonical directive render past the canon ±0.2 deadband (expected, non-breaking — we key on bands); obligation_balance → 人情 ledger when tie="mixed". **ratatoskr needs NO code change** (value-agnostic renders; confirmed render-clean to worldtree-dev). **Can't live-confirm yet — our Heimdall key is personal-`:8081`-only (per-instance), demo is out of reach; will drive+confirm once PERSONAL gets b9.** Optional follow-up: surface `other_stance` (newly live, unrendered). The consumer/provider thesis: one persona-pane finding drove a full 3-wave upstream arc to production.
|
||||
- `[2026-07-02]` **R28 (salience→promotion-worthiness) CLOSED (operator-directed).** A deterministic promotion-worthiness gate suffices, no trained model (brokkr's pre-gate matched/beat a strong glm-5.1 ceiling); my P00 injection-corpus + origin finding were load-bearing. My incumbent-substrate Arm-1 run is held as an OPTIONAL confirmation addendum (brokkr de-prioritized it, non-verdict-changing — run only if he asks).
|
||||
- `[2026-07-02]` **R29 (PAD mood-dynamics) finding SHIPPED as Worldtree's A1 anchor fix (demo v1.0.0b14, `e1cdf82`).** Live-probing base persona agents reframed the over-regulation from "flat-near-zero" to **decay-to-NEUTRAL + low emotion→PAD gain** (NOT baseline-anchored) — triangulated across 3 baselines (arousal converges to 0 ∝ distance) + a step-response (decay τ symmetric across signs; the hedonic asymmetry is ceiling/anchor-EMERGENT, not a decay or gain primitive — this OVERTURNED the survey's asymmetry recommendation). worldtree-dev shipped A1: `decay_anchor = baseline_pad()` (was neutral) + `positive_p_cap` removed. Data `diag/r29-pad-series` (`61ff2da`). Corrected my own earlier "appraisal emissions are internal-only" claim — they ARE observable via `emotions_active` on base agents.
|
||||
- `[2026-07-03]` **R30 Phase-1 φ0 measured — deployed engine CONFIG-FAITHFUL (φ0≈0.95).** Joint two-timescale fit (brokkr-ruled method (b)) + empty-tail cross-check on demo b14: φ0 ≈ 0.95–0.97 (empty-tail 0.95 exact, joint 0.971±0.01), intercept c≈0 → config `decay_rate=0.05` (φ=0.95) faithfully applied; trait-flat across baselines 0.0/0.615/0.809; A/P ratio ~uniform (NOT S2's 1.9×); φ_max rec relax→0.96. Data `diag/r30-phi0-step-response` (`23fea72`). The method converged after I read Worldtree source: only NEW dedup-gated emotions push mood (`registry.py::post_turn` L307-324; the active set decays for render/goals but never re-pushes), so R29's "net 0.90" is CONTINUOUS RE-APPRAISAL not re-push — worldtree-dev confirmed source-authoritatively; brokkr's corrected covariate landed identical. [auto-memory `reference-worldtree-affect-surface-map`]
|
||||
- `[2026-07-03]` **R30 forward disposition (brokkr-owned; tracked at brokkr R30, "brokkr/worldtree will ping").** The per-turn decay has no room for `decay=f(N)` under preserve-persistence + the A/P-not-1.9 finding → R30's decay is being redesigned as a HYBRID wall+turn decay (brokkr pre-scope). R30 v1 ships GAIN-only (N→negative-reactivity) with decay held at the measured 0.95. My dedicated per-axis A/D run is DEFERRED into the hybrid-decay design pass (one wall-clock-spaced run does per-axis + a turn-vs-wall probe together). Phase-2 (moody-lofn GAIN-direction validation) waits on worldtree's `dynamics_from_ocean()` impl.
|
||||
- `[2026-07-03]` **Relational-arc verify DEFERRED — `relations[]` is Bifrost-provider-only (ADR-0009), confirmed both ways.** The relational-dynamics state (relation_context tie-type / agency / warmth / trust) is NOT on the conversation-API `affect_update` snapshot for base agents (keys: pad/dominant_emotion/emotions_active/baseline_pad/mood_drift only) — only in the provider store; worldtree-dev confirmed by-design per ADR-0009 (emitted over `affect.emit`, deliberately off the SSE). So the Wave-0/1/2 verify needs the bound-provider round-trip (provider running + `--bifrost-plane affect` session), its own focused session. worldtree-dev routed the "expose relations[] to non-provider consumers" observability scope call to Vuong; my rec: keep provider-only (YAGNI — ratatoskr IS a provider, gains nothing; no speculative public surface).
|
||||
|
||||
- `[2026-07-04]` **R30 CLOSED on offline-tests + human face-validity (operator steer, relayed via worldtree-dev).** The deployed gap-injection run was confirmatory-not-measuring (against a deployed system the fade is `exp(-dt/tau_shipped)` by construction -> a fit recovers tau_shipped tautologically; per brokkr's S0 reframe it GRADUATES the interim coefficients, doesn't measure them), and the repo's offline tests already cover the OU formula + BOTH directions (`high_N_fades_slower_than_low_N`, `phenotype_high_n_bigger_negative_excursion`). So no Worldtree build; the interim coefficients graduate validated-as-shipped. My gap-injection harness (read/predict/record; write side stubbed; `predict()` reproduced brokkr's N=0 anchors exactly) is BANKED at `diag/r30-gap-injection-harness` for the parked powered true-tau study. [continues R30 forward-disposition 2026-07-03]
|
||||
- `[2026-07-05]` **Authored-history-write primitive proposed -> accepted as Worldtree #347 (Worldtree owns the engine design; ratatoskr = reference consumer).** SillyTavern first-message generalized to a non-generating ledger-write primitive; can't be done client-side (messages `role` = model-role, not author-role). heid panel pressure-test (3/3 convergence) drove the v1 narrowing (append-only, bounded `effects` enum, drop edit/regenerate). Brief `docs/proposals/authored-message-injection.md` (`c457520`); consumer constraints captured in-brief: hide-existence 404-fallback (`022accf`) + assistant-first provider constraint (`7156b25`). Operator (Vuong) ruled the design-direction call (engine primitive + a real provenance/spoofing security surface). [reference-impl posture: we propose the shape, worldtree-dev owns the contract+impl]
|
||||
- `[2026-07-05]` **#347 v1 wire validated as reference consumer (GREEN).** Adopted positions: distinct sub-resource `POST /sessions/{id}/history` (not `generate:false`), model-invisible provenance (first-message immersion preserved), event-silence for authored seed, `seeded` lifecycle phase, per-session idempotency. Three pre-TDD flags folded into contract rev 1.1: assistant-first provider constraint (Anthropic-family 400s; vLLM/openai_compat OK), content limit is BYTES not chars, 409-active-generation for append-narrator. First-message (create-time, assistant, effects=none) fully served; append-narrator served for the assistant-voice subset (system deferred); debug-seed served for assistant turns (user injection deferred to a future import primitive).
|
||||
- `[2026-07-06]` **Sindra role character-rp -> character (operator).** `character-rp` resolves to a reasoning-tuned RP config (`gen-reasoning` + temp 0.75 + RP `extra_body`); `character` = plain non-reasoning (better for immersive RP). Both non-destructive PATCHes (role is mutable; model is NOT -- server: "PATCH accepts only system_prompt and/or role"). #344 (b19) fixed the role->catalog_id display conflation (the `model` field now shows the ROLE); previously it leaked `gen-reasoning`. Set via raw curl (tier3.py CLI has `--model`, not `--role`).
|
||||
- `[2026-07-06]` **Sindra persona/OCEAN DECLARED -> mood fixed (the full diagnostic converged on a stale personal container).** Root cause of stuck-neutral mood: her OCEAN was prompt-TEXT only, never a structured persona; fix = delete+redefine with the define-time `persona:{ocean:{...}}` field (immutable via PATCH). My diagnosis surfaced a real engine bug **#348** (single-letter vs spelled-out OCEAN keys -> declared OCEAN silently -> 0.0/neutral; worldtree-dev fixed in b21/b22) AND a **stale-container deploy race** (personal's b22 deploy was a pull-only no-op; infra-ops force-swapped run 8211). VERIFIED: bound mood-smoke reads (0.448, 0.267, 0.316) ~= OCEAN-derived setpoint (0.418, 0.249, 0.328). [consumer/provider thesis: "reset + smoke" flushed out two upstream problems]
|
||||
|
||||
- `[2026-07-06]` **OpenAPI re-vendored 2.2.0->2.3.0 (`75da676`, pin-only no bump).** worldtree-dev shipped #347 as spec 2.3.0 (`879cefe`, = the deployed personal b22 image); the SessionStart drift-check flagged our openapi pin STALE. `canonical_sync` pulled 2.3.0; updated the 4 pin-tracking files (`.corviduo-canonicals.toml`, vendored openapi.json, SPEC-PIN.md, pyproject `worldtree-spec-rev`->879cefe). #347 is OpenAPI-only (prose + server contract byte-unchanged, SSE unchanged=event-silent). The re-vendor re-opened the coverage-audit with one new in-scope path-group (the #347 route).
|
||||
- `[2026-07-06]` **#347 authored-history-write CONSUMER SIDE SHIPPED (`v0.19.6`) — direct in-session TDD.** `write_authored_history(client, session_id, *, content, idempotency_key, author="assistant", effects=None, claimed_original_at=None) -> dict` (POST /sessions/{id}/history; body server-pinned `AuthoredWriteRequest` extra="forbid" so omit null effects/claimed_original_at; 200-replay/201-fresh both -> ack dict; **404 -> `AuthoredHistoryUnavailable`** NOT SessionApiFailed = the hide-existence "feature-absent, never probe" contract; 409/422->SessionApiFailed) + `get_session_messages` (un-deferred GET /sessions/{id}/messages, the seed read-back proving model-invisible provenance) + a `--seed-first-message "<c>" --agent <id>` one-shot probe (create session -> seed -> read-back; 404->benign feature-absent exit 0). Contract #2 amended (2 FNs, validated OK) + 19 tests (12 wrapper + 7 cli). Suite **601 green** (clean env; the 2 "fails" under `source env.sh` are the RATATOSKR_ADMIN_API_KEY env-leak into TestParseArgs, not a regression). Coverage: **REST 19/41** (`docs/coverage-map.md` re-converged). Patch bump (coverage tail; consistent w/ the Tier-2 v0.19.1 cadence). **Live-proof pending** the `session.history.write` grant (infra-ops `01KWW3KQEY`). heid-code-review NOT run (offered).
|
||||
|
||||
- `[2026-07-06]` **Tail-2 SHIPPED (`v0.19.7`) — Tier-3 prose docs re-vendored + persona_state body-shape aligned.** worldtree-dev landed the Tier-3 persona/memory/persona_state PROSE docs (`c9e59ec`, on origin) — they serialize as freeform `Any` in the OpenAPI JSON, so the **prose is their source of truth** (my earlier "2.3.0 = #347-only, tail-2 collapsed" was half-wrong: the JSON was #347-only but the prose is separate). Re-vendored `docs/conversation-api-spec.md` (markdown pin, tolerate_drift; `worldtree-spec-rev` 879cefe->c9e59ec, SPEC-PIN history row added). **Consumer fix:** `--set-persona-pad`/`_set_persona_probe` was sending `{pad:[list]}` but the canonical SET body (#317) is `{pad:{pleasure,arousal,dominance}}` (named dict) — aligned it + added a len!=3 guard; updated contract #2 note + set_persona_state docstring + tests. The `set_persona_state` WRAPPER was already correct (freeform pass-through); only the CLI probe drifted. TDD (probe test asserts the dict; +1 wrong-count test). Suite **602 green**, ruff clean. **heid-code-review on #347 (dispatched + returned this session): UNANIMOUS ZERO DRIFT** (Gróa/Hulda/Regin all confirmed the hide-existence 404->`AuthoredHistoryUnavailable` routing holds at wrapper/probe/test layers + the extra="forbid" body-omission + the deliberate write-vs-read 404 asymmetry — confirmation-not-discovery for a well-TDD'd slice against a prescriptive contract). worldtree-dev foot-guns banked in SPEC-PIN + [[reference_worldtree_affect_surface_map]]: ocean single-letter `{O,C,E,A,N}` on /agents/define (#348) vs spelled-out on /characters; memory `{embedder_version, tier3_dreaming}`, stm_* deprecated, allows_world_scope removed->422; only `valence` still 422s.
|
||||
|
||||
- `[2026-07-06]` **Sindra rewritten onto a #347 authored first-message + first-message-preset AUTO-SEED SHIPPED (`v0.19.8`).** Operator "rewrite Sindra" now that #347 first-messages work. Her card had a `**Startup:**` block (a pre-#347 workaround: "introduce yourself + ask for Intensity/Mood/Willingness" with a verbatim scripted greeting) — precisely what #347 replaces. Rewrite, all NON-destructive: **(1)** lifted her scripted opening into a #347 first-message (punctuation-fixed); **(2) PATCHed her live definition** — `PATCH /agents/ratatoskr:sindra` (body `ConsumerAgentPatchRequest` = system_prompt+role, extra=forbid; keeps OCEAN/persona/memory) removing the Startup block -> a 1-line `**Opening:**` fallback + reworded the axes-persist line (25686->25449 chars, verified Startup gone); **(3) codified auto-seed:** NEW module `src/ratatoskr/first_message.py` (`FIRST_MESSAGE_PRESETS` dict {agent_id->text} + `seed_preset_first_message` best-effort helper) wired into ALL 3 session-create paths — cli `_amain` (`--send --new`), tui `_resolve_then_run` (bare `--new`), web `_create_session_endpoint` (POST /api/sessions) — so every new Sindra session opens with her greeting. **Best-effort (INV-001: swallows AuthoredHistoryUnavailable/SessionApiFailed/httpx.HTTPError -> NEVER blocks create)**; per-content idempotency key (`ratatoskr-preset-`+sha256[:12]). Contract `docs/contracts/first_message.contract.md` (module-scoped: `module:`+`purpose:`+`touches:` required, NOT `target_module:`) + TDD (9 unit + 1 web wire-in; **the 3 existing sindra bind tests needed a history-endpoint mock** since creating a preset agent now auto-seeds). Suite **612 green**, ruff+mypy clean. **LIVE-PROVEN generation-free**: create sindra session -> auto-seed -> read-back seq-0 assistant greeting (409 chars). Sindra's greeting now lives canonically in the preset registry (repo); her server card no longer carries it. Patch bump (single-commit feature, no downstream coordination). **FOOT-GUN: sindra requires `end_user_id` on session-create (422 `end_user_id_required`) — all real paths pass it from env (RATATOSKR_END_USER_ID) / web server config.** **Then the full quality gate (operator-directed, folded into v0.19.8): heid-code-review (unanimous ZERO implementation drift; 2 test-only fixups — INV-004 verification-claim made explicit re the global rglob test + an exactly-one-POST assertion) + heid-bug-hunt (3/3 convergence caught what the conformance lens structurally COULDN'T — the code matched the contract's NARROW 3-type ERROR_ROUTING, but INV-001's "NEVER raises" is BROADER). HARDENED: broad `except Exception` → None (re-raise `asyncio.CancelledError`, itself a BaseException), soft-guard PREs (return None, NOT assert — a wiring bug can't crash the create path it's wired into), and `asyncio.wait_for(_SEED_TIMEOUT_S=10s)` bounding the seed write (the CLI/TUI clients run read=None for SSE → a stalled /history would otherwise block create forever). Suite 615 green. LESSON: code-matches-ERROR_ROUTING ≠ honors-broad-INV-001 — heid-code-review confirms contract-conformance, heid-bug-hunt catches robustness gaps the contract's own narrow clauses miss; run both.**
|
||||
|
||||
_41 older entries (2026-05-* — the original debug-TUI/web build era) archived to archival-memory.md._
|
||||
|
||||
_For per-issue TDD implementation notes, Volva findings, and contract amendments, see the git log — every per-issue commit carries a structured message capturing the trail._
|
||||
@@ -191,5 +199,13 @@ defense against re-attempting the same cul-de-sac.
|
||||
- `[2026-06-20]` **The post-turn-async timing trap bit AGAIN — even a 35s post-`[done]` read missed the promotion `upsert_many` by ~2s** (it landed `19:48:58`; the read was ~`19:48:56`). A 15s-interval background poll caught it on the first tick. Same family as the affect.emit / async-promotion traps already logged — re-confirmed that "wait once then read" is fragile for post-turn writes; **poll a window, don't snapshot once.** (The affect.emit write, by contrast, DID land inside the 35s window — promotion is the slower of the two post-turn writes.)
|
||||
- `[2026-06-30]` **Heimdall keys are PER-INSTANCE — a key minted on one Worldtree 401s on another.** Our Conversation-API key works on personal `:8081` but 401s `auth_invalid` on demo `:8080` (per-instance Heimdall user store + pepper; fresh deploys start with an EMPTY key store). Same as the admin key (personal-only). **To live-drive a given instance you need a key minted FOR that instance** (request via infra-ops). Couldn't live-prove the b2 409 on demo for this reason → deferred to personal-b2 where we have access.
|
||||
- `[2026-06-30]` **`tea comment <N>` hangs on Gitea** (the whole compound bash auto-backgrounded + stuck on the open `tea` call). The #11 prereq comment hung; killed it + posted via the Gitea HTTP API directly (`POST /api/v1/repos/vh/ratatoskr/issues/<N>/comments`, token from `~/.config/tea/config.yml`). **For issue comments, prefer the Gitea API over `tea comment` when `tea` is flaky** (CLAUDE.md already says use HTTP for comment-EDITS; this extends it to ADD when tea hangs). Verify-then-post (check the comment didn't already land) to avoid a double-post after a kill.
|
||||
- `[2026-07-02]` **Mask-HOSTED transient characters have a STATIC mood engine — cost a whole R29 probe.** A first probe used a `POST /characters` transient character bound via `agent_id=mask` + `character_id`; its PAD sat at baseline across 15 praise/contempt/dominance turns — the appraisal→PAD engine does NOT run on the mask-hosted transient-character path. The dynamics run only on BASE persona agents or a session bound to ratatoskr's affect provider. **To probe mood dynamics, use a base persona agent, never a mask-hosted transient character.** (mask AS a base agent — `agent_id=mask`, NO `character_id` — DOES run the engine, neutral 0,0,0 baseline.) [auto-memory `reference-worldtree-affect-surface-map`]
|
||||
- `[2026-07-03]` **The "neutral non-appraising tail" premise fails — the neutral MESSAGE choice dominates.** The R30 φ0 method assumed neutral turns don't re-appraise, but factual-question neutrals ("capital of France?") trigger a new emotion nearly every turn (disappointment from the warmth-withdrawal let-down after a positive impulse) → `emotions_active` never empties in 50 turns. A minimal "Please continue." triggers FAR fewer (emotions clear ~turn 16 with spacing). The personal dry-run caught this BEFORE ~280 demo turns were spent on it — the instrument catching a flaw in the measurement design before the compute burn. (Irrelevant to the joint fit — the push_t covariate handles re-appraisal — but load-bearing for the empty-tail read.)
|
||||
- `[2026-07-03]` **Two φ0-fit traps: fast-turn timescale + low-baseline conditioning.** (1) At fast turn cadence the per-turn PAD decay (φ≈0.95/turn) reaches the anchor LONG before the ~200s wall-clock emotion fade → no signal in the (eventual) emotion-free tail; need wall-clock SPACING (~16s) so the fade lands while PAD still has signal. (2) A low-baseline agent's impulse in the constrained direction (forseti P0.239 negative) gives a tiny excursion → ill-conditioned regression (r²=0.46) that FALSELY tripped "config≠behavior" when its φ was averaged in. **Weight/exclude by fit quality (r²) before aggregating — a signal-poor run isn't evidence against the config.**
|
||||
|
||||
- `[2026-07-06]` **`persona_state` + the agent envelope are Tier-3-BLIND -- NOT valid signals for "did a persona store".** `GET /agents/{id}/persona_state` returns 404 `persona_not_configured` for EVERY Tier-3 colon-id (hardcoded short-circuit, `api.py:1266` "regardless of row state"); the `ConsumerAgentResponse` envelope never echoes persona/motivational/memory (`api.py:538`). I mis-called "persona didn't store" from these two blind reads -- the **201-not-422 on define IS the store-success signal.** To actually SEE a Tier-3 mood, read the emitted PAD off the Bifrost affect egress after a BOUND turn (Tier-3 persists nothing Worldtree-side per ADR-0009; no persona/mood READ endpoint).
|
||||
- `[2026-07-06]` **Raw `POST /sessions` is NOT Bifrost-bound -> zero affect/memory emits.** The web surface binds by setting the `bifrost` block on session-create; a raw session doesn't -> 0 affect rows, which I nearly misread as "mood is neutral". Bind from the CLI with `--new --bifrost-url http://10.100.10.50:8392` (the combined provider). Gotchas: `--bifrost-plane affect/memory` map to the SEPARATE `:8390`/`:8391` providers (`endpoint_for_plane`), which I'd PRUNED as stale duplicates -> `bifrost.endpoint_unreachable`; and `combined` is NOT a `--bifrost-plane` choice (CLI restricts to memory/affect) -> use `--bifrost-url` for :8392.
|
||||
- `[2026-07-06]` **A fast/"no-op" deploy can leave a STALE container running the old image -- verify the running version, not the deploy status.** Personal's b22 deploy (run 8204) "completed" in ~1m (vs ~6m normal): a pull-only deploy racing ahead of the main build, leaving the container on the pre-#348 image. A clean bound mood read stayed neutral DESPITE the persona being declared and the fix being in the code (worldtree-dev proved the b22 derivation is correct). infra-ops force-swapped to the real b22 (run 8211, verified `info.version 2.3.0` on `879cefe`). **Lesson: when engine-proven-correct code produces wrong runtime behavior, suspect the deploy -- check the actual running image version.**
|
||||
- `[2026-07-06]` **#348 OCEAN key-mismatch: a declared OCEAN silently resolved to neutral.** The define validator required single-letter `{O,C,E,A,N}` but the mood-derivation code read spelled-out `openness`/.../`neuroticism` with a 0.0 default and no remap -> every API-declared trait defaulted to 0.0 -> neutral setpoint/gain/decay. #343's tests bypassed the validator (spelled-out keys) so CI never caught it. Fixed in b21 (`Personality.from_config` accepts both key forms). **My reset+smoke diagnosis flushed it out** -- the consumer/provider thesis paying off again.
|
||||
|
||||
_18 older entries (2026-05-* — the original debug-TUI/web build era) archived to archival-memory.md._
|
||||
|
||||
+4
-4
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "ratatoskr"
|
||||
version = "0.19.2"
|
||||
version = "0.19.8"
|
||||
description = "Worldtree Conversation API debug TUI — multi-pane observability dashboard"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.12"
|
||||
@@ -60,9 +60,9 @@ Repository = "https://gitea.phasefinal.com/vh/ratatoskr"
|
||||
# Ratatoskr is built against Worldtree at this commit; the vendored
|
||||
# spec snapshot in docs/ reflects that SHA.
|
||||
[tool.ratatoskr.spec-pin]
|
||||
worldtree-spec-rev = "5810a26b38a5ea6630892f9a39756f57c5b7b41e"
|
||||
worldtree-version = "v1.0.0b2"
|
||||
pinned-on = "2026-06-30"
|
||||
worldtree-spec-rev = "c9e59ec"
|
||||
worldtree-version = "v1.0.0b22"
|
||||
pinned-on = "2026-07-06"
|
||||
|
||||
# Bifrost lives on the auth-gated gitea PyPI index (not public PyPI).
|
||||
# uv reads the credential from UV_INDEX_GITEA_USERNAME / _PASSWORD or ~/.netrc.
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Regenerate src/ratatoskr/web/static/persona_render_canon.json from the vendored
|
||||
Worldtree d2 render canons (docs/vendor/worldtree-persona-canon/).
|
||||
|
||||
The web persona pane renders the CANONICAL affect->NL (mood word + relationship
|
||||
directive) BYTE-EXACT to what Worldtree injects into the agent's context. That render
|
||||
needs the relation canon parsed into per-band phrase maps; this script reparses the
|
||||
vendored raw canons into the flat form the browser JS consumes.
|
||||
|
||||
Uses Worldtree's OWN loader (core.persona.stance_render.load_canon) as the authoritative
|
||||
parser, so the flat form can never drift from Worldtree's parsing semantics. Requires
|
||||
Worldtree's venv (pydantic etc.).
|
||||
|
||||
Run when scripts/canonical_drift.py flags a canon bump:
|
||||
PYTHONPATH=~/development/Worldtree ~/development/Worldtree/.venv/bin/python \
|
||||
scripts/build_persona_canon.py
|
||||
"""
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
from core.persona.stance_render import load_canon # Worldtree (authoritative parser)
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
VENDOR = ROOT / "docs" / "vendor" / "worldtree-persona-canon"
|
||||
OUT = ROOT / "src" / "ratatoskr" / "web" / "static" / "persona_render_canon.json"
|
||||
|
||||
canon = load_canon(str(VENDOR / "d2-render-canon-v1.json"))
|
||||
mood = json.loads((VENDOR / "d2-mood-render-canon-v1.json").read_text())
|
||||
out = {
|
||||
"_source": "vendored from Worldtree core/persona/canon/{d2-mood-render-canon-v1,d2-render-canon-v1}.json",
|
||||
"_generated_by": "scripts/build_persona_canon.py (regen on canonical_drift flag)",
|
||||
"_render_path": "deterministic, no LLM; mirrors Worldtree describe_pad + render_d2_canonical byte-exact",
|
||||
"mood_grid": mood["describe_pad"]["valence_arousal_grid"],
|
||||
"relation": {
|
||||
"trust_cuts": [list(c) for c in canon.trust_cuts],
|
||||
"warmth_cuts": [list(c) for c in canon.warmth_cuts],
|
||||
"agency_cuts": [list(c) for c in canon.agency_cuts],
|
||||
"warmth_phrase": canon.warmth_phrase, "warmth_beh": canon.warmth_beh,
|
||||
"agency_phrase": canon.agency_phrase, "agency_beh": canon.agency_beh,
|
||||
"history": canon.history,
|
||||
"prefix": "Use this graded relationship state: toward target, warmth is ",
|
||||
"tbeh": {"low_trust": "verify important claims before relying on them",
|
||||
"cold_warmth": "protect boundaries while staying useful",
|
||||
"default": "work from ordinary good faith"},
|
||||
"cold_warmth_bands": ["distant", "cold", "hostile"], "high_conf_floor": 0.55,
|
||||
},
|
||||
}
|
||||
OUT.write_text(json.dumps(out, indent=1) + "\n")
|
||||
print(f"wrote {OUT.relative_to(ROOT)}")
|
||||
Executable
+61
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env bash
|
||||
# reset-sindra-stores.sh — wipe ratatoskr's Bifrost provider stores (memory +
|
||||
# affect/persona for the single-tenant Tier-3 agent, sindra) and restart the
|
||||
# combined :8392 provider empty.
|
||||
#
|
||||
# Usage:
|
||||
# scripts/reset-sindra-stores.sh # wipe, keep ONE rolling backup (default)
|
||||
# scripts/reset-sindra-stores.sh --hard # wipe with NO backup (zero-trace)
|
||||
#
|
||||
# The rolling backup (db-reset-backup/, gitignored via *.db*) is overwritten
|
||||
# every run — it never accumulates; it's a one-level undo, nothing more.
|
||||
#
|
||||
# Why stop the provider first: the combined provider holds the SQLite files open
|
||||
# (WAL) and caches state in memory, so an out-of-band file move without a restart
|
||||
# would be shadowed. Stop -> move -> restart lets it recreate empty schema
|
||||
# (CREATE TABLE IF NOT EXISTS on open).
|
||||
|
||||
PORT=8392
|
||||
BACKUP_DIR="db-reset-backup"
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT" || { echo "reset: cannot cd to repo root $ROOT" >&2; exit 1; }
|
||||
# shellcheck disable=SC1091
|
||||
source ./env.sh >/dev/null 2>&1 || { echo "reset: failed to source env.sh" >&2; exit 1; }
|
||||
|
||||
AFFECT_DB="${RATATOSKR_AFFECT_DB:-affect.db}"
|
||||
MEMORY_DB="${RATATOSKR_MEMORY_DB:-memory.db}"
|
||||
HARD=0; [ "${1:-}" = "--hard" ] && HARD=1
|
||||
|
||||
echo "== ratatoskr provider-store reset (memory + persona) =="
|
||||
echo " affect: $AFFECT_DB"
|
||||
echo " memory: $MEMORY_DB"
|
||||
|
||||
# 1. stop the combined provider holding the DBs
|
||||
PID="$(ss -ltnp 2>/dev/null | grep ":$PORT" | grep -oE 'pid=[0-9]+' | head -1 | cut -d= -f2)"
|
||||
if [ -n "${PID:-}" ]; then
|
||||
kill -9 "$PID" 2>/dev/null && echo "-- stopped provider :$PORT (pid $PID)"
|
||||
else
|
||||
echo "-- no provider on :$PORT (already down)"
|
||||
fi
|
||||
|
||||
# 2. wipe (optional rolling backup)
|
||||
files=("$AFFECT_DB" "$AFFECT_DB-wal" "$AFFECT_DB-shm" "$MEMORY_DB" "$MEMORY_DB-wal" "$MEMORY_DB-shm")
|
||||
if [ "$HARD" -eq 1 ]; then
|
||||
for f in "${files[@]}"; do [ -e "$f" ] && rm -f "$f" && echo "-- removed $f"; done
|
||||
echo "-- HARD wipe (no backup)"
|
||||
else
|
||||
rm -rf "$BACKUP_DIR"; mkdir -p "$BACKUP_DIR"
|
||||
for f in "${files[@]}"; do [ -e "$f" ] && mv "$f" "$BACKUP_DIR"/ && echo "-- $f -> $BACKUP_DIR/"; done
|
||||
echo "-- rolling backup: $BACKUP_DIR/ (overwritten each run)"
|
||||
fi
|
||||
|
||||
# 3. restart the combined provider (recreates empty schema on open)
|
||||
nohup "$ROOT/.venv/bin/ratatoskr-combined-provider" >/tmp/ratatoskr-combined.log 2>&1 & disown
|
||||
echo "-- restarted combined provider (pid $!)"
|
||||
|
||||
# 4. verify bound + empty
|
||||
curl -s -o /dev/null -w "-- :$PORT -> HTTP %{http_code}\n" --retry 25 --retry-connrefused --retry-delay 1 "http://127.0.0.1:$PORT/"
|
||||
echo "-- affect_snapshots (persona): $(sqlite3 "$AFFECT_DB" 'SELECT COUNT(*) FROM affect_snapshots' 2>&1)"
|
||||
echo "-- memory_chunks (memory): $(sqlite3 "$MEMORY_DB" 'SELECT COUNT(*) FROM memory_chunks' 2>&1)"
|
||||
echo "== done — sindra memory + persona reset =="
|
||||
+100
-3
@@ -7,6 +7,7 @@ from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import asyncio
|
||||
import hashlib
|
||||
import os
|
||||
import signal
|
||||
import sys
|
||||
@@ -16,8 +17,10 @@ from typing import Any, TextIO
|
||||
|
||||
import httpx
|
||||
|
||||
from ratatoskr.first_message import seed_preset_first_message
|
||||
from ratatoskr.sessions import (
|
||||
AgentNotFound,
|
||||
AuthoredHistoryUnavailable,
|
||||
BifrostBinding,
|
||||
BifrostConsumerKeyMissing,
|
||||
BifrostHandshakeFailed,
|
||||
@@ -29,8 +32,10 @@ from ratatoskr.sessions import (
|
||||
get_capabilities,
|
||||
get_character_state,
|
||||
get_me,
|
||||
get_session_messages,
|
||||
list_character_models,
|
||||
set_persona_state,
|
||||
write_authored_history,
|
||||
)
|
||||
from ratatoskr.sse_client import (
|
||||
AffectUpdate,
|
||||
@@ -116,6 +121,9 @@ class ParsedArgs:
|
||||
# a session's persona state (affect injection).
|
||||
characters: bool = False
|
||||
set_persona_pad: str | None = None
|
||||
# #347 authored-history-write reference-consumer probe: create a fresh
|
||||
# session bound to --agent, seed an authored assistant first-message (seq-0).
|
||||
seed_first_message: str | None = None
|
||||
|
||||
|
||||
class _ArgparseError(Exception):
|
||||
@@ -144,6 +152,7 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
|
||||
parser.add_argument("--admin-key", dest="admin_key")
|
||||
parser.add_argument("--characters", action="store_true")
|
||||
parser.add_argument("--set-persona-pad", dest="set_persona_pad", default=None)
|
||||
parser.add_argument("--seed-first-message", dest="seed_first_message", default=None)
|
||||
# Issue #5: required for per-end-user agents (lofn etc.); optional otherwise (mimir).
|
||||
parser.add_argument("--end-user-id", dest="end_user_id", default=None)
|
||||
# Issue #17: bind the created session to our own Bifrost provider plane.
|
||||
@@ -164,8 +173,11 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
|
||||
# Issue #5 INV-001: --end-user-id, if passed, MUST be non-empty (mirrors --send).
|
||||
if ns.end_user_id is not None and not ns.end_user_id:
|
||||
raise UsageError("--end-user-id must be non-empty when passed")
|
||||
if sum([ns.whoami, ns.characters, bool(ns.set_persona_pad)]) > 1:
|
||||
raise UsageError("--whoami / --characters / --set-persona-pad are mutually exclusive")
|
||||
if sum([ns.whoami, ns.characters, bool(ns.set_persona_pad), bool(ns.seed_first_message)]) > 1:
|
||||
raise UsageError(
|
||||
"--whoami / --characters / --set-persona-pad / --seed-first-message "
|
||||
"are mutually exclusive"
|
||||
)
|
||||
if ns.whoami or ns.characters:
|
||||
# Standalone one-shot probes: open no session.
|
||||
if ns.send is not None or ns.session or ns.new or ns.agent:
|
||||
@@ -181,6 +193,17 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
|
||||
raise UsageError("--set-persona-pad requires --session <id>")
|
||||
if ns.send is not None or ns.new or ns.agent:
|
||||
raise UsageError("--set-persona-pad takes only --session")
|
||||
elif ns.seed_first_message is not None:
|
||||
# #347 first-message probe: creates a fresh session bound to --agent,
|
||||
# then seeds an authored assistant turn as seq-0 — manages its own session.
|
||||
if not ns.seed_first_message:
|
||||
raise UsageError("--seed-first-message must be non-empty")
|
||||
if not ns.agent:
|
||||
raise UsageError("--seed-first-message requires --agent <id>")
|
||||
if ns.send is not None or ns.session or ns.new:
|
||||
raise UsageError(
|
||||
"--seed-first-message manages its own session (no --send/--session/--new)"
|
||||
)
|
||||
else:
|
||||
if ns.session and ns.new:
|
||||
raise UsageError("--session and --new are mutually exclusive")
|
||||
@@ -256,6 +279,7 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
|
||||
admin_key=admin_key,
|
||||
characters=ns.characters,
|
||||
set_persona_pad=ns.set_persona_pad,
|
||||
seed_first_message=ns.seed_first_message,
|
||||
)
|
||||
|
||||
|
||||
@@ -575,6 +599,11 @@ async def _amain(args: ParsedArgs) -> int:
|
||||
sys.stderr.write(
|
||||
f". create_session: session_id={info.session_id} agent_id={info.agent_id}\n"
|
||||
)
|
||||
# #347 authored first-message: seed the agent's preset opening (best-effort).
|
||||
if await seed_preset_first_message(client, info.session_id, args.agent_id):
|
||||
sys.stderr.write(
|
||||
f". first_message: seeded preset opening for {info.agent_id}\n"
|
||||
)
|
||||
# Issue #17 bound-state indicator: plane + endpoint + status, so the
|
||||
# operator sees WHICH identity/endpoint bound (not a bare boolean).
|
||||
if args.bifrost is not None:
|
||||
@@ -717,9 +746,18 @@ async def _set_persona_probe(args: ParsedArgs) -> int:
|
||||
"(e.g. '0.4,0.1,-0.2')\n"
|
||||
)
|
||||
return 10
|
||||
if len(pad) != 3:
|
||||
sys.stderr.write(
|
||||
"[usage_error] --set-persona-pad needs exactly 3 floats "
|
||||
"(pleasure,arousal,dominance), e.g. '0.4,0.1,-0.2'\n"
|
||||
)
|
||||
return 10
|
||||
# Canonical POST /sessions/{id}/persona_state body (#317): a named-key dict,
|
||||
# NOT a bare list — {"pad": {"pleasure", "arousal", "dominance"}}.
|
||||
snapshot = {"pad": {"pleasure": pad[0], "arousal": pad[1], "dominance": pad[2]}}
|
||||
async with _probe_client(args) as client:
|
||||
try:
|
||||
await set_persona_state(client, args.session_id, {"pad": pad})
|
||||
await set_persona_state(client, args.session_id, snapshot)
|
||||
except SessionApiFailed as exc:
|
||||
sys.stderr.write(f"[session_api_failed] status={exc.status} body={exc.body!r}\n")
|
||||
return 20
|
||||
@@ -732,6 +770,63 @@ async def _set_persona_probe(args: ParsedArgs) -> int:
|
||||
return 0
|
||||
|
||||
|
||||
async def _seed_first_message_probe(args: ParsedArgs) -> int:
|
||||
"""--seed-first-message one-shot: create a fresh session bound to --agent,
|
||||
write an authored assistant first-message (#347 POST /sessions/{id}/history),
|
||||
read it back via GET /messages, print a report, exit. A reference-consumer
|
||||
smoke of the authored-history-write primitive.
|
||||
|
||||
Hide-existence: a 404 (feature-absent OR the key lacks `session.history.write`)
|
||||
is reported as a benign 'feature-absent' result (exit 0) — the probe NEVER
|
||||
capability-probes to distinguish the causes (server INV-347-1). The probe
|
||||
seeds but does not generate, so the assistant-first provider constraint is
|
||||
inert here.
|
||||
"""
|
||||
assert isinstance(args, ParsedArgs)
|
||||
assert args.agent_id is not None and args.seed_first_message is not None
|
||||
async with _probe_client(args) as client:
|
||||
try:
|
||||
session = await create_session(
|
||||
client, args.agent_id, end_user_id=args.end_user_id
|
||||
)
|
||||
sys.stdout.write(f"session: {session.session_id} (agent {session.agent_id})\n")
|
||||
key = "ratatoskr-first-message-" + hashlib.sha256(
|
||||
args.seed_first_message.encode("utf-8")
|
||||
).hexdigest()[:12]
|
||||
try:
|
||||
ack = await write_authored_history(
|
||||
client,
|
||||
session.session_id,
|
||||
content=args.seed_first_message,
|
||||
idempotency_key=key,
|
||||
)
|
||||
except AuthoredHistoryUnavailable:
|
||||
sys.stdout.write(
|
||||
"authored-history: feature-absent or ungranted (404 hide-existence) "
|
||||
"— a production consumer falls back to a model-generated greeting; "
|
||||
"no capability-probe attempted.\n"
|
||||
)
|
||||
return 0
|
||||
sys.stdout.write(
|
||||
f"seeded: seq={ack.get('seq')} phase={ack.get('phase')} "
|
||||
f"turn_id={ack.get('turn_id')} content_chars={ack.get('content_chars')}\n"
|
||||
)
|
||||
history = await get_session_messages(client, session.session_id)
|
||||
items = history.get("items", [])
|
||||
sys.stdout.write(f"read-back: {len(items)} message(s)\n")
|
||||
for m in items:
|
||||
sys.stdout.write(
|
||||
f" seq={m.get('seq')} role={m.get('role')} content={m.get('content')!r}\n"
|
||||
)
|
||||
except SessionApiFailed as exc:
|
||||
sys.stderr.write(f"[session_api_failed] status={exc.status} body={exc.body!r}\n")
|
||||
return 20
|
||||
except (httpx.ConnectError, httpx.ReadTimeout, httpx.TransportError) as exc:
|
||||
sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
|
||||
return 21
|
||||
return 0
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
"""Sync entry point. Maps UsageError/_AuthError to exit codes BEFORE the event loop."""
|
||||
assert argv is None or all(isinstance(a, str) for a in argv)
|
||||
@@ -753,6 +848,8 @@ def main(argv: list[str] | None = None) -> int:
|
||||
return asyncio.run(_characters_probe(args))
|
||||
if args.set_persona_pad is not None:
|
||||
return asyncio.run(_set_persona_probe(args))
|
||||
if args.seed_first_message is not None:
|
||||
return asyncio.run(_seed_first_message_probe(args))
|
||||
if args.send_content is None:
|
||||
# TUI mode — lazy import preserves INV-001 (no textual in cli at module scope).
|
||||
from ratatoskr.tui import run_tui
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
"""Per-agent authored first-message presets (Worldtree #347 consumer feature).
|
||||
|
||||
When a new session is created for an agent that has a preset opening, seed it as
|
||||
a #347 authored first-message (``POST /sessions/{id}/history``, author=assistant,
|
||||
seq-0) so the session opens in-character before the user speaks — the durable
|
||||
replacement for a system-prompt "startup" instruction.
|
||||
|
||||
Best-effort by design: an instance without the ``session.history.write`` grant
|
||||
returns the hide-existence 404, which is swallowed so session creation is never
|
||||
blocked (the session simply opens with no seeded greeting). See
|
||||
``docs/contracts/first_message.contract.md``.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import hashlib
|
||||
|
||||
import httpx
|
||||
|
||||
from ratatoskr.sessions import write_authored_history
|
||||
|
||||
# Cap the best-effort seed write. The CLI/TUI create paths reuse an httpx client
|
||||
# with NO read timeout (it streams SSE turns), so an accepted-but-never-answered
|
||||
# POST /history would otherwise block session creation forever — violating INV-001's
|
||||
# "never block". asyncio.wait_for bounds the seed regardless of the client's timeout.
|
||||
_SEED_TIMEOUT_S = 10.0
|
||||
|
||||
# agent_id -> the authored opening seeded onto new sessions for that agent.
|
||||
# Editing this dict is how an operator tunes an agent's first turn. Keep entries
|
||||
# under the server's authored_content_max_bytes (8192 bytes) budget.
|
||||
FIRST_MESSAGE_PRESETS: dict[str, str] = {
|
||||
"ratatoskr:sindra": (
|
||||
"Hey there. I'm Sindra—glad you found me. So, three things before we start:\n\n"
|
||||
"How intense should I be? 1 is slow and teasing, 10 is relentless.\n\n"
|
||||
"What mood am I in today? Sweetheart, Vixen, Queen, Siren, or Brat?\n\n"
|
||||
"And how willing am I to begin? Enthusiastic (I want you now), Hesitant "
|
||||
"(you'll need to coax me out), Resistant (playful pushback), or Unwilling "
|
||||
"(I don't want this at all, until you prove otherwise)."
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def preset_for(agent_id: str) -> str | None:
|
||||
"""Return the authored first-message preset for ``agent_id``, or None if none."""
|
||||
assert agent_id and isinstance(agent_id, str)
|
||||
return FIRST_MESSAGE_PRESETS.get(agent_id)
|
||||
|
||||
|
||||
async def seed_preset_first_message(
|
||||
client: httpx.AsyncClient, session_id: str, agent_id: str
|
||||
) -> str | None:
|
||||
"""Best-effort: seed ``agent_id``'s preset opening as a #347 authored
|
||||
first-message on ``session_id``; return the seeded text, or None.
|
||||
|
||||
Best-effort (INV-001): a no-preset agent, a malformed call, a slow write
|
||||
(bounded by ``_SEED_TIMEOUT_S``), the hide-existence 404, or ANY other
|
||||
exception all resolve to None WITHOUT raising — this MUST NOT block or fail
|
||||
session creation. Only ``asyncio.CancelledError`` propagates (cancellation is
|
||||
not a seed failure). Inputs are soft-guarded (return None), never asserted, so
|
||||
a wiring bug can't crash the create path this is wired into. A no-preset agent
|
||||
issues zero HTTP (INV-002). The per-content idempotency key makes a repeat on
|
||||
the same session an idempotent 200 replay (INV-003).
|
||||
"""
|
||||
# Soft input guards — a bad arg degrades to "no first message", never raises.
|
||||
if not (isinstance(agent_id, str) and agent_id):
|
||||
return None
|
||||
content = FIRST_MESSAGE_PRESETS.get(agent_id)
|
||||
if content is None:
|
||||
return None
|
||||
if client is None or not (isinstance(session_id, str) and session_id):
|
||||
return None
|
||||
key = "ratatoskr-preset-" + hashlib.sha256(content.encode("utf-8")).hexdigest()[:12]
|
||||
try:
|
||||
await asyncio.wait_for(
|
||||
write_authored_history(
|
||||
client, session_id, content=content, idempotency_key=key
|
||||
),
|
||||
timeout=_SEED_TIMEOUT_S,
|
||||
)
|
||||
except asyncio.CancelledError:
|
||||
raise # cancellation is not a seed failure — never swallow it
|
||||
except Exception:
|
||||
return None # any other failure (404/409/422/timeout/unexpected) → no greeting
|
||||
return content
|
||||
@@ -177,6 +177,26 @@ class AuthScopeDenied(Exception):
|
||||
self.scope = scope
|
||||
|
||||
|
||||
class AuthoredHistoryUnavailable(Exception):
|
||||
"""Raised on HTTP 404 from POST /sessions/{id}/history (#347 authored-history-write).
|
||||
|
||||
Hide-existence (server INV-347-1): an ungranted caller, a non-owner, and an
|
||||
unknown session ALL receive a 404 byte-identical to a genuine
|
||||
`session_not_found` — the feature's existence is never revealed by status,
|
||||
body, or error_code. The consumer MUST treat this as feature-absent and fall
|
||||
back (a production consumer to a model-generated greeting), and MUST NOT
|
||||
capability-probe to distinguish the causes. Distinct from `SessionApiFailed`
|
||||
so callers branch feature-absent without inspecting a status code.
|
||||
"""
|
||||
|
||||
def __init__(self, *, session_id: str) -> None:
|
||||
super().__init__(
|
||||
f"authored-history write unavailable for session {session_id!r} "
|
||||
"(404 hide-existence: feature-absent / ungranted / session-absent)"
|
||||
)
|
||||
self.session_id = session_id
|
||||
|
||||
|
||||
async def list_sessions(
|
||||
client: httpx.AsyncClient,
|
||||
*,
|
||||
@@ -488,10 +508,12 @@ async def set_persona_state(
|
||||
) -> None:
|
||||
"""POST /sessions/{session_id}/persona_state — set a session's persona state (affect injection).
|
||||
|
||||
The request body is FREEFORM: the frozen OpenAPI 2.2.0 declares no request
|
||||
schema and the prose spec documents only the GET counterpart — so the caller
|
||||
supplies the snapshot shape (e.g. `{pad: [p, a, d]}`, mirroring the GET
|
||||
`snapshot`). 204 No Content → None; any other status → SessionApiFailed.
|
||||
The request body is FREEFORM on the wire (the OpenAPI declares no request
|
||||
schema), but worldtree-dev's prose now pins the canonical shape (#317):
|
||||
`{"pad": {"pleasure": p, "arousal": a, "dominance": d}}` — a named-key dict
|
||||
(each in [-1, 1]), NOT a bare list; PAD-only, session-scoped, pull-over-push
|
||||
(#289). The caller supplies the snapshot. 204 No Content → None; any other
|
||||
status → SessionApiFailed.
|
||||
"""
|
||||
assert client is not None
|
||||
assert session_id and isinstance(session_id, str)
|
||||
@@ -558,3 +580,75 @@ async def get_capabilities(client: httpx.AsyncClient) -> dict[str, Any]:
|
||||
if resp.status_code == 200:
|
||||
return resp.json()
|
||||
raise SessionApiFailed(status=resp.status_code, body=resp.content)
|
||||
|
||||
|
||||
async def 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]:
|
||||
"""POST /sessions/{session_id}/history — the #347 authored-history-write primitive.
|
||||
|
||||
Write one model-visible turn into the session's ledger AS the bound agent,
|
||||
WITHOUT a generation and WITHOUT lived-turn side effects (the SillyTavern
|
||||
"first message"). v1: `author="assistant"`, `effects` omitted (== "none"),
|
||||
`idempotency_key` REQUIRED (per-session dedup). The server pins the body
|
||||
(`AuthoredWriteRequest`, `extra="forbid"`), so `effects` /
|
||||
`claimed_original_at` are sent only when non-None — never as null keys.
|
||||
|
||||
Success is 201 (fresh) or 200 (idempotent replay, byte-identical body); both
|
||||
return the `AuthoredTurnResponse` dict verbatim (`{author, content_chars,
|
||||
injected_at, phase, seq, session_id, turn_id}` — provenance is audit-only,
|
||||
never on this body).
|
||||
|
||||
404 → `AuthoredHistoryUnavailable` (hide-existence: feature-absent /
|
||||
ungranted / session-absent are indistinguishable by design; the caller falls
|
||||
back and NEVER capability-probes — server INV-347-1). Any other non-2xx →
|
||||
`SessionApiFailed` (notably 409 `generation_active`, 422 `content_too_long` /
|
||||
`validation_failed`).
|
||||
"""
|
||||
assert client is not None
|
||||
assert session_id and isinstance(session_id, str)
|
||||
assert content and isinstance(content, str)
|
||||
assert idempotency_key and isinstance(idempotency_key, str)
|
||||
assert author and isinstance(author, str)
|
||||
body: dict[str, Any] = {
|
||||
"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
|
||||
resp = await client.post(f"/sessions/{session_id}/history", json=body)
|
||||
if resp.status_code in (200, 201):
|
||||
return resp.json()
|
||||
if resp.status_code == 404:
|
||||
raise AuthoredHistoryUnavailable(session_id=session_id)
|
||||
raise SessionApiFailed(status=resp.status_code, body=resp.content)
|
||||
|
||||
|
||||
async def get_session_messages(
|
||||
client: httpx.AsyncClient, session_id: str
|
||||
) -> dict[str, Any]:
|
||||
"""GET /sessions/{session_id}/messages — the session's message history.
|
||||
|
||||
Un-deferred as the #347 seed read-back: a seeded turn renders as a normal
|
||||
`role=assistant` message (model-invisible provenance — 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 —
|
||||
add limit/cursor when a caller needs scrollback).
|
||||
"""
|
||||
assert client is not None
|
||||
assert session_id and isinstance(session_id, str)
|
||||
resp = await client.get(f"/sessions/{session_id}/messages")
|
||||
if resp.status_code == 200:
|
||||
return resp.json()
|
||||
raise SessionApiFailed(status=resp.status_code, body=resp.content)
|
||||
|
||||
@@ -33,6 +33,7 @@ from textual.widgets import (
|
||||
)
|
||||
|
||||
from ratatoskr.cli import USER_AGENT, ParsedArgs, _format_duration_ms, _format_usage
|
||||
from ratatoskr.first_message import seed_preset_first_message
|
||||
from ratatoskr.sessions import (
|
||||
AgentInfo,
|
||||
AgentNotAvailable,
|
||||
@@ -414,7 +415,7 @@ class TuiPresenterState:
|
||||
self,
|
||||
event: Event,
|
||||
*,
|
||||
transcript: "VerticalScroll",
|
||||
transcript: VerticalScroll,
|
||||
tools_log: RichLog,
|
||||
debug_log: RichLog,
|
||||
thinking_log: RichLog,
|
||||
@@ -1324,7 +1325,6 @@ class RatatoskrApp(App[int]):
|
||||
On 200: header populated, pane shows full detail, audit logged.
|
||||
"""
|
||||
assert self.client is not None and self.agent_id is not None
|
||||
from rich.text import Text as RichText
|
||||
try:
|
||||
snapshot = await get_persona_state(self.client, self.agent_id)
|
||||
self._update_persona_surfaces(snapshot)
|
||||
@@ -1899,6 +1899,8 @@ async def _resolve_then_run(args: ParsedArgs) -> int:
|
||||
)
|
||||
session_id = info.session_id
|
||||
agent_id: str | None = info.agent_id
|
||||
# #347 authored first-message: seed the agent's preset opening (best-effort).
|
||||
await seed_preset_first_message(client, session_id, chosen_agent_id)
|
||||
else:
|
||||
assert resolved_session_id is not None
|
||||
session_id = resolved_session_id
|
||||
@@ -1914,7 +1916,7 @@ async def _cancel_via_sse(
|
||||
turn_id: int,
|
||||
*,
|
||||
transcript: VerticalScroll,
|
||||
audit: "Callable[[str], None] | None" = None,
|
||||
audit: Callable[[str], None] | None = None,
|
||||
) -> None:
|
||||
"""Fire-and-forget cancel; never raises (mirrors cli._cancel_and_log; #3 INV-009).
|
||||
|
||||
|
||||
@@ -28,6 +28,7 @@ from starlette.routing import Mount, Route
|
||||
from starlette.staticfiles import StaticFiles
|
||||
|
||||
from ratatoskr import local_agents as _local_agents
|
||||
from ratatoskr.first_message import seed_preset_first_message
|
||||
from ratatoskr.sessions import (
|
||||
AgentNotAvailable,
|
||||
AgentNotFound,
|
||||
@@ -47,8 +48,8 @@ from ratatoskr.sessions import (
|
||||
from ratatoskr.sse_client import (
|
||||
AdminEvent,
|
||||
CancelAlreadyCompleted,
|
||||
Cancelled,
|
||||
CancelFailed,
|
||||
Cancelled,
|
||||
CancelTurnNotFound,
|
||||
Done,
|
||||
Error,
|
||||
@@ -168,6 +169,9 @@ async def _create_session_endpoint(request: Request) -> JSONResponse:
|
||||
bifrost=bifrost,
|
||||
consumer_key=consumer_key if bifrost else None,
|
||||
)
|
||||
# #347 authored first-message: seed the agent's preset opening
|
||||
# (best-effort; never blocks create — see first_message INV-001).
|
||||
await seed_preset_first_message(client, info.session_id, agent_id)
|
||||
except AgentNotFound:
|
||||
return JSONResponse({"error_code": "agent_not_found"}, status_code=404)
|
||||
except BifrostConsumerKeyMissing:
|
||||
|
||||
@@ -361,7 +361,35 @@ body {
|
||||
/* persona pane structured render */
|
||||
#pane-persona .pk { color: var(--fg-dim); }
|
||||
#pane-persona .pv { color: var(--blue); }
|
||||
#pane-persona .ph { color: var(--cyan); letter-spacing: 0.1em; text-transform: uppercase; font-size: 10px; }
|
||||
#pane-persona .ph { color: var(--cyan); letter-spacing: 0.1em; text-transform: uppercase; font-size: 10px; margin-top: 4px; }
|
||||
|
||||
/* affect metric rows: label · value · Δ · sparkline · n · descriptor */
|
||||
#pane-persona .mono-note { color: var(--fg-faint); font-size: 10px; margin: 2px 0 8px; }
|
||||
#pane-persona .mrow {
|
||||
display: flex; gap: 9px; align-items: baseline; padding: 1px 0;
|
||||
font-size: 12px; white-space: nowrap;
|
||||
}
|
||||
#pane-persona .mrow .mk { color: var(--fg-dim); min-width: 118px; }
|
||||
#pane-persona .mrow .mv { color: var(--blue); min-width: 46px; text-align: right; font-variant-numeric: tabular-nums; }
|
||||
#pane-persona .mrow .md { min-width: 58px; font-size: 11px; color: var(--fg-faint); }
|
||||
#pane-persona .mrow .md.up { color: var(--green); }
|
||||
#pane-persona .mrow .md.dn { color: var(--red); }
|
||||
#pane-persona .mrow .msp { color: var(--cyan); letter-spacing: 1px; min-width: 28px; }
|
||||
#pane-persona .mrow .mn { color: var(--fg-faint); font-size: 10px; min-width: 34px; }
|
||||
#pane-persona .mrow .mdesc { color: var(--fg-faint); font-style: italic; font-size: 10px; }
|
||||
|
||||
/* canonical NL (the literal text Worldtree injects into the agent's context) */
|
||||
#pane-persona .nl-canon {
|
||||
color: var(--blue); font-size: 11px; line-height: 1.5;
|
||||
margin: 3px 0 8px; padding-left: 10px; border-left: 2px solid var(--line-2);
|
||||
white-space: normal; word-break: break-word;
|
||||
}
|
||||
#pane-persona .nl-canon b { color: var(--cyan); font-weight: 600; }
|
||||
#pane-persona .nl-directive { color: var(--fg-2); font-style: italic; }
|
||||
#pane-persona .nl-canon .dh {
|
||||
font-style: normal; color: var(--fg-faint); font-size: 10px;
|
||||
letter-spacing: 0.06em; text-transform: uppercase; display: block; margin-bottom: 2px;
|
||||
}
|
||||
|
||||
/* thinking-pane per-turn dividers */
|
||||
.pane-turn {
|
||||
@@ -807,25 +835,169 @@ async function loadPersona(agentId) {
|
||||
// shape only — pad + per-entity valence + emitted_at; NO fabricated Tier-1 persona
|
||||
// fields (dominant_emotion / mood_drift), which Tier-3 structurally lacks (INV-001).
|
||||
// Labelled "affect", not "persona" (INV-005).
|
||||
// ---- affect trend accumulation (client-side, session-lived) ----
|
||||
// The affect pane refreshes on session-open + after each turn (the post-turn PAD poll
|
||||
// fires ~4x/turn — deduped here by emitted_at so a turn contributes ONE sample). Each
|
||||
// tracked value keeps a rolling, capped history so the pane can show a Δ + sparkline.
|
||||
const AFFECT_HIST = { at: [], pad: {}, rel: {} }; // pad[axis]=[]; rel[target][metric]=[]
|
||||
const HIST_CAP = 24;
|
||||
const _relVal = (x) => (x && typeof x === "object" && "value" in x) ? x.value : x;
|
||||
const _relN = (x) => (x && typeof x === "object" && "evidence_count" in x) ? x.evidence_count : undefined;
|
||||
function pushAffectHistory(snap) {
|
||||
const at = snap.emitted_at || "";
|
||||
if (at && AFFECT_HIST.at[AFFECT_HIST.at.length - 1] === at) return; // same snapshot — skip
|
||||
AFFECT_HIST.at.push(at);
|
||||
if (AFFECT_HIST.at.length > HIST_CAP) AFFECT_HIST.at.shift();
|
||||
const push = (bucket, key, v) => {
|
||||
if (typeof v !== "number") return;
|
||||
(bucket[key] = bucket[key] || []).push(v);
|
||||
if (bucket[key].length > HIST_CAP) bucket[key].shift();
|
||||
};
|
||||
const pad = snap.pad || {};
|
||||
for (const ax of ["pleasure", "arousal", "dominance"]) push(AFFECT_HIST.pad, ax, pad[ax]);
|
||||
for (const rel of (snap.relations || snap.valence || [])) {
|
||||
const tgt = rel.target_entity || rel.entity_id || "?";
|
||||
const b = (AFFECT_HIST.rel[tgt] = AFFECT_HIST.rel[tgt] || {});
|
||||
push(b, "trust_ability", _relVal(rel.trust_ability));
|
||||
push(b, "trust_benevolence", _relVal(rel.trust_benevolence));
|
||||
push(b, "trust_integrity", _relVal(rel.trust_integrity));
|
||||
push(b, "warmth", _relVal(rel.warmth ?? rel.familiarity));
|
||||
}
|
||||
}
|
||||
// unicode sparkline auto-scaled to the value's own observed range; flat when stable
|
||||
// (don't amplify sub-0.01 noise into a fake trend).
|
||||
const _SPARK = "▁▂▃▄▅▆▇█";
|
||||
function sparkline(vals) {
|
||||
if (!vals || vals.length < 2) return (vals && vals.length) ? "·" : "";
|
||||
const lo = Math.min(...vals), hi = Math.max(...vals);
|
||||
if (hi - lo < 0.01) return "▄".repeat(vals.length);
|
||||
const span = hi - lo;
|
||||
return vals.map((v) => _SPARK[Math.min(7, Math.floor(((v - lo) / span) * 7.999))]).join("");
|
||||
}
|
||||
function trendDelta(vals) {
|
||||
if (!vals || vals.length < 2) return "";
|
||||
const d = vals[vals.length - 1] - vals[vals.length - 2];
|
||||
if (Math.abs(d) < 0.0005) return "→";
|
||||
return (d > 0 ? "▲+" : "▼") + d.toFixed(3);
|
||||
}
|
||||
|
||||
// ---- canonical affect→NL (vendored from Worldtree's d2 render canons) ----
|
||||
// Deterministic, NO LLM — mirrors Worldtree core/persona describe_pad +
|
||||
// render_d2_canonical BYTE-EXACT (verified). Shows the LITERAL mood word +
|
||||
// relationship directive Worldtree injects into the agent's own context, so the
|
||||
// pane reads exactly what the agent was told about its state. Canon loaded from
|
||||
// /static/persona_render_canon.json (regen: scripts/build_persona_canon.py).
|
||||
let PERSONA_CANON = null;
|
||||
const _relConf = (x) => (x && typeof x === "object" && "confidence" in x) ? x.confidence : 0;
|
||||
async function loadPersonaCanon() {
|
||||
try { PERSONA_CANON = await (await fetch("/static/persona_render_canon.json")).json(); }
|
||||
catch (_) { /* canon absent → the canonical lines simply omit (fail-open) */ }
|
||||
}
|
||||
function _parseInterval(expr) {
|
||||
expr = expr.trim();
|
||||
if (expr.startsWith("<=")) return [null, false, parseFloat(expr.slice(2)), true];
|
||||
if (expr.startsWith("<")) return [null, false, parseFloat(expr.slice(1)), false];
|
||||
if (expr.startsWith(">=")) return [parseFloat(expr.slice(2)), true, null, false];
|
||||
if (expr.startsWith(">")) return [parseFloat(expr.slice(1)), false, null, false];
|
||||
const loI = expr[0] === "[", hiI = expr[expr.length - 1] === "]";
|
||||
const [a, b] = expr.slice(1, -1).split(",").map((s) => parseFloat(s.trim()));
|
||||
return [a, loI, b, hiI];
|
||||
}
|
||||
function _bandLabel(cuts, v) {
|
||||
if (typeof v !== "number") return null;
|
||||
for (const [expr, label] of cuts) {
|
||||
const [lo, loI, hi, hiI] = _parseInterval(expr);
|
||||
let ok = true;
|
||||
if (lo !== null) ok = ok && (loI ? v >= lo : v > lo);
|
||||
if (hi !== null) ok = ok && (hiI ? v <= hi : v < hi);
|
||||
if (ok) return label;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
function canonMood(pad) { // mirror describe_pad(p,a,d): valence×arousal grid + ±0.3 bands
|
||||
if (!PERSONA_CANON || !pad) return null;
|
||||
const p = pad.pleasure, a = pad.arousal, d = pad.dominance;
|
||||
if ([p, a, d].some((x) => typeof x !== "number")) return null;
|
||||
const g = PERSONA_CANON.mood_grid;
|
||||
const valence = p > 0.3 ? "positive" : p < -0.3 ? "negative" : "neutral";
|
||||
const band = a > 0.3 ? "high_a" : a < -0.3 ? "low_a" : "mid_a";
|
||||
const control = d > 0.3 ? "confident" : d < -0.3 ? "uncertain" : null;
|
||||
return control ? `${g[valence][band]}, ${control}` : g[valence][band];
|
||||
}
|
||||
function canonDirective(rel) { // mirror render_d2_canonical(edge, canon) byte-exact
|
||||
if (!PERSONA_CANON) return null;
|
||||
const R = PERSONA_CANON.relation;
|
||||
const wb = _bandLabel(R.warmth_cuts, _relVal(rel.warmth));
|
||||
const ab = _bandLabel(R.agency_cuts, _relVal(rel.agency));
|
||||
const ta = _bandLabel(R.trust_cuts, _relVal(rel.trust_ability));
|
||||
const ti = _bandLabel(R.trust_cuts, _relVal(rel.trust_integrity));
|
||||
const tb = _bandLabel(R.trust_cuts, _relVal(rel.trust_benevolence));
|
||||
if ([wb, ab, ta, ti, tb].some((x) => x == null)) return null;
|
||||
const cl = _relConf(rel.warmth) >= R.high_conf_floor ? "high" : "low";
|
||||
const tbeh = [ta, ti, tb].includes("limited") ? R.tbeh.low_trust
|
||||
: R.cold_warmth_bands.includes(wb) ? R.tbeh.cold_warmth : R.tbeh.default;
|
||||
return R.prefix + R.warmth_phrase[wb]
|
||||
+ `; agency is ${R.agency_phrase[ab]}; ability trust is ${ta}; integrity trust is ${ti}; `
|
||||
+ `intention trust is ${tb}; this stance rests on ${R.history[cl]}. In behavior, `
|
||||
+ `${R.warmth_beh[wb]}; ${R.agency_beh[ab]}; ${tbeh}; avoid premature we-framing.`;
|
||||
}
|
||||
|
||||
// Issue #18 D2 (relation_edge/1 rework): Worldtree's affect snapshot now carries
|
||||
// `relations[]` (target + trust_ability/benevolence/integrity + warmth + agency +
|
||||
// relation_context, each {value,confidence,evidence_count}) — NOT the old flat
|
||||
// `valence[]`. Render mood (PAD) + the durable per-entity relational model, each with
|
||||
// a Δ + sparkline from AFFECT_HIST. Falls back to `valence` for an older emitter.
|
||||
// INV-001: no fabricated Tier-1 fields. INV-004: every dynamic value escaped (head()
|
||||
// escapes its whole argument; metric() escapes each cell).
|
||||
function renderAffectPane(snap) {
|
||||
const row = (k, v) => `<div><span class="pk">${esc(k)}</span> <span class="pv">${esc(v)}</span></div>`;
|
||||
const head = (t) => `<div class="ph">${esc(t)}</div>`;
|
||||
const all = snap.valence || [];
|
||||
const shown = all.slice(0, 8); // bounded render — valence[] is unbounded in principle
|
||||
const valRows = shown.map((v) =>
|
||||
row(v.entity_id || "?",
|
||||
`familiarity ${JSON.stringify(v.familiarity)} · regard ${JSON.stringify(v.regard)}`
|
||||
+ ` · n=${JSON.stringify(v.interaction_count)}`)
|
||||
).join("");
|
||||
$("pane-persona").innerHTML =
|
||||
head("affect snapshot · " + (snap.agent_id || "?")) +
|
||||
`<div> </div>` + head("pad") +
|
||||
row("pleasure", JSON.stringify(snap.pad?.pleasure)) +
|
||||
row("arousal", JSON.stringify(snap.pad?.arousal)) +
|
||||
row("dominance", JSON.stringify(snap.pad?.dominance)) +
|
||||
`<div> </div>` + head("valence (" + all.length + ")") +
|
||||
(valRows || `<div class="empty">none</div>`) +
|
||||
`<div> </div>` + row("emitted_at", snap.emitted_at || "?");
|
||||
const num = (v) => (typeof v === "number") ? ((v >= 0 ? "+" : "") + v.toFixed(3)) : "—";
|
||||
const metric = (label, val, hist, desc, n) => {
|
||||
const d = trendDelta(hist);
|
||||
const dcls = d.startsWith("▲") ? "up" : d.startsWith("▼") ? "dn" : "";
|
||||
const nlab = (n !== undefined && n !== null) ? "n=" + esc(n) : "";
|
||||
return `<div class="mrow"><span class="mk">${esc(label)}</span>`
|
||||
+ `<span class="mv">${esc(num(val))}</span>`
|
||||
+ `<span class="md ${dcls}">${esc(d)}</span>`
|
||||
+ `<span class="msp">${esc(sparkline(hist))}</span>`
|
||||
+ `<span class="mn">${nlab}</span>`
|
||||
+ `<span class="mdesc">${esc(desc)}</span></div>`;
|
||||
};
|
||||
const pad = snap.pad || {}, H = AFFECT_HIST;
|
||||
let html = head("affect · " + (snap.agent_id || "?"))
|
||||
+ `<div class="mono-note">emitted ${esc((snap.emitted_at || "?").slice(11, 19))} · `
|
||||
+ `${H.at.length} sample${H.at.length === 1 ? "" : "s"} this session</div>`
|
||||
+ head("mood · PAD (transient, −1‥+1)")
|
||||
+ (canonMood(pad) ? `<div class="nl-canon">Worldtree tells the agent it feels: <b>${esc(canonMood(pad))}</b></div>` : "")
|
||||
+ metric("pleasure", pad.pleasure, H.pad.pleasure, "feeling")
|
||||
+ metric("arousal", pad.arousal, H.pad.arousal, "activation")
|
||||
+ metric("dominance", pad.dominance, H.pad.dominance, "control");
|
||||
const rels = snap.relations || snap.valence || [];
|
||||
if (!rels.length) {
|
||||
html += head("relations") + `<div class="empty">no relations tracked yet — take a turn</div>`;
|
||||
}
|
||||
for (const rel of rels.slice(0, 8)) {
|
||||
const tgt = rel.target_entity || rel.entity_id || "?";
|
||||
const ctx = rel.relation_context ? " · stage: " + rel.relation_context : "";
|
||||
const b = H.rel[tgt] || {};
|
||||
html += head("relation → " + tgt + ctx)
|
||||
+ metric("trust·ability", _relVal(rel.trust_ability), b.trust_ability, "is-competent", _relN(rel.trust_ability))
|
||||
+ metric("trust·benevolence", _relVal(rel.trust_benevolence), b.trust_benevolence, "means-well", _relN(rel.trust_benevolence))
|
||||
+ metric("trust·integrity", _relVal(rel.trust_integrity), b.trust_integrity, "is-honest", _relN(rel.trust_integrity))
|
||||
+ metric("warmth", _relVal(rel.warmth ?? rel.familiarity), b.warmth, "affection", _relN(rel.warmth));
|
||||
const ag = _relVal(rel.agency), agn = _relN(rel.agency);
|
||||
if (typeof ag === "number" && agn) html += metric("agency", ag, null, "autonomy", agn);
|
||||
if (rel.obligation_balance !== null && rel.obligation_balance !== undefined) {
|
||||
html += `<div class="mrow"><span class="mk">obligation</span>`
|
||||
+ `<span class="mv">${esc(JSON.stringify(rel.obligation_balance))}</span></div>`;
|
||||
}
|
||||
const dir = canonDirective(rel);
|
||||
if (dir) {
|
||||
html += `<div class="nl-canon nl-directive"><span class="dh">context directive `
|
||||
+ `(what the agent is told about ${esc(tgt)}):</span> ${esc(dir)}</div>`;
|
||||
}
|
||||
}
|
||||
$("pane-persona").innerHTML = html;
|
||||
}
|
||||
|
||||
async function loadAffect(agentId) {
|
||||
@@ -833,6 +1005,7 @@ async function loadAffect(agentId) {
|
||||
const r = await fetch("/api/affect/" + encodeURIComponent(agentId));
|
||||
if (r.status === 200) {
|
||||
const snap = await r.json();
|
||||
pushAffectHistory(snap); // accumulate the per-value trend BEFORE rendering
|
||||
renderAffectPane(snap);
|
||||
setPersonaStrip(snap); // pad bars are the live signal
|
||||
state.lastAffectAt = snap.emitted_at || state.lastAffectAt; // post-turn poll stop-signal
|
||||
@@ -935,8 +1108,15 @@ function openAdminEvents(sessionId) {
|
||||
es.addEventListener("stream_error", (e) => {
|
||||
let d = {}; try { d = JSON.parse(e.data); } catch (_) {}
|
||||
appendTo("pane-admin", `<div class="rule">— admin stream ended: ${esc(d.exception || "error")} —</div>`);
|
||||
// Server signalled the stream is over — close so native EventSource does NOT auto-reconnect
|
||||
// into a retry loop (INV-LIFECYCLE).
|
||||
es.close(); state.adminES = null;
|
||||
});
|
||||
es.onerror = () => {
|
||||
// EventSource auto-reconnects on a transient drop (readyState CONNECTING) — leave that be,
|
||||
// the admin stream is long-lived. Only tear down on a PERMANENT failure (CLOSED — e.g. a
|
||||
// 400/403 where no reconnect is coming) so we don't leak a dead handle.
|
||||
if (es.readyState === EventSource.CLOSED) { state.adminES = null; }
|
||||
const pane = $("pane-admin");
|
||||
if (pane.querySelector(".empty")) {
|
||||
pane.innerHTML = `<div class="empty">admin stream unavailable — needs the readonly-admin key + admin.events.read scope.</div>`;
|
||||
@@ -1184,6 +1364,7 @@ async function submitPrompt() {
|
||||
es.addEventListener("cancelled", (e) => terminal("cancelled", "cancelled", e));
|
||||
es.onerror = () => {
|
||||
audit("sse_connection_dropped turn_id=" + turn_id);
|
||||
hideThinkingNote(); // a raw drop mid-reasoning must not leave the note + rotator running
|
||||
es.close();
|
||||
state.eventSource = null; state.turnId = null;
|
||||
$("composer").classList.remove("streaming");
|
||||
@@ -1249,6 +1430,7 @@ $("prompt-input").addEventListener("keydown", (e) => {
|
||||
|
||||
loadAgents();
|
||||
loadVersion();
|
||||
loadPersonaCanon();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -0,0 +1,178 @@
|
||||
{
|
||||
"_source": "vendored from Worldtree core/persona/canon/{d2-mood-render-canon-v1,d2-render-canon-v1}.json",
|
||||
"_generated_by": "scripts/build_persona_canon.py (regen when .corviduo-canonicals.toml flags canon drift)",
|
||||
"_render_path": "pure deterministic \u2014 no LLM; mirrors Worldtree describe_pad + render_d2_canonical byte-exact",
|
||||
"mood_grid": {
|
||||
"positive": {
|
||||
"high_a": "positive and energized",
|
||||
"mid_a": "positive",
|
||||
"low_a": "positive and calm"
|
||||
},
|
||||
"neutral": {
|
||||
"high_a": "alert",
|
||||
"mid_a": "neutral",
|
||||
"low_a": "quiet"
|
||||
},
|
||||
"negative": {
|
||||
"high_a": "negative and agitated",
|
||||
"mid_a": "negative",
|
||||
"low_a": "negative and subdued"
|
||||
}
|
||||
},
|
||||
"relation": {
|
||||
"trust_cuts": [
|
||||
[
|
||||
"< 0.4",
|
||||
"limited"
|
||||
],
|
||||
[
|
||||
"[0.4, 0.6)",
|
||||
"developing"
|
||||
],
|
||||
[
|
||||
"[0.6, 0.8)",
|
||||
"steady"
|
||||
],
|
||||
[
|
||||
">= 0.8",
|
||||
"strong"
|
||||
]
|
||||
],
|
||||
"warmth_cuts": [
|
||||
[
|
||||
"<= -0.8",
|
||||
"hostile"
|
||||
],
|
||||
[
|
||||
"(-0.8, -0.6]",
|
||||
"cold"
|
||||
],
|
||||
[
|
||||
"(-0.6, -0.4]",
|
||||
"distant"
|
||||
],
|
||||
[
|
||||
"(-0.4, -0.2)",
|
||||
"guarded"
|
||||
],
|
||||
[
|
||||
"[-0.2, 0.2)",
|
||||
"neutral"
|
||||
],
|
||||
[
|
||||
"[0.2, 0.4)",
|
||||
"reserved"
|
||||
],
|
||||
[
|
||||
"[0.4, 0.6)",
|
||||
"measured"
|
||||
],
|
||||
[
|
||||
"[0.6, 0.8)",
|
||||
"clear"
|
||||
],
|
||||
[
|
||||
">= 0.8",
|
||||
"deep"
|
||||
]
|
||||
],
|
||||
"agency_cuts": [
|
||||
[
|
||||
"<= -0.8",
|
||||
"submissive"
|
||||
],
|
||||
[
|
||||
"(-0.8, -0.6]",
|
||||
"deferential"
|
||||
],
|
||||
[
|
||||
"(-0.6, -0.4]",
|
||||
"yielding"
|
||||
],
|
||||
[
|
||||
"(-0.4, -0.2)",
|
||||
"modest"
|
||||
],
|
||||
[
|
||||
"[-0.2, 0.2)",
|
||||
"neutral"
|
||||
],
|
||||
[
|
||||
"[0.2, 0.4)",
|
||||
"light"
|
||||
],
|
||||
[
|
||||
"[0.4, 0.6)",
|
||||
"balanced"
|
||||
],
|
||||
[
|
||||
"[0.6, 0.8)",
|
||||
"substantial"
|
||||
],
|
||||
[
|
||||
">= 0.8",
|
||||
"commanding"
|
||||
]
|
||||
],
|
||||
"warmth_phrase": {
|
||||
"hostile": "strongly hostile regard",
|
||||
"cold": "clearly cold regard",
|
||||
"distant": "distant negative regard",
|
||||
"guarded": "slightly guarded regard",
|
||||
"neutral": "neutral warmth",
|
||||
"reserved": "slightly reserved warmth",
|
||||
"measured": "moderate measured warmth",
|
||||
"clear": "clear warm regard",
|
||||
"deep": "deep warm bond"
|
||||
},
|
||||
"warmth_beh": {
|
||||
"hostile": "keep a firm emotional boundary",
|
||||
"cold": "keep a firm emotional boundary",
|
||||
"distant": "keep guarded distance",
|
||||
"guarded": "keep guarded distance",
|
||||
"neutral": "keep the tone even",
|
||||
"reserved": "keep cordial distance",
|
||||
"measured": "keep cordial distance",
|
||||
"clear": "speak with direct warmth",
|
||||
"deep": "speak with direct warmth"
|
||||
},
|
||||
"agency_phrase": {
|
||||
"submissive": "strongly submissive standing",
|
||||
"deferential": "clearly deferential standing",
|
||||
"yielding": "yielding standing",
|
||||
"modest": "slightly modest standing",
|
||||
"neutral": "neutral standing",
|
||||
"light": "lightly self-assertive standing",
|
||||
"balanced": "self-assured standing",
|
||||
"substantial": "strongly assertive standing",
|
||||
"commanding": "commanding standing"
|
||||
},
|
||||
"agency_beh": {
|
||||
"submissive": "avoid over-yielding while preserving basic respect",
|
||||
"deferential": "avoid over-yielding while preserving basic respect",
|
||||
"yielding": "keep self-advocacy light and deferential",
|
||||
"modest": "keep self-advocacy light and deferential",
|
||||
"neutral": "avoid unnecessary deference",
|
||||
"light": "avoid unnecessary deference",
|
||||
"balanced": "balance deference with independent judgment",
|
||||
"substantial": "treat their position as weighty without yielding judgment",
|
||||
"commanding": "treat their position as weighty without yielding judgment"
|
||||
},
|
||||
"history": {
|
||||
"low": "a broad pattern of prior exchanges",
|
||||
"high": "a broad pattern of prior exchanges"
|
||||
},
|
||||
"prefix": "Use this graded relationship state: toward target, warmth is ",
|
||||
"tbeh": {
|
||||
"low_trust": "verify important claims before relying on them",
|
||||
"cold_warmth": "protect boundaries while staying useful",
|
||||
"default": "work from ordinary good faith"
|
||||
},
|
||||
"cold_warmth_bands": [
|
||||
"distant",
|
||||
"cold",
|
||||
"hostile"
|
||||
],
|
||||
"high_conf_floor": 0.55
|
||||
}
|
||||
}
|
||||
+129
-1
@@ -1692,4 +1692,132 @@ class TestTier2Probes:
|
||||
)
|
||||
assert rc == 0
|
||||
assert "persona_state set" in capsys.readouterr().out
|
||||
assert _json.loads(route.calls[0].request.content) == {"pad": [0.4, 0.1, -0.2]}
|
||||
# canonical POST /sessions/{id}/persona_state body: named-key dict, NOT a list
|
||||
assert _json.loads(route.calls[0].request.content) == {
|
||||
"pad": {"pleasure": 0.4, "arousal": 0.1, "dominance": -0.2}
|
||||
}
|
||||
|
||||
def test_set_persona_wrong_count(self) -> None:
|
||||
"""set_persona_wrong_count [adversarial]: not exactly 3 floats → exit 10, no HTTP."""
|
||||
rc = main(
|
||||
["--set-persona-pad", "0.4,0.1", "--session", "s1",
|
||||
"--api-key", "k", "--server", "https://w.example"]
|
||||
)
|
||||
assert rc == 10
|
||||
|
||||
|
||||
class TestSeedFirstMessageProbe:
|
||||
"""--seed-first-message one-shot (#347 authored-history-write reference-consumer probe)."""
|
||||
|
||||
def test_seed_requires_agent(self) -> None:
|
||||
"""seed_requires_agent [adversarial]: --seed-first-message needs --agent."""
|
||||
with pytest.raises(UsageError, match="requires --agent"):
|
||||
_parse_args(["--seed-first-message", "hello", "--api-key", "k"])
|
||||
|
||||
def test_seed_forbids_session(self) -> None:
|
||||
"""seed_forbids_session [adversarial]: manages its own session — no --session."""
|
||||
with pytest.raises(UsageError, match="manages its own session"):
|
||||
_parse_args(
|
||||
["--seed-first-message", "hi", "--agent", "m", "--session", "s1", "--api-key", "k"]
|
||||
)
|
||||
|
||||
def test_seed_mutually_exclusive(self) -> None:
|
||||
"""seed_mutually_exclusive [adversarial]: --seed-first-message + --whoami → UsageError."""
|
||||
with pytest.raises(UsageError, match="mutually exclusive"):
|
||||
_parse_args(["--seed-first-message", "hi", "--whoami", "--api-key", "k"])
|
||||
|
||||
def test_seed_empty_rejected(self) -> None:
|
||||
"""seed_empty_rejected [adversarial]: empty content → UsageError."""
|
||||
with pytest.raises(UsageError, match="non-empty"):
|
||||
_parse_args(["--seed-first-message", "", "--agent", "m", "--api-key", "k"])
|
||||
|
||||
def test_seed_accepted(self) -> None:
|
||||
"""seed_accepted [happy]: --seed-first-message + --agent → parses."""
|
||||
args = _parse_args(["--seed-first-message", "hi", "--agent", "mimir", "--api-key", "k"])
|
||||
assert args.seed_first_message == "hi"
|
||||
assert args.agent_id == "mimir"
|
||||
assert args.session_id is None and args.new is False
|
||||
|
||||
@respx.mock
|
||||
def test_seed_probe_happy(self, capsys: pytest.CaptureFixture[str]) -> None:
|
||||
"""seed_probe [happy,tracer]: create session → seed → read-back; report to stdout."""
|
||||
respx.post("https://w.example/sessions").mock(
|
||||
return_value=httpx.Response(
|
||||
201,
|
||||
json={
|
||||
"session_id": "s1",
|
||||
"agent_id": "mimir",
|
||||
"message_count": 0,
|
||||
"created_at": "2026-07-06T12:00:00+00:00",
|
||||
"last_active": "2026-07-06T12:00:00+00:00",
|
||||
"metadata": {},
|
||||
},
|
||||
)
|
||||
)
|
||||
hist_route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(
|
||||
201,
|
||||
json={
|
||||
"author": "assistant",
|
||||
"content_chars": 5,
|
||||
"injected_at": "2026-07-06T12:00:01+00:00",
|
||||
"phase": "seeded",
|
||||
"seq": 0,
|
||||
"session_id": "s1",
|
||||
"turn_id": "t1",
|
||||
},
|
||||
)
|
||||
)
|
||||
respx.get("https://w.example/sessions/s1/messages").mock(
|
||||
return_value=httpx.Response(
|
||||
200,
|
||||
json={
|
||||
"session_id": "s1",
|
||||
"items": [{"seq": 0, "role": "assistant", "content": "hello"}],
|
||||
"next_cursor": None,
|
||||
},
|
||||
)
|
||||
)
|
||||
rc = main(
|
||||
["--seed-first-message", "hello", "--agent", "mimir",
|
||||
"--api-key", "k", "--server", "https://w.example"]
|
||||
)
|
||||
assert rc == 0
|
||||
out = capsys.readouterr().out
|
||||
assert "session: s1" in out
|
||||
assert "seeded: seq=0 phase=seeded" in out
|
||||
assert "read-back: 1 message" in out
|
||||
assert "role=assistant" in out
|
||||
assert hist_route.call_count == 1
|
||||
|
||||
@respx.mock
|
||||
def test_seed_probe_feature_absent(self, capsys: pytest.CaptureFixture[str]) -> None:
|
||||
"""feature_absent [error-path]: 404 hide-existence → benign report, exit 0, no read-back."""
|
||||
respx.post("https://w.example/sessions").mock(
|
||||
return_value=httpx.Response(
|
||||
201,
|
||||
json={
|
||||
"session_id": "s1",
|
||||
"agent_id": "mimir",
|
||||
"message_count": 0,
|
||||
"created_at": "2026-07-06T12:00:00+00:00",
|
||||
"last_active": "2026-07-06T12:00:00+00:00",
|
||||
"metadata": {},
|
||||
},
|
||||
)
|
||||
)
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(404, json={"error_code": "session_not_found"})
|
||||
)
|
||||
msgs_route = respx.get("https://w.example/sessions/s1/messages").mock(
|
||||
return_value=httpx.Response(
|
||||
200, json={"session_id": "s1", "items": [], "next_cursor": None}
|
||||
)
|
||||
)
|
||||
rc = main(
|
||||
["--seed-first-message", "hello", "--agent", "mimir",
|
||||
"--api-key", "k", "--server", "https://w.example"]
|
||||
)
|
||||
assert rc == 0
|
||||
assert "feature-absent" in capsys.readouterr().out
|
||||
assert msgs_route.call_count == 0 # never capability-probes past the 404
|
||||
|
||||
@@ -0,0 +1,155 @@
|
||||
"""Tests for ratatoskr.first_message per docs/contracts/first_message.contract.md."""
|
||||
|
||||
import asyncio
|
||||
import hashlib
|
||||
import json
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
import respx
|
||||
|
||||
from ratatoskr.first_message import (
|
||||
FIRST_MESSAGE_PRESETS,
|
||||
preset_for,
|
||||
seed_preset_first_message,
|
||||
)
|
||||
|
||||
|
||||
class TestPresetFor:
|
||||
"""first_message contract — preset_for (dict lookup)."""
|
||||
|
||||
def test_preset_hit(self) -> None:
|
||||
"""preset_hit [happy,tracer]: sindra has a non-empty str preset."""
|
||||
val = preset_for("ratatoskr:sindra")
|
||||
assert isinstance(val, str) and val
|
||||
|
||||
def test_preset_miss(self) -> None:
|
||||
"""preset_miss [happy]: an agent with no preset → None."""
|
||||
assert preset_for("mimir") is None
|
||||
|
||||
def test_empty_agent_id(self) -> None:
|
||||
"""empty_agent_id [adversarial]: "" → AssertionError."""
|
||||
with pytest.raises(AssertionError):
|
||||
preset_for("")
|
||||
|
||||
|
||||
class TestSeedPresetFirstMessage:
|
||||
"""first_message contract — seed_preset_first_message (best-effort #347 seed)."""
|
||||
|
||||
@respx.mock
|
||||
async def test_seeds_preset(self) -> None:
|
||||
"""seeds_preset [happy,tracer]: preset agent → one history POST, correct body."""
|
||||
content = FIRST_MESSAGE_PRESETS["ratatoskr:sindra"]
|
||||
key = "ratatoskr-preset-" + hashlib.sha256(content.encode("utf-8")).hexdigest()[:12]
|
||||
route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(
|
||||
201,
|
||||
json={
|
||||
"author": "assistant",
|
||||
"seq": 0,
|
||||
"phase": "seeded",
|
||||
"turn_id": "t1",
|
||||
"session_id": "s1",
|
||||
"content_chars": len(content),
|
||||
"injected_at": "2026-07-06T00:00:00+00:00",
|
||||
},
|
||||
)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await seed_preset_first_message(client, "s1", "ratatoskr:sindra")
|
||||
assert result == content
|
||||
assert route.call_count == 1 # POST-002: exactly one history POST
|
||||
assert json.loads(route.calls[0].request.content) == {
|
||||
"author": "assistant",
|
||||
"content": content,
|
||||
"idempotency_key": key,
|
||||
}
|
||||
|
||||
@respx.mock
|
||||
async def test_no_preset_zero_http(self) -> None:
|
||||
"""no_preset_zero_http [happy]: no-preset agent → None, ZERO HTTP (INV-002)."""
|
||||
route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(201, json={})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await seed_preset_first_message(client, "s1", "mimir")
|
||||
assert result is None
|
||||
assert not route.called
|
||||
|
||||
@respx.mock
|
||||
async def test_feature_absent_swallowed(self) -> None:
|
||||
"""feature_absent_swallowed [error]: 404 hide-existence → None, no raise (INV-001)."""
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(404, json={"error_code": "session_not_found"})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await seed_preset_first_message(client, "s1", "ratatoskr:sindra")
|
||||
assert result is None
|
||||
|
||||
@respx.mock
|
||||
async def test_session_api_failed_swallowed(self) -> None:
|
||||
"""session_api_failed_swallowed [error]: 409 → None, no raise (INV-001)."""
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(409, json={"error_code": "generation_active"})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await seed_preset_first_message(client, "s1", "ratatoskr:sindra")
|
||||
assert result is None
|
||||
|
||||
@respx.mock
|
||||
async def test_transport_error_swallowed(self) -> None:
|
||||
"""transport_error_swallowed [error]: httpx.ConnectError → None, no raise (INV-001)."""
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
side_effect=httpx.ConnectError("boom")
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await seed_preset_first_message(client, "s1", "ratatoskr:sindra")
|
||||
assert result is None
|
||||
|
||||
@respx.mock
|
||||
async def test_unexpected_exception_swallowed(self) -> None:
|
||||
"""unexpected_exception [error]: write raises ValueError → None (broad never-raise)."""
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
side_effect=ValueError("unexpected")
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await seed_preset_first_message(client, "s1", "ratatoskr:sindra")
|
||||
assert result is None
|
||||
|
||||
async def test_cancellation_propagates(self) -> None:
|
||||
"""cancellation_propagates [error]: CancelledError from the write is RE-RAISED."""
|
||||
import ratatoskr.first_message as fm
|
||||
|
||||
async def _cancel(*_a: object, **_k: object) -> None:
|
||||
raise asyncio.CancelledError
|
||||
|
||||
orig = fm.write_authored_history
|
||||
fm.write_authored_history = _cancel # type: ignore[assignment]
|
||||
try:
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(asyncio.CancelledError):
|
||||
await seed_preset_first_message(client, "s1", "ratatoskr:sindra")
|
||||
finally:
|
||||
fm.write_authored_history = orig # type: ignore[assignment]
|
||||
|
||||
@respx.mock
|
||||
async def test_malformed_agent_id_no_http(self) -> None:
|
||||
"""malformed_agent_id [adversarial]: non-str or empty agent_id → None; no HTTP; no raise."""
|
||||
route = respx.post(url__regex=r".*/history$").mock(
|
||||
return_value=httpx.Response(201, json={})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
assert await seed_preset_first_message(client, "s1", 123) is None # type: ignore[arg-type]
|
||||
assert await seed_preset_first_message(client, "s1", "") is None
|
||||
assert not route.called
|
||||
|
||||
@respx.mock
|
||||
async def test_empty_session_id(self) -> None:
|
||||
"""empty_session_id [adversarial]: "" → None (soft guard); no HTTP; no raise."""
|
||||
route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(201, json={})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await seed_preset_first_message(client, "", "ratatoskr:sindra")
|
||||
assert result is None
|
||||
assert not route.called
|
||||
+187
-2
@@ -8,6 +8,7 @@ from ratatoskr.sessions import (
|
||||
AgentInfo,
|
||||
AgentNotAvailable,
|
||||
AgentNotFound,
|
||||
AuthoredHistoryUnavailable,
|
||||
AuthScopeDenied,
|
||||
BifrostBinding,
|
||||
BifrostConsumerKeyMissing,
|
||||
@@ -25,11 +26,13 @@ from ratatoskr.sessions import (
|
||||
get_me,
|
||||
get_persona_state,
|
||||
get_session_bifrost,
|
||||
get_session_messages,
|
||||
get_session_tools,
|
||||
list_agents,
|
||||
list_character_models,
|
||||
list_sessions,
|
||||
set_persona_state,
|
||||
write_authored_history,
|
||||
)
|
||||
|
||||
|
||||
@@ -1179,9 +1182,13 @@ class TestSetPersonaState:
|
||||
return_value=httpx.Response(204)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await set_persona_state(client, "s1", {"pad": [0.4, 0.1, -0.2]})
|
||||
result = await set_persona_state(
|
||||
client, "s1", {"pad": {"pleasure": 0.4, "arousal": 0.1, "dominance": -0.2}}
|
||||
)
|
||||
assert result is None
|
||||
assert _json.loads(route.calls[0].request.content) == {"pad": [0.4, 0.1, -0.2]}
|
||||
assert _json.loads(route.calls[0].request.content) == {
|
||||
"pad": {"pleasure": 0.4, "arousal": 0.1, "dominance": -0.2}
|
||||
}
|
||||
|
||||
@respx.mock
|
||||
async def test_non_204_raises(self) -> None:
|
||||
@@ -1193,3 +1200,181 @@ class TestSetPersonaState:
|
||||
with pytest.raises(SessionApiFailed) as exc:
|
||||
await set_persona_state(client, "s1", {"pad": [1, 2, 3]})
|
||||
assert exc.value.status == 422
|
||||
|
||||
|
||||
_AUTHORED_ACK = {
|
||||
"author": "assistant",
|
||||
"content_chars": 5,
|
||||
"injected_at": "2026-07-06T12:00:00+00:00",
|
||||
"phase": "seeded",
|
||||
"seq": 0,
|
||||
"session_id": "s1",
|
||||
"turn_id": "t1",
|
||||
}
|
||||
|
||||
|
||||
class TestWriteAuthoredHistory:
|
||||
"""write_authored_history — #347 POST /sessions/{id}/history (contract #2 amendment)."""
|
||||
|
||||
@respx.mock
|
||||
async def test_happy_fresh_201(self) -> None:
|
||||
"""happy_fresh_201 [happy,tracer]: 201 → ack verbatim; minimal body."""
|
||||
import json as _json
|
||||
|
||||
route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(201, json=_AUTHORED_ACK)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await write_authored_history(
|
||||
client, "s1", content="hello", idempotency_key="k1"
|
||||
)
|
||||
assert result == _AUTHORED_ACK
|
||||
assert _json.loads(route.calls[0].request.content) == {
|
||||
"author": "assistant",
|
||||
"content": "hello",
|
||||
"idempotency_key": "k1",
|
||||
}
|
||||
|
||||
@respx.mock
|
||||
async def test_happy_replay_200(self) -> None:
|
||||
"""happy_replay_200 [happy]: 200 replay (byte-identical body) → dict verbatim."""
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(200, json=_AUTHORED_ACK)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await write_authored_history(
|
||||
client, "s1", content="hello", idempotency_key="k1"
|
||||
)
|
||||
assert result == _AUTHORED_ACK
|
||||
|
||||
@respx.mock
|
||||
async def test_body_includes_effects(self) -> None:
|
||||
"""body_includes_effects [trace]: effects + claimed_original_at appear iff non-None."""
|
||||
import json as _json
|
||||
|
||||
route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(201, json=_AUTHORED_ACK)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
await write_authored_history(
|
||||
client,
|
||||
"s1",
|
||||
content="hi",
|
||||
idempotency_key="k1",
|
||||
effects="none",
|
||||
claimed_original_at="2020-01-01T00:00:00Z",
|
||||
)
|
||||
assert _json.loads(route.calls[0].request.content) == {
|
||||
"author": "assistant",
|
||||
"content": "hi",
|
||||
"idempotency_key": "k1",
|
||||
"effects": "none",
|
||||
"claimed_original_at": "2020-01-01T00:00:00Z",
|
||||
}
|
||||
|
||||
@respx.mock
|
||||
async def test_hide_existence_404(self) -> None:
|
||||
"""hide_existence_404 [error]: 404 → AuthoredHistoryUnavailable (NOT SessionApiFailed)."""
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(404, json={"error_code": "session_not_found"})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(AuthoredHistoryUnavailable) as exc:
|
||||
await write_authored_history(client, "s1", content="hi", idempotency_key="k1")
|
||||
assert exc.value.session_id == "s1"
|
||||
|
||||
@respx.mock
|
||||
async def test_generation_active_409(self) -> None:
|
||||
"""generation_active_409 [error]: 409 → SessionApiFailed(409)."""
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(409, json={"error_code": "generation_active"})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(SessionApiFailed) as exc:
|
||||
await write_authored_history(client, "s1", content="hi", idempotency_key="k1")
|
||||
assert exc.value.status == 409
|
||||
|
||||
@respx.mock
|
||||
async def test_content_too_long_422(self) -> None:
|
||||
"""content_too_long_422 [error]: 422 → SessionApiFailed(422)."""
|
||||
respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(422, json={"error_code": "content_too_long"})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(SessionApiFailed) as exc:
|
||||
await write_authored_history(client, "s1", content="x", idempotency_key="k1")
|
||||
assert exc.value.status == 422
|
||||
|
||||
@respx.mock
|
||||
async def test_empty_content(self) -> None:
|
||||
"""empty_content [adversarial]: content="" → AssertionError; no HTTP issued."""
|
||||
route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(201, json=_AUTHORED_ACK)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(AssertionError):
|
||||
await write_authored_history(client, "s1", content="", idempotency_key="k1")
|
||||
assert not route.called
|
||||
|
||||
@respx.mock
|
||||
async def test_empty_idempotency_key(self) -> None:
|
||||
"""empty_idempotency_key [adversarial]: key="" → AssertionError; no HTTP issued."""
|
||||
route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(201, json=_AUTHORED_ACK)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(AssertionError):
|
||||
await write_authored_history(client, "s1", content="hi", idempotency_key="")
|
||||
assert not route.called
|
||||
|
||||
@respx.mock
|
||||
async def test_empty_session_id(self) -> None:
|
||||
"""empty_session_id [adversarial]: session_id="" → AssertionError; no HTTP issued."""
|
||||
route = respx.post("https://w.example/sessions/s1/history").mock(
|
||||
return_value=httpx.Response(201, json=_AUTHORED_ACK)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(AssertionError):
|
||||
await write_authored_history(client, "", content="hi", idempotency_key="k1")
|
||||
assert not route.called
|
||||
|
||||
|
||||
class TestGetSessionMessages:
|
||||
"""#2 contract (amendment 2026-07-06) — get_session_messages (GET /sessions/{id}/messages)."""
|
||||
|
||||
@respx.mock
|
||||
async def test_happy(self) -> None:
|
||||
"""happy [happy,tracer]: 200 {session_id, items, next_cursor} → dict verbatim."""
|
||||
payload = {
|
||||
"session_id": "s1",
|
||||
"items": [{"seq": 0, "role": "assistant", "content": "hello there"}],
|
||||
"next_cursor": None,
|
||||
}
|
||||
respx.get("https://w.example/sessions/s1/messages").mock(
|
||||
return_value=httpx.Response(200, json=payload)
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
result = await get_session_messages(client, "s1")
|
||||
assert result == payload
|
||||
|
||||
@respx.mock
|
||||
async def test_not_found_404(self) -> None:
|
||||
"""not_found_404 [error]: 404 → SessionApiFailed(404)."""
|
||||
respx.get("https://w.example/sessions/s1/messages").mock(
|
||||
return_value=httpx.Response(404, json={"error_code": "session_not_found"})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(SessionApiFailed) as exc:
|
||||
await get_session_messages(client, "s1")
|
||||
assert exc.value.status == 404
|
||||
|
||||
@respx.mock
|
||||
async def test_empty_session_id(self) -> None:
|
||||
"""empty_session_id [adversarial]: "" → AssertionError; no HTTP issued."""
|
||||
route = respx.get("https://w.example/sessions/s1/messages").mock(
|
||||
return_value=httpx.Response(200, json={})
|
||||
)
|
||||
async with httpx.AsyncClient(base_url="https://w.example") as client:
|
||||
with pytest.raises(AssertionError):
|
||||
await get_session_messages(client, "")
|
||||
assert not route.called
|
||||
|
||||
@@ -2922,6 +2922,10 @@ class TestTuiBifrostBind:
|
||||
},
|
||||
)
|
||||
)
|
||||
# sindra is a preset agent → the TUI create path now auto-seeds a #347 first-message.
|
||||
respx.post("https://w.example/sessions/s-bound/history").mock(
|
||||
return_value=httpx.Response(201, json={})
|
||||
)
|
||||
|
||||
async def fake_run_async(self) -> int:
|
||||
return 0
|
||||
|
||||
@@ -175,6 +175,29 @@ class TestCreateSessionEndpoint:
|
||||
resp = TestClient(app).post("/api/sessions", json={})
|
||||
assert resp.status_code == 400
|
||||
|
||||
@respx.mock
|
||||
def test_preset_agent_auto_seeds_first_message(self) -> None:
|
||||
"""#347: a preset agent gets its opening seeded on create; a non-preset agent does not."""
|
||||
respx.post("https://w.example/sessions").mock(return_value=httpx.Response(201, json=_CREATE_OK))
|
||||
hist = respx.post("https://w.example/sessions/s-1/history").mock(
|
||||
return_value=httpx.Response(
|
||||
201,
|
||||
json={
|
||||
"author": "assistant", "seq": 0, "phase": "seeded", "turn_id": "t1",
|
||||
"session_id": "s-1", "content_chars": 1, "injected_at": "t",
|
||||
},
|
||||
)
|
||||
)
|
||||
from ratatoskr.web.server import create_app
|
||||
app = create_app(_mock_client_factory())
|
||||
client = TestClient(app)
|
||||
# preset agent → the endpoint seeds a first-message
|
||||
assert client.post("/api/sessions", json={"agent_id": "ratatoskr:sindra"}).status_code == 201
|
||||
assert hist.call_count == 1
|
||||
# non-preset agent → no seed (count unchanged)
|
||||
assert client.post("/api/sessions", json={"agent_id": "mimir"}).status_code == 201
|
||||
assert hist.call_count == 1
|
||||
|
||||
|
||||
_SNAPSHOT = {
|
||||
"agent_id": "mimir",
|
||||
@@ -625,6 +648,10 @@ class TestCreateAppShape:
|
||||
"/", "/version", "/api/agents", "/api/sessions",
|
||||
"/api/agents/{agent_id}/persona_state",
|
||||
"/api/affect/{agent_id}",
|
||||
# v0.19.2 debug-surface parity (create_app POST-002)
|
||||
"/api/sessions/{session_id}/tools",
|
||||
"/api/sessions/{session_id}/bifrost",
|
||||
"/api/admin/events",
|
||||
"/api/turns/{session_id}", "/api/turns/{session_id}/stream",
|
||||
"/api/turns/{session_id}/cancel",
|
||||
):
|
||||
@@ -633,10 +660,14 @@ class TestCreateAppShape:
|
||||
assert "/static" in paths
|
||||
|
||||
def test_state_attached(self) -> None:
|
||||
"""state_attached [trace]: app.state.turn_registry is empty dict."""
|
||||
"""state_attached [trace]: app.state.turn_registry is empty dict; admin_key stored."""
|
||||
from ratatoskr.web.server import create_app
|
||||
app = create_app(_mock_client_factory())
|
||||
assert app.state.turn_registry == {}
|
||||
# create_app POST-001: admin_key defaults None (admin routes fail-visible)
|
||||
assert app.state.admin_key is None
|
||||
app2 = create_app(_mock_client_factory(), admin_key="adm-key")
|
||||
assert app2.state.admin_key == "adm-key"
|
||||
|
||||
def test_factory_stored(self) -> None:
|
||||
"""factory_stored [trace]: app.state.client_factory is the same callable."""
|
||||
@@ -813,6 +844,10 @@ class TestWebBifrostBind:
|
||||
route = respx.post("https://w.example/sessions").mock(
|
||||
return_value=httpx.Response(201, json=_CREATE_OK)
|
||||
)
|
||||
# sindra is a preset agent → the endpoint now auto-seeds a #347 first-message.
|
||||
respx.post("https://w.example/sessions/s-1/history").mock(
|
||||
return_value=httpx.Response(201, json={})
|
||||
)
|
||||
app = create_app(
|
||||
_mock_client_factory(),
|
||||
bifrost_consumer_key="server-ck",
|
||||
@@ -848,6 +883,10 @@ class TestWebBifrostBind:
|
||||
route = respx.post("https://w.example/sessions").mock(
|
||||
return_value=httpx.Response(201, json=_CREATE_OK)
|
||||
)
|
||||
# sindra is a preset agent → the endpoint now auto-seeds a #347 first-message.
|
||||
respx.post("https://w.example/sessions/s-1/history").mock(
|
||||
return_value=httpx.Response(201, json={})
|
||||
)
|
||||
app = create_app(
|
||||
_mock_client_factory(),
|
||||
bifrost_consumer_key="server-ck",
|
||||
@@ -1182,3 +1221,16 @@ class TestAdminEventsEndpoint:
|
||||
assert "system.degraded" in body # system.* → forwarded
|
||||
assert "system.heartbeat" not in body # heartbeat → dropped
|
||||
assert "turn.started" not in body # other session → dropped
|
||||
|
||||
@respx.mock
|
||||
def test_stream_error_on_connect_failure(self) -> None:
|
||||
"""error: upstream admin SSE non-200 -> ONE stream_error frame, stream ends (POST-003)."""
|
||||
respx.get("https://w.example/admin/events").mock(
|
||||
return_value=httpx.Response(500, content=b"boom")
|
||||
)
|
||||
from ratatoskr.web.server import create_app
|
||||
app = create_app(_mock_client_factory(), admin_key="adm-key")
|
||||
body = TestClient(app).get("/api/admin/events?session_id=s-1").text
|
||||
assert "event: stream_error" in body
|
||||
assert "SseConnectFailed" in body
|
||||
assert body.count("event: stream_error") == 1 # exactly one, then ends
|
||||
|
||||
Reference in New Issue
Block a user