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:
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
Reference in New Issue
Block a user