Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

37.2 KB
Raw Blame
"""The generic engine that runs a user-created workflow definition.

``DynamicWorkflow`` wraps a stored :class:`DynamicWorkflowDef` and implements
the :class:`Workflow` ABC by *interpreting* the definition's steps — there is
no per-workflow code. It reuses the exact building blocks the hand-written
workflows use (``load_or_create_profile``, ``retrieve``,
``route_to_specialist``) so a dynamic workflow behaves like a built-in: same
SSE events, same artifact shape, same run persistence.

Step interpretation:
- ``specialist``  → consult the named specialist with the rendered goal
                    (and optional RAG), store the output.
- ``approval_gate`` → yield a ``WaitForHumanEvent`` carrying a
                    ``WorkflowResumeState``. The caller checkpoints and pauses;
                    once the human answers, ``resume()`` re-enters at the next
                    step (see "Pause and resume" below).
- ``synthesis``   → assemble prior outputs into the final Markdown artifact,
                    either by concatenation or via one synthesis consult.
- ``action``      → run the ``workflow_actor`` agent with ONLY the step's
                    approved tools (``workflows/action_step.py``); its report
                    of what it did becomes the step's output.

Pause and resume
----------------
``run()`` and ``resume()`` share one step loop, ``_run_steps``, which takes
the index to start at and the outputs accumulated so far. That is the whole
mechanism: nothing serialises a generator frame. At a gate the engine hands
the caller a ``WorkflowResumeState`` (workflow name, gate id and index, next
index, completed outputs); on resume the caller hands it back, the engine
re-validates it against the live definition, records the human's decision as
the gate step's own output, and runs the loop from the next index.

A second gate needs no special handling — it is simply another pause raised
from the same loop, with a fresh payload.
"""
from __future__ import annotations

import hashlib
import string
from collections.abc import AsyncIterator
from typing import TYPE_CHECKING, Any, TypeVar

from pydantic import BaseModel, Field, create_model

from openexecutive.knowledge.retriever import retrieve
from openexecutive.knowledge.store import ChromaDBStore
from openexecutive.memory.company_profile import CompanyProfile
from openexecutive.onboarding.profile_builder import load_or_create_profile
from openexecutive.orchestrator.router import SPECIALIST_REGISTRY, route_to_specialist
from openexecutive.workflows.base import (
    Workflow,
    WorkflowEvent,
    WorkflowMeta,
    WorkflowStepDef,
)
from openexecutive.workflows.dynamic_models import (
    ActionStepSpec,
    ApprovalGateStepSpec,
    DynamicWorkflowDef,
    SpecialistStepSpec,
    SynthesisStepSpec,
)
from openexecutive.workflows.playbooks import load_playbook, playbook_clause
from openexecutive.workflows.tool_catalog import unavailable_step_tools
from openexecutive.workflows.wait_for_human import (
    CONTINUE_DECISIONS,
    DECISION_VERBS,
    NON_APPROVAL_SHAPES,
    HeldCall,
    WaitForHumanEvent,
    WaitForHumanResolution,
    WorkflowResumeState,
)

if TYPE_CHECKING:  # imported lazily at runtime (workflows -> orchestrator cycle)
    from openexecutive.workflows.action_step import TargetPolicy

# How long the owner has to answer about new write targets. No answer means
# the held writes are skipped and the run finishes without them.
HELD_WRITES_TIMEOUT_HOURS = 48

# Synthetic first step every dynamic workflow runs — loads the company profile
# and surfaces a "Load context" row in the UI, mirroring the built-ins.
_CONTEXT_STEP_ID = "context"


def _context_start() -> WorkflowEvent:
    return WorkflowEvent(type="step_start", step_id=_CONTEXT_STEP_ID, step_title="Load context")

_StepT = TypeVar("_StepT", ApprovalGateStepSpec, ActionStepSpec)


def _with_dropped(
    error: WorkflowEvent, workflow_name: str, state: WorkflowResumeState, reason: str
) -> WorkflowEvent:
    """A resume that stops before settling its held writes: audit them as
    dropped and say so in the error."""
    if state.kind != "held_writes" or not state.held:
        return error
    from openexecutive.workflows.action_step import drop_held_calls

    note = drop_held_calls(workflow_name, state.gate_step_id, state.held, reason)
    return error.model_copy(update={"message": f"{error.message} ({note})"})


def _load_context(verb: str) -> tuple[str, WorkflowEvent]:
    """The company block, plus the event closing the "Load context" row.

    Re-derived on resume rather than persisted: it is a pure function of the
    profile, and a profile edited during a pause is the one later steps see.
    """
    profile = load_or_create_profile()
    return _company_context_block(profile), WorkflowEvent(
        type="step_done",
        step_id=_CONTEXT_STEP_ID,
        summary=f"{verb} profile for {profile.name or 'company'}.",
    )

# Cap on the approver's own text carried into the artifact — and therefore
# into the synthesis specialist's prompt. A decision needs a sentence or two
# of reasoning; anything longer is not a sign-off note.
_MAX_REPLY_CHARS = 500


class _FlatFormatter(string.Formatter):
    """A Formatter that only substitutes flat ``{name}`` placeholders.

    Defense-in-depth alongside ``validate_definition``: it refuses attribute
    access (``{x.__class__}``), indexing (``{x[0]}``), and positional fields
    (``{0}`` / ``{}``), so a goal template can never walk object internals —
    even a definition that somehow bypassed validation. Disallowed forms raise
    KeyError, which the engine surfaces as a step error.
    """

    def get_field(self, field_name: str, args: Any, kwargs: Any) -> Any:
        if (
            not field_name
            or field_name[0].isdigit()
            or "." in field_name
            or "[" in field_name
        ):
            raise KeyError(field_name)
        return kwargs[field_name], field_name


_FLAT_FORMATTER = _FlatFormatter()


def _render(template: str, values: dict[str, Any]) -> str:
    """Substitute only flat declared-field placeholders into ``template``."""
    return _FLAT_FORMATTER.vformat(template, (), values)


class DynamicWorkflow(Workflow):
    """A ``Workflow`` backed by a stored :class:`DynamicWorkflowDef`."""

    def __init__(self, defn: DynamicWorkflowDef) -> None:
        self._defn = defn
        self.name = defn.name
        self.title = defn.title
        self.description = defn.description
        self.section = defn.section
        self.estimated_minutes = defn.estimated_minutes
        self._input_model: type[BaseModel] | None = None

    # -- ABC ---------------------------------------------------------------

    def input_model(self) -> type[BaseModel]:
        """Build a Pydantic model from the declared input fields (cached).

        Every field is a string (dynamic workflows take free-text inputs).
        Required fields use ``...``; optional fields default to ``""``.
        """
        if self._input_model is not None:
            return self._input_model
        field_defs: dict[str, Any] = {}
        for f in self._defn.input_fields:
            default = ... if f.required else ""
            field_defs[f.name] = (
                str,
                Field(default, title=f.label, description=f.description),
            )
        model: type[BaseModel] = create_model(  # type: ignore[call-overload]
            f"DynamicInput_{self.name}", **field_defs
        )
        self._input_model = model
        return model

    def steps(self) -> list[WorkflowStepDef]:
        out = [
            WorkflowStepDef(
                id=_CONTEXT_STEP_ID,
                title="Load context",
                description="Pull the company profile and prepare the run.",
            )
        ]
        for step in self._defn.steps:
            out.append(
                WorkflowStepDef(id=step.id, title=step.title, description=step.description)
            )
        return out

    def meta(self) -> WorkflowMeta:
        m = super().meta()
        return m.model_copy(update={"is_custom": True})

    def followed_playbooks(self) -> list[str]:
        names = [
            s.playbook
            for s in self._defn.steps
            if isinstance(s, SpecialistStepSpec) and s.playbook
        ]
        return list(dict.fromkeys(names))

    def sample_inputs(self) -> dict[str, Any] | None:
        if not self._defn.input_fields:
            return None
        # No synthetic content — just blank scaffolding the user fills in.
        return {f.name: "" for f in self._defn.input_fields}

    async def run(
        self,
        inputs: BaseModel,
        store: ChromaDBStore,
    ) -> AsyncIterator[WorkflowEvent]:
        values = inputs.model_dump()

        # --- pre-flight ---
        # Definitions are validated on create/update, not on load, so a stored
        # definition can outlive a specialist (the `talent` key was removed).
        # `route_to_specialist` would return the string "Unknown specialist: …"
        # as a step's OUTPUT — or, via a synthesis step's own `specialist`, as
        # the whole artifact. Check every step up front so the run fails
        # before any approval gate is raised or any specialist call is paid for.
        stale = _stale_specialist_steps(self._defn)
        if stale:
            yield _stale_error(stale)
            return
        # Same promise for action steps: a tool that vanished (server removed,
        # deny-listed, gateway down) fails the run BEFORE any step acts, not
        # after earlier steps already sent or changed something.
        missing_tools = await unavailable_step_tools(self._defn)
        if missing_tools:
            yield _missing_tools_error(missing_tools)
            return

        # --- context ---
        yield _context_start()
        company_block, loaded = _load_context("Loaded")
        yield loaded

        async for event in self._run_steps(
            start_index=0,
            values=values,
            company_block=company_block,
            outputs={},
            store=store,
            policy=self._target_policy(),
        ):
            yield event

    async def resume(
        self,
        *,
        inputs: BaseModel,
        state: WorkflowResumeState,
        resolution: WaitForHumanResolution,
        store: ChromaDBStore,
    ) -> AsyncIterator[WorkflowEvent]:
        """Continue a run that paused at an approval gate, now answered.

        Called by ``resumer._execute_resume`` in a background task, long after
        the HTTP request that started the run is gone. Yields the same event
        types ``run()`` does, so every consumer of a workflow stream works
        unchanged — including a second ``WaitForHumanEvent`` if the definition
        has another gate further on.
        """
        values = inputs.model_dump()

        # Same pre-flight as run(): the pause may have outlived a specialist.
        # A resumed run has already been paid for up to the gate, but finishing
        # it with "Unknown specialist: …" as a section is worse than failing.
        stale = _stale_specialist_steps(self._defn)
        if stale:
            yield _with_dropped(_stale_error(stale), self.name, state, "the run could not resume")
            return

        if state.kind == "held_writes":
            async for event in self._resume_held_writes(
                values=values, state=state, resolution=resolution, store=store
            ):
                yield event
            return

        gate = self._gate_for_resume(state)
        if gate is None:
            # `upsert_definition` overwrites by name, so the definition can
            # have been edited while the run sat at the gate — which silently
            # re-points the stored index at a different step. Resuming anyway
            # would skip or repeat work and produce a plausible-looking wrong
            # artifact, so refuse and say why.
            yield WorkflowEvent(
                type="error",
                message=(
                    "the workflow definition changed while this run was "
                    "awaiting approval, so it can no longer be resumed safely "
                    f"(expected an approval gate {state.gate_step_id!r} at "
                    f"step {state.gate_step_index}) — re-run the workflow"
                ),
            )
            return

        yield _context_start()
        company_block, loaded = _load_context("Reloaded")
        yield loaded

        decision = str(resolution.parsed_decision.get("decision") or "")
        if not _may_continue(gate, decision):
            # Not a recognisable yes, so stop rather than produce the
            # deliverable they did not approve. Everything after the gate
            # exists to act on an approval. The full decision — including a
            # verdict we did not recognise — stays in `resolution_json`.
            note = str(resolution.parsed_decision.get("note") or "").strip()
            verb = DECISION_VERBS.get(decision) or (
                f"Stopped on an unrecognised decision {decision!r}"
                if decision
                else "Stopped with no decision recorded"
            )
            yield WorkflowEvent(
                type="error",
                message=(
                    f"{verb} at the {gate.title!r} approval gate"
                    + (f": {note}" if note else "")
                ),
            )
            return

        # Only the steps still to run matter — the ones before the gate already
        # acted. Checked after the gate and the decision, so a rejection is
        # reported as a rejection, but before any remaining step acts.
        missing_tools = await unavailable_step_tools(
            self._defn, start_index=state.gate_step_index + 1
        )
        if missing_tools:
            yield _missing_tools_error(missing_tools, resuming=True)
            return

        # Give the synthesis step the decision as a readable section, and
        # close the gate's step in the event stream for symmetry with a fresh
        # run. Nothing consumes these events on the resume path today — the
        # original SSE socket closed hours ago and the run-detail page polls
        # JSON — but `resume()` yields the same shape `run()` does so any
        # future consumer (a reconnecting stream) needs no special case.
        outputs: dict[str, tuple[str, str]] = dict(state.outputs)
        outputs[gate.id] = (gate.title, _format_resolution(gate, resolution))
        yield WorkflowEvent(
            type="step_done",
            step_id=gate.id,
            summary=_first_line(outputs[gate.id][1]),
        )

        async for event in self._run_steps(
            # DERIVED from the validated gate index, never read from the
            # payload: a stored cursor is a second source of truth, and the
            # copy an attacker can edit would be the one we obeyed.
            start_index=state.gate_step_index + 1,
            values=values,
            company_block=company_block,
            outputs=outputs,
            store=store,
            policy=self._target_policy(state.run_created),
        ):
            yield event

    async def _resume_held_writes(
        self,
        *,
        values: dict[str, Any],
        state: WorkflowResumeState,
        resolution: WaitForHumanResolution,
        store: ChromaDBStore,
    ) -> AsyncIterator[WorkflowEvent]:
        """Continue a run that paused because an action step held new-target writes.

        The step itself already ran. Only an explicit "approve" runs the held
        calls (exactly as stored); a "no", a timeout, or anything unreadable
        skips them. Either way the run then carries on at the next step.
        """
        from openexecutive.workflows.action_step import run_held_calls

        step = self._step_for_resume(state, ActionStepSpec)
        if step is None:
            yield _with_dropped(
                WorkflowEvent(
                    type="error",
                    message=(
                        "the workflow definition changed while this run was waiting "
                        "for approval of new write targets, so it can no longer be "
                        f"resumed safely (expected action step {state.gate_step_id!r}) "
                        "— re-run the workflow"
                    ),
                ),
                self.name, state, "the definition changed",
            )
            return

        yield _context_start()
        company_block, loaded = _load_context("Reloaded")
        yield loaded

        # Same order as a gate: the remaining steps' tools are checked before
        # anything acts — including the held writes about to be approved.
        missing_tools = await unavailable_step_tools(
            self._defn, start_index=state.gate_step_index + 1
        )
        if missing_tools:
            yield _with_dropped(
                _missing_tools_error(missing_tools, resuming=True),
                self.name, state, "a later step's tools are unavailable",
            )
            return

        decision = str(resolution.parsed_decision.get("decision") or "")
        approved = decision == "approve"
        skip_reason = {
            "reject": "declined",
            "auto_proceed": "no answer in time",
        }.get(decision, "not approved")
        policy = self._target_policy(state.run_created)
        section = await run_held_calls(
            step,
            state.held,
            workflow_name=self.name,
            run_id=resolution.run_id,
            approved=approved,
            skip_reason=skip_reason,
            policy=policy,
        )
        outputs: dict[str, tuple[str, str]] = dict(state.outputs)
        title, text = outputs.get(step.id, (step.title, ""))
        outputs[step.id] = (title, f"{text}\n\n{section}".strip())
        yield WorkflowEvent(
            type="step_done", step_id=step.id, summary=_first_line(section)
        )

        async for event in self._run_steps(
            start_index=state.gate_step_index + 1,
            values=values,
            company_block=company_block,
            outputs=outputs,
            store=store,
            policy=policy,
        ):
            yield event

    async def _held_writes_pause(
        self,
        step: ActionStepSpec,
        index: int,
        held: list[HeldCall],
        outputs: dict[str, tuple[str, str]],
        policy: TargetPolicy | None,
    ) -> WaitForHumanEvent | None:
        """The pause that asks the owner about ``step``'s held writes.

        Asks the workflow's creator (falling back to the principal). With no
        one to ask, the held writes are skipped, noted in the step's output,
        and None is returned so the run carries on.
        """
        from openexecutive.workflows.action_step import held_question, run_held_calls
        from openexecutive.workflows.approved_targets import approver_for

        approver = approver_for(self.name)
        if approver is None:
            section = await run_held_calls(
                step,
                held,
                workflow_name=self.name,
                run_id="",
                approved=False,
                skip_reason="no one to approve it",
                policy=policy,
            )
            title, text = outputs[step.id]
            outputs[step.id] = (title, f"{text}\n\n{section}")
            return None
        return WaitForHumanEvent(
            person_id=approver,
            question=held_question(self.title, held),
            timeout_hours=HELD_WRITES_TIMEOUT_HOURS,
            # No answer skips the held writes (only "approve" runs them) and
            # lets the rest of the run finish.
            on_timeout="auto_proceed",
            expected_reply_shape="approve_reject",
            context_summary=f"New write targets in workflow {self.title!r}",
            resume_state=WorkflowResumeState(
                workflow_name=self.name,
                gate_step_id=step.id,
                gate_step_index=index,
                steps_fingerprint=_steps_fingerprint(self._defn),
                outputs=dict(outputs),
                kind="held_writes",
                held=list(held),
                run_created=policy.created() if policy is not None else [],
            ),
        )

    def _target_policy(self, created: list[str] | None = None) -> TargetPolicy:
        from openexecutive.workflows.action_step import TargetPolicy

        return TargetPolicy.for_workflow(self._defn, created=created or ())

    # -- step loop ---------------------------------------------------------

    def _gate_for_resume(
        self, state: WorkflowResumeState
    ) -> ApprovalGateStepSpec | None:
        """The approval gate this payload paused at, or None if it no longer matches."""
        return self._step_for_resume(state, ApprovalGateStepSpec)

    def _step_for_resume(
        self, state: WorkflowResumeState, step_type: type[_StepT]
    ) -> _StepT | None:
        """The step a payload paused at (a gate, or the action step that held
        writes), or None if it no longer matches.

        Every field is checked against the LIVE definition because all of them
        can go stale during a pause: the payload may predate this build
        (`version`/`engine`), name a workflow this object isn't, or point at an
        index the definition no longer has — or has, but now holds a different
        step.
        """
        if state.version != 1 or state.engine != "dynamic":
            return None
        if state.workflow_name != self.name:
            return None
        if not 0 <= state.gate_step_index < len(self._defn.steps):
            return None
        step = self._defn.steps[state.gate_step_index]
        if not isinstance(step, step_type) or step.id != state.gate_step_id:
            return None
        # The gate being where we left it is NOT enough. Someone can keep the
        # gate identical and replace every step after it while the run is
        # parked, so the approver's yes lands on work they never saw. Pin the
        # whole list. (An empty fingerprint is a payload written before this
        # check existed; refuse it rather than grandfather a gap in the very
        # control this is protecting.)
        if state.steps_fingerprint != _steps_fingerprint(self._defn):
            return None
        return step

    async def _run_steps(
        self,
        *,
        start_index: int,
        values: dict[str, Any],
        company_block: str,
        outputs: dict[str, tuple[str, str]],
        store: ChromaDBStore,
        policy: TargetPolicy | None,
    ) -> AsyncIterator[WorkflowEvent]:
        """Interpret steps from ``start_index`` on.

        The single place step semantics live, so ``run()`` and ``resume()``
        cannot drift apart — and so a gate reached on a resumed run raises the
        same pause, with the same payload shape, as one reached on a fresh run.
        """
        for index in range(start_index, len(self._defn.steps)):
            step = self._defn.steps[index]

            if isinstance(step, SpecialistStepSpec):
                yield WorkflowEvent(
                    type="step_start", step_id=step.id, step_title=step.title
                )
                try:
                    goal = _render(step.goal, values)
                    playbook_body = load_playbook(step.playbook) if step.playbook else ""
                    goal += playbook_clause(playbook_body, "Follow this playbook")
                    rag = ""
                    if step.rag_query:
                        rag = retrieve(
                            query=_render(step.rag_query, values),
                            specialist_name=step.specialist,
                            n_builtin=5,
                            n_company=3,
                            store=store,
                        )
                except (KeyError, IndexError) as exc:
                    yield WorkflowEvent(
                        type="error",
                        message=f"step {step.id!r} placeholder error: {exc}",
                    )
                    return
                if step.playbook and not playbook_body.strip():
                    # Say so in the run rather than silently changing what an
                    # approved workflow follows.
                    yield WorkflowEvent(
                        type="progress",
                        step_id=step.id,
                        summary=(
                            f"Playbook '{step.playbook}' is unavailable or empty (hidden, "
                            "deleted or unreadable); this step runs on its own goal."
                        ),
                    )
                result = await route_to_specialist(
                    specialist_name=step.specialist,
                    query=goal,
                    context=company_block,
                    retrieved_knowledge=rag,
                )
                outputs[step.id] = (step.title, result)
                yield WorkflowEvent(
                    type="step_done", step_id=step.id, summary=_first_line(result)
                )

            elif isinstance(step, ApprovalGateStepSpec):
                yield WorkflowEvent(
                    type="step_start", step_id=step.id, step_title=step.title
                )
                try:
                    question = _render(step.question, values)
                except (KeyError, IndexError) as exc:
                    yield WorkflowEvent(
                        type="error",
                        message=f"step {step.id!r} placeholder error: {exc}",
                    )
                    return
                # The caller delivers the question, checkpoints the run
                # (status='awaiting_human') and stops. `resume_state` is what
                # lets it be picked up again — without it the gate is
                # pause-only and the steps below never run.
                # WaitForHumanEvent is a sentinel the caller isinstance-checks;
                # it isn't a WorkflowEvent, hence the typed-yield ignore.
                gate = WaitForHumanEvent(
                    person_id=step.person_id,
                    question=question,
                    timeout_hours=step.timeout_hours,
                    on_timeout=step.on_timeout,
                    expected_reply_shape=step.expected_reply_shape,
                    context_summary=f"Approval gate in workflow {self.title!r}",
                    resume_state=WorkflowResumeState(
                        workflow_name=self.name,
                        gate_step_id=step.id,
                        gate_step_index=index,
                        steps_fingerprint=_steps_fingerprint(self._defn),
                        # Copy: the caller serialises this after we return, and
                        # a live reference would keep mutating under it if the
                        # loop ever continued.
                        outputs=dict(outputs),
                        run_created=policy.created() if policy is not None else [],
                    ),
                )
                yield gate  # type: ignore[misc]
                return

            elif isinstance(step, ActionStepSpec):
                from openexecutive.workflows.action_step import (
                    drop_held_calls,
                    run_action_step,
                )

                yield WorkflowEvent(
                    type="step_start", step_id=step.id, step_title=step.title
                )
                try:
                    goal = _render(step.goal, values)
                except (KeyError, IndexError) as exc:
                    yield WorkflowEvent(
                        type="error",
                        message=f"step {step.id!r} placeholder error: {exc}",
                    )
                    return
                held: list[HeldCall] = []
                try:
                    async for kind, payload in run_action_step(
                        step,
                        workflow_name=self.name,
                        workflow_title=self.title,
                        goal=goal,
                        values=values,
                        company_block=company_block,
                        prior_outputs=dict(outputs),
                        policy=policy,
                    ):
                        if kind == "progress":
                            yield WorkflowEvent(
                                type="progress", step_id=step.id, summary=payload
                            )
                        elif kind == "held":
                            held.append(payload)
                        elif kind == "error":
                            if held:
                                note = drop_held_calls(self.name, step.id, held, "the step failed")
                                payload = f"{payload} ({note})"
                            yield WorkflowEvent(type="error", message=payload)
                            return
                        else:
                            outputs[step.id] = (step.title, payload)
                            yield WorkflowEvent(
                                type="step_done", step_id=step.id, summary=_first_line(payload)
                            )
                except BaseException:  # cancellation too: they will never run
                    if held:
                        drop_held_calls(self.name, step.id, held, "the step stopped")
                    raise
                if held:
                    pause = await self._held_writes_pause(step, index, held, outputs, policy)
                    if pause is not None:
                        yield pause  # type: ignore[misc]
                        return

            elif isinstance(step, SynthesisStepSpec):
                yield WorkflowEvent(
                    type="step_start", step_id=step.id, step_title=step.title
                )
                artifact = await _synthesize(step, self.title, outputs, company_block)
                yield WorkflowEvent(
                    type="step_done",
                    step_id=step.id,
                    summary=f"Assembled {len(artifact)} characters.",
                )
                yield WorkflowEvent(type="artifact", content=artifact)
                return


# ---------------------------------------------------------------------------
# Internal helpers (mirror the private helpers in the hand-written workflows)
# ---------------------------------------------------------------------------


def _steps_fingerprint(defn: DynamicWorkflowDef) -> str:
    """A stable digest of a definition's step list.

    Covers the steps only — not the title, cadence or description — because
    those do not change what a resumed run will DO. Serialised through the
    Pydantic models so field order is fixed and a semantically identical
    definition fingerprints identically across processes.
    """
    body = "\n".join(step.model_dump_json() for step in defn.steps)
    return hashlib.sha256(body.encode("utf-8")).hexdigest()


def _may_continue(step: ApprovalGateStepSpec, decision: str) -> bool:
    """Whether a resumed run may proceed past this gate.

    Fails closed for approve/reject gates: only a recognised approval
    continues. The other reply shapes are questions, not permission, so their
    answer is data and the run always continues.
    """
    if step.expected_reply_shape in NON_APPROVAL_SHAPES:
        return True
    return decision in CONTINUE_DECISIONS


def _stale_error(stale: list[tuple[str, str]]) -> WorkflowEvent:
    """The error a run (or resume) fails with when a specialist has gone.

    Shared by both entry points so the message a resumed run dies with is the
    same one a fresh run would have shown.
    """
    return WorkflowEvent(
        type="error",
        message=(
            "workflow names a specialist that no longer exists — "
            + "; ".join(f"step {sid!r} uses {name!r}" for sid, name in stale)
            + " — edit the workflow to use a current specialist"
        ),
    )


