type-contracts.md

AgentCeption — Type Contracts Reference

Updated: 2026-03-15 | Reflects the full entity surface including shared type aliases (JsonValue, JsonSchemaObj), MCP method-level result TypedDicts, query result TypedDicts, plan tool result TypedDicts, the planner/executor architecture, stall detection, plan-scoped branches, daily metrics, org presets, working memory, and task runner protocol. Any and object do not exist in any production file. JsonValue uses invariant list/dict — no covariance. Every type boundary is named.

This document is the single source of truth for every named entity (TypedDict, Pydantic BaseModel, SQLAlchemy ORM class, Enum, Protocol) in the AgentCeption codebase. It covers the full contract of each type: fields, types, optionality, and intended use.

---

Table of Contents

1. Design Philosophy
2. Shared Type Aliases (agentception/types.py)
3. Domain Models (agentception/models/)
   • Agent Lifecycle
   • Pipeline State
   • Agent Task Spec
   • Pipeline Configuration
   • Spawn API
   • Role Studio API
   • Cognitive Architecture API
   • Template API
   • Org Tree
   • PlanSpec — YAML Contract
   • EnrichedManifest — Coordinator Contract
   • Execution Plan
4. Health Model
5. Config Types (agentception/config.py)
6. ORM Models (agentception/db/models.py)
7. Query TypedDicts (agentception/db/queries/types.py)
   • Issue and PR Rows
   • Agent Run Rows
   • Wave and Conductor Rows
   • Phase and Board Rows
   • Workflow and Dispatch Rows
   • MCP Query Rows
   • Metrics Rows
8. LLM Service Types (agentception/services/llm.py)
9. Code Indexer Types (agentception/services/code_indexer.py)
10. Working Memory Types (agentception/services/working_memory.py)
11. Task Runner Protocol (agentception/services/task_runner.py)
12. MCP Protocol Types (agentception/mcp/types.py)
    • MCP Method-Level Result Types
    • MCP Result Payload Union
13. MCP Query Result Types (agentception/mcp/query_tools.py)
14. MCP Plan Tool Result Types (agentception/mcp/plan_tools.py)
15. Workflow Types
    • Status (workflow/status.py)
    • State Machine (workflow/state_machine.py)
    • Link Discovery (workflow/linking.py)
    • Invariants (workflow/invariants.py)
16. Intelligence Types
    • Dependency DAG (intelligence/dag.py)
    • Issue Analyzer (intelligence/analyzer.py)
    • Pipeline Guards (intelligence/guards.py)
    • Scaling (intelligence/scaling.py)
    • A/B Results (intelligence/ab_results.py)
17. Telemetry Types (agentception/telemetry.py)
18. Org Preset Types (agentception/data/org_presets.py)
19. Entity Hierarchy
20. Entity Graphs (Mermaid)

---

Design Philosophy

Every entity in this codebase follows five rules:

1. No Any. No object. Ever. Both collapse type safety for downstream callers. Every boundary is typed with a concrete named entity — TypedDict, BaseModel, Protocol, or a specific union.

2. No covariance in type aliases. JsonValue uses invariant list/dict, never covariant Sequence/Mapping. If a function's return contains list[str] values in a dict, create a TypedDict for that specific shape instead of forcing dict[str, JsonValue].

3. Boundaries own coercion. When external data arrives (JSON from GitHub, DB rows, YAML files), the boundary module coerces it to the canonical internal type. Downstream code always sees clean types. JsonValue is reserved for genuinely dynamic JSON with unknown shape (e.g. raw json.loads() / yaml.safe_load() output before validation).

4. TypedDicts for read-only query results, Pydantic for validated I/O. DB query functions return TypedDict rows — plain, fast, no validation overhead. HTTP request/response bodies and pipeline config use Pydantic BaseModel so validation errors surface at the boundary with clear messages. MCP tool results and query results each get their own named TypedDict.

5. ORM models stay in db/. SQLAlchemy Base subclasses never cross into routes/ or services/. They are converted to TypedDict rows by query functions in db/queries/.

What to use instead

Banned	Use instead
Any	TypedDict, BaseModel, specific union
object	The actual type or a constrained union
list (bare)	list[X] with concrete element type
dict (bare)	dict[K, V] with concrete key/value types
dict[str, X] with known keys	TypedDict or BaseModel — name the keys
Sequence/Mapping in type aliases	list/dict — no covariance
cast(T, x)	Fix the callee to return T
# type: ignore	Fix the underlying type error

---

Shared Type Aliases

Path: agentception/types.py

Cross-cutting type aliases referenced by multiple packages (services, readers, routes, MCP, etc.).

JsonValue

TypeAlias — The true runtime type of json.loads() and yaml.safe_load() output. Only used for genuinely dynamic JSON with unknown shape — known structures always get their own named TypedDict.

JsonValue: TypeAlias = (
    str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
)

Uses invariant list/dict (not covariant Sequence/Mapping). This means list[str] is NOT list[JsonValue] — if you need to put list[str] values inside a dict, create a TypedDict for that dict shape instead of using dict[str, JsonValue].

JsonSchemaObj

TypeAlias — A JSON Schema object (Draft-07 / OpenAPI 3.x compatible). The schema spec is inherently recursive (items, properties values, allOf members are all schemas themselves), so the value type is JsonValue.

JsonSchemaObj: TypeAlias = dict[str, JsonValue]

Used for ToolFunction.parameters, plan_get_schema() return, and any MCP inputSchema field.

---

Domain Models

Path: agentception/models/__init__.py

All Pydantic BaseModel subclasses. Wire format is snake_case throughout.

Agent Lifecycle

AgentStatus

str, Enum — Lifecycle state of a single pipeline agent. Mirror of agentception.workflow.status.AgentStatus.

Value	Meaning
"pending_launch"	Worktree created, task runner not yet started
"implementing"	Agent is actively writing code
"blocked"	Agent reported a blocker via MCP
"reviewing"	PR open, awaiting review
"completed"	PR merged; work done
"cancelled"	Run explicitly cancelled
"stopped"	Run stopped (agent stopped itself)
"failed"	Run failed with an error

The canonical AgentStatus in agentception/workflow/status.py includes two additional states not present in the models mirror: "stalled" (set by poller watchdog when no DB heartbeat progress) and "recovering" (set on auto-heal / re-dispatch attempts). See Workflow Status for the full state machine.

AgentNode

BaseModel — A single agent in the pipeline tree, for the Build dashboard.

Field	Type	Default	Description
id	str	required	Worktree basename or UUID
role	str	required	Role slug (e.g. "python-developer")
status	AgentStatus	required	Current lifecycle state
issue_number	int | None	None	GitHub issue being worked
pr_number	int | None	None	GitHub PR opened by this agent
branch	str | None	None	Git branch name
batch_id	str | None	None	Batch this run belongs to
worktree_path	str | None	None	Container-side worktree path
message_count	int	0	Number of transcript messages
last_activity_mtime	float	0.0	File mtime of last transcript write
children	list[AgentNode]	[]	Sub-agents spawned by this agent
cognitive_arch	str | None	None	Arch string (e.g. "feynman:python")
tier	str | None	None	"coordinator" | "worker"
org_domain	str | None	None	"c-suite" | "engineering" | "qa"
parent_run_id	str | None	None	Run ID of spawning agent

StaleClaim

BaseModel — A GitHub issue with agent/wip label but no local worktree.

Field	Type	Description
issue_number	int	GitHub issue number
issue_title	str	Issue title
worktree_path	str	Expected path that does not exist

Pipeline State

BoardIssue

BaseModel — Lightweight issue summary for the overview board sidebar.

Field	Type	Default	Description
number	int	required	GitHub issue number
title	str	required	Issue title
state	str	"open"	"open" or "closed"
labels	list[str]	[]	Label name strings
claimed	bool	False	Whether agent/wip label is set
phase_label	str | None	None	Active phase label at last sync
last_synced_at	str | None	None	ISO-8601 UTC timestamp

PlanDraftEvent

BaseModel — A plan-draft lifecycle event emitted by the poller.

Field	Type	Default	Description
event	str	required	"plan_draft_ready" | "plan_draft_timeout"
draft_id	str	required	Stable draft identifier
yaml_text	str	""	Raw YAML (filled for plan_draft_ready)
output_path	str	required	Absolute path of the output file

StalledAgentEvent

BaseModel — Structured record of a stalled agent emitted by the poller on every tick.

Field	Type	Description
run_id	str	Agent run identifier
issue_number	int	GitHub issue number
worktree_path	str	Container-side worktree path
last_activity_at	str	ISO-format UTC timestamp from the DB row
stalled_for_minutes	int	Minutes since last DB heartbeat

PipelineState

BaseModel — Snapshot of the entire pipeline at a point in time. Served to the dashboard via SSE.

Field	Type	Default	Description
active_label	str | None	required	Currently active phase label
issues_open	int	required	Count of open GitHub issues
prs_open	int	required	Count of open GitHub PRs
agents	list[AgentNode]	required	All live agent nodes (tree)
alerts	list[str]	[]	Human-readable alert strings
stale_claims	list[StaleClaim]	[]	Issues with dangling agent/wip labels
board_issues	list[BoardIssue]	[]	Unclaimed issues for the active phase
polled_at	float	required	UNIX timestamp of this snapshot
closed_issues_count	int	0	Issues closed in the last 24 hours
merged_prs_count	int	0	PRs merged in the last 24 hours
stale_branches	list[str]	[]	Local branches without a live worktree
pending_approval	list[dict[str, JsonValue]]	[]	Issues awaiting human approval
plan_draft_events	list[PlanDraftEvent]	[]	New plan-draft events for this tick
loop_guard_triggered	list[str]	[]	Run IDs flagged by loop guard
stalled_agents	list[StalledAgentEvent]	[]	Agents with stale DB heartbeats

Agent Task Spec

IssueSub

BaseModel — One entry in a coordinator's dispatch queue.

Field	Type	Default
number	int	required
title	str	""
role	str	""
cognitive_arch	str	""
depends_on	list[int]	[]
file_ownership	list[str]	[]
branch	str | None	None

PRSub

BaseModel — One entry in a QA coordinator's review queue.

Field	Type	Default
number	int	required
title	str	""
branch	str	""
role	str	""
cognitive_arch	str	""
grade_threshold	str	""
merge_order	int	0
closes_issues	list[int]	[]

AgentTaskSpec

BaseModel — In-memory representation of all task context for one agent run. Populated exclusively from the ACAgentRun DB row. All fields are optional; the DB row is the single source of truth.

Group	Field	Type	Default	Description
Core	task	str | None	None	Task description
	id	str | None	None	Task identifier
	attempt_n	int	0	Attempt number
	is_resumed	bool	False	Whether this is a resumed task
Agent	role	str | None	None	Role slug
	tier	str | None	None	"coordinator" | "worker"
	org_domain	str | None	None	"c-suite" | "engineering" | "qa"
	cognitive_arch	str | None	None	Arch string
Repo	gh_repo	str | None	None	owner/name
	base	str | None	None	Base branch
Pipeline	batch_id	str | None	None	Wave batch identifier
	parent_run_id	str | None	None	Spawning agent's run ID
	coord_fingerprint	str | None	None	Coordinator run_id that spawned this
	spawn_mode	str | None	None	Spawn mode string
Target	issue_number	int | None	None	Target GitHub issue
	pr_number	int | None	None	Target GitHub PR
	closes_issues	list[int]	[]	Issues closed by the PR
Worktree	worktree	str | None	None	Worktree path
	branch	str | None	None	Git branch name
