uro-cli 0.6.0__tar.gz → 0.8.0__tar.gz

{uro_cli-0.6.0 → uro_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: uro-cli
-Version: 0.6.0
+Version: 0.8.0
 Summary: Uro Engine reference client — play, dry-run, and dev tools against the engine
 Project-URL: Homepage, https://github.com/cupskeee/uro
 Project-URL: Repository, https://github.com/cupskeee/uro
@@ -12,8 +12,8 @@ Requires-Python: >=3.12
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: rich>=13.9
 Requires-Dist: typer>=0.27.2
-Requires-Dist: uro-core[llm,postgres]==0.6.0
-Requires-Dist: uro-server==0.6.0
+Requires-Dist: uro-core[llm,postgres]==0.8.0
+Requires-Dist: uro-server==0.8.0
 Requires-Dist: websockets>=16.1
 Description-Content-Type: text/markdown
 

{uro_cli-0.6.0 → uro_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uro-cli"
-version = "0.6.0"
+version = "0.8.0"
 description = "Uro Engine reference client — play, dry-run, and dev tools against the engine"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -13,8 +13,8 @@ requires-python = ">=3.12"
 # pair a new uro-cli with an old uro-core; `just release` bumps all three together, and the
 # `{workspace = true}` sources make a drifted pin fail `uv sync` locally.
 dependencies = [
-    "uro-core[postgres,llm]==0.6.0",
-    "uro-server==0.6.0",
+    "uro-core[postgres,llm]==0.8.0",
+    "uro-server==0.8.0",
     "typer>=0.27.2",
     "rich>=13.9",
     "websockets>=16.1",

uro_cli-0.8.0/tests/test_connect.py

@@ -0,0 +1,133 @@
+"""`uro connect`, the reference play client, against a real server on a local port.
+
+Its prompt used to come back the moment an intent was sent: it sat above the streaming narration,
+and nothing was on screen while the beat was still being extracted and committed, so a player in
+the first live run (2026-10-31) retyped an intent and played it twice.
+"""
+
+import asyncio
+import socket
+import threading
+import time
+from collections.abc import AsyncIterator
+
+import uvicorn
+from typer.testing import CliRunner
+from uro_cli.main import app
+from uro_server.app import ServerDeps, create_app
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return int(s.getsockname()[1])
+
+
+def test_the_prompt_waits_for_each_beat_to_settle() -> None:
+    started: list[str] = []
+
+    async def run_beat(campaign_id: str, participant: str, text: str) -> AsyncIterator[str]:
+        started.append(text)
+        for word in ("The ", "tide ", "turns."):
+            await asyncio.sleep(0.05)
+            yield word
+        await asyncio.sleep(0.3)  # extraction: the narration is done, the beat isn't
+
+    async def campaign_exists(campaign_id: str) -> bool:
+        return True
+
+    deps = ServerDeps(
+        resolve_participant={"tok": "player-1"}.get,
+        campaign_exists=campaign_exists,
+        run_beat=run_beat,
+    )
+    port = _free_port()
+    server = uvicorn.Server(
+        uvicorn.Config(create_app(deps), host="127.0.0.1", port=port, log_level="warning")
+    )
+    thread = threading.Thread(target=server.run, daemon=True)
+    thread.start()
+    while not server.started:
+        time.sleep(0.02)
+    try:
+        result = CliRunner().invoke(
+            app,
+            ["connect", "camp-1", "--server", f"http://127.0.0.1:{port}", "--token", "tok"],
+            input="first\nsecond\n/quit\n",  # typed ahead, as an impatient player would
+        )
+    finally:
+        server.should_exit = True
+        thread.join(5)
+    out = result.output
+    assert result.exit_code == 0, out
+    assert started == ["first", "second"]
+    prompts = [i for i in range(len(out)) if out.startswith("> ", i)]
+    first, second = out.index("✓ [player-1] 'first'"), out.index("✓ [player-1] 'second'")
+    assert len(prompts) == 3, out
+    assert first < prompts[1] < second < prompts[2], out  # each prompt only after its beat settled
+
+
+def test_another_players_identical_intent_never_settles_ours() -> None:
+    # Review: the client matched outcomes by intent TEXT. In a party, another player typing the same
+    # words while our beat ran got `not_your_turn`, broadcast to everyone, and released our prompt
+    # mid-beat. Intents now carry an id the server echoes back.
+    import json
+
+    import websockets
+    from uro_core.session import PartyArbiter
+
+    async def run_beat(campaign_id: str, participant: str, text: str) -> AsyncIterator[str]:
+        yield "The "
+        await asyncio.sleep(1.2)
+        yield "end."
+
+    async def campaign_exists(campaign_id: str) -> bool:
+        return True
+
+    deps = ServerDeps(
+        resolve_participant={"tok": "player-1", "tok2": "player-2"}.get,
+        campaign_exists=campaign_exists,
+        run_beat=run_beat,
+    )
+    port = _free_port()
+    server = uvicorn.Server(
+        uvicorn.Config(
+            create_app(deps, arbiter=PartyArbiter()),
+            host="127.0.0.1",
+            port=port,
+            log_level="warning",
+        )
+    )
+    thread = threading.Thread(target=server.run, daemon=True)
+    thread.start()
+    while not server.started:
+        time.sleep(0.02)
+
+    def player_two() -> None:  # joins second (so player-1 holds the turn), same words mid-beat
+        async def go() -> None:
+            await asyncio.sleep(0.3)
+            uri = f"ws://127.0.0.1:{port}/campaigns/c/play?token=tok2"
+            async with websockets.connect(uri) as ws:
+                await asyncio.sleep(0.2)
+                await ws.send(json.dumps({"type": "intent", "text": "look around"}))
+                await asyncio.sleep(1.5)
+
+        asyncio.run(go())
+
+    other = threading.Thread(target=player_two)
+    other.start()
+    try:
+        result = CliRunner().invoke(
+            app,
+            ["connect", "c", "--server", f"http://127.0.0.1:{port}", "--token", "tok"],
+            input="look around\n/quit\n",
+        )
+    finally:
+        other.join()
+        server.should_exit = True
+        thread.join(5)
+    out = result.output
+    assert "not your turn" in out, out  # player-2's identical intent did reach us...
+    ours = out.index("✓ [player-1] 'look around'")  # ...but our prompt waited for OUR beat
+    prompts = [i for i in range(len(out)) if out.startswith("> ", i)]
+    assert len(prompts) == 2 and prompts[1] > ours, out

{uro_cli-0.6.0 → uro_cli-0.8.0}/uro_cli/main.py

@@ -11,7 +11,7 @@ import json
 import sys
 import time
 import webbrowser
-from collections.abc import Awaitable
+from collections.abc import AsyncIterator, Awaitable
 from pathlib import Path
 from typing import Any
 
@@ -24,7 +24,7 @@ from uro_core.providers.router import ProviderRouter
 from uro_core.rulesets import registry
 from uro_core.rulesets.base import CharSpec, Ruleset
 from uro_core.rulesets.rng import Rng
-from uro_core.timeline.models import STARTING_GEAR, World
+from uro_core.timeline.models import FORK_TIME_SKIP, STARTING_GEAR, World
 
 from uro_cli.wiring import (
     build_router,
@@ -88,6 +88,27 @@ _ROLES = tuple(sorted(ROLES))
 PARTICIPANT = "player-1"  # Phase 0 is single-player; participants arrive in Phase 5.
 
 
+@contextlib.asynccontextmanager
+async def _metered(router: ProviderRouter) -> AsyncIterator[ProviderRouter]:
+    """Meter a command's model calls when the database is reachable (D-66). Best effort: `world
+    backfill` and `world probe` work on a pack file alone, so a down database never stops them —
+    their calls just go unrecorded."""
+    store: PostgresEventStore | None = None
+    try:
+        connecting = build_store()
+        await asyncio.wait_for(connect_store(connecting), timeout=5)
+        store = connecting
+    except Exception:
+        pass  # no database: run unmetered
+    if store is not None:
+        router.recorder = store.record_llm_call
+    try:
+        yield router
+    finally:
+        if store is not None:
+            await store.close()
+
+
 def _run_async(coro_factory) -> None:  # type: ignore[no-untyped-def]
     """Run an async command, turning config/credential/lookup errors into a clean message."""
     try:
@@ -278,6 +299,8 @@ def world_create(
             needs_fill = backfill and check_sufficiency(pack).grade != "runnable"
             router = build_router(provider, model) if needs_fill else None
             await connect_store(store)
+            if router is not None:  # the backfill's calls are metered like any other (D-66)
+                router.recorder = store.record_llm_call
             result = await import_pack(store, pack, backfill_router=router)
         except PackError as exc:
             typer.echo(f"error: {exc}", err=True)
@@ -353,7 +376,8 @@ def world_backfill(
         if before.grade == "runnable":
             typer.echo("pack is already runnable — nothing to backfill")
             return
-        augmented, added = await backfill_gaps(pack, build_router(provider, model), report=before)
+        async with _metered(build_router(provider, model)) as router:
+            augmented, added = await backfill_gaps(pack, router, report=before)
         after = check_sufficiency(augmented)
         typer.echo(f"backfill: {before.grade} → {after.grade}")
         for a in added:
@@ -384,7 +408,8 @@ def world_probe(
         except PackError as exc:
             typer.echo(f"error: {exc}", err=True)
             raise typer.Exit(1) from exc
-        report = await run_probes(pack.manifest, build_router(provider, model), tries=tries)
+        async with _metered(build_router(provider, model)) as router:
+            report = await run_probes(pack.manifest, router, tries=tries)
         typer.echo(f"probe report for {report.world}: {'OK' if report.ok else 'ISSUES'}")
         for r in report.results:
             gate = f"  (gates {r.gate_for})" if r.gate_for else ""
@@ -552,6 +577,13 @@ def serve(
         "(consensus). UNSET = auto (solo for 1 token, party for >1). Setting it EXPLICITLY binds "
         "that shape even for a 1-token launch, so a runtime-added player still gets turns (D-39).",
     ),
+    nats_url: str = typer.Option(
+        None,
+        "--nats",
+        help="push every commit — from any process — to WebSocket clients live, via the NATS "
+        "subjects `uro outbox relay` publishes to (D-67)",
+    ),
+    subject_prefix: str = typer.Option("uro", "--subject-prefix", help="the relay's prefix"),
     cors_origin: list[str] = typer.Option(  # noqa: B008
         None,
         "--cors-origin",
@@ -616,18 +648,29 @@ def serve(
     else:
         arbiter = shapes[arbiter_kind]()
     deps = engine_deps(store, engine, tokens, admin_tokens, router=router)
-    fastapi_app = create_app(deps, arbiter=arbiter, cors_origins=cors_origin or None)
+    commit_feed = None
+    if nats_url:
+        from uro_core.adapters.nats import NatsCommitFeed
+
+        commit_feed = NatsCommitFeed(nats_url, subject_prefix=subject_prefix)
 
-    @fastapi_app.on_event("startup")
     async def _startup() -> None:
         await connect_store(store)
         if deps.hydrate_tokens is not None:  # load durable runtime tokens (D-39) — AFTER connect
             await deps.hydrate_tokens()
 
-    @fastapi_app.on_event("shutdown")
     async def _shutdown() -> None:
         await store.close()
 
+    fastapi_app = create_app(
+        deps,
+        arbiter=arbiter,
+        cors_origins=cors_origin or None,
+        commit_feed=commit_feed,
+        startup=_startup,
+        shutdown=_shutdown,
+    )
+
     # (The DB preflight is folded into _resolve_router above — its connect_store gives the same
     # clean docker-first hint on a down DB, and the pool it opens is closed before uvicorn starts;
     # the startup hook re-opens one on uvicorn's own loop.)
@@ -641,6 +684,8 @@ def serve(
         typer.echo(f"  token {t!r} → {p}")
     if cors_origin:
         typer.echo(f"  CORS: allowing {', '.join(cors_origin)}")
+    if nats_url:
+        typer.echo(f"  live commits: {nats_url} ({subject_prefix}.>) — run `uro outbox relay` too")
     uvicorn.run(fastapi_app, host=host, port=port, log_level="warning")
 
 
@@ -656,6 +701,7 @@ def connect(
     the campaign stream in live."""
     import asyncio
     import json
+    import uuid
 
     import websockets
 
@@ -666,11 +712,44 @@ def connect(
         try:
             async with websockets.connect(uri) as ws:
                 typer.echo(f"connected to {campaign_id} as {token!r}. Type an action; /quit.\n")
+                # An intent's beat is SETTLED by one of these, each echoing the intent's text. The
+                # prompt waits for it: shown at once, it sat above the streaming narration and was
+                # gone by the time the beat committed (extraction runs after the narration), so a
+                # player retyped the intent and played it twice (live run, 2026-10-31).
+                settles = {
+                    "beat_committed",
+                    "beat_failed",
+                    "not_your_turn",
+                    "proposal_opened",
+                    "intent_rejected",
+                }
+                # intent id → (its text, set when it settles). The server echoes the id as
+                # `intent_id`, so another player's identical text never settles ours. Only a server
+                # that has never echoed one (an older one) is matched by text; once one has, a frame
+                # without an id is another client's.
+                pending: dict[str, tuple[str, asyncio.Event]] = {}
+                echoes = False
+
+                def settle(msg: dict[str, Any]) -> None:
+                    if "intent_id" in msg:
+                        hit = pending.pop(str(msg["intent_id"]), None)
+                    elif not echoes:
+                        text = str(msg.get("intent", msg.get("text", "")))
+                        rid = next((k for k, (t, _) in pending.items() if t == text), None)
+                        hit = pending.pop(rid) if rid is not None else None
+                    else:
+                        hit = None
+                    if hit is not None:
+                        hit[1].set()
 
                 async def receive() -> None:
+                    nonlocal echoes
                     async for raw in ws:
                         msg = json.loads(raw)
                         kind = msg.get("type")
+                        echoes = echoes or "intent_id" in msg
+                        if kind in settles:
+                            settle(msg)
                         if kind == "narration_chunk":
                             typer.echo(msg["text"], nl=False)
                         elif kind == "beat_committed":
@@ -699,6 +778,15 @@ def connect(
                             )
                         elif kind == "beat_failed":
                             typer.echo(f"\n  ✗ beat failed: {msg['error']}")
+                        elif kind == "intent_rejected":
+                            typer.echo(
+                                f"  ✗ [{msg['participant_id']}] intent rejected: {msg['text']!r}"
+                            )
+                        elif kind == "commit":  # made elsewhere: another server, the CLI (D-67)
+                            for beat in msg.get("beats") or []:
+                                typer.echo(f"\n[{beat['participant_id']}] {beat['narration']}")
+                            if not msg.get("beats"):
+                                typer.echo("\n  · the world changed (no new narration)")
                         elif kind in ("participant_joined", "participant_left"):
                             typer.echo(f"  · {msg['participant_id']} {kind.split('_')[1]}")
 
@@ -713,7 +801,20 @@ def connect(
                     elif intent.startswith("/vote "):  # non-canon consensus vote (D-38)
                         await ws.send(json.dumps({"type": "vote", "choice": intent[6:]}))
                     elif intent:
-                        await ws.send(json.dumps({"type": "intent", "text": intent}))
+                        rid = uuid.uuid4().hex
+                        settled = asyncio.Event()
+                        pending[rid] = (intent, settled)
+                        await ws.send(json.dumps({"type": "intent", "text": intent, "id": rid}))
+                        waiting = asyncio.ensure_future(settled.wait())
+                        # a slow beat (a reasoning model's extraction) still settles well inside
+                        # this; past it — or if the server goes away — the prompt comes back anyway
+                        await asyncio.wait(
+                            {waiting, receiver}, timeout=600, return_when=asyncio.FIRST_COMPLETED
+                        )
+                        waiting.cancel()
+                        pending.pop(rid, None)
+                        if receiver.done():  # the server closed the connection
+                            break
                 receiver.cancel()
         except OSError as exc:
             typer.echo(f"could not connect to {server}: {exc} (is `uro serve` running?)", err=True)
@@ -918,7 +1019,7 @@ def branch_fork(
                 pick = registry.resolve_for_branch(store, branch.branch_id)
                 ruleset = await _time_skip_ruleset(pick)
                 engine = Engine(store, build_router("stub", None), ruleset=ruleset)
-                await engine.agenda_tick(branch.branch_id, time_skip_days)
+                await engine.agenda_tick(branch.branch_id, time_skip_days, reason=FORK_TIME_SKIP)
         finally:
             await store.close()
         forked = branch.forked_from if branch.forked_from else "-"
@@ -1174,15 +1275,29 @@ def chronicle(
     _run_async(_run)
 
 
+async def _call_scope(
+    store: PostgresEventStore, world: str | None, campaign: str | None
+) -> tuple[str | None, list[str] | None]:
+    """--world / --campaign → (world_id, branch_ids); a campaign's calls are its branch's (D-66)."""
+    world_id = (await _world_or_exit(store, world)).world_id if world else None
+    branch_ids = [(await _campaign_or_exit(store, campaign)).branch_id] if campaign else None
+    return world_id, branch_ids
+
+
 @app.command()
-def usage(stage: str = typer.Option(None, "--stage", help="only this pipeline stage")) -> None:
-    """LLM-call telemetry by stage: calls, models, tokens (0 until metered), average latency."""
+def usage(
+    stage: str = typer.Option(None, "--stage", help="only this pipeline stage"),
+    world: str = typer.Option(None, "--world", help="only calls that served this world"),
+    campaign: str = typer.Option(None, "--campaign", help="only calls on this campaign's branch"),
+) -> None:
+    """LLM-call telemetry by stage: calls, models, token counts, average latency (D-66)."""
 
     async def _run() -> None:
         store = build_store()
         await connect_store(store)
         try:
-            rows = await store.usage_by_stage(stage)
+            world_id, branch_ids = await _call_scope(store, world, campaign)
+            rows = await store.usage_by_stage(stage, world_id=world_id, branch_ids=branch_ids)
         finally:
             await store.close()
         typer.echo(f"total calls: {sum(int(r['calls']) for r in rows)}")
@@ -1192,6 +1307,41 @@ def usage(stage: str = typer.Option(None, "--stage", help="only this pipeline st
     _run_async(_run)
 
 
+@app.command()
+def calls(
+    stage: str = typer.Option(None, "--stage", help="e.g. extractor, planner"),
+    world: str = typer.Option(None, "--world", help="only calls that served this world"),
+    campaign: str = typer.Option(None, "--campaign", help="only calls on this campaign's branch"),
+    limit: int = typer.Option(5, "--limit", min=1, max=200, help="how many, newest first"),
+) -> None:
+    """Recent LLM calls with what each structured one returned (D-66) — e.g. the extractor's raw
+    JSON for a beat that committed less than its narration said."""
+
+    async def _run() -> None:
+        store = build_store()
+        await connect_store(store)
+        try:
+            world_id, branch_ids = await _call_scope(store, world, campaign)
+            rows = await store.recent_llm_calls(
+                stage=stage, world_id=world_id, branch_ids=branch_ids, limit=limit
+            )
+        finally:
+            await store.close()
+        if not rows:
+            typer.echo("(no metered calls)")
+        for r in rows:
+            tokens = f"{r['tokens_in'] or '?'}→{r['tokens_out'] or '?'} tokens"
+            typer.echo(
+                f"{r['created_at']:%Y-%m-%d %H:%M:%S}  {r['stage_tag']:<10} {r['model'] or '-'}  "
+                f"{tokens}  {r['latency_ms']}ms"
+                + (f"  FAILED: {r['error']}" if r.get("error") else "")
+            )
+            if r["response"] is not None:
+                typer.echo(f"  {r['response']}")
+
+    _run_async(_run)
+
+
 @ruleset_app.command("list")
 def ruleset_list() -> None:
     """The rulesets a world can declare (`[ruleset] id` in world.toml): the built-ins and installed