diff --git a/CHANGELOG.md b/CHANGELOG.md index 00303920..d4bb2f1c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Docs +- **Managed Python runtime gets its guide, and the front doors catch up with the product.** + New `guides/python-runtime.md` covers the desktop one-click interpreter install + (ADR 0094) end to end — what needs it, both install paths, the pre-failure status + surfaces, the stale-baseline refresh, and the API. The README and docs landing now + mention archetypes (the wizard picks one, not a "persona preset"), the `execute_code`/ + `coder`/`friction`/`orgchart` plugins, workflow `gate: human` approval steps, the ⌘K + palette + Fleet Room, and `/export` + `/btw`. protobanana left the core roadmap (it's a + plugin, tracked in its own repo and the directory), and the internal `plans/`/`design/` + working docs are excluded from the published site. - **Documentation audit — stale claims fixed, missing reference material added.** The docs landing no longer claims Discord/Google ship first-party (they're official external installs) or that cost-v1 rides a DataPart (it's the artifact metadata map); the README diff --git a/README.md b/README.md index 92ac5bcf..7993a8d9 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ rename / release-pipeline wiring. | Tracing | `observability/tracing.py` | Langfuse trace_session with distributed `a2a.trace` propagation and the OTel cross-context-detach filter | | Observability | `observability/metrics.py`, `observability/audit.py` | Prometheus metrics with per-agent prefix, JSONL audit log with trace IDs | | Output protocol | `graph/output_format.py` | `` / `` parsing so the model can think without it leaking to users | -| UI | `apps/web/` (React console) | React operator console (the default `--ui console` tier + the Tauri desktop app) over the REST/A2A API — live token-by-token streaming, chat continuity across navigation (+ interrupted-stream self-heal), plugin-contributed rail views, and a PWA shell. See [ADR 0010](./docs/adr/0010-headless-setup-and-ui-tiers.md) | +| UI | `apps/web/` (React console) | React operator console (the default `--ui console` tier + the Tauri desktop app) over the REST/A2A API — live token-by-token streaming, chat continuity across navigation (+ interrupted-stream self-heal), plugin-contributed rail views, a ⌘K command palette + presence-aware Fleet Room, `/export` (save a chat to Markdown) and `/btw` (a side question answered from the chat's context, saved nowhere), and a PWA shell. See [ADR 0010](./docs/adr/0010-headless-setup-and-ui-tiers.md) | | Release pipeline | `.github/workflows/*.yml` | Autonomous semver bumps, GHCR image push, GitHub release with filtered notes, optional Discord post | ## Quickstart — from zero to chatting in 5 minutes @@ -74,8 +74,9 @@ uv sync && uv run python -m server # core, serves the React console (-- # python -m server # 3. Open the wizard — pick your endpoint, pick a model, name the -# agent, pick a persona preset, hit Launch. The console chat appears -# once setup completes. +# agent, pick an archetype (Basic, Cowork, Project Manager, Design System +# Engineer — or any installed bundle that declares one), hit Launch. The +# console chat appears once setup completes. open http://localhost:7870 ``` @@ -172,9 +173,13 @@ First-party plugins ship in `plugins/` — `delegates` is a built-in, `notes`, ` | [`artifact`](./plugins/artifact/) | tools · view · skill | **On by default** — generative UI; `show_artifact` renders charts, diagrams, Mermaid, Markdown, or live React into a sandboxed panel ([ADR 0038](./docs/adr/0038-generative-ui-artifacts-two-mode.md)) | | [`craft`](./plugins/craft/) | skills · subagent | **On by default** — engineering rituals as user-only slash commands (`/grill`, `/standup`, `/code-review`, `/writing-skills`) + the `skill_writer` subagent; prompt-only | | [`plugin-devkit`](./plugins/plugin-devkit/) | tool · subagent · skill · workflow · view | The authoring kit + reference plugin — the agent can scaffold and build its own plugins | -| [`workflows`](./plugins/workflows/) | tools | Declarative multi-step subagent workflows (DAG recipes) | +| [`workflows`](./plugins/workflows/) | tools | Declarative multi-step subagent workflows (DAG recipes) — a step can carry `gate: human`, pausing for operator approval before it runs | | [`telegram`](./plugins/telegram/) | surface | Run the agent as a Telegram bot — the reference [communication plugin](./docs/guides/communication-plugins.md) | | [`github`](./plugins/github/) | tools | Read-only GitHub tools over the `gh` CLI | +| [`execute_code`](./plugins/execute_code/) | tool · settings | A Python interpreter the agent runs code in — on desktop, provision the one-click [managed runtime](./docs/guides/python-runtime.md) and the document skills (docx · xlsx · pptx · pdf) light up | +| [`coder`](./plugins/coder/) | tool · settings | Verifier-grounded code-solve (`coder_solve`) — an execution-grounded search ladder for testable coding tasks ([guide](./docs/guides/coder.md)) | +| [`friction`](./plugins/friction/) | tools | Friction log — the agent records its own missing/awkward tooling and confusing errors, so you can fix the sharp edges | +| [`orgchart`](./plugins/orgchart/) | view | Live diagram of the agent fleet — every agent a node, delegation edges drawn as they happen | | [`hello`](./plugins/hello/) | tool · skill · view | Minimal example — copy it to start your own | Integrations like **Discord**, **Slack** (Socket Mode `ChatAdapter`) and **Google** diff --git a/ROADMAP.md b/ROADMAP.md index fe0c7d94..723cb14c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -17,7 +17,8 @@ In-progress ref points at a closed issue — rotate shipped work into `## Shippe ## In progress -- **Image generation plugin (protobanana)** — generate → look → refine image workflows on the new media platform: tools save artifacts the chat renders inline, and the vision model critiques its own output. +- **Design-system alignment** — migrating the remaining bespoke console surfaces onto DS primitives as the design system grows (bottom sheet for the mobile session sheet, dense icon buttons — tracked in protoContent). + ## Shipped diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 9a029576..7716afad 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -20,7 +20,7 @@ export default defineConfig({ // docs/dev/ is the team's internal engineering area (handoffs + notes) — it // lives in the repo (committed, shared) but is NOT part of the published site. - srcExclude: ["dev/**"], + srcExclude: ["dev/**", "design/**"], head: [ ["link", { rel: "icon", type: "image/svg+xml", href: `${base}favicon.svg` }], @@ -142,6 +142,7 @@ export default defineConfig({ collapsed: false, items: [ { text: "Operator console (React/Tauri)", link: "/guides/react-tauri-ui" }, + { text: "Managed Python runtime (desktop)", link: "/guides/python-runtime" }, { text: "Command palette (⌘K)", link: "/guides/command-palette" }, { text: "Developer flags (gate pre-release features)", link: "/guides/developer-flags" }, { text: "Access from your phone (LAN / Tailscale)", link: "/guides/phone-access" }, diff --git a/docs/guides/index.md b/docs/guides/index.md index 62f35702..ab7664ef 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -78,6 +78,7 @@ Surface the agent to people — the operator console, or no UI at all. | Guide | When to read | |---|---| | [Operator console (React/Tauri)](/guides/react-tauri-ui) | You want the multi-chat React console and to package it for desktop | +| [Managed Python runtime (desktop)](/guides/python-runtime) | You're on the desktop app and `execute_code` / the document skills (docx · xlsx · pptx · pdf) need their one-click interpreter install | | [Command palette (⌘K)](/guides/command-palette) | You want the fast keyboard path to jump between surfaces + inline chat | | [Developer flags](/guides/developer-flags) | You want to merge a half-built feature behind a tiered flag (off/dev/beta/on) instead of a long-lived branch | | [Access from your phone (LAN / Tailscale)](/guides/phone-access) | You want to drive the agent from your phone — installable PWA over your LAN or tailnet, add-to-home-screen | diff --git a/docs/guides/python-runtime.md b/docs/guides/python-runtime.md new file mode 100644 index 00000000..86929706 --- /dev/null +++ b/docs/guides/python-runtime.md @@ -0,0 +1,74 @@ +# Managed Python runtime (desktop) + +On the **packaged desktop app** the server is a frozen binary — `sys.executable` *is* +protoAgent, not a Python interpreter — so [`execute_code`](/guides/plugins) has nothing +to run child code with. The **managed Python runtime** +([ADR 0094](../adr/0094-managed-python-runtime.md)) fixes that: a one-click, consented +download of a pinned CPython that the desktop app owns, plus the **document baseline** +([ADR 0092](../adr/0092-desktop-document-baseline-and-versioned-file-artifacts.md)) — +the libraries that let document skills produce real `.docx` / `.xlsx` / `.pptx` / `.pdf` +files. + +**Source runs never need this.** A `python -m server` / `uv run` instance spawns its own +interpreter; every status surface reports `needed: false` and stays hidden. This page is +desktop-only behavior. + +## What needs it + +- **`execute_code`** — the in-tree Python-interpreter plugin. On a frozen build its tool + registers either way, but calls return an actionable "runtime isn't installed yet" + notice until you provision. +- **Everything routed through `execute_code`** — above all the **Cowork document skills** + (docx / xlsx / pptx / reportlab-PDF). This is why the Cowork archetype declares + `requires: [python_runtime]` and the new-agent picker warns at choose-time + (see [Fleet § archetypes](/guides/fleet)). + +## Install it (once per machine) + +Two equivalent paths — both fetch a **hash-verified CPython 3.12.13** (the frozen +sidecar's own interpreter line, ~35 MB) and then pip-install the document baseline +(`apps/desktop/sidecar/requirements-docs.txt`) into the runtime's own site-packages: + +- **Console** — **Settings ▸ Tools** shows an install card while the runtime is missing: + one click, live progress (download → document libraries), done. The card renders + nothing once the runtime is present and current. +- **CLI** — `protoagent runtime install-python` (and `protoagent runtime list` shows + `python: not provisioned — …` / version + baseline state). + +The download is a deliberate consent point — ~130 MB on disk after the baseline lands — +so nothing auto-provisions. + +## How you find out before something fails + +- **Settings nav badge** — the **Tools** entry carries a warning dot whenever the + runtime needs attention (not provisioned, stale baseline, failed install; pulsing + while an install runs), so the state is visible while browsing, not mid-task. +- **Archetype choose-time warning** — picking an archetype that declares + `requires: [python_runtime]` (Cowork) shows a notice under the card grid when this + host's runtime isn't ready. +- **Actionable tool copy** — an `execute_code` call on an unprovisioned build returns + the fix ("Settings ▸ Tools, or `protoagent runtime install-python`") instead of a + bare error. + +## The baseline can go stale + +The runtime records a hash of the `requirements-docs.txt` it installed. When a release +changes the document pins, the status flips to `baseline_current: false` and the +surfaces above offer an **update** (re-runs the pip phase only) — the runtime itself +stays put. + +## Status & API + +`GET /api/runtime/python` returns `{python, install}`: + +| Key | Meaning | +|---|---| +| `needed` | this process would use it (frozen builds only) | +| `managed` / `managed_version` / `exe` | a working install is present, its version, its interpreter path | +| `baseline_installed` / `baseline_current` | document-library state vs the current pins | +| `supported` / `target_version` | can this platform/arch provision, and what an install fetches | + +`POST /api/runtime/python/install` starts the provisioning in the background (`202`; +poll the GET for phase + percent). Unsupported platform/arch combinations return the +banner state instead — `execute_code` (and the skills behind it) can't run on that +desktop build. diff --git a/docs/guides/react-tauri-ui.md b/docs/guides/react-tauri-ui.md index c9720c79..77930d44 100644 --- a/docs/guides/react-tauri-ui.md +++ b/docs/guides/react-tauri-ui.md @@ -133,6 +133,10 @@ parallel with engine startup** (#2203): the in-app UpdateNotice pulls that resul it mounts and opens the changelog modal if a newer build exists — so the prompt lands before the engine finishes booting, then the normal 10s-settle + 6h re-check cycle takes over. +On a frozen build, `execute_code` (and the document skills behind it) need the one-click +[managed Python runtime](/guides/python-runtime) — Settings ▸ Tools shows the install card +until it's provisioned. + On macOS, `spawn_sidecar` augments the sidecar's `PATH` with the user's login-shell `PATH` (via `$SHELL -ilc`, plus the Homebrew/local fallbacks) before spawning. A Finder/Dock launch otherwise inherits only `launchd`'s minimal `PATH`, so `npx`/`node`/ACP coding-agent adapters diff --git a/docs/index.md b/docs/index.md index 1ebfb248..307ee83b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,6 +21,8 @@ features: details: DuckDuckGo web search, URL fetch, safe calculator, and IANA-timezone clock — zero API keys, enough to demo a real research loop on a fresh clone. - title: A lean core, opt-in plugins details: Start small; add tools, skills, subagents, workflows, FastAPI routes, console dashboards, memory backends, and managed MCP servers as git-URL plugins (python -m server plugin install, pinned in plugins.lock) — without touching core. Telegram and the plugin-devkit ship in-tree; Discord, Google (Gmail+Calendar), and more install as official external plugins from the directory. + - title: Archetypes + real documents + details: Spin up agents from starter types — Cowork, Project Manager, Design System Engineer, or any bundle that declares one. Cowork's document skills produce real .docx/.xlsx/.pptx/.pdf via execute_code and the one-click managed Python runtime on desktop. - title: Release pipeline details: Dispatch prepare-release → semver bump PR → merge → tag → GHCR image → GitHub release → Discord embed. Flip the RELEASE_ENABLED repo variable to enable it on a fork. --- diff --git a/plugins/docs/nav.json b/plugins/docs/nav.json index a00b906b..b75c0dd1 100644 --- a/plugins/docs/nav.json +++ b/plugins/docs/nav.json @@ -183,6 +183,10 @@ "path": "guides/react-tauri-ui.md", "title": "Operator console (React/Tauri)" }, + { + "path": "guides/python-runtime.md", + "title": "Managed Python runtime (desktop)" + }, { "path": "guides/command-palette.md", "title": "Command palette (⌘K)" diff --git a/sites/marketing/data/roadmap.json b/sites/marketing/data/roadmap.json index a14a0fa1..0cbbb6bf 100644 --- a/sites/marketing/data/roadmap.json +++ b/sites/marketing/data/roadmap.json @@ -43,8 +43,8 @@ "status": "In progress", "items": [ { - "title": "Image generation plugin (protobanana)", - "detail": "generate → look → refine image workflows on the new media platform: tools save artifacts the chat renders inline, and the vision model critiques its own output.", + "title": "Design-system alignment", + "detail": "migrating the remaining bespoke console surfaces onto DS primitives as the design system grows (bottom sheet for the mobile session sheet, dense icon buttons — tracked in protoContent).", "refs": [] } ]