Ad-hoc	task_description	str | None	None	Inline task description
	prompt_variant	str | None	None	A/B prompt variant tag
Planning	draft_id	str | None	None	Plan draft identifier
	output_path	str | None	None	Plan output file path
	output_format	str | None	None	Expected output format
	domain	str | None	None	Domain scope
	issue_queue	list[IssueSub]	[]	Issues to spawn
	pr_queue	list[PRSub]	[]	PRs to review
Extended	depends_on	list[int]	[]	Dependency issue numbers
	spawn_sub_agents	bool	False	Whether to spawn children
	wave	str | None	None	Wave identifier
	vp_fingerprint	str | None	None	VP run_id fingerprint
	session_id	str | None	None	Task runner session ID
	on_block	str | None	None	Block handler instruction
	required_output	str | None	None	Output requirement
	file_ownership	list[str]	[]	Files this agent owns
	files_changed	list[str]	[]	Files already changed
	grade_threshold	str | None	None	QA grade threshold
	has_migration	bool	False	Whether issue involves DB migration
	merge_after	str | None	None	Merge order constraint
	linked_pr	int | None	None	Linked PR number

Pipeline Configuration

AbModeConfig

BaseModel — A/B mode configuration for role file experimentation.

Field	Type	Default	Description
enabled	bool	False	Whether A/B mode is active
target_role	str | None	None	Role slug being experimented on
variant_a_file	str | None	None	Path to variant A role file
variant_b_file	str | None	None	Path to variant B role file

ProjectConfig

BaseModel — A single project entry in pipeline-config.json.

Field	Type	Default	Description
name	str	required	Display name for the project
gh_repo	str	required	GitHub owner/repo string
repo_dir	str | None	None	Override for the local repo path
worktrees_dir	str | None	None	Override for worktrees directory
ide_project_id	str | None	None	Optional IDE/client project slug (e.g. for transcript lookup)

PipelineConfig

BaseModel — Validated shape of .agentception/pipeline-config.json.

Field	Type	Default	Description
coordinator_limits	dict[str, int]	{"engineering-coordinator": 1, "qa-coordinator": 1}	Max concurrent coordinator instances
pool_size	int	4	Leaf agents per coordinator
active_labels_order	list[str]	[]	Ordered phase labels for auto-advance
ab_mode	AbModeConfig	AbModeConfig()	A/B experimentation config
projects	list[ProjectConfig]	[]	All configured projects
active_project	str | None	None	Name of the active project
approval_required_labels	list[str]	["db-schema", "security", "api-contract"]	Labels that trigger approval gate
phase_advance_blocked_label	str	"pipeline/gated"	Label removed on phase advance
phase_advance_active_label	str	"pipeline/active"	Label added on phase advance
max_attempts	int	3	Max message_count before loop guard triggers
stall_threshold_minutes	int	30	Minutes of DB-heartbeat silence before STALLED

SwitchProjectRequest

BaseModel — Request body for POST /api/config/switch-project.

Field	Type	Description
project_name	str	Must match the name field of a ProjectConfig entry

Spawn API

SpawnRequest / SpawnResult

Model	Field	Type	Description
SpawnRequest	issue_number	int	Issue to work on
	role	str	Role slug (validated against taxonomy)
SpawnResult	spawned	int	Issue number that was spawned
	worktree	str	Container-side worktree path
	host_worktree	str	Host-side path for the worktree
	branch	str	Git branch name
	agent_task	str	Raw DB context row content
	spawned_at	str	ISO-8601 UTC timestamp

SpawnConductorRequest / SpawnConductorResult

Model	Field	Type	Description
SpawnConductorRequest	phases	list[str]	Phase labels to conduct
	org	str | None	Org scope override
SpawnConductorResult	wave_id	str	Generated conductor ID
	worktree	str	Container-side path
	host_worktree	str	Host-side path
	branch	str	Git branch
	agent_task	str	DB context row content

SpawnCoordinatorRequest / SpawnCoordinatorResult

Model	Field	Type	Description
SpawnCoordinatorRequest	plan_text	str	Free-form planning text
	label_prefix	str	Phase label prefix
SpawnCoordinatorResult	slug	str	Worktree directory name
	worktree	str	Container-side path
	host_worktree	str	Host-side path
	branch	str	Git branch
	agent_task	str	DB context row content

Role Studio API

Role file models

Model	Key Fields	Description
RoleMeta	slug, path, line_count, mtime, last_commit_sha, last_commit_message	File metadata without content
RoleContent	slug, content, meta: RoleMeta	Full file with metadata — GET /api/roles/{slug}
RoleUpdateRequest	content: str	Request body for PUT /api/roles/{slug}
RoleUpdateResponse	slug, diff, meta: RoleMeta	Diff and refreshed metadata
RoleDiffRequest	content: str	Proposed content for preview
RoleDiffResponse	slug, diff	Unified diff vs HEAD
RoleCommitRequest	content: str	Content to write and commit
RoleCommitResponse	slug, commit_sha, message	Resulting git SHA
RoleVersionEntry	sha, label, timestamp: int	One version in history
RoleVersionInfo	current: str, history: list[RoleVersionEntry]	Version tracking data
RoleVersionsResponse	slug, versions: RoleVersionInfo	GET /api/roles/{slug}/versions
RoleHistoryEntry	sha, date, subject	One git log entry for a role file's revision history

Cognitive Architecture API

TaxonomyRole

BaseModel — Single role from the org hierarchy taxonomy.

Field	Type	Description
slug	str	Role identifier
label	str	Display name
title	str	Job title
category	str	Role category
description	str	Role description
spawnable	bool	Whether directly spawnable
compatible_figures	list[str]	Compatible persona slugs
compatible_skill_domains	list[str]	Compatible skill IDs
file_exists	bool	Whether role Markdown file exists

TaxonomyLevel

BaseModel — One tier of the org hierarchy.

Field	Type	Description
id	str	Tier identifier
label	str	Display name (e.g. "C-Suite")
description	str	Tier description
roles	list[TaxonomyRole]	All roles in this tier

TaxonomyResponse: levels: list[TaxonomyLevel] — GET /api/roles/taxonomy.

PersonaEntry

BaseModel — A single historical/industry figure from the cognitive arch library.

Field	Type	Description
id	str	Figure slug (e.g. "feynman")
display_name	str	Display name
layer	str	Arch layer ("figures")
extends	str	Parent archetype slug
description	str	Short description
prompt_prefix	str	Injected context block at spawn
overrides	dict[str, str]	Atom dimension overrides

PersonasResponse: personas: list[PersonaEntry] — GET /api/roles/personas.

Atom models

Model	Fields	Description
AtomValue	id, label, description	One value within a dimension
AtomDimension	dimension, description, values: list[AtomValue]	One cognitive atom
AtomsResponse	atoms: list[AtomDimension]	GET /api/roles/atoms

Template API

Model	Key Fields	Description
TemplateExportRequest	name, version	Request to export a template
TemplateManifest	name, version, created_at, gh_repo, files: list[str]	Archive metadata
TemplateConflict	path, exists: bool	File conflict during import
TemplateImportResult	name, version, extracted: list[str], conflicts: list[TemplateConflict]	Import result
TemplateListEntry	filename, name, version, created_at, gh_repo, size_bytes: int	Archive listing

Org Tree

OrgTreeRole

BaseModel — A role entry in the org tree.

Field	Type	Description
slug	str	Role identifier
name	str	Display name
tier	str	"c-suite" | "coordinator" | "worker"
assigned_phases	list[str]	Phase labels assigned to this role
figures	list[str]	First two compatible figure slugs

OrgTreeNode

BaseModel — One node in the D3 org tree (recursive).

Field	Type	Description
name	str	Display name
id	str	Node identifier
tier	str	Tier label
roles	list[OrgTreeRole]	Role cards at this level
children	list[OrgTreeNode]	Sub-nodes (recursive)

PlanSpec — YAML Contract

The typed YAML contract between Phase 1A (LLM planner) and Phase 1B (human review).

PlanIssue

BaseModel — A single GitHub issue to be created.

Field	Type	Default	Description
id	str	required	Stable kebab-case slug (e.g. "auth-001")
title	str	required	Issue title
body	str	required	Markdown body
depends_on	list[str]	[]	Issue IDs (not titles) this issue depends on
skills	list[str]	[]	Skill domain IDs from cognitive arch catalog
cognitive_arch	str	""	Resolved arch string ("figure:skill1[:skill2]")

PlanPhase

BaseModel — A sequenced phase grouping related issues.

Field	Type	Default	Description
label	str	required	Phase label — must match ^[0-9]+-[a-z0-9][a-z0-9-]*$
description	str	required	One-sentence gate criterion
depends_on	list[str]	[]	Phase labels that must complete first
issues	list[PlanIssue]	required	Non-empty list of issues

PlanSpec

BaseModel — Root schema for the plan-step-v2 YAML contract.

Field	Type	Default	Description
initiative	str	required	Short slug (e.g. "auth-rewrite")
phases	list[PlanPhase]	required	Non-empty; phase 0 has no deps
coordinator_arch	dict[str, str]	{}	Maps coordinator role slugs to arch strings

Invariants: phases non-empty; phase depends_on DAG (no forward refs, no cycles); issue IDs globally unique; issue depends_on references valid IDs.

Serialization: to_yaml() -> str / from_yaml(text: str) -> PlanSpec.

EnrichedManifest — Coordinator Contract

Produced by the LLM coordinator after enriching a PlanSpec with full issue bodies and metadata.

EnrichedIssue

BaseModel — A fully-specified GitHub issue with acceptance criteria.

Field	Type	Default	Description
title	str	required	Issue title
body	str	required	Markdown body
labels	list[str]	required	GitHub label strings
phase	str	required	Phase label
depends_on	list[str]	[]	Issue titles that must merge first
can_parallel	bool	True	Whether safe to run concurrently
acceptance_criteria	list[str]	required	Completion criteria
tests_required	list[str]	required	Required test scenarios
docs_required	list[str]	required	Required doc updates

EnrichedPhase

BaseModel — A sequenced phase in an EnrichedManifest.

Field	Type	Default	Description
label	str	required	Phase slug
description	str	required	Gate criterion
depends_on	list[str]	[]	Phase labels that must complete first
issues	list[EnrichedIssue]	required	Issues in this phase
parallel_groups	list[list[str]]	required	Concurrent execution groups by title

EnrichedManifest

BaseModel — Root coordinator input contract.

Field	Type	Description
initiative	str | None	Initiative slug
phases	list[EnrichedPhase]	Non-empty phase list
total_issues	int	Computed: sum(len(p.issues) for p in phases)
estimated_waves	int	Computed: critical-path length through dep graph

Execution Plan

PlanOperation

BaseModel — A single atomic file operation produced by the planner agent. Maps 1-to-1 to a tool call the executor agent will make.

Field	Type	Default	Description
tool	Literal["replace_in_file", "insert_after_in_file", "write_file"]	required	Operation type
file	str	required	Relative path from worktree root
old_string	str | None	None	Text to replace (replace_in_file)
new_string	str | None	None	Replacement text (replace_in_file)
after	str | None	None	Line to insert after (insert_after_in_file)
text	str | None	None	Text to insert (insert_after_in_file)
content	str | None	None	File content (write_file)

ExecutionPlan

BaseModel — Immutable ordered list of file operations for implementing a single GitHub issue.

