Skip to content

Orchestration

Planning, subagents, and code verification.

Plan

Plan dataclass

Plan execution - immutable state machine.

State machine: draft -> approved -> executing -> completed/cancelled. cancel() is available from any state.

approve 

approve(by: ApprovalSource) -> Plan

draft -> approved.

Raises: ValueError: if the plan is not in draft status.

start_execution 

start_execution() -> Plan

approved -> executing.

Raises: ValueError: if the plan is not in approved status.

mark_completed 

mark_completed() -> Plan

executing -> completed.

Raises: ValueError: if the plan is not in executing status.

cancel 

cancel() -> Plan

Any status -> cancelled.

update_step 

update_step(updated_step: PlanStep) -> Plan

Update a step by id and return a new plan.

Raises: ValueError: if the step id is not found.

PlanStep

PlanStep dataclass

Immutable plan step with state-transition helpers.

start 

start() -> PlanStep

pending -> in_progress.

complete 

complete(result: str) -> PlanStep
  • -> completed with result.

fail 

fail(reason: str) -> PlanStep

Transition to failed with the provided reason.

skip 

skip(reason: str) -> PlanStep

Transition to skipped with the provided reason.

PlanStore Protocol

PlanStore

Bases: Protocol

Store planoin - ISP: <=4 methods.

Multi-tenant: user_id + topic_id in each other.

save async 

save(plan: Plan) -> None

Save or update plan.

load async 

load(plan_id: str) -> Plan | None

Load.

list_plans async 

list_plans(user_id: str, topic_id: str) -> list[Plan]

List plans.

update_step async 

update_step(plan_id: str, step: PlanStep) -> None

Update step.

InMemoryPlanStore

InMemoryPlanStore

In-memory PlanStore with multi-tenant namespace isolation.

Namespace is set via set_namespace(user_id, topic_id). save() binds the plan to the current namespace. list_plans() filters by namespace.

set_namespace 

set_namespace(user_id: str, topic_id: str) -> None

Set the namespace for save/list operations.

save async 

save(plan: Plan) -> None

Save or update plan. Binds to current namespace.

load async 

load(plan_id: str) -> Plan | None

Load plan by ID.

list_plans async 

list_plans(user_id: str, topic_id: str) -> list[Plan]

List plans filtered by namespace.

update_step async 

update_step(plan_id: str, step: PlanStep) -> None

Atomically update a step within a plan.