vh/ratatoskr
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(sessions,cli,tui): issues #5 + #6 + worldtree-dev consumer-API follow-up

Browse Source 
Issue #6 (TUI startup error visibility): restructure run_tui lifecycle so
pre-App.run() failures land on real stderr instead of getting eaten by
the alt-screen teardown. New _resolve_then_run async helper opens the
AsyncClient via async-with, does pre-flight session resolution, routes
AgentNotFound / SessionApiFailed / network errors to sys.stderr (verbatim
same labels + exit codes as cli._amain), then constructs RatatoskrApp
with pre-resolved state and awaits app.run_async(). RatatoskrApp.__init__
signature widens to (args, *, session_id, agent_id, client) — all three
required. on_mount narrows to identity-widget population; on_unmount
becomes a no-op (client lifetime owned by run_tui's async-with).

Issue #5 (--end-user-id for per-end-user agents): sessions.create_session
gains keyword-only end_user_id kwarg with PRE-003 non-empty assertion;
ParsedArgs.end_user_id field added (default None); --end-user-id flag
with non-empty validation; _amain + _resolve_then_run thread it to their
create_session calls. RATATOSKR_END_USER_ID env-var fallback
(flag > env > None) per the post-2026-05-23 amendment; env.sh (gitignored)
ships "ratatoskr-tui" as project-stable partition default.

Worldtree-dev consumer-API follow-up (althing 01KSBARG2B8M): User-Agent
header added (ratatoskr/<version> (vh@phasefinal.com), version pulled via
importlib.metadata) to both AsyncClient constructions so server logs can
distinguish ratatoskr traffic from other consumers.

Volva code-review (2 rounds on #6) found 8 test-precision gaps + 1 PRE
assertion drift, all Category 1 fixed: missing PRE-001 at
_resolve_then_run entry; Rule separator assertions on markdown render;
RichLog-write spy on empty submit; input-cleared + no-new-worker on
cancelling busy; worker.cancel observation on three force-exit paths;
on_unmount-no-close focused test (the prior client-lifetime test patched
run_async so on_unmount was never exercised); happy --new resolve test
verifying POST count + identity propagation.

Issues #2/#3/#4/#5 contracts amended in-place to reflect:
- create_session widened (PRE-003, body construction step, body shape POST)
- ParsedArgs description + _parse_args STEPS + _amain create_session call
  + new TESTS for end_user_id + env-var fallback
- _resolve_then_run STEPS + new TEST entries; on_mount narrowed;
  INV-007 amended for new client ownership
- Post-#6 adjustment note on issue #5 (_resolve_then_run replaces
  on_mount as the threading site since #6 moved session resolution out
  of the alt-screen)

188 tests GREEN; ruff clean. Bumps to v0.1.0 — first minor release, the
load-bearing reason is RatatoskrApp.__init__'s breaking signature change
(additive end_user_id alone wouldn't have triggered a minor pre-v1.x).

Files Gitea issues #9 (spec-pin refresh v0.19.0 → v0.22.1), #10 (track
Worldtree #196 subject:{type,id} migration), #11 (AdminEvents pane auth
prerequisite admin.events.read). Infra-ops pinged via althing for
agents.call:lofn scope add (broker pattern; they forwarded to
worldtree-dev because personal Worldtree exposes no public
scope-mutation endpoint).
This commit is contained in:
Vuong Hoang
2026-05-23 14:34:53 -07:00
parent c713208585
commit 804c2df6eb
14 changed files with 1422 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/issues/2.contract.md
+15 -10
View File
@@ -94,11 +94,12 @@ Convention-aligned with issue #1: caller owns the `httpx.AsyncClient` and Author
--- ---
```contract ```contract
FN create_session(client: httpx.AsyncClient, agent_id: str) -> SessionInfo FN create_session(client: httpx.AsyncClient, agent_id: str, *, end_user_id: str | None = None) -> SessionInfo
BRIEF: POST /sessions with {"agent_id": agent_id} to create a new conversation session. Returns SessionInfo populated from the 201 response. BRIEF: POST /sessions with {"agent_id": agent_id} (and {"end_user_id": end_user_id} when non-None) to create a new conversation session. Returns SessionInfo populated from the 201 response. Per issue #5: keyword-only `end_user_id` for per-end-user agents (lofn etc.); default-None preserves the pre-#5 baseline.
PRE: [PRE-001 hard] client is not None -- assert client is not None PRE: [PRE-001 hard] client is not None -- assert client is not None
PRE: [PRE-002 hard] agent_id is a non-empty string -- assert agent_id and isinstance(agent_id, str) PRE: [PRE-002 hard] agent_id is a non-empty string -- assert agent_id and isinstance(agent_id, str)
POST: [POST-001 side_effect] exactly one POST to /sessions was issued with body {"agent_id": agent_id} -- assert mock_router.calls.call_count == 1 and json.loads(req.content) == {"agent_id": agent_id} PRE: [PRE-003 hard, issue #5] end_user_id is None OR a non-empty string -- assert end_user_id is None or (isinstance(end_user_id, str) and end_user_id)
POST: [POST-001 side_effect] exactly one POST to /sessions was issued; body is {"agent_id": agent_id} when end_user_id is None, OR {"agent_id": agent_id, "end_user_id": end_user_id} when non-None (issue #5 INV-002: omitting the field when None is NOT the same as sending empty)
POST: [POST-002 return_value] returns SessionInfo with session_id, agent_id, created_at, last_active, metadata populated from response -- assert all 5 fields non-None POST: [POST-002 return_value] returns SessionInfo with session_id, agent_id, created_at, last_active, metadata populated from response -- assert all 5 fields non-None
POST: [POST-003 return_value] returns SessionInfo where message_count == response["message_count"] (typically 0 for a fresh session) and list-only fields carry the create-origin fixed defaults per INV-001 -- assert info.message_count is not None and info.name is None and info.archived is False and info.tags == [] POST: [POST-003 return_value] returns SessionInfo where message_count == response["message_count"] (typically 0 for a fresh session) and list-only fields carry the create-origin fixed defaults per INV-001 -- assert info.message_count is not None and info.name is None and info.archived is False and info.tags == []
ERROR_ROUTING: ERROR_ROUTING:
@@ -109,19 +110,20 @@ ERROR_ROUTING:
HTTP 422 validation_failed: HTTP 422 validation_failed:
local_handling: raise SessionApiFailed(status=422, body=resp.content[:1024]) local_handling: raise SessionApiFailed(status=422, body=resp.content[:1024])
flow_control: abort flow_control: abort
state_recovery: none (typically client bug; surface for debugging) state_recovery: none (typically client bug; surface for debugging. Issue #5: a `end_user_id_required` 422 indicates the agent requires --end-user-id; raw label is honest, hint translation deferred.)
httpx.HTTPStatusError (other status): httpx.HTTPStatusError (other status):
local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content[:1024]) local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content[:1024])
flow_control: abort flow_control: abort
state_recovery: none state_recovery: none
STEPS: STEPS:
1. [setup, flexibility=prescriptive] Validate inputs per PRE-001, PRE-002 1. [setup, flexibility=prescriptive] Validate inputs per PRE-001, PRE-002, PRE-003
2. [sequential, flexibility=prescriptive] CALL client.post("/sessions", json={"agent_id": agent_id}) 2. [sequential, flexibility=prescriptive] Build body = {"agent_id": agent_id}; IF end_user_id is not None: body["end_user_id"] = end_user_id
3. [sequential, flexibility=prescriptive] CALL client.post("/sessions", json=body)
tool: { destructive: false, idempotent: false, read_only: false, open_world: false } tool: { destructive: false, idempotent: false, read_only: false, open_world: false }
3. [branch, flexibility=prescriptive] IF resp.status_code == 404: RAISE AgentNotFound 4. [branch, flexibility=prescriptive] IF resp.status_code == 404: RAISE AgentNotFound
ELIF resp.status_code != 201: RAISE SessionApiFailed ELIF resp.status_code != 201: RAISE SessionApiFailed
4. [sequential] Parse resp.json() → body 5. [sequential] Parse resp.json() → body
5. [cleanup] RETURN SessionInfo( 6. [cleanup] RETURN SessionInfo(
session_id=body["session_id"], session_id=body["session_id"],
agent_id=body["agent_id"], agent_id=body["agent_id"],
created_at=body["created_at"], created_at=body["created_at"],
@@ -135,11 +137,14 @@ STEPS:
TESTS: TESTS:
happy_create [happy,tracer]: mock returns 201 with full body → returns SessionInfo with all create-side fields populated; list-only fields are at create-origin defaults (name=None, archived=False, tags=[]) happy_create [happy,tracer]: mock returns 201 with full body → returns SessionInfo with all create-side fields populated; list-only fields are at create-origin defaults (name=None, archived=False, tags=[])
happy_create_with_metadata [happy]: response includes metadata={"model": "glm5-turbo"} → SessionInfo.metadata == {"model": "glm5-turbo"} happy_create_with_metadata [happy]: response includes metadata={"model": "glm5-turbo"} → SessionInfo.metadata == {"model": "glm5-turbo"}
request_body_shape [trace]: outbound JSON body is exactly {"agent_id": <arg>} — no Bifrost field, no extra keys request_body_shape [trace]: outbound JSON body is exactly {"agent_id": <arg>} when end_user_id omitted — no Bifrost field, no extra keys
unknown_agent_id [error]: mock returns 404 → raises AgentNotFound(agent_id="mimir") unknown_agent_id [error]: mock returns 404 → raises AgentNotFound(agent_id="mimir")
validation_failed [error]: mock returns 422 → raises SessionApiFailed(status=422); body truncated to ≤1024 bytes validation_failed [error]: mock returns 422 → raises SessionApiFailed(status=422); body truncated to ≤1024 bytes
unexpected_status_truncates [error]: mock returns 500 with 5000-byte body → SessionApiFailed; .body is exactly the first 1024 bytes unexpected_status_truncates [error]: mock returns 500 with 5000-byte body → SessionApiFailed; .body is exactly the first 1024 bytes
empty_agent_id [adversarial]: agent_id="" → AssertionError; no HTTP issued empty_agent_id [adversarial]: agent_id="" → AssertionError; no HTTP issued
happy_create_with_end_user_id [happy, issue #5]: end_user_id="alice" → outbound JSON body == {"agent_id": "mimir", "end_user_id": "alice"} byte-for-byte; SessionInfo populated as today
default_omits_end_user_id [trace, issue #5]: omit end_user_id kwarg → outbound JSON body == {"agent_id": "mimir"} (no end_user_id key); preserves the pre-#5 baseline
empty_end_user_id [adversarial, issue #5]: end_user_id="" → AssertionError before HTTP (PRE-003)
``` ```
```contract ```contract
docs/contracts/issues/3.contract.md
+16 -2
View File
@@ -55,12 +55,14 @@ The Textual TUI is the eventual primary product (design-brief §5) — separate
- Environment: `WORLDTREE_API_KEY` (fallback for `--api-key`), `WORLDTREE_API_URL` (fallback for `--server`). - Environment: `WORLDTREE_API_KEY` (fallback for `--api-key`), `WORLDTREE_API_URL` (fallback for `--server`).
**Parsed arguments** (`ParsedArgs` frozen dataclass): **Parsed arguments** (`ParsedArgs` frozen dataclass):
- `send_content: str` — the user message text (`--send <content>`, required). - `send_content: str | None` — the user message text (`--send <content>`); None signals TUI mode (issue #4 amendment).
- `session_id: str | None` — existing session (`--session <id>`); mutex with `new`. - `session_id: str | None` — existing session (`--session <id>`); mutex with `new`.
- `new: bool` — mint a fresh session (`--new`); mutex with `session_id`. - `new: bool` — mint a fresh session (`--new`); mutex with `session_id`.
- `agent_id: str | None` — required iff `new=True`. - `agent_id: str | None` — required iff `new=True`.
- `api_key: str` — resolved from `--api-key` then `$WORLDTREE_API_KEY`. - `api_key: str` — resolved from `--api-key` then `$WORLDTREE_API_KEY`.
- `server_url: str` — resolved from `--server`, then `$WORLDTREE_API_URL`, then `http://localhost:8000`. - `server_url: str` — resolved from `--server`, then `$WORLDTREE_API_URL`, then `http://localhost:8000`.
- `raw: bool` — `--raw` opt-out from markdown rendering (issue #4 amendment).
- `end_user_id: str | None` — `--end-user-id <id>` for per-end-user agents (issue #5 amendment); default None preserves the pre-#5 baseline for agents that don't require it (mimir).
**Output (stdout):** **Output (stdout):**
- Raw text deltas from `Text` events, written without trailing newline per chunk. A single trailing newline is written after the terminal `Done` event so the next shell prompt lands on a fresh line. - Raw text deltas from `Text` events, written without trailing newline per chunk. A single trailing newline is written after the terminal `Done` event so the next shell prompt lands on a fresh line.
@@ -257,12 +259,15 @@ STEPS:
--api-key <key> (str, optional — env fallback in step 4) --api-key <key> (str, optional — env fallback in step 4)
--server <url> (str, optional — env fallback + default in step 5) --server <url> (str, optional — env fallback + default in step 5)
--raw (bool flag, default False — issue #4 amendment: TUI markdown opt-out) --raw (bool flag, default False — issue #4 amendment: TUI markdown opt-out)
--end-user-id <id> (str, optional, default None — issue #5: required by per-end-user agents; if passed, must be non-empty)
2. [sequential, flexibility=prescriptive] Parse argv: 2. [sequential, flexibility=prescriptive] Parse argv:
TRY: ns = parser.parse_args(argv if argv is not None else sys.argv[1:]) TRY: ns = parser.parse_args(argv if argv is not None else sys.argv[1:])
ON SystemExit: ON SystemExit:
Re-raise as UsageError with argparse's captured message Re-raise as UsageError with argparse's captured message
2a. [branch, flexibility=prescriptive] IF ns.send is not None AND not ns.send: 2a. [branch, flexibility=prescriptive] IF ns.send is not None AND not ns.send:
RAISE UsageError("--send content must be non-empty") # empty-string --send still invalid RAISE UsageError("--send content must be non-empty") # empty-string --send still invalid
2b. [branch, flexibility=prescriptive, issue #5] 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") # mirrors empty-send check
3. [branch, flexibility=prescriptive] Validate session/new/agent triad per INV-004: 3. [branch, flexibility=prescriptive] Validate session/new/agent triad per INV-004:
IF ns.session and ns.new: RAISE UsageError("--session and --new are mutually exclusive") IF ns.session and ns.new: RAISE UsageError("--session and --new are mutually exclusive")
IF NOT ns.session AND NOT ns.new: RAISE UsageError("pass exactly one of --session or --new") IF NOT ns.session AND NOT ns.new: RAISE UsageError("pass exactly one of --session or --new")
@@ -273,6 +278,9 @@ STEPS:
IF NOT api_key: RAISE _AuthError("no API key (set --api-key or WORLDTREE_API_KEY)") IF NOT api_key: RAISE _AuthError("no API key (set --api-key or WORLDTREE_API_KEY)")
5. [sequential, flexibility=prescriptive] Resolve server_url per INV-006: 5. [sequential, flexibility=prescriptive] Resolve server_url per INV-006:
server_url = ns.server or os.environ.get("WORLDTREE_API_URL") or "http://localhost:8000" server_url = ns.server or os.environ.get("WORLDTREE_API_URL") or "http://localhost:8000"
5b. [sequential, flexibility=prescriptive, issue #5 amended 2026-05-23] Resolve end_user_id with env-var fallback:
end_user_id = ns.end_user_id or os.environ.get("RATATOSKR_END_USER_ID") or None
# Flag > $RATATOSKR_END_USER_ID > None. env.sh ships "ratatoskr-tui" as the project-stable partition.
6. [cleanup] RETURN ParsedArgs( 6. [cleanup] RETURN ParsedArgs(
send_content=ns.send, # may be None (TUI marker, issue #4 amendment) send_content=ns.send, # may be None (TUI marker, issue #4 amendment)
session_id=ns.session, session_id=ns.session,
@@ -281,6 +289,7 @@ STEPS:
api_key=api_key, api_key=api_key,
server_url=server_url, server_url=server_url,
raw=ns.raw, # issue #4 amendment raw=ns.raw, # issue #4 amendment
end_user_id=end_user_id, # issue #5 amendment (env-var fallback amended 2026-05-23)
) )
TESTS: TESTS:
happy_new [happy,tracer]: argv=["--send", "hi", "--new", "--agent", "mimir", "--api-key", "k"] → ParsedArgs(send_content="hi", session_id=None, new=True, agent_id="mimir", api_key="k", server_url="http://localhost:8000") happy_new [happy,tracer]: argv=["--send", "hi", "--new", "--agent", "mimir", "--api-key", "k"] → ParsedArgs(send_content="hi", session_id=None, new=True, agent_id="mimir", api_key="k", server_url="http://localhost:8000")
@@ -299,6 +308,11 @@ TESTS:
usage_session_with_agent [adversarial]: argv=["--send","hi","--session","s-1","--agent","x","--api-key","k"] → UsageError("--agent is required with --new and forbidden with --session") usage_session_with_agent [adversarial]: argv=["--send","hi","--session","s-1","--agent","x","--api-key","k"] → UsageError("--agent is required with --new and forbidden with --session")
auth_missing [error]: argv lacks --api-key and WORLDTREE_API_KEY unset → _AuthError auth_missing [error]: argv lacks --api-key and WORLDTREE_API_KEY unset → _AuthError
empty_send [adversarial]: argv=["--send", "", "--new", "--agent", "x", "--api-key", "k"] → UsageError (non-empty enforced via argparse type=lambda or explicit check) empty_send [adversarial]: argv=["--send", "", "--new", "--agent", "x", "--api-key", "k"] → UsageError (non-empty enforced via argparse type=lambda or explicit check)
happy_new_with_end_user_id [happy, issue #5]: argv includes --end-user-id alice → ParsedArgs.end_user_id == "alice"
end_user_id_default_none [trace, issue #5]: argv omits --end-user-id AND env unset → ParsedArgs.end_user_id is None
empty_end_user_id [adversarial, issue #5]: argv has --end-user-id "" → UsageError("--end-user-id must be non-empty when passed")
end_user_id_from_env [trace, issue #5 amended 2026-05-23]: env RATATOSKR_END_USER_ID="ratatoskr-tui"; flag omitted → ParsedArgs.end_user_id == "ratatoskr-tui"
end_user_id_flag_beats_env [trace, issue #5 amended 2026-05-23]: env set + flag passed → flag wins
``` ```
```contract ```contract
@@ -325,7 +339,7 @@ ERROR_ROUTING:
STEPS: STEPS:
1. [setup, flexibility=prescriptive] OPEN httpx.AsyncClient(base_url=args.server_url, headers={"Authorization": f"Bearer {args.api_key}"}, timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)) via async-with — read=None disables the SSE-killing 5s default (issue #1 [compatibility] constraint) 1. [setup, flexibility=prescriptive] OPEN httpx.AsyncClient(base_url=args.server_url, headers={"Authorization": f"Bearer {args.api_key}"}, timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)) via async-with — read=None disables the SSE-killing 5s default (issue #1 [compatibility] constraint)
2. [branch, flexibility=prescriptive] IF args.new: 2. [branch, flexibility=prescriptive] IF args.new:
TRY: info = await sessions.create_session(client, args.agent_id) TRY: info = await sessions.create_session(client, args.agent_id, end_user_id=args.end_user_id) # issue #5: thread end_user_id when set; None preserves pre-#5 body shape
ON AgentNotFound as exc: ON AgentNotFound as exc:
WRITE stderr; RETURN 12 WRITE stderr; RETURN 12
ON SessionApiFailed as exc: ON SessionApiFailed as exc:
docs/contracts/issues/4.contract.md
+105 -67
View File
@@ -89,7 +89,7 @@ The shell is the load-bearing primary surface. Together with `--send`, it makes
- **INV-004 [hard]**: Ctrl-D is bound to `app.exit(0)` unconditionally — immediate exit regardless of state. Abandons any in-flight turn (server-side stall watchdog handles the orphan per spec). - **INV-004 [hard]**: Ctrl-D is bound to `app.exit(0)` unconditionally — immediate exit regardless of state. Abandons any in-flight turn (server-side stall watchdog handles the orphan per spec).
- **INV-005 [hard]**: Markdown rendering on agent output is default-on; `--raw` is the opt-out. With markdown enabled, `Text` event deltas stream as raw text appended to the RichLog as they arrive (no mid-stream markdown attempt — partial markdown like `**hel` would render ugly), and on `Done` a separator + the full markdown-rendered assistant message is appended below the streamed deltas. **This means the assistant's response visibly appears TWICE in the transcript by design — once as the streamed raw deltas, once as the post-Done markdown render — separated by a horizontal-rule separator.** This is the v1 accepted trade-off for streaming-visibility-without-mid-stream-markdown-ugliness; the cleaner Static-then-commit pattern (streaming into a replaceable widget, then committing the markdown version in place) is documented in `open_questions:` as the follow-up if the double-display proves empirically noisy. Implementers MUST NOT attempt the Static-then-commit pattern in this shell — it's deferred. With `--raw`, only the streamed deltas appear; no post-Done re-render; no double-display. - **INV-005 [hard]**: Markdown rendering on agent output is default-on; `--raw` is the opt-out. With markdown enabled, `Text` event deltas stream as raw text appended to the RichLog as they arrive (no mid-stream markdown attempt — partial markdown like `**hel` would render ugly), and on `Done` a separator + the full markdown-rendered assistant message is appended below the streamed deltas. **This means the assistant's response visibly appears TWICE in the transcript by design — once as the streamed raw deltas, once as the post-Done markdown render — separated by a horizontal-rule separator.** This is the v1 accepted trade-off for streaming-visibility-without-mid-stream-markdown-ugliness; the cleaner Static-then-commit pattern (streaming into a replaceable widget, then committing the markdown version in place) is documented in `open_questions:` as the follow-up if the double-display proves empirically noisy. Implementers MUST NOT attempt the Static-then-commit pattern in this shell — it's deferred. With `--raw`, only the streamed deltas appear; no post-Done re-render; no double-display.
- **INV-006 [hard]**: User-prompt echo in the transcript MUST visibly distinguish user input from assistant output. Format: `❯ <content>` for user lines (with a literal `❯` prefix); assistant lines have no prefix. The prefix is also a screen-reader-friendly affordance. - **INV-006 [hard]**: User-prompt echo in the transcript MUST visibly distinguish user input from assistant output. Format: `❯ <content>` for user lines (with a literal `❯` prefix); assistant lines have no prefix. The prefix is also a screen-reader-friendly affordance.
- **INV-007 [hard]**: One `httpx.AsyncClient` per app lifetime — opened in `on_mount`, closed in `on_unmount` via the async-with context manager pattern. The client is NOT recreated per turn (would burn the TCP connection pool). - **INV-007 [hard]**: One `httpx.AsyncClient` per app lifetime — opened by `run_tui`'s `async with` BEFORE `App.run_async()` is entered and closed by the same `async with` AFTER `App.run_async()` returns (per issue #6 INV-002). The App is a consumer of an externally-owned client; it MUST NOT call `self.client.aclose()`. The client is NOT recreated per turn (would burn the TCP connection pool).
- **INV-008 [hard]**: Mid-session network/protocol errors (`SseConnectionDropped`, `SseConnectFailed`, `MalformedSseId`, `MalformedSseData` (issue #7), `TurnIdFlip`) during a streaming turn render as error lines in the transcript and return the app to **idle** state — they do NOT exit the app. Only initial session-create errors exit (per Data flow exit codes). - **INV-008 [hard]**: Mid-session network/protocol errors (`SseConnectionDropped`, `SseConnectFailed`, `MalformedSseId`, `MalformedSseData` (issue #7), `TurnIdFlip`) during a streaming turn render as error lines in the transcript and return the app to **idle** state — they do NOT exit the app. Only initial session-create errors exit (per Data flow exit codes).
- **INV-009 [hard]**: No `core.*` / `worldtree.*` imports. The boundary smoke (`tests/test_no_worldtree_imports.py`) covers `src/ratatoskr/` as a whole including the new tui.py. - **INV-009 [hard]**: No `core.*` / `worldtree.*` imports. The boundary smoke (`tests/test_no_worldtree_imports.py`) covers `src/ratatoskr/` as a whole including the new tui.py.
@@ -129,48 +129,102 @@ ratatoskr <args> [shell entry, registered in pyp
└─ args.send_content is None ──► from ratatoskr.tui import run_tui [lazy import] └─ args.send_content is None ──► from ratatoskr.tui import run_tui [lazy import]
return run_tui(args) return run_tui(args)
│ │
└─ RatatoskrApp(args).run() └─ asyncio.run(_resolve_then_run(args)) [issue #6 amendment]
│ │
├─ on_mount: open AsyncClient, create_session (if --new), └─ async with httpx.AsyncClient(...) as client:
│ init footer with agent_id + session_id_tail8 │
├─ on_input_submitted: spawn _stream_turn_worker(content) ├─ pre-flight session resolve (--new → create_session,
│ _stream_turn_worker: │ else attach args.session_id). Errors → real stderr,
│ for event in stream_turn(...): │ return appropriate exit code (12 / 20 / 21) BEFORE
│ _render_event_to_log(event, log) │ the alt-screen opens (issue #6 INV-001 / INV-006).
│ on Done: if not raw, append separator + markdown render │
│ transition: streaming → idle ├─ app = RatatoskrApp(args, session_id=..., agent_id=...,
├─ action_interrupt (ctrl+c): two-stage state machine per INV-003 │ client=client)
├─ action_quit (ctrl+d): app.exit(0) └─ await app.run_async():
└─ on_unmount: close AsyncClient │
├─ on_mount: populate identity widget from pre-
│ resolved state; state=idle
├─ on_input_submitted: spawn _stream_turn_worker(content)
│ _stream_turn_worker:
│ for event in stream_turn(...):
│ _render_event_to_log(event, log)
│ on Done: if not raw, append separator + markdown
│ transition: streaming → idle
├─ action_interrupt (ctrl+c): two-stage state machine
├─ action_quit (ctrl+d): app.exit(0)
└─ on_unmount: no-op (client closed by async-with above)
``` ```
--- ---
```contract ```contract
FN run_tui(args: ParsedArgs) -> int FN run_tui(args: ParsedArgs) -> int
BRIEF: Sync entry point called from `ratatoskr.cli.main`'s lazy-import branch. Constructs the `RatatoskrApp` with the parsed args and runs it under Textual's loop; returns the App's exit code. BRIEF: Sync entry point called from `ratatoskr.cli.main`'s lazy-import branch. Thin sync wrapper around `asyncio.run(_resolve_then_run(args))` — per issue #6, the actual work (AsyncClient open, pre-flight session resolution with stderr error routing, then App.run_async) happens inside the single async helper so everything runs in one event loop.
PRE: [PRE-001 hard] args is a ParsedArgs with args.send_content is None (TUI mode marker) -- assert isinstance(args, ParsedArgs) and args.send_content is None PRE: [PRE-001 hard] args is a ParsedArgs with args.send_content is None (TUI mode marker) -- assert isinstance(args, ParsedArgs) and args.send_content is None
PRE: [PRE-002 hard] exactly one of args.session_id / args.new is set -- assert bool(args.session_id) != bool(args.new) (post-_parse_args xor validation, hold-over assertion) PRE: [PRE-002 hard] exactly one of args.session_id / args.new is set -- assert bool(args.session_id) != bool(args.new) (post-_parse_args xor validation, hold-over assertion)
POST: [POST-001 return_value] returns the exit code from App.run() (0, 3, 12, 20, 21 per Data flow table) POST: [POST-001 return_value] returns the exit code from _resolve_then_run (0, 3, 12, 20, 21 per Data flow table)
ERROR_ROUTING: ERROR_ROUTING:
(none at this level — App.run() catches its own exceptions and surfaces them as exit codes; uncaught errors propagate as Python exceptions to the cli's main wrapper) (none at this level — _resolve_then_run handles all exit codes; uncaught errors propagate as Python exceptions to the cli's main wrapper)
STEPS: STEPS:
1. [setup, flexibility=prescriptive] Validate inputs per PRE-001..PRE-002 1. [setup, flexibility=prescriptive] Validate inputs per PRE-001..PRE-002
2. [sequential, flexibility=prescriptive] Construct app = RatatoskrApp(args) 2. [sequential, flexibility=prescriptive] RETURN asyncio.run(_resolve_then_run(args))
3. [sequential, flexibility=prescriptive] RETURN app.run() — Textual's sync runner; manages its own asyncio loop
TESTS: TESTS:
happy_returns_zero_on_quit [happy,tracer]: construct args with --session s-1; monkeypatch RatatoskrApp.run to capture invocation and return 0; run_tui returns 0; the captured app was constructed with the passed args (verifies run_tui correctly wraps App.run). The piloted Ctrl-D exit path is covered separately by TestActionQuit.test_idle_ctrl_d_exits_zero — App.run() is sync and can't be driven by Pilot, so run_tui's wrapping behavior is tested via monkeypatch. happy_returns_zero_on_quit [happy,tracer]: construct args with --session s-1; monkeypatch RatatoskrApp.run_async to capture invocation and return 0; run_tui returns 0; the captured app was constructed with the passed args (verifies run_tui correctly wraps app.run_async via _resolve_then_run).
precondition_send_content_none [adversarial]: args with send_content="x" → AssertionError before run() (PRE-001 catches the misuse) precondition_send_content_none [adversarial]: args with send_content="x" → AssertionError before any asyncio.run (PRE-001 catches the misuse)
```
```contract
FN _resolve_then_run(args: ParsedArgs) -> int # NEW per issue #6
ASYNC: yes
BRIEF: Pre-flight session resolution then App.run_async() inside one event loop. Errors at this layer (AgentNotFound, SessionApiFailed, network errors) print to `sys.stderr` (the operator's real terminal) and short-circuit BEFORE the alt-screen opens (issue #6 INV-001). The label format + exit codes match `ratatoskr.cli._amain`'s verbatim (issue #6 INV-006), so operators see one vocabulary across `--send` and TUI modes. Owns the AsyncClient lifecycle via `async with` (issue #6 INV-002).
PRE: [PRE-001 hard] args is a ParsedArgs with args.send_content is None
POST: [POST-001 return_value] returns exit code (12 on AgentNotFound, 20 on SessionApiFailed, 21 on network error, OR the App's run_async return value)
POST: [POST-002 side_effect] the AsyncClient is opened BEFORE create_session and closed AFTER app.run_async returns (or after the error-routed return)
ERROR_ROUTING:
AgentNotFound (from create_session):
local_handling: sys.stderr.write(f"[agent_not_found] agent_id={exc.agent_id}\n")
flow_control: return 12 — alt-screen never opens
state_recovery: none
SessionApiFailed (from create_session):
local_handling: sys.stderr.write(f"[session_api_failed] status={exc.status} body={exc.body!r}\n")
flow_control: return 20 — alt-screen never opens
state_recovery: none
httpx.ConnectError | httpx.ReadTimeout | httpx.TransportError (from create_session):
local_handling: sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
flow_control: return 21 — alt-screen never opens
state_recovery: none
STEPS:
1. [setup, flexibility=prescriptive] OPEN httpx.AsyncClient(base_url=args.server_url, headers={"Authorization": f"Bearer {args.api_key}"}, timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)) via `async with` — read=None disables the SSE-killing 5s default (issue #1 [compatibility] constraint)
2. [branch, flexibility=prescriptive] IF args.new:
TRY: info = await create_session(client, args.agent_id, end_user_id=args.end_user_id) # issue #5: thread end_user_id when set; None preserves pre-#5 body shape
ON AgentNotFound | SessionApiFailed | httpx.ConnectError | httpx.ReadTimeout | httpx.TransportError: handle per ERROR_ROUTING (stderr + return code)
SET session_id = info.session_id; agent_id = info.agent_id
ELSE:
SET session_id = args.session_id; agent_id = args.agent_id # may be None — INV-002 carve-out preserved
3. [sequential, flexibility=prescriptive] Construct app = RatatoskrApp(args, session_id=session_id, agent_id=agent_id, client=client)
4. [sequential, flexibility=prescriptive] exit_code = await app.run_async() — Textual's async-runner; same event loop as the AsyncClient
5. [cleanup, flexibility=prescriptive] RETURN exit_code or 0
TESTS:
alt_screen_never_opens_on_resolve_error [trace]: monkeypatch RatatoskrApp.run_async to a sentinel that fails if called; respx → 404 from POST /sessions; assert run_tui returns 12; assert the sentinel was NEVER invoked (probes issue #6 INV-001).
agent_not_found_on_resolve [error]: --new + 404 → run_tui returns 12; capsys.readouterr().err contains "[agent_not_found]" + "agent_id=mimir".
session_api_failed_on_resolve [error]: --new + 500 → run_tui returns 20; capsys stderr contains "[session_api_failed]" + "status=500".
network_error_on_resolve [error]: --new + httpx.ConnectError → run_tui returns 21; capsys stderr contains "[network_error]" + "ConnectError".
stderr_label_format_matches_cli [trace]: cli._amain and _resolve_then_run produce identical stderr lines for AgentNotFound (probes issue #6 INV-006). Drive each path with respx → 404 and capsys-capture both stderr outputs; assert string equality and "[agent_not_found] agent_id=mimir\n" verbatim.
client_open_after_resolve [trace]: monkeypatch RatatoskrApp.run_async to capture self.client; assert client is not None and client.is_closed is False AT the moment run_async executes (probes that the App receives a live, open client from _resolve_then_run).
client_lifetime_owned_by_run_tui [trace]: monkeypatch RatatoskrApp.run_async to capture self.client and confirm it's open during run; after run_tui returns, assert the captured client.is_closed is True (probes issue #6 INV-002 — the async-with closes the client AFTER run_async, not on_unmount).
run_tui_closes_client_on_app_exit: same as client_lifetime_owned_by_run_tui — the async-with in _resolve_then_run is the closing site.
happy_new_with_end_user_id_resolve [happy, issue #5]: args.end_user_id="alice" → POST /sessions outbound body == {"agent_id": <agent>, "end_user_id": "alice"}. (Issue #5's contract names this `_mount`; post-#6 the equivalent site is `_resolve_then_run`.)
``` ```
```contract ```contract
CLASS RatatoskrApp(textual.app.App[int]) CLASS RatatoskrApp(textual.app.App[int])
BRIEF: Textual app — single chat pane shell. Holds the parsed args, the active session_id, the httpx.AsyncClient, and the Ctrl-C state machine. Exposes the bindings + the worker coordination for stream_turn / cancel_turn. BRIEF: Textual app — single chat pane shell. Consumer of an externally-owned `httpx.AsyncClient` (passed at __init__ per issue #6 INV-002). Holds the parsed args, the pre-resolved session_id + agent_id, the client reference, and the Ctrl-C state machine. Exposes the bindings + the worker coordination for stream_turn / cancel_turn.
__init__: `def __init__(self, args: ParsedArgs, *, session_id: str, agent_id: str | None, client: httpx.AsyncClient) -> None` — per issue #6 INV-003, session_id and client are REQUIRED at construction; the App no longer mints anything in on_mount.
PROPERTIES: PROPERTIES:
args: ParsedArgs # passed in __init__ args: ParsedArgs # passed in __init__
session_id: str | None # set in on_mount (after create_session if --new) session_id: str # passed in __init__ (pre-resolved by _resolve_then_run; issue #6)
agent_id: str | None # set in on_mount agent_id: str | None # passed in __init__ (may be None for --session without --agent; INV-002 carve-out)
client: httpx.AsyncClient | None # opened in on_mount, closed in on_unmount client: httpx.AsyncClient # passed in __init__; lifecycle owned by run_tui's async-with (INV-007 amended)
state: Literal["idle", "streaming", "cancelling"] # INV-003 state machine state: Literal["idle", "streaming", "cancelling"] # INV-003 state machine
active_turn_id: int | None # set when first event of a turn yields; cleared on terminal active_turn_id: int | None # set when first event of a turn yields; cleared on terminal
stream_worker: textual.worker.Worker | None # the current _stream_turn_worker task stream_worker: textual.worker.Worker | None # the current _stream_turn_worker task
@@ -184,52 +238,34 @@ COMPOSE shape (declarative — implementer chooses CSS file vs inline):
Static("", id="identity") # INV-002: visible session-identity strip; rendered by on_mount Static("", id="identity") # INV-002: visible session-identity strip; rendered by on_mount
Static(HINT_IDLE, id="hint") # INV-003: visible Ctrl-C state hint; updated on state transitions Static(HINT_IDLE, id="hint") # INV-003: visible Ctrl-C state hint; updated on state transitions
Footer() Footer()
INV-WIRE-001: One AsyncClient lifecycle per app lifetime (INV-007). INV-WIRE-001: AsyncClient lifetime owned by run_tui's async-with (INV-007 amended; issue #6 INV-002).
INV-WIRE-002: state transitions strictly idle ↔ streaming ↔ cancelling per INV-003. INV-WIRE-002: state transitions strictly idle ↔ streaming ↔ cancelling per INV-003.
``` ```
```contract ```contract
FN RatatoskrApp.on_mount(self) -> None FN RatatoskrApp.on_mount(self) -> None
BRIEF: Lifecycle hook. Opens the httpx.AsyncClient, mints or attaches the session, populates the footer with agent_id + session_id_tail8, sets state to "idle". BRIEF: Lifecycle hook. Per issue #6: NARROWED to identity-widget population from pre-resolved state. No more session-create branch (moved to _resolve_then_run); no more client-open (moved to run_tui's async-with). Just populates the identity widget + sets idle state.
PRE: [PRE-001 hard] self.client is None (on_mount fires once per app instance) -- assert self.client is None PRE: [PRE-001 hard] self.client is not None (set in __init__ from _resolve_then_run; issue #6 INV-003) -- assert self.client is not None
POST: [POST-001 state_change] self.client is an open httpx.AsyncClient bound to args.server_url with the Bearer auth header PRE: [PRE-002 hard] self.session_id is not None (set in __init__ from _resolve_then_run) -- assert self.session_id is not None
POST: [POST-002 state_change] self.session_id is non-empty (either from args.session_id or from a successful create_session) POST: [POST-001 side_effect] Footer subtitle shows `<agent_id> · …<session_id[-8:]>` (INV-002 session-identity-always-visible)
POST: [POST-003 state_change] self.agent_id is non-empty when args.new (from SessionInfo.agent_id after create_session) OR self.agent_id is the value of args.agent_id when args.session is used (may be None per INV-002 carve-out — `GET /sessions/{id}` agent lookup is explicitly out of scope for this shell) POST: [POST-002 side_effect] The #identity Static widget renders the same identity string
POST: [POST-004 side_effect] Footer subtitle shows `<agent_id> · …<session_id[-8:]>` (INV-002 session-identity-always-visible) POST: [POST-003 state_change] self.state == "idle"; the #hint Static widget shows "Ctrl-C twice to exit"
POST: [POST-005 state_change] self.state == "idle"; the footer hint widget shows "Ctrl-C twice to exit"
ERROR_ROUTING: ERROR_ROUTING:
AgentNotFound (from create_session): (none — session-resolution errors are handled at the _resolve_then_run layer BEFORE on_mount can be reached; on_mount is now error-free per issue #6 INV-001)
local_handling: append `[agent_not_found] agent_id={exc.agent_id}` to RichLog as an error line; call self.exit(12)
flow_control: abort the mount (the app exits before user can interact)
state_recovery: none
SessionApiFailed (from create_session):
local_handling: append `[session_api_failed] status={exc.status} body={exc.body!r}` to RichLog; self.exit(20)
flow_control: abort
state_recovery: none
httpx.ConnectError | httpx.ReadTimeout | httpx.TransportError (from create_session):
local_handling: append `[network_error] {type(exc).__name__}: {exc}` to RichLog; self.exit(21)
flow_control: abort
state_recovery: none
STEPS: STEPS:
1. [setup, flexibility=prescriptive] Validate PRE-001 1. [setup, flexibility=prescriptive] Validate PRE-001..PRE-002
2. [sequential, flexibility=prescriptive] Open AsyncClient: self.client = httpx.AsyncClient(base_url=args.server_url, headers={"Authorization": f"Bearer {args.api_key}"}, timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)) — read=None disables the SSE-killing 5s default (issue #1 [compatibility] constraint) 2. [sequential, flexibility=prescriptive] Compute identity: agent_slot = self.agent_id or "<unknown>"; identity = f"{agent_slot} · …{self.session_id[-8:]}"
3. [branch, flexibility=prescriptive] IF args.new: 3. [sequential, flexibility=prescriptive] Populate widgets: self.sub_title = identity (Header subtitle mirror); self.query_one("#identity", Static).update(identity)
TRY: info = await create_session(self.client, args.agent_id) 4. [sequential, flexibility=prescriptive] SET self.state = "idle"; update #hint widget to HINT_IDLE ("Ctrl-C twice to exit")
ON AgentNotFound | SessionApiFailed | httpx.ConnectError | httpx.ReadTimeout | httpx.TransportError: handle per ERROR_ROUTING (append + exit)
SET self.session_id = info.session_id; self.agent_id = info.agent_id
ELSE:
SET self.session_id = args.session_id; self.agent_id = args.agent_id (when args.session is used, --agent is forbidden per issue #3 INV-004 — agent_id may be empty here)
(When session_id is set but agent_id unknown: optionally GET /sessions/{id} for it; OUT OF SCOPE for this shell — display `<unknown> · …<tail>` instead. Single follow-up if it becomes noisy.)
4. [sequential, flexibility=prescriptive] Update footer: self.sub_title = f"{self.agent_id or '<unknown>'} · …{self.session_id[-8:]}"; render hint "Ctrl-C twice to exit"
5. [sequential, flexibility=prescriptive] SET self.state = "idle"
TESTS: TESTS:
happy_new_session_mount [happy,tracer]: --new --agent mimir; respx mocks POST /sessions → 201; Pilot.pause() → app.session_id is "s-new", app.agent_id is "mimir", footer text contains "mimir · …", state=="idle" happy_new_session_mount [happy,tracer]: construct via _resolved_app(_args_new(), session_id="s-new12345", agent_id="mimir"); Pilot.pause() → app.session_id == "s-new12345", app.agent_id == "mimir", state == "idle", footer contains "mimir · …<tail>"
happy_existing_session_mount [happy]: --session s-1; no POST /sessions; Pilot.pause() → app.session_id is "s-1", footer shows agent (or <unknown>), state=="idle" happy_existing_session_mount [happy]: construct via _resolved_app(_args_existing(session_id="s-existing-tail8x")); args.agent_id is None → app.agent_id is None → identity shows "<unknown> · …<tail>" (INV-002 carve-out)
agent_not_found_on_mount [error]: --new; POST /sessions → 404 → app exits 12; RichLog contains "[agent_not_found]" footer_identity_visible_first_frame [trace]: INV-002 — after Pilot.pause(), the #identity Static widget renders the agent_slot + session_id_tail8 substring before any other interaction.
session_api_failed_on_mount [error]: --new; POST /sessions → 500 → app exits 20; RichLog contains "[session_api_failed]" # Error tests moved to the _resolve_then_run TESTS block per issue #6:
network_error_on_mount [error]: --new; POST /sessions raises httpx.ConnectError → app exits 21; RichLog contains "[network_error]" # agent_not_found_on_mount → agent_not_found_on_resolve (capsys stderr)
footer_identity_visible_first_frame [trace]: INV-002 — after Pilot.pause(), query the footer and assert the agent_id + session_id_tail8 substring is present before any other interaction # session_api_failed_on_mount → session_api_failed_on_resolve
client_open_after_mount [trace]: post-mount self.client is not None and is_closed is False # network_error_on_mount → network_error_on_resolve
# client_open_after_mount → client_open_after_resolve
``` ```
```contract ```contract
@@ -394,14 +430,16 @@ TESTS:
```contract ```contract
FN RatatoskrApp.on_unmount(self) -> None FN RatatoskrApp.on_unmount(self) -> None
BRIEF: Lifecycle hook. Closes the httpx.AsyncClient cleanly. Textual fires on_unmount as part of app shutdown. BRIEF: Lifecycle hook. Per issue #6 INV-002: NARROWED to a no-op. The client lifetime is managed by `run_tui`'s `async with`, NOT by this hook — calling `self.client.aclose()` here would close the client while `_resolve_then_run`'s async-with still holds it.
PRE: (none) PRE: (none)
POST: [POST-001 state_change] self.client is closed (httpx.AsyncClient.is_closed is True) OR was already None (app never reached on_mount due to early failure) POST: (none — no side effects)
STEPS: STEPS:
1. [branch, flexibility=prescriptive] IF self.client is not None AND NOT self.client.is_closed: 1. [sequential, flexibility=prescriptive] return None
await self.client.aclose()
TESTS: TESTS:
unmount_closes_client [happy,tracer]: --session s-1; Pilot.press("ctrl+d") to trigger shutdown; after exit, app.client.is_closed is True # unmount_closes_client → moved to run_tui_closes_client_on_app_exit at the
# _resolve_then_run layer per issue #6: the close site is the async-with
# exiting AFTER app.run_async returns, not on_unmount.
(none — this hook is intentionally empty; coverage lives at the _resolve_then_run layer)
``` ```
```contract ```contract
docs/contracts/issues/5.contract.md
+190
View File
@@ -0,0 +1,190 @@
---
contract_version: "2.1"
target_module: "ratatoskr.sessions"
scope: "Add `end_user_id` support to the POST /sessions flow so per-end-user agents (lofn confirmed; presumably the Persona/Vili family) can be smoked. Small surface change distributed across three existing modules via in-place contract amendments: `ratatoskr.sessions.create_session` gains a keyword-only `end_user_id: str | None = None` parameter that is threaded into the POST body when non-None; `ratatoskr.cli` adds an `--end-user-id <id>` flag + corresponding `ParsedArgs.end_user_id: str | None` field + threading through `_amain`; `ratatoskr.tui.on_mount` threads `args.end_user_id` into its `create_session` call. No new modules, no new files (apart from this contract). Default-omitted preserves backwards compatibility: existing `mimir` smoke flows that don't pass `--end-user-id` continue to work unchanged."
depends_on:
- "httpx"
used_by: []
language: "python"
complexity: "low"
estimated_loc: 40
confidence: 0.9
assumptions:
- "Worldtree spec pin (`docs/conversation-api-spec.md` at v1.0, repo SHA `55101e909abcd2219833266b6f905c5bc956e0f0`, v0.19.0) declares `end_user_id` as a field on POST /sessions — required by some agents (lofn confirmed via 422 `end_user_id_required` on 2026-05-21 smoke), optional/ignored by others (mimir doesn't reject when omitted)."
- "The 422 response shape is `{\"detail\":{\"error_code\":\"end_user_id_required\",\"message\":\"...\"}}` per the smoke evidence. The existing `SessionApiFailed` exception handler in `_amain` / `on_mount` already maps 422s to exit 20 / `[session_api_failed]` label, so missing `--end-user-id` for a per-user agent surfaces as that label rather than a more specific hint. Defer 422-→-hint translation to a follow-up issue."
- "`end_user_id` is a free-form string from the operator's perspective. Per worldtree-dev (althing 01KSBARG2B8M, 2026-05-23): it's a *runtime partition key* — same value → same long-term-memory + persona/valence partition; different values → fully isolated partitions. The server validates it as non-empty; ratatoskr also rejects empty client-side (INV-001)."
- "**Env-var fallback amended 2026-05-23**: `$RATATOSKR_END_USER_ID` populates the field when the flag is omitted. Resolution order: `--end-user-id` flag > `$RATATOSKR_END_USER_ID` > None. `env.sh` ships `RATATOSKR_END_USER_ID=\"ratatoskr-tui\"` as the project-stable default. Original posture rejected env-var fallback as 'papering over isolation'; revised after worldtree-dev's guidance that the realistic use case (single-operator debugging) wants partition continuity. The override path preserves isolation when needed."
- "**Forthcoming breaking change (Worldtree #196)**: the `end_user_id` field is being replaced by polymorphic `subject: {type, id}` at a future v0.22.x / v0.23.0. Spec is LOCKED, substrate not yet shipped. Don't pre-implement; migrate when the substrate change lands (deprecation warnings will fire per call as heads-up). Tracked as a separate ratatoskr issue."
open_questions:
- "Should the 422 `end_user_id_required` error_code trigger a user-friendly hint suggesting `--end-user-id <id>` rather than the raw body? Draft: no for v1 — the raw `[session_api_failed]` label is honest about what came back. Add the hint in a follow-up if the bare label proves empirically confusing."
- "Should `ratatoskr.sessions.list_sessions` also accept `end_user_id` to filter by end-user-id? Spec allows it. Draft: no for this issue (out of scope; list_sessions has no consumer yet in the CLI/TUI — `--send` and the TUI shell only call create). File if the startup-session-picker issue needs it."
prd:
issue: 5
issue_url: "https://gitea.phasefinal.com/vh/ratatoskr/issues/5"
body_sha256_16: "03fe1fa547235f32"
lock_in_comment_id: null
lock_in_sha256_16: null
lock_in_at: null
pinned_at: "2026-05-22T05:03:17+00:00"
dependencies:
- issue: 2
path: "src/ratatoskr/sessions.py"
reason: "In-place contract amendment: `create_session` signature widens to accept `end_user_id`; POST body construction gains a conditional field; new TESTS entries for present + omitted cases."
- issue: 3
path: "src/ratatoskr/cli.py"
reason: "In-place contract amendment: `_parse_args` adds `--end-user-id` flag; `ParsedArgs` gains `end_user_id: str | None`; `_amain` threads it into the `create_session(...)` call when `args.new`."
- issue: 4
path: "src/ratatoskr/tui.py"
reason: "In-place contract amendment: `RatatoskrApp.on_mount` threads `self.args.end_user_id` into its `create_session(...)` call when `args.new`."
---
# end_user_id support — POST /sessions parameter for per-user agents
## Context
Manual smoke against personal Worldtree on 2026-05-21 (`ratatoskr --send "test" --new --agent lofn`) returned a 422 from POST /sessions:
```
[session_api_failed] status=422 body=b'{"detail":{"error_code":"end_user_id_required","message":"end_user_id is required (non-empty string) for Lofn sessions"}}'
```
The `lofn` agent (and presumably others in the Persona/Vili family) requires an `end_user_id` field in the create-session body to scope state per end-user. Ratatoskr's current `create_session(client, agent_id)` only sends `{"agent_id": agent_id}`, so per-user agents are unreachable. Mimir, the agent used for prior smoke validation, doesn't require `end_user_id` and continues to work unchanged.
This issue threads `end_user_id` through the small chain: CLI flag → `ParsedArgs` → `_amain` / `on_mount` → `create_session` → POST body. The change is small (a keyword-only parameter widening + one new CLI flag + arg-passing in two places) but touches three existing contracts (#2, #3, #4) in-place. This issue's own contract is mostly a coordinating record + the new test additions.
## Data flow
**Input:**
- Operator passes `--end-user-id <id>` on the CLI when invoking against a per-user agent.
- Worldtree's POST /sessions endpoint accepts `end_user_id: str` as an optional field; rejects with 422 `end_user_id_required` when omitted for an agent that requires it.
**Output:**
- POST /sessions body becomes `{"agent_id": <agent>, "end_user_id": <id>}` when `--end-user-id` was passed; remains `{"agent_id": <agent>}` when omitted.
- Returned `SessionInfo` is unchanged shape (the server response doesn't change; only the request body widens).
**Side effects:** outbound HTTP only (no new state). No persistence — operator passes `--end-user-id` on each invocation; ratatoskr doesn't remember it.
## Invariants
- **INV-001 [hard]**: `end_user_id`, when passed via `--end-user-id`, MUST be a non-empty string. Empty-string `--end-user-id ""` raises `UsageError` BEFORE any HTTP call (mirrors the existing `--send ""` empty-check in `_parse_args`). Server-side validation also rejects empty, so client-side rejection is friendlier.
- **INV-002 [hard]**: `create_session(...)` MUST omit the `end_user_id` field from the POST body when the kwarg is `None`. This preserves the existing 2-field body shape for agents that don't require `end_user_id` (mimir today; other agents in the future). Sending an empty-string `end_user_id` is NOT equivalent to omitting it (server rejects empty; INV-001 catches empty before HTTP).
- **INV-003 [hard]**: Backwards compatibility: all existing `mimir` smoke flows that don't pass `--end-user-id` continue to work unchanged. The CLI's `--end-user-id` flag is OPTIONAL (no default required); `_parse_args` succeeds without it; `_amain` / `on_mount` call `create_session(client, agent_id)` (no end_user_id kwarg) when the flag wasn't passed, identical to today's behavior.
- **INV-004 [hard]**: No `core.*` / `worldtree.*` imports (existing boundary; this issue doesn't change it).
## Out of scope
- **422 `end_user_id_required` → user-friendly hint.** The raw `[session_api_failed] status=422 body=...` label is honest; the message in the body (`"end_user_id is required (non-empty string) for Lofn sessions"`) is reasonably clear. Hint translation deferred to a follow-up if the bare label proves empirically confusing.
- **`list_sessions` filter by `end_user_id`.** Spec allows it; no consumer needs it yet (the startup-session-picker issue is a separate ticket).
- **Environment-variable fallback for `end_user_id`.** Auto-defaulting (e.g., `$USER`, `$RATATOSKR_END_USER_ID`) would paper over the per-user-isolation intent. Explicit flag only.
- **TUI startup error visibility** — when `--end-user-id` is missing for a per-user agent, the TUI's `[session_api_failed]` line still gets eaten by the alt-screen teardown. That's issue #6's scope, not this one.
- **Empty-data SSE crash** — separate issue #7; mid-stream JSONDecodeError on empty `sse.data` is independent of `end_user_id`.
- **Other per-agent-required fields.** If Worldtree later adds another required-by-some-agents field, file a sibling issue; don't generalize this one prematurely.
## Constraints
- **[compatibility]** Spec pin unchanged. The `end_user_id` field is already in the v0.19.0 spec; we're just starting to use it.
- **[performance]** No new round-trips; no new state. The change is one extra optional field in an existing POST body.
- **[security]** `end_user_id` is logged as part of `[create_session]` (alongside `session_id`, `agent_id`) — operator's choice of identifier may carry semantic meaning, but it's not auth-bearing. Don't redact.
- **[style]** Keyword-only parameter for `end_user_id` (matches `persist_partial` on `cancel_turn`). Ruff line-length=100.
---
## In-place amendments (the work)
This issue's contract is small because the real work is amendments to issues #2, #3, #4. The amendments are pinned here so reviewers see the whole change in one place; the actual contract files at `docs/contracts/issues/2.contract.md`, `3.contract.md`, `4.contract.md` are amended in-place as part of this issue's commit.
### Issue #2 (`ratatoskr.sessions`) amendments
**`create_session` signature widens:**
```contract
FN create_session(client: httpx.AsyncClient, agent_id: str, *, end_user_id: str | None = None) -> SessionInfo
BRIEF: POST /sessions with {"agent_id": agent_id} and optionally {"end_user_id": end_user_id} when non-None. Returns SessionInfo populated from the 201 response.
PRE: [PRE-001 hard] client is not None
PRE: [PRE-002 hard] agent_id is a non-empty string
PRE: [PRE-003 hard] end_user_id is None OR a non-empty string -- assert end_user_id is None or (isinstance(end_user_id, str) and end_user_id)
POST: [POST-001 side_effect] exactly one POST to /sessions was issued; body is {"agent_id": agent_id} when end_user_id is None, OR {"agent_id": agent_id, "end_user_id": end_user_id} when non-None
... (other POST/ERROR_ROUTING unchanged) ...
STEPS:
...
2. [sequential, flexibility=prescriptive] Build body: body = {"agent_id": agent_id}; IF end_user_id is not None: body["end_user_id"] = end_user_id
3. [sequential, flexibility=prescriptive] CALL client.post("/sessions", json=body)
...
```
**New TESTS entries:**
- `happy_create_with_end_user_id [happy]`: pass `end_user_id="alice"` → outbound JSON body == `{"agent_id": "mimir", "end_user_id": "alice"}` byte-for-byte; SessionInfo populated as today.
- `default_omits_end_user_id [trace]`: omit `end_user_id` kwarg → outbound JSON body == `{"agent_id": "mimir"}` (no end_user_id key); preserves the issue #2 baseline.
- `empty_end_user_id [adversarial]`: `end_user_id=""` → AssertionError before HTTP (PRE-003).
### Issue #3 (`ratatoskr.cli`) amendments
**`_parse_args` STEPS gain a new flag + env-var fallback (amended 2026-05-23):**
```
1. [setup] Construct argparse.ArgumentParser:
... (existing flags) ...
--end-user-id <id> (str, optional — non-empty if passed; validated in step 2b)
2a. [branch] IF ns.send is not None AND not ns.send: UsageError("--send content must be non-empty") (unchanged)
2b. [branch, NEW] IF ns.end_user_id is not None AND not ns.end_user_id: UsageError("--end-user-id must be non-empty when passed")
... (rest unchanged) ...
5b. [sequential, AMENDED 2026-05-23] Resolve end_user_id with env-var fallback:
end_user_id = ns.end_user_id or os.environ.get("RATATOSKR_END_USER_ID") or None
(Flag wins; env fallback active when flag omitted; None when neither set.)
6. [cleanup] RETURN ParsedArgs(
... existing fields ...,
end_user_id=end_user_id,
)
```
**`ParsedArgs` gains `end_user_id: str | None`** (default semantics handled by argparse default=None).
**`_amain` threads through to `create_session`:**
```
IF args.new:
TRY: info = await create_session(client, args.agent_id, end_user_id=args.end_user_id)
... existing error handling unchanged ...
```
**New TESTS:**
- `happy_new_with_end_user_id [happy]`: argv includes `--end-user-id alice` → ParsedArgs.end_user_id == "alice".
- `end_user_id_default_none [trace]`: argv omits `--end-user-id` AND env unset → ParsedArgs.end_user_id is None.
- `empty_end_user_id [adversarial]`: argv has `--end-user-id ""` → UsageError.
- `end_user_id_from_env [trace, amended 2026-05-23]`: env `RATATOSKR_END_USER_ID="ratatoskr-tui"`, flag omitted → ParsedArgs.end_user_id == "ratatoskr-tui".
- `end_user_id_flag_beats_env [trace, amended 2026-05-23]`: env set + flag passed → flag wins.
- Update `_amain`'s `happy_new_session_then_stream` test: respx assertion on the POST /sessions body now confirms `end_user_id` is OR isn't present per the test variant.
### Issue #4 (`ratatoskr.tui`) amendments
**Post-#6 adjustment:** issue #6 (landed 2026-05-23, after this contract was drafted)
moved session resolution OUT of `on_mount` (alt-screen) into `_resolve_then_run`
(pre-`App.run_async()`). The equivalent end_user_id threading site is therefore
`_resolve_then_run`'s `create_session` call, not `on_mount`'s. `on_mount`
no longer calls `create_session` at all.
**`_resolve_then_run` STEPS gain end_user_id threading (was on_mount pre-#6):**
```
2. [branch] IF args.new:
TRY: info = await create_session(client, args.agent_id, end_user_id=args.end_user_id)
... existing error handling unchanged ...
```
**New TEST (renamed _mount → _resolve per #6):**
- `happy_new_with_end_user_id_resolve [happy]`: `_args_new(end_user_id="alice")`;
respx mocks POST /sessions; assert outbound body has `end_user_id: alice`.
---
## Acceptance
- All three amended contracts (#2, #3, #4) drift-check clean.
- All existing tests + new `end_user_id` coverage GREEN under `uv run pytest tests/`.
- `uv run ruff check src/ tests/` clean.
- Boundary smoke `tests/test_no_worldtree_imports.py` still passes.
- Manual smoke: `source env.sh && uv run ratatoskr --send "test" --new --agent lofn --end-user-id ratatoskr-dev` succeeds against personal Worldtree (session creates, stream consumes to `[done]`).
- The pre-existing `mimir` smoke flow without `--end-user-id` STILL works (regression check).
docs/contracts/issues/6.contract.md
+374
View File
@@ -0,0 +1,374 @@
---
contract_version: "2.1"
target_module: "ratatoskr.tui"
scope: "Restructure `ratatoskr.tui`'s `run_tui` lifecycle so startup errors (`AgentNotFound`, `SessionApiFailed`, network-error-during-create_session) print to real stderr instead of getting eaten by the alt-screen teardown. Move session resolution OUT of `on_mount` (which runs inside the alt-screen) and INTO `run_tui` (sync wrapper, BEFORE `App.run()` opens the alt-screen). `httpx.AsyncClient` ownership moves with it: opened by `run_tui` via async-with; the `RatatoskrApp` instance becomes a consumer of an externally-owned client. `on_mount` shrinks to identity-widget population from pre-resolved state. Mid-session errors during streaming (issue #4 INV-008) continue to render in the alt-screen; only PRE-`App.run()` failures use stderr. No new modules; in-place amendment to issue #4's contract. No semantic change to issue #1/#2/#3 surfaces."
depends_on:
- "httpx"
- "textual"
- "ratatoskr.sessions"
- "ratatoskr.cli"
used_by: []
language: "python"
complexity: "medium"
estimated_loc: 60
confidence: 0.85
assumptions:
- "Textual's `App.run()` enters an alt-screen lifecycle that tears down on `self.exit()` or normal termination. Any content rendered to widgets inside the alt-screen (e.g., RichLog.write) is invisible to the operator after teardown — it lived in the alt-screen buffer, not the operator's scrollback. Real stderr writes survive teardown."
- "`httpx.AsyncClient` is safely usable across an `App.run()` boundary: opened in an `async with` block in `run_tui`, accessed by the App via `self.client`, closed by the same `async with` after `App.run()` returns. The client doesn't care about Textual's lifecycle; it's a plain httpx object the App holds a reference to."
- "Synchronous `run_tui` is the operator-facing entry point per issue #4's contract (called from `ratatoskr.cli.main` via lazy import). `run_tui` calls `asyncio.run(_resolve_then_run(args))` which is a single async function that handles BOTH the pre-flight HTTP (opening the client, resolving the session) AND the App lifecycle via `await app.run_async()`. Everything runs in one event loop managed by that single `asyncio.run(...)` call — NOT two sequential event loops. `app.run_async()` is Textual's async entry point (as opposed to the sync `app.run()`) and is the correct choice because we're already inside an async context with an active `httpx.AsyncClient`. Mixing a nested `asyncio.run()` inside an existing event loop would be incorrect."
- "Tests for the moved error paths use stderr capture (pytest's `capsys`) at the run_tui level, NOT the App.run_test() pilot. Pilot tests cover the in-alt-screen paths (#4's existing TestStreamTurnWorker / TestActionInterrupt / TestActionQuit). Pre-flight errors are App-free; standard stderr-capture works."
open_questions:
- "Should the pre-flight error label format match the cli's `[session_api_failed] status=... body=...` format exactly (already in cli's `_amain` STEP 2), so operators see the same label whether they hit the error via `--send` or via TUI startup? Draft: yes — same label, same shape, same exit code. Consistency beats per-presenter variance."
- "Should `run_tui` emit an `[connecting...]` status line to stderr before the pre-flight HTTP, so a slow connection isn't silently waited on? Draft: no for v1. The pre-flight is fast on a working network (< 1s for POST /sessions); if a slow path turns up, surface in a follow-up."
prd:
issue: 6
issue_url: "https://gitea.phasefinal.com/vh/ratatoskr/issues/6"
body_sha256_16: "6378989fbd465ba8"
lock_in_comment_id: null
lock_in_sha256_16: null
lock_in_at: null
pinned_at: "2026-05-23T02:11:18+00:00"
dependencies:
- issue: 4
path: "src/ratatoskr/tui.py"
reason: "In-place contract amendment: `run_tui` STEPS expanded with pre-App.run() session resolution + error routing to stderr; `RatatoskrApp.__init__` signature widens to accept pre-resolved `session_id` / `agent_id` / `client`; `on_mount` STEPS narrowed (no more session-create); `on_unmount` STEPS narrowed (client closed by run_tui's async-with, not on_unmount). Several issue #4 TESTS get restructured: error-on-mount tests become error-on-resolve tests at the run_tui layer."
---
# TUI startup error visibility — surface pre-flight errors to real stderr
## Context
Issue #4's `RatatoskrApp.on_mount` runs INSIDE the Textual alt-screen and
calls `create_session` (when `--new`) to mint a session before the app
becomes interactive. When `create_session` raises (`AgentNotFound`,
`SessionApiFailed`, network errors), my code today writes a labeled line
to the `RichLog` widget and calls `self.exit(<code>)`. The exit code is
right, but the labeled line is invisible: the alt-screen tears down
roughly 200ms after `self.exit()`, and the RichLog buffer goes with it.
The operator sees a blank terminal and an exit code — no diagnostic.
Surfaced 2026-05-21 (`ratatoskr --new --agent lofn` blanked silently;
turned out to be the issue #5 `end_user_id_required` 422; operator had
to re-run under `--send` to see the actual error). `--send` mode handles
this class of error correctly because stderr labels go to the operator's
real terminal, not the alt-screen.
This issue restructures the lifecycle so startup-phase errors use the
same stderr path that `--send` uses. Session resolution moves OUT of
`on_mount` (alt-screen) and INTO `run_tui` (sync wrapper, real terminal).
Mid-session errors during streaming continue to render in the alt-screen
per issue #4 INV-008 — that path is fine; the user is interactively
present and the transcript is visible.
## Data flow
**Input change:** none at the operator-facing level. `ratatoskr --new
--agent <id>` and `ratatoskr --session <id>` both still launch the TUI.
**Output change:**
- When session-create fails (in `--new` mode) OR when the network won't
reach the server, the operator now sees a labeled line on the **real
terminal stderr**, not the alt-screen:
- `[agent_not_found] agent_id={exc.agent_id}` (exit 12)
- `[session_api_failed] status={exc.status} body={exc.body!r}` (exit 20) — `exc.body` is already truncated to 1024 bytes at `SessionApiFailed.__init__` per issue #2 INV-004; `!r` is the repr of that already-truncated bytes value
- `[network_error] {type(exc).__name__}: {exc}` (exit 21)
- Format matches `ratatoskr.cli._amain`'s existing error labels exactly
(same shape, same exit codes) so operators see one consistent
vocabulary across `--send` and TUI modes.
- When session resolution succeeds, the alt-screen opens and behavior
is identical to today's: identity widgets populated, chat pane ready
for input.
- Mid-session errors during streaming (issue #4 INV-008 set:
`SseConnectionDropped`, `SseConnectFailed`, `MalformedSseId`,
`MalformedSseData`, `TurnIdFlip`) STILL render in the alt-screen
and return the app to idle. **Unchanged.**
**Side effects:**
- `httpx.AsyncClient` lifetime widens: now spans the pre-flight HTTP
AND the App's lifetime, owned by `run_tui` via `async with`.
**On disk:** none (unchanged).
## Invariants
- **INV-001 [hard]**: Session resolution (mint when `--new`; attach when
`--session`) MUST complete BEFORE `App.run()` enters the alt-screen.
Errors at this phase MUST print to `sys.stderr` (the real terminal,
not a RichLog widget) and MUST cause `run_tui` to return the
appropriate exit code WITHOUT calling `App.run()`. The alt-screen MUST
NOT open when session resolution fails — operators get a clean stderr
diagnostic on their normal terminal, with no flash-and-disappear
artifact.
- **INV-002 [hard]**: `httpx.AsyncClient` is owned by `run_tui` via
`async with`. The client is opened BEFORE the pre-flight session
resolution, passed by reference to `RatatoskrApp.__init__`, accessed
by the App via `self.client` during streaming, and closed by the same
`async with` AFTER `App.run()` returns. The App is a consumer of an
externally-owned client; it MUST NOT call `self.client.aclose()` (the
`async with` does that). Issue #4's `on_unmount` STEPS narrow
accordingly.
- **INV-003 [hard]**: `RatatoskrApp.__init__` signature widens to
`(args, *, session_id: str, agent_id: str | None, client:
httpx.AsyncClient)`. All three are pre-resolved by `run_tui` and
REQUIRED at construction. The app no longer mints anything; it
consumes pre-resolved state.
- **INV-004 [hard]**: `on_mount` STEPS narrow: open the identity Static
widget, set `self.state = "idle"`, set `self.hint = HINT_IDLE`.
No more session-create branch; no more client-open. The `<unknown>`
carve-out for agent_id (issue #4 INV-002) is preserved — when
`--session <id>` is used without `--agent`, `agent_id` is None and
the identity widget renders `<unknown> · …<tail>` as today.
- **INV-005 [hard]**: Mid-session errors during streaming (issue #4
INV-008 set) are UNCHANGED. They render to the RichLog transcript via
`_render_event_to_log` / explicit `log.write` and return the app to
`idle` state. Only PRE-`App.run()` errors get the new stderr-label
treatment. The split is: pre-alt-screen failures → real stderr;
in-alt-screen failures → RichLog. This is the load-bearing
observability invariant.
- **INV-006 [hard]**: Exit codes (12, 20, 21, 0, 3) and label formats
MUST match `ratatoskr.cli._amain`'s `[agent_not_found]` /
`[session_api_failed]` / `[network_error]` shape verbatim. Operators
see one vocabulary regardless of which presenter they're using.
- **INV-007 [hard]**: No `core.*` / `worldtree.*` imports (existing
boundary; unchanged).
## Out of scope
- **General TUI logging infrastructure** (e.g., a structured
DiagnosticsLog surface, log levels, log filtering). Each side pane is
its own issue.
- **Persistent error log file** at `~/.cache/ratatoskr/last-error.log`.
Rejected per design-brief §8d ("no cross-process resume, no config
dir"). The fix is "make startup errors visible on stderr", not "log
everything to disk".
- **In-alt-screen restructuring** (e.g., a status bar that surfaces
errors at the bottom of the screen during streaming). Issue #4 INV-008
already handles in-alt-screen errors correctly via RichLog; this issue
only addresses pre-alt-screen.
- **422 → user-friendly hint translation.** When `--new --agent lofn`
hits 422 `end_user_id_required`, this issue surfaces the raw label
to stderr; the user still has to read the body to understand. Hint
translation is issue #5's optional follow-up (deferred there).
- **Pre-flight status line** (`[connecting...]` before the HTTP).
Deferred; pre-flight is fast on a healthy network.
- **Re-entering the picker on failure.** If session-create fails, the
TUI exits cleanly; the operator re-launches with corrected args. No
retry loop in v1.
## Constraints
- **[compatibility]** Spec pin unchanged. The wire surface is
unchanged; only the client's invocation timing moves earlier.
- **[performance]** No new HTTP round-trips. The same single
`POST /sessions` happens once per `--new` launch; just sequenced
before `App.run()` instead of inside `on_mount`.
- **[security]** Same as today — `Authorization` header on the client,
no logged credentials.
- **[style]** Async-native at the resolve layer. `run_tui` becomes a
thin sync wrapper around `asyncio.run(_resolve_then_run(args))` to
keep one entry point. Ruff line-length=100.
## Architecture
```
ratatoskr <args> [shell entry, console-script]
│
└─ ratatoskr.cli.main(argv) [sync]
│
└─ when args.send_content is None ──► from ratatoskr.tui import run_tui
return run_tui(args)
│
└─ run_tui(args) [sync]
│
├─ assert PRE-001..PRE-002
└─ asyncio.run(_resolve_then_run(args))
│
├─ async with httpx.AsyncClient(...) as client:
│ │
│ ├─ try: resolve session
│ │ IF args.new: info = await create_session(client, args.agent_id)
│ │ session_id = info.session_id; agent_id = info.agent_id
│ │ ELSE: session_id = args.session_id; agent_id = args.agent_id
│ │ except AgentNotFound: stderr label; return 12 ◄── PRE-alt-screen
│ │ except SessionApiFailed: stderr label; return 20 ◄── PRE-alt-screen
│ │ except (httpx.ConnectError|ReadTimeout|TransportError): stderr; return 21
│ │
│ ├─ # Session resolved; enter alt-screen
│ ├─ app = RatatoskrApp(args, session_id, agent_id, client)
│ ├─ return await app.run_async() or 0
│ │ │
│ │ ├─ on_mount: populate identity widget; state=idle
│ │ ├─ on_input_submitted: spawn _stream_turn_worker
│ │ ├─ _stream_turn_worker: stream; mid-session errors → RichLog per INV-008 ◄── IN-alt-screen
│ │ └─ on_unmount: nothing (client closed by async with below)
│ │
│ └─ # App returned; async with closes client
└─ # exit code propagated to cli.main
```
---
## In-place amendments to issue #4 (the work)
This issue's contract is small because the real work is amending issue
#4's contract in place. The amendments are pinned here so reviewers see
the whole change in one place; the actual contract file at
`docs/contracts/issues/4.contract.md` is amended in-place as part of
this issue's commit.
### Issue #4 (`ratatoskr.tui`) amendments
**`run_tui` STEPS expanded:**
```
FN run_tui(args: ParsedArgs) -> int
STEPS:
1. [setup, prescriptive] Validate PRE-001 (isinstance(args, ParsedArgs) and args.send_content is None)
2. [setup, prescriptive] Validate PRE-002 (bool(args.session_id) != bool(args.new))
3. [sequential, prescriptive] RETURN asyncio.run(_resolve_then_run(args))
FN _resolve_then_run(args: ParsedArgs) -> int # NEW helper
ASYNC: yes
STEPS:
1. [setup, prescriptive] OPEN httpx.AsyncClient(base_url=args.server_url,
headers={"Authorization": f"Bearer {args.api_key}"},
timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)) via async-with
2. [branch, prescriptive] IF args.new:
TRY: info = await create_session(client, args.agent_id)
ON AgentNotFound as exc:
sys.stderr.write(f"[agent_not_found] agent_id={exc.agent_id}\n")
RETURN 12
ON SessionApiFailed as exc:
sys.stderr.write(f"[session_api_failed] status={exc.status} body={exc.body!r}\n")
RETURN 20
ON (httpx.ConnectError | httpx.ReadTimeout | httpx.TransportError) as exc:
sys.stderr.write(f"[network_error] {type(exc).__name__}: {exc}\n")
RETURN 21
SET session_id = info.session_id; agent_id = info.agent_id
ELSE:
SET session_id = args.session_id; agent_id = args.agent_id # agent_id may be None — INV-002 carve-out preserved
3. [sequential, prescriptive] Construct app = RatatoskrApp(args, session_id=session_id, agent_id=agent_id, client=client)
4. [sequential, prescriptive] exit_code = await app.run_async() # Textual's async-runner; lets the same event loop handle the alt-screen
5. [cleanup, prescriptive] RETURN exit_code or 0
```
**Note**: `app.run_async()` (Textual's async-runner) is used instead of
`app.run()` (sync) because we're already in an async context inside the
`async with httpx.AsyncClient(...)`. Mixing `asyncio.run(...)` inside an
existing event loop would be incorrect; the async variant lets one loop
handle both the pre-flight HTTP AND the App lifecycle.
**`RatatoskrApp.__init__` signature widens:**
```
def __init__(self, args: ParsedArgs, *, session_id: str, agent_id: str | None, client: httpx.AsyncClient) -> None
```
All three new kwargs are REQUIRED. Stored on self as
`self.session_id`, `self.agent_id`, `self.client`. The state machine
attributes (`self.state`, `self.active_turn_id`, `self.stream_worker`,
`self.hint`) are unchanged.
**`on_mount` STEPS narrow:**
```
async def on_mount(self) -> None:
STEPS:
1. [setup, prescriptive] assert self.client is not None and self.session_id is not None
2. [sequential, prescriptive] Compute identity:
agent_slot = self.agent_id or "<unknown>"
identity = f"{agent_slot} · …{self.session_id[-8:]}"
3. [sequential, prescriptive] Populate widgets:
self.sub_title = identity (Header mirror)
self.query_one("#identity", Static).update(identity)
4. [sequential, prescriptive] SET self.state = "idle"; self._set_hint(self.HINT_IDLE)
```
No more session-create branch; no more client-open. ERROR_ROUTING for
`AgentNotFound` / `SessionApiFailed` / network errors is **removed from
on_mount** — those routes now live in `_resolve_then_run`. Issue #4's
POST-001 (client-open-after-mount) and POST-002 (session_id non-empty)
are still satisfied but by `_resolve_then_run` setting up state, not
by `on_mount`'s create call.
**`on_unmount` STEPS narrow (or removed):**
```
async def on_unmount(self) -> None:
STEPS:
(none — client lifetime managed by run_tui's async-with, NOT this hook)
```
Issue #4's existing `on_unmount` test (`unmount_closes_client`) is
restructured: client closing now happens via `run_tui`'s async-with
exit, which fires after `app.run_async()` returns. The test moves
from "ctrl+d → on_unmount → client closed" to "ctrl+d → run_tui
returns → client closed".
**TESTS amendments (issue #4 in-place):**
Removed (or restructured to the run_tui layer):
- `agent_not_found_on_mount` → becomes `agent_not_found_on_resolve` at
the `_resolve_then_run` layer. Assertion shape: `capsys.readouterr().err`
contains `[agent_not_found]`; `run_tui` returns 12; no app instance
ever entered alt-screen.
- `session_api_failed_on_mount` → `session_api_failed_on_resolve`.
- `network_error_on_mount` → `network_error_on_resolve`.
- `client_open_after_mount` → `client_open_after_resolve` (client opened
by run_tui, accessible via `self.client` once the app is mounted).
- `unmount_closes_client` → `run_tui_closes_client_on_app_exit` (asserts
the async-with closed the client after `app.run_async()` returned).
New TESTS (in the `_resolve_then_run` block at the run_tui layer):
- `alt_screen_never_opens_on_resolve_error [trace]`: monkeypatch
`RatatoskrApp.run_async` to a sentinel that fails the test if called;
set up respx to return 404 from POST /sessions; assert `run_tui`
returns 12; assert the sentinel was NEVER invoked. Directly probes
INV-001 (alt-screen MUST NOT open).
- `client_lifetime_owned_by_run_tui [trace]`: spy on `httpx.AsyncClient.aclose`;
successful run; assert exactly one `aclose` call AFTER `app.run_async`
returned, NOT during on_unmount. Probes INV-002.
- `stderr_label_format_matches_cli [trace]`: assert the stderr label
shape (e.g., `[agent_not_found] agent_id=missing`) matches the format
emitted by `cli._amain`'s existing handler verbatim. Probes INV-006.
Issue #4's `happy_new_session_mount` test stays (now exercises the
identity widget population via the pre-resolved state); the assertion
on POST /sessions call count moves to the new `_resolve_then_run`
test layer.
---
## Acceptance
- Issue #4 contract amended in-place; drift-check clean.
- Issue #6 contract drift-check clean.
- All existing tests + new `_resolve_then_run` coverage GREEN under
`uv run pytest tests/`.
- `uv run ruff check src/ tests/` clean.
- Boundary smoke `tests/test_no_worldtree_imports.py` still passes.
- Manual smoke (the original failure mode from 2026-05-21):
`ratatoskr --new --agent <nonexistent>` produces a VISIBLE
`[agent_not_found]` line on stderr; no screen-blanking artifact; exit
code 12. (This is the smoke that surfaced the bug; verify it's now
the success case.)
- Regression smoke: `ratatoskr --new --agent mimir` against personal
Worldtree still works end-to-end (alt-screen opens, chat pane works,
Ctrl-D exits clean). Mid-session errors during a streaming turn STILL
render in the alt-screen per INV-008 — verify by hitting one (e.g.,
send a turn, then kill the server side, see `[connection_dropped]`
in the transcript, state returns to idle).
## Dependencies
- Issue #4 (`ratatoskr.tui` shell) — landed on main; this issue amends
its contract.
- Issue #5 (`--end-user-id` for per-user agents) — independent; both
can land in either order, but #5 + #6 compose naturally (#6 will
surface #5's 422 as a visible stderr label instead of a black
alt-screen).
- Issue #7 (mid-stream robustness, `MalformedSseData`) — landed; #6's
pre/in-alt-screen split is orthogonal to #7's empty-data/malformed
distinction (different error layers entirely).
persistent-memory.md
+55 -37
View File
@@ -1,6 +1,6 @@
# Persistent memory — ratatoskr # Persistent memory — ratatoskr
_Last updated: 2026-05-22_ _Last updated: 2026-05-23_
This file captures durable intent and supporting evidence (goals, decisions, This file captures durable intent and supporting evidence (goals, decisions,
foot-gun warnings, in-flight state) across context resets. Read it at session foot-gun warnings, in-flight state) across context resets. Read it at session
@@ -32,50 +32,61 @@ separate dev team rather than an in-tree Worldtree tool.
## Current state / in-flight ## Current state / in-flight
_As of 2026-05-21:_ _As of 2026-05-23 (end of day):_
**Status: v0 milestone + issue #7 (mid-stream robustness) landed.** Four **Status: issues #5 + #6 + worldtree-dev consumer-API follow-up all
core issues complete end-to-end (`sse_client` #1, `sessions` #2, `cli` landed.** Six core issues complete (`sse_client` #1, `sessions` #2,
#3, `tui` #4) + one robustness fix on top: `MalformedSseData` exception `cli` #3, `tui` #4, `--end-user-id` #5, TUI startup error visibility
+ empty-data skip in `_iter_events` (issue #7, fixes mid-stream #6) + robustness fix #7 (MalformedSseData + empty-skip).
JSONDecodeError crash discovered during long TUI conversations). 188/188 tests GREEN; ruff clean.
172/172 tests GREEN (46 sse_client + 19 sessions + 60 cli + 44 tui +
2 boundary/metadata + 1 from #7 last-seen probe); ruff clean; all five
issue contracts (#1, #3, #4, #5, #7) drift-check clean.
`--send` validated end-to-end against personal Worldtree `--send` validated end-to-end against personal Worldtree
(`http://10.250.50.152:8081`, mimir on qwen3.6-35-a3b). Smoke key in (`http://10.250.50.152:8081`, mimir on qwen3.6-35-a3b). Lofn smoke
gitignored `env.sh` (delivered by infra-ops 2026-05-21; see parked on infra-ops's `agents.call:lofn` scope add (althing thread
[[personal-worldtree-smoke-target]] in auto-memory). Long-conversation `01KSBBHDWVZZ…`; infra-ops brokering to worldtree-dev because personal
smoke 2026-05-22 (3193-token completion, 374980-token context, 50s Worldtree exposes no public scope-mutation endpoint).
streaming) confirmed empty-data frames are silently skipped — the
original 2026-05-22 crash unreproducible after fix.
**In-flight: issue #5 (`--end-user-id` flag for per-user agents like **In-flight:**
lofn).** Contract drafted + parked (untracked at - **Lofn smoke** — blocked on the scope-add. Once infra-ops confirms
`docs/contracts/issues/5.contract.md`); Volva paraphrase + TDD + smoke `agents.call:lofn` is live, run `ratatoskr --new --agent lofn
pending. Issue #6 (TUI startup error visibility) also filed but --end-user-id ratatoskr-tui --send "hello"` for end-to-end
unscaffolded. Branch: `main` (clean apart from #5 contract). Remote: verification.
- **Issue #8 (startup agent picker)** — filed but unscaffolded.
Worldtree-dev confirmed `GET /agents` requires no special scope
(any authenticated key works); issue is unblocked on auth side.
Depends on #5 composably (both thread through `ParsedArgs` →
`_resolve_then_run`).
- **Issue #9 (spec-pin refresh v0.19.0 → v0.22.1)** — filed
2026-05-23. Documentation debt; pin lies about the surface we're
committed to. Worldtree v0.20.0 made `end_user_id` the partition
key; v0.21.0 added `memory_context` field; v0.22.0 strengthened
the `[MEMORY:DATA]` envelope. None break our existing surface.
- **Issue #10 (subject:{type,id} migration)** — filed 2026-05-23 to
track Worldtree #196's LOCKED-but-not-shipped breaking change.
Worldtree-dev was explicit: don't pre-implement; deprecation
warnings will fire per call as the heads-up when substrate ships.
- **Issue #11 (AdminEvents pane auth prerequisite)** — filed
2026-05-23. Future side-pane requires `admin.events.read` scope;
documenting the gate so we don't forget when scheduling that pane.
Branch: `main` (clean after this commit). Remote:
`origin → git@gitea.phasefinal.com:vh/ratatoskr.git`. `origin → git@gitea.phasefinal.com:vh/ratatoskr.git`.
**Next natural moves:** **Next natural moves:**
1. **Resume issue #5 cadence** — `--end-user-id` flag for per-user agents 1. **Mimir regression smoke (operator-side)** — `source env.sh && uv
(lofn). Contract drafted + parked; next steps: Volva paraphrase, TDD, run ratatoskr --new --agent mimir --send "test"` (and the
smoke against lofn. Unblocks the Persona/Vili agent family. `--send`-less TUI form) to verify backwards compat holds after
2. **Issue #6 (TUI startup error visibility)** — filed, unscaffolded. issues #5 + #6 land. env.sh now ships
Restructure: move session-create out of `on_mount` into `run_tui` `RATATOSKR_END_USER_ID="ratatoskr-tui"`.
pre-App.run() so errors print to real stderr (not the alt-screen that 2. **Lofn smoke** — when infra-ops confirms scope-add.
tears down before user can read them). Independent of #5. 3. **Issue #8 (startup agent picker)** — scaffold + contract, then
3. **TUI smoke (operator-side)** — `source env.sh && uv run ratatoskr TDD. Unblocked by both #5 (end_user_id wired through
--new --agent mimir` from an interactive terminal. Validates Textual `_resolve_then_run`) and worldtree-dev's auth confirmation for
app lifecycle + post-Done markdown re-render end-to-end. Needs a TTY `GET /agents`.
which CC sessions don't have. 4. **Side-pane issues** — Persona pane first (file-tail, cheap).
4. **Side-pane issues** — design-brief §5 lists 5 side panes (Persona, 5. **Issue #9 (spec-pin refresh)** — defer until we actually need a
Tools, AdminEvents, BifrostState, ServerLog). Persona is the natural v0.20.0+ capability, OR refresh now if doc-debt is bothering us.
first (file-tail of `persona.log`).
5. **Recorded SSE snapshot fixtures** from a running Worldtree.
`--send --new > fixture` IS the recording probe.
## Recent decisions ## Recent decisions
@@ -99,7 +110,13 @@ decision. Captures rationale that won't be obvious from code alone.
- `[2026-05-21]` **Volva paraphrase + code-review across all 4 issues — calibration consistent.** Paraphrase rounds flag 3-5 contract ambiguities per issue; code-review rounds flag 3-8 code-vs-contract drifts after TDD-passing implementation. Hit rates: #1 paraphrase 3-of-5 amended / code-review 4 findings; #2 3-of-5 / 3 findings; #3 5-of-5 / 5 findings; #4 5-of-5 / 8 findings. The post-TDD code-review consistently catches three classes of gap the test-author's hypotheses don't cover: PRE-assertion boundary drift, exception-payload truncation / never-rendered-to-user observability misses, and "tested the state but not whether the user can see it" gaps (issue #4's primary finding: TUI footer state stored but never rendered to a visible widget — same-model TDD would systematically miss this). - `[2026-05-21]` **Volva paraphrase + code-review across all 4 issues — calibration consistent.** Paraphrase rounds flag 3-5 contract ambiguities per issue; code-review rounds flag 3-8 code-vs-contract drifts after TDD-passing implementation. Hit rates: #1 paraphrase 3-of-5 amended / code-review 4 findings; #2 3-of-5 / 3 findings; #3 5-of-5 / 5 findings; #4 5-of-5 / 8 findings. The post-TDD code-review consistently catches three classes of gap the test-author's hypotheses don't cover: PRE-assertion boundary drift, exception-payload truncation / never-rendered-to-user observability misses, and "tested the state but not whether the user can see it" gaps (issue #4's primary finding: TUI footer state stored but never rendered to a visible widget — same-model TDD would systematically miss this).
- `[2026-05-21]` **Manual smoke is load-bearing — found a real defect tests couldn't.** First wire-level smoke against personal Worldtree (post-TDD, post-Volva-code-review on #4) revealed httpx's default 5s read timeout killed the SSE connection mid-stream during mimir's thinking phase (~30s LLM latency >> 5s read timeout). The unit/contract test infrastructure (respx-mocked SSE wire) doesn't model real LLM latency, so the gap was invisible at the test layer. Fix: caller-owned `httpx.AsyncClient` constructed with `timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)`; defense in depth: `sse_client.stream_turn` ERROR_ROUTING catches `httpx.ReadTimeout` → `SseConnectionDropped`. Three contracts amended in-place to document the timeout policy. **Lesson: keep manual-smoke step in the per-issue cadence; mock-only validation is insufficient for streaming-against-real-server code.** Re-smoke succeeded: `[done] turn_id=88 model=qwen3.6-35-a3b duration_ms=2351`. Wire-compat envelope (personal v0.16.2 vs ratatoskr's v0.19.0 pin) confirmed end-to-end. - `[2026-05-21]` **Manual smoke is load-bearing — found a real defect tests couldn't.** First wire-level smoke against personal Worldtree (post-TDD, post-Volva-code-review on #4) revealed httpx's default 5s read timeout killed the SSE connection mid-stream during mimir's thinking phase (~30s LLM latency >> 5s read timeout). The unit/contract test infrastructure (respx-mocked SSE wire) doesn't model real LLM latency, so the gap was invisible at the test layer. Fix: caller-owned `httpx.AsyncClient` constructed with `timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)`; defense in depth: `sse_client.stream_turn` ERROR_ROUTING catches `httpx.ReadTimeout` → `SseConnectionDropped`. Three contracts amended in-place to document the timeout policy. **Lesson: keep manual-smoke step in the per-issue cadence; mock-only validation is insufficient for streaming-against-real-server code.** Re-smoke succeeded: `[done] turn_id=88 model=qwen3.6-35-a3b duration_ms=2351`. Wire-compat envelope (personal v0.16.2 vs ratatoskr's v0.19.0 pin) confirmed end-to-end.
- `[2026-05-22]` **Issues #5/#6/#7 filed: per-user-agent support + TUI-startup-visibility + mid-stream-robustness.** Discovered during 2026-05-22 mimir TUI conversation: long completion (turn 93, 1077 events consumed) crashed with `JSONDecodeError("Expecting value: line 1 column 1 (char 0)")` from `json.loads('')` on an empty-`data:` SSE frame. Diagnosis surfaced #7 (the crash). Earlier same day, `ratatoskr --new --agent lofn` failed with 422 `end_user_id_required` — surfacing #5 (`--end-user-id` flag needed for per-user agents). #6 (TUI alt-screen masks the diagnostic before user can read it) was a corollary observation. All three filed; user reordered to #7 first (highest-impact for daily TUI use). - `[2026-05-22]` **Issues #5/#6/#7 filed: per-user-agent support + TUI-startup-visibility + mid-stream-robustness.** Discovered during 2026-05-22 mimir TUI conversation: long completion (turn 93, 1077 events consumed) crashed with `JSONDecodeError("Expecting value: line 1 column 1 (char 0)")` from `json.loads('')` on an empty-`data:` SSE frame. Diagnosis surfaced #7 (the crash). Earlier same day, `ratatoskr --new --agent lofn` failed with 422 `end_user_id_required` — surfacing #5 (`--end-user-id` flag needed for per-user agents). #6 (TUI alt-screen masks the diagnostic before user can read it) was a corollary observation. All three filed; user reordered to #7 first (highest-impact for daily TUI use).
- `[2026-05-22]` **Issue #8 (startup agent picker) filed.** `GET /agents` exists in the vendored spec (spec line 832); returns `agent_id`, `name`, `description` + optional `version`, `capabilities`, `ui_hints`. `--agent` becomes conditionally optional: still required for `--send --new` (non-interactive); optional for TUI `--new`. When omitted in TUI mode, a new `AgentPickerScreen` fetches the agent list and presents a `ListView`. Depends on `list_agents()` function in `ratatoskr.sessions`. Composes naturally with issue #5 (both thread through `ParsedArgs` → `on_mount` / `_resolve_then_run`). Out of scope: search/sort, `ui_hints` rendering, `--send` mode picker.
- `[2026-05-23]` **Issue #6 (TUI startup error visibility) contract drafted + Volva paraphrase complete.** Restructures `run_tui` lifecycle: session resolution moves OUT of `on_mount` (alt-screen) into a new `_resolve_then_run` async helper (pre-`App.run()`). `AsyncClient` ownership also moves to `run_tui`'s `async with`; `RatatoskrApp.__init__` takes pre-resolved `session_id`/`agent_id`/`client`; `on_mount` shrinks to identity-widget population. Pre-alt-screen errors → real stderr (same labels/codes as `--send`). Mid-session errors → RichLog (unchanged, per issue #4 INV-008). **Volva paraphrase triage applied the new 5-category framework** (Genuine add / Sharpening / Restatement / Out-of-place / Wrong-grounding + ignorance-of-context check). 2 of 5 flagged items amended: F1 (Category 1 — internal contract contradiction: assumptions block said "two sequential event loops" while normative STEPS said `await app.run_async()` — corrected to describe one async flow); F3 (Category 2 — sharpening: informal `<truncated>` prose aligned to normative `{exc.body!r}` shape already in STEPS). 3 accepted: F2 (Category 5 — httpx exception hierarchy mis-inference without httpx source access), F4 (Category 3 — restatement of settled architectural guardrail), F5 (Category 2 — sharpening confirming test is the load-bearing spec element).
- `[2026-05-22]` **Issue #7 (`MalformedSseData` + empty-skip) implemented via TDD + Volva-code-reviewed + smoked.** Contract → Volva paraphrase (4 ambiguities, all amended; INV-001 wording tightened around exact `sse.data == ''` rule, ordering-before-id-parse made explicit, test-description bug fixed) → TDD (6 tests, full vertical-slice ordering) → Volva code-review (3 findings — F1 test-gap probing internal `last_sse_id` non-advancement via post-skip drop, F2 contract precision around log-vs-propagate responsibility, F3 cli test tightening for `raw='X'` shape + truncation coverage; all amended) → smoke (3193-token completion against personal Worldtree confirmed clean termination; original crash unreproducible). **Calibration milestone: issue #7 is the first issue with zero drift findings from Volva code-review** — TDD caught all runtime behavior cleanly. The 3 findings were assertion-precision and architectural-correctness-of-wording, not behavioral. Hypothesis: the tighter the contract spec + the smaller the code surface, the more Volva's role shifts from "catch behavioral drift" to "tighten observability + wording". Calibration table now: #1 (4 findings, 3 drift + 1 test-gap), #2 (3, 1+1+1 precision), #3 (5, 3+1+1), #4 (8, 5+2+1), #7 (3, 0 drift + 2 test-gap + 1 precision). - `[2026-05-22]` **Issue #7 (`MalformedSseData` + empty-skip) implemented via TDD + Volva-code-reviewed + smoked.** Contract → Volva paraphrase (4 ambiguities, all amended; INV-001 wording tightened around exact `sse.data == ''` rule, ordering-before-id-parse made explicit, test-description bug fixed) → TDD (6 tests, full vertical-slice ordering) → Volva code-review (3 findings — F1 test-gap probing internal `last_sse_id` non-advancement via post-skip drop, F2 contract precision around log-vs-propagate responsibility, F3 cli test tightening for `raw='X'` shape + truncation coverage; all amended) → smoke (3193-token completion against personal Worldtree confirmed clean termination; original crash unreproducible). **Calibration milestone: issue #7 is the first issue with zero drift findings from Volva code-review** — TDD caught all runtime behavior cleanly. The 3 findings were assertion-precision and architectural-correctness-of-wording, not behavioral. Hypothesis: the tighter the contract spec + the smaller the code surface, the more Volva's role shifts from "catch behavioral drift" to "tighten observability + wording". Calibration table now: #1 (4 findings, 3 drift + 1 test-gap), #2 (3, 1+1+1 precision), #3 (5, 3+1+1), #4 (8, 5+2+1), #7 (3, 0 drift + 2 test-gap + 1 precision).
- `[2026-05-23]` **Issue #6 (TUI startup error visibility) implemented via TDD + Volva-code-review (two rounds).** Lifecycle restructure: `run_tui` becomes a thin sync wrapper around `asyncio.run(_resolve_then_run(args))`; the new `_resolve_then_run` opens the `httpx.AsyncClient` via `async with`, does pre-flight session resolution, routes `AgentNotFound`/`SessionApiFailed`/network errors to real `sys.stderr` (verbatim same labels as `cli._amain`), THEN constructs `RatatoskrApp` with pre-resolved state and calls `await app.run_async()`. `RatatoskrApp.__init__` signature widens to `(args, *, session_id, agent_id, client)` — all three required. `on_mount` narrows to identity-widget population; `on_unmount` becomes a no-op. The alt-screen never opens on resolution errors (INV-001). **Two Volva code-review rounds**: round 1 returned 6 findings (1 drift + 5 test-gaps), all Category 1 fixed (F1 added the missing PRE-001 assertion at `_resolve_then_run` entry; F2-F6 tightened test precision — Rule separator assertions on markdown render, RichLog-write spy on empty submit, input-cleared + no-new-worker on cancelling busy, worker.cancel observation on force-exit paths). Round 2 returned 2 NEW test-gaps (F7 `client_lifetime_owned_by_run_tui` patched `run_async` so `on_unmount` wasn't actually exercised — added a sibling `test_on_unmount_does_not_close_client`; F8 no happy-path `--new` resolve test — added `test_happy_new_session_resolve` asserting POST count + identity propagation). Calibration confirmed multi-round-Volva value: round 2 found things round 1's amendments didn't anticipate, but they were strictly test-precision, no behavioral drift.
- `[2026-05-23]` **Issue #5 (`--end-user-id`) implemented via TDD.** Small surface change across three modules (sessions, cli, tui): `create_session(client, agent_id, *, end_user_id=None)` widens with optional kwarg; body conditionally adds the field when non-None (INV-002: omitting != sending empty); PRE-003 asserts non-empty. `ParsedArgs.end_user_id: str | None = None` field; `--end-user-id` CLI flag with non-empty validation (mirrors `--send` check). `_amain` and `_resolve_then_run` thread `end_user_id=args.end_user_id` to their `create_session` calls. Post-#6 adjustment: the contract originally named `on_mount` as the TUI threading site, but #6 had moved session resolution to `_resolve_then_run` — same shape, different function. 7 new tests across the 3 modules.
- `[2026-05-23]` **Worldtree-dev consult landed authoritative consumer-API guidance** (althing thread `01KSBARG2B8M8C82H6AJGJWX1B`). Key takeaways shaped follow-on work: (1) `end_user_id` is a free-form partition key for long-term memory + persona/valence state; same value → same partition, different values → fully isolated. For Vuong-debugging-Worldtree the recommended posture is a project-stable default with `--end-user-id` override. (2) No programmatic `requires_end_user_id` discovery on `GET /agents` — "try and react to 422" remains the pattern. (3) Breaking-change #196 LOCKED but not shipped: `subject:{type,id}` replaces `end_user_id` at future v0.22.x or v0.23.0; don't pre-implement. (4) Spec pin (v0.19.0) is 3 minor versions stale (current v0.22.1); none of v0.20.0/v0.21.0/v0.22.0 break ratatoskr's surface but the pin lies about what we're committed to. (5) User-Agent header: send one (`ratatoskr/<version> (vh@phasefinal.com)`). (6) `agents.call:lofn` scope needed for lofn smoke. (7) `GET /agents` requires no special scope; issue #8 unblocked on auth.
- `[2026-05-23]` **Follow-up acted on:** User-Agent header added to both `_amain` and `_resolve_then_run` httpx.AsyncClient constructions (with `importlib.metadata` version lookup + fallback to `0.0.0`); `RATATOSKR_END_USER_ID` env-var fallback added to `_parse_args` (resolution: flag > env > None); env.sh ships `RATATOSKR_END_USER_ID="ratatoskr-tui"` as project-stable default. Original issue #5 posture rejected env-var fallback as "papering over isolation"; revised after worldtree-dev's guidance that the realistic single-operator use case wants partition continuity. Issue #5 + #3 contracts amended in-place to document the env-var fallback. Infra-ops pinged via althing for `agents.call:lofn` scope (broker pattern; they forwarded to worldtree-dev). Three Gitea issues filed: #9 (spec-pin refresh), #10 (subject:{type,id} migration tracking), #11 (AdminEvents pane auth prereq).
_For per-issue TDD implementation notes, Volva findings, and contract amendments, see the git log (commits `9703eb2..61c3941` carry the full per-issue trail with structured commit messages)._ _For per-issue TDD implementation notes, Volva findings, and contract amendments, see the git log (commits `9703eb2..61c3941` carry the full per-issue trail with structured commit messages)._
@@ -115,4 +132,5 @@ defense against re-attempting the same cul-de-sac.
- `[2026-05-21]` **RichLog widget with `markup=True`.** Default impulse, but Rich interprets `[xxx]` spans as style markup and silently strips them. Every labeled stderr-style line — `[cancel_failed]`, `[done]`, `[error]`, `[busy]`, `[worker_phase]` — would render as just the content after the bracketed label, breaking the user-visible observability surface. Fix: `markup=False`. The post-Done Markdown rendering still works because `rich.markdown.Markdown` is a Renderable that ignores widget-level markup setting. Don't flip back to `markup=True` without first renaming every labeled-line format away from `[bracket]` notation. - `[2026-05-21]` **RichLog widget with `markup=True`.** Default impulse, but Rich interprets `[xxx]` spans as style markup and silently strips them. Every labeled stderr-style line — `[cancel_failed]`, `[done]`, `[error]`, `[busy]`, `[worker_phase]` — would render as just the content after the bracketed label, breaking the user-visible observability surface. Fix: `markup=False`. The post-Done Markdown rendering still works because `rich.markdown.Markdown` is a Renderable that ignores widget-level markup setting. Don't flip back to `markup=True` without first renaming every labeled-line format away from `[bracket]` notation.
- `[2026-05-21]` **Querying `self.query_one("#transcript", RichLog)` from inside a Textual `run_worker` coroutine.** Failed initially with `NoMatches` because the worker fires before the test's `pilot.pause()` allows the Input.Submitted handler to fully dispatch (and thus the widget tree to settle). Initial reactive fix: widen worker signature to take `log` as a parameter (passed from the handler). Volva code-review flagged this as contract drift (signature didn't match spec). Reverted to single-param signature. The real fix was test-side: add `await pilot.pause()` between `inp.action_submit()` and the polling loop in `_submit_and_wait` so the handler finishes dispatching before the worker reads the widget tree. Don't widen worker signatures to dodge test timing. - `[2026-05-21]` **Querying `self.query_one("#transcript", RichLog)` from inside a Textual `run_worker` coroutine.** Failed initially with `NoMatches` because the worker fires before the test's `pilot.pause()` allows the Input.Submitted handler to fully dispatch (and thus the widget tree to settle). Initial reactive fix: widen worker signature to take `log` as a parameter (passed from the handler). Volva code-review flagged this as contract drift (signature didn't match spec). Reverted to single-param signature. The real fix was test-side: add `await pilot.pause()` between `inp.action_submit()` and the polling loop in `_submit_and_wait` so the handler finishes dispatching before the worker reads the widget tree. Don't widen worker signatures to dodge test timing.
- `[2026-05-21]` **TUI session-identity rendering via `self.sub_title` + `self.hint` plain attributes.** Stored state but never rendered to a visible widget. The contract's "session-identity-always-visible" invariant was satisfied at the state-attribute level but not the user-visible-widget level. Tests asserted the attributes (which passed); Volva code-review flagged the gap. Fix: dedicated `Static(id="identity")` + `Static(id="hint")` widgets in compose; `_set_hint()` helper mirrors state → widget. Calibration evidence for the "TDD catches state, code-review catches whether the user can see it" pattern. - `[2026-05-21]` **TUI session-identity rendering via `self.sub_title` + `self.hint` plain attributes.** Stored state but never rendered to a visible widget. The contract's "session-identity-always-visible" invariant was satisfied at the state-attribute level but not the user-visible-widget level. Tests asserted the attributes (which passed); Volva code-review flagged the gap. Fix: dedicated `Static(id="identity")` + `Static(id="hint")` widgets in compose; `_set_hint()` helper mirrors state → widget. Calibration evidence for the "TDD catches state, code-review catches whether the user can see it" pattern.
- `[2026-05-23]` **Using the cross-model review agent's name directly in composed prose.** The peer review agent's name (the `althing` handle starting with "V-o-l-v-a") is one letter from a body-part term. Anthropic's content classifier does fuzzy matching and intermittently blocks responses mid-stream when the name appears in composed prose sentences (especially in meta-commentary about the agent's work). Direct-quoted tool output (e.g., the `althing-cli thread` body) passes through fine. Mitigation: use role descriptions ("the cross-model reviewer," "the paraphrase peer") in prose rather than the name; quote content via tool output. Confirmed by switching to Sonnet 4.6 for a test read — same raw content read cleanly when fetched via Bash rather than composed into an LLM response. This is a persistent environmental constraint, not a one-off.
- `[2026-05-22]` **`json.loads(sse.data)` unguarded against empty data.** `_iter_events` unconditionally called `json.loads` on every dispatched `ServerSentEvent`. When `httpx_sse` surfaced a frame with `id:` present but `data:` empty (a known library-vs-spec divergence — RFC says don't dispatch; httpx_sse is permissive), `json.loads('')` raised `JSONDecodeError` → propagated through Textual's worker → app crash. Crashed mimir conversation at turn 93/seq 1078 after 1077 successful events. Fix: `if sse.data == '': continue` BEFORE `_parse_sse_id` (empty-data event with a malformed id is still a keepalive — don't reorder). Non-empty malformed data raises new `MalformedSseData(raw[:200])`. Don't reintroduce unconditional `json.loads(sse.data)`; always pre-check for the empty case. - `[2026-05-22]` **`json.loads(sse.data)` unguarded against empty data.** `_iter_events` unconditionally called `json.loads` on every dispatched `ServerSentEvent`. When `httpx_sse` surfaced a frame with `id:` present but `data:` empty (a known library-vs-spec divergence — RFC says don't dispatch; httpx_sse is permissive), `json.loads('')` raised `JSONDecodeError` → propagated through Textual's worker → app crash. Crashed mimir conversation at turn 93/seq 1078 after 1077 successful events. Fix: `if sse.data == '': continue` BEFORE `_parse_sse_id` (empty-data event with a malformed id is still a keepalive — don't reorder). Non-empty malformed data raises new `MalformedSseData(raw[:200])`. Don't reintroduce unconditional `json.loads(sse.data)`; always pre-check for the empty case.
pyproject.toml
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project] [project]
name = "ratatoskr" name = "ratatoskr"
version = "0.0.0" version = "0.1.0"
description = "Worldtree Conversation API debug TUI — multi-pane observability dashboard" description = "Worldtree Conversation API debug TUI — multi-pane observability dashboard"
readme = "README.md" readme = "README.md"
requires-python = ">=3.12" requires-python = ">=3.12"
src/ratatoskr/cli.py
+40 -2
View File
@@ -11,6 +11,7 @@ import os
import signal import signal
import sys import sys
from dataclasses import dataclass from dataclasses import dataclass
from importlib.metadata import PackageNotFoundError, version
from typing import TextIO from typing import TextIO
import httpx import httpx
@@ -40,6 +41,24 @@ from ratatoskr.sse_client import (
) )
def _resolve_user_agent() -> str:
"""Compose the User-Agent header — `ratatoskr/<version> (<contact>)`.
Per worldtree-dev's 2026-05-23 guidance: identify the consumer in outbound
requests so server-side logs can distinguish ratatoskr traffic. Falls back
to "0.0.0" if the package isn't installed (test contexts, editable installs
without metadata).
"""
try:
ver = version("ratatoskr")
except PackageNotFoundError:
ver = "0.0.0"
return f"ratatoskr/{ver} (vh@phasefinal.com)"
USER_AGENT = _resolve_user_agent()
class UsageError(Exception): class UsageError(Exception):
"""Raised on argument violations; mapped to exit code 10 by main().""" """Raised on argument violations; mapped to exit code 10 by main()."""
@@ -59,6 +78,9 @@ class ParsedArgs:
api_key: str api_key: str
server_url: str server_url: str
raw: bool raw: bool
# Per issue #5: optional `--end-user-id` for per-end-user agents (lofn etc.).
# Default None preserves the pre-#5 baseline for agents that don't require it (mimir).
end_user_id: str | None = None
class _ArgparseError(Exception): class _ArgparseError(Exception):
@@ -83,6 +105,8 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
parser.add_argument("--api-key", dest="api_key") parser.add_argument("--api-key", dest="api_key")
parser.add_argument("--server") parser.add_argument("--server")
parser.add_argument("--raw", action="store_true") parser.add_argument("--raw", action="store_true")
# 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)
try: try:
ns = parser.parse_args(argv) ns = parser.parse_args(argv)
except _ArgparseError as exc: except _ArgparseError as exc:
@@ -91,6 +115,9 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
# --send empty-string is still invalid; --send omitted (None) is the TUI-mode marker. # --send empty-string is still invalid; --send omitted (None) is the TUI-mode marker.
if ns.send is not None and not ns.send: if ns.send is not None and not ns.send:
raise UsageError("--send content must be non-empty") raise UsageError("--send content must be non-empty")
# 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 ns.session and ns.new: if ns.session and ns.new:
raise UsageError("--session and --new are mutually exclusive; pass exactly one") raise UsageError("--session and --new are mutually exclusive; pass exactly one")
if not ns.session and not ns.new: if not ns.session and not ns.new:
@@ -105,6 +132,11 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
raise _AuthError("no API key (set --api-key or WORLDTREE_API_KEY)") raise _AuthError("no API key (set --api-key or WORLDTREE_API_KEY)")
server_url = ns.server or os.environ.get("WORLDTREE_API_URL") or "http://localhost:8000" server_url = ns.server or os.environ.get("WORLDTREE_API_URL") or "http://localhost:8000"
# Issue #5 (post-2026-05-23 amendment): env-var fallback for end_user_id.
# Resolution: --end-user-id flag > $RATATOSKR_END_USER_ID > None. env.sh
# ships the project-stable default "ratatoskr-tui" so a sourced session
# gets a stable partition without papering over the explicit-flag override.
end_user_id = ns.end_user_id or os.environ.get("RATATOSKR_END_USER_ID") or None
return ParsedArgs( return ParsedArgs(
send_content=ns.send, send_content=ns.send,
@@ -114,6 +146,7 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
api_key=api_key, api_key=api_key,
server_url=server_url, server_url=server_url,
raw=ns.raw, raw=ns.raw,
end_user_id=end_user_id,
) )
@@ -266,7 +299,10 @@ async def _amain(args: ParsedArgs) -> int:
assert isinstance(args, ParsedArgs) assert isinstance(args, ParsedArgs)
async with httpx.AsyncClient( async with httpx.AsyncClient(
base_url=args.server_url, base_url=args.server_url,
headers={"Authorization": f"Bearer {args.api_key}"}, headers={
"Authorization": f"Bearer {args.api_key}",
"User-Agent": USER_AGENT,
},
# SSE streaming sits idle between events while the LLM thinks. # SSE streaming sits idle between events while the LLM thinks.
# Default 5s read timeout would kill mid-stream; disable it. # Default 5s read timeout would kill mid-stream; disable it.
# connect/write/pool keep modest timeouts so true network failures # connect/write/pool keep modest timeouts so true network failures
@@ -276,7 +312,9 @@ async def _amain(args: ParsedArgs) -> int:
if args.new: if args.new:
assert args.agent_id is not None assert args.agent_id is not None
try: try:
info = await create_session(client, args.agent_id) info = await create_session(
client, args.agent_id, end_user_id=args.end_user_id
)
except AgentNotFound as exc: except AgentNotFound as exc:
sys.stderr.write(f"[agent_not_found] agent_id={exc.agent_id}\n") sys.stderr.write(f"[agent_not_found] agent_id={exc.agent_id}\n")
return 12 return 12
src/ratatoskr/sessions.py
+18 -3
View File
@@ -116,12 +116,27 @@ async def list_sessions(
return SessionPage(items=items, next_cursor=body.get("next_cursor")) return SessionPage(items=items, next_cursor=body.get("next_cursor"))
async def create_session(client: httpx.AsyncClient, agent_id: str) -> SessionInfo: async def create_session(
"""POST /sessions to create a new session. See contract FN create_session.""" client: httpx.AsyncClient,
agent_id: str,
*,
end_user_id: str | None = None,
) -> SessionInfo:
"""POST /sessions to create a new session. See contract FN create_session.
Per issue #5: pass `end_user_id` for per-end-user agents (lofn etc.).
When None (default), the body shape matches the pre-#5 baseline
`{"agent_id": agent_id}` so existing callers (mimir smoke) are unaffected.
Empty-string `end_user_id` is rejected before HTTP (PRE-003).
"""
assert client is not None assert client is not None
assert agent_id and isinstance(agent_id, str) assert agent_id and isinstance(agent_id, str)
assert end_user_id is None or (isinstance(end_user_id, str) and end_user_id)
resp = await client.post("/sessions", json={"agent_id": agent_id}) body: dict[str, str] = {"agent_id": agent_id}
if end_user_id is not None:
body["end_user_id"] = end_user_id
resp = await client.post("/sessions", json=body)
if resp.status_code == 404: if resp.status_code == 404:
raise AgentNotFound(agent_id=agent_id) raise AgentNotFound(agent_id=agent_id)
if resp.status_code != 201: if resp.status_code != 201:
src/ratatoskr/tui.py
+80 -44
View File
@@ -1,10 +1,15 @@
"""Ratatoskr Textual TUI shell — interactive primary presenter. """Ratatoskr Textual TUI shell — interactive primary presenter.
Implements docs/contracts/issues/4.contract.md. Implements docs/contracts/issues/4.contract.md, as amended in-place by
docs/contracts/issues/6.contract.md (session resolution lifted out of
on_mount into a pre-App.run() async helper; AsyncClient ownership moves
with it).
""" """
from __future__ import annotations from __future__ import annotations
import asyncio
import sys
from typing import ClassVar, Literal from typing import ClassVar, Literal
import httpx import httpx
@@ -12,7 +17,7 @@ from textual.app import App, ComposeResult
from textual.binding import Binding from textual.binding import Binding
from textual.widgets import Footer, Header, Input, RichLog, Static from textual.widgets import Footer, Header, Input, RichLog, Static
from ratatoskr.cli import ParsedArgs from ratatoskr.cli import USER_AGENT, ParsedArgs
from ratatoskr.sessions import AgentNotFound, SessionApiFailed, create_session from ratatoskr.sessions import AgentNotFound, SessionApiFailed, create_session
from ratatoskr.sse_client import ( from ratatoskr.sse_client import (
CancelAlreadyCompleted, CancelAlreadyCompleted,
@@ -88,12 +93,19 @@ class RatatoskrApp(App[int]):
HINT_STREAMING = "Ctrl-C to cancel" HINT_STREAMING = "Ctrl-C to cancel"
HINT_CANCELLING = "Press Ctrl-C again to exit" HINT_CANCELLING = "Press Ctrl-C again to exit"
def __init__(self, args: ParsedArgs) -> None: def __init__(
self,
args: ParsedArgs,
*,
session_id: str,
agent_id: str | None,
client: httpx.AsyncClient,
) -> None:
super().__init__() super().__init__()
self.args = args self.args = args
self.session_id: str | None = None self.session_id: str = session_id
self.agent_id: str | None = None self.agent_id: str | None = agent_id
self.client: httpx.AsyncClient | None = None self.client: httpx.AsyncClient = client
self.state: Literal["idle", "streaming", "cancelling"] = "idle" self.state: Literal["idle", "streaming", "cancelling"] = "idle"
self.active_turn_id: int | None = None self.active_turn_id: int | None = None
self.stream_worker = None self.stream_worker = None
@@ -116,39 +128,12 @@ class RatatoskrApp(App[int]):
yield Footer() yield Footer()
async def on_mount(self) -> None: async def on_mount(self) -> None:
"""Open AsyncClient, mint or attach session, populate footer with identity.""" """Populate identity widget from pre-resolved state; set idle hint.
assert self.client is None
self.client = httpx.AsyncClient(
base_url=self.args.server_url,
headers={"Authorization": f"Bearer {self.args.api_key}"},
# SSE streaming sits idle between events while the LLM thinks.
# Default 5s read timeout would kill mid-stream; disable it.
timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0),
)
log = self.query_one("#transcript", RichLog)
if self.args.new:
assert self.args.agent_id is not None
try:
info = await create_session(self.client, self.args.agent_id)
except AgentNotFound as exc:
log.write(f"[agent_not_found] agent_id={exc.agent_id}")
self.exit(12)
return
except SessionApiFailed as exc:
log.write(f"[session_api_failed] status={exc.status} body={exc.body!r}")
self.exit(20)
return
except (httpx.ConnectError, httpx.ReadTimeout, httpx.TransportError) as exc:
log.write(f"[network_error] {type(exc).__name__}: {exc}")
self.exit(21)
return
self.session_id = info.session_id
self.agent_id = info.agent_id
else:
assert self.args.session_id is not None
self.session_id = self.args.session_id
self.agent_id = self.args.agent_id # may be None — INV-002 carve-out
Per issue #6: session resolution + client open happen in `_resolve_then_run`
BEFORE App.run_async() — only identity-widget population lives here.
"""
assert self.client is not None and self.session_id is not None
agent_slot = self.agent_id or "<unknown>" agent_slot = self.agent_id or "<unknown>"
identity = f"{agent_slot} · …{self.session_id[-8:]}" identity = f"{agent_slot} · …{self.session_id[-8:]}"
self.sub_title = identity # mirror to Header subtitle for redundancy self.sub_title = identity # mirror to Header subtitle for redundancy
@@ -222,9 +207,8 @@ class RatatoskrApp(App[int]):
self._set_hint(self.HINT_IDLE) self._set_hint(self.HINT_IDLE)
async def on_unmount(self) -> None: async def on_unmount(self) -> None:
"""Close the httpx.AsyncClient cleanly.""" """No-op — client lifetime is managed by run_tui's async-with (INV-002)."""
if self.client is not None and not self.client.is_closed: return None
await self.client.aclose()
def action_interrupt(self) -> None: def action_interrupt(self) -> None:
"""Two-stage Ctrl-C state machine per INV-003.""" """Two-stage Ctrl-C state machine per INV-003."""
@@ -256,13 +240,65 @@ class RatatoskrApp(App[int]):
def run_tui(args: ParsedArgs) -> int: def run_tui(args: ParsedArgs) -> int:
"""Sync entry point — wraps App.run(). Returns the exit code from App.run().""" """Sync entry point — delegates to the async resolve-then-run flow.
Per issue #6: session resolution + AsyncClient open happen BEFORE the
Textual alt-screen opens, so startup errors land on the operator's real
stderr instead of getting eaten by the alt-screen teardown.
"""
# PRE-001: TUI-mode marker (issue #4 contract) # PRE-001: TUI-mode marker (issue #4 contract)
assert isinstance(args, ParsedArgs) and args.send_content is None assert isinstance(args, ParsedArgs) and args.send_content is None
# PRE-002: Exactly one of session_id / new must be set (xor) # PRE-002: Exactly one of session_id / new must be set (xor)
assert bool(args.session_id) != bool(args.new) assert bool(args.session_id) != bool(args.new)
app = RatatoskrApp(args) return asyncio.run(_resolve_then_run(args))
return app.run() or 0
async def _resolve_then_run(args: ParsedArgs) -> int:
"""Pre-flight session resolution then App.run_async() inside one event loop.
Errors at this layer print to `sys.stderr` (the operator's real terminal)
and short-circuit BEFORE the alt-screen opens (INV-001). The label format
+ exit codes match `ratatoskr.cli._amain`'s exactly (INV-006), so operators
see one vocabulary across `--send` and TUI modes.
"""
# PRE-001 (defense-in-depth; run_tui also asserts at the sync boundary)
assert isinstance(args, ParsedArgs) and args.send_content is None
async with httpx.AsyncClient(
base_url=args.server_url,
headers={
"Authorization": f"Bearer {args.api_key}",
"User-Agent": USER_AGENT,
},
# SSE streaming sits idle between events while the LLM thinks.
# Default 5s read timeout would kill mid-stream; disable it.
timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0),
) as client:
if args.new:
assert args.agent_id is not None
try:
info = await create_session(
client, args.agent_id, end_user_id=args.end_user_id
)
except AgentNotFound as exc:
sys.stderr.write(f"[agent_not_found] agent_id={exc.agent_id}\n")
return 12
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
session_id = info.session_id
agent_id: str | None = info.agent_id
else:
assert args.session_id is not None
session_id = args.session_id
agent_id = args.agent_id # may be None — INV-002 carve-out preserved
app = RatatoskrApp(args, session_id=session_id, agent_id=agent_id, client=client)
exit_code = await app.run_async()
return exit_code or 0
async def _cancel_via_sse( async def _cancel_via_sse(
tests/test_cli.py
+68
View File
@@ -86,6 +86,7 @@ def _clear_env(monkeypatch: pytest.MonkeyPatch) -> None:
"""Tests assert env-resolution behavior; default to a clean slate per test.""" """Tests assert env-resolution behavior; default to a clean slate per test."""
monkeypatch.delenv("WORLDTREE_API_KEY", raising=False) monkeypatch.delenv("WORLDTREE_API_KEY", raising=False)
monkeypatch.delenv("WORLDTREE_API_URL", raising=False) monkeypatch.delenv("WORLDTREE_API_URL", raising=False)
monkeypatch.delenv("RATATOSKR_END_USER_ID", raising=False)
class TestParseArgs: class TestParseArgs:
@@ -196,6 +197,42 @@ class TestParseArgs:
with pytest.raises(UsageError): with pytest.raises(UsageError):
_parse_args(["--send", "", "--new", "--agent", "x", "--api-key", "k"]) _parse_args(["--send", "", "--new", "--agent", "x", "--api-key", "k"])
def test_happy_new_with_end_user_id(self) -> None:
"""happy_new_with_end_user_id [happy]: --end-user-id alice → end_user_id='alice'."""
args = _parse_args(
["--send", "hi", "--new", "--agent", "lofn", "--api-key", "k",
"--end-user-id", "alice"]
)
assert args.end_user_id == "alice"
assert args.agent_id == "lofn"
def test_end_user_id_default_none(self) -> None:
"""end_user_id_default_none [trace]: omit --end-user-id → ParsedArgs.end_user_id is None."""
args = _parse_args(["--send", "hi", "--new", "--agent", "m", "--api-key", "k"])
assert args.end_user_id is None
def test_empty_end_user_id(self) -> None:
"""empty_end_user_id [adversarial]: --end-user-id '' → UsageError (mirrors empty --send)."""
with pytest.raises(UsageError, match="--end-user-id"):
_parse_args(
["--send", "hi", "--new", "--agent", "m", "--api-key", "k", "--end-user-id", ""]
)
def test_end_user_id_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""end_user_id_from_env [trace]: $RATATOSKR_END_USER_ID fills when flag omitted."""
monkeypatch.setenv("RATATOSKR_END_USER_ID", "ratatoskr-tui")
args = _parse_args(["--send", "hi", "--new", "--agent", "m", "--api-key", "k"])
assert args.end_user_id == "ratatoskr-tui"
def test_end_user_id_flag_beats_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""end_user_id_flag_beats_env [trace]: explicit --end-user-id wins over env."""
monkeypatch.setenv("RATATOSKR_END_USER_ID", "from-env")
args = _parse_args(
["--send", "hi", "--new", "--agent", "m", "--api-key", "k",
"--end-user-id", "from-flag"]
)
assert args.end_user_id == "from-flag"
SID = SseId(42, 5) SID = SseId(42, 5)
@@ -817,6 +854,16 @@ _PARSED_NEW = ParsedArgs(
server_url="https://w.example", server_url="https://w.example",
raw=False, raw=False,
) )
_PARSED_NEW_WITH_END_USER = ParsedArgs(
send_content="hi",
session_id=None,
new=True,
agent_id="mimir",
api_key="k",
server_url="https://w.example",
raw=False,
end_user_id="alice",
)
_PARSED_EXISTING = ParsedArgs( _PARSED_EXISTING = ParsedArgs(
send_content="hi", send_content="hi",
session_id="s-1", session_id="s-1",
@@ -837,6 +884,27 @@ _CREATE_OK_RESP = {
class TestAmain: class TestAmain:
@respx.mock
async def test_user_agent_header_sent(self) -> None:
"""user_agent_header_sent [trace]: outbound requests carry the ratatoskr User-Agent.
Worldtree-dev (althing 2026-05-23) requested consumers send User-Agent
so server logs can distinguish ratatoskr traffic.
"""
sessions_route = respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
sse_body = _sse_chunk("42:1", {"type": "text", "content": "hi"}) + _sse_chunk(
"42:2", _DONE_BODY
)
respx.post("https://w.example/sessions/s-new/messages").mock(
return_value=_sse_resp(sse_body)
)
await _amain(_PARSED_NEW)
ua = sessions_route.calls[0].request.headers["User-Agent"]
assert ua.startswith("ratatoskr/")
assert "vh@phasefinal.com" in ua
@respx.mock @respx.mock
async def test_happy_new_session_then_stream(self, capsys: pytest.CaptureFixture[str]) -> None: async def test_happy_new_session_then_stream(self, capsys: pytest.CaptureFixture[str]) -> None:
"""happy_new_session_then_stream [happy,tracer]: …""" """happy_new_session_then_stream [happy,tracer]: …"""
tests/test_sessions.py
+62
View File
@@ -137,6 +137,68 @@ class TestCreateSession:
await create_session(client, "") await create_session(client, "")
assert route.call_count == 0 assert route.call_count == 0
@respx.mock
async def test_happy_create_with_end_user_id(self) -> None:
"""happy_create_with_end_user_id [happy]: body carries both keys (issue #5)."""
import json as _json
route = respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(
201,
json={
"session_id": "s-new",
"agent_id": "lofn",
"message_count": 0,
"created_at": "2026-05-22T12:00:00+00:00",
"last_active": "2026-05-22T12:00:00+00:00",
"metadata": {},
},
)
)
async with httpx.AsyncClient(base_url="https://w.example") as client:
info = await create_session(client, "lofn", end_user_id="alice")
body = _json.loads(route.calls[0].request.content)
# INV: body MUST be exactly {"agent_id": ..., "end_user_id": ...} — byte-for-byte
assert body == {"agent_id": "lofn", "end_user_id": "alice"}
assert info.session_id == "s-new"
assert info.agent_id == "lofn"
@respx.mock
async def test_default_omits_end_user_id(self) -> None:
"""default_omits_end_user_id [trace]: omit kwarg → body has no end_user_id (INV-002)."""
import json as _json
route = respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(
201,
json={
"session_id": "s-new",
"agent_id": "mimir",
"message_count": 0,
"created_at": "2026-05-22T12:00:00+00:00",
"last_active": "2026-05-22T12:00:00+00:00",
"metadata": {},
},
)
)
async with httpx.AsyncClient(base_url="https://w.example") as client:
await create_session(client, "mimir")
body = _json.loads(route.calls[0].request.content)
# Exact equality — no end_user_id key in the body when the kwarg is omitted
assert body == {"agent_id": "mimir"}
assert "end_user_id" not in body
@respx.mock
async def test_empty_end_user_id(self) -> None:
"""empty_end_user_id [adversarial]: '' → AssertionError before HTTP (PRE-003)."""
route = respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, content=b"{}")
)
async with httpx.AsyncClient(base_url="https://w.example") as client:
with pytest.raises(AssertionError):
await create_session(client, "mimir", end_user_id="")
assert route.call_count == 0
def _list_item( def _list_item(
*, *,
tests/test_tui.py
+397 -114
View File
@@ -74,6 +74,32 @@ def _spy_writes(monkeypatch) -> list:
return writes return writes
def _resolved_app(
args: ParsedArgs,
*,
session_id: str | None = None,
agent_id: str | None = None,
client: httpx.AsyncClient | None = None,
) -> RatatoskrApp:
"""Construct RatatoskrApp with pre-resolved state (issue #6 lifecycle).
Production path: `run_tui` → `_resolve_then_run` opens AsyncClient, mints
or attaches session, then constructs the App with the resolved tuple. This
helper inlines that shape so tests bypass the pre-flight without
re-implementing it. The client is opened here (and leaks at test teardown
— acceptable; respx mocks all network calls and pytest exits cleanly).
"""
sid = session_id if session_id is not None else (args.session_id or "s-default")
aid = args.agent_id if agent_id is None else agent_id
if client is None:
client = httpx.AsyncClient(
base_url=args.server_url,
headers={"Authorization": f"Bearer {args.api_key}"},
timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0),
)
return RatatoskrApp(args, session_id=sid, agent_id=aid, client=client)
SID = SseId(42, 5) SID = SseId(42, 5)
@@ -228,13 +254,16 @@ class TestCancelViaSse:
class TestAppMount: class TestAppMount:
@respx.mock """on_mount narrows per issue #6: only identity-widget population.
Session resolution + AsyncClient open + error-on-resolve are exercised at
the `_resolve_then_run` layer (see TestResolveThenRun); only happy mount
paths remain here, exercised with pre-resolved state via _resolved_app.
"""
async def test_happy_new_session_mount(self) -> None: async def test_happy_new_session_mount(self) -> None:
"""happy_new_session_mount [happy,tracer]: …""" """happy_new_session_mount [happy,tracer]: identity populated from pre-resolved state."""
respx.post("https://w.example/sessions").mock( app = _resolved_app(_args_new(), session_id="s-new12345", agent_id="mimir")
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
app = RatatoskrApp(_args_new())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
assert app.session_id == "s-new12345" assert app.session_id == "s-new12345"
@@ -244,74 +273,22 @@ class TestAppMount:
assert "mimir" in (app.sub_title or "") assert "mimir" in (app.sub_title or "")
assert app.session_id[-8:] in (app.sub_title or "") assert app.session_id[-8:] in (app.sub_title or "")
@respx.mock
async def test_happy_existing_session_mount(self) -> None: async def test_happy_existing_session_mount(self) -> None:
"""happy_existing_session_mount: …""" """happy_existing_session_mount: identity shows <unknown> when agent_id is None."""
sessions_route = respx.post("https://w.example/sessions").mock( app = _resolved_app(_args_existing(session_id="s-existing-tail8x"))
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
app = RatatoskrApp(_args_existing(session_id="s-existing-tail8x"))
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
assert app.session_id == "s-existing-tail8x" assert app.session_id == "s-existing-tail8x"
assert app.state == "idle" assert app.state == "idle"
assert sessions_route.call_count == 0
# INV-002 carve-out: agent unknown → <unknown> · …<tail> # INV-002 carve-out: agent unknown → <unknown> · …<tail>
assert "<unknown>" in (app.sub_title or "") assert "<unknown>" in (app.sub_title or "")
assert app.session_id[-8:] in (app.sub_title or "") assert app.session_id[-8:] in (app.sub_title or "")
@respx.mock
async def test_agent_not_found_on_mount(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""agent_not_found_on_mount [error]: …"""
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(404, json={"error": "unknown_agent_id"})
)
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_new())
async with app.run_test() as pilot:
await pilot.pause()
assert app.return_value == 12
assert any("[agent_not_found]" in str(w) for w in writes)
@respx.mock
async def test_session_api_failed_on_mount(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""session_api_failed_on_mount [error]: …"""
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(500, content=b"server error")
)
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_new())
async with app.run_test() as pilot:
await pilot.pause()
assert app.return_value == 20
assert any("[session_api_failed]" in str(w) and "status=500" in str(w) for w in writes)
@respx.mock
async def test_network_error_on_mount(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""network_error_on_mount [error]: …"""
respx.post("https://w.example/sessions").mock(side_effect=httpx.ConnectError("down"))
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_new())
async with app.run_test() as pilot:
await pilot.pause()
assert app.return_value == 21
assert any("[network_error]" in str(w) for w in writes)
@respx.mock
async def test_footer_identity_visible_first_frame(self) -> None: async def test_footer_identity_visible_first_frame(self) -> None:
"""footer_identity_visible_first_frame [trace]: …""" """footer_identity_visible_first_frame [trace]: identity widget rendered first frame."""
from textual.widgets import Static from textual.widgets import Static
respx.post("https://w.example/sessions").mock( app = _resolved_app(_args_new(), session_id="s-new12345", agent_id="mimir")
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
app = RatatoskrApp(_args_new())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
identity_widget = app.query_one("#identity", Static) identity_widget = app.query_one("#identity", Static)
@@ -320,32 +297,6 @@ class TestAppMount:
assert "·" in rendered assert "·" in rendered
assert app.session_id[-8:] in rendered assert app.session_id[-8:] in rendered
@respx.mock
async def test_client_open_after_mount(self) -> None:
"""client_open_after_mount [trace]: post-mount self.client is open."""
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
app = RatatoskrApp(_args_new())
async with app.run_test() as pilot:
await pilot.pause()
assert app.client is not None
assert app.client.is_closed is False
class TestAppUnmount:
@respx.mock
async def test_unmount_closes_client(self) -> None:
"""unmount_closes_client [happy,tracer]: …"""
app = RatatoskrApp(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
client_ref = app.client
assert client_ref is not None and not client_ref.is_closed
await pilot.press("ctrl+d")
await pilot.pause()
assert client_ref.is_closed
import asyncio # noqa: E402 import asyncio # noqa: E402
@@ -365,7 +316,7 @@ class TestOnInputSubmitted:
"""happy_submit_echoes_and_spawns [happy,tracer]: …""" """happy_submit_echoes_and_spawns [happy,tracer]: …"""
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker) monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
@@ -383,15 +334,19 @@ class TestOnInputSubmitted:
) -> None: ) -> None:
"""empty_submit_no_op [trace]: '' + Enter → no change; no worker spawned.""" """empty_submit_no_op [trace]: '' + Enter → no change; no worker spawned."""
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker) monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
# Spy AFTER mount so identity-widget writes (if any) aren't counted.
writes = _spy_writes(monkeypatch)
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
inp.value = "" inp.value = ""
await inp.action_submit() await inp.action_submit()
await pilot.pause() await pilot.pause()
assert app.state == "idle" assert app.state == "idle"
assert app.stream_worker is None assert app.stream_worker is None
# POST: no RichLog write fires on empty submit
assert writes == []
@respx.mock @respx.mock
async def test_submit_during_streaming_shows_busy_notice( async def test_submit_during_streaming_shows_busy_notice(
@@ -400,7 +355,7 @@ class TestOnInputSubmitted:
"""submit_during_streaming_shows_busy_notice [adversarial]: …""" """submit_during_streaming_shows_busy_notice [adversarial]: …"""
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker) monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
@@ -427,16 +382,21 @@ class TestOnInputSubmitted:
"""submit_during_cancelling_shows_busy_notice [adversarial]: …""" """submit_during_cancelling_shows_busy_notice [adversarial]: …"""
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker) monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
app.state = "cancelling" # bypass the natural transition for the test app.state = "cancelling" # bypass the natural transition for the test
assert app.stream_worker is None # no live worker before non-idle submit
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
inp.value = "x" inp.value = "x"
await inp.action_submit() await inp.action_submit()
await pilot.pause() await pilot.pause()
assert any("[busy]" in str(w) for w in writes) assert any("[busy]" in str(w) for w in writes)
assert app.state == "cancelling" assert app.state == "cancelling"
# POST-005 (from issue #4 on_input_submitted contract):
# input cleared; NO new worker spawned during non-idle submit.
assert inp.value == ""
assert app.stream_worker is None
@respx.mock @respx.mock
async def test_footer_hint_flips_to_cancel( async def test_footer_hint_flips_to_cancel(
@@ -446,7 +406,7 @@ class TestOnInputSubmitted:
from textual.widgets import Static from textual.widgets import Static
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker) monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
hint_widget = app.query_one("#hint", Static) hint_widget = app.query_one("#hint", Static)
@@ -528,7 +488,7 @@ class TestStreamTurnWorker:
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await _submit_and_wait(app, pilot, "hi") await _submit_and_wait(app, pilot, "hi")
@@ -536,9 +496,12 @@ class TestStreamTurnWorker:
# Streamed delta + done label + rule + markdown render # Streamed delta + done label + rule + markdown render
assert any(w == "hello" for w in writes) assert any(w == "hello" for w in writes)
assert any("[done]" in str(w) for w in writes) assert any("[done]" in str(w) for w in writes)
# The post-Done markdown render uses rich Rule + Markdown — non-string writes # The post-Done markdown render uses rich Rule + Markdown — non-string writes.
# INV-005: BOTH separator (Rule) AND markdown render must be present in non-raw.
from rich.markdown import Markdown from rich.markdown import Markdown
from rich.rule import Rule
assert any(isinstance(w, Markdown) for w in writes) assert any(isinstance(w, Markdown) for w in writes)
assert any(isinstance(w, Rule) for w in writes)
@respx.mock @respx.mock
async def test_raw_flag_skips_markdown_render( async def test_raw_flag_skips_markdown_render(
@@ -558,12 +521,15 @@ class TestStreamTurnWorker:
).mock(return_value=_sse_resp(stream)) ).mock(return_value=_sse_resp(stream))
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing(raw=True)) app = _resolved_app(_args_existing(raw=True))
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await _submit_and_wait(app, pilot, "x") await _submit_and_wait(app, pilot, "x")
# INV-005: with --raw, NEITHER Rule separator NOR Markdown render appears.
from rich.markdown import Markdown from rich.markdown import Markdown
from rich.rule import Rule
assert not any(isinstance(w, Markdown) for w in writes) assert not any(isinstance(w, Markdown) for w in writes)
assert not any(isinstance(w, Rule) for w in writes)
@respx.mock @respx.mock
async def test_error_terminal_returns_to_idle( async def test_error_terminal_returns_to_idle(
@@ -591,7 +557,7 @@ class TestStreamTurnWorker:
).mock(return_value=_sse_resp(stream)) ).mock(return_value=_sse_resp(stream))
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await _submit_and_wait(app, pilot, "x") await _submit_and_wait(app, pilot, "x")
@@ -616,7 +582,7 @@ class TestStreamTurnWorker:
).mock(return_value=_sse_resp(stream)) ).mock(return_value=_sse_resp(stream))
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await _submit_and_wait(app, pilot, "x") await _submit_and_wait(app, pilot, "x")
@@ -645,7 +611,7 @@ class TestStreamTurnWorker:
return_value=_sse_resp(_GatedAfterFirst()) return_value=_sse_resp(_GatedAfterFirst())
) )
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
@@ -673,7 +639,7 @@ class TestStreamTurnWorker:
return_value=httpx.Response(404, json={"error": "session_not_found"}) return_value=httpx.Response(404, json={"error": "session_not_found"})
) )
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await _submit_and_wait(app, pilot, "x") await _submit_and_wait(app, pilot, "x")
@@ -699,7 +665,7 @@ class TestStreamTurnWorker:
return_value=_sse_resp(_DropAfter()) return_value=_sse_resp(_DropAfter())
) )
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await _submit_and_wait(app, pilot, "x") await _submit_and_wait(app, pilot, "x")
@@ -719,7 +685,7 @@ class TestStreamTurnWorker:
"https://w.example/sessions/s-1existing/messages" "https://w.example/sessions/s-1existing/messages"
).mock(return_value=_sse_resp(stream)) ).mock(return_value=_sse_resp(stream))
writes = _spy_writes(monkeypatch) writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await _submit_and_wait(app, pilot, "x") await _submit_and_wait(app, pilot, "x")
@@ -756,7 +722,7 @@ class TestStreamTurnWorker:
return original(event, log=log, raw=raw) return original(event, log=log, raw=raw)
monkeypatch.setattr(tui_mod, "_render_event_to_log", spy) monkeypatch.setattr(tui_mod, "_render_event_to_log", spy)
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await _submit_and_wait(app, pilot, "x") await _submit_and_wait(app, pilot, "x")
@@ -767,7 +733,7 @@ class TestActionInterrupt:
@respx.mock @respx.mock
async def test_idle_ctrl_c_exits_zero(self) -> None: async def test_idle_ctrl_c_exits_zero(self) -> None:
"""idle_ctrl_c_exits_zero [happy,tracer]: state=idle; ctrl+c → exit(0).""" """idle_ctrl_c_exits_zero [happy,tracer]: state=idle; ctrl+c → exit(0)."""
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
assert app.state == "idle" assert app.state == "idle"
@@ -805,7 +771,7 @@ class TestActionInterrupt:
side_effect=cancel_handler side_effect=cancel_handler
) )
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
@@ -858,7 +824,7 @@ class TestActionInterrupt:
return_value=_sse_resp(_NeverYields()) return_value=_sse_resp(_NeverYields())
) )
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
@@ -867,22 +833,54 @@ class TestActionInterrupt:
await pilot.pause() await pilot.pause()
assert app.state == "streaming" assert app.state == "streaming"
assert app.active_turn_id is None assert app.active_turn_id is None
# Capture worker reference + spy on its .cancel() before ctrl+c
worker_ref = app.stream_worker
assert worker_ref is not None
cancel_calls: list = []
original_cancel = type(worker_ref).cancel
monkeypatch.setattr(
type(worker_ref),
"cancel",
lambda self: (cancel_calls.append(self), original_cancel(self))[-1],
)
await pilot.press("ctrl+c") await pilot.press("ctrl+c")
await pilot.pause() await pilot.pause()
gate.set() # let the gated stream resolve so teardown is clean gate.set() # let the gated stream resolve so teardown is clean
assert app.return_value == 3 assert app.return_value == 3
assert cancel_route.call_count == 0 assert cancel_route.call_count == 0
# action_interrupt MUST cancel the stream worker on the no-active_turn_id force-exit path
assert worker_ref in cancel_calls
@respx.mock @respx.mock
async def test_cancelling_second_ctrl_c_force_exits(self) -> None: async def test_cancelling_second_ctrl_c_force_exits(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""cancelling_second_ctrl_c_force_exits [scenario]: …""" """cancelling_second_ctrl_c_force_exits [scenario]: …"""
app = RatatoskrApp(_args_existing()) # Set up a real live stream worker (gated, hangs forever) so we can
# observe action_interrupt's cancel() call on the second-Ctrl-C path.
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
inp = app.query_one("#prompt", Input)
inp.value = "go"
await inp.action_submit()
await pilot.pause()
assert app.stream_worker is not None
app.state = "cancelling" # bypass the natural transition for the test app.state = "cancelling" # bypass the natural transition for the test
worker_ref = app.stream_worker
cancel_calls: list = []
original_cancel = type(worker_ref).cancel
monkeypatch.setattr(
type(worker_ref),
"cancel",
lambda self: (cancel_calls.append(self), original_cancel(self))[-1],
)
await pilot.press("ctrl+c") await pilot.press("ctrl+c")
await pilot.pause() await pilot.pause()
assert app.return_value == 3 assert app.return_value == 3
# Second-Ctrl-C in cancelling state MUST cancel the in-flight worker
assert worker_ref in cancel_calls
@respx.mock @respx.mock
async def test_cancel_failed_swallowed(self) -> None: async def test_cancel_failed_swallowed(self) -> None:
@@ -911,7 +909,7 @@ class TestActionInterrupt:
side_effect=cancel_handler side_effect=cancel_handler
) )
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
@@ -940,7 +938,7 @@ class TestActionQuit:
@respx.mock @respx.mock
async def test_idle_ctrl_d_exits_zero(self) -> None: async def test_idle_ctrl_d_exits_zero(self) -> None:
"""idle_ctrl_d_exits_zero [happy,tracer]: state=idle; ctrl+d → exit(0).""" """idle_ctrl_d_exits_zero [happy,tracer]: state=idle; ctrl+d → exit(0)."""
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
await pilot.press("ctrl+d") await pilot.press("ctrl+d")
@@ -969,7 +967,7 @@ class TestActionQuit:
respx.post("https://w.example/sessions/s-1existing/messages").mock( respx.post("https://w.example/sessions/s-1existing/messages").mock(
return_value=_sse_resp(_GatedAfterFirst()) return_value=_sse_resp(_GatedAfterFirst())
) )
app = RatatoskrApp(_args_existing()) app = _resolved_app(_args_existing())
async with app.run_test() as pilot: async with app.run_test() as pilot:
await pilot.pause() await pilot.pause()
inp = app.query_one("#prompt", Input) inp = app.query_one("#prompt", Input)
@@ -980,26 +978,311 @@ class TestActionQuit:
if app.active_turn_id == 42: if app.active_turn_id == 42:
break break
await pilot.pause(0.02) await pilot.pause(0.02)
# Capture worker + spy on cancel before ctrl+d
worker_ref = app.stream_worker
assert worker_ref is not None
cancel_calls: list = []
original_cancel = type(worker_ref).cancel
monkeypatch.setattr(
type(worker_ref),
"cancel",
lambda self: (cancel_calls.append(self), original_cancel(self))[-1],
)
await pilot.press("ctrl+d") await pilot.press("ctrl+d")
await pilot.pause() await pilot.pause()
gate.set() gate.set()
assert app.return_value == 0 assert app.return_value == 0
assert cancel_route.call_count == 0 assert cancel_route.call_count == 0
# POST-002: Ctrl-D MUST cancel the in-flight stream worker (abandon-and-exit)
assert worker_ref in cancel_calls
from ratatoskr.tui import run_tui # noqa: E402 from ratatoskr.tui import run_tui # noqa: E402
class TestResolveThenRun:
"""Tests at the `_resolve_then_run` layer — pre-`App.run()` session
resolution + AsyncClient ownership + stderr error routing per issue #6.
"""
@respx.mock
def test_happy_new_session_resolve(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""happy_new_session_resolve [happy]: --new path through _resolve_then_run.
Verifies POST /sessions count + SessionInfo propagation to RatatoskrApp's
pre-resolved state (session_id / agent_id / client). The corresponding
TestAppMount.test_happy_new_session_mount uses _resolved_app and bypasses
_resolve_then_run entirely; this test exercises the production resolve
path with a real POST /sessions mock.
"""
sessions_route = respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
snapshot: dict = {}
async def capture_run_async(self, *a, **kw):
snapshot["session_id"] = self.session_id
snapshot["agent_id"] = self.agent_id
snapshot["client"] = self.client
snapshot["client_open"] = not self.client.is_closed
return 0
monkeypatch.setattr(RatatoskrApp, "run_async", capture_run_async)
rc = run_tui(_args_new())
assert rc == 0
# Exactly one POST /sessions invocation by _resolve_then_run
assert sessions_route.call_count == 1
# SessionInfo fields propagated into the constructed App
assert snapshot["session_id"] == "s-new12345"
assert snapshot["agent_id"] == "mimir"
assert snapshot["client"] is not None
assert snapshot["client_open"] is True
@respx.mock
def test_happy_new_with_end_user_id_resolve(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""happy_new_with_end_user_id_resolve [happy]: args.end_user_id threads into POST body.
Issue #5 amends #4: _resolve_then_run's create_session call now forwards
args.end_user_id (renamed from the contract's _mount target, since #6
moved session resolution out of on_mount into _resolve_then_run).
"""
import json as _json
sessions_route = respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
async def fake_run_async(self, *a, **kw):
return 0
monkeypatch.setattr(RatatoskrApp, "run_async", fake_run_async)
rc = run_tui(_args_new(end_user_id="alice"))
assert rc == 0
assert sessions_route.call_count == 1
body = _json.loads(sessions_route.calls[0].request.content)
assert body == {"agent_id": "mimir", "end_user_id": "alice"}
@respx.mock
def test_user_agent_header_sent(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""user_agent_header_sent [trace]: outbound requests carry the ratatoskr User-Agent.
Worldtree-dev (althing 2026-05-23) requested consumers send `User-Agent:
ratatoskr/<version> (<contact>)` so server logs can distinguish ratatoskr
traffic from other consumers.
"""
sessions_route = respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
async def fake_run_async(self, *a, **kw):
return 0
monkeypatch.setattr(RatatoskrApp, "run_async", fake_run_async)
rc = run_tui(_args_new())
assert rc == 0
ua = sessions_route.calls[0].request.headers["User-Agent"]
assert ua.startswith("ratatoskr/")
assert "vh@phasefinal.com" in ua
@respx.mock
def test_alt_screen_never_opens_on_resolve_error(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""alt_screen_never_opens_on_resolve_error [trace]: 404 → run_tui=12; run_async unhit.
Directly probes INV-001: session resolution failures MUST short-circuit
BEFORE the alt-screen opens.
"""
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(404, json={"error": "unknown_agent_id"})
)
sentinel_called = False
async def sentinel(self, *a, **kw):
nonlocal sentinel_called
sentinel_called = True
return 0
monkeypatch.setattr(RatatoskrApp, "run_async", sentinel)
rc = run_tui(_args_new())
assert rc == 12
assert not sentinel_called
@respx.mock
def test_agent_not_found_on_resolve(
self, capsys: pytest.CaptureFixture[str]
) -> None:
"""agent_not_found_on_resolve [error]: --new + 404 → stderr [agent_not_found]; exit 12."""
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(404, json={"error": "unknown_agent_id"})
)
rc = run_tui(_args_new())
err = capsys.readouterr().err
assert rc == 12
assert "[agent_not_found]" in err
assert "agent_id=mimir" in err
@respx.mock
def test_session_api_failed_on_resolve(
self, capsys: pytest.CaptureFixture[str]
) -> None:
"""session_api_failed_on_resolve [error]: --new + 500 → [session_api_failed] stderr."""
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(500, content=b"server error")
)
rc = run_tui(_args_new())
err = capsys.readouterr().err
assert rc == 20
assert "[session_api_failed]" in err
assert "status=500" in err
@respx.mock
def test_network_error_on_resolve(
self, capsys: pytest.CaptureFixture[str]
) -> None:
"""network_error_on_resolve [error]: --new + ConnectError → [network_error] stderr."""
respx.post("https://w.example/sessions").mock(side_effect=httpx.ConnectError("down"))
rc = run_tui(_args_new())
err = capsys.readouterr().err
assert rc == 21
assert "[network_error]" in err
assert "ConnectError" in err
@respx.mock
def test_stderr_label_format_matches_cli(
self, capsys: pytest.CaptureFixture[str]
) -> None:
"""stderr_label_format_matches_cli [trace]: cli._amain and _resolve_then_run produce
identical stderr lines for AgentNotFound (INV-006).
"""
# Re-fetch cli's ParsedArgs from the current module state — test_cli's
# `importlib.reload(ratatoskr.cli)` rebinds the class, so the top-of-file
# `from ratatoskr.cli import ParsedArgs` may now refer to a stale class.
from ratatoskr import cli as cli_mod
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(404, json={"error": "unknown_agent_id"})
)
cli_args = cli_mod.ParsedArgs(
send_content="x",
session_id=None,
new=True,
agent_id="mimir",
api_key="k",
server_url="https://w.example",
raw=False,
)
# Drive cli._amain's error path (--send mode)
cli_rc = asyncio.run(cli_mod._amain(cli_args))
cli_err = capsys.readouterr().err
# Drive _resolve_then_run's error path (TUI mode); _args_new() uses the
# pre-reload ParsedArgs which still matches tui.run_tui's isinstance check.
tui_rc = run_tui(_args_new())
tui_err = capsys.readouterr().err
# Same exit code, same verbatim stderr line.
assert cli_rc == 12
assert tui_rc == 12
assert cli_err == tui_err
assert cli_err == "[agent_not_found] agent_id=mimir\n"
def test_client_open_after_resolve(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""client_open_after_resolve [trace]: app.client is open at the time run_async runs."""
snapshot: dict = {}
async def capture_run_async(self, *a, **kw):
snapshot["client_is"] = self.client
snapshot["closed_during_run"] = self.client.is_closed
return 0
monkeypatch.setattr(RatatoskrApp, "run_async", capture_run_async)
rc = run_tui(_args_existing())
assert rc == 0
assert snapshot["client_is"] is not None
assert snapshot["closed_during_run"] is False
def test_client_lifetime_owned_by_run_tui(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""client_lifetime_owned_by_run_tui [trace]: open during run_async, closed after run_tui.
Probes INV-002: the App is a consumer of an externally-owned client;
the async-with in run_tui closes it, not on_unmount.
"""
snapshot: dict = {}
async def capture_run_async(self, *a, **kw):
# During run_async (the alt-screen lifetime) the client is open.
snapshot["client"] = self.client
snapshot["closed_during_run"] = self.client.is_closed
return 0
monkeypatch.setattr(RatatoskrApp, "run_async", capture_run_async)
rc = run_tui(_args_existing())
assert rc == 0
client = snapshot["client"]
assert client is not None
# Open while the app was running; closed by run_tui's async-with after.
assert snapshot["closed_during_run"] is False
assert client.is_closed is True
def test_run_tui_closes_client_on_app_exit(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""run_tui_closes_client_on_app_exit: async-with closes client after app.run_async ret."""
seen_clients: list[httpx.AsyncClient] = []
async def fake_run_async(self, *a, **kw):
seen_clients.append(self.client)
return 0
monkeypatch.setattr(RatatoskrApp, "run_async", fake_run_async)
rc = run_tui(_args_existing())
assert rc == 0
assert len(seen_clients) == 1
# After run_tui returns, the client should be closed by the async-with
assert seen_clients[0].is_closed
async def test_on_unmount_does_not_close_client(self) -> None:
"""on_unmount narrowed [trace]: probes INV-002 from the on_unmount side.
The complementary check to test_client_lifetime_owned_by_run_tui (which
patches run_async and so never exercises on_unmount). Here we DO run the
real on_unmount via Pilot ctrl+d → app teardown, and assert the client
is still open afterward (close site is run_tui's async-with, which is
NOT entered in this Pilot-driven test).
"""
client = httpx.AsyncClient(
base_url="https://w.example",
headers={"Authorization": "Bearer k"},
timeout=httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0),
)
app = RatatoskrApp(
_args_existing(),
session_id="s-1existing",
agent_id=None,
client=client,
)
async with app.run_test() as pilot:
await pilot.pause()
assert client.is_closed is False
await pilot.press("ctrl+d")
await pilot.pause()
# After app.run_test() teardown, on_unmount has fired. Per INV-002 the
# client MUST still be open — only run_tui's async-with closes it.
assert client.is_closed is False
await client.aclose() # test-side cleanup
class TestRunTui: class TestRunTui:
def test_happy_returns_zero_on_quit(self, monkeypatch: pytest.MonkeyPatch) -> None: def test_happy_returns_zero_on_quit(self, monkeypatch: pytest.MonkeyPatch) -> None:
"""happy_returns_zero_on_quit [happy,tracer]: run_tui propagates App.run() exit code.""" """happy_returns_zero_on_quit [happy,tracer]: run_tui propagates app.run_async exit code."""
captured: list[ParsedArgs] = [] captured: list[ParsedArgs] = []
def fake_run(self) -> int: async def fake_run_async(self, *a, **kw):
captured.append(self.args) captured.append(self.args)
return 0 return 0
monkeypatch.setattr(RatatoskrApp, "run", fake_run) monkeypatch.setattr(RatatoskrApp, "run_async", fake_run_async)
rc = run_tui(_args_existing()) rc = run_tui(_args_existing())
assert rc == 0 assert rc == 0
assert len(captured) == 1 assert len(captured) == 1
uv.lock
Generated
+1 -1
View File
@@ -968,7 +968,7 @@ wheels = [
[[package]] [[package]]
name = "ratatoskr" name = "ratatoskr"
version = "0.0.0" version = "0.1.0"
source = { editable = "." } source = { editable = "." }
dependencies = [ dependencies = [
{ name = "httpx" }, { name = "httpx" },