---
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
---

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/runtime-engine.md and run `make generate-ai`.
-->

# 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.