118 lines
6.4 KiB
Markdown
Executable File
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).
|