def _format_resolution(
    step: ApprovalGateStepSpec, resolution: WaitForHumanResolution
) -> str:
    """Render the human's answer as the gate step's Markdown output.

    The gate is a step, so on resume it gets an output like any other and
    flows into synthesis — which is how the decision ends up IN the artifact
    rather than only in a database column. Shape-aware, because a `numeric`
    gate's answer is a number and rendering it as an approval would be a lie.
    """
    parsed = resolution.parsed_decision or {}
    shape = step.expected_reply_shape
    lines: list[str] = []

    def _quote(text: str) -> str:
        """Fence the human's own words before they reach a specialist prompt.

        This section becomes a "section draft" handed to the synthesis
        specialist, so anything the approver wrote arrives as prompt context.
        Label it as data and cap it: a `free_text` gate otherwise passes the
        whole reply through (Slack allows tens of thousands of characters),
        and an approver could reshape the artifact by writing instructions
        into their answer.
        """
        clean = " ".join(str(text).split())
        if len(clean) > _MAX_REPLY_CHARS:
            clean = clean[: _MAX_REPLY_CHARS - 1].rstrip() + "…"
        return f"> {clean}" if clean else ""

    if shape == "numeric":
        value = parsed.get("value")
        unit = str(parsed.get("unit") or "").strip()
        rendered = "no value given" if value is None else f"{value}{' ' + unit if unit else ''}"
        lines.append(f"**Answer:** {rendered}")
    elif shape == "free_text":
        lines.append(_quote(parsed.get("text") or resolution.reply_text or ""))
    elif shape == "document":
        preview = str(parsed.get("text_preview") or "").strip()
        lines.append("**Document received.**" if parsed.get("received") else "**No document received.**")
        if preview:
            lines.append("\n" + _quote(preview))
    else:  # approve_reject
        decision = str(parsed.get("decision") or "")
        lines.append(f"**{DECISION_VERBS.get(decision, 'Recorded')}**")
        note = str(parsed.get("note") or "").strip()
        if note:
            lines.append("\n" + _quote(note))

    if str(parsed.get("decision") or "") == "auto_proceed":
        lines.append(
            "\n_No human reply arrived before the deadline; the workflow's "
            "`on_timeout` policy auto-proceeded._"
        )

    provenance = f"person {resolution.person_id}"
    if resolution.source_channel:
        provenance += f" via {resolution.source_channel}"
    if resolution.resolved_at:
        provenance += f" at {resolution.resolved_at}"
    lines.append(f"\n_Recorded from {provenance}._")

    body = "\n".join(part for part in lines if part).strip()
    return f"## {step.title}\n\n{body}\n"


