handler-ai 0.1.0__py3-none-any.whl

handler_harness/data/harnesses/claude-code/Containerfile

@@ -0,0 +1,27 @@
+# Claude Code harness image: toolbox + the ACP adapter for the Claude Agent SDK.
+# The SDK ships the native Claude Code binary as an npm optional dependency (one package per
+# platform); it is also linked as `claude`, the terminal program of `handler terminal` (D.16), so both
+# run the same version on the same history.
+#
+# Not pinned: every rebuild (`handler image rebuild claude-code`, or the web UI) installs the latest release.
+# What was installed is recorded in /usr/share/handler/version (contract B.6); the build fails if
+# the versions cannot be read, so a package layout change is noticed.
+ARG TOOLBOX_IMAGE=localhost/handler-ai-toolbox:latest
+FROM ${TOOLBOX_IMAGE}
+
+RUN npm install -g --no-fund --no-audit @agentclientprotocol/claude-agent-acp \
+    && npm cache clean --force \
+    && command -v claude-agent-acp \
+    && adapter=/usr/lib/node_modules/@agentclientprotocol/claude-agent-acp \
+    && sdk="$adapter/node_modules/@anthropic-ai/claude-agent-sdk" \
+    && acp_version="$(jq -er .version "$adapter/package.json")" \
+    && claude_version="$(jq -er .claudeCodeVersion "$sdk/package.json")" \
+    && for bin in "$adapter"/node_modules/@anthropic-ai/claude-agent-sdk-linux-*/claude; do \
+         "$bin" --version >/dev/null 2>&1 && ln -s "$bin" /usr/local/bin/claude && break; \
+       done \
+    && claude --version \
+    && mkdir -p /usr/share/handler \
+    && echo "Claude Code ${claude_version} (claude-agent-acp ${acp_version})" > /usr/share/handler/version \
+    && rm -rf /home/agent  # build-time npm logs (npm runs as root with HOME=/home/agent)
+
+LABEL org.opencontainers.image.title="handler-ai-claude-code"

handler_harness/data/harnesses/claude-code/harness.toml

@@ -0,0 +1,95 @@
+# Claude Code harness descriptor (contract B, handler.harness/v1).
+apiVersion = "handler.harness/v1"
+name = "claude-code"
+product = "Claude Code"
+image = "localhost/handler-ai-claude-code"  # no tag: launches use :latest (contract B.6)
+acpCommand = ["claude-agent-acp"]
+home = "/home/agent"
+
+# The hosts it reaches belong to what it runs on: the login below, or a provider (its endpoint).
+# A provider it can use speaks:
+providerProtocols = ["anthropic"]   # ANTHROPIC_BASE_URL + key + model (verified)
+
+modelOption = "model"   # ACP config option id (config options: mode, model, effort, fast)
+
+# User skills (verified: claude-agent-acp loads settingSources "user"): each skill of the
+# agent and its addons is mounted read-only at ~/.claude/skills/<folder name>.
+skillsDir = "~/.claude/skills"
+
+# MCP servers passed in ACP session/new (its addons'): claude-agent-acp
+# advertises mcpCapabilities http and sse; stdio is mandatory in ACP. It starts stdio servers at
+# session/new with its own environment, minus its token (verified 2026-09-26): mcpEnv "inherit".
+mcpTransports = ["stdio", "http", "sse"]
+
+[env]
+NODE_USE_ENV_PROXY = "1"     # Node's fetch only honours HTTPS_PROXY with this
+DISABLE_AUTOUPDATER = "1"    # the image is the unit of upgrade, not the container
+# Privacy (verified in the binary, 2.1.283): the strongest of its three levels. No telemetry,
+# Sentry error reports, GrowthBook feature flags, /feedback or update checks; only the API.
+CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
+CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY = "1"   # gated on its own, not by the line above
+
+# Settings and history: the agent's own (handler keeps them).
+# The login is not here: an account's token (below) reaches it as an env var.
+[stateSlots.config_dir]
+target = "~/.claude"
+kind = "dir"
+required = false
+
+[stateSlots.config_json]
+target = "~/.claude.json"
+kind = "file"
+required = false
+# Its terminal UI (`handler terminal`) onboards a new ~/.claude.json, and onboarding asks to log in
+# even with the account's token set (verified, 2.1.286): the account brings the login, so the
+# file starts onboarded.
+initial = "{\"hasCompletedOnboarding\": true}\n"
+
+# An account: a Claude subscription's long-lived token (verified 2026-09-30, Claude Code 2.1.285).
+# The person runs `claude setup-token` themselves (Anthropic's own sign-in, in their browser) and
+# gives handler the token it prints, or a reference to where they keep it: handler never runs the sign-in
+# nor reads its output (Anthropic's terms, D.9). A token lasts a year and has no refresh, so any
+# number of sandboxes can share it. (`/login` would leave ~/.claude/.credentials.json with a
+# refresh token instead, which several sandboxes sharing one account could invalidate for each
+# other.)
+[login]
+subscription = "Claude Pro or Max"
+# Unattended use (an automation's agent run): refused. A Claude subscription is for interactive
+# use by its owner (plan limits "assume ordinary, individual usage"): sessions you start and follow,
+# never runs nobody is there for (docs/dev/ui-ux.md "Vendors' terms").
+unattended = "refused"
+terms = "https://www.anthropic.com/legal/consumer-terms"
+checked = 2026-10-05
+token = "CLAUDE_CODE_OAUTH_TOKEN"
+tokenCommand = "claude setup-token"
+# its sign-in page may show a code to paste back into `claude setup-token` (when the browser
+# cannot call it back): that code is not the token, refused as "401 Invalid bearer token"
+tokenPrefix = "sk-ant-oat01-"
+tokenLifetimeDays = 365
+hosts = ["api.anthropic.com:443", "platform.claude.com:443"]
+help = "It is Claude Code's own sign-in, with your Claude subscription, for your own use (Anthropic's terms). Run it in a terminal where Claude Code is installed and sign in on the page it opens (a code that page shows goes back into that terminal), then give handler the token it prints at the end (sk-ant-oat01-…)."
+# The token says nothing of the subscription: Claude Code reads its plan from the env (verified,
+# 2.1.286: without it, "Claude API" and an API user's default model).
+plans = ["pro", "max", "team", "enterprise"]
+planEnv = "CLAUDE_CODE_SUBSCRIPTION_TYPE"
+
+# Neutral permission mode → ACP session mode (decision 4).
+[permissions]
+ask = { sessionMode = "default" }
+accept-edits = { sessionMode = "acceptEdits" }
+bypass = { sessionMode = "bypassPermissions" }
+
+# `handler terminal` (D.16): Claude Code's own terminal UI instead of the ACP adapter; the same binary
+# (the SDK's, linked by the Containerfile). The agent's settings reach it as flags.
+[terminal]
+command = ["claude"]
+modelFlag = "--model"
+mcpConfigFlag = "--mcp-config"
+instructionsFlag = "--append-system-prompt"   # the agent's instructions, after its own prompt
+[terminal.permissions]
+ask = ["--permission-mode", "default"]
+accept-edits = ["--permission-mode", "acceptEdits"]
+bypass = ["--dangerously-skip-permissions"]
+
+[accountConnectors]
+offEnv = { ENABLE_CLAUDEAI_MCP_SERVERS = "false" }   # verified: hides claude.ai connectors

handler_harness/data/harnesses/codex/Containerfile

@@ -0,0 +1,26 @@
+# Codex harness image: toolbox + codex-acp, the ACP adapter for OpenAI Codex. It starts
+# `codex app-server`; the Codex binary comes with it (its @openai/codex dependency).
+# codex-acp starts handler-codex instead (CODEX_PATH, harness.toml): that Codex with privacy config
+# overrides. `-c` beats config.toml; unset, analytics are on and metrics go to OpenAI (statsig).
+#
+# Not pinned: every rebuild (`handler image rebuild codex`, or the web UI) installs the latest release.
+# What was installed is recorded in /usr/share/handler/version (contract B.6); the build fails if
+# the versions cannot be read, so a package layout change is noticed.
+ARG TOOLBOX_IMAGE=localhost/handler-ai-toolbox:latest
+FROM ${TOOLBOX_IMAGE}
+
+RUN npm install -g --no-fund --no-audit @agentclientprotocol/codex-acp \
+    && npm cache clean --force \
+    && command -v codex-acp \
+    && adapter=/usr/lib/node_modules/@agentclientprotocol/codex-acp \
+    && test -f "$adapter/node_modules/@openai/codex/bin/codex.js" \
+    && printf '#!/bin/sh\nexec node %s -c analytics.enabled=false -c feedback.enabled=false -c check_for_update_on_startup=false -c otel.metrics_exporter=none "$@"\n' \
+        "$adapter/node_modules/@openai/codex/bin/codex.js" > /usr/local/bin/handler-codex \
+    && chmod 755 /usr/local/bin/handler-codex \
+    && acp_version="$(jq -er .version "$adapter/package.json")" \
+    && codex_version="$(jq -er .version "$adapter/node_modules/@openai/codex/package.json")" \
+    && mkdir -p /usr/share/handler \
+    && echo "Codex ${codex_version} (codex-acp ${acp_version})" > /usr/share/handler/version \
+    && rm -rf /home/agent  # build-time npm logs (npm runs as root with HOME=/home/agent)
+
+LABEL org.opencontainers.image.title="handler-ai-codex"

handler_harness/data/harnesses/codex/harness.toml

@@ -0,0 +1,103 @@
+# OpenAI Codex harness descriptor (contract B, handler.harness/v1). ACP through the codex-acp
+# adapter, which drives `codex app-server`.
+apiVersion = "handler.harness/v1"
+name = "codex"
+product = "Codex"
+image = "localhost/handler-ai-codex"  # no tag: launches use :latest (contract B.6)
+acpCommand = ["codex-acp"]
+home = "/home/agent"
+
+# The hosts it reaches belong to what it runs on: the login below, or a provider (its endpoint).
+# A provider it can use speaks:
+providerProtocols = ["responses"]
+
+# ACP config options (codex-acp): mode, collaboration_mode, model, reasoning_effort, fast-mode.
+modelOption = "model"
+
+# User skills (Codex loads $CODEX_HOME/skills, CODEX_HOME = ~/.codex): each skill of the
+# agent and its addons is mounted read-only at ~/.codex/skills/<folder name>.
+skillsDir = "~/.codex/skills"
+# MCP servers of session/new: codex-acp advertises mcpCapabilities http (no sse) and hands them to
+# Codex, which starts stdio ones with a reduced environment (HOME, PATH, USER, LANG… and the
+# entry's env): "sandbox", render wraps them with handler-sandbox-env.
+mcpTransports = ["stdio", "http"]
+mcpEnv = "sandbox"
+
+# Codex writes its state under ~/.codex (auth.json after an API-key login, sessions, logs,
+# its sqlite state): writable, including when files are mounted inside it.
+writablePaths = ["~/.codex"]
+
+[env]
+CODEX_HOME = "/home/agent/.codex"
+NO_BROWSER = "1"   # headless: no browser ChatGPT login among the ACP auth methods
+# Without a ChatGPT login (auth_json), session/new logs in with the provider's key instead of
+# answering auth_required.
+DEFAULT_AUTH_REQUEST = '{"methodId": "api-key"}'
+# codex-acp starts `$CODEX_PATH app-server`: handler-codex is Codex with privacy overrides (analytics,
+# feedback uploads, update check and metrics to ab.chatgpt.com off; see the Containerfile). They
+# are config keys, not env: Codex has no env switch for them.
+CODEX_PATH = "handler-codex"
+
+# Codex's config.toml (model, model_provider, [model_providers.*] for a local model…). Codex
+# rewrites it (e.g. trusted projects): copied, not mounted; changes discarded.
+[configFiles.config_toml]
+target = "~/.codex/config.toml"
+description = "Codex config.toml"
+seed = true
+
+# Model metadata for models Codex does not know (a local model): context window, reasoning
+# levels, tools. config.toml points at it: model_catalog_json =
+# "~/.codex/model-catalog.json". Without it, Codex warns and uses fallback metadata.
+[configFiles.model_catalog_json]
+target = "~/.codex/model-catalog.json"
+description = "Codex model catalog (model_catalog_json)"
+
+# The system prompt, replacing the model's (config.toml: model_instructions_file =
+# "~/.codex/instructions.md"). For a model in model_catalog_json, which has none of its own.
+[configFiles.instructions_md]
+target = "~/.codex/instructions.md"
+description = "Codex system prompt (model_instructions_file)"
+
+# Credentials of a ChatGPT login (the account's, see [login]). Codex refreshes the tokens in it,
+# so it is bound writable.
+[stateSlots.auth_json]
+target = "~/.codex/auth.json"
+kind = "file"
+required = false
+credential = true
+
+# Session history (Codex writes its rollouts to $CODEX_HOME/sessions/YYYY/MM/DD/*.jsonl). Per
+# session: the daemon binds it to the session's own folder (contracts F.2), so a stopped session
+# can be resumed with ACP `session/load`.
+[stateSlots.sessions]
+target = "~/.codex/sessions"
+kind = "dir"
+required = false
+perSession = true
+
+# An account: a ChatGPT plan (verified 2026-09-30, Codex 0.159.2). `codex login` (on the host,
+# D.9) opens the sign-in page, which comes back to it on localhost. Its credential store is the OS
+# keyring when there is one, so it is told to write the file, in CODEX_HOME.
+[login]
+subscription = "ChatGPT"
+# Unattended use (an automation's agent run): its terms not read yet.
+unattended = "check-terms"
+terms = "https://openai.com/policies/terms-of-use/"
+command = ["npx", "--yes", "@openai/codex", "-c", "cli_auth_credentials_store=file", "login"]
+env = { CODEX_HOME = "{dir}" }
+file = "auth_json"
+hosts = ["chatgpt.com:443", "auth.openai.com:443"]
+help = "Sign in on the page it opens (or the link it prints)."
+
+# Neutral permission mode → ACP session mode (codex-acp: read-only, agent, agent-full-access).
+# None asks before an edit: "read-only" (despite its id) edits the project and runs commands in
+# Codex's workspace-write sandbox without asking, and asks the user before anything outside it;
+# that is "accept-edits". "ask" is left out: an agent asking for it is refused. ("agent" lets
+# a model approve instead of the user: not mapped.) "agent-full-access" never asks and drops
+# Codex's own sandbox (the container is the boundary).
+# In a container Codex's sandbox cannot start (bubblewrap needs user namespaces, verified
+# 2026-09-27 under the default `strict` confinement): in "read-only", each sandboxed command or
+# edit fails and Codex asks to run it unsandboxed, so it asks more, never less.
+[permissions]
+accept-edits = { sessionMode = "read-only" }
+bypass = { sessionMode = "agent-full-access" }

handler_harness/data/harnesses/pi/Containerfile

@@ -0,0 +1,27 @@
+# pi harness image: toolbox + the pi coding agent + pi-acp, its ACP adapter (spawns `pi --mode rpc`)
+# + pi-mcp-adapter, the pi extension that gives it MCP servers. pi-acp starts handler-pi instead of pi
+# (PI_ACP_PI_COMMAND, harness.toml): pi with that extension, which reads the servers `render`
+# writes to ~/.config/mcp/mcp.json.
+#
+# Not pinned: every rebuild (`handler image rebuild pi`, or the web UI) installs the latest releases.
+# What was installed is recorded in /usr/share/handler/version (contract B.6); the build fails if
+# the versions cannot be read, so a package rename is noticed.
+ARG TOOLBOX_IMAGE=localhost/handler-ai-toolbox:latest
+FROM ${TOOLBOX_IMAGE}
+
+RUN npm install -g --no-fund --no-audit @earendil-works/pi-coding-agent pi-acp pi-mcp-adapter \
+    && npm cache clean --force \
+    && command -v pi \
+    && command -v pi-acp \
+    && modules=/usr/lib/node_modules \
+    && test -f "$modules/pi-mcp-adapter/index.ts" \
+    && printf '#!/bin/sh\nexec pi --extension %s "$@"\n' "$modules/pi-mcp-adapter" > /usr/local/bin/handler-pi \
+    && chmod 755 /usr/local/bin/handler-pi \
+    && pi_version="$(jq -er .version "$modules/@earendil-works/pi-coding-agent/package.json")" \
+    && acp_version="$(jq -er .version "$modules/pi-acp/package.json")" \
+    && mcp_version="$(jq -er .version "$modules/pi-mcp-adapter/package.json")" \
+    && mkdir -p /usr/share/handler \
+    && echo "pi ${pi_version} (pi-acp ${acp_version}, pi-mcp-adapter ${mcp_version})" > /usr/share/handler/version \
+    && rm -rf /home/agent  # build-time npm logs (npm runs as root with HOME=/home/agent)
+
+LABEL org.opencontainers.image.title="handler-ai-pi"

handler_harness/data/harnesses/pi/harness.toml

@@ -0,0 +1,65 @@
+# pi harness descriptor (contract B, handler.harness/v1). ACP through the pi-acp adapter.
+apiVersion = "handler.harness/v1"
+name = "pi"
+product = "pi"
+image = "localhost/handler-ai-pi"  # no tag: launches use :latest (contract B.6)
+acpCommand = ["pi-acp"]
+home = "/home/agent"
+
+# No account: pi has no subscription of its own (its /login signs in to other vendors'), so it runs
+# on a provider, whose endpoint is the host it reaches. A provider it can use speaks:
+providerProtocols = ["openai-chat"]   # models.json + settings.json
+
+# ACP config options (pi-acp): model, thought_level. Its ACP session modes are thinking levels.
+modelOption = "model"
+
+# User skills (verified: pi-acp and pi load <agent-dir>/skills, agent dir = ~/.pi/agent): each
+# skill of the agent and its addons is mounted read-only at ~/.pi/agent/skills/<folder name>.
+skillsDir = "~/.pi/agent/skills"
+# MCP servers (its addons'): pi has no MCP of its own and pi-acp ignores
+# session/new's mcpServers. The image runs pi with the pi-mcp-adapter extension (handler-pi), which
+# reads ~/.config/mcp/mcp.json: render writes the servers there. It starts stdio servers with pi's
+# whole environment, provider keys included ("sandbox": render wraps them with handler-sandbox-env to
+# drop them); http servers fall back to SSE.
+mcpTransports = ["stdio", "http", "sse"]
+mcpEnv = "sandbox"
+mcpConfigFile = "~/.config/mcp/mcp.json"
+
+# pi writes its state under ~/.pi/agent (sessions, trust.json, settings.json) and pi-acp its
+# session map under ~/.pi/pi-acp: writable, including when files are mounted inside it.
+writablePaths = ["~/.pi"]
+
+[env]
+NODE_USE_ENV_PROXY = "1"     # Node's fetch only honours HTTPS_PROXY with this
+PI_ACP_PI_COMMAND = "handler-pi" # pi with the pi-mcp-adapter extension (see the Containerfile)
+PI_SKIP_VERSION_CHECK = "1"  # the image is the unit of upgrade (and pi.dev is not in egress)
+PI_TELEMETRY = "0"           # no install report to pi.dev, no attribution headers to providers
+PI_OFFLINE = "1"             # no startup network: version check, model catalog refresh from pi.dev,
+                             # fd/rg downloads (the toolbox has them), package update checks
+
+# pi's settings.json (defaultProvider, defaultModel, quietStartup…). pi rewrites it (e.g. the
+# model chosen over ACP): copied, not mounted; changes discarded.
+[configFiles.settings_json]
+target = "~/.pi/agent/settings.json"
+description = "pi settings.json"
+seed = true
+
+# Custom providers and models, e.g. a local OpenAI-compatible endpoint.
+[configFiles.models_json]
+target = "~/.pi/agent/models.json"
+description = "pi models.json"
+
+# Session history (verified: pi writes <agent dir>/sessions/<cwd>/*.jsonl, and pi-acp's
+# session/load, when its ~/.pi/pi-acp session map does not know the id, finds the file by scanning
+# that folder). Per session: the daemon binds it to the session's own folder (contracts F.2), so a
+# stopped session can be resumed with ACP `session/load`. A settings.json `sessionDir` defeats it.
+[stateSlots.sessions]
+target = "~/.pi/agent/sessions"
+kind = "dir"
+required = false
+perSession = true
+
+# pi never asks before a tool call (docs/security.md: "it does not ask for approval"), so only
+# "bypass" is honest. "ask" and "accept-edits" are left out: an agent asking for them is refused.
+[permissions]
+bypass = {}

handler_harness/data/harnesses/vibe/Containerfile

@@ -0,0 +1,19 @@
+# Mistral Vibe harness image: toolbox + mistral-vibe (speaks ACP natively via `vibe-acp`).
+#
+# Not pinned: every rebuild (`handler image rebuild vibe`, or the web UI) installs the latest release.
+# What was installed is recorded in /usr/share/handler/version (contract B.6).
+ARG TOOLBOX_IMAGE=localhost/handler-ai-toolbox:latest
+FROM ${TOOLBOX_IMAGE}
+
+ENV UV_TOOL_DIR=/opt/uv-tools \
+    UV_TOOL_BIN_DIR=/usr/local/bin \
+    UV_PYTHON_INSTALL_DIR=/opt/uv-python
+RUN uv tool install --python 3.12 mistral-vibe \
+    && command -v vibe-acp \
+    && version="$(uv tool list | sed -n 's/^mistral-vibe v//p')" \
+    && test -n "$version" \
+    && mkdir -p /usr/share/handler \
+    && echo "Mistral Vibe ${version}" > /usr/share/handler/version \
+    && rm -rf /home/agent  # build-time caches (uv runs as root with HOME=/home/agent)
+
+LABEL org.opencontainers.image.title="handler-ai-vibe"

handler_harness/data/harnesses/vibe/harness.toml

@@ -0,0 +1,96 @@
+# Mistral Vibe harness descriptor (contract B, handler.harness/v1).
+apiVersion = "handler.harness/v1"
+name = "vibe"
+product = "Mistral Vibe"
+image = "localhost/handler-ai-vibe"  # no tag: launches use :latest (contract B.6)
+acpCommand = ["vibe-acp"]
+home = "/home/agent"
+
+# The hosts it reaches belong to what it runs on: the login below, or a provider (its endpoint).
+# A provider it can use speaks:
+providerProtocols = ["openai-chat"]   # [[providers]] + [[models]] in config.toml
+
+modelOption = "model"   # ACP config option id (probed: mode, model, thinking)
+
+# User skills (verified: vibe GLOBAL_SKILLS_DIR = VIBE_HOME/skills): each skill of the agent
+# and its addons is mounted read-only at ~/.vibe/skills/<folder name>.
+skillsDir = "~/.vibe/skills"
+# MCP servers of session/new (verified 2026-09-26): vibe-acp starts stdio ones at session/new, with
+# only HOME, PATH and the entry's env ("sandbox": render wraps them with handler-sandbox-env so they
+# get the sandbox's environment). It advertises no mcpCapabilities: no http or sse.
+mcpTransports = ["stdio"]
+mcpEnv = "sandbox"
+
+# Vibe writes its own state under ~/.vibe (trusted_folders.toml, logs…): it must be writable by
+# the agent, including when files are mounted inside it (config.toml, skills).
+writablePaths = ["~/.vibe"]
+
+[env]
+VIBE_CONFIG_DIR = "/home/agent/.vibe"
+# Privacy (VIBE_* env beats config.toml, verified in mistral-vibe 2.25.8): enable_telemetry
+# gates its usage events, Sentry error reports and GrowthBook experiments (and OTel traces).
+VIBE_ENABLE_TELEMETRY = "false"
+VIBE_ENABLE_UPDATE_CHECKS = "false"   # the image is the unit of upgrade
+VIBE_ENABLE_AUTO_UPDATE = "false"
+
+# Vibe's configuration (providers, models, active_model, MCP servers…), e.g. to use a local
+# model. Written from the agent's provider (handler_harness/providers.py), or given whole by the
+# provider's [files.vibe] (a host file, an env var or inline). Without a provider (a Mistral
+# account) Vibe uses its defaults.
+[configFiles.config_toml]
+target = "~/.vibe/config.toml"
+description = "Vibe config.toml"
+seed = true   # Vibe rewrites it (e.g. model chosen over ACP): copied, not mounted; changes discarded
+
+# Vibe keeps the rest of its state in the (ephemeral) home.
+
+# Session history (verified: vibe.core.paths.SESSION_LOG_DIR = ~/.vibe/logs/session). Per
+# session: the daemon binds it to the session's own folder (contracts F.2), so a stopped session
+# can be resumed with ACP `session/load` and an agent sees only its own history.
+[stateSlots.sessions]
+target = "~/.vibe/logs/session"
+kind = "dir"
+required = false
+perSession = true
+
+# The key Vibe's sign-in registers, in the dotenv file it reads at start (the account's, see
+# [login]). Vibe does not rewrite it.
+[stateSlots.env_file]
+target = "~/.vibe/.env"
+kind = "file"
+required = false
+readOnly = true
+credential = true
+
+# An account: a Mistral account's Vibe key (verified 2026-09-30, mistral-vibe 2.25.8). `vibe
+# --setup` (on the host, D.9) opens the sign-in page; its home is handler's folder, and without a
+# keyring the key goes to its .env (else to the desktop's keyring).
+[login]
+subscription = "Mistral"
+# Unattended use (an automation's agent run): its terms not read yet.
+unattended = "check-terms"
+terms = "https://mistral.ai/terms"
+command = ["uvx", "--python", "3.12", "--from", "mistral-vibe", "vibe", "--setup"]
+env = { VIBE_HOME = "{dir}", PYTHON_KEYRING_BACKEND = "keyring.backends.fail.Keyring" }
+file = "env_file"
+hosts = ["api.mistral.ai:443"]
+help = "Choose to sign in with your Mistral account: its page opens in your browser. Then quit."
+
+# Neutral permission mode → ACP session mode (probed: ask, plan, accept-edits, auto-approve).
+[permissions]
+ask = { sessionMode = "ask" }
+accept-edits = { sessionMode = "accept-edits" }
+bypass = { sessionMode = "auto-approve" }
+
+# D.16: the harness's own terminal program (`handler terminal`). No model or MCP-config flags: VIBE_*
+# env vars override its config.toml (verified mistral-vibe 2.25.8; env MCP servers are added to
+# the config's, by name); the model is an alias of its config, as over ACP.
+[terminal]
+command = ["vibe"]
+modelEnv = "VIBE_ACTIVE_MODEL"
+mcpServersEnv = "VIBE_MCP_SERVERS"
+[terminal.permissions]
+ask = ["--agent", "ask"]
+accept-edits = ["--agent", "accept-edits"]
+bypass = ["--agent", "auto-approve"]
+

handler_harness/data/toolbox/Containerfile

