Files
obsidian-vault/personal/projects/archive/execution-broker-repo-cleanup-2026-10-16/README.md
T

118 lines
6.4 KiB
Markdown
Executable File

# Архив исходника Broker
Историческая копия до очистки репозитория 2026-10-16. Источник: `mallexxx/execution-broker`, commit `ae92c15d31c8396789765cebf82f7971d6f4cb12`, файл `README.md`. Старые статусы и deployment pins ниже не заменяют актуальную [[personal/projects/balda/execution-broker|эксплуатационную карточку]].
---
# Execution Broker
Execution Broker runs Balda tasks in disposable Docker workers or Virfield macOS
VMs. Callee executes the workflow; a separate Prism adapter owns the durable
Beads Story. Balda receives progress, asks the user for approval, and reports the
result. Provider credentials remain outside plugin packages and VM images.
**Release candidate:** use the [support matrix](docs/support.md) to select a
verified deployment. A Docker smoke test does not qualify Docker coding agents,
and installation does not configure access to managed production hosts.
The GitHub `main` branch is the source of truth for product code and public
documentation. The plugin version is defined in
[`plugins/execution-broker/plugin.json`](plugins/execution-broker/plugin.json);
[`docs/support.md`](docs/support.md) records tested deployment boundaries.
Candidate source is not a published release until the release procedure passes.
Runs can consume retained artifacts from an earlier run in the same session using
the exact source run, name and SHA256. Broker holds the bytes during the dependency;
Runner verifies them before execution and exposes `$BROKER_INPUT_DIR`. See the
[input contract](docs/protocol.md#artifact-inputs) for limits and the required
worker protocol. Artifact inputs do not install a toolchain or change its policy.
[Immutable repository caching](docs/repository-cache.md) and [safe environment
changes](docs/environment-changes.md) use operator policy and execution/v3.
An agent can select an operator-approved [tooling profile](docs/tooling.md) for
Make/C/C++, Python, Node, JVM or other stacks. Recipes supply checked archives,
reviewed Linux image packages or preinstalled guest tools and report their actual
versions. Adding a tool does not require a Broker code change. A missing profile
or failed prerequisite stops before implementation. Dependencies discovered later
use an explicitly authored safe checkpoint and approved environment continuation.
## Install the Balda plugin
The repository and binary archives include an Agent Plugins package and a Balda
marketplace index. After connecting Broker and Prism, open Balda's Backoffice
**Operations → Plugins → Marketplaces**, add the repository or extracted archive
directory, and refresh it. Review the exact `execution-broker` revision, then
select **Install plugin**.
In a new conversation, use `/execute <task>` or
`/skill execution-broker:execution-broker <task>`. A chat transport may require
mentioning the bot. Existing sessions keep their old capability snapshot until
reset. See [Balda setup](integrations/balda/README.md) for service credentials,
event routing, upgrades and removal.
## Start a smoke deployment
Requirements: Docker Engine with Compose, Python 3.12+, Git, and a private Docker
network shared with Balda. Source builds also require Go 1.26.9+; the test suite
requires Node.js 22+. The example
builds Linux ARM64 workers; set `TARGETARCH=amd64` and pass `amd64` to the two
helper scripts on an AMD64 Docker host.
```sh
python3 -m pip install -r requirements-tools.txt
make check build linux
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
./scripts/build-callee.sh "$PWD/.build/linux/broker-callee"
./scripts/fetch-beads.sh arm64
python3 scripts/worker-config.py
docker build -f deploy/Dockerfile.runner -t execution-broker-worker:local .
python3 scripts/init-deployment.py --directory ./state/deploy \
--worker-image "$(docker image inspect execution-broker-worker:local --format '{{.Id}}')"
export BROKER_CONFIG_DIR="$PWD/state/deploy"
export BALDA_NETWORK=balda_default # replace with the existing Balda network
# Use docker-compose instead if your installation provides the standalone CLI.
docker compose -p execution-broker -f deploy/compose.yaml up -d --build
.build/bin/executionctl --token-file "$BROKER_CONFIG_DIR/broker.token" --operation tools
```
For a binary installation, extract the **Linux** archive matching Docker's CPU,
run `scripts/prepare-binary-deployment.sh`, and continue at `fetch-beads.sh`.
Docker always requires Linux binaries, including when its host runs macOS.
Use a native `executionctl` from your host archive for the final diagnostic
command; `.build/bin/executionctl` is the source-build output.
The macOS archive provides native operator and VM binaries.
The initial configuration allows only the deterministic `smoke/story` fixture
and its pinned repository. Configure reviewed profiles and repository allowlists
before enabling coding. [Deployment profiles](docs/deployment.md) explain macOS,
provider credentials and signed managed-host plans.
## Components
| Component | Responsibility |
|---|---|
| `execution-broker` | Admission, leases, event journal, Human responses, artifacts and notification outbox |
| `execution-runner` | Worker-local checkout, Callee execution, cancellation and artifact collection |
| `execution-worker` | Restricted Docker gateway; the only service with the Docker socket |
| `execution-host-runner` | Fixed, signed host operations and bounded rollback |
| `execution-prism-adapter` | Story/Task lifecycle and idempotent Beads projection |
| `execution-credentials` | Encrypted persistent OAuth identity, issuance and checkpointing |
| `executionctl` | MCP/HTTP diagnostics and operator plan signing |
Broker does not interpret workflow graphs or write Beads. Requests cannot supply
host paths, shell commands or Docker options. Worker configuration, workflow
versions, repository access and agent profiles belong to the operator.
## Documentation
- [Installation and profiles](docs/deployment.md), [Balda integration](integrations/balda/README.md)
- [Protocol and guarantees](docs/protocol.md), [supported configurations](docs/support.md)
- [Operations](docs/operations.md), [coordinated recovery](docs/recovery.md)
- [Executor profiles and enrollment](docs/executors.md)
- [Credential lifecycle](docs/credentials.md), [security](docs/security.md)
- [Testing](docs/testing.md), [release procedure](docs/releasing.md)
MIT licensed. Dependency licenses and inventories are included in every binary
archive; see [third-party notices](THIRD_PARTY_NOTICES.md).