def _missing_tools_error(missing: list[str], *, resuming: bool = False) -> WorkflowEvent:
    outcome = (
        "the steps after the approval did not run"
        if resuming
        else "the workflow did not start"
    )
    return WorkflowEvent(
        type="error",
        message=f"these tools are not available right now, so {outcome}: {', '.join(missing)}",
    )


def _stale_specialist_steps(defn: DynamicWorkflowDef) -> list[tuple[str, str]]:
    """(step_id, specialist) for every step that would consult a specialist
    missing from the live registry. A synthesis step only consults one when it
    has `instructions`."""
    stale: list[tuple[str, str]] = []
    for step in defn.steps:
        if isinstance(step, ApprovalGateStepSpec | ActionStepSpec):
            continue
        if isinstance(step, SynthesisStepSpec) and not step.instructions:
            continue
        if step.specialist not in SPECIALIST_REGISTRY:
            stale.append((step.id, step.specialist))
    return stale


async def _synthesize(
    step: SynthesisStepSpec,
    workflow_title: str,
    outputs: dict[str, tuple[str, str]],
    company_block: str,
) -> str:
    """Build the final Markdown artifact from prior step outputs."""
    joined = "\n\n".join(
        _ensure_heading(text, f"## {title}") for title, text in outputs.values()
    )
    if not step.instructions:
        body = joined or "_(No content was generated.)_"
        return f"# {workflow_title}\n\n{body}\n"
    # Run one synthesis consult over the drafts.
    result = await route_to_specialist(
        specialist_name=step.specialist,
        query=(
            f"{step.instructions}\n\n"
            "Assemble the following section drafts into one coherent Markdown "
            f"document titled '{workflow_title}'. Preserve substance; remove "
            "redundancy.\n\nSection drafts:\n\n" + joined
        ),
        context=company_block,
    )
    return result.strip() + "\n"


def _company_context_block(profile: CompanyProfile | None) -> str:
    if profile is None or profile.is_empty():
        return ""
    return profile.to_prompt_block()


def _first_line(text: str, max_len: int = 140) -> str:
    if not text:
        return "(empty)"
    line = text.strip().split("\n", 1)[0].lstrip("# ").strip()
    return line[: max_len - 1] + "…" if len(line) > max_len else line


def _ensure_heading(text: str, expected_heading: str) -> str:
    stripped = text.strip()
    if not stripped:
        return f"{expected_heading}\n\n_(No content generated for this section.)_"
    first_line = stripped.split("\n", 1)[0]
    # Any Markdown heading (#, ##, ###…) means the section already self-labels;
    # don't prepend our own and invert the hierarchy (e.g. ## above a #).
    if first_line.lstrip().startswith("#"):
        return stripped
    return f"{expected_heading}\n\n{stripped}"