@@ -0,0 +1,56 @@
+# handler toolbox — the development environment agents work in. Yours to edit (README.md).
+#
+# Harness-independent: every harness and addon image is built FROM this one, so Claude Code,
+# Vibe, … all get the same tools. Add tools here, then rebuild the toolbox (web UI or
+# `handler image rebuild toolbox`): every harness and addon image is rebuilt on it and checked before any
+# switches.
+#
+# Runtime conventions (set by handler-sandbox-podman, contract A3):
+#   - runs as the host user's uid/gid (keep-id), HOME=/home/agent on a private tmpfs;
+#   - toolchain state (~/.cargo, ~/.m2, ~/.npm, ~/.cache, ~/.local, podman's images, …) comes from
+#     the cache mounts declared in toolbox.toml (each project chooses whether they are shared),
+#     so nothing user-specific is baked in here;
+#   - chromium (and fonts) for web development and the playwright addon
+#     (docs/dev/design/browser.md §6): its own sandbox cannot start under `strict`, so it runs
+#     with --no-sandbox (the container is the boundary); headed only when the sandbox is given a
+#     display (contract A.6);
+#   - wl-clipboard: the clipboard of the display, when there is one (A.6), e.g. a harness's
+#     terminal UI pasting an image (`wl-paste`);
+#   - podman is here for podman in podman, which works only when the agent asks for
+#     `confinement = "nested"` (or `privileged`, contract A.5); the launcher then provides
+#     /etc/subuid, /etc/subgid and the inner podman's configuration (fuse-overlayfs, cgroupfs,
+#     events and `podman logs` in files: no systemd nor journald). Under the default `strict` it
+#     cannot start containers.
+FROM docker.io/library/archlinux:latest
+
+RUN pacman -Syu --noconfirm --needed \
+        base-devel gcc pkgconf make \
+        git openssh ca-certificates curl wget unzip zip tar \
+        ripgrep fd jq less which diffutils findutils procps-ng \
+        jdk25-openjdk maven \
+        python python-pip uv \
+        nodejs npm \
+        rustup sccache \
+        podman fuse-overlayfs passt \
+        chromium ttf-liberation ttf-dejavu \
+        wl-clipboard \
+    && pacman -Scc --noconfirm
+
+# Inner rootless podman (`nested`): newuidmap/newgidmap need their file capabilities, which
+# pacman's install hook cannot set during an image build.
+RUN setcap cap_setuid=ep /usr/bin/newuidmap \
+    && setcap cap_setgid=ep /usr/bin/newgidmap
+
+# Bun is not in the Arch repositories: official installer, into /usr/local (not ~/.bun, which is
+# a cache mount at runtime).
+ARG BUN_VERSION=bun-v1.4.2
+RUN curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash -s "${BUN_VERSION}" \
+    && rm -rf /usr/local/install
+
+ENV LANG=C.UTF-8 \
+    HOME=/home/agent \
+    PATH=/home/agent/.cargo/bin:/home/agent/.local/bin:/home/agent/.bun/bin:/usr/local/bin:/usr/bin:/usr/sbin \
+    JAVA_HOME=/usr/lib/jvm/default
+
+LABEL org.opencontainers.image.title="handler-ai-toolbox" \
+      org.opencontainers.image.description="Development environment for handler agent sandboxes"

handler_harness/data/toolbox/README.md

@@ -0,0 +1,24 @@
+# toolbox — `localhost/handler-ai-toolbox:latest`
+
+The development environment agents work in, **independent of the harness**: every harness
+and addon image is built `FROM` it, so all agents get the same tools. This folder is yours: handlerd
+copied it to `~/.config/handler-ai/toolbox/` from its default on first start and never changes it
+afterwards.
+
+Default contents (Arch Linux): base-devel, gcc, pkgconf, git, JDK 25 + Maven, Python + pip + uv,
+Node + npm, Bun, rustup + sccache, ripgrep, fd, jq, curl, Chromium, wl-clipboard (the display's
+clipboard, contract A.6), podman.
+
+- Add a tool to `Containerfile`, then `handler image rebuild toolbox` (or **Rebuild** in the web UI): it
+  also updates the system packages, rebuilds every harness and addon image on top, checks them,
+  then switches them all, or none.
+- Toolchain *state* is not baked in: `toolbox.toml` declares the caches (`~/.cargo`, `~/.rustup`,
+  `~/.bun`, `~/.m2`, `~/.npm`, `~/.cache`, `~/.local`, inner podman's image store) mounted at
+  runtime, kept per project or global as each project chooses (contract D.8). A new toolchain with state to keep adds its table there
+  (`target`, `about`, `general` for a folder any tool writes to), or Settings → Caches does.
+
+What Handler needs from it (contract B.6): a glibc system with `sh`; what the harness and addon
+recipes install with (`npm`, `uv`, `jq`); `python3` for harnesses whose MCP servers run through
+`handler-sandbox-env`; `chromium` for the playwright addon; podman with setcap'd
+`newuidmap`/`newgidmap` only for agents with `confinement = "nested"`. Something missing shows as
+a failed rebuild: nothing switches.

handler_harness/data/toolbox/toolbox.toml

@@ -0,0 +1,41 @@
+# What the toolbox declares besides its image (contract B.6).
+#
+# caches: the toolchains' state kept between sessions, one table per cache: target, the home
+# path it is mounted at; about, what it holds; general = true for a folder any tool writes to
+# (~/.cache), not one tool's. Each project chooses whether its agents keep their own, use the
+# global ones with other projects (a write channel between projects), or get none (D.8).
+
+[caches.cargo]
+target = "~/.cargo"
+about = "Rust crates, and the commands cargo installs (on PATH)"
+
+[caches.rustup]
+target = "~/.rustup"
+about = "Rust toolchains"
+
+[caches.bun]
+target = "~/.bun"
+about = "Bun's packages, and the commands it installs (on PATH)"
+
+[caches.m2]
+target = "~/.m2"
+about = "Maven packages"
+
+[caches.npm]
+target = "~/.npm"
+about = "npm packages"
+
+[caches.cache]
+target = "~/.cache"
+about = "What tools cache: uv and pip packages, Playwright's browsers…"
+general = true
+
+[caches.local]
+target = "~/.local"
+about = "What is installed for the user: uv's tools and Pythons, pip --user, pipx; their commands are on PATH"
+general = true
+
+[caches.podman]
+target = "~/.local/share/containers/storage"
+about = "Container images and build layers (agents that run containers)"
+general = true

handler_harness/images.py

@@ -0,0 +1,62 @@
+"""Harness and addon images: their names, how each is built, where it records its version.
+
+Image layering (docs/dev/code-map.md):
+    images/toolbox/Containerfile    → localhost/handler-ai-toolbox:<tag>  (dev tools)
+    harnesses/<name>/Containerfile  → <descriptor.image>:<tag>  (the agent, FROM the toolbox)
+    addons/<name>/Containerfile     → <manifest.image>:<tag>    (a tool, built in the toolbox,
+                                                                 shipped FROM scratch, G.1)
+
+Tags (contract B.6): agents launch `:latest`, the only tag. A rebuild (handlerd, D.4) builds an
+untagged image from the files on disk, checks it, then tags it `:latest`. Harness recipes
+are not version-pinned: a rebuild installs the latest release and the image records what it got
+in IMAGE_VERSION_FILE.
+
+Only data: the runtime builds and queries images (sandbox's `image` verbs, A.7, run by handlerd).
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from handler_contracts import ADDON_VERSION_FILE, IMAGE_VERSION_FILE
+
+from .addons import Addon
+from .catalog import Harness, toolbox_dir
+
+TOOLBOX = "localhost/handler-ai-toolbox"
+LATEST = "latest"
+
+
+def ref(image: str, tag: str) -> str:
+    return f"{image}:{tag}"
+
+
+@dataclass(frozen=True)
+class Recipe:
+    """What a rebuild builds (D.4, G.4), for the runtime's `image build`."""
+
+    context: Path  # holds the Containerfile
+    build_args: dict[str, str]
+    pull: bool  # pull the base image again: system updates
+    no_cache: bool  # every step runs again: the agent's or tool's latest release
+    no_intermediate: bool  # keep only the final image (an addon's build stage would stay behind)
+
+
+def toolbox_recipe() -> Recipe:
+    return Recipe(toolbox_dir(), {}, pull=True, no_cache=True, no_intermediate=False)
+
+
+def recipe(unit: Harness | Addon, toolbox: str) -> Recipe:
+    """A harness or an addon image, FROM the toolbox (a reference or an image id)."""
+    return Recipe(
+        unit.directory,
+        {"TOOLBOX_IMAGE": toolbox},
+        pull=False,
+        no_cache=True,
+        no_intermediate=isinstance(unit, Addon),
+    )
+
+
+def version_file(unit: Harness | Addon) -> str:
+    """Where the image records what it installed: B.6 for a harness; an addon's `version` (G.1) is
+    at the root of its image, which is mounted at its mount path."""
+    return f"/{ADDON_VERSION_FILE}" if isinstance(unit, Addon) else IMAGE_VERSION_FILE