Field	Type	Default	Description
run_id	str	required	Agent run identifier
issue_number	int	required	Target GitHub issue
operations	list[PlanOperation]	required	Non-empty ordered operations
created_at	datetime	auto	UTC creation timestamp

FileEditEvent

BaseModel (frozen) — A single file-edit event carrying a unified diff for inspector-panel rendering.

Field	Type	Default	Description
timestamp	datetime	required	When the edit occurred
path	str	required	Relative path in the worktree
diff	str	required	Unified diff string (max 120 visible lines)
lines_omitted	int	0	Count of hidden lines when truncated

---

Health Model

Path: agentception/models/health.py

HealthSnapshot

BaseModel — Point-in-time system health metrics. Returned by GET /api/health/detailed.

Field	Type	Constraint	Description
uptime_seconds	float	≥ 0.0	Seconds since process start
memory_rss_mb	float	≥ 0.0	Resident Set Size in MB
active_worktree_count	int	≥ 0	Live git worktrees on disk
github_api_latency_ms	float	—	Most recent GitHub API probe latency; -1.0 if never run

---

Config Types

Path: agentception/config.py

TaskRunnerChoice

str, Enum — Task runner backend for agent execution. Agent tasks run via the server-side agent loop.

Value	Description
"anthropic"	Direct Anthropic (or local LLM) API calls (default)

LLMProviderChoice

str, Enum — Which LLM backend to use for completion, streaming, and tool-use.

Value	Description
"anthropic"	Anthropic Messages API (default)
"local"	OpenAI-compatible local server

AgentCeptionSettings

BaseSettings — Service configuration mapped from environment variables.

Key fields (not exhaustive — see config.py for the full list):

Field	Type	Env Var	Description
worktrees_dir	str	WORKTREES_DIR	Container-side worktrees directory
host_worktrees_dir	str	HOST_WORKTREES_DIR	Host-side worktrees directory
repo_dir	str	REPO_DIR	Container-side repo directory
gh_repo	str	GH_REPO	GitHub owner/repo string
ac_api_key	str | None	AC_API_KEY	API key for agent callback authentication
anthropic_api_key	str | None	ANTHROPIC_API_KEY	Anthropic API key
ac_task_runner	TaskRunnerChoice	AC_TASK_RUNNER	Agent execution backend (currently anthropic only)
llm_provider	LLMProviderChoice	LLM_PROVIDER	LLM provider selection
database_url	str	DATABASE_URL	PostgreSQL connection string
qdrant_url	str	QDRANT_URL	Qdrant vector DB URL

---

ORM Models

Path: agentception/db/models.py

SQLAlchemy async Base subclasses. Never exposed directly to routes — consumed through db/queries/ functions that return named TypedDict rows.

Table	Class	Primary Key	Purpose
waves	ACWave	id: str	One row per batch spawn ("Start Wave")
agent_runs	ACAgentRun	id: str	Lifecycle of one agent working one issue
issues	ACIssue	(github_number, repo)	Mirror of a GitHub issue (hash-diff sync)
pull_requests	ACPullRequest	(github_number, repo)	Mirror of a GitHub PR (hash-diff sync)
agent_messages	ACAgentMessage	id: int (autoincrement)	One agent transcript message
agent_events	ACAgentEvent	id: int (autoincrement)	Structured MCP callback events
initiative_phases	ACInitiativePhase	(repo, initiative, batch_id, phase_label)	Phase DAG per initiative
pipeline_snapshots	ACPipelineSnapshot	id: int (autoincrement)	Time-series tick state
pr_issue_links	ACPRIssueLink	id: int (autoincrement)	PR↔Issue linkage with provenance
issue_workflow_state	ACIssueWorkflowState	(repo, issue_number)	Canonical swim-lane state per issue
plan_issues	ACPlanIssue	(plan_id, repo, issue_number)	Issues belonging to a plan batch
plan_branches	ACPlanBranch	(plan_id, repo)	Integration branch per plan
execution_plans	ACExecutionPlan	run_id: str	Planner/executor immutable plan

Key field contracts

ACAgentRun — selected fields

Field	Type	Description
id	String(512)	Worktree basename or UUID
status	String(64)	IMPLEMENTING | REVIEWING | DONE | STALE | UNKNOWN
tier	String(64) | None	coordinator | worker
org_domain	String(64) | None	c-suite | engineering | qa
parent_run_id	String(512) | None	Spawning agent's run ID
cognitive_arch	String(256) | None	Arch string at spawn
task_description	Text | None	Inline task description for ad-hoc runs
gh_repo	String(256) | None	GitHub owner/repo slug
plan_id	String(128) | None	Plan-scoped integration branch ID
plan_branch	String(256) | None	Branch name for this plan
is_resumed	Boolean	Whether this run is a retry
coord_fingerprint	String(256) | None	Coordinator run_id fingerprint
total_input_tokens	Integer	Cumulative input tokens
total_output_tokens	Integer	Cumulative output tokens
total_cache_write_tokens	Integer	Tokens written to prompt cache
total_cache_read_tokens	Integer	Tokens read from prompt cache
prompt_variant	String(64) | None	A/B prompt variant tag

ACIssueWorkflowState — key fields

Field	Type	Description
lane	String(32)	todo | active | pr_open | reviewing | done
issue_state	String(32)	open | closed
pr_link_method	String(64) | None	explicit | body_closes | branch_regex | run_pr_number | title_mention
pr_link_confidence	Integer | None	0–100 reliability score

ACPRIssueLink — link methods

Value	Confidence	Evidence
explicit	100	Directly written by build_report_done
body_closes	95	Closes #N pattern in PR body
branch_regex	90	agent/issue-{N} branch naming
run_pr_number	85	Agent run's stored pr_number
title_mention	varies	Title keyword match

ACPlanIssue — plan membership

Field	Type	Description
plan_id	String(128)	Filing batch identifier
repo	String(256)	GitHub owner/repo
issue_number	Integer	GitHub issue number

ACPlanBranch — integration branch

Field	Type	Description
plan_id	String(128)	Filing batch identifier
repo	String(256)	GitHub owner/repo
branch_name	String(256)	Integration branch name

ACExecutionPlan — planner/executor

Field	Type	Description
run_id	String(512)	FK-equivalent to agent_runs.id
issue_number	Integer	Target issue
plan_json	Text	Serialised ExecutionPlan JSON (immutable)
created_at	DateTime	Plan creation timestamp

---

Query TypedDicts

Path: agentception/db/queries/types.py

All query functions return plain TypedDict instances. No SQLAlchemy ORM objects cross this boundary. All datetime fields are serialised as ISO-8601 UTC strings.

Issue and PR Rows

TypedDict	Fields	Returned by
LabelEntry	name: str	Embedded in board rows
BoardIssueRow	number, title, state, labels: list[LabelEntry], claimed, phase_label, last_synced_at	get_board_issues()
AllIssueRow	number, title, state, labels: list[str], phase_label, closed_at, last_synced_at	get_all_issues()
LinkedIssueRow	number, title, state	Embedded in PRDetailRow
IssueDetailRow	number, title, body, state, labels: list[str], phase_label, claimed, first_seen_at, last_synced_at, closed_at, linked_prs: list[LinkedPRRow], agent_runs: list[IssueAgentRunRow]	get_issue_detail()
IssueAgentRunRow	id, role, status, branch, pr_number, spawned_at, last_activity_at	Embedded in IssueDetailRow
AllPRRow	number, title, state, head_ref, labels: list[str], closes_issue_number, merged_at, last_synced_at	get_all_prs_db()
OpenPRRow	number, title, state, headRefName, labels: list[LabelEntry]	get_open_prs_db()
LinkedPRRow	number, title, state, head_ref, merged_at	Embedded in IssueDetailRow
PRDetailRow	number, title, state, head_ref, labels: list[str], closes_issue_number, merged_at, first_seen_at, last_synced_at, linked_issue: LinkedIssueRow | None, agent_runs: list[PRAgentRunRow]	get_pr_detail()
PRAgentRunRow	id, role, status, branch, issue_number, spawned_at, last_activity_at	Embedded in PRDetailRow
OpenPRForIssueRow	pr_number: int, head_ref: str | None	get_open_prs_by_issue()

Agent Run Rows

TypedDict	Fields	Returned by
AgentRunRow	id, wave_id, issue_number, pr_number, branch, worktree_path, role, status, attempt_number, spawn_mode, batch_id, spawned_at, last_activity_at, completed_at, tier, org_domain, parent_run_id	get_agent_run_history()
AgentMessageRow	role, content, tool_name, sequence_index, recorded_at	Embedded in AgentRunDetail
AgentRunDetail	id, issue_number, pr_number, branch, role, status, spawned_at, last_activity_at, completed_at, batch_id, cognitive_arch, tier, org_domain, parent_run_id, messages: list[AgentMessageRow]	get_agent_run_detail()
SiblingRunRow	id, role, status, issue_number, tier	get_sibling_runs()
AgentRunTeardownRow	worktree_path: str | None, branch: str | None, plan_branch: str | None	get_agent_run_for_teardown() (all fields optional — total=False)
AgentEventRow	id: int, event_type, payload: str (raw JSON), recorded_at	get_agent_events_tail()
AgentThoughtRow	seq: int, role, content, tool_name, recorded_at	get_agent_thoughts_tail()
PendingLaunchRow	run_id, issue_number, role, branch, worktree_path, host_worktree_path, batch_id, spawned_at, tier, org_domain, parent_run_id	get_pending_launches()
BatchSummaryRow	batch_id, spawned_at, total_count, active_count	get_batch_summaries_for_initiative()

Wave and Conductor Rows

TypedDict	Fields	Description
WaveAgentRow	id, role, status, issue_number, pr_number, branch, batch_id, worktree_path, cognitive_arch, message_count	Agent entry inside a wave
WaveRow	batch_id, started_at: float, ended_at: float | None, issues_worked: list[int], prs_opened, prs_merged, estimated_tokens, estimated_cost_usd, agents: list[WaveAgentRow]	get_waves_from_db()
ConductorHistoryRow	wave_id, worktree, host_worktree, started_at, status	get_conductor_history()

Phase and Board Rows

TypedDict	Fields	Description
PipelineTrendRow	polled_at, active_label, issues_open, prs_open, agents_active, alert_count	get_pipeline_trend()
PhasedIssueRow	number, title, body_excerpt, state, url, labels, depends_on: list[int]	Issue in a phase group
PhaseGroupRow	label, issues: list[PhasedIssueRow], locked: bool, complete: bool, depends_on: list[str]	get_issues_grouped_by_phase()
ShipReviewerRunRow	id, status, spawned_at, last_activity_at	Latest reviewer run on Ship board
ShipPRRow	number, title, state, head_ref, url, labels: list[str], closes_issue_number, merged_at, phase_label, reviewer_run: ShipReviewerRunRow | None	PR on Ship board
ShipPhaseGroupRow	label, prs: list[ShipPRRow]	Phase group on Ship board
InitiativePhaseMeta	label, order: int, depends_on: list[str]	get_initiative_phase_meta()
PhaseSummary	label, count: int	Phase count for launch modal
IssueSummary	number: int, title: str	Issue for launch modal picker
LabelContext	phases: list[PhaseSummary], issues: list[IssueSummary]	get_label_context()
BlockedDepsRow	github_number: int, dep_numbers: list[int]	get_blocked_deps_open_issues()

Workflow and Dispatch Rows

TypedDict	Fields	Description
WorkflowStateRow	lane, issue_state, run_id, agent_status, pr_number, pr_state, pr_base, pr_head_ref, pr_link_method, pr_link_confidence, warnings: list[str]	get_workflow_state_for_issues()
RunForIssueRow	id, role, cognitive_arch, status, agent_status, pr_number, branch, spawned_at, last_activity_at, current_step, steps_completed, tier, org_domain, batch_id	get_runs_for_issue_numbers()
RunTreeNodeRow	id, role, status, agent_status, tier, org_domain, parent_run_id, issue_number, pr_number, batch_id, spawned_at, last_activity_at, current_step	get_run_tree_by_batch_id()

MCP Query Rows

TypedDict	Fields	Description
RunSummaryRow	run_id, status, role, issue_number, pr_number, branch, worktree_path, batch_id, tier, org_domain, parent_run_id, spawned_at, last_activity_at, completed_at	get_run_by_id(), get_children_by_parent_id()
RunContextRow	run_id, status, role, cognitive_arch, task_description, issue_number, pr_number, branch, worktree_path, batch_id, tier, org_domain, parent_run_id, gh_repo, is_resumed, coord_fingerprint, spawned_at, last_activity_at, completed_at, pr_base_branch	get_run_context() — full task context for MCP resource ac://runs/{run_id}/context
StatusCountRow	status: str, count: int	get_status_counts()
TerminalRunRow	id, worktree_path: str, branch: str | None	get_terminal_runs_with_worktrees()
InitiativeIssueRow	number, title, url, state	Embedded in InitiativePhaseRow
InitiativePhaseRow	label, short_label, order: int, is_active: bool, is_complete: bool, issues: list[InitiativeIssueRow]	Embedded in InitiativeSummary
InitiativeSummary	repo, initiative, batch_id, phase_count, issue_count, open_count, closed_count, filed_at, phases: list[InitiativePhaseRow]	get_initiative_summary()

Metrics Rows

TypedDict	Fields	Description
DailyMetrics	date, issues_closed, prs_merged, reviewer_runs, grade_a_count, grade_b_count, grade_c_count, grade_d_count, grade_f_count, first_pass_rate, rework_rate, avg_iterations, max_iter_hit_count, avg_cycle_time_seconds, cost_usd, cost_per_issue_usd, redispatch_count, auto_merge_rate	get_daily_metrics()

---

LLM Service Types

Path: agentception/services/llm.py

The LLM layer exposes a provider-agnostic contract: the same three entry points and types regardless of backend (Anthropic or local OpenAI-compatible). Callers use only these; provider selection is via settings.effective_llm_provider (see LLM contract and provider abstraction).

LLMChunk

TypedDict — One event yielded by completion_stream() (any provider).

Field	Type	Description
type	Literal["thinking", "content"]	Discriminant — thinking = reasoning token; content = output token. Consumers discard thinking and accumulate content.
text	str	Text fragment

Tool schema shapes

TypedDict	Fields	Description
ToolFunction	name: str, description: str, parameters: JsonSchemaObj	Function spec inside a tool definition
ToolDefinition	type: Literal["function"], function: ToolFunction	OpenAI-format tool definition passed to model

Tool call response shapes

TypedDict	Fields	Description
ToolCallFunction	name: str, arguments: str	Function call detail — arguments is JSON-encoded
ToolCall	id: str, type: Literal["function"], function: ToolCallFunction	One tool invocation returned by the model
ToolResponse	stop_reason: str, content: str, tool_calls: list[ToolCall], input_tokens: NotRequired[int], output_tokens: NotRequired[int], cache_creation_input_tokens: NotRequired[int], cache_read_input_tokens: NotRequired[int]	Return value from completion_with_tools()

ToolResponse.stop_reason values: "stop" (model finished), "tool_calls" (model wants to call tools), "length" (max tokens hit).

Token counting fields (all NotRequired): input_tokens covers all tokens billed this turn (including cached reads at their discounted rate). cache_creation_input_tokens and cache_read_input_tokens are non-zero only when prompt caching is active; used by telemetry to confirm cache hits and quantify per-turn discount.

Three public entry points (provider-agnostic):

Function	Returns	Use
completion(user_prompt, ...)	str	Single-turn completion; used by phase planner, recon, and local probe
completion_stream(user_prompt, ...)	AsyncGenerator[LLMChunk, None]	Streaming for plan preview; yields thinking/content chunks
completion_with_tools(messages, ...)	ToolResponse	Multi-turn tool-use for the agent loop

Internal adapters (e.g. call_anthropic, call_local_completion) implement these behaviours; callers must not use them directly.

---

Code Indexer Types

Path: agentception/services/code_indexer.py

Qdrant-backed semantic code search — self-hosted vector search for the agent loop.

IndexStats

TypedDict — Result returned by index_codebase().

Field	Type	Description
ok	bool	Whether indexing succeeded
files_indexed	int	Number of files processed
chunks_indexed	int	Number of vector chunks upserted
files_skipped	int	Number of files skipped (too large, binary, etc.)
error	str | None	Error message on failure; None on success

SearchMatch

TypedDict — A single result from search_codebase().

Field	Type	Description
file	str	Relative file path from repo root
chunk	str	The matching text chunk
score	float	Cosine similarity score (0.0–1.0)
start_line	int	1-based starting line number
end_line	int	1-based ending line number

_ChunkSpec (internal): chunk_id: int, file: str, text: str, start_line: int, end_line: int, symbol: str, file_hash: str — a raw chunk before embedding. symbol is the AST symbol name (e.g. "class Foo"; empty for char chunks). file_hash is a SHA-256 hex digest of the whole file. Not part of the public API.

Indexing parameters:

Constant	Value	Description
_CHUNK_SIZE	1500	Characters per chunk
_CHUNK_OVERLAP	200	Overlap between consecutive chunks
_MAX_FILE_BYTES	200000	Skip files larger than ~200 KB

---

Working Memory Types

Path: agentception/services/working_memory.py

FileEditEventJSON

TypedDict — JSON-safe representation of FileEditEvent. All fields are plain scalars.

Field	Type	Description
timestamp	str	ISO-format timestamp
path	str	Relative file path
diff	str	Unified diff string
lines_omitted	int	Hidden line count

WorkingMemoryJSON

TypedDict (total=False) — JSON-serialisable mirror of in-memory working memory state.

Field	Type	Description
plan	str	Current execution plan text
files_written	list[FileEditEventJSON]	File edit history
files_examined	list[str]	Files read during execution
findings	dict[str, str]	Key observations keyed by topic
decisions	list[str]	Architectural decisions made
next_steps	list[str]	Planned next actions
blockers	list[str]	Identified blockers

---

Task Runner Protocol

Path: agentception/services/task_runner.py

TaskRunner

Protocol — Abstraction for task execution engines. Implementations spawn agent processes with the given prompt and context.

Method	Signature	Description
run	(prompt: str, worktree_path: Path, mcp_server: str, role: str, run_id: str) -> str | None	Spawn an agent; returns session ID or None

Implementations: AnthropicTaskRunner (direct Anthropic API).

---

MCP Protocol Types

Path: agentception/mcp/types.py

Named TypedDict for every shape in the MCP JSON-RPC 2.0 wire protocol. No dict[str, object] or Any is used here. Every result payload has its own named TypedDict.

JSON-RPC 2.0 Error Constants

Constant	Value	Meaning
JSONRPC_ERR_PARSE_ERROR	-32700	Invalid JSON
JSONRPC_ERR_INVALID_REQUEST	-32600	Not a valid request object
JSONRPC_ERR_METHOD_NOT_FOUND	-32601	Unknown method
JSONRPC_ERR_INVALID_PARAMS	-32602	Invalid method parameters
JSONRPC_ERR_INTERNAL_ERROR	-32603	Internal server error

Tool protocol types

TypedDict	Fields	Description
ACToolDef	name, description, inputSchema: JsonSchemaObj	One tools/list item
ACToolContent	type: str ("text"), text: str	One content item in a tool result
ACToolResult	content: list[ACToolContent], isError: bool	tools/call result

Resource protocol types

TypedDict	Fields	Description
ACResourceDef	uri, name, description, mimeType	Static resource definition
ACResourceTemplate	uriTemplate, name, description, mimeType	Parameterised resource (RFC 6570)
ACResourceContent	uri, mimeType, text	One content item in a resources/read response
ACResourceResult	contents: list[ACResourceContent]	resources/read result (always 1 item)

ac:// URI scheme catalogue:

URI	Returns
ac://runs/active	All live runs
ac://runs/pending	Queued pending-launch runs
ac://runs/{run_id}	Single run metadata
ac://runs/{run_id}/children	Child runs
ac://runs/{run_id}/events	Structured event log (append ?after_id=N to paginate)
ac://runs/{run_id}/context	Full task context — RunContextRow with status, role, cognitive_arch, task_description, issue_number, worktree_path, pr_base_branch and related fields
ac://batches/{batch_id}/tree	Full batch run tree
ac://system/dispatcher	Dispatcher counters
ac://system/health	DB reachability + status counts
ac://system/config	Pipeline label config
ac://plan/schema	PlanSpec JSON Schema
ac://plan/labels	GitHub label catalogue
ac://plan/figures/{role}	Cognitive-arch figures for a role
ac://roles/list	All available role slugs
ac://roles/{slug}	Full role definition Markdown
ac://arch/figures	Index of all cognitive figures; returns {figures: [{id, display_name, description}]} sorted by id
ac://arch/archetypes	Index of all cognitive archetypes; returns {archetypes: [{id, display_name, description}]}
ac://arch/figures/{figure_id}	Full cognitive figure profile; id discoverable from ac://arch/figures
ac://arch/archetypes/{archetype_id}	Full archetype definition; id discoverable from ac://arch/archetypes
ac://arch/skills/{skill_id}	Full skill domain definition: id, display_name, description, characteristic patterns
ac://arch/atoms/{atom_id}	Full cognitive atom definition; atom ids include epistemic_style, quality_bar, error_posture

Prompt protocol types

TypedDict	Fields	Description
ACPromptArgument	name, description, required: bool	One argument a prompt accepts
ACPromptDef	name, description, arguments: list[ACPromptArgument]	prompts/list item
ACPromptContent	type: str ("text"), text: str	Text content inside a prompt message
ACPromptMessage	role: str ("user"), content: ACPromptContent	One message in a prompt result
ACPromptResult	description: str, messages: list[ACPromptMessage]	prompts/get result (1 message)

MCP Method-Level Result Types

Named TypedDicts for each MCP JSON-RPC method's result payload. Each method returns a specific, well-defined shape — no generic catch-all types.

TypedDict	Fields	MCP Method
McpServerInfo	name: str, version: str	Embedded in InitializeResult
McpCapabilities	tools: dict[str, str], resources: dict[str, str], prompts: dict[str, str]	Embedded in InitializeResult
InitializeResult	protocolVersion: str, capabilities: McpCapabilities, serverInfo: McpServerInfo	initialize
ToolListResult	tools: list[ACToolDef]	tools/list
PromptListResult	prompts: list[ACPromptDef]	prompts/list
ResourceListResult	resources: list[ACResourceDef]	resources/list
ResourceTemplateListResult	resourceTemplates: list[ACResourceTemplate]	resources/templates/list

MCP Result Payload Union

McpResultPayload is a TypeAlias union of all concrete result TypedDicts that can appear as the result field of a JsonRpcSuccessResponse:

McpResultPayload = (
    ACToolResult
    | ACPromptResult
    | ACResourceResult
    | InitializeResult
    | ToolListResult
    | PromptListResult
    | ResourceListResult
    | ResourceTemplateListResult
    | dict[str, str | int | float | bool | None]
)

The trailing dict[str, ...] arm covers simple scalar-valued responses (e.g. ping). Every structured result is a named TypedDict — no JsonValue or object in the union.

JSON-RPC 2.0 envelope types

TypedDict	Fields	Description
JsonRpcError	code: int, message: str, data: JsonValue	Error object in an error response
JsonRpcSuccessResponse	jsonrpc: str, id: int | str | None, result: McpResultPayload	Success response envelope
JsonRpcErrorResponse	jsonrpc: str, id: int | str | None, error: JsonRpcError	Error response envelope

---

MCP Query Result Types

Path: agentception/mcp/query_tools.py

Every MCP query function returns its own named TypedDict — no generic dict[str, JsonValue] for known shapes. Functions with found/not-found outcomes return explicit union types.

Query result TypedDicts

TypedDict	Fields	Returned by
PendingRunsResult	pending: list[PendingLaunchRow], count: int	query_pending_runs()
QueryRunFoundResult	ok: bool, run: RunSummaryRow	query_run() (found)
QueryRunNotFoundResult	ok: bool, error: str	query_run() (not found)
QueryContextFoundResult	ok: bool, context: RunContextRow	query_run_context() (found)
QueryChildrenResult	ok: bool, children: list[RunSummaryRow], count: int	query_children()
QueryEventsResult	ok: bool, events: list[AgentEventRow], count: int	query_run_events()
QueryActiveRunsResult	ok: bool, runs: list[RunSummaryRow], count: int	query_active_runs()
QueryRunTreeResult	ok: bool, nodes: list[RunTreeNodeRow], count: int	query_run_tree()
QueryDispatcherResult	ok: bool, status_counts: list[StatusCountRow], active_count: int, latest_batch_id: str | None	query_dispatcher_state()
QueryRunStatusFoundResult	ok: bool, run_id: str, status: str, completed_at: str | None	query_run_status() (found)
QueryHealthResult	ok: bool, db_ok: bool, status_counts: list[StatusCountRow], total_runs: int	query_system_health()

Function return types

Functions that can return different shapes use explicit union return types:

Function	Return Type
query_pending_runs()	PendingRunsResult
query_run(run_id)	QueryRunFoundResult | QueryRunNotFoundResult
query_run_context(run_id)	QueryContextFoundResult | QueryRunNotFoundResult
query_children(run_id)	QueryChildrenResult
query_run_events(run_id, after_id)	QueryEventsResult
query_active_runs()	QueryActiveRunsResult
query_run_tree(batch_id)	QueryRunTreeResult
query_dispatcher_state()	QueryDispatcherResult
query_run_status(run_id)	QueryRunStatusFoundResult | QueryRunNotFoundResult
query_system_health()	QueryHealthResult

---

MCP Plan Tool Result Types

Path: agentception/mcp/plan_tools.py

Every plan tool function returns its own named TypedDict. Validation tools use explicit union types for success/failure outcomes.

Plan tool TypedDicts

TypedDict	Fields	Returned by
CognitiveFigureEntry	id: str, display_name: str, description: str	Embedded in CognitiveFiguresResult
CognitiveFiguresResult	role: str, figures: list[CognitiveFigureEntry], error: NotRequired[str]	plan_get_cognitive_figures()
ValidateSpecSuccessResult	valid: bool, spec: dict[str, JsonValue]	plan_validate_spec() (success)
ValidationErrorResult	valid: bool, errors: list[str]	plan_validate_spec() / plan_validate_manifest() (failure)
RepoLabelEntry	name: str, description: str	Embedded in LabelsResult
LabelsResult	labels: list[RepoLabelEntry]	plan_get_labels()
ValidateManifestSuccessResult	valid: bool, manifest: dict[str, JsonValue], total_issues: int, estimated_waves: int	plan_validate_manifest() (success)

Function return types

Function	Return Type
plan_get_cognitive_figures(role)	CognitiveFiguresResult
plan_get_schema()	JsonSchemaObj
plan_validate_spec(spec_json)	ValidateSpecSuccessResult | ValidationErrorResult
plan_get_labels()	LabelsResult
plan_validate_manifest(json_text)	ValidateManifestSuccessResult | ValidationErrorResult

---

Workflow Types

Status

Path: agentception/workflow/status.py

The canonical agent status definitions — single source of truth for the lifecycle state machine.

AgentStatus (canonical)

str, Enum — 10 lifecycle states stored in agent_runs.status. The models-layer enum mirrors all values except stalled and recovering.

Value	Meaning
"pending_launch"	Worktree created, task runner not yet started
"implementing"	Agent is actively writing code
"blocked"	Agent reported a blocker via MCP
"reviewing"	PR open, awaiting review
"stalled"	Set by poller watchdog when no DB heartbeat progress
"recovering"	Set on auto-heal / re-dispatch attempts
"completed"	PR merged; work done
"cancelled"	Run explicitly cancelled
"stopped"	Run stopped (agent stopped itself)
"failed"	Run failed with an error

State machine transitions:

pending_launch → implementing : build_claim_run
pending_launch → cancelled    : build_cancel_run
implementing   → stalled      : poller watchdog (no commit progress)
implementing   → completed    : build_complete_run
implementing   → cancelled    : build_cancel_run
stalled        → recovering   : auto-heal / re-dispatch
stalled        → failed       : max_attempts exceeded
recovering     → implementing : re-dispatch succeeded
completed/cancelled/stopped/failed → terminal

Status sets (frozenset constants):

Constant	Values	Use
ACTIVE_STATUSES	implementing, blocked, reviewing, stalled, recovering	Run has a live worktree
LIVE_STATUSES	pending_launch + ACTIVE_STATUSES	Visible as "live" in the UI
TERMINAL_STATUSES	completed, cancelled, stopped, failed	No further transitions
RESUMABLE_STATUSES	blocked, stopped	Can be resumed
STALE_THRESHOLD	1800 seconds (30 min)	compute_agent_status() threshold

State Machine

Path: agentception/workflow/state_machine.py

The canonical swim-lane computation module. All lane assignments flow through here — no other code recomputes lanes.

IssueInput

TypedDict — Minimal issue fields consumed by the state machine.

Field	Type
number	int
state	str
labels	list[str]
phase_key	str | None
initiative	str | None

RunInput

TypedDict — Minimal agent-run fields consumed by the state machine.

Field	Type
id	str
status	str
agent_status	str
pr_number	int | None

WorkflowState

TypedDict — Canonical computed workflow state for one issue.

Field	Type	Description
lane	str	todo | active | pr_open | reviewing | done
issue_state	str	GitHub issue state
run_id	str | None	Most relevant run ID
agent_status	str | None	Computed agent status string
pr_number	int | None	Best-linked PR number
pr_state	str | None	PR state
pr_base	str | None	PR target branch
pr_head_ref	str | None	PR source branch
pr_link_method	str | None	How the PR was linked
pr_link_confidence	int | None	Link confidence (0–100)
warnings	list[str]	Surfaced to maintainer
content_hash	str	Hash of canonical state — update guard

Lane rules (explicit state machine — no if ladder):

Lane	Condition
done	Issue closed OR (PR merged AND closure stable)
reviewing	PR open AND agent_status == reviewing
pr_open	PR open (any link method, any base branch)
active	Agent run in active status, no open PR
todo	None of the above

Link Discovery

Path: agentception/workflow/linking.py

PR↔Issue link discovery and best-PR selection.

CandidateLink

TypedDict — One candidate PR↔Issue link produced by the linker.

Field	Type	Description
repo	str	owner/repo
pr_number	int	PR number
issue_number	int	Issue number
link_method	str	Discovery method
confidence	int	0–100 score
evidence_json	str	JSON blob with evidence

PRRow / RunRow (linker inputs)

TypedDict	Key Fields	Description
PRRow	number, title, head_ref, base_ref, body, labels	Minimal PR for link discovery
RunRow	id, issue_number, pr_number	Minimal run for run_pr_number signal

BestPR

TypedDict — Canonical PR associated with an issue after resolution.

Field	Type
pr_number	int
pr_state	str
pr_base	str | None
pr_head_ref	str | None
link_method	str
confidence	int

PRInfo: number, state, base_ref, head_ref — minimal PR metadata for best-PR selection.

Invariants

Path: agentception/workflow/invariants.py

Tick-level invariant checks and alerts for the workflow state machine.

InvariantContext

TypedDict — Data snapshot passed to the invariant checker.

Field	Type	Description
repo	str	GitHub owner/repo
issue_numbers	list[int]	All tracked issue numbers
pr_numbers_in_db	set[int]	PR numbers with DB rows
run_pr_numbers	dict[str, int | None]	Run ID → PR number mapping
link_issue_numbers_by_pr	dict[int, list[int]]	PR → linked issue numbers
workflow_states	dict[int, WorkflowSnapshot]	Issue → workflow state
pr_states	dict[int, str]	PR → state string
pr_bases	dict[int, str | None]	PR → target branch
closes_refs_by_pr	dict[int, list[int]]	PR → Closes #N references

WorkflowSnapshot

TypedDict — Minimal workflow state fields for invariant checking.

Field	Type
lane	str
pr_number	int | None
pr_state	str | None
agent_status	str | None
issue_state	str

---

Intelligence Types

Dependency DAG

Path: agentception/intelligence/dag.py

IssueNode

BaseModel — A single issue node in the dependency DAG.

Field	Type	Description
number	int	GitHub issue number
title	str	Issue title
state	str	"open" or "closed"
labels	list[str]	Label strings
has_wip	bool	Whether agent/wip label is set
deps	list[int]	Issue numbers this one depends on

DependencyDAG

BaseModel — Directed acyclic graph of open issue dependencies.

Field	Type	Description
nodes	list[IssueNode]	All open issues
edges	list[tuple[int, int]]	(from, to) — from depends on to

Issue Analyzer

Path: agentception/intelligence/analyzer.py

IssueAnalysis

BaseModel — Structured analysis of a GitHub issue body.

Field	Type	Description
number	int	GitHub issue number
dependencies	list[int]	Issue numbers declared in Depends on #N
parallelism	Literal["safe", "risky", "serial"]	Concurrent-execution safety
conflict_risk	Literal["none", "low", "high"]	Estimated merge-conflict risk
modifies_files	list[str]	Paths from ### Files to Create / Modify
recommended_role	Literal["python-developer", "database-architect"]	Role that should handle this issue
recommended_merge_after	int | None	Largest dependency number

Pipeline Guards

Path: agentception/intelligence/guards.py

PRViolation

BaseModel — A PR whose linked issue belongs to a pipeline phase that is no longer active.

Field	Type	Description
pr_number	int	PR number
pr_title	str	PR title
expected_label	str	Currently active phase label
actual_label	str	Label carried by the linked issue
linked_issue	int | None	Issue number parsed from Closes #N

Scaling

Path: agentception/intelligence/scaling.py

ScalingRecommendation

BaseModel — A single scaling recommendation produced by compute_recommendation().

Field	Type	Description
action	Literal["increase_coordinator_limit", "increase_pool", "no_change"]	Machine-readable action verb
target_role	str | None	Coordinator role slug (for increase_coordinator_limit)
reason	str	Human-readable explanation
current_value	int	Current config value
recommended_value	int	Suggested new value
confidence	Literal["high", "medium", "low"]	Based on completed wave history

A/B Results

Path: agentception/intelligence/ab_results.py

ABVariantResult

BaseModel — Outcome metrics for one A/B role variant across all applicable batches.

Field	Type	Description
variant	Literal["A", "B"]	Even-second = A, odd-second = B
role_sha	str	Git SHA of the role file version
batch_ids	list[str]	Batch IDs in this variant
prs_opened	int	Total PRs opened
prs_merged	int	Total PRs merged
avg_grade	str | None	Mean letter grade (None when no graded PRs)
merge_rate	float	prs_merged / prs_opened

---

Telemetry Types

Path: agentception/telemetry.py

WaveSummary

BaseModel — Aggregated telemetry for one VP/Engineering batch wave.

Field	Type	Description
batch_id	str	Batch identifier
started_at	float	UNIX timestamp (from worktree mtime)
ended_at	float | None	UNIX timestamp; None when still active
issues_worked	list[int]	Issue numbers processed
prs_opened	int	PRs opened in this wave
prs_merged	int	PRs merged in this wave
estimated_tokens	int	Estimated total tokens consumed
estimated_cost_usd	float	Estimated cost in USD

---

Org Preset Types

Path: agentception/data/org_presets.py

PresetGroup

Literal type alias — "engineering" | "data" | "executive" | "product" | "marketing" | "security" | "operations".

PresetNodeTemplate

BaseModel — One node in an org tree template (recursive).

Field	Type	Default	Description
role	str	required	Role slug
figure	str	""	Cognitive figure slug
children	list[PresetNodeTemplate]	[]	Child nodes (recursive)

OrgPresetSummary

BaseModel — Lightweight preset descriptor for list endpoint.

Field	Type	Description
id	str	Preset identifier
name	str	Display name
description	str	Short description
icon	str	Emoji icon
accent	str	CSS colour accent
node_count	int	Total nodes in template
group	PresetGroup	Category group

OrgPresetDetail

OrgPresetSummary (extends) — Full preset including the recursive tree template.

Field	Type	Description
inherits all from OrgPresetSummary
template	PresetNodeTemplate	Root template node

---

Entity Hierarchy

AgentCeption
│
├── Shared Type Aliases (agentception/types.py)
│   ├── JsonValue                  — TypeAlias: recursive JSON union (invariant list/dict)
│   └── JsonSchemaObj              — TypeAlias: dict[str, JsonValue]
│
├── Domain Models (agentception/models/__init__.py)
│   │
│   ├── Agent Lifecycle
│   │   ├── AgentStatus              — str Enum: 8 lifecycle values (mirror)
│   │   ├── AgentNode                — BaseModel: one agent in pipeline tree (recursive children)
│   │   └── StaleClaim               — BaseModel: issue with dangling agent/wip label
│   │
│   ├── Pipeline State
│   │   ├── BoardIssue               — BaseModel: lightweight issue card for sidebar
│   │   ├── PlanDraftEvent           — BaseModel: plan-draft SSE event
│   │   ├── StalledAgentEvent        — BaseModel: stalled agent record for SSE
│   │   └── PipelineState            — BaseModel: full pipeline snapshot (SSE broadcast)
│   │
│   ├── Agent Task Spec
│   │   ├── IssueSub                 — BaseModel: issue queue entry in coordinator dispatch
│   │   ├── PRSub                    — BaseModel: PR review queue entry in coordinator dispatch
│   │   └── AgentTaskSpec            — BaseModel: full parsed DB task context
│   │
│   ├── Pipeline Configuration
│   │   ├── AbModeConfig             — BaseModel: A/B role experimentation
│   │   ├── ProjectConfig            — BaseModel: one project in pipeline-config.json
│   │   ├── PipelineConfig           — BaseModel: full pipeline-config.json shape
│   │   └── SwitchProjectRequest     — BaseModel: project switch request
│   │
│   ├── Spawn API
│   │   ├── SpawnRequest / SpawnResult
│   │   ├── SpawnConductorRequest / SpawnConductorResult
│   │   └── SpawnCoordinatorRequest / SpawnCoordinatorResult
│   │
│   ├── Role Studio API
│   │   ├── RoleMeta, RoleContent
│   │   ├── RoleUpdateRequest, RoleUpdateResponse
│   │   ├── RoleDiffRequest, RoleDiffResponse
│   │   ├── RoleCommitRequest, RoleCommitResponse
│   │   ├── RoleVersionEntry, RoleVersionInfo, RoleVersionsResponse
│   │   └── RoleHistoryEntry
│   │
│   ├── Cognitive Architecture API
│   │   ├── TaxonomyRole, TaxonomyLevel, TaxonomyResponse
│   │   ├── PersonaEntry, PersonasResponse
│   │   └── AtomValue, AtomDimension, AtomsResponse
│   │
│   ├── Template API
│   │   ├── TemplateExportRequest, TemplateManifest
│   │   └── TemplateConflict, TemplateImportResult, TemplateListEntry
│   │
│   ├── Org Tree
│   │   ├── OrgTreeRole
│   │   └── OrgTreeNode              — recursive children
│   │
│   ├── PlanSpec Contract
│   │   ├── PlanIssue                — one GitHub issue to create
│   │   ├── PlanPhase                — ordered phase group
│   │   └── PlanSpec                 — root YAML contract (to_yaml / from_yaml)
│   │
│   ├── EnrichedManifest Contract
│   │   ├── EnrichedIssue            — fully-specified issue with acceptance criteria
│   │   ├── EnrichedPhase            — phase with parallel groups
│   │   └── EnrichedManifest         — root coordinator input contract
│   │
│   └── Execution Plan
│       ├── PlanOperation            — single atomic file operation
│       ├── ExecutionPlan            — immutable ordered operation list
│       └── FileEditEvent            — file-edit diff event (frozen)
│
├── Health Model (agentception/models/health.py)
│   └── HealthSnapshot               — BaseModel: system metrics for /api/health/detailed
│
├── Config (agentception/config.py)
│   ├── TaskRunnerChoice             — str Enum: anthropic (server-side agent loop)
│   ├── LLMProviderChoice            — str Enum: anthropic | local
│   └── AgentCeptionSettings         — BaseSettings: env-var config
│
├── ORM Layer (agentception/db/models.py)
│   ├── ACWave                       — one batch spawn
│   ├── ACAgentRun                   — one agent lifecycle (FK to ACWave)
│   ├── ACIssue                      — GitHub issue mirror (hash-diff sync)
│   ├── ACPullRequest                — GitHub PR mirror (hash-diff sync)
│   ├── ACAgentMessage               — one transcript message (FK to ACAgentRun)
│   ├── ACAgentEvent                 — structured MCP callback event
│   ├── ACInitiativePhase            — phase DAG per initiative+batch
│   ├── ACPipelineSnapshot           — tick-level time series
│   ├── ACPRIssueLink                — PR↔Issue link with provenance
│   ├── ACIssueWorkflowState         — canonical swim-lane state (computed)
│   ├── ACPlanIssue                  — issues belonging to a plan batch
│   ├── ACPlanBranch                 — integration branch per plan
│   └── ACExecutionPlan              — planner/executor immutable plan
│
├── Query TypedDicts (agentception/db/queries/types.py)
│   ├── Issue/PR: LabelEntry, BoardIssueRow, AllIssueRow, IssueDetailRow, PRDetailRow, …
│   ├── Runs: AgentRunRow, AgentRunDetail, AgentMessageRow, RunForIssueRow, RunTreeNodeRow, …
│   ├── Waves: WaveAgentRow, WaveRow, ConductorHistoryRow
│   ├── Phases: PhasedIssueRow, PhaseGroupRow, InitiativePhaseMeta, InitiativeSummary, …
│   ├── Workflow: WorkflowStateRow, PendingLaunchRow, AgentEventRow
│   ├── MCP: RunSummaryRow, RunContextRow, StatusCountRow, TerminalRunRow
│   └── Metrics: DailyMetrics
│
├── LLM Service (agentception/services/llm.py)
│   ├── LLMChunk                     — streaming event {type, text}
│   ├── ToolFunction, ToolDefinition — OpenAI tool schema shapes
│   ├── ToolCallFunction, ToolCall   — tool call response shapes
│   └── ToolResponse                 — completion_with_tools() return (incl. token counts)
│
├── Code Indexer (agentception/services/code_indexer.py)
│   ├── IndexStats                   — index_codebase() result
│   └── SearchMatch                  — search_codebase() result item
│
├── Working Memory (agentception/services/working_memory.py)
│   ├── FileEditEventJSON            — JSON-safe file edit event
│   └── WorkingMemoryJSON            — JSON-safe working memory snapshot
│
├── Task Runner (agentception/services/task_runner.py)
│   └── TaskRunner                   — Protocol: agent execution engine
│
├── MCP Protocol (agentception/mcp/types.py)
│   ├── Tools: ACToolDef, ACToolContent, ACToolResult
│   ├── Resources: ACResourceDef, ACResourceTemplate, ACResourceContent, ACResourceResult
│   ├── Prompts: ACPromptArgument, ACPromptDef, ACPromptContent, ACPromptMessage, ACPromptResult
│   ├── Method Results: McpServerInfo, McpCapabilities, InitializeResult,
│   │   ToolListResult, PromptListResult, ResourceListResult, ResourceTemplateListResult
│   ├── McpResultPayload           — TypeAlias: union of all result TypedDicts
│   └── JSON-RPC: JsonRpcError, JsonRpcSuccessResponse, JsonRpcErrorResponse
│
├── MCP Query Results (agentception/mcp/query_tools.py)
│   ├── PendingRunsResult, QueryRunFoundResult, QueryRunNotFoundResult
│   ├── QueryContextFoundResult, QueryChildrenResult, QueryEventsResult
│   ├── QueryActiveRunsResult, QueryRunTreeResult, QueryDispatcherResult
│   └── QueryRunStatusFoundResult, QueryHealthResult
│
├── MCP Plan Tool Results (agentception/mcp/plan_tools.py)
│   ├── CognitiveFigureEntry, CognitiveFiguresResult
│   ├── ValidateSpecSuccessResult, ValidationErrorResult
│   ├── RepoLabelEntry, LabelsResult
│   └── ValidateManifestSuccessResult
│
├── Workflow Layer (agentception/workflow/)
│   ├── Status: AgentStatus (canonical, 10 values), ACTIVE_STATUSES, TERMINAL_STATUSES, …
│   ├── State Machine: IssueInput, RunInput, WorkflowState
│   ├── Linking: CandidateLink, PRRow, RunRow, BestPR, PRInfo
│   └── Invariants: InvariantContext, WorkflowSnapshot
│
├── Intelligence Layer (agentception/intelligence/)
│   ├── IssueNode, DependencyDAG     — dag.py
│   ├── IssueAnalysis                — analyzer.py
│   ├── PRViolation                  — guards.py
│   ├── ScalingRecommendation        — scaling.py
│   └── ABVariantResult              — ab_results.py
│
├── Telemetry (agentception/telemetry.py)
│   └── WaveSummary                  — batch wave telemetry
│
└── Org Presets (agentception/data/org_presets.py)
    ├── PresetNodeTemplate            — recursive org template node
    ├── OrgPresetSummary              — lightweight preset descriptor
    └── OrgPresetDetail               — full preset with template tree

---

Entity Graphs (Mermaid)

Arrow conventions and stereotype key follow the same pattern as the reference document. Stereotypes: <<TypedDict>>, <<BaseModel>>, <<ORM>>, <<Enum>>, <<Protocol>>.

---

Diagram 1 — PlanSpec YAML Contract

The typed YAML contract between the LLM planner (Phase 1A) and the human review step (Phase 1B). PlanSpec is the root; it decomposes into phases and issues. ExecutionPlan is produced from the resolved plan.

classDiagram
    class PlanSpec {
        <<BaseModel>>
        +initiative : str
        +phases : list~PlanPhase~
        +coordinator_arch : dict~str, str~
        +to_yaml() str
        +from_yaml(text) PlanSpec
    }
    class PlanPhase {
        <<BaseModel>>
        +label : str
        +description : str
        +depends_on : list~str~
        +issues : list~PlanIssue~
    }
    class PlanIssue {
        <<BaseModel>>
        +id : str
        +title : str
        +body : str
        +depends_on : list~str~
        +skills : list~str~
        +cognitive_arch : str
    }
    class EnrichedManifest {
        <<BaseModel>>
        +initiative : str | None
        +phases : list~EnrichedPhase~
        +total_issues : int
        +estimated_waves : int
    }
    class EnrichedPhase {
        <<BaseModel>>
        +label : str
        +description : str
        +issues : list~EnrichedIssue~
        +parallel_groups : list~list~str~~
    }
    class EnrichedIssue {
        <<BaseModel>>
        +title : str
        +body : str
        +labels : list~str~
        +phase : str
        +depends_on : list~str~
        +acceptance_criteria : list~str~
        +tests_required : list~str~
    }
    class PlanOperation {
        <<BaseModel>>
        +tool : Literal
        +file : str
        +old_string : str | None
        +new_string : str | None
        +content : str | None
    }
    class ExecutionPlan {
        <<BaseModel>>
        +run_id : str
        +issue_number : int
        +operations : list~PlanOperation~
        +created_at : datetime
    }

    PlanSpec *-- PlanPhase : phases
    PlanPhase *-- PlanIssue : issues
    EnrichedManifest *-- EnrichedPhase : phases
    EnrichedPhase *-- EnrichedIssue : issues
    PlanSpec ..> EnrichedManifest : coordinator enriches
    ExecutionPlan *-- PlanOperation : operations
    PlanIssue ..> ExecutionPlan : planner produces

Loading

---

Diagram 2 — Agent Lifecycle and Pipeline State

The domain model for the Build dashboard SSE feed. PipelineState is the root broadcast; it composes AgentNode trees with StaleClaim, BoardIssue, and StalledAgentEvent lists.

classDiagram
    class AgentStatus {
        <<Enum>>
        PENDING_LAUNCH
        IMPLEMENTING
        BLOCKED
        REVIEWING
        COMPLETED
        CANCELLED
        STOPPED
        FAILED
    }
    class AgentNode {
        <<BaseModel>>
        +id : str
        +role : str
        +status : AgentStatus
        +issue_number : int | None
        +pr_number : int | None
        +tier : str | None
        +org_domain : str | None
        +parent_run_id : str | None
        +children : list~AgentNode~
        +cognitive_arch : str | None
    }
    class StaleClaim {
        <<BaseModel>>
        +issue_number : int
        +issue_title : str
        +worktree_path : str
    }
    class BoardIssue {
        <<BaseModel>>
        +number : int
        +title : str
        +state : str
        +labels : list~str~
        +claimed : bool
    }
    class PlanDraftEvent {
        <<BaseModel>>
        +event : str
        +draft_id : str
        +yaml_text : str
        +output_path : str
    }
    class StalledAgentEvent {
        <<BaseModel>>
        +run_id : str
        +issue_number : int
        +worktree_path : str
        +last_activity_at : str
        +stalled_for_minutes : int
    }
    class PipelineState {
        <<BaseModel>>
        +active_label : str | None
        +issues_open : int
        +prs_open : int
        +polled_at : float
        +agents : list~AgentNode~
        +stale_claims : list~StaleClaim~
        +board_issues : list~BoardIssue~
        +plan_draft_events : list~PlanDraftEvent~
        +loop_guard_triggered : list~str~
        +stalled_agents : list~StalledAgentEvent~
    }

    PipelineState --> AgentNode : agents (tree)
    PipelineState --> StaleClaim : stale_claims
    PipelineState --> BoardIssue : board_issues
    PipelineState --> PlanDraftEvent : plan_draft_events
    PipelineState --> StalledAgentEvent : stalled_agents
    AgentNode --> AgentStatus : status
    AgentNode --> AgentNode : children (recursive)

Loading

---

Diagram 3 — ORM Entity Relationships

The full database schema. All ORM models inherit from Base. ACAgentRun has FK relationships to ACWave and ACAgentMessage. Plan-scoped tables (ACPlanIssue, ACPlanBranch, ACExecutionPlan) link to ACAgentRun by convention (not hard FK).

classDiagram
    class ACWave {
        <<ORM>>
        +id : str PK
        +phase_label : str
        +role : str
        +started_at : datetime
        +spawn_count : int
        +skip_count : int
    }
    class ACAgentRun {
        <<ORM>>
        +id : str PK
        +wave_id : str FK~ACWave~
        +status : str
        +tier : str | None
        +org_domain : str | None
        +parent_run_id : str | None
        +cognitive_arch : str | None
        +task_description : str | None
        +gh_repo : str | None
        +plan_id : str | None
        +plan_branch : str | None
        +is_resumed : bool
        +coord_fingerprint : str | None
        +total_input_tokens : int
        +total_output_tokens : int
        +prompt_variant : str | None
        +issue_number : int | None
        +pr_number : int | None
    }
    class ACAgentMessage {
        <<ORM>>
        +id : int PK
        +agent_run_id : str FK~ACAgentRun~
        +role : str
        +content : str | None
        +sequence_index : int
    }
    class ACAgentEvent {
        <<ORM>>
        +id : int PK
        +agent_run_id : str | None FK
        +event_type : str
        +payload : str
    }
    class ACIssue {
        <<ORM>>
        +github_number : int PK
        +repo : str PK
        +title : str
        +state : str
        +content_hash : str
    }
    class ACPullRequest {
        <<ORM>>
        +github_number : int PK
        +repo : str PK
        +state : str
        +is_draft : bool
        +body_hash : str | None
    }
    class ACPRIssueLink {
        <<ORM>>
        +id : int PK
        +repo : str
        +pr_number : int
        +issue_number : int
        +link_method : str
        +confidence : int 0-100
    }
    class ACIssueWorkflowState {
        <<ORM>>
        +repo : str PK
        +issue_number : int PK
        +lane : str
        +pr_link_method : str | None
        +pr_link_confidence : int | None
    }
    class ACInitiativePhase {
        <<ORM>>
        +repo : str PK
        +initiative : str PK
        +batch_id : str PK
        +phase_label : str PK
        +phase_order : int
    }
    class ACPipelineSnapshot {
        <<ORM>>
        +id : int PK
        +polled_at : datetime
        +issues_open : int
        +prs_open : int
        +agents_active : int
    }
    class ACPlanIssue {
        <<ORM>>
        +plan_id : str PK
        +repo : str PK
        +issue_number : int PK
    }
    class ACPlanBranch {
        <<ORM>>
        +plan_id : str PK
        +repo : str PK
        +branch_name : str
    }
    class ACExecutionPlan {
        <<ORM>>
        +run_id : str PK
        +issue_number : int
        +plan_json : str
        +created_at : datetime
    }

    ACWave *-- ACAgentRun : agent_runs
    ACAgentRun *-- ACAgentMessage : messages
    ACAgentRun --> ACAgentEvent : events
    ACAgentRun ..> ACExecutionPlan : run_id
    ACPRIssueLink --> ACIssue : issue_number
    ACPRIssueLink --> ACPullRequest : pr_number
    ACIssueWorkflowState --> ACIssue : (repo, issue_number)
    ACIssueWorkflowState --> ACPRIssueLink : best link
    ACPlanIssue ..> ACIssue : issue_number

Loading

---

Diagram 4 — LLM Wire Types (Tool Use)

The simplified OpenAI-compatible type surface for completion_with_tools(). Token counting fields on ToolResponse enable cost tracking and cache-hit verification.

classDiagram
    class LLMChunk {
        <<TypedDict>>
        +type : Literal~thinking, content~
        +text : str
    }
    class ToolFunction {
        <<TypedDict>>
        +name : str
        +description : str
        +parameters : JsonSchemaObj
    }
    class ToolDefinition {
        <<TypedDict>>
        +type : Literal~function~
        +function : ToolFunction
    }
    class ToolCallFunction {
        <<TypedDict>>
        +name : str
        +arguments : str
    }
    class ToolCall {
        <<TypedDict>>
        +id : str
        +type : Literal~function~
        +function : ToolCallFunction
    }
    class ToolResponse {
        <<TypedDict>>
        +stop_reason : str
        +content : str
        +tool_calls : list~ToolCall~
        +input_tokens : int (NotRequired)
        +output_tokens : int (NotRequired)
        +cache_creation_input_tokens : int (NotRequired)
        +cache_read_input_tokens : int (NotRequired)
    }

    ToolDefinition --> ToolFunction : function
    ToolCall --> ToolCallFunction : function
    ToolResponse --> ToolCall : tool_calls

Loading

---

Diagram 5 — Code Indexer and Semantic Search

The Qdrant-backed semantic search pipeline for self-hosted codebase search. IndexStats is the public result of indexing; SearchMatch is the public result of searching.

classDiagram
    class IndexStats {
        <<TypedDict>>
        +ok : bool
        +files_indexed : int
        +chunks_indexed : int
        +files_skipped : int
        +error : str | None
    }
    class SearchMatch {
        <<TypedDict>>
        +file : str
        +chunk : str
        +score : float
        +start_line : int
        +end_line : int
    }
    class _ChunkSpec {
        <<TypedDict internal>>
        +chunk_id : int
        +file : str
        +text : str
        +start_line : int
        +end_line : int
        +symbol : str
        +file_hash : str
    }
    class AsyncQdrantClient {
        <<external>>
        +get_collections()
        +create_collection()
        +upsert()
        +query_points()
    }
    class TextEmbedding {
        <<external ONNX>>
        BAAI/bge-small-en-v1.5
        384-dim vectors
        CPU-only, no API key
    }

    _ChunkSpec ..> TextEmbedding : embed text
    TextEmbedding ..> AsyncQdrantClient : upsert vectors
    AsyncQdrantClient ..> SearchMatch : query_points → results
    IndexStats ..> _ChunkSpec : counts chunks

Loading

---

Diagram 6 — MCP Protocol Types

The full MCP JSON-RPC 2.0 wire protocol. JsonRpcSuccessResponse and JsonRpcErrorResponse are the two response envelopes. McpResultPayload is a union of all named result TypedDicts — no object or Any. Each MCP method returns a specific result shape.

classDiagram
    class JsonRpcSuccessResponse {
        <<TypedDict>>
        +jsonrpc : str
        +id : int | str | None
        +result : McpResultPayload
    }
    class JsonRpcErrorResponse {
        <<TypedDict>>
        +jsonrpc : str
        +id : int | str | None
        +error : JsonRpcError
    }
    class JsonRpcError {
        <<TypedDict>>
        +code : int
        +message : str
        +data : JsonValue
    }
    class McpResultPayload {
        <<TypeAlias>>
        ACToolResult
        ACPromptResult
        ACResourceResult
        InitializeResult
        ToolListResult
        PromptListResult
        ResourceListResult
        ResourceTemplateListResult
    }
    class InitializeResult {
        <<TypedDict>>
        +protocolVersion : str
        +capabilities : McpCapabilities
        +serverInfo : McpServerInfo
    }
    class McpCapabilities {
        <<TypedDict>>
        +tools : dict~str, str~
        +resources : dict~str, str~
        +prompts : dict~str, str~
    }
    class McpServerInfo {
        <<TypedDict>>
        +name : str
        +version : str
    }
    class ToolListResult {
        <<TypedDict>>
        +tools : list~ACToolDef~
    }
    class PromptListResult {
        <<TypedDict>>
        +prompts : list~ACPromptDef~
    }
    class ResourceListResult {
        <<TypedDict>>
        +resources : list~ACResourceDef~
    }
    class ResourceTemplateListResult {
        <<TypedDict>>
        +resourceTemplates : list~ACResourceTemplate~
    }
    class ACToolDef {
        <<TypedDict>>
        +name : str
        +description : str
        +inputSchema : JsonSchemaObj
    }
    class ACToolResult {
        <<TypedDict>>
        +content : list~ACToolContent~
        +isError : bool
    }
    class ACResourceResult {
        <<TypedDict>>
        +contents : list~ACResourceContent~
    }
    class ACPromptResult {
        <<TypedDict>>
        +description : str
        +messages : list~ACPromptMessage~
    }

    JsonRpcSuccessResponse --> McpResultPayload : result
    JsonRpcErrorResponse --> JsonRpcError : error
    McpResultPayload ..> ACToolResult
    McpResultPayload ..> ACPromptResult
    McpResultPayload ..> ACResourceResult
    McpResultPayload ..> InitializeResult
    McpResultPayload ..> ToolListResult
    McpResultPayload ..> PromptListResult
    McpResultPayload ..> ResourceListResult
    McpResultPayload ..> ResourceTemplateListResult
    InitializeResult --> McpCapabilities : capabilities
    InitializeResult --> McpServerInfo : serverInfo
    ToolListResult --> ACToolDef : tools
    PromptListResult ..> ACPromptDef : prompts
    ResourceListResult ..> ACResourceDef : resources
    ResourceTemplateListResult ..> ACResourceTemplate : resourceTemplates

Loading

---

Diagram 7 — Workflow State Machine

The deterministic swim-lane computation. IssueInput + RunInput + BestPR → WorkflowState. The CandidateLink → BestPR selection runs first and is fed into the state machine. InvariantContext drives tick-level consistency checks.

classDiagram
    class IssueInput {
        <<TypedDict>>
        +number : int
        +state : str
        +labels : list~str~
        +phase_key : str | None
        +initiative : str | None
    }
    class RunInput {
        <<TypedDict>>
        +id : str
        +status : str
        +agent_status : str
        +pr_number : int | None
    }
    class WorkflowState {
        <<TypedDict>>
        +lane : str
        +issue_state : str
        +run_id : str | None
        +agent_status : str | None
        +pr_number : int | None
        +pr_state : str | None
        +pr_link_method : str | None
        +pr_link_confidence : int | None
        +warnings : list~str~
        +content_hash : str
    }
    class CandidateLink {
        <<TypedDict>>
        +repo : str
        +pr_number : int
        +issue_number : int
        +link_method : str
        +confidence : int
        +evidence_json : str
    }
    class BestPR {
        <<TypedDict>>
        +pr_number : int
        +pr_state : str
        +pr_base : str | None
        +pr_head_ref : str | None
        +link_method : str
        +confidence : int
    }
    class ACIssueWorkflowState {
        <<ORM persisted>>
        +lane : str
        +content_hash : str
    }
    class InvariantContext {
        <<TypedDict>>
        +repo : str
        +issue_numbers : list~int~
        +workflow_states : dict
        +pr_states : dict
    }
    class WorkflowSnapshot {
        <<TypedDict>>
        +lane : str
        +pr_number : int | None
        +agent_status : str | None
        +issue_state : str
    }

    IssueInput ..> WorkflowState : state machine input
    RunInput ..> WorkflowState : state machine input
    BestPR ..> WorkflowState : pr fields
    CandidateLink ..> BestPR : best_pr_for_issue()
    WorkflowState ..> ACIssueWorkflowState : persisted on change
    InvariantContext --> WorkflowSnapshot : checks against

Loading

---

Diagram 8 — Intelligence Layer

The dependency DAG, issue analysis, pipeline guards, scaling recommendations, and A/B results.

classDiagram
    class IssueNode {
        <<BaseModel>>
        +number : int
        +title : str
        +state : str
        +labels : list~str~
        +has_wip : bool
        +deps : list~int~
    }
    class DependencyDAG {
        <<BaseModel>>
        +nodes : list~IssueNode~
        +edges : list~tuple~int,int~~
    }
    class IssueAnalysis {
        <<BaseModel>>
        +number : int
        +dependencies : list~int~
        +parallelism : Literal~safe,risky,serial~
        +conflict_risk : Literal~none,low,high~
        +modifies_files : list~str~
        +recommended_role : str
        +recommended_merge_after : int | None
    }
    class PRViolation {
        <<BaseModel>>
        +pr_number : int
        +pr_title : str
        +expected_label : str
        +actual_label : str
        +linked_issue : int | None
    }
    class ScalingRecommendation {
        <<BaseModel>>
        +action : Literal
        +target_role : str | None
        +reason : str
        +current_value : int
        +recommended_value : int
        +confidence : Literal~high,medium,low~
    }
    class ABVariantResult {
        <<BaseModel>>
        +variant : Literal~A,B~
        +role_sha : str
        +batch_ids : list~str~
        +prs_opened : int
        +prs_merged : int
        +avg_grade : str | None
        +merge_rate : float
    }

    DependencyDAG *-- IssueNode : nodes
    IssueNode ..> IssueAnalysis : analyzed to produce

Loading

---

Diagram 9 — Query Row Hierarchy

The full TypedDict surface of db/queries/types.py. Rows are grouped by usage context. All datetime fields are ISO-8601 strings; no datetime objects cross this boundary.

classDiagram
    class BoardIssueRow {
        <<TypedDict>>
        +number : int
        +title : str
        +state : str
        +labels : list~LabelEntry~
        +claimed : bool
        +phase_label : str | None
    }
    class AgentRunDetail {
        <<TypedDict>>
        +id : str
        +role : str
        +status : str
        +tier : str | None
        +org_domain : str | None
        +parent_run_id : str | None
        +cognitive_arch : str | None
        +messages : list~AgentMessageRow~
    }
    class AgentMessageRow {
        <<TypedDict>>
        +role : str
        +content : str | None
        +tool_name : str | None
        +sequence_index : int
    }
    class RunForIssueRow {
        <<TypedDict>>
        +id : str
        +role : str
        +agent_status : str
        +current_step : str | None
        +steps_completed : int
        +tier : str | None
        +org_domain : str | None
    }
    class RunTreeNodeRow {
        <<TypedDict>>
        +id : str
        +role : str
        +tier : str | None
        +parent_run_id : str | None
        +agent_status : str
    }
    class WaveRow {
        <<TypedDict>>
        +batch_id : str
        +agents : list~WaveAgentRow~
        +estimated_cost_usd : float
    }
    class WaveAgentRow {
        <<TypedDict>>
        +id : str
        +role : str
        +status : str
        +cognitive_arch : str | None
    }
    class RunSummaryRow {
        <<TypedDict>>
        +run_id : str
        +status : str
        +role : str
        +tier : str | None
        +org_domain : str | None
        +parent_run_id : str | None
    }
    class RunContextRow {
        <<TypedDict>>
        +run_id : str
        +status : str
        +role : str
        +cognitive_arch : str | None
        +task_description : str | None
        +pr_base_branch : str | None
    }
    class InitiativeSummary {
        <<TypedDict>>
        +repo : str
        +initiative : str
        +phases : list~InitiativePhaseRow~
        +phase_count : int
        +issue_count : int
    }
    class InitiativePhaseRow {
        <<TypedDict>>
        +label : str
        +is_active : bool
        +is_complete : bool
        +issues : list~InitiativeIssueRow~
    }
    class DailyMetrics {
        <<TypedDict>>
        +date : str
        +issues_closed : int
        +prs_merged : int
        +cost_usd : float
        +first_pass_rate : float
        +auto_merge_rate : float
    }

    AgentRunDetail --> AgentMessageRow : messages
    WaveRow --> WaveAgentRow : agents
    InitiativeSummary --> InitiativePhaseRow : phases
    RunTreeNodeRow --> RunTreeNodeRow : parent_run_id (tree)

Loading

---

Diagram 10 — MCP Query and Plan Tool Result Types

Named TypedDicts for every MCP query and plan tool return shape. Functions with found/not-found outcomes return explicit unions. Leaf nodes reference db/queries/types.py rows.

classDiagram
    class PendingRunsResult {
        <<TypedDict>>
        +pending : list~PendingLaunchRow~
        +count : int
    }
    class QueryRunFoundResult {
        <<TypedDict>>
        +ok : bool
        +run : RunSummaryRow
    }
    class QueryRunNotFoundResult {
        <<TypedDict>>
        +ok : bool
        +error : str
    }
    class QueryContextFoundResult {
        <<TypedDict>>
        +ok : bool
        +context : RunContextRow
    }
    class QueryChildrenResult {
        <<TypedDict>>
        +ok : bool
        +children : list~RunSummaryRow~
        +count : int
    }
    class QueryEventsResult {
        <<TypedDict>>
        +ok : bool
        +events : list~AgentEventRow~
        +count : int
    }
    class QueryActiveRunsResult {
        <<TypedDict>>
        +ok : bool
        +runs : list~RunSummaryRow~
        +count : int
    }
    class QueryRunTreeResult {
        <<TypedDict>>
        +ok : bool
        +nodes : list~RunTreeNodeRow~
        +count : int
    }
    class QueryDispatcherResult {
        <<TypedDict>>
        +ok : bool
        +status_counts : list~StatusCountRow~
        +active_count : int
        +latest_batch_id : str | None
    }
    class QueryHealthResult {
        <<TypedDict>>
        +ok : bool
        +db_ok : bool
        +status_counts : list~StatusCountRow~
        +total_runs : int
    }
    class CognitiveFiguresResult {
        <<TypedDict>>
        +role : str
        +figures : list~CognitiveFigureEntry~
        +error : NotRequired~str~
    }
    class CognitiveFigureEntry {
        <<TypedDict>>
        +id : str
        +display_name : str
        +description : str
    }
    class ValidateSpecSuccessResult {
        <<TypedDict>>
        +valid : bool
        +spec : dict~str, JsonValue~
    }
    class ValidationErrorResult {
        <<TypedDict>>
        +valid : bool
        +errors : list~str~
    }
    class LabelsResult {
        <<TypedDict>>
        +labels : list~RepoLabelEntry~
    }
    class RepoLabelEntry {
        <<TypedDict>>
        +name : str
        +description : str
    }
    class ValidateManifestSuccessResult {
        <<TypedDict>>
        +valid : bool
        +manifest : dict~str, JsonValue~
        +total_issues : int
        +estimated_waves : int
    }

    PendingRunsResult --> PendingLaunchRow : pending
    QueryRunFoundResult --> RunSummaryRow : run
    QueryContextFoundResult --> RunContextRow : context
    QueryChildrenResult --> RunSummaryRow : children
    QueryEventsResult --> AgentEventRow : events
    QueryActiveRunsResult --> RunSummaryRow : runs
    QueryRunTreeResult --> RunTreeNodeRow : nodes
    QueryDispatcherResult --> StatusCountRow : status_counts
    QueryHealthResult --> StatusCountRow : status_counts
    CognitiveFiguresResult --> CognitiveFigureEntry : figures
    LabelsResult --> RepoLabelEntry : labels

Loading