README
¶
Agent Runtime
Agent Runtime is a Go monorepo for a durable, session-based agent platform.
Public documentation is available at
0x63616c.github.io/agent-runtime.
M0 and the M2 payload milestone are complete. M1 declarative infrastructure
and M3 sandbox-control work are active. The repository now exposes a runnable
isolated Tilt infrastructure foundation and the reusable temporalpayload
package, but it does not yet expose the public agent runtime service, working
examples, production runtime image composition, or verified Firecracker
isolation.
The first M5 slice now publishes the Temporal-free Go contract at
github.com/0x63616c/agent-runtime/sdk/go plus a deterministic internal kernel
for immutable Agent revisions, revision-pinned Sessions, idempotent Input,
serialized Turns, cancellation, and cursor-addressed Product events. The
contract compiles from an independent module. It is not yet backed by the
public HTTP service, PostgreSQL, or Temporal orchestration.
The current Tilt foundation projects the reviewed typed local Stack into eight health-only trust-scoped role images—API, orchestration, model, tool, blob, codec, sandbox control, and sandbox host—with per-role identities and exact credential references. It proves isolated infrastructure, image builds, readiness, reset, and teardown; it is not yet the public Agent Runtime. See the local Stack guide for the exact boundary.
Verification
The supported incremental repository check is:
just check
It requires just 1.58.0 (pinned in .tool-versions) and runs module
verification, the Go race suite, vet, an AST-based real-time-wait check, and
schema/completeness validation for the generated 183-row
catalog and
ledger. check proves the evidence
register is structurally honest; it does not turn non-green rows into passes.
just verify is the binding milestone/release completion gate. It reruns
check, emits the complete 183-row status/evidence report, and currently fails
because requirements are in_progress or not_started, with no immutable
main-CI or complete acceptance evidence. just completion-check is an alias.
This is expected until the full release ledger is green; it does not reopen a
previously completed milestone.
Configuration and status evidence
Process configuration is constructed explicitly through runtimeconfig; domain
packages do not read environment variables. Diagnostics, JSON, formatting and
structured logs redact notifier credentials. The only accepted status topic is
https://ntfy.sh/0x63616c-ai-agant (spelling intentional).
The milestone implementation accepts a complete canonical catalog before it builds a weighted estimate, retains evidence before notifier delivery, records failures as retryable classified codes, and transports only the ADR-defined structured payload. It provides a deterministic fake notifier for tests and a fixed-topic ntfy transport for completion operations. The retained M0 record preceded successful delivery; later milestone owners use the same pipeline only after their complete evidence gates are green.
Compatibility
The repository publishes one root module,
github.com/0x63616c/agent-runtime, and currently requires Go 1.26 or newer.
Contributor and delivery policy is in CONTRIBUTING.md; the
Go compatibility and
generated ownership policies state
the current boundaries.
All public packages share one semver release train. Compatibility, deprecation,
generated API ownership, and clean external-consumer verification remain
release requirements and are not yet release guarantees.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
afk-evidence
command
Command afk-evidence creates and validates bounded direct-main evidence logs.
|
Command afk-evidence creates and validates bounded direct-main evidence logs. |
|
agent-runtime-api
command
|
|
|
agent-spec-backfill-controller
command
Command agent-spec-backfill-controller validates one explicit controller declaration.
|
Command agent-spec-backfill-controller validates one explicit controller declaration. |
|
dev-role
command
Command dev-role is the deliberately minimal local composition image for the API, worker, and codec roles before their product implementations land.
|
Command dev-role is the deliberately minimal local composition image for the API, worker, and codec roles before their product implementations land. |
|
egress-proxy
command
Command egress-proxy runs a finite allowlisted HTTP and HTTPS CONNECT proxy.
|
Command egress-proxy runs a finite allowlisted HTTP and HTTPS CONNECT proxy. |
|
firecracker-e2e
command
Command firecracker-e2e records whether this host can run the protected Linux/KVM lane.
|
Command firecracker-e2e records whether this host can run the protected Linux/KVM lane. |
|
firecracker-smoke
command
Command firecracker-smoke records a fail-closed protected-runner preflight.
|
Command firecracker-smoke records a fail-closed protected-runner preflight. |
|
generate-requirement-manifest
command
Command generate-requirement-manifest renders canonical evidence metadata.
|
Command generate-requirement-manifest renders canonical evidence metadata. |
|
generate-runtime-openapi
command
Command generate-runtime-openapi derives private server and SDK route tables from the public OpenAPI authority.
|
Command generate-runtime-openapi derives private server and SDK route tables from the public OpenAPI authority. |
|
ledger-report
command
Command ledger-report validates a machine-readable weighted evidence ledger.
|
Command ledger-report validates a machine-readable weighted evidence ledger. |
|
milestone-notify
command
Command milestone-notify retains and sends a bounded milestone completion report.
|
Command milestone-notify retains and sends a bounded milestone completion report. |
|
no-real-wait
command
Command no-real-wait verifies owned Go source has no real-time wait primitive.
|
Command no-real-wait verifies owned Go source has no real-time wait primitive. |
|
runtime
command
Command runtime composes one validated Agent Runtime process role.
|
Command runtime composes one validated Agent Runtime process role. |
|
runtime-operations-drill
command
Command runtime-operations-drill records one protected operational drill.
|
Command runtime-operations-drill records one protected operational drill. |
|
sandbox-control
command
|
|
|
sandbox-host
command
|
|
|
sandbox-reaper
command
|
|
|
stackctl
command
Command stackctl renders and inspects reviewed declarative Stack documents.
|
Command stackctl renders and inspects reviewed declarative Stack documents. |
|
internal
|
|
|
afkevidence
Package afkevidence validates bounded, secret-safe direct-main evidence logs.
|
Package afkevidence validates bounded, secret-safe direct-main evidence logs. |
|
agentspecbackfill
Package agentspecbackfill owns the pure immutable request, verification, and archive seam for Agent-spec backfill.
|
Package agentspecbackfill owns the pure immutable request, verification, and archive seam for Agent-spec backfill. |
|
agentspecbackfillcr
Package agentspecbackfillcr owns the structural, canonical AgentSpecBackfill request and status wires.
|
Package agentspecbackfillcr owns the structural, canonical AgentSpecBackfill request and status wires. |
|
agentspecbackfillcrd
Package agentspecbackfillcrd renders and validates the structural AgentSpecBackfill Kubernetes CRD.
|
Package agentspecbackfillcrd renders and validates the structural AgentSpecBackfill Kubernetes CRD. |
|
agentspecbackfillexportprocess
Package agentspecbackfillexportprocess composes the separately-authorized terminal archive exporter.
|
Package agentspecbackfillexportprocess composes the separately-authorized terminal archive exporter. |
|
agentspecbackfillkube
Package agentspecbackfillkube adapts the fixed AgentSpecBackfill Kubernetes resource to controller ports.
|
Package agentspecbackfillkube adapts the fixed AgentSpecBackfill Kubernetes resource to controller ports. |
|
agentspecbackfillprocess
Package agentspecbackfillprocess composes the AgentSpecBackfill controller from explicit, narrow ports.
|
Package agentspecbackfillprocess composes the AgentSpecBackfill controller from explicit, narrow ports. |
|
approval
Package approval owns the pure, persistence-free human-approval state machine.
|
Package approval owns the pure, persistence-free human-approval state machine. |
|
clock
Package clock provides explicit time sources for deterministic runtime decisions.
|
Package clock provides explicit time sources for deterministic runtime decisions. |
|
docsrefresh
Package docsrefresh deterministically renders allow-listed public documentation.
|
Package docsrefresh deterministically renders allow-listed public documentation. |
|
egressproxy
Package egressproxy provides an exact-target forward proxy for trust-scoped workloads.
|
Package egressproxy provides an exact-target forward proxy for trust-scoped workloads. |
|
firecracker
Package firecracker owns the Linux/KVM-only, internal Firecracker host profile.
|
Package firecracker owns the Linux/KVM-only, internal Firecracker host profile. |
|
firecrackerbootprobejournal
Package firecrackerbootprobejournal owns the host-instance-exclusive durable launch-intent record required before an M4 Jailer may start.
|
Package firecrackerbootprobejournal owns the host-instance-exclusive durable launch-intent record required before an M4 Jailer may start. |
|
firecrackerbootprobelease
Package firecrackerbootprobelease owns the private persisted lease guard for one sealed Firecracker boot probe.
|
Package firecrackerbootprobelease owns the private persisted lease guard for one sealed Firecracker boot probe. |
|
firecrackerbootprobeprotocol
Package firecrackerbootprobeprotocol owns the private signed M3-to-M4 boot-probe command and M4 observation wire.
|
Package firecrackerbootprobeprotocol owns the private signed M3-to-M4 boot-probe command and M4 observation wire. |
|
firecrackerbootprobev2
Package firecrackerbootprobev2 owns the private, persisted successor and acknowledgement contract for one sealed Firecracker boot-probe lease.
|
Package firecrackerbootprobev2 owns the private, persisted successor and acknowledgement contract for one sealed Firecracker boot-probe lease. |
|
firecrackerlaunchgrant
Package firecrackerlaunchgrant owns the private, operator-only M3/M4 boot-probe binding.
|
Package firecrackerlaunchgrant owns the private, operator-only M3/M4 boot-probe binding. |
|
identity
Package identity defines runtime-owned opaque identifiers.
|
Package identity defines runtime-owned opaque identifiers. |
|
milestone
Package milestone builds retained status evidence and notification attempts.
|
Package milestone builds retained status evidence and notification attempts. |
|
nowait
Package nowait checks owned Go code for nondeterministic real-time waiting.
|
Package nowait checks owned Go code for nondeterministic real-time waiting. |
|
openapicontract
Package openapicontract validates the repository-owned public Agent Runtime OpenAPI contract.
|
Package openapicontract validates the repository-owned public Agent Runtime OpenAPI contract. |
|
roles
Package roles validates trust-scoped runtime process composition.
|
Package roles validates trust-scoped runtime process composition. |
|
runtime/kernel
Package kernel owns deterministic Agent, Session, Input, Turn, and Product-event transitions.
|
Package kernel owns deterministic Agent, Session, Input, Turn, and Product-event transitions. |
|
runtimeadmission
Package runtimeadmission owns the content-reference and durable SendInput admission seam.
|
Package runtimeadmission owns the content-reference and durable SendInput admission seam. |
|
runtimeapi
Package runtimeapi exposes the public, Temporal-free HTTP boundary of Agent Runtime.
|
Package runtimeapi exposes the public, Temporal-free HTTP boundary of Agent Runtime. |
|
runtimeapiprocess
Package runtimeapiprocess composes the separately runnable public API role from explicit operator configuration.
|
Package runtimeapiprocess composes the separately runnable public API role from explicit operator configuration. |
|
runtimeconfig
Package runtimeconfig defines explicit, validated process configuration.
|
Package runtimeconfig defines explicit, validated process configuration. |
|
runtimecontent
Package runtimecontent owns runtime-scoped immutable Agent specification and Input content.
|
Package runtimecontent owns runtime-scoped immutable Agent specification and Input content. |
|
runtimeerror
Package runtimeerror adds safe context at runtime boundaries.
|
Package runtimeerror adds safe context at runtime boundaries. |
|
runtimemodel
Package runtimemodel owns the narrow model-effect worker seam.
|
Package runtimemodel owns the narrow model-effect worker seam. |
|
runtimeoperations
Package runtimeoperations owns the protected operational-evidence drill.
|
Package runtimeoperations owns the protected operational-evidence drill. |
|
runtimeorchestration
Package runtimeorchestration contains the private Temporal composition for state-backed Session work.
|
Package runtimeorchestration contains the private Temporal composition for state-backed Session work. |
|
runtimepostgres
Package runtimepostgres owns the PostgreSQL implementation of runtime-state persistence.
|
Package runtimepostgres owns the PostgreSQL implementation of runtime-state persistence. |
|
runtimestate
Package runtimestate defines the metadata-only S2/S7 runtime lifecycle authority.
|
Package runtimestate defines the metadata-only S2/S7 runtime lifecycle authority. |
|
runtimetool
Package runtimetool owns capability-bound external tool execution.
|
Package runtimetool owns capability-bound external tool execution. |
|
sandboxcontrolapi
Package sandboxcontrolapi serves the private sandbox.control/v1 control process without exposing persistence, authentication, or transport types in the public sandbox SDK.
|
Package sandboxcontrolapi serves the private sandbox.control/v1 control process without exposing persistence, authentication, or transport types in the public sandbox SDK. |
|
sandboxcontrolprocess
Package sandboxcontrolprocess composes the separately runnable sandbox control role from one strict operator document and explicit secret sources.
|
Package sandboxcontrolprocess composes the separately runnable sandbox control role from one strict operator document and explicit secret sources. |
|
sandboxhostapi
Package sandboxhostapi exposes the private mutually authenticated host control surface.
|
Package sandboxhostapi exposes the private mutually authenticated host control surface. |
|
sandboxhostjournal
Package sandboxhostjournal persists the reference host's receipt journal before any fake effect.
|
Package sandboxhostjournal persists the reference host's receipt journal before any fake effect. |
|
sandboxhostprocess
Package sandboxhostprocess composes the separately runnable reference host.
|
Package sandboxhostprocess composes the separately runnable reference host. |
|
sandboxhostprotocol
Package sandboxhostprotocol owns the private, bounded host-control wire contract.
|
Package sandboxhostprotocol owns the private, bounded host-control wire contract. |
|
sandboxreaperprocess
Package sandboxreaperprocess composes the independently deployable durable sandbox reconciliation owner.
|
Package sandboxreaperprocess composes the independently deployable durable sandbox reconciliation owner. |
|
stack
Package stack defines the typed desired-state input for operator-owned infrastructure.
|
Package stack defines the typed desired-state input for operator-owned infrastructure. |
|
temporalpayloadruntime
Package temporalpayloadruntime owns the sole runtime Temporal client and worker converter factory.
|
Package temporalpayloadruntime owns the sole runtime Temporal client and worker converter factory. |
|
temporalpayloaduiprocess
Package temporalpayloaduiprocess composes the local Temporal UI payload-inspection handler from explicit policy.
|
Package temporalpayloaduiprocess composes the local Temporal UI payload-inspection handler from explicit policy. |
|
toolpolicy
Package toolpolicy evaluates one already-normalized tool intent against one immutable operator-authored policy projection.
|
Package toolpolicy evaluates one already-normalized tool intent against one immutable operator-authored policy projection. |
|
Package sandbox defines the public durable sandbox control contract.
|
Package sandbox defines the public durable sandbox control contract. |
|
sdk
|
|
|
go
Package agentruntime defines the stable, Temporal-free Go contract for Agent Runtime.
|
Package agentruntime defines the stable, Temporal-free Go contract for Agent Runtime. |
|
skills
|
|
|
refresh-agent-runtime-docs/scripts/refresh-docs
command
Command refresh-docs regenerates allow-listed public documentation from declared sources.
|
Command refresh-docs regenerates allow-listed public documentation from declared sources. |
|
Package temporalpayload provides the local, size-aware Temporal payload codec chain.
|
Package temporalpayload provides the local, size-aware Temporal payload codec chain. |
|
s3
Package s3 adapts an S3-compatible object store to temporalpayload.BlobStore.
|
Package s3 adapts an S3-compatible object store to temporalpayload.BlobStore. |
|
tools
|
|
|
dev
command
Command dev owns the explicit local-only Stack materialization lifecycle.
|
Command dev owns the explicit local-only Stack materialization lifecycle. |
|
firecracker/guest-agent
command
Command guest-agent is the project-owned, static smoke-fixture init program.
|
Command guest-agent is the project-owned, static smoke-fixture init program. |
Click to show internal directories.
Click to hide internal directories.