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
FN create_session(client: httpx.AsyncClient, agent_id: str) -> SessionInfo
BRIEF: POST /sessions with {"agent_id": agent_id} to create a new conversation session. Returns SessionInfo populated from the 201 response.
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 {"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-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-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:
@@ -109,19 +110,20 @@ ERROR_ROUTING:
HTTP 422 validation_failed:
local_handling: raise SessionApiFailed(status=422, body=resp.content[:1024])
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):
local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content[:1024])
flow_control: abort
state_recovery: none
STEPS:
1. [setup, flexibility=prescriptive] Validate inputs per PRE-001, PRE-002
2. [sequential, flexibility=prescriptive] CALL client.post("/sessions", json={"agent_id": agent_id})
1. [setup, flexibility=prescriptive] Validate inputs per PRE-001, PRE-002, PRE-003
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 }
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
4. [sequential] Parse resp.json() → body
5. [cleanup] RETURN SessionInfo(
5. [sequential] Parse resp.json() → body
6. [cleanup] RETURN SessionInfo(
session_id=body["session_id"],
agent_id=body["agent_id"],
created_at=body["created_at"],
@@ -135,11 +137,14 @@ STEPS:
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_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")
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
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
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`).
**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`.
- `new: bool` — mint a fresh session (`--new`); mutex with `session_id`.
- `agent_id: str | None` — required iff `new=True`.
- `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`.
- `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):**
- 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)
--server <url> (str, optional — env fallback + default in step 5)
--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:
TRY: ns = parser.parse_args(argv if argv is not None else sys.argv[1:])
ON SystemExit:
Re-raise as UsageError with argparse's captured message
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
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:
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")
@@ -273,6 +278,9 @@ STEPS:
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:
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(
send_content=ns.send, # may be None (TUI marker, issue #4 amendment)
session_id=ns.session,
@@ -281,6 +289,7 @@ STEPS:
api_key=api_key,
server_url=server_url,
raw=ns.raw, # issue #4 amendment
end_user_id=end_user_id, # issue #5 amendment (env-var fallback amended 2026-05-23)
)
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")
@@ -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")
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)
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
@@ -325,7 +339,7 @@ ERROR_ROUTING:
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 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:
WRITE stderr; RETURN 12
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-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-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-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]
return run_tui(args)
│
└─ RatatoskrApp(args).run()
└─ asyncio.run(_resolve_then_run(args)) [issue #6 amendment]
│
├─ on_mount: open AsyncClient, create_session (if --new),
│ init footer with agent_id + session_id_tail8
├─ 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 render
│ transition: streaming → idle
├─ action_interrupt (ctrl+c): two-stage state machine per INV-003
├─ action_quit (ctrl+d): app.exit(0)
└─ on_unmount: close AsyncClient
└─ async with httpx.AsyncClient(...) as client:
│
├─ pre-flight session resolve (--new → create_session,
│ else attach args.session_id). Errors → real stderr,
│ return appropriate exit code (12 / 20 / 21) BEFORE
│ the alt-screen opens (issue #6 INV-001 / INV-006).
│
├─ app = RatatoskrApp(args, session_id=..., agent_id=...,
│ client=client)
└─ await app.run_async():
│
├─ 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
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-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:
(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:
1. [setup, flexibility=prescriptive] Validate inputs per PRE-001..PRE-002
2. [sequential, flexibility=prescriptive] Construct app = RatatoskrApp(args)
3. [sequential, flexibility=prescriptive] RETURN app.run() — Textual's sync runner; manages its own asyncio loop
2. [sequential, flexibility=prescriptive] RETURN asyncio.run(_resolve_then_run(args))
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.
precondition_send_content_none [adversarial]: args with send_content="x" → AssertionError before run() (PRE-001 catches the misuse)
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 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
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:
args: ParsedArgs # passed in __init__
session_id: str | None # set in on_mount (after create_session if --new)
agent_id: str | None # set in on_mount
client: httpx.AsyncClient | None # opened in on_mount, closed in on_unmount
session_id: str # passed in __init__ (pre-resolved by _resolve_then_run; issue #6)
agent_id: str | None # passed in __init__ (may be None for --session without --agent; INV-002 carve-out)
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
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
@@ -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(HINT_IDLE, id="hint") # INV-003: visible Ctrl-C state hint; updated on state transitions
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.
```
```contract
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".
PRE: [PRE-001 hard] self.client is None (on_mount fires once per app instance) -- assert self.client is None
POST: [POST-001 state_change] self.client is an open httpx.AsyncClient bound to args.server_url with the Bearer auth header
POST: [POST-002 state_change] self.session_id is non-empty (either from args.session_id or from a successful create_session)
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-004 side_effect] Footer subtitle shows `<agent_id> · …<session_id[-8:]>` (INV-002 session-identity-always-visible)
POST: [POST-005 state_change] self.state == "idle"; the footer hint widget shows "Ctrl-C twice to exit"
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 not None (set in __init__ from _resolve_then_run; issue #6 INV-003) -- assert self.client is not None
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-001 side_effect] Footer subtitle shows `<agent_id> · …<session_id[-8:]>` (INV-002 session-identity-always-visible)
POST: [POST-002 side_effect] The #identity Static widget renders the same identity string
POST: [POST-003 state_change] self.state == "idle"; the #hint Static widget shows "Ctrl-C twice to exit"
ERROR_ROUTING:
AgentNotFound (from create_session):
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
(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)
STEPS:
1. [setup, flexibility=prescriptive] Validate PRE-001
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)
3. [branch, flexibility=prescriptive] IF args.new:
TRY: info = await create_session(self.client, args.agent_id)
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"
1. [setup, flexibility=prescriptive] Validate PRE-001..PRE-002
2. [sequential, flexibility=prescriptive] Compute identity: agent_slot = self.agent_id or "<unknown>"; identity = f"{agent_slot} · …{self.session_id[-8:]}"
3. [sequential, flexibility=prescriptive] Populate widgets: self.sub_title = identity (Header subtitle mirror); self.query_one("#identity", Static).update(identity)
4. [sequential, flexibility=prescriptive] SET self.state = "idle"; update #hint widget to HINT_IDLE ("Ctrl-C twice to exit")
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_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"
agent_not_found_on_mount [error]: --new; POST /sessions → 404 → app exits 12; RichLog contains "[agent_not_found]"
session_api_failed_on_mount [error]: --new; POST /sessions → 500 → app exits 20; RichLog contains "[session_api_failed]"
network_error_on_mount [error]: --new; POST /sessions raises httpx.ConnectError → app exits 21; RichLog contains "[network_error]"
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
client_open_after_mount [trace]: post-mount self.client is not None and is_closed is False
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]: 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)
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.
# Error tests moved to the _resolve_then_run TESTS block per issue #6:
# agent_not_found_on_mount → agent_not_found_on_resolve (capsys stderr)
# 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
```
```contract
@@ -394,14 +430,16 @@ TESTS:
```contract
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)
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:
1. [branch, flexibility=prescriptive] IF self.client is not None AND NOT self.client.is_closed:
await self.client.aclose()
1. [sequential, flexibility=prescriptive] return None
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
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
_Last updated: 2026-05-22_
_Last updated: 2026-05-23_
This file captures durable intent and supporting evidence (goals, decisions,
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
_As of 2026-05-21:_
_As of 2026-05-23 (end of day):_
**Status: v0 milestone + issue #7 (mid-stream robustness) landed.** Four
core issues complete end-to-end (`sse_client` #1, `sessions` #2, `cli`
#3, `tui` #4) + one robustness fix on top: `MalformedSseData` exception
+ empty-data skip in `_iter_events` (issue #7, fixes mid-stream
JSONDecodeError crash discovered during long TUI conversations).
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.
**Status: issues #5 + #6 + worldtree-dev consumer-API follow-up all
landed.** Six core issues complete (`sse_client` #1, `sessions` #2,
`cli` #3, `tui` #4, `--end-user-id` #5, TUI startup error visibility
#6) + robustness fix #7 (MalformedSseData + empty-skip).
188/188 tests GREEN; ruff clean.
`--send` validated end-to-end against personal Worldtree
(`http://10.250.50.152:8081`, mimir on qwen3.6-35-a3b). Smoke key in
gitignored `env.sh` (delivered by infra-ops 2026-05-21; see
[[personal-worldtree-smoke-target]] in auto-memory). Long-conversation
smoke 2026-05-22 (3193-token completion, 374980-token context, 50s
streaming) confirmed empty-data frames are silently skipped — the
original 2026-05-22 crash unreproducible after fix.
(`http://10.250.50.152:8081`, mimir on qwen3.6-35-a3b). Lofn smoke
parked on infra-ops's `agents.call:lofn` scope add (althing thread
`01KSBBHDWVZZ…`; infra-ops brokering to worldtree-dev because personal
Worldtree exposes no public scope-mutation endpoint).
**In-flight: issue #5 (`--end-user-id` flag for per-user agents like
lofn).** Contract drafted + parked (untracked at
`docs/contracts/issues/5.contract.md`); Volva paraphrase + TDD + smoke
pending. Issue #6 (TUI startup error visibility) also filed but
unscaffolded. Branch: `main` (clean apart from #5 contract). Remote:
**In-flight:**
- **Lofn smoke** — blocked on the scope-add. Once infra-ops confirms
`agents.call:lofn` is live, run `ratatoskr --new --agent lofn
--end-user-id ratatoskr-tui --send "hello"` for end-to-end
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`.
**Next natural moves:**
1. **Resume issue #5 cadence** — `--end-user-id` flag for per-user agents
(lofn). Contract drafted + parked; next steps: Volva paraphrase, TDD,
smoke against lofn. Unblocks the Persona/Vili agent family.
2. **Issue #6 (TUI startup error visibility)** — filed, unscaffolded.
Restructure: move session-create out of `on_mount` into `run_tui`
pre-App.run() so errors print to real stderr (not the alt-screen that
tears down before user can read them). Independent of #5.
3. **TUI smoke (operator-side)** — `source env.sh && uv run ratatoskr
--new --agent mimir` from an interactive terminal. Validates Textual
app lifecycle + post-Done markdown re-render end-to-end. Needs a TTY
which CC sessions don't have.
4. **Side-pane issues** — design-brief §5 lists 5 side panes (Persona,
Tools, AdminEvents, BifrostState, ServerLog). Persona is the natural
first (file-tail of `persona.log`).
5. **Recorded SSE snapshot fixtures** from a running Worldtree.
`--send --new > fixture` IS the recording probe.
1. **Mimir regression smoke (operator-side)** — `source env.sh && uv
run ratatoskr --new --agent mimir --send "test"` (and the
`--send`-less TUI form) to verify backwards compat holds after
issues #5 + #6 land. env.sh now ships
`RATATOSKR_END_USER_ID="ratatoskr-tui"`.
2. **Lofn smoke** — when infra-ops confirms scope-add.
3. **Issue #8 (startup agent picker)** — scaffold + contract, then
TDD. Unblocked by both #5 (end_user_id wired through
`_resolve_then_run`) and worldtree-dev's auth confirmation for
`GET /agents`.
4. **Side-pane issues** — Persona pane first (file-tail, cheap).
5. **Issue #9 (spec-pin refresh)** — defer until we actually need a
v0.20.0+ capability, OR refresh now if doc-debt is bothering us.
## 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]` **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]` **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-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)._
@@ -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]` **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-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.
pyproject.toml
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "ratatoskr"
version = "0.0.0"
version = "0.1.0"
description = "Worldtree Conversation API debug TUI — multi-pane observability dashboard"
readme = "README.md"
requires-python = ">=3.12"
src/ratatoskr/cli.py
+40 -2
View File
@@ -11,6 +11,7 @@ import os
import signal
import sys
from dataclasses import dataclass
from importlib.metadata import PackageNotFoundError, version
from typing import TextIO
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):
"""Raised on argument violations; mapped to exit code 10 by main()."""
@@ -59,6 +78,9 @@ class ParsedArgs:
api_key: str
server_url: str
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):
@@ -83,6 +105,8 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
parser.add_argument("--api-key", dest="api_key")
parser.add_argument("--server")
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:
ns = parser.parse_args(argv)
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.
if ns.send is not None and not ns.send:
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:
raise UsageError("--session and --new are mutually exclusive; pass exactly one")
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)")
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(
send_content=ns.send,
@@ -114,6 +146,7 @@ def _parse_args(argv: list[str] | None) -> ParsedArgs:
api_key=api_key,
server_url=server_url,
raw=ns.raw,
end_user_id=end_user_id,
)
@@ -266,7 +299,10 @@ async def _amain(args: ParsedArgs) -> int:
assert isinstance(args, ParsedArgs)
async with httpx.AsyncClient(
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.
# Default 5s read timeout would kill mid-stream; disable it.
# connect/write/pool keep modest timeouts so true network failures
@@ -276,7 +312,9 @@ async def _amain(args: ParsedArgs) -> int:
if args.new:
assert args.agent_id is not None
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:
sys.stderr.write(f"[agent_not_found] agent_id={exc.agent_id}\n")
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"))
async def create_session(client: httpx.AsyncClient, agent_id: str) -> SessionInfo:
"""POST /sessions to create a new session. See contract FN create_session."""
async def 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 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:
raise AgentNotFound(agent_id=agent_id)
if resp.status_code != 201:
src/ratatoskr/tui.py
+80 -44
View File
@@ -1,10 +1,15 @@
"""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
import asyncio
import sys
from typing import ClassVar, Literal
import httpx
@@ -12,7 +17,7 @@ from textual.app import App, ComposeResult
from textual.binding import Binding
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.sse_client import (
CancelAlreadyCompleted,
@@ -88,12 +93,19 @@ class RatatoskrApp(App[int]):
HINT_STREAMING = "Ctrl-C to cancel"
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__()
self.args = args
self.session_id: str | None = None
self.agent_id: str | None = None
self.client: httpx.AsyncClient | None = None
self.session_id: str = session_id
self.agent_id: str | None = agent_id
self.client: httpx.AsyncClient = client
self.state: Literal["idle", "streaming", "cancelling"] = "idle"
self.active_turn_id: int | None = None
self.stream_worker = None
@@ -116,39 +128,12 @@ class RatatoskrApp(App[int]):
yield Footer()
async def on_mount(self) -> None:
"""Open AsyncClient, mint or attach session, populate footer with identity."""
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
"""Populate identity widget from pre-resolved state; set idle hint.
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>"
identity = f"{agent_slot} · …{self.session_id[-8:]}"
self.sub_title = identity # mirror to Header subtitle for redundancy
@@ -222,9 +207,8 @@ class RatatoskrApp(App[int]):
self._set_hint(self.HINT_IDLE)
async def on_unmount(self) -> None:
"""Close the httpx.AsyncClient cleanly."""
if self.client is not None and not self.client.is_closed:
await self.client.aclose()
"""No-op — client lifetime is managed by run_tui's async-with (INV-002)."""
return None
def action_interrupt(self) -> None:
"""Two-stage Ctrl-C state machine per INV-003."""
@@ -256,13 +240,65 @@ class RatatoskrApp(App[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)
assert isinstance(args, ParsedArgs) and args.send_content is None
# PRE-002: Exactly one of session_id / new must be set (xor)
assert bool(args.session_id) != bool(args.new)
app = RatatoskrApp(args)
return app.run() or 0
return asyncio.run(_resolve_then_run(args))
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(
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."""
monkeypatch.delenv("WORLDTREE_API_KEY", raising=False)
monkeypatch.delenv("WORLDTREE_API_URL", raising=False)
monkeypatch.delenv("RATATOSKR_END_USER_ID", raising=False)
class TestParseArgs:
@@ -196,6 +197,42 @@ class TestParseArgs:
with pytest.raises(UsageError):
_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)
@@ -817,6 +854,16 @@ _PARSED_NEW = ParsedArgs(
server_url="https://w.example",
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(
send_content="hi",
session_id="s-1",
@@ -837,6 +884,27 @@ _CREATE_OK_RESP = {
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
async def test_happy_new_session_then_stream(self, capsys: pytest.CaptureFixture[str]) -> None:
"""happy_new_session_then_stream [happy,tracer]: …"""
tests/test_sessions.py
+62
View File
@@ -137,6 +137,68 @@ class TestCreateSession:
await create_session(client, "")
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(
*,
tests/test_tui.py
+397 -114
View File
@@ -74,6 +74,32 @@ def _spy_writes(monkeypatch) -> list:
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)
@@ -228,13 +254,16 @@ class TestCancelViaSse:
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:
"""happy_new_session_mount [happy,tracer]: …"""
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
app = RatatoskrApp(_args_new())
"""happy_new_session_mount [happy,tracer]: identity populated from pre-resolved state."""
app = _resolved_app(_args_new(), session_id="s-new12345", agent_id="mimir")
async with app.run_test() as pilot:
await pilot.pause()
assert app.session_id == "s-new12345"
@@ -244,74 +273,22 @@ class TestAppMount:
assert "mimir" 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:
"""happy_existing_session_mount: …"""
sessions_route = respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
app = RatatoskrApp(_args_existing(session_id="s-existing-tail8x"))
"""happy_existing_session_mount: identity shows <unknown> when agent_id is None."""
app = _resolved_app(_args_existing(session_id="s-existing-tail8x"))
async with app.run_test() as pilot:
await pilot.pause()
assert app.session_id == "s-existing-tail8x"
assert app.state == "idle"
assert sessions_route.call_count == 0
# INV-002 carve-out: agent unknown → <unknown> · …<tail>
assert "<unknown>" 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:
"""footer_identity_visible_first_frame [trace]: …"""
"""footer_identity_visible_first_frame [trace]: identity widget rendered first frame."""
from textual.widgets import Static
respx.post("https://w.example/sessions").mock(
return_value=httpx.Response(201, json=_CREATE_OK_RESP)
)
app = RatatoskrApp(_args_new())
app = _resolved_app(_args_new(), session_id="s-new12345", agent_id="mimir")
async with app.run_test() as pilot:
await pilot.pause()
identity_widget = app.query_one("#identity", Static)
@@ -320,32 +297,6 @@ class TestAppMount:
assert "·" 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
@@ -365,7 +316,7 @@ class TestOnInputSubmitted:
"""happy_submit_echoes_and_spawns [happy,tracer]: …"""
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
inp = app.query_one("#prompt", Input)
@@ -383,15 +334,19 @@ class TestOnInputSubmitted:
) -> None:
"""empty_submit_no_op [trace]: '' + Enter → no change; no worker spawned."""
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
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.value = ""
await inp.action_submit()
await pilot.pause()
assert app.state == "idle"
assert app.stream_worker is None
# POST: no RichLog write fires on empty submit
assert writes == []
@respx.mock
async def test_submit_during_streaming_shows_busy_notice(
@@ -400,7 +355,7 @@ class TestOnInputSubmitted:
"""submit_during_streaming_shows_busy_notice [adversarial]: …"""
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
inp = app.query_one("#prompt", Input)
@@ -427,16 +382,21 @@ class TestOnInputSubmitted:
"""submit_during_cancelling_shows_busy_notice [adversarial]: …"""
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
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.value = "x"
await inp.action_submit()
await pilot.pause()
assert any("[busy]" in str(w) for w in writes)
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
async def test_footer_hint_flips_to_cancel(
@@ -446,7 +406,7 @@ class TestOnInputSubmitted:
from textual.widgets import Static
monkeypatch.setattr(RatatoskrApp, "_stream_turn_worker", _noop_worker)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
hint_widget = app.query_one("#hint", Static)
@@ -528,7 +488,7 @@ class TestStreamTurnWorker:
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
await _submit_and_wait(app, pilot, "hi")
@@ -536,9 +496,12 @@ class TestStreamTurnWorker:
# Streamed delta + done label + rule + markdown render
assert any(w == "hello" 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.rule import Rule
assert any(isinstance(w, Markdown) for w in writes)
assert any(isinstance(w, Rule) for w in writes)
@respx.mock
async def test_raw_flag_skips_markdown_render(
@@ -558,12 +521,15 @@ class TestStreamTurnWorker:
).mock(return_value=_sse_resp(stream))
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing(raw=True))
app = _resolved_app(_args_existing(raw=True))
async with app.run_test() as pilot:
await pilot.pause()
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.rule import Rule
assert not any(isinstance(w, Markdown) for w in writes)
assert not any(isinstance(w, Rule) for w in writes)
@respx.mock
async def test_error_terminal_returns_to_idle(
@@ -591,7 +557,7 @@ class TestStreamTurnWorker:
).mock(return_value=_sse_resp(stream))
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
await _submit_and_wait(app, pilot, "x")
@@ -616,7 +582,7 @@ class TestStreamTurnWorker:
).mock(return_value=_sse_resp(stream))
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
await _submit_and_wait(app, pilot, "x")
@@ -645,7 +611,7 @@ class TestStreamTurnWorker:
return_value=_sse_resp(_GatedAfterFirst())
)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
inp = app.query_one("#prompt", Input)
@@ -673,7 +639,7 @@ class TestStreamTurnWorker:
return_value=httpx.Response(404, json={"error": "session_not_found"})
)
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
await _submit_and_wait(app, pilot, "x")
@@ -699,7 +665,7 @@ class TestStreamTurnWorker:
return_value=_sse_resp(_DropAfter())
)
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
await _submit_and_wait(app, pilot, "x")
@@ -719,7 +685,7 @@ class TestStreamTurnWorker:
"https://w.example/sessions/s-1existing/messages"
).mock(return_value=_sse_resp(stream))
writes = _spy_writes(monkeypatch)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
await _submit_and_wait(app, pilot, "x")
@@ -756,7 +722,7 @@ class TestStreamTurnWorker:
return original(event, log=log, raw=raw)
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:
await pilot.pause()
await _submit_and_wait(app, pilot, "x")
@@ -767,7 +733,7 @@ class TestActionInterrupt:
@respx.mock
async def test_idle_ctrl_c_exits_zero(self) -> None:
"""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:
await pilot.pause()
assert app.state == "idle"
@@ -805,7 +771,7 @@ class TestActionInterrupt:
side_effect=cancel_handler
)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
inp = app.query_one("#prompt", Input)
@@ -858,7 +824,7 @@ class TestActionInterrupt:
return_value=_sse_resp(_NeverYields())
)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
inp = app.query_one("#prompt", Input)
@@ -867,22 +833,54 @@ class TestActionInterrupt:
await pilot.pause()
assert app.state == "streaming"
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.pause()
gate.set() # let the gated stream resolve so teardown is clean
assert app.return_value == 3
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
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]: …"""
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:
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
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.pause()
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
async def test_cancel_failed_swallowed(self) -> None:
@@ -911,7 +909,7 @@ class TestActionInterrupt:
side_effect=cancel_handler
)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
inp = app.query_one("#prompt", Input)
@@ -940,7 +938,7 @@ class TestActionQuit:
@respx.mock
async def test_idle_ctrl_d_exits_zero(self) -> None:
"""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:
await pilot.pause()
await pilot.press("ctrl+d")
@@ -969,7 +967,7 @@ class TestActionQuit:
respx.post("https://w.example/sessions/s-1existing/messages").mock(
return_value=_sse_resp(_GatedAfterFirst())
)
app = RatatoskrApp(_args_existing())
app = _resolved_app(_args_existing())
async with app.run_test() as pilot:
await pilot.pause()
inp = app.query_one("#prompt", Input)
@@ -980,26 +978,311 @@ class TestActionQuit:
if app.active_turn_id == 42:
break
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.pause()
gate.set()
assert app.return_value == 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
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:
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] = []
def fake_run(self) -> int:
async def fake_run_async(self, *a, **kw):
captured.append(self.args)
return 0
monkeypatch.setattr(RatatoskrApp, "run", fake_run)
monkeypatch.setattr(RatatoskrApp, "run_async", fake_run_async)
rc = run_tui(_args_existing())
assert rc == 0
assert len(captured) == 1
uv.lock
Generated
+1 -1
View File
@@ -968,7 +968,7 @@ wheels = [
[[package]]
name = "ratatoskr"
version = "0.0.0"
version = "0.1.0"
source = { editable = "." }
dependencies = [
{ name = "httpx" },