Local Runtime is a local-first, single-machine runtime for a self-growing agent. It turns a local task or IM message into bounded context, validated actions, evidence, verification, and a response. vNext is the active delivery direction. The installed v0.2 runtime is frozen as an executable rollback path until a separately verified vNext cutover; it is not a parallel roadmap.
The accepted vNext architecture keeps one persistent local-first Evi self while replacing the Goal-centric runtime foundation: ordinary work becomes a Turn in a Run, Pi owns the only Agent Loop, SQLite owns structured runtime state, and an Evi Action Gateway owns effects. This target does not expand the implemented v0.1/v0.2 contract or claim a deployment cutover. Current source behavior and delivery status are owned by source, tests, bounded Issues/PRs, and deployment evidence; the architecture and runtime-contract documents below define the stable owner model and acceptance semantics.
- Chinese operator entrypoint: docs/README.cn.md
- Compact documentation router: docs/INDEX.md and docs/INDEX.cn.md
- Current module ownership, delegated capability seams, and staged migration: docs/ARCHITECTURE.md and docs/ARCHITECTURE.cn.md
- Source, directory, dependency, test, and documentation structure: docs/ENGINEERING.md and docs/ENGINEERING.cn.md
- Repository work rules: AGENTS.md and docs/AGENTS.cn.md
- Stable identity and learning stance: core/soul.md and core/soul.cn.md
- Runtime contract and local operations (read the routed section on demand): docs/RUNTIME_CONTRACT.md and docs/LOCAL_RUNTIME.md
- SOP, skill, and active-vault boundaries: docs/LOCAL_LEARNING.md
- Accepted long-term product and gated evolution vision: docs/PRODUCT_VISION.md and docs/PRODUCT_VISION.cn.md
- Historical v0.2 multi-node design (not the active roadmap): docs/V0.2_MULTI_NODE_EVOLUTION.md and docs/V0.2_MULTI_NODE_EVOLUTION.cn.md
The linked documents are authoritative for their own subjects. Keep this file as the short entrypoint; do not duplicate detailed command references, contracts, or historical decisions here.
The currently installed rollback runtime is intentionally narrow:
- one local user and one machine;
- bounded repo/state actions through the harness;
- CLI, localhost web console, and local IM adapters;
- evidence-backed verification and explicit learning gates.
vNext keeps execution, raw memory, and runtime state node-local. It is still not a hosted multi-user service, public marketplace, shared runtime-state system, or autonomous rewrite system.
main is the release branch. develop is the protected integration branch.
Every source change begins and remains in one isolated worktree branch until a
pull request has passed its required verification and is merged into develop.
No source change is committed or pushed directly to develop.
main -> feature worktree -> PR -> develop -> main
The root checkout stays clean on develop as the control plane. A release
candidate is verified from an isolated local environment before develop
merges into main and receives a version tag.
Runtime identifiers, config fields, capability IDs, scripts, and persisted
state use capability-oriented names such as local-runtime, project_design,
model, and im-channel. Names of this repository or external reference
projects must not become implementation contracts.
The current v0.2 deployment is still owned by GoalRuntime, its Harness,
canonical evidence, and OutcomeReceipt; ADR 0001
records that implemented boundary. The accepted replacement is
ADR 0012: ordinary Turns do not require
a Goal, Pi owns the only Agent Loop, and SQLite is the structured state
authority. ADR 0013 defines
the reservation-first Action Gateway; the currently composed effect set is
reported only by the implemented Runtime Contract.
ADR 0014 defines explicit
continuation after terminal Action reconciliation. ADR 0015
defines Run Execution ownership and model-dispatch crash recovery.
ADR 0016 closes persisted Pi
tool-call protocol recovery and marks the Kernel-foundation exit gate.
ADR 0017 owns the
final Evi/Pi division, parent-child orchestration, Delivery Lineage, and
specialized completion model.
v0.2 remains the rollback runtime until a separately verified cutover.
| Need | Source |
|---|---|
| Implemented behavior | source, tests, and docs/RUNTIME_CONTRACT.md |
| Accepted durable direction | docs/adr/ and stable project docs |
| Current v0.2 execution and verified terminal result | GoalRuntime, Harness, evidence, OutcomeReceipt |
| Accepted vNext owner model | Turn / Run, Pi Agent Loop, SQLite, Action Gateway, optional Goal, Adaptation |
| Reflection before material evolution | grill-me -> bounded Direction Proposal |
| Historical task/spec/decision evidence | frozen .trellis/ archive |
Do not refresh or preload Trellis-generated agent context. It is retained only as historical evidence and is not the default workflow for new work.
pnpm install --frozen-lockfile
pnpm run check
pnpm run release:verify
pnpm run runtime -- doctor --state-root ~/.local-runtime/state/eviStart the local runtime after configuring ignored local credentials:
pnpm run runtime -- service restart --target runtime --state-root ~/.local-runtime/state/evi
pnpm run runtime -- service health --target runtime --state-root ~/.local-runtime/state/eviTracked files under config/ are safe defaults. API keys and app secrets
belong only in ignored local configuration or the selected local state root;
never commit them.
apps/cli/ CLI entrypoint
packages/core/ context, harness, evidence, governance
packages/runtime/ config, models, service, web and IM adapters
packages/kernel/ vNext Turn/Run kernel, SQLite state, Action Gateway, Pi adapter
config/ tracked safe defaults
core/ stable identity and memory policy
docs/ architecture, engineering, runtime and operator documentation
.trellis/ frozen historical specs, tasks, decisions, generated context