agent-managed-compute

Agent-Managed Compute

This directory is the canonical plan for agents that allocate, steer, and recover compute through agent-runtime.

Verdict

The runtime supports single-owner SQL failover for retained provider runs. It is not a general distributed workflow engine.

The core execution model is sound:

• An AgentProfile describes the agent.
• A Scope lets a driver spawn, observe, steer, and stop children.
• A Supervisor owns the shared budget and child lifecycle.
• An Executor runs one child on a selected backend.
• An AgentEnvironmentProvider exposes external compute and resumable sessions.
• MCP exposes coordination actions to an agent runner as native tools.

Retained provider children and managers can reconcile original invocations after a local coordinator restart. Durable inputs, ordered admissions, content-addressed results, and usage records support that recovery. New retained sessions use deterministic, bounded identifiers that are safe for provider workspace paths. Recovery preserves the recorded session and execution identifiers and validates the original request material. Recovery restores live descendants and their reservations before the manager resumes. Managers and children then continue together through the existing Scope lifecycle. Unresolved provider work remains uncertain until exact identity and completion can be established.

Remote MCP uses scoped credentials, bounded requests, and caller-provided network reachability. Providers must advertise runtime MCP attachment support before receiving coordination tools beside the unchanged profile. One-shot providers remain nonsteerable.

The file run lock coordinates local ownership. createFencedSqlRunContext adds a SQL ownership lease, generation-checked publications, and a durable coordination log. A second live process cannot acquire the run; after owner loss, a contender can take over without local files. This requires a shared durable SQL service and a retained provider with idempotent create/dispatch. External keyed effects must deduplicate at the effect site. Arbitrary unkeyed effects are not made exactly-once by SQL. Live multi-provider recovery and generation-fenced remote steering remain separate validation work. See reliability.md for the supported recovery boundary and remaining distributed requirements.

Product Definition

Agent-managed compute means an agent may decide at runtime to:

1. do work itself,
2. start one or more child agents,
3. choose their profiles and compute providers,
4. inspect progress and outputs,
5. send corrections or follow-up instructions,
6. stop or replace work that is failing,
7. preserve useful state across process failure,
8. finish only when an independent check accepts the result.

The runtime manages logical work, budgets, recovery, and records.

Compute providers manage machines, containers, sessions, process health, and placement.

MCP is the tool-facing control adapter.

MCP is not the scheduler or durable state store.

Documents

Document	Purpose
current-state.md	What is implemented, what was tested, and what is only claimed.
architecture.md	The converged execution model, package ownership, and target public API.
reliability.md	Failure behavior, recovery rules, security, concurrency, and workspace safety.
roadmap.md	Dependency-ordered implementation plan with completion criteria.
validation.md	Tests, failure injection, live-provider runs, and benchmark acceptance targets.

These six files are the only active planning documents for this effort.

The broader runtime architecture, call-routing protocol, environment-provider implementation record, context-lifecycle research, and interactive-session proposal remain source references.

When a source reference conflicts with this directory about distributed readiness or implementation order, this directory wins.

The older simplification tracker is historical and is superseded by roadmap.md for execution and API convergence.

Source Document Ledger

This table tracks the existing documents that materially overlap this plan.

Document	Classification	Use
Runtime architecture	Current reference	Recursive agent model and package-wide architecture.
Canonical API	Current reference	Shipped entry points and anti-duplication guidance.
Execution model	Current reference	Existing executor and driver behavior.
Agent bus protocol	Current reference	Call-routing headers and depth controls. It is not durable coordination state.
Durability adapters	Current reference	Conversation persistence only. It does not provide supervised-tree recovery.
Environment provider adapter	Current source	Provider contract and adapter implementation history.
Context lifecycle	Current source	Long-run context and knowledge transfer research.
Interactive sessions	Historical input	Session UX and tmux exploration. Its completion checklist is not current acceptance evidence.
Long-horizon agent map	Historical input	Earlier product and control design.
RSI atom masterplan	Historical input	Earlier recursive-agent build plan.
Simplification plan	Superseded plan	Earlier API and module inventory.
atom-mcp-e2e.mts	Historical experiment	Useful prototype with stale tool names and incomplete result accounting.

Status Summary

Capability	Current status	Evidence
Agent calls coordination actions through real HTTP MCP	Implemented in one process	tests/kernel/coordination-mcp.test.ts
Driver dynamically spawns, waits for, and selects children	Implemented	tests/kernel/coordination-driver.test.ts
Recursive driver starts another driver	Implemented	tests/kernel/coordination-driver.test.ts
Shared budget and depth limits across a tree	Implemented	src/runtime/supervise/budget.ts, src/runtime/supervise/scope.ts
Provider-neutral compute adapter	Implemented	src/runtime/environment-provider.ts
One-shot delegation restart recovery	Partially implemented	src/mcp/task-queue.ts
Conversation turn restart recovery	Implemented for one writer	src/conversation/run-conversation.ts
Supervised tree restart recovery	Committed replay, retained children, and reconstructed nested managers with original reservations and finalizers	src/runtime/supervise/supervisor.ts
Durable cross-process coordination messages	Owner-scoped SQL side-log, replayed with original bus stamps	tests/durability/sql-context-stores.test.ts
Authenticated remote coordination MCP	Implemented; requires caller-provided reachable endpoint	src/runtime/supervise/coordination-mcp.ts
Concurrent coordinator failover	Fenced SQL claim, live-owner exclusion, SIGKILL takeover, and stale-owner rejection	tests/durability/sql-run-context.test.ts, tests/durability/sql-run-store.test.ts
One simple multi-round public API	Not implemented	runConversation, runPersonified, runAgentic, and runAgentRounds overlap.
Acyclic runtime and knowledge packages	Implemented	agent-knowledge imports no runtime code; agent-runtime owns the optional composition in src/knowledge/; direct release lines align, while transitive packages may retain internal copies.

Scope Boundaries

This work must not turn agent-runtime into a machine scheduler.

Use existing provider systems for compute allocation and process lifecycle.

This work must not put knowledge policy into the runtime.

agent-knowledge remains the general knowledge engine, and an agent may use it as a tool or work product during a run.

This work must not create another profile format.

AgentProfile remains the portable description of agent behavior.

This work must not promise exactly-once network delivery.

It must provide idempotent commands, deduplicated events, and one accepted terminal result.