Skip to content
Agent Forge Docs

Effect architecture conventions

Much of the runtime is described with Effect so cancellation, dependency injection, and per-directory isolation stay explicit. At the outer boundary, makeRuntime turns that into Promises and callbacks. Session-level concurrency is single-flight via Runner so two outer loops cannot corrupt the same session.

makeRuntime

Section titled “makeRuntime”

Wires service Layers to plain TypeScript: runPromise / runFork / runSync. Shared memo avoids rebuilding Layers; instance references and telemetry can attach. At the boundary, Effect failures map to errors callers can handle.

InstanceState

Section titled “InstanceState”

Scoped state cached by project directory: multiple projects in one process do not share mutable state. Destruction runs finalizers. When two directories must not share mutable state, put it in InstanceState—not in module-level globals. Aligns with instance boundaries.

Runner

Section titled “Runner”
stateDiagram-v2
  [*] --> Idle
  Idle --> Running: ensureRunning
  Idle --> Shell: startShell
  Running --> Idle: complete / cancel
  Shell --> Idle: complete / cancel

Only one main task runs per session at a time; concurrent prompts are rejected while busy. Cancellation ends with a recognizable cancel error. Kernel-side behavior: instance boundaries and concurrency.

Related reading: