PyPI - zu-cli - Versions diffs - 0.1.0__py3-none-any.whl - Mend

zu-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

zu_cli/__init__.py +0 -0
zu_cli/build.py +111 -0
zu_cli/config.py +738 -0
zu_cli/construct.py +318 -0
zu_cli/construct_sandbox.py +139 -0
zu_cli/contribute.py +104 -0
zu_cli/demo.py +373 -0
zu_cli/deploy.py +207 -0
zu_cli/explore.py +93 -0
zu_cli/guardrails.py +102 -0
zu_cli/harden.py +221 -0
zu_cli/main.py +1126 -0
zu_cli/mcp_server.py +444 -0
zu_cli/observe.py +69 -0
zu_cli/offline.py +335 -0
zu_cli/sandbox.py +276 -0
zu_cli/scaffold.py +116 -0
zu_cli/server.py +363 -0
zu_cli/trace.py +111 -0
zu_cli-0.1.0.dist-info/METADATA +26 -0
zu_cli-0.1.0.dist-info/RECORD +23 -0
zu_cli-0.1.0.dist-info/WHEEL +4 -0
zu_cli-0.1.0.dist-info/entry_points.txt +4 -0

zu_cli/demo.py ADDED Viewed

@@ -0,0 +1,373 @@
+"""The demos behind ``zu demo`` — shipped in the package so they run after a
+pip install, no repo clone needed.
+The demos exist to prove **runnability**: that a freshly installed Zu actually
+runs an agent against a **real model** and produces a validated result. So a real
+run needs an API key — the default. (``--offline`` replays a scripted, fixtured
+run instead; that proves the *wiring* for CI/self-test, not a real run, and is
+labelled as such.)
+Demo types (``--type``), ordered by what they require to run:
+* **minimal** — a model answers a question as JSON, schema-validated. No tools,
+  no network. Requires: an **API key**.
+* **web** (default) — a real ``http_fetch`` of a real page + the model extracts a
+  field + schema/grounding validation. This is **tier 1**: requires an **API key
+  + network**, and the ``[demo]`` extra. **No Docker.**
+* **escalation** — the full fetch → fail-on-JS → escalate-to-browser arc. Tier 2
+  (a real browser) needs **Docker**, and the headless-Chromium image is not yet
+  published — so the *real* path isn't available out of the box. Use
+  ``--offline`` to watch the escalation logic with a fixtured browser.
+The requirement ladder: Python → +network (tier 1) → +Docker (tier 2), plus an
+API key for any real model. We never ship or require a key.
+"""
+from __future__ import annotations
+from typing import Any
+from zu_core.bus import EventBus
+from zu_core.contracts import Result, Status, TaskSpec
+from zu_core.loop import run_task
+from zu_core.ports import ModelProvider, ToolCall
+from zu_core.registry import Registry
+# The web tools (zu-tools) are an opt-in extra; this module must still import on
+# the lean base, so plugin packages are imported lazily inside the builders.
+_WEB_HINT = "this demo needs the web tools — install them with: pip install 'zu-runtime[demo]'"
+def ensure_web_tools() -> None:
+    """Raise a clear, actionable error if the web tools aren't installed."""
+    try:
+        import zu_tools  # noqa: F401
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(_WEB_HINT) from exc
+# --- tasks -------------------------------------------------------------------
+_MINIMAL_TASK = TaskSpec(
+    query="Reply with the capital of France as a JSON object: {\"capital\": ...}.",
+    max_tier=1,
+    output_schema={
+        "type": "object",
+        "properties": {"capital": {"type": "string"}},
+        "required": ["capital"],
+    },
+)
+_WEB_URL = "https://example.com"
+_WEB_TASK = TaskSpec(
+    query=(
+        "Fetch the page and extract its main heading. "
+        "Return a JSON object: {\"title\": ...}."
+    ),
+    target=_WEB_URL,
+    max_tier=1,
+    output_schema={
+        "type": "object",
+        "properties": {"title": {"type": "string"}},
+        "required": ["title"],
+    },
+)
+# A stand-in for example.com used only by the offline self-test (no network).
+_EXAMPLE_HTML = (
+    "<html><head><title>Example Domain</title></head><body><main>"
+    "<h1>Example Domain</h1>"
+    "<p>This domain is for use in illustrative examples in documents.</p>"
+    "</main></body></html>"
+)
+# --- the escalation arc (offline self-test; real tier-2 needs Docker + image) -
+_SHELL_URL = "http://shop.test/product/123"
+_SHELL = '<html><body><div id="root"></div><script src="/app.js"></script></body></html>'
+_RENDERED = (
+    "<html><body><main><h1>Acme Widget</h1><span class='price'>$9.00</span></main></body></html>"
+)
+_ESCALATION_TASK = TaskSpec(
+    query="Extract the product name and price.",
+    target=_SHELL_URL,
+    max_tier=2,
+    output_schema={
+        "type": "object",
+        "properties": {"name": {"type": "string"}, "price": {"type": "string"}},
+        "required": ["name", "price"],
+    },
+)
+class _FixtureBrowser:
+    """A stand-in SandboxBackend for the offline escalation self-test: no Docker,
+    no real browser — returns the saved rendered page."""
+    name = "fixture-browser"
+    def __init__(self, rendered: str) -> None:
+        self._rendered = rendered
+        self.launched: list[dict] = []
+        self.destroyed = 0
+    async def launch(self, spec: dict) -> dict:
+        self.launched.append(spec)
+        return {"id": "sbx-1", "spec": spec}
+    async def exec(self, sandbox: dict, call: ToolCall) -> dict:
+        return {"status": 200, "html": self._rendered, "url": call.args["url"]}
+    async def destroy(self, sandbox: dict) -> None:
+        self.destroyed += 1
+# --- registries (built per type; ``offline`` fixtures the network/browser) ----
+def _minimal_registry(offline: bool) -> tuple[Registry, None]:
+    from zu_checks.validators.schema import SchemaValidator
+    reg = Registry()
+    reg.register("validators", "schema", SchemaValidator())
+    return reg, None
+def _web_registry(offline: bool) -> tuple[Registry, None]:
+    ensure_web_tools()
+    from zu_checks.validators.grounding import GroundingValidator
+    from zu_checks.validators.schema import SchemaValidator
+    from zu_tools.fetch import HttpFetch
+    from zu_tools.parse import HtmlParse
+    if offline:
+        import httpx
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, text=_EXAMPLE_HTML)
+        fetch = HttpFetch(allow_private=True, transport=httpx.MockTransport(handler))
+    else:
+        fetch = HttpFetch()  # real network
+    reg = Registry()
+    reg.register("tools", "http_fetch", fetch)
+    reg.register("tools", "html_parse", HtmlParse())
+    reg.register("validators", "schema", SchemaValidator())
+    reg.register("validators", "grounding", GroundingValidator())
+    return reg, None
+def _escalation_registry(offline: bool) -> tuple[Registry, Any]:
+    if not offline:
+        raise RuntimeError(
+            "the real escalation demo needs Docker and a published tier-2 browser image "
+            "(not available yet); run it with --offline to see the escalation logic."
+        )
+    ensure_web_tools()
+    import httpx
+    from zu_checks.detectors.bot_wall import BotWallDetector
+    from zu_checks.detectors.empty import EmptyDetector
+    from zu_checks.detectors.error import ErrorDetector
+    from zu_checks.detectors.js_shell import JsShellDetector
+    from zu_checks.validators.grounding import GroundingValidator
+    from zu_checks.validators.schema import SchemaValidator
+    from zu_tools.fetch import HttpFetch
+    from zu_tools.parse import HtmlParse
+    from zu_tools.render import RenderDom
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, text=_SHELL)
+    backend = _FixtureBrowser(_RENDERED)
+    reg = Registry()
+    reg.register("tools", "http_fetch", HttpFetch(allow_private=True, transport=httpx.MockTransport(handler)))
+    reg.register("tools", "html_parse", HtmlParse())
+    # allow_private: the offline demo renders a non-resolvable fixture host
+    # through a fake browser backend (no real egress), so skip the SSRF DNS check.
+    reg.register("tools", "render_dom", RenderDom(backend=backend, allow_private=True))
+    for name, det in [
+        ("empty", EmptyDetector()),
+        ("error", ErrorDetector()),
+        ("js-shell", JsShellDetector()),
+        ("bot-wall", BotWallDetector()),
+    ]:
+        reg.register("detectors", name, det)
+    reg.register("validators", "schema", SchemaValidator())
+    reg.register("validators", "grounding", GroundingValidator())
+    return reg, backend
+# --- scripted providers (used ONLY by --offline self-test) -------------------
+def _minimal_scripted() -> Any:
+    from zu_providers.scripted import ScriptedProvider
+    return ScriptedProvider.from_moves([{"text": '{"capital": "Paris"}', "finish": "stop"}])
+def _web_scripted() -> Any:
+    from zu_providers.scripted import ScriptedProvider
+    return ScriptedProvider.from_moves(
+        [
+            {"tool": "http_fetch", "args": {"url": _WEB_URL}},
+            {"text": '{"title": "Example Domain"}', "finish": "stop"},
+        ]
+    )
+def _escalation_scripted() -> Any:
+    from zu_providers.scripted import ScriptedProvider
+    return ScriptedProvider.from_moves(
+        [
+            {"tool": "http_fetch", "args": {"url": _SHELL_URL}},
+            {"tool": "render_dom", "args": {"url": _SHELL_URL}},
+            {"text": '{"name": "Acme Widget", "price": "$9.00"}', "finish": "stop"},
+        ]
+    )
+DEMOS: dict[str, dict[str, Any]] = {
+    "minimal": {
+        "task": _MINIMAL_TASK,
+        "registry": _minimal_registry,
+        "scripted": _minimal_scripted,
+        "needs_web": False,
+        "requires": "an API key (a real model)",
+        "title": "minimal — a model answers, schema-validated (no tools, no network)",
+    },
+    "web": {
+        "task": _WEB_TASK,
+        "registry": _web_registry,
+        "scripted": _web_scripted,
+        "needs_web": True,
+        "requires": "an API key + network · tier 1, no Docker",
+        "title": "web — fetch a real page, extract a field, validate (tier 1)",
+    },
+    "escalation": {
+        "task": _ESCALATION_TASK,
+        "registry": _escalation_registry,
+        "scripted": _escalation_scripted,
+        "needs_web": True,
+        "requires": "an API key + Docker (tier-2 browser) — real path not yet available; use --offline",
+        "title": "escalation — fetch, fail on JS, escalate to a browser, validate (tier 2)",
+    },
+}
+DEMO_TYPES = tuple(DEMOS)
+# --- running ------------------------------------------------------------------
+async def run_arc(
+    provider: ModelProvider, kind: str = "web", offline: bool = False, bus: EventBus | None = None
+) -> tuple[Result, EventBus, Any]:
+    """Drive the chosen demo; return the result, the event bus, and the fixture
+    browser (escalation) or None. Pass a ``bus`` with a subscriber attached to
+    watch the run live."""
+    registry, backend = DEMOS[kind]["registry"](offline)
+    bus = bus or EventBus()
+    result = await run_task(DEMOS[kind]["task"], provider, registry, bus)
+    return result, bus, backend
+async def run_demo(
+    provider: ModelProvider,
+    provider_label: str = "scripted",
+    kind: str = "web",
+    offline: bool = False,
+) -> int:
+    """Run the chosen demo and print the narrated timeline + result. Returns a
+    process exit code (0 success, 1 otherwise)."""
+    meta = DEMOS[kind]
+    task = meta["task"]
+    # Only a real model id, never the provider name standing in for one — a
+    # scripted/offline provider has no model, and "model=scripted" conflates the
+    # two. None here means the provider line below shows the provider alone.
+    model = getattr(provider, "model", None)
+    print("=" * 72)
+    print(f"Zu · demo: {meta['title']}")
+    print("=" * 72)
+    print(f"type     : {kind}{'  (offline self-test — wiring only, not a real run)' if offline else ''}")
+    print(f"requires : {meta['requires']}")
+    print(f"task     : {task.query}")
+    if task.target:
+        print(f"target   : {task.target}")
+    print(f"provider : {provider_label}" + (f"  model: {model}" if model else ""))
+    print("-" * 72)
+    # Watch the run live — the train of thought, tools, and escalations stream
+    # to the console as the loop runs (the same trace `zu run` shows).
+    from .trace import live_printer
+    bus = EventBus()
+    bus.subscribe(live_printer())
+    try:
+        result, bus, backend = await run_arc(provider, kind, offline, bus=bus)
+    except Exception as exc:  # noqa: BLE001 - a clean message beats a traceback
+        print(f"\nrun failed: {type(exc).__name__}: {exc}")
+        return 1
+    print("-" * 72)
+    print(f"RESULT   : {result.status.value}")
+    if result.value is not None:
+        print(f"value    : {result.value}")
+    if result.reason is not None:
+        print(f"reason   : {result.reason}")
+    if backend is not None:
+        print(
+            f"provenance: {await bus.count()} events recorded · "
+            f"tier-2 browser leased {len(backend.launched)}×, torn down {backend.destroyed}×"
+        )
+    else:
+        print(f"provenance: {await bus.count()} events recorded")
+    if result.status is Status.SUCCESS:
+        proof = "wiring verified (offline)" if offline else "a real model ran end to end"
+        print(f"\n{proof}: validated result + a queryable event log. See the quickstart.")
+        return 0
+    print("\nThe run did not succeed — inspect the timeline above and the event log.")
+    return 1
+def build_provider(
+    provider: str | None,
+    model: str | None,
+    api_key: str | None,
+    api_key_env: str | None,
+    base_url_env: str | None,
+    kind: str = "web",
+    offline: bool = False,
+) -> tuple[ModelProvider, str]:
+    """Pick the demo's model. ``--offline`` uses the scripted self-test provider;
+    otherwise a real provider is built the same way ``zu run`` does (proving one
+    config surface), defaulting to Anthropic when only a model is given."""
+    if offline:
+        return DEMOS[kind]["scripted"](), "scripted"
+    from .config import ConfigError, ProviderConfig
+    from .config import build_provider as cfg_build_provider
+    # No hard-coded provider default: an agent must say which provider it runs on.
+    # If a real run names none, fail clearly rather than silently assuming one.
+    if not provider:
+        raise ConfigError(
+            "a real run needs a provider — pass --provider (e.g. --provider "
+            "openai-compatible --model openai/gpt-4o-mini, or --provider anthropic "
+            "--model claude-opus-4-8), or use --offline for the scripted self-test."
+        )
+    prov = cfg_build_provider(
+        ProviderConfig(
+            name=provider,
+            model=model,
+            api_key=api_key,
+            api_key_env=api_key_env,
+            base_url_env=base_url_env,
+        )
+    )
+    return prov, provider

zu_cli/deploy.py ADDED Viewed

@@ -0,0 +1,207 @@
+"""Deployment — turn a config + task into something running, from the CLI.
+Two paths, both honest about credentials (secrets are never baked into an image
+or a manifest — they are referenced as environment variables the platform
+injects at deploy time):
+* **local** — generate a project Dockerfile (pip-installs ``zu-runtime``, copies
+  the config), build it, and run ``zu serve`` in a container, passing the
+  provider's key env through. One command to a running, streamable agent.
+* **manifests** — emit a Dockerfile / docker-compose / Fly / Render config you
+  apply with your platform's own tooling (we don't hold your cloud creds).
+The generated artifacts are deterministic text, so the manifest path needs no
+Docker and is fully testable; only ``local`` touches the daemon.
+"""
+from __future__ import annotations
+import os
+TARGETS = ("local", "dockerfile", "compose", "fly", "render")
+# Env vars worth passing through to a container / referencing in a manifest.
+# Provider key/base-url envs plus ZU_SERVE_TOKEN (the bearer token `zu serve`
+# requires when bound to a non-localhost host — see server.py). A config that
+# names a *different* key env (a custom provider) has it added on top by
+# ``key_envs_for_config`` below, so the passthrough isn't limited to these.
+_KEY_ENVS = (
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "OPENROUTER_API_KEY",
+    "OPENROUTER_BASE_URL",
+    "ZU_SERVE_TOKEN",
+)
+def key_envs_for_config(cfg: object | None) -> tuple[str, ...]:
+    """The env vars to pass through for ``cfg``: the defaults above plus any
+    ``api_key_env`` / ``base_url_env`` the config's provider(s) actually name —
+    so a custom provider reading e.g. ``GROQ_API_KEY`` is credentialled in the
+    deployed container instead of silently starting without a key. Order is
+    stable (defaults first, then config-declared extras) and de-duplicated."""
+    envs: list[str] = list(_KEY_ENVS)
+    provider = getattr(cfg, "provider", None)
+    providers = list(getattr(cfg, "providers", {}).values()) if cfg is not None else []
+    for p in [provider, *providers]:
+        for attr in ("api_key_env", "base_url_env"):
+            val = getattr(p, attr, None)
+            if isinstance(val, str) and val and val not in envs:
+                envs.append(val)
+    return tuple(envs)
+def dockerfile_text(
+    config: str, *, extras: str = "all", port: int = 8000,
+    python_version: str = "3.11", version: str | None = None,
+) -> str:
+    # Pin the runtime version when known, so a rebuilt image is reproducible
+    # rather than silently pulling a newer (possibly breaking) release. The
+    # Python base is configurable for the same reason — a pinned, deliberate base.
+    spec = f"zu-runtime[{extras}]" + (f"=={version}" if version else "")
+    return (
+        "# Generated by `zu deploy`. Runs your agent as an HTTP service.\n"
+        "# Secrets are NOT baked in — pass them at run time (-e ANTHROPIC_API_KEY=...).\n"
+        f"FROM python:{python_version}-slim\n"
+        "ENV PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1\n"
+        f'RUN pip install "{spec}"\n'
+        "WORKDIR /app\n"
+        f"COPY {config} ./{config}\n"
+        f"EXPOSE {port}\n"
+        f'CMD ["zu", "serve", "-c", "{config}", "--host", "0.0.0.0", "--port", "{port}"]\n'
+    )
+def pack_dockerfile_text(base: str = "zu:latest", *, agent: str = "agent.yaml") -> str:
+    """A Dockerfile that BAKES a bundle (its ``agent.yaml`` + ``tools/`` + a
+    ``requirements.txt``) into a standalone image, FROM a Zu runtime ``base``.
+    Unlike ``--sandboxed`` (which mounts the bundle and so is limited to the base
+    image's packages), pack installs the bundle's own pip deps at build time — so
+    a bundle whose tools need extra libraries runs anywhere. Secrets are NOT
+    baked: pass them at run time (``-e ANTHROPIC_API_KEY=...``). The bundle is on
+    ``PYTHONPATH`` so its ``tools.x:Class`` import-refs resolve; the image runs as
+    the base's non-root user."""
+    return (
+        "# Generated by `zu pack`. Bakes this bundle into a standalone image.\n"
+        "# Secrets are NOT baked — pass them at run time (-e ANTHROPIC_API_KEY=...).\n"
+        f"FROM {base}\n"
+        "USER root\n"
+        "WORKDIR /agent\n"
+        "COPY . /agent\n"
+        "RUN if [ -f requirements.txt ]; then pip install --no-cache-dir -r requirements.txt; fi\n"
+        "ENV PYTHONPATH=/agent\n"
+        "RUN chown -R 10001:10001 /agent 2>/dev/null || true\n"
+        "USER 10001\n"
+        f'CMD ["zu", "run", "/agent/{agent}"]\n'
+    )
+def pack_build_command(tag: str, bundle: str) -> list[str]:
+    """The ``docker build`` argv for ``zu pack``. The Dockerfile is fed on stdin
+    (``-f -``) with the bundle as the build context, so packing never writes a
+    file into the user's bundle directory."""
+    return ["docker", "build", "-t", tag, "-f", "-", bundle]
+def compose_text(name: str, config: str, *, port: int = 8000, envs: tuple[str, ...] = _KEY_ENVS) -> str:
+    env_lines = "\n".join(f"      - {k}" for k in envs)
+    return (
+        "# Generated by `zu deploy compose`. Secrets pass through from your shell\n"
+        "# (export them, or use an env_file). `docker compose up --build`.\n"
+        "services:\n"
+        f"  {name}:\n"
+        "    build: .\n"
+        f'    ports: ["{port}:{port}"]\n'
+        "    environment:\n"
+        f"{env_lines}\n"
+        "    restart: unless-stopped\n"
+    )
+def fly_text(name: str, *, port: int = 8000) -> str:
+    return (
+        "# Generated by `zu deploy fly`. Then: fly launch --no-deploy (once),\n"
+        "# fly secrets set ANTHROPIC_API_KEY=... , fly deploy.\n"
+        f'app = "{name}"\n\n'
+        "[build]\n\n"
+        "[http_service]\n"
+        f"  internal_port = {port}\n"
+        "  force_https = true\n"
+        "  auto_stop_machines = true\n"
+        "  min_machines_running = 0\n\n"
+        "[[vm]]\n"
+        '  memory = "512mb"\n'
+        "  cpus = 1\n"
+    )
+def render_text(name: str, *, port: int = 8000, envs: tuple[str, ...] = _KEY_ENVS) -> str:
+    env_lines = "\n".join(f"      - key: {k}\n        sync: false" for k in envs)
+    return (
+        "# Generated by `zu deploy render`. Commit, then create a Blueprint on Render.\n"
+        "services:\n"
+        "  - type: web\n"
+        f"    name: {name}\n"
+        "    runtime: docker\n"
+        "    dockerfilePath: ./Dockerfile\n"
+        "    envVars:\n"
+        f"{env_lines}\n"
+    )
+def write_dockerfile(
+    directory: str, config: str, *, extras: str, port: int, force: bool,
+    python_version: str = "3.11", version: str | None = None,
+) -> str:
+    path = os.path.join(directory, "Dockerfile")
+    if os.path.exists(path) and not force:
+        return path  # respect an existing Dockerfile (e.g. a hand-tuned one)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(dockerfile_text(
+            config, extras=extras, port=port, python_version=python_version, version=version,
+        ))
+    return path
+def generate(
+    target: str, directory: str, *, name: str, config: str, extras: str, port: int, force: bool,
+    python_version: str = "3.11", version: str | None = None,
+    envs: tuple[str, ...] = _KEY_ENVS,
+) -> list[str]:
+    """Write the manifest(s) for a non-local target. Returns the paths written."""
+    written: list[str] = [write_dockerfile(
+        directory, config, extras=extras, port=port, force=True,
+        python_version=python_version, version=version,
+    )]
+    files: dict[str, str] = {}
+    if target == "dockerfile":
+        pass  # the Dockerfile above is the whole artifact
+    elif target == "compose":
+        files["docker-compose.yml"] = compose_text(name, config, port=port, envs=envs)
+    elif target == "fly":
+        files["fly.toml"] = fly_text(name, port=port)
+    elif target == "render":
+        files["render.yaml"] = render_text(name, port=port, envs=envs)
+    for fname, content in files.items():
+        path = os.path.join(directory, fname)
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(content)
+        written.append(path)
+    return written
+def local_commands(
+    name: str, config: str, *, port: int, envs: tuple[str, ...] = _KEY_ENVS
+) -> tuple[list[str], list[str]]:
+    """The (build, run) docker command lines for a local deploy. The run command
+    passes through whichever of ``envs`` are actually set, so no secret is ever
+    written to a file or the image."""
+    build = ["docker", "build", "-t", name, "."]
+    run = ["docker", "run", "-d", "--name", name, "-p", f"{port}:{port}"]
+    for key in envs:
+        if os.environ.get(key):
+            run += ["-e", key]
+    run.append(name)
+    return build, run

zu_cli/explore.py ADDED Viewed

@@ -0,0 +1,93 @@
+"""Harness-driven pathfinding — turn a coding agent's exploration into a track.
+A developer's OWN harness model (Claude Code, Codex, Cursor — any MCP client) drives zu's
+off-box tools step by step over ``zu mcp``: fetch a page, open the browser, act, read, react
+to what it sees, and find the path. Each step + its observation is recorded; when the path
+reaches the data, the session is projected into a ``fixtures/`` bundle — so the discovery the
+developer would do anyway BECOMES the agent's replayable path. The frontier reasoning is
+spent once, in the harness they already pay for; everything downstream replays it free
+(``zu run --offline``), with the model returning only on divergence at run time.
+This module is the SESSION core, with the tools injected — the real off-box tools in
+production (a live browser via the docker backend), fakes in tests — so the orchestration is
+verified at $0. The ``zu mcp`` server wraps one session per process as ``zu_explore`` /
+``zu_explore_save``.
+"""
+from __future__ import annotations
+import json
+from dataclasses import dataclass, field
+from typing import Any
+from .offline import Bundle
+# The off-box tools a harness drives while pathfinding. Pure tools (html_parse, recall) need
+# no exploration — they run unchanged offline — so they are not part of an explore session.
+EXPLORABLE = ("http_fetch", "render_dom", "browser")
+@dataclass
+class ExplorationSession:
+    """One live pathfinding session: the tools being driven (the persistent ``browser`` keeps
+    its session across steps), a read-only ``ctx``, and the ordered (tool, args, observation)
+    trail the harness builds. Project it into a :class:`~zu_cli.offline.Bundle` when the path
+    reaches the data."""
+    tools: dict[str, Any]
+    ctx: Any
+    steps: list[dict] = field(default_factory=list)
+    async def step(self, tool: str, args: dict) -> dict:
+        """Drive one tool call, record the (tool, args, observation), and return the
+        observation so the harness model can decide the next step. An unknown/non-explorable
+        tool is a loud error, not a silent no-op."""
+        if tool not in self.tools:
+            raise KeyError(
+                f"{tool!r} is not an explorable tool; choose one of {sorted(self.tools)}")
+        obs = await self.tools[tool](self.ctx, **args)
+        self.steps.append({"tool": tool, "args": dict(args), "observation": obs})
+        return obs
+    def to_bundle(self, *, task: str, answer: Any, model: str | None = None) -> Bundle:
+        """Project the recorded trail into a replayable Bundle — the SAME shape
+        :func:`zu_cli.offline.project_capture` produces: one move per step in order, then a
+        final text move carrying ``answer`` (so offline replay reproduces both the navigation
+        and the extraction); observations grouped by tool. A browser ``op=close`` has no
+        replayable observation (the tool returns without a session read), so it is dropped to
+        keep each tool's observation sequence aligned with its calls."""
+        moves: list[dict] = [{"tool": s["tool"], "args": s["args"]} for s in self.steps]
+        moves.append({"text": json.dumps(answer), "finish": "stop"})
+        observations: dict[str, list[dict]] = {}
+        for s in self.steps:
+            if s["tool"] == "browser" and s["args"].get("op") == "close":
+                continue
+            if isinstance(s["observation"], dict):
+                observations.setdefault(s["tool"], []).append(dict(s["observation"]))
+        return Bundle(task=task, moves=moves, observations=observations, model=model)
+def default_tools(*, allow_private: bool = False) -> dict[str, Any]:
+    """The real off-box tools a LIVE exploration drives: a one-shot ``http_fetch`` /
+    ``render_dom`` and a persistent ``browser`` (a real headless browser via the docker
+    backend). ``allow_private`` stays False so the SSRF guard holds against a real site."""
+    from zu_tools.browser import Browser
+    from zu_tools.fetch import HttpFetch
+    from zu_tools.render import RenderDom
+    return {
+        "http_fetch": HttpFetch(allow_private=allow_private),
+        "render_dom": RenderDom(allow_private=allow_private),
+        "browser": Browser(allow_private=allow_private),
+    }
+def new_session(*, tools: dict[str, Any] | None = None, allow_private: bool = False
+                ) -> ExplorationSession:
+    """A fresh exploration session — real off-box tools unless ``tools`` is injected (tests)."""
+    from zu_core.ports import RunContext
+    return ExplorationSession(
+        tools=tools if tools is not None else default_tools(allow_private=allow_private),
+        ctx=RunContext(spec=None),
+    )