简体中文： 阅读中文镜像
Audience: contributors · Status: current
Why BuildMax is built the way it is. These are rationale, not user documentation — when a design ships something configurable, the user-facing half lives in the manual or ../reference/, and the design record keeps the trade-offs and the open gaps.
Documents use stable, semantic filenames. The index supplies their lifecycle and reading order; filenames do not encode chronology or roadmap priority.
Durable product decisions that guide more than one roadmap phase.
| Document | Scope |
|---|---|
| Product vision | Long-range product model, ownership boundaries, and rules for future bets |
| Surface positioning | How Agent Core, CLI, Desktop, and Portal relate |
| Agent execution and Task threads | Agent definitions execute directly through Space-owned Task/TaskRun threads; Conversation is an optional foreground origin, not an execution parent |
| Orchestration and continuity decisions | Decision record over the recent proposals: Task workspace checkpoints is the single continuity record, the ownership boundary is renamed to Space, structured output joins the roadmap, and the delegation/Assistant question is deferred |
| Task workspace checkpoints | Planned Task continuity contract: workspace/ is the sole Agent-writable checkpoint root, Space files seed a private Task fork, buildmax-home/ is reconstructed from typed state and immutable Plugin environment revisions, and Pod storage remains scratch |
Work tracked by ROADMAP.md. Plans can be partly implemented; their status must say what is shipped and what remains. When a plan is complete, move durable decisions into a subsystem specification or the architecture reference, then delete the plan.
| Document | Priority | Current state |
|---|---|---|
| Agent Core trust harness | P0.5 | Hooks and sandbox worker hardening (surface selection, process limits, downgrade marking, the command/http hook boundary) shipped; trace follow-ups and the §3.9 worker-boundary authority question open — its network/filesystem granularity half is proposed in agent-sandbox-policy.md |
| Worker API network boundary | R0 | Planned: separate public and worker listeners, an internal worker Service, TLS, route placement, and a worker-port NetworkPolicy; general worker egress remains open in the trust harness |
| gVisor worker runtime | R0 | Planned behind qualification: an operator-selected, fail-closed RuntimeClass places the whole worker Pod behind gVisor while retaining bwrap for command policy; exact nested-sandbox compatibility and performance are the first gate |
| Agent-scoped sandbox policy | P0.5 follow-on | Backend implemented: agent-revision-scoped network/filesystem sandbox tiers, claim-time resolution and pinning, and SandboxSurfaceWorker selection. Portal selectors, the space default tier, and cluster-level verification are open |
| Context durability | P0.5 | Implemented: accumulating compaction, durable session notes, the pre-compaction checkpoint, and the additional system prompt. The §6 and §11 follow-ups are open |
| Local Projects and Project Memory | P0.5 local follow-on | Phases 1 and 2 shipped: shared CLI/Desktop Project identity, bounded cross-session Project Memory, MemoryRead and MemoryWrite on enabled local primary runs, and the memory half of buildmax info and the TUI /info panel. Desktop lists and reads memories and nothing more; its editor, per-memory delete, and enable toggle are unbuilt, as is the §17 session review command. Phase 3 not started. Portal, space, and user memory remain outside this record |
| Local session storage | unscheduled | Implemented: atomic session bundles, linked journal history, rewind, and physical-copy fork. Server synchronization is outside this record |
| Session usage stats | P1 follow-on | Per-session buildmax info and the session tab of the TUI /info panel shipped, with the subagent and compaction metering fixes they required. Cross-session aggregation and the Desktop surface are designed and not built |
| Local background jobs | P0.5 | Stages 1–3 shipped: background Bash/Task jobs, Monitor, typed delivery with parked wake-up on both surfaces, durable job logs. Durability beyond the process — spool, supervisor, scheduling — is decided against, not pending |
| Evaluation and qualification | P0.6 | Local and worker slices shipped: the contract, both black-box adapters, deterministic/command/trace graders, preflight, repetition, paired comparison, and three tasks. The legacy harness is retired. The Terminal-Bench 2.1 adapter and importer are built and pinned, and have run the oracle smoke and a one-task canary; no wider run exists, so there is no external score yet. The canary subset is pinned and selectable but has not been run; that run, conversation and deployment adapters, model-grader calibration, the holdout, and the Inspect spike are open |
| Issue agent access | unscheduled | Shipped on both planes: GetIssue and ReportToIssue, scoped by construction, behind run-token routes for a worker and buildmax issue start locally. Status, assignment, and hierarchy stay out of the model's hands, and a local report is stored as local_agent — a claim, never the agent a scheduled run writes. Artifact references in GetIssue are deferred on an ownership question |
| Enterprise deployment | P3 | M1, M2, M4, and M5 shipped; M3 mostly done. Operating evidence and configuration checks remain. |
| Graceful shutdown | P3 follow-on | Implemented: the shutdown ladder and its budget, the draining state, watcher-stream drain and its Portal half, turn quiescing, managed terminal callbacks, HTTP timeouts, the manifests, a worker that reports what it produced when asked to stop, a bounded scheduler stop, and the recorded liveness signal that closes a run whose worker was killed without warning. Re-dispatching an interrupted run belongs to run retry; durable workflow advance stays open |
| Managed LLM gateway | P3 | Shipped for CLI/TUI/Desktop and task runs; strict quota open. Sections 1, 4.2, 7, 10, and 12 are revised by client modes, summarised in its status block |
| Prompt cache control | P3 follow-on | Phases 1–3 shipped and phase 4's mechanism with them: cache policy, the Anthropic and OpenAI native paths, usage and cost telemetry. The qualification suite has been run and both native paths qualified; compatible profiles stay empty by decision. The per-entry capability claim and the section 6 diagnostics are open |
| Local Ollama provider | P1 follow-on | Complete: the adapter, local inventory, the CLI surface, and credential-free managed targets |
| Space governance | P4 | Roles, quota, workflow lifecycle, the audit trail, its retention and export, and quota alerting shipped; the second slice of actions and audit-to-run correlation open |
| System administration | P4 | Implemented: grant model, operator command, admin API, Portal area, and model catalog surface |
| Space Secrets and run delivery | R0 credential debt, R3 space surface | Phase 1 complete: a Space owns a group of named items in one encrypted row (unversioned), an Agent revision configures its env consumption, an owner manages secrets and an owner or admin configures agent consumption in Portal, a run receives the values through a no-store worker route and the env_scrub allow-list, the materialization is recorded, and the values are redacted from trace, tool results, and stream. Records that a run can read what it was granted, so the boundary is Space ownership, per-Agent consumption, credential lifetime, and audit rather than confidentiality against the model. Phases 2–5 (file delivery, short-lived exchange, external providers, workload identity) follow. Answers Phase D3 of plugin-space-distribution.md |
| Plugin distribution and private marketplace | post-Beta, P4 follow-on | Phases A–C shipped: plugins load, the Marketplace publishes and installs, Portal and Desktop manage it. Phase D is tracked by the next record; its instruction-only D1 slice is shipped |
| Space and worker plugin distribution | post-Beta, after the Marketplace | D1 works end to end: a space curates its plugin list or opens the whole catalog, an agent loads only what it names, and a worker materializes exactly the pinned releases. Portal manages activations; the agent's own plugin field is still API-only. Task-scoped autonomous acquisition is accepted but unimplemented: it creates immutable Plugin environment revisions rather than preserving expanded directories. Neither D2, executable content behind operator eligibility, nor D3, secret delivery, is started |
| Entity identity and relational keys | Beta gate | Implemented: opaque public handles, numeric relational keys, and the store boundary between them. §8 decided database foreign keys: none, until a real deletion feature adds them, and the §17 amendment moving storage off BINARY(12) to the canonical text form is in the schema |
| Workspace root and worktrees | step 5 product bet | Complete, phases 1-5: the root is session state every tool reads per call, an agent creates, enters, leaves, and removes its own worktrees under the containment, permission, and occupancy rules, derived configuration follows a move, three hook events announce it, and a delegate can have a tree of its own. Whether listing alone keeps worktrees from accumulating is the open question |
| Tool permissions | unscheduled | Implemented; operator control over autonomous surfaces (§7) and the §10 open questions remain, one of which records a defect in shipped sandbox policy rather than in this design |
| Parallel tool execution | unscheduled | Implemented for read-only tools and read-only Task agent types; presentation and trace questions open (§11) |
| Local end-to-end verification | unscheduled | Harness, CLI, Desktop bridge, Desktop UI (React app plus bindings, via wails dev's browser server), CI policy, named suites, and the runbook done; some Portal paths, the deployment cancellation and failure-recovery paths, and the native-window/packaged-app smoke open |
| Verification program | R0–R4 | Planned risk-weighted verification matrix, pull-request MySQL gate, deterministic critical journeys, controlled failure injection, scheduled deployment evidence, and external release rehearsal |
| Workflow runtime | R5 | Direction accepted: a Space-scoped, revision-pinned durable adaptive graph over Task/TaskRun. Current code remains a linear callback-driven precursor; durability, dataflow, graph execution, typed decisions, and waits are phased and unshipped |
| Structured output | R5 prerequisite | Proposed: a provider-neutral structured-output contract in the shared runtime — a JSON Schema subset on the request, a validated value on the completion, per-provider mapping with honest capability reporting. Additive to text output; unblocks Workflow typed routes/planners and a richer Task result. Not started |
| Unified artifacts | P2 follow-on | Implemented: durable space artifacts with stable opaque references, upload/preview/download, tombstoned deletion, and UploadArtifact on every surface with a server. Registering a run's output directory is decided against; external sharing is reopened by the record below; the phase 4 follow-ons stay open |
| Artifact public sharing and preview | P2 follow-on | Implemented (phases 1–2): reopens unified-artifacts phase 3 with a revocable stored share token for anonymous public links, UploadArtifact(share=true), the public_base_url the server renders links from, and rich Portal preview (Markdown plus opaque-origin sandboxed HTML) shared by the authenticated detail page and the public page. Share-expiry audit awaits a share retention sweep; a couple of Phase 3 follow-ons stay open |
| Portal execution model | P2 follow-on | Phases 0 and 3 shipped and phase 1 half shipped: outcome projection, durable result delivery, and run provenance. Its mandatory Tier 1 hierarchy and Conversation-owned Task shape are superseded by agent execution and Task threads |
Durable records for implemented or partly implemented subsystems. Keep these
aligned with code and link user-facing behavior to guide/ or reference/.
| Document | Current state | User docs |
|---|---|---|
| Client modes: local and managed | Implemented: the mode is whether a login is stored, models come from one source, the alias layer and per-space model policy are gone, and the call ledger is user-scoped | manual/models-and-modes.md |
| LLM provider adapters | Three wire protocols, reasoning, prompt caching, and image input are implemented | manual/models-and-modes.md |
| Worker run token | The run-scoped credential is the only credential accepted by worker routes; the shared worker token is removed | reference/configuration.md |
| Space membership lifecycle | Invitation, role change, ownership transfer, access recovery, and their Portal surfaces are implemented | — |
| Timestamp representation | Persisted instants use time.Time, DATETIME(6), and RFC 3339 with UTC-pinned database connections |
— |
| Hook system | 16 events and 4 transports implemented; the optional inspector and frontmatter integrations stay deferred | manual/hooks.md |
| Sandbox boundaries | Local phases A–E implemented, process limits and the command/http hook boundary included; phase F's worker surface selection, production-pod verification, and downgrade marking shipped, its example-config docs and the sandbox overrides command open |
manual/sandbox.md |
| Durable run trace | Phase 1 implemented; richer events and retention open | manual/sessions-and-traces.md |
| Queued messages | Queueing on all three surfaces, mid-run injection on CLI/TUI and Desktop; persistence and Portal injection decided against | manual/cli.md |
| Area | Package |
|---|---|
| Shared agent runtime assembly | internal/agentapp |
| Task-run execution runtime | internal/agentapp/taskrun |
| Tier 1 conversation orchestration | internal/service/conversation |
| Issue, task, workflow, and quota services | internal/service/* |
| HTTP API handlers | internal/server/handlers |
| Scheduler | internal/server/scheduler |
| Worker API client and updater | internal/infra/workerclient |
| Runtime agent tools | internal/tool |
Full tree: contribute/repo-layout.md.
- Choose a short semantic filename such as
execution-policy.md. - State the problem, options considered, chosen approach, status, and phases.
- Add it to exactly one section above.
- If it ships something a user configures, write the user-facing half in
guide/orreference/and link it from the table.
When it stops describing the current direction, delete it and remove its row. Git history keeps it; see contribute/documentation.md.