zu-cli 0.2.0__tar.gz

zu_cli-0.2.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Test / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Zu runtime artifacts
+*.db
+zu.db
+zu.yaml.local
+zu_review.jsonl
+*.review.jsonl
+# Per-agent cost telemetry ledger — machine-local run history, not source.
+cost.jsonl
+# A recorded replay path is learned per-run and machine-local — regenerated on
+# every successful run, not source. The agent ships; its track does not.
+track.json
+# …except the flagship example ships its track on purpose, as a demo of the
+# record/replay convergence (committed; re-runs show as ordinary modifications).
+!examples/agents/vet-appointment/track.json
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Claude Code local session state
+.claude/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Microsoft Office temp/lock files
+~$*
+
+# Internal design / strategy docs — kept local, never in the public repo
+*.docx
+*.pdf
+# BUILD.md is the internal build-sequence / deferred-gaps ledger — kept local.
+# (ARCHITECTURE.md is public: an onboarding agent needs the structural map.)
+docs/BUILD.md
+
+# Local secret — API key for live validation, never commit
+zu_demo_key.md
+*_key.md
+
+# Local PyPI publish token — never commit
+/pypi
+
+# Local Discord credentials (bot token / app secrets) — never commit
+/discord

zu_cli-0.2.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: zu-cli
+Version: 0.2.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.2.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.2.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# zu-cli
+
+The `zu` command, the HTTP server, and the MCP server — the surfaces you *drive*
+Zu through. This package wires the same runtime path the `import zu` facade uses
+(config in → typed `Result` out), so the CLI, the server, and embedding are one
+runtime, not three.
+
+This package registers **no plugins**; it consumes them.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `zu run agent.yaml` | Run one task; streams a live trace. `--every 5m` for a scheduled worker, `--no-stream` for CI, `--sandboxed` to run contained. |
+| `zu init --template web` | Scaffold a starter `agent.yaml` (`minimal` / `web` / `research`). |
+| `zu demo` | Prove a real run end to end (`--offline` for a scripted self-test). |
+| `zu serve -c agent.yaml` | HTTP service: `POST /run`, `POST /run/stream` (SSE), `GET /healthz`. Needs `[serve]`. |
+| `zu deploy local\|compose\|fly\|render\|dockerfile` · `zu pack` | Turn a config/bundle into a running/deployable service or image. |
+| `zu mcp` | An MCP stdio server so coding agents (Claude Code, Cursor, Codex) drive Zu — design/run, **construct**, explore, and report capability gaps. Needs `[mcp]`. |
+| `zu plugins` · `zu test-plugin <pkg>` | List discovered plugins · run a plugin through the test gate (see `zu-redteam`). |
+
+**The construction sequence** — `task + site → production agent`, frontier spend bounded to one live capture (see [`docs/agent-construction-sequence.md`](../../docs/agent-construction-sequence.md)):
+
+| Command | What it does |
+|---------|--------------|
+| `zu capture <agent>` | Drive the target **once** (live) → `fixtures/capture.json`. The one live spend. |
+| `zu run <agent> --offline` | Replay the captured bundle at **~$0** (no model/network) — the free construction inner loop. |
+| `zu build <agent>` | The offline spine: build → record track → harden, gated on resilience. |
+| `zu harden <agent>` | Score a captured path against perturbed fixtures (offline brittleness audit + resilience). |
+| `zu construct <agent> [--check\|--sandboxed]` | The anti-hardcode readiness gate (G1–G3) / the autonomous, contained construction loop. |
+
+## Modules
+
+`main.py` (the Typer app), `config.py` (config/task loading + assembly + shared coercion
+helpers), `server.py` (FastAPI), `mcp_server.py`, `demo.py`, `deploy.py`, `scaffold.py`,
+`trace.py` (the live train-of-thought formatter). The construction surface:
+`offline.py` (replay + `FixtureSessionBackend`), `build.py`, `harden.py`, `guardrails.py`,
+`construct.py` (the meta-agent driver + `LiveStrategist`), `construct_sandbox.py` (contained
+construction), `explore.py` (harness-driven pathfinding), `contribute.py` (capability-gap
+issues).
+
+## Tests
+
+`uv run pytest packages/zu-cli` — offline. Fixture agents the suite drives live in
+[`tests/agents/`](tests/agents/) (the sole shipped example is `examples/agents/vet-appointment/`).

zu_cli-0.2.0/README.md

@@ -0,0 +1,45 @@
+# zu-cli
+
+The `zu` command, the HTTP server, and the MCP server — the surfaces you *drive*
+Zu through. This package wires the same runtime path the `import zu` facade uses
+(config in → typed `Result` out), so the CLI, the server, and embedding are one
+runtime, not three.
+
+This package registers **no plugins**; it consumes them.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `zu run agent.yaml` | Run one task; streams a live trace. `--every 5m` for a scheduled worker, `--no-stream` for CI, `--sandboxed` to run contained. |
+| `zu init --template web` | Scaffold a starter `agent.yaml` (`minimal` / `web` / `research`). |
+| `zu demo` | Prove a real run end to end (`--offline` for a scripted self-test). |
+| `zu serve -c agent.yaml` | HTTP service: `POST /run`, `POST /run/stream` (SSE), `GET /healthz`. Needs `[serve]`. |
+| `zu deploy local\|compose\|fly\|render\|dockerfile` · `zu pack` | Turn a config/bundle into a running/deployable service or image. |
+| `zu mcp` | An MCP stdio server so coding agents (Claude Code, Cursor, Codex) drive Zu — design/run, **construct**, explore, and report capability gaps. Needs `[mcp]`. |
+| `zu plugins` · `zu test-plugin <pkg>` | List discovered plugins · run a plugin through the test gate (see `zu-redteam`). |
+
+**The construction sequence** — `task + site → production agent`, frontier spend bounded to one live capture (see [`docs/agent-construction-sequence.md`](../../docs/agent-construction-sequence.md)):
+
+| Command | What it does |
+|---------|--------------|
+| `zu capture <agent>` | Drive the target **once** (live) → `fixtures/capture.json`. The one live spend. |
+| `zu run <agent> --offline` | Replay the captured bundle at **~$0** (no model/network) — the free construction inner loop. |
+| `zu build <agent>` | The offline spine: build → record track → harden, gated on resilience. |
+| `zu harden <agent>` | Score a captured path against perturbed fixtures (offline brittleness audit + resilience). |
+| `zu construct <agent> [--check\|--sandboxed]` | The anti-hardcode readiness gate (G1–G3) / the autonomous, contained construction loop. |
+
+## Modules
+
+`main.py` (the Typer app), `config.py` (config/task loading + assembly + shared coercion
+helpers), `server.py` (FastAPI), `mcp_server.py`, `demo.py`, `deploy.py`, `scaffold.py`,
+`trace.py` (the live train-of-thought formatter). The construction surface:
+`offline.py` (replay + `FixtureSessionBackend`), `build.py`, `harden.py`, `guardrails.py`,
+`construct.py` (the meta-agent driver + `LiveStrategist`), `construct_sandbox.py` (contained
+construction), `explore.py` (harness-driven pathfinding), `contribute.py` (capability-gap
+issues).
+
+## Tests
+
+`uv run pytest packages/zu-cli` — offline. Fixture agents the suite drives live in
+[`tests/agents/`](tests/agents/) (the sole shipped example is `examples/agents/vet-appointment/`).

zu_cli-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "zu-cli"
+version = "0.2.0"
+description = "The `zu` command — Agent Production Runtime CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+# The lean engine: the `zu` command + config, and nothing but the core. Plugins
+# are opt-in — installed as separate packages (zu-tools, zu-providers, …) or
+# pulled by the `zu-runtime` bundle and its extras. The CLI discovers whatever
+# is installed at runtime, so it never forces a plugin (or its deps) on a user.
+dependencies = [
+    "zu-core==0.2.0",
+    "typer",
+    "pyyaml",
+]
+
+[project.optional-dependencies]
+# `zu serve` — the HTTP wrapper. Kept optional so the CLI/library never force a
+# web framework on a user who only embeds or runs one-shot tasks.
+serve = ["fastapi>=0.110", "uvicorn>=0.27"]
+# `zu mcp` — the MCP server, so coding agents (Claude Code, Cursor, …) drive Zu.
+mcp = ["mcp>=1.2"]
+# `zu test-plugin` — the plugin-test gate + adversarial red team. Optional: a
+# contributor/CI tool, not needed to run an agent.
+test = ["zu-redteam==0.2.0"]
+
+[project.urls]
+Homepage = "https://github.com/k3-mt/zu"
+Repository = "https://github.com/k3-mt/zu"
+
+[project.scripts]
+zu = "zu_cli.main:app"
+# In-container entrypoint for the whole-agent-in-container form: the sandbox
+# launcher execs this inside the hardened container (see zu_cli.sandbox).
+zu-run-contained = "zu_cli.sandbox:run_contained_from_env"
+# In-container entrypoint for autonomous construction: the launcher execs this in
+# the same hardened box to run the construct() loop contained (see construct_sandbox).
+zu-construct-contained = "zu_cli.construct_sandbox:construct_contained_from_env"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zu_cli"]

zu_cli-0.2.0/src/zu_cli/build.py

@@ -0,0 +1,111 @@
+"""The construction spine — chain the OFFLINE stages of the sequence into one run.
+
+``zu build`` composes what the earlier increments shipped: replay the captured bundle
+offline (stage 3), project the resilient track from that clean run (stage 4), and score
+it against perturbed fixtures (stage 5) — gating the track on the resilience score. The
+output is a production-ready, hardened ``track.json`` next to the agent, produced at $0:
+no model, no network.
+
+The two LIVE stages and promotion are deliberately NOT in this spine — they need keys,
+network, or a registry push, and are left behind explicit seams so the cheap, testable
+core stands on its own:
+
+* **Stage 2 (capture)** is the one live step; ``zu build`` requires its output
+  (``fixtures/capture.json``) and points at ``zu capture`` when it is missing.
+* **Stage 6 (canary)** — one live validation run before promotion — is the live lane,
+  guarded by ``_canary`` raising ``NotImplementedError`` so ``--with-canary`` fails
+  loudly rather than pretending. It is the next increment.
+* **Stage 7 (promote)** — ``zu pack`` / ``zu deploy`` — is left to its existing commands;
+  ``zu build`` prints them as the next step.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .harden import HardenReport, harden
+from .offline import Bundle, replay_offline
+
+
+@dataclass
+class StageResult:
+    """One stage of the spine: its outcome and a one-line detail for the summary."""
+
+    name: str
+    status: str   # "ok" | "failed" | "skipped"
+    detail: str
+
+
+@dataclass
+class BuildReport:
+    stages: list[StageResult] = field(default_factory=list)
+    track_path: str | None = None
+    harden: HardenReport | None = None
+
+    @property
+    def ok(self) -> bool:
+        return all(s.status != "failed" for s in self.stages)
+
+    def _add(self, name: str, status: str, detail: str) -> StageResult:
+        s = StageResult(name=name, status=status, detail=detail)
+        self.stages.append(s)
+        return s
+
+
+def _canary(spec: Any, cfg: Any) -> None:
+    """Stage 6 — the live canary. The seam for the live lane: one real run guarding
+    fixture drift before promotion. Not built here (needs keys + network)."""
+    raise NotImplementedError(
+        "the live canary (stage 6) is the live lane — it needs keys + network and is the "
+        "next increment. Validate manually for now with `zu run <agent>` (live), then "
+        "promote with `zu pack` / `zu deploy`."
+    )
+
+
+async def build_offline(
+    spec: Any, cfg: Any, agent_dir: str | Path, bundle: Bundle, *, min_score: float = 1.0,
+) -> BuildReport:
+    """Run the offline spine — build → record track → harden — and write the hardened
+    track. Each stage gates the next: a failed offline build is not tracked, and a track
+    that fails the resilience gate is recorded but flagged failed so promotion is held."""
+    from zu_core.contracts import Status
+    from zu_core.track import record_track
+
+    report = BuildReport()
+
+    # Stage 3 — build offline (the keystone). A clean replay is the precondition.
+    result, events = await replay_offline(spec, cfg, bundle)
+    if result.status is not Status.SUCCESS:
+        report._add("build", "failed",
+                    f"offline run did not succeed ({result.status.value}: {result.reason})")
+        return report
+    report._add("build", "ok", f"offline run succeeded → {result.value}")
+
+    # Stage 4 — record the track from the clean offline run.
+    track = record_track(events, task=spec.query, model=bundle.model)
+    track_path = str(Path(agent_dir) / "track.json")
+    track.save(track_path)
+    report.track_path = track_path
+    climbs = sorted({s.tier for s in track.steps})
+    tiers = (f"tiers {min(climbs)}→{max(climbs)}" if len(climbs) > 1
+             else f"tier {climbs[0]}" if climbs else "no tools")
+    report._add("track", "ok", f"recorded {len(track.steps)} steps ({tiers}) → {track_path}")
+
+    # Stage 5 — harden: score the track against perturbed fixtures and gate on it.
+    hr = await harden(spec, cfg, bundle)
+    report.harden = hr
+    score = hr.resilience
+    if not hr.grounding_load_bearing:
+        report._add("harden", "failed",
+                    "a value-deletion control passed — grounding is not gating; the "
+                    "resilience score is unreliable")
+    elif score < min_score:
+        report._add("harden", "failed",
+                    f"resilience {score:.0%} below --min-score {min_score:.0%} "
+                    f"({len(hr.findings)} brittle step(s) to fix)")
+    else:
+        report._add("harden", "ok",
+                    f"resilience {score:.0%}; {len(hr.findings)} brittle step(s) noted")
+    return report