runtime-engine

name	runtime-engine
description	Working on RuntimeEngine, ExecutionContext, agent execution, or the request lifecycle. Primary tasks are tasks/0003-compiled-agent-graph.md and tasks/0004-runtime-engine.md.
generated	true
source	.ai/skills/runtime-engine.md

Skill: Runtime Engine

When to use this skill

Use this when modifying RuntimeEngine, ExecutionContext, agent execution, or the request lifecycle. Primary tasks: tasks/0003-compiled-agent-graph.md, tasks/0004-runtime-engine.md.

Files to read first

• AGENTS.md
• docs/ARCHITECTURE.md
• docs/RUNTIME_LIFECYCLE.md
• docs/adr/0001-runtime-engine-created-once.md

Architecture rules

• RuntimeEngine is long-lived, created once at startup from the CompiledAgentGraph.
• ExecutionContext is per-request and carries all request-scoped state.
• The compiled graph is immutable at runtime.
• The runtime operates only on compiled, typed models — never raw YAML.

Implementation rules

• Construct the engine only on startup paths; never inside request handlers.
• Do not put request state (identity, tenant, current request, rendered prompts) on RuntimeEngine or the compiled graph.
• Pass ExecutionContext explicitly through routing, context resolution, prompt rendering, and tool execution.
• Keep the engine concurrency-safe by keeping it stateless w.r.t. requests.
• Build the engine in src/agentplatform/runtime; the graph in src/agentplatform/graph.

Validation checklist

• Engine constructed once (startup), not per request.
• No request-scoped fields on the engine or graph.
• All per-request data lives on ExecutionContext.
• Compiled graph treated as immutable.
• Tests cover concurrent requests not leaking state.
• make check passes.

Common mistakes to avoid

• Recreating the runtime or recompiling the graph per request.
• Storing "current user/request" on the engine.
• Mutating the compiled graph during execution.
• Hidden global/singleton request state.