oc_orchestrator.plans Namespace Reference

Functions
tuple[str, str]|None	parse_plan_filename (str name)
Path|None	_find_plan_file (Path plans_dir, str plan_id)
None	_rename_to_state (Path plans_dir, str plan_id, str new_status)
tuple[PlanInventory, Path]	_resolve_inventory (PlanInventory|None inventory, Path plans_dir)
tuple[str, Path]	create_plan (str description, str|None session_name=None, *, PlanInventory|None inventory=None, Path|None plans_dir=None)
PlanRecord	_transition (str plan_id, str new_status, PlanInventory|None inventory, Path|None plans_dir)
PlanRecord	pause_plan (str plan_id, *, PlanInventory|None inventory=None, Path|None plans_dir=None)
PlanRecord	continue_plan (str plan_id, *, PlanInventory|None inventory=None, Path|None plans_dir=None)
PlanRecord	complete_plan (str plan_id, *, PlanInventory|None inventory=None, Path|None plans_dir=None)
PlanRecord	abort_plan (str plan_id, *, PlanInventory|None inventory=None, Path|None plans_dir=None)
list[PlanRecord]	list_plans (*, PlanInventory|None inventory=None)
PlanRecord|None	find_plan_by_id (str plan_id_or_prefix, *, PlanInventory|None inventory=None)
str|None	get_plan_status (str plan_id, *, PlanInventory|None inventory=None)

Detailed Description

High-level plan operations on top of the plan inventory.

Purpose
-------
Public functions that combine inventory writes with filename mirroring.
Every state-change operation follows the protocol:

    1. Inventory write FIRST (atomic).
    2. Filename rename SECOND.
    3. On filename failure, inventory still correct; next call's
       reconcile() heals the filename.

Responsibilities
----------------
- :func:`create_plan` — allocate next prefix, generate kebab-case stem,
  register inventory record, return ``(plan_id, path)``. Does NOT
  create the file on disk; the agent is expected to ``write_file`` it.
- :func:`pause_plan`, :func:`continue_plan`, :func:`complete_plan`,
  :func:`abort_plan` — lifecycle transitions.
- :func:`list_plans` — return all records (from inventory), grouped or
  not by status as the caller wishes.
- :func:`find_plan_by_id` — resolve a 3-digit prefix OR full stem to a
  ``PlanRecord``. Returns ``None`` for ambiguous prefix.
- :func:`get_plan_status` — convenience wrapper for ``inventory.get(id).status``.
- :func:`parse_plan_filename` — regex helper exposed for callers.

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — high-level operation lifecycle
    L3 — semantic details (plan_id, prefix, status transition)
    L4 — deep tracing (filesystem rename attempts, reconcile diffs)

Contracts
---------
- All public mutators raise :class:`KeyError` for unknown plan_ids.
- :func:`continue_plan` raises :class:`ValueError` if the plan is not
  currently paused. :func:`complete_plan` / :func:`abort_plan` raise on
  terminal-to-terminal transitions.
- :func:`create_plan` writes to inventory and chooses a filename, but
  does NOT create the file on disk.
- :func:`find_plan_by_id` returns the matching record or ``None``.
  Raises :class:`ValueError` only when the input is ambiguous
  (multiple matches by prefix).

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_orchestrator.plan_inventory (PlanInventory, get_inventory, reconcile)
- oc_orchestrator.wordgen (random_plan_filename)

Function Documentation

_find_plan_file()

Path | None oc_orchestrator.plans._find_plan_file ( Path plans_dir, str plan_id )

protected

Locate the on-disk file for ``plan_id`` (any suffix). Returns None.

Definition at line 100 of file plans.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_rename_to_state()

None oc_orchestrator.plans._rename_to_state ( Path plans_dir, str plan_id, str new_status )

protected

Rename the on-disk file to match the new inventory status.

No-op if the file is missing or already at the expected name.
Raises :class:`OSError` if the rename fails (caller may swallow and
rely on :func:`reconcile` to heal later).

Definition at line 109 of file plans.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_resolve_inventory()

tuple[PlanInventory, Path] oc_orchestrator.plans._resolve_inventory ( PlanInventory | None inventory, Path plans_dir )

protected

Internal: pick the active inventory and resolve plans_dir.

Definition at line 130 of file plans.py.

Here is the caller graph for this function:

_transition()

PlanRecord oc_orchestrator.plans._transition ( str plan_id, str new_status, PlanInventory | None inventory, Path | None plans_dir )

protected

Shared implementation: inventory update first, then rename.

Definition at line 181 of file plans.py.

Here is the call graph for this function:

Here is the caller graph for this function:

abort_plan()

PlanRecord oc_orchestrator.plans.abort_plan	(	str	plan_id,
		*	,
		PlanInventory | None	inventory = None,
		Path | None	plans_dir = None )

Mark a plan aborted. Terminal.

Definition at line 257 of file plans.py.

Here is the call graph for this function:

complete_plan()

PlanRecord oc_orchestrator.plans.complete_plan	(	str	plan_id,
		*	,
		PlanInventory | None	inventory = None,
		Path | None	plans_dir = None )

Mark a plan complete. Terminal.

Definition at line 239 of file plans.py.

Here is the call graph for this function:

continue_plan()

PlanRecord oc_orchestrator.plans.continue_plan	(	str	plan_id,
		*	,
		PlanInventory | None	inventory = None,
		Path | None	plans_dir = None )

Resume a paused plan. Refuses if not currently paused.

Definition at line 221 of file plans.py.

Here is the call graph for this function:

create_plan()

tuple[str, Path] oc_orchestrator.plans.create_plan	(	str	description,
		str | None	session_name = None,
		*	,
		PlanInventory | None	inventory = None,
		Path | None	plans_dir = None )

Allocate a new plan and register its inventory record.

Returns ``(plan_id, path)``. The on-disk file is **not** created;
the caller (typically the agent via ``write_file``) writes the
Markdown content to ``path``.

Refusal logic (e.g., "another plan is active") is the caller's
responsibility — this function does not consult any session state.

Definition at line 140 of file plans.py.

Here is the call graph for this function:

find_plan_by_id()

PlanRecord | None oc_orchestrator.plans.find_plan_by_id	(	str	plan_id_or_prefix,
		*	,
		PlanInventory | None	inventory = None )

Resolve a 3-digit prefix or full stem to a :class:`PlanRecord`.

- If the input matches a full plan_id exactly, return that record.
- If the input is a 3-digit prefix and exactly one record matches,
  return that record.
- Returns ``None`` for no match.
- Raises :class:`ValueError` for ambiguous prefix (multiple matches).

Definition at line 284 of file plans.py.

get_plan_status()

str | None oc_orchestrator.plans.get_plan_status	(	str	plan_id,
		*	,
		PlanInventory | None	inventory = None )

Return the status of ``plan_id`` from the inventory, or ``None``.

Definition at line 316 of file plans.py.

list_plans()

list[PlanRecord] oc_orchestrator.plans.list_plans	(	*	,
		PlanInventory | None	inventory = None )

Return all records, sorted by ``created_at`` descending.

Definition at line 275 of file plans.py.

parse_plan_filename()

tuple[str, str] | None oc_orchestrator.plans.parse_plan_filename

(

str

name

)

Parse a plan filename into ``(stem, state)``.

State is ``"active"`` when no suffix is present; otherwise one of
``"paused"``, ``"complete"``, ``"aborted"``. Returns ``None`` for
filenames that don't match the plan-file pattern.

Definition at line 86 of file plans.py.

Here is the caller graph for this function:

pause_plan()

PlanRecord oc_orchestrator.plans.pause_plan	(	str	plan_id,
		*	,
		PlanInventory | None	inventory = None,
		Path | None	plans_dir = None )

Pause an active plan. Idempotent on already-paused.

Definition at line 201 of file plans.py.

Here is the call graph for this function: