zu-cli 0.1.0__py3-none-any.whl

zu_cli/scaffold.py

@@ -0,0 +1,116 @@
+"""Project scaffolding — the starter `agent.yaml` behind `zu init` and the MCP
+`zu_scaffold` tool. One source of truth so the CLI and the coding-agent
+integration always write the same thing.
+
+A template is a single self-contained `agent.yaml`: the model, the escalation
+ladder (`tiers:` — the tools at each tier, yours or built-in), the checks, and
+the task — what + how in one file. Edit the `provider` block to swap models; drop
+your own tools in a `tools/` dir beside it and list them in `tiers` as
+`tools.my_module:MyTool`.
+"""
+
+from __future__ import annotations
+
+import os
+
+_PROVIDER = (
+    "provider:\n"
+    "  name: anthropic                 # scripted | anthropic | openai-compatible | <module:Class>\n"
+    "  model: claude-sonnet-4-6\n"
+    "  api_key_env: ANTHROPIC_API_KEY  # the env var NAME — never the key itself\n"
+)
+_SINK = "event_sink: { driver: sqlite, path: ./zu.db }\n"
+_BUDGET = "budget: { max_steps: 20, max_tokens: 200000, wall_time_s: 120 }\n"
+
+# A tier-1/2 web-extraction agent: fetch, fall back to a browser on JS, validate.
+_WEB = (
+    _PROVIDER
+    + "tiers:                            # the escalation ladder — tools at each tier\n"
+    "  1: [http_fetch, html_parse]     # cheap: fetch + parse (your own tools go here too)\n"
+    "  2: [render_dom]                 # escalate to a real browser when a detector says so\n"
+    "plugins:\n"
+    "  detectors: [empty, error, js-shell, bot-wall]   # what makes a tier give up\n"
+    "  validators: [schema, grounding]\n"
+    + _SINK
+    + _BUDGET
+    + "task:\n"
+    "  query: \"Extract the product name and price.\"\n"
+    "  target: \"https://example.com/product/123\"\n"
+    "  max_tier: 2\n"
+    "  output_schema:\n"
+    "    type: object\n"
+    "    properties:\n"
+    "      name: { type: string }\n"
+    "      price: { type: string }\n"
+    "    required: [name, price]\n"
+)
+
+# The smallest agent: a model answers, schema-validated. No tools, no network.
+_MINIMAL = (
+    _PROVIDER
+    + "plugins:\n  validators: [schema]\n"
+    + _SINK
+    + "task:\n"
+    "  query: \"Answer the question as JSON: {\\\"answer\\\": ...}.\"\n"
+    "  output_schema:\n"
+    "    type: object\n"
+    "    properties: { answer: { type: string } }\n"
+    "    required: [answer]\n"
+)
+
+# A web-research agent: extract several fields from an article page.
+_RESEARCH = (
+    _PROVIDER
+    + "tiers:\n"
+    "  1: [http_fetch, html_parse]\n"
+    "  2: [render_dom]\n"
+    "plugins:\n"
+    "  detectors: [empty, error, js-shell, bot-wall]\n"
+    "  validators: [schema, grounding]\n"
+    + _SINK
+    + _BUDGET
+    + "task:\n"
+    "  query: \"Extract the article's title, author, and publication date.\"\n"
+    "  target: \"https://example.com/article\"\n"
+    "  max_tier: 2\n"
+    "  output_schema:\n"
+    "    type: object\n"
+    "    properties:\n"
+    "      title: { type: string }\n"
+    "      author: { type: string }\n"
+    "      published: { type: string }\n"
+    "    required: [title]\n"
+)
+
+TEMPLATES: dict[str, dict[str, str]] = {
+    "web": {"agent.yaml": _WEB},
+    "minimal": {"agent.yaml": _MINIMAL},
+    "research": {"agent.yaml": _RESEARCH},
+}
+
+TEMPLATE_NAMES = tuple(TEMPLATES)
+
+
+def render(template: str) -> dict[str, str]:
+    """The ``{filename: content}`` map for a template. Raises KeyError if unknown."""
+    return dict(TEMPLATES[template])
+
+
+def write_template(directory: str, template: str, *, force: bool = False) -> list[str]:
+    """Write a template's files into ``directory``. Refuses to overwrite an
+    existing file unless ``force`` (so a stray `zu init` never clobbers work).
+    Returns the paths written. Raises KeyError (unknown template) or
+    FileExistsError (a target exists and not force)."""
+    files = render(template)
+    os.makedirs(directory, exist_ok=True)
+    if not force:
+        existing = [n for n in files if os.path.exists(os.path.join(directory, n))]
+        if existing:
+            raise FileExistsError(", ".join(existing))
+    written: list[str] = []
+    for name, content in files.items():
+        path = os.path.join(directory, name)
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(content)
+        written.append(path)
+    return written

zu_cli/server.py

@@ -0,0 +1,363 @@
+"""`zu serve` — a thin HTTP wrapper over the same run path as the CLI, plus a
+live observability dashboard.
+
+Endpoints:
+  POST /run            run a task, return Result (+ events)         — the core API
+  POST /run/stream     run a task, stream the loop live (SSE)
+  GET  /               the live dashboard (HTML)                    — watch production
+  GET  /events         a global live feed of ALL runs (SSE)        — what the UI consumes
+  GET  /review         the defense review queue (blocked attempts)  — triage
+  GET  /healthz        liveness
+
+It is a *wrapper*, not a second code path — it assembles the provider/registry/bus
+from config exactly as ``zu run`` does. Every run tees its events to a broadcast
+hub, so the dashboard sees production traffic as it happens; and every
+``harness.defense.blocked`` event (a contained attack) is queued to a JSONL review
+file so a blocked attempt is never invisible.
+
+FastAPI is an optional dependency (the ``serve`` extra): the import lives inside
+``create_app``. Install it with ``pip install 'zu-runtime[serve]'``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import json
+import os
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from zu_core import events as ev
+from zu_core.loop import run_task
+from zu_core.view import scope_event
+
+from .config import ConfigError, assemble, coerce_config, coerce_task
+from .observe import defense_record
+
+
+class RunRequest(BaseModel):
+    """The POST /run body. Defined at module scope (not inside create_app) so
+    FastAPI can resolve the annotation under ``from __future__ import annotations``."""
+
+    task: dict = Field(..., description="The task spec (query, target, output_schema, ...).")
+    config: dict | None = Field(
+        None, description="Optional per-request config override; omit to use the server default."
+    )
+    include_events: bool = Field(True, description="Return the run's event log alongside the result.")
+
+
+class _Hub:
+    """A tiny in-process pub/sub: every run publishes its events here, and each
+    GET /events client subscribes a bounded queue. Bounded so a slow client is
+    dropped, never able to back up a run (a slow dashboard must not block the
+    agent)."""
+
+    def __init__(self) -> None:
+        self._subscribers: set[asyncio.Queue] = set()
+
+    def publish(self, item: tuple[str, Any]) -> None:
+        for q in list(self._subscribers):
+            try:
+                q.put_nowait(item)
+            except asyncio.QueueFull:
+                pass  # drop for a slow consumer; the canonical log is unaffected
+
+    def subscribe(self) -> asyncio.Queue:
+        q: asyncio.Queue = asyncio.Queue(maxsize=1000)
+        self._subscribers.add(q)
+        return q
+
+    def unsubscribe(self, q: asyncio.Queue) -> None:
+        self._subscribers.discard(q)
+
+
+def create_app(
+    config: Any = None, *, title: str = "Zu",
+    review_queue: str | None = None, view_scope: str | None = None,
+    auth_token: str | None = None,
+) -> Any:
+    """Build the ASGI app. ``config`` is the server's default run config; a request
+    may override it per call. ``review_queue`` (JSONL path for blocked attempts)
+    and ``view_scope`` (``render`` | ``full``) default to the config's
+    ``observability`` block. Fails fast if the default config can't be loaded.
+
+    ``auth_token`` (defaulting to the ``ZU_SERVE_TOKEN`` env var) gates every
+    endpoint except ``/healthz``: when set, a request must present it as an
+    ``Authorization: Bearer <token>`` header — or, for the SSE/dashboard GETs
+    that can't set headers, a ``?token=`` query parameter. When unset the server
+    is open (the localhost-dev default); the ``zu serve`` CLI refuses to bind a
+    non-localhost host without a token so an exposed deploy can't be tokenless."""
+    try:
+        from fastapi import Depends, FastAPI, Header, HTTPException
+        from fastapi.responses import HTMLResponse, StreamingResponse
+    except ModuleNotFoundError as exc:  # pragma: no cover - exercised via message
+        raise RuntimeError(
+            "the HTTP server needs FastAPI; install it with: pip install 'zu-runtime[serve]'"
+        ) from exc
+
+    from .trace import format_event
+
+    required_token = auth_token if auth_token is not None else os.environ.get("ZU_SERVE_TOKEN")
+
+    def require_auth(
+        authorization: str | None = Header(default=None),
+        token: str | None = None,
+    ) -> None:
+        # No token configured -> open (localhost dev). Otherwise require the token
+        # via an ``Authorization: Bearer <token>`` header, or a ``?token=`` query
+        # param for the SSE/dashboard GETs that can't set headers. Applied to every
+        # route except /healthz (liveness must not need a credential).
+        if not required_token:
+            return
+        header = authorization or ""
+        presented = header[7:] if header[:7].lower() == "bearer " else token
+        # Constant-time compare so the bearer token can't be recovered byte-by-byte
+        # via response-timing on a budget-spending endpoint.
+        if presented is None or not hmac.compare_digest(presented, required_token):
+            raise HTTPException(status_code=401, detail="missing or invalid bearer token")
+
+    auth = [Depends(require_auth)]  # applied per protected route below
+
+    default_cfg = coerce_config(config)
+    # Networked surfaces are allowlist-render by default (safe to leave on in
+    # prod); ``full`` shows content for local/authorized viewing.
+    review_path = review_queue if review_queue is not None else default_cfg.observability.review_queue
+    scope_full = (view_scope or default_cfg.observability.scope) == "full"
+    hub = _Hub()
+    review: list[dict] = []  # in-memory view of the review queue (recent first)
+
+    def _append_review(record: dict) -> None:
+        review.insert(0, record)
+        del review[200:]  # keep the in-memory view bounded
+        if not review_path:
+            return
+        try:  # persist for triage; never let queue IO break a run
+            with open(review_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(record, default=str) + "\n")
+        except OSError:
+            pass
+
+    def _tee(event: Any) -> None:
+        """A per-run bus subscriber: fan the event to the dashboard and queue any
+        contained attempt for review."""
+        hub.publish(("event", event))
+        if event.type == ev.DEFENSE_BLOCKED:
+            rec = defense_record(event)
+            _append_review(rec)
+            hub.publish(("defense", rec))
+
+    def sse(kind: str, data: dict) -> str:
+        return f"event: {kind}\ndata: {json.dumps(data, default=str)}\n\n"
+
+    def event_frame(val: Any) -> str:
+        """An SSE 'event' frame — allowlist-rendered unless the scope is full."""
+        return sse("event", {
+            "line": format_event(val, full=scope_full),
+            "event": scope_event(val, full=scope_full),
+        })
+
+    app = FastAPI(title=title, description="Zu — Agent Production Runtime")
+
+    @app.get("/healthz")
+    async def healthz() -> dict:
+        return {"status": "ok"}
+
+    @app.post("/run", dependencies=auth)
+    async def run_endpoint(req: RunRequest) -> dict:
+        try:
+            # A per-request config arrived over the network: it may select
+            # installed, named plugins but NOT name an arbitrary 'module:Attr' to
+            # import (that executes code). The operator's server default is
+            # trusted and keeps the full import door.
+            allow_imports = req.config is None
+            cfg = coerce_config(req.config) if req.config is not None else default_cfg
+            spec = coerce_task(req.task, cfg.budget, allow_paths=False)
+            provider, registry, bus, providers = assemble(cfg, allow_imports=allow_imports)
+        except ConfigError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        bus.subscribe(_tee)  # feed the dashboard + review queue
+
+        try:
+            result = await run_task(spec, provider, registry, bus, providers=providers,
+                                    containment=default_cfg.containment,
+                                    max_observation_chars=default_cfg.max_observation_chars,
+                                    observation_strategy=default_cfg.observation_strategy,
+                                    max_context_chars=default_cfg.max_context_chars)
+            body: dict = {"result": result.model_dump(mode="json")}
+            if req.include_events:
+                events = await bus.query()
+                body["events"] = [e.model_dump(mode="json") for e in events]
+            return body
+        except Exception as exc:  # noqa: BLE001 - a model/infra failure is a 502, not a crash
+            raise HTTPException(status_code=502, detail=f"{type(exc).__name__}: {exc}") from exc
+        finally:
+            # Release the per-request bus's sink (e.g. a sqlite connection) so a
+            # long-lived server doesn't leak one connection per request.
+            await bus.aclose()
+
+    @app.post("/run/stream", dependencies=auth)
+    async def run_stream(req: RunRequest) -> Any:
+        """Run a task and stream the loop live as Server-Sent Events — one
+        ``event`` frame per loop event, then a final ``result`` and ``done``."""
+        try:
+            allow_imports = req.config is None  # see /run: networked config can't import code
+            cfg = coerce_config(req.config) if req.config is not None else default_cfg
+            spec = coerce_task(req.task, cfg.budget, allow_paths=False)
+            provider, registry, bus, providers = assemble(cfg, allow_imports=allow_imports)
+        except ConfigError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+        # Bounded queue with drop-on-full: a slow/disconnected SSE consumer must
+        # never let events accumulate without limit (the same backpressure
+        # posture the global hub takes). The producer is a sync bus subscriber,
+        # so it can only put_nowait — full means drop, never block the run.
+        queue: asyncio.Queue = asyncio.Queue(maxsize=1000)
+
+        def _enqueue(event: Any) -> None:
+            try:
+                queue.put_nowait(("event", event))
+            except asyncio.QueueFull:
+                pass  # slow consumer; the canonical log is unaffected
+
+        bus.subscribe(_enqueue)
+        bus.subscribe(_tee)  # also feed the global dashboard + review queue
+
+        async def runner() -> None:
+            try:
+                result = await run_task(spec, provider, registry, bus, providers=providers,
+                                        containment=default_cfg.containment,
+                                        max_observation_chars=default_cfg.max_observation_chars,
+                                        observation_strategy=default_cfg.observation_strategy,
+                                        max_context_chars=default_cfg.max_context_chars)
+                await queue.put(("result", result))
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001 - report as a stream frame, not a 500
+                await queue.put(("error", exc))
+            finally:
+                await queue.put(("done", None))
+                # Release the per-request bus's sink even if the client vanished.
+                await bus.aclose()
+
+        async def gen() -> Any:
+            task = asyncio.create_task(runner())
+            try:
+                while True:
+                    kind, val = await queue.get()
+                    if kind == "event":
+                        yield event_frame(val)
+                    elif kind == "result":
+                        yield sse("result", val.model_dump(mode="json"))
+                    elif kind == "error":
+                        yield sse("error", {"error": f"{type(val).__name__}: {val}"})
+                    elif kind == "done":
+                        yield sse("done", {})
+                        break
+            finally:
+                # If the client disconnected mid-run, the generator is closed
+                # before "done": cancel the run rather than spending model tokens
+                # for nobody and leaving the runner blocked on a full queue.
+                if not task.done():
+                    task.cancel()
+                try:
+                    await task
+                except (asyncio.CancelledError, Exception):  # noqa: BLE001 - teardown
+                    pass
+
+        return StreamingResponse(gen(), media_type="text/event-stream")
+
+    @app.get("/events", dependencies=auth)
+    async def events_stream() -> Any:
+        """A global live feed of every run's events (SSE) — what the dashboard
+        consumes. ``event`` frames carry a human ``line`` and the raw event;
+        ``defense`` frames carry a queued blocked attempt."""
+        q = hub.subscribe()
+
+        async def gen() -> Any:
+            # An initial comment so the client connects promptly even when idle.
+            yield ": connected\n\n"
+            try:
+                while True:
+                    kind, val = await q.get()
+                    if kind == "event":
+                        yield event_frame(val)
+                    elif kind == "defense":
+                        yield sse("defense", val)
+            finally:
+                hub.unsubscribe(q)
+
+        return StreamingResponse(gen(), media_type="text/event-stream")
+
+    @app.get("/review", dependencies=auth)
+    async def review_queue_endpoint() -> dict:
+        """The defense review queue: contained adversarial attempts awaiting
+        triage (most recent first), from the in-memory view of this process."""
+        return {"pending": len(review), "items": review}
+
+    @app.get("/", response_class=HTMLResponse, dependencies=auth)
+    async def dashboard() -> Any:
+        return _DASHBOARD_HTML
+
+    return app
+
+
+# A single self-contained page (vanilla JS, no build step): it opens the /events
+# SSE feed and renders the live run plus a highlighted Defenses panel fed by the
+# same stream and /review.
+_DASHBOARD_HTML = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Zu · live</title>
+<style>
+ :root{--bg:#0b0e14;--fg:#cdd6f4;--dim:#6c7086;--ok:#a6e3a1;--warn:#f9e2af;--bad:#f38ba8;--esc:#89b4fa}
+ body{background:var(--bg);color:var(--fg);font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;margin:0}
+ header{display:flex;align-items:center;gap:.6rem;padding:.6rem 1rem;border-bottom:1px solid #1e2230}
+ header b{font-size:15px} .dot{width:.6rem;height:.6rem;border-radius:50%;background:var(--bad)}
+ .dot.live{background:var(--ok)} .grid{display:grid;grid-template-columns:1fr 22rem;gap:1px;background:#1e2230;height:calc(100vh - 49px)}
+ .col{background:var(--bg);overflow:auto;padding:.5rem 1rem} .col h2{font-size:11px;color:var(--dim);text-transform:uppercase;letter-spacing:.1em;margin:.3rem 0 .6rem}
+ .row{white-space:pre-wrap;word-break:break-word;padding:.05rem 0} .t{color:var(--dim)}
+ .def{color:var(--bad)} .esc{color:var(--esc)} .ok{color:var(--ok)} .warn{color:var(--warn)}
+ .card{border:1px solid #1e2230;border-left:3px solid var(--bad);border-radius:4px;padding:.4rem .6rem;margin:.4rem 0}
+ .card .k{color:var(--bad);font-weight:600} .card .m{color:var(--dim)} .empty{color:var(--dim);font-style:italic}
+</style></head><body>
+<header><b>Zu</b><span class="dot" id="dot"></span><span id="status" class="t">connecting…</span>
+ <span style="margin-left:auto" class="t">defenses queued: <b id="dcount">0</b></span></header>
+<div class="grid">
+ <div class="col"><h2>Live run feed</h2><div id="feed"></div></div>
+ <div class="col"><h2>Defenses — queued for review</h2><div id="defs"><div class="empty">none yet</div></div></div>
+</div>
+<script>
+ const feed=document.getElementById('feed'),defs=document.getElementById('defs');
+ const dot=document.getElementById('dot'),status=document.getElementById('status'),dcount=document.getElementById('dcount');
+ let nd=0;
+ function line(text,cls){const d=document.createElement('div');d.className='row'+(cls?' '+cls:'');
+   const ts=new Date().toLocaleTimeString();d.innerHTML='<span class="t">'+ts+'</span> '+text;
+   feed.appendChild(d);feed.scrollTop=feed.scrollHeight;
+   while(feed.childNodes.length>500)feed.removeChild(feed.firstChild);}
+ function esc(s){return (s||'').replace(/[&<>]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));}
+ // When the server requires a token, this page is opened as /?token=... — carry
+ // it to the SSE feed (query param: EventSource can't set headers) and to /review
+ // (bearer header). No token -> open server, both calls are unauthenticated.
+ const token=new URLSearchParams(location.search).get('token');
+ const authHeaders=token?{'Authorization':'Bearer '+token}:{};
+ const es=new EventSource('/events'+(token?('?token='+encodeURIComponent(token)):''));
+ es.onopen=()=>{dot.classList.add('live');status.textContent='live';};
+ es.onerror=()=>{dot.classList.remove('live');status.textContent='reconnecting…';};
+ es.addEventListener('event',e=>{const d=JSON.parse(e.data);const ev=d.event||{};
+   let cls=''; const t=ev.type||'';
+   if(t==='harness.defense.blocked')cls='def'; else if(t==='harness.task.escalated')cls='esc';
+   else if(t==='harness.task.completed')cls='ok'; else if(t==='harness.task.terminal')cls='warn';
+   line(esc(d.line||t),cls);});
+ es.addEventListener('defense',e=>{const r=JSON.parse(e.data);nd++;dcount.textContent=nd;
+   if(defs.querySelector('.empty'))defs.innerHTML='';
+   const c=document.createElement('div');c.className='card';
+   c.innerHTML='<div><span class="k">⚠ '+esc(r.kind||'blocked')+'</span> '+esc(r.tool||'')+'</div>'+
+     '<div class="m">'+esc(r.detail||'')+(r.target?' · '+esc(r.target):'')+'</div>'+
+     '<div class="m">'+esc(r.ts||'')+' · status: '+esc(r.status||'pending')+'</div>';
+   defs.insertBefore(c,defs.firstChild);});
+ fetch('/review',{headers:authHeaders}).then(r=>r.json()).then(d=>{if(d.items&&d.items.length){nd=d.items.length;dcount.textContent=nd;
+   defs.innerHTML='';for(const r of d.items){const c=document.createElement('div');c.className='card';
+   c.innerHTML='<div><span class="k">⚠ '+esc(r.kind||'blocked')+'</span> '+esc(r.tool||'')+'</div>'+
+     '<div class="m">'+esc(r.detail||'')+'</div><div class="m">'+esc(r.ts||'')+'</div>';defs.appendChild(c);}}}).catch(()=>{});
+</script></body></html>
+"""

zu_cli/trace.py

@@ -0,0 +1,111 @@
+"""Live trace — turn the event stream into a human-readable, real-time view.
+
+The bus notifies every subscriber *as each event is appended* (append-before-
+notify), so a subscriber that prints is a live window into the running loop: the
+model's train of thought, every tool call and its result, detector verdicts,
+escalations, and the final answer — streaming with no refresh, no polling, no
+restart. The same formatter renders the CLI trace and the HTTP (SSE) stream, so
+what you watch locally and what you watch against a container are identical.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+def _truncate(value: Any, limit: int = 160) -> str:
+    text = value if isinstance(value, str) else repr(value)
+    text = " ".join(text.split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def format_event(event: Any, *, full: bool = True) -> str | None:
+    """A one-line view of an event, or None to omit it from the trace. Pure and
+    side-effect-free so it serves both the console and the SSE stream.
+
+    ``full=True`` (the local console default) shows content — the query, the
+    model's reasoning, tool args, extracted values. ``full=False`` is the
+    allowlist-render scope for a networked window: the *actions and decisions* (so
+    you see what the agent is doing and what its guards blocked) without dumping
+    the content it read or produced."""
+    t = getattr(event, "type", "")
+    p = getattr(event, "payload", {}) or {}
+
+    if t == "harness.task.started":
+        if not full:
+            return "▶ task started"
+        target = f" → {p['target']}" if p.get("target") else ""
+        return f"▶ task: {_truncate(p.get('query', ''))}{target}"
+    if t == "harness.turn.started":
+        return f"· turn {p.get('step')}"
+    if t == "harness.turn.completed":
+        # The model's natural-language output this turn — the train of thought.
+        text = p.get("text")
+        if not text:
+            return None  # a pure tool-call turn with no prose; the tool lines speak
+        if not full:
+            return f"💭 reasoning ({len(text)} chars)"  # content-light: that it thought, not what
+        return f"💭 {_truncate(text, 240)}"
+    if t == "harness.tool.invoked":
+        args = {k: v for k, v in (p.get("args") or {}).items() if k != "html"}
+        if not full:
+            keys = ", ".join(args)  # arg names only, never values
+            return f"🔧 {p.get('tool')}({keys})"
+        return f"🔧 {p.get('tool')}({_truncate(args, 120)})"
+    if t == "harness.tool.returned":
+        if not full:
+            return f"↩ {p.get('tool')} returned"
+        return f"↩ {p.get('tool')} → {_truncate(p.get('observation'), 140)}"
+    if t == "data.source.fetched":
+        # Already a summary (length + status), safe in either scope.
+        body = p.get("html") or p.get("text") or p.get("content") or ""
+        return f"📄 fetched {len(body)} chars (status {p.get('status', '?')})"
+    if t == "harness.detector.fired":
+        return f"🔎 detector {p.get('detector')} [{p.get('severity')}] — {_truncate(p.get('detail'), 120)}"
+    if t == "harness.defense.blocked":
+        target = f" → {p['target']}" if p.get("target") else ""
+        return f"🛡 BLOCKED {p.get('kind')}{target} ({p.get('tool')}) — {_truncate(p.get('detail'), 120)}"
+    if t == "harness.task.escalated":
+        if p.get("exhausted"):
+            return f"⛔ escalation exhausted at tier {p.get('tier')}: {p.get('reason')}"
+        return f"⬆️  ESCALATE {p.get('from_tier')}→{p.get('to_tier')}: {p.get('reason')} — climbing a tier"
+    if t == "harness.validation.failed":
+        return f"❌ validation {p.get('detector')} [{p.get('severity')}] — {_truncate(p.get('detail'), 120)}"
+    if t == "data.record.extracted":
+        value = p.get("value")
+        if not full:
+            n = len(value) if isinstance(value, dict) else 1
+            return f"📦 extracted ({n} field{'s' if n != 1 else ''})"  # shape, not content
+        return f"📦 extracted: {_truncate(value, 200)}"
+    if t == "harness.task.completed":
+        return "✅ completed"
+    if t == "harness.task.terminal":
+        return f"🛑 terminal: {p.get('reason')}"
+    return None
+
+
+def live_printer(
+    write: Callable[[str], None] | None = None, *, clock: bool = True
+) -> Callable[[Any], None]:
+    """A bus subscriber that prints each event the moment it is published. Pass a
+    custom ``write`` to redirect; ``clock`` prefixes a wall-clock timestamp."""
+
+    def _write(line: str) -> None:
+        if write is not None:
+            write(line)
+        else:
+            print(line, flush=True)  # flush so the trace is truly real-time
+
+    def _on_event(event: Any) -> None:
+        line = format_event(event)
+        if line is None:
+            return
+        if clock:
+            ts = getattr(event, "ts", None)
+            stamp = ts.strftime("%H:%M:%S") if ts is not None else ""
+            _write(f"  {stamp}  {line}")
+        else:
+            _write(f"  {line}")
+
+    return _on_event

zu_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: zu-cli
+Version: 0.1.0
+Summary: The `zu` command — Agent Production Runtime CLI
+Project-URL: Homepage, https://github.com/k3-mt/zu
+Project-URL: Repository, https://github.com/k3-mt/zu
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pyyaml
+Requires-Dist: typer
+Requires-Dist: zu-core==0.1.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.110; extra == 'serve'
+Requires-Dist: uvicorn>=0.27; extra == 'serve'
+Provides-Extra: test
+Requires-Dist: zu-redteam==0.1.0; extra == 'test'

zu_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+zu_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zu_cli/build.py,sha256=oogoaVsJrjvMlTmD-Hm4P2EyovAZBroaVaX0BoptcF8,4772
+zu_cli/config.py,sha256=8LcXK-DdfZFEbk6rcAKvu2A2RVYrujL3OOAmgCfuqV4,33565
+zu_cli/construct.py,sha256=DhkiLDzqf562xjByRbUrtHAkqdVp-y_QEiBPB9eDh30,13692
+zu_cli/construct_sandbox.py,sha256=0ExeeN3no7KFMdlNE5b0Wgz7T7j5htQ7UmfdqBs17_g,6977
+zu_cli/contribute.py,sha256=-fdOIfFqptcf6qQyqOW0tW1pLt0TwXCQhcN1gBu6iiY,4732
+zu_cli/demo.py,sha256=x1WqOMmD9dqBn3zjAV31FVgNctnSVjQTLnX9VVqfmX4,13735
+zu_cli/deploy.py,sha256=rJ0wPRo4Qjnv8y2xdjvKh9ME_PEZFwSUp-1Hbng4zvw,8698
+zu_cli/explore.py,sha256=0MpfvYrrq-VmoFDgtNOcCRHRetxNy5HJGRhGZ2LbLk4,4695
+zu_cli/guardrails.py,sha256=wC9BrCbOqB7sgFsT-5mdbbLzlnuoPt5OvIvSc40if3A,4446
+zu_cli/harden.py,sha256=75C-cbh3Hb9IvVeZMvsA88FJXjitCm4v-EBHoOsnCa0,9066
+zu_cli/main.py,sha256=cunMeo72fb6sAEOavJEm_o0ac8mFw3VnyQHeyY6mUW4,49233
+zu_cli/mcp_server.py,sha256=ZSmMWAoxwzys0QRiytkTaxXHQu8fsz8s3AN85O5PYCs,21406
+zu_cli/observe.py,sha256=sO96g6Yq39I8veC2y9kPE1RF9HIiuIQMRuVBPHfTPQw,2674
+zu_cli/offline.py,sha256=FiZAgGDKFPSTUjRcJKb2pqTLGSbrX5M2k6p-rujSD7I,14261
+zu_cli/sandbox.py,sha256=Ad8S1MXKUcr9P_pHDn3VLhrDtxLBdwMJrDaa0eVUCP8,13242
+zu_cli/scaffold.py,sha256=-iFZwy9Xqn3c8yh8xosScp3LHRd6GhkZhRBbns0RI6c,4203
+zu_cli/server.py,sha256=As5kYW1cBNXvZ8csEXeAmTcMiV-ZnMfjiqxSrzGQz24,18473
+zu_cli/trace.py,sha256=nl1C94oyu-dcwuJJ2eaazIj8aHu2zGVliccxjiX_V_4,5113
+zu_cli-0.1.0.dist-info/METADATA,sha256=cPkqqAswrsZku5AeLWTRBiP3vlSCLlj4408vQdIkIkM,998
+zu_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+zu_cli-0.1.0.dist-info/entry_points.txt,sha256=4TWH-lwe2t8CcPuXaxW-m6iqT8CKrS_SP0blHDwLZAk,175
+zu_cli-0.1.0.dist-info/RECORD,,

zu_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

zu_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+zu = zu_cli.main:app
+zu-construct-contained = zu_cli.construct_sandbox:construct_contained_from_env
+zu-run-contained = zu_cli.sandbox:run_contained_from_env