AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""HTTP surface for the workflows package.
Endpoints:
- GET /workflows List available workflows with metadata
- GET /workflows/{name} Get one workflow's metadata + input schema
- POST /workflows/{name}/runs Start a run; streams progress as SSE
(403 for a principal-only one unless the principal)
- GET /workflows/runs List recent runs across all workflows
- GET /workflows/runs/{run_id} Get a specific past run (with artifact)
- POST /workflows/runs/{run_id}/rerun Run a failed scheduled run again
- DELETE /workflows/runs/{run_id} Delete a past run
"""
from __future__ import annotations
import json
import logging
import time
import uuid
from typing import Any
from fastapi import APIRouter, HTTPException, Request
from fastapi.responses import StreamingResponse
from pydantic import ValidationError
from openexecutive.api import caller as api_caller
from openexecutive.workflows import (
get_workflow,
list_workflows,
)
from openexecutive.workflows.dynamic_models import (
TOOL_NAME_RE,
ActionStepSpec,
DynamicWorkflowDef,
)
from openexecutive.workflows.dynamic_store import (
activate_if_unchanged,
delete_definition,
get_definition,
get_owner,
list_definitions,
save_if_unchanged,
set_active,
upsert_definition,
)
from openexecutive.workflows.gate import checkpoint_gate
from openexecutive.workflows.persistence import (
complete_run,
create_run,
delete_run,
fail_run,
get_run,
initialize_runs_db,
list_runs,
run_visible_to,
stored_artifact,
)
from openexecutive.workflows.tool_catalog import resolve as resolve_tools_catalog
from openexecutive.workflows.tool_catalog import search as search_tools_catalog
from openexecutive.workflows.tool_catalog import validate_definition_and_tools
from openexecutive.workflows.wait_for_human import WaitForHumanEvent
router = APIRouter()
logger = logging.getLogger(__name__)
@router.get("/workflows")
async def list_workflow_meta() -> dict[str, Any]:
"""Public catalog of available workflows."""
return {"workflows": [w.meta().model_dump() for w in list_workflows()]}
@router.get("/workflows/runs")
async def list_workflow_runs(
request: Request, workflow: str | None = None, limit: int = 100
) -> dict[str, Any]:
"""Recent runs across all workflows (or filtered by workflow name) that
the caller may see (``persistence.run_visible_to``): the team's, and
their own."""
initialize_runs_db()
return {
"runs": list_runs(
workflow_name=workflow, limit=limit, visible_to=_caller_person_id(request)
)
}
def _caller_person_id(request: Request) -> int | None:
from openexecutive.api.routes.chat import _resolve_caller_person_id
return _resolve_caller_person_id(request)
def _visible_run(run_id: str, request: Request) -> dict[str, Any]:
"""The run, or 404 — also for someone else's, so its existence is not
revealed either."""
run = get_run(run_id)
if run is None or not run_visible_to(run, _caller_person_id(request)):
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
return run
@router.get("/workflows/runs/{run_id}")
async def get_workflow_run(run_id: str, request: Request) -> dict[str, Any]:
"""Full record of one run, including the artifact if complete.
`resume_state_json` is replaced by a small `resume_progress` summary. The
payload holds the full text of every step completed before the gate, and
the run-detail page POLLS this endpoint while a run is unfinished — so
returning it would re-send the whole run body every few seconds to render
a progress list that only needs the step ids.
"""
run = _visible_run(run_id, request)
run["resume_progress"] = _resume_progress(run.pop("resume_state_json", None))
run["rerunnable"] = _rerunnable(run)
return run
def _rerunnable(run: dict[str, Any]) -> bool:
"""Whether Run again can queue this run (a failed scheduled one), so the
run page offers the button only where it works."""
if run.get("status") != "error":
return False
from openexecutive.workflows.failure_alerts import RerunRefused, rerun_target
try:
rerun_target(run)
except RerunRefused:
return False
return True
@router.delete("/workflows/runs/{run_id}")
async def delete_workflow_run(run_id: str, request: Request) -> dict[str, str]:
_visible_run(run_id, request)
if not delete_run(run_id):
raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
return {"status": "deleted", "run_id": run_id}
@router.post("/workflows/runs/{run_id}/rerun")
def rerun_workflow_run(run_id: str, request: Request) -> dict[str, Any]:
"""Run a failed scheduled run again (the Run again on its Home card).
A plain ``def`` so FastAPI runs it in the threadpool: ``queue_rerun``
takes a threading lock around SQLite work, which must not block the
event loop.
Queues the same scheduled action, due now, which delivers the way the
scheduled run would have. The principal may, and for a saved workflow
also the person it delivers to. A run someone started from /jobs is
started again from its page instead (409).
"""
from openexecutive.api.routes.people import caller_is_principal
from openexecutive.workflows.failure_alerts import (
RerunRefused,
queue_rerun,
rerun_target,
)
run = _visible_run(run_id, request)
try:
_kind, _ref, assignee = rerun_target(run)
except RerunRefused as exc:
raise HTTPException(status_code=exc.status, detail=exc.detail) from exc
caller = _caller_person_id(request)
if not caller_is_principal(request) and (assignee is None or caller != assignee):
raise HTTPException(
status_code=403, detail="Only the principal, or the person it goes to, can run it again."
)
try:
action_id = queue_rerun(run)
except RerunRefused as exc:
raise HTTPException(status_code=exc.status, detail=exc.detail) from exc
from openexecutive.audit import log_event as audit_log
audit_log(
"workflow_rerun",
f"Run again: {run.get('title') or run.get('workflow_name')}",
actor="user",
details={"run_id": run_id, "action_id": action_id},
)
return {"status": "queued", "run_id": run_id, "action_id": action_id}
_WEB_DECISIONS = {"approve", "reject"}
@router.post("/workflows/runs/{run_id}/decision")
async def decide_workflow_run(run_id: str, request: Request) -> dict[str, Any]:
"""Answer a run waiting for a yes/no sign-off from the web app.
The same resolution a chat reply produces, so the run resumes exactly as
it would have. Only the person the run is waiting on — or the principal —
may answer; free-text / numeric / document requests still need a reply in
chat, since there is nothing here to parse.
"""
from openexecutive.api.routes.chat import _resolve_caller_person_id
from openexecutive.people.store import is_principal_or_self
from openexecutive.workflows.resumer import apply_resolution
from openexecutive.workflows.wait_for_human import WaitForHumanResolution
try:
body = await request.json()
except json.JSONDecodeError:
body = {}
decision = body.get("decision") if isinstance(body, dict) else None
if decision not in _WEB_DECISIONS:
raise HTTPException(status_code=422, detail="decision must be 'approve' or 'reject'")
run = _visible_run(run_id, request)
if run.get("status") != "awaiting_human":
raise HTTPException(status_code=409, detail="This run isn't waiting for an answer.")
try:
gate = json.loads(run.get("state_json") or "{}")
except json.JSONDecodeError:
gate = {}
if not isinstance(gate, dict) or gate.get("expected_reply_shape", "approve_reject") != "approve_reject":
raise HTTPException(
status_code=409, detail="This request needs a written reply — answer it in chat."
)
awaiting = run.get("awaiting_person_id")
caller = _resolve_caller_person_id(request)
if not is_principal_or_self(caller, awaiting):
raise HTTPException(
status_code=403, detail="Only the person this is waiting on, or the principal, can answer."
)
assert caller is not None # is_principal_or_self refuses an unresolved caller
resolution = WaitForHumanResolution(
run_id=run_id,
reply_text=f"[{decision} from the web app]",
source_channel="web",
parsed_decision={"decision": decision, "note": "answered in the web app"},
person_id=caller,
)
if not await apply_resolution(run_id, resolution):
raise HTTPException(status_code=409, detail="This run was answered already.")
return {"status": "resolved", "run_id": run_id, "decision": decision}
# -----------------------------------------------------------------------------
# Dynamic (user-created) workflow CRUD. Declared BEFORE "/workflows/{name}" so
# the literal "custom" segment isn't captured by the {name} path parameter.
# -----------------------------------------------------------------------------
_TOOL_SEARCH_MAX_QUERY = 200
@router.get("/workflows/tools/search")
async def search_workflow_tools(q: str = "") -> dict[str, Any]:
"""Tools an action step can use that match ``q`` (built-ins + MCP gateway).
Backs the advanced editor's tool picker. Literal path, declared before
``/workflows/{name}``.
"""
query = q.strip()[:_TOOL_SEARCH_MAX_QUERY]
if not query:
return {"tools": []}
return {"tools": [t.as_dict() for t in await search_tools_catalog(query)]}
_TOOL_DESCRIBE_MAX_NAMES = 32
@router.get("/workflows/tools/describe")
async def describe_workflow_tools(names: str = "") -> dict[str, Any]:
"""Exact-name lookup for a comma-separated list of tool names.
Lets the review card and the advanced editor label each approved tool
(description, reads-only) — the definition itself only stores names.
Unknown names are simply absent from the result.
"""
# Only well-formed, distinct names: each non-built-in one costs a gateway
# search, so junk must not fan out into the shared MCP session.
wanted = list(
dict.fromkeys(n.strip() for n in names.split(",") if TOOL_NAME_RE.match(n.strip()))
)[:_TOOL_DESCRIBE_MAX_NAMES]
if not wanted:
return {"tools": []}
found = await resolve_tools_catalog(wanted)
return {"tools": [found[n].as_dict() for n in wanted if n in found]}
def _with_owner(defn: DynamicWorkflowDef) -> dict[str, Any]:
"""A definition as the UI sees it: its fields plus who created it.
``owner_person_id`` is server-managed (a column, not a definition field),
so a client echoing it back in a body has no effect.
"""
return {**defn.model_dump(), "owner_person_id": get_owner(defn.name)}
def _refuse_unless_creator(
defn: DynamicWorkflowDef, request: Request, owner_id: int | None, *, stored: bool = False,
) -> None:
"""403 when ``defn`` sends email as its creator or reads their mail and
the caller isn't that creator, verified, or it reads and does what a run
may not after reading mail (``workflow_email.save_refusal``)."""
from openexecutive.delegation.workflow_email import save_refusal
# The copy being replaced: only who may change it (an edit may be what
# takes out a tool it may no longer list).
refused = save_refusal(defn, api_caller.caller(request), owner_id, check_tools=not stored)
if refused is not None:
raise HTTPException(status_code=403, detail=refused)
@router.get("/workflows/custom")
async def list_custom_workflows() -> dict[str, Any]:
"""All dynamic definitions (active and inactive) for the builder UI."""
return {"definitions": [_with_owner(d) for d in list_definitions(active_only=False)]}
@router.post("/workflows/custom", status_code=201)
async def create_custom_workflow(request: Request) -> dict[str, Any]:
"""Create a new dynamic workflow definition from a builder-UI submission.
The signed-in caller becomes its owner — the person asked to approve its
first write to a new target.
"""
from openexecutive.api.routes.chat import _resolve_caller_person_id
defn = await _parse_definition(request)
exists = f"A custom workflow named {defn.name!r} already exists"
if get_definition(defn.name) is not None:
raise HTTPException(status_code=409, detail=exists)
errors = await validate_definition_and_tools(defn)
if errors:
raise HTTPException(status_code=422, detail=errors)
owner_person_id = _resolve_caller_person_id(request)
_refuse_unless_creator(defn, request, owner_person_id)
# Insert-only: a create racing another save of the same name is a 409,
# never a silent overwrite of someone else's workflow (or its owner).
stored = save_if_unchanged(defn, None, owner_person_id=owner_person_id)
if stored is None:
raise HTTPException(status_code=409, detail=exists)
_sync_cadence(stored)
return _with_owner(stored)
@router.get("/workflows/custom/{name}")
async def get_custom_workflow(name: str) -> dict[str, Any]:
defn = get_definition(name)
if defn is None:
raise HTTPException(status_code=404, detail=f"Custom workflow {name!r} not found")
return _with_owner(defn)
@router.put("/workflows/custom/{name}")
async def update_custom_workflow(name: str, request: Request) -> dict[str, Any]:
if get_definition(name) is None:
raise HTTPException(status_code=404, detail=f"Custom workflow {name!r} not found")
defn = await _parse_definition(request)
if defn.name != name:
raise HTTPException(
status_code=422, detail="definition name does not match the path name"
)
errors = await validate_definition_and_tools(defn)
if errors:
raise HTTPException(status_code=422, detail=errors)
# Sending as its creator: only they may change it, keeping it or adding it.
owner = get_owner(name)
_refuse_unless_creator(defn, request, owner)
current = get_definition(name)
if current is not None:
_refuse_unless_creator(current, request, owner, stored=True)
stored = upsert_definition(defn)
_sync_cadence(stored)
return stored.model_dump()
@router.delete("/workflows/custom/{name}")
async def delete_custom_workflow(name: str) -> dict[str, str]:
from openexecutive.workflows.dynamic_cadence import cancel_cadence_rows
cancel_cadence_rows(name)
if not delete_definition(name):
raise HTTPException(status_code=404, detail=f"Custom workflow {name!r} not found")
return {"status": "deleted", "name": name}
@router.get("/workflows/custom/{name}/targets")
async def list_approved_targets(name: str) -> dict[str, Any]:
"""Where this workflow's tool steps may write without asking again."""
from openexecutive.workflows.approved_targets import list_targets
if get_definition(name) is None:
raise HTTPException(status_code=404, detail=f"Custom workflow {name!r} not found")
return {"targets": list_targets(name)}
@router.delete("/workflows/custom/{name}/targets")
async def forget_approved_target(name: str, value: str) -> dict[str, str]:
"""Forget one approved target; the next write there asks again."""
from openexecutive.workflows.approved_targets import forget
if not forget(name, value):
raise HTTPException(status_code=404, detail="That target isn't approved for this workflow")
return {"status": "forgotten", "name": name}
# Fields a reviewer can't see or that the server manages; the rest is what the
# review card shows, and what an activation must match.
_REVIEW_EXCLUDE = {"is_active", "created_at", "updated_at"}
def _reviewed_matches(stored: DynamicWorkflowDef, reviewed: Any) -> bool:
"""True when ``reviewed`` (the definition the user looked at) is ``stored``."""
try:
seen = DynamicWorkflowDef.model_validate(reviewed)
except ValidationError:
return False
return seen.model_dump(exclude=_REVIEW_EXCLUDE) == stored.model_dump(exclude=_REVIEW_EXCLUDE)
@router.post("/workflows/custom/{name}/save-edit")
async def save_designer_edit(name: str, request: Request) -> dict[str, Any]:
"""Save the draft of a conversation that edits ``name``.
The conversation is opened by ``POST /workflows/designer/edit``. This saves
that session's own draft, never a definition the client sends, and only
when it is the ``definition`` the user reviewed (a message that landed
after the card loaded is a 409, so the click saves only what was shown)
and the stored workflow is still the version the conversation opened on:
an edit started before someone changed it or switched it off is a 409,
not a silent overwrite. The stored on/off state is kept. Declared under
``/workflows/custom`` so whatever limits writes to custom workflows covers
it too.
"""
from openexecutive.api.routes import workflow_designer as designer_routes
try:
body = await request.json()
except json.JSONDecodeError:
body = {}
session_id = body.get("session_id") if isinstance(body, dict) else None
if not isinstance(session_id, str) or not session_id:
raise HTTPException(status_code=422, detail="session_id is required")
session = designer_routes._get_session(session_id)
with designer_routes._one_turn(session):
original = session.original
if session.editing != name or original is None:
raise HTTPException(
status_code=409, detail="That conversation is about a different workflow."
)
if session.phase != "draft" or session.draft is None:
raise HTTPException(status_code=409, detail="There are no changes to save yet.")
if not _reviewed_matches(session.draft.definition, body.get("definition")):
raise HTTPException(
status_code=409,
detail="The draft changed since you reviewed it — check the latest version.",
)
defn = session.draft.definition.model_copy(
update={"name": name, "is_active": original.is_active}
)
errors = await validate_definition_and_tools(defn)
if errors:
raise HTTPException(status_code=422, detail=errors)
owner = get_owner(name)
_refuse_unless_creator(defn, request, owner)
_refuse_unless_creator(original, request, owner, stored=True)
stored = save_if_unchanged(defn, original)
if stored is None:
raise HTTPException(
status_code=409,
detail=(
"This workflow changed since you started editing it — open it "
"again to see the current version."
),
)
# Later saves in the same conversation compare with what is stored now.
session.original = stored
_sync_cadence(stored)
return _with_owner(stored)
def _tapper_person_id(who: Any) -> int | None:
"""The People entry of a card's tapper: a request's caller, or a chat
app's proven tap (``ChatTap``)."""
if isinstance(who, api_caller.Caller):
return api_caller.person_id_for(who)
from openexecutive.people.store import find_person_by_email
email = str(getattr(who, "email", "") or "")
person = find_person_by_email(email) if email else None
return person.id if person is not None else None
async def apply_chat_change(
name: str, definition: dict[str, Any], base: Any, who: Any
) -> DynamicWorkflowDef:
"""Save a change chat staged on a card (``orchestrator.workflow_change``),
on its person's tap. ``base`` is the version the card was made from: a
workflow changed since is a 409, so the tap saves only what the card
showed. ``who`` is the tapper (a request's caller, or a chat app's proven
tap), checked as a save from the Workflows page is. The on/off state is
kept."""
from openexecutive.delegation.workflow_email import save_refusal
from openexecutive.people.store import is_principal_or_self
current = get_definition(name)
if current is None:
raise HTTPException(status_code=404, detail="That workflow isn't there any more.")
if not _reviewed_matches(current, base):
raise HTTPException(
status_code=409,
detail="This workflow changed since the card was made, so nothing was changed. Ask again in chat.",
)
try:
defn = DynamicWorkflowDef.model_validate(definition)
except ValidationError:
raise HTTPException(status_code=422, detail="This change can't be read any more. Ask again in chat.") from None
if defn.name != name:
raise HTTPException(status_code=422, detail="This change is for a different workflow.")
defn = defn.model_copy(update={"is_active": current.is_active})
errors = await validate_definition_and_tools(defn)
if errors:
raise HTTPException(status_code=422, detail="; ".join(errors)[:300])
owner = get_owner(name)
# The card may be a day old: whoever taps must still be the account owner
# or the workflow's creator, as when it was staged.
if not is_principal_or_self(_tapper_person_id(who), owner):
raise HTTPException(
status_code=403,
detail="Only the account owner or the person who created this workflow can change it.",
)
for checked, stored in ((defn, False), (current, True)):
refused = save_refusal(checked, who, owner, check_tools=not stored)
if refused is not None:
raise HTTPException(status_code=403, detail=refused)
saved = save_if_unchanged(defn, current)
if saved is None:
raise HTTPException(
status_code=409,
detail="This workflow changed while saving, so nothing was changed. Ask again in chat.",
)
_sync_cadence(saved)
return saved
@router.post("/workflows/custom/{name}/activate")
async def activate_custom_workflow(name: str, request: Request) -> dict[str, Any]:
"""Turn a custom workflow on or off.
Turning one on is the approval for a tool workflow chat saved switched off,
so the body must carry the ``definition`` the user reviewed when the stored
one has action steps: a mismatch (e.g. chat overwrote it while the card was
open) is a 409, so the click can only switch on what was shown.
"""
try:
body = await request.json()
except json.JSONDecodeError:
body = {}
if not isinstance(body, dict):
body = {}
is_active = bool(body.get("is_active", True))
current = get_definition(name)
if current is None:
raise HTTPException(status_code=404, detail=f"Custom workflow {name!r} not found")
if is_active:
reviewed = body.get("definition")
needs_review = any(isinstance(s, ActionStepSpec) for s in current.steps)
changed = "This workflow changed since you opened it — reload to review the current version."
if (needs_review or reviewed is not None) and not _reviewed_matches(current, reviewed):
raise HTTPException(status_code=409, detail=changed)
# Its tools must still resolve — same check as create/update.
errors = await validate_definition_and_tools(current)
if errors:
raise HTTPException(status_code=422, detail=errors)
_refuse_unless_creator(current, request, get_owner(name))
# The check above may await the gateway, and chat may run in another
# process: switch on only if the row is still the revision validated.
switched = activate_if_unchanged(current)
if switched is None:
raise HTTPException(status_code=404, detail=f"Custom workflow {name!r} not found")
if not switched:
raise HTTPException(status_code=409, detail=changed)
elif not set_active(name, is_active):
raise HTTPException(status_code=404, detail=f"Custom workflow {name!r} not found")
defn = get_definition(name)
assert defn is not None
_sync_cadence(defn)
return defn.model_dump()
@router.get("/workflows/{name}")
async def get_workflow_meta(name: str) -> dict[str, Any]:
try:
workflow = get_workflow(name)
except KeyError as e:
raise HTTPException(status_code=404, detail=str(e)) from e
return workflow.meta().model_dump()
@router.get("/workflows/{name}/sample")
async def get_workflow_sample(name: str) -> dict[str, Any]:
"""Realistic sample inputs for the 'Load sample run' button.
Returns 404 if the workflow does not exist or has no sample defined.
"""
try:
workflow = get_workflow(name)
except KeyError as e:
raise HTTPException(status_code=404, detail=str(e)) from e
sample = workflow.sample_inputs()
if sample is None:
raise HTTPException(
status_code=404, detail=f"Workflow {name!r} does not expose a sample"
)
return {"workflow": name, "inputs": sample}
@router.post("/workflows/{name}/runs")
async def start_workflow_run(name: str, request: Request) -> StreamingResponse:
"""Start a workflow run. Streams progress events as Server-Sent Events.
Each SSE event is a JSON-encoded `WorkflowEvent`. The final event in
a successful run is `{"type": "done", "run_id": "..."}`. A workflow that
is the principal's alone in the workspace's mode is a 403 for anyone
else (`refuse_principal_only_run`), before any run row is created.
"""
try:
workflow = get_workflow(name)
except KeyError as e:
raise HTTPException(status_code=404, detail=str(e)) from e
from openexecutive.memory.workspace_settings import read_stored_mode
refuse_principal_only_run(request, workflow, read_stored_mode(), surface="jobs")
try:
payload = await request.json()
except json.JSONDecodeError as e:
raise HTTPException(status_code=400, detail=f"Invalid JSON: {e}") from e
input_model_cls = workflow.input_model()
try:
inputs = input_model_cls.model_validate(payload)
except ValidationError as e:
raise HTTPException(status_code=422, detail=e.errors()) from e
run_id = uuid.uuid4().hex
title = _derive_title(workflow.name, payload)
# Started by hand: the run and its output are the caller's alone. Fails
# closed: a caller who can't be placed on the roster starts nothing that
# would otherwise land in the team's history.
try:
owner_person_id = _caller_person_id(request)
except Exception as exc:
logger.exception("workflow run: caller lookup failed — refusing the run")
raise HTTPException(status_code=503, detail="Couldn't read the People list.") from exc
if owner_person_id is None and api_caller.caller(request).email:
raise HTTPException(
status_code=403, detail="Runs are kept for people on the People list."
)
from openexecutive.delegation.workflow_reads import owns_runs, run_refusal
reader = owns_runs(workflow.name)
if reader is not None:
# Its creator, verified as a save of it is: the stream carries what
# their mail said.
refused = run_refusal(reader, owner_person_id, api_caller.caller(request))
if refused is not None:
raise HTTPException(status_code=403, detail=refused)
from openexecutive.orchestrator.artifact_records import (
NOBODY,
pinned_viewer,
viewer_for_person,
)
run_viewer = viewer_for_person(owner_person_id) if owner_person_id is not None else NOBODY
create_run(
run_id=run_id,
workflow_name=workflow.name,
title=title,
inputs=payload,
owner_person_id=owner_person_id,
)
store = getattr(request.app.state, "store", None)
if store is None:
raise HTTPException(status_code=503, detail="Knowledge store not initialized")
async def event_stream():
t_start = time.monotonic()
artifact: str = ""
private_to_principal = False
paused = False
try:
# Tell the client which run_id to track and what the planned steps are.
yield _sse({
"type": "run_created",
"run_id": run_id,
"title": title,
"workflow": workflow.name,
"steps": [s.model_dump() for s in workflow.steps()],
})
async for event in workflow.run(inputs=inputs, store=store):
# An approval-gate step yields a WaitForHumanEvent (not a
# WorkflowEvent): checkpoint the run, tell the client it is
# paused, and stop. The resumer applies the timeout policy;
# the inbound resolver records the human's reply.
if isinstance(event, WaitForHumanEvent):
# Delivery + checkpoint live in `workflows.gate` so this
# route, the chat tool and the resumer cannot drift apart.
pause = await checkpoint_gate(
run_id=run_id,
event=event,
workflow_title=workflow.title,
)
paused = True
yield _sse({
"type": "awaiting_human",
"run_id": run_id,
"person_id": pause.person_id,
"question": pause.question,
"awaiting_until": pause.awaiting_until.isoformat(),
# "sent" / "self" / "suppressed" / "alerted" / "failed" —
# the client must not say "waiting on them" when the
# question never reached them.
"delivery": pause.delivery,
# True when the run will continue by itself once the
# answer lands; False for a pause-only gate.
"resumable": pause.resumable,
# No `done` or `error` follows a pause — this IS the
# last frame. Without it a client waiting for a
# terminal event just sees the connection close and
# spins on the gate step forever.
"terminal": True,
})
break
event_dict = event.model_dump()
if event.type == "artifact" and event.content is not None:
artifact = event.content
elif event.type == "result" and event.data and event.data.get("private_to_principal"):
private_to_principal = True
yield _sse(event_dict)
if paused:
# Run left in 'awaiting_human'; the awaiting_human frame above
# was terminal, so nothing more is emitted.
pass
elif artifact:
# Run history is readable by everyone signed in; a run that
# drew on what is private to the principal keeps a stand-in
# (the stream above already carried the text to this caller).
complete_run(
run_id=run_id,
artifact=stored_artifact(artifact, private_to_principal=private_to_principal),
)
yield _sse({"type": "done", "run_id": run_id})
else:
fail_run(run_id=run_id, error="Workflow finished without producing an artifact")
yield _sse({
"type": "error",
"run_id": run_id,
"message": "Workflow finished without producing an artifact",
})
except Exception as exc: # noqa: BLE001 — must report any failure to the client
logger.exception("workflow.run_failed run_id=%s workflow=%s", run_id, workflow.name)
# NOT after a successful checkpoint. `fail_run` has no status
# guard, so failing here would overwrite 'awaiting_human' with
# 'error' and destroy the resume payload — for something as
# ordinary as the client disconnecting while we yield the frame.
# The run is safely parked; only the stream broke.
if not paused:
fail_run(run_id=run_id, error=str(exc))
yield _sse({"type": "error", "run_id": run_id, "message": str(exc)})
finally:
logger.info(
"workflow.run_complete run_id=%s workflow=%s duration_s=%.2f",
run_id,
workflow.name,
time.monotonic() - t_start,
)
async def owned_stream():
# The run's steps read and draft as its owner (nobody for a team
# run), so no one else's documents reach its output.
from openexecutive.delegation.workflow_reads import private_run
with pinned_viewer(run_viewer), private_run(workflow.name):
async for chunk in event_stream():
yield chunk
return StreamingResponse(
owned_stream(),
media_type="text/event-stream",
headers={
"Cache-Control": "no-cache",
"X-Accel-Buffering": "no", # disable nginx buffering for SSE
},
)
# -----------------------------------------------------------------------------
# Helpers
# -----------------------------------------------------------------------------
PRINCIPAL_ONLY_DETAIL = "Only the principal can run this workflow."
def refuse_principal_only_run(
request: Request,
workflow: Any,
mode: str | None,
*,
surface: str,
detail: str = PRINCIPAL_ONLY_DETAIL,
extra: dict[str, Any] | None = None,
) -> None:
"""Raise 403 unless this web caller may start ``workflow`` in ``mode``.
This decides who may start (or, from an eval, trigger) a run, not who
may read one: a stored run and its artifact are read under the
``/workflows/runs`` rules like any other run. A workflow whose
``principal_only_modes`` holds the mode it would run in (the weekly
review in both modes, the morning brief in solo) may be started over
HTTP only by the principal (``_caller_is_the_principal``), as
``run_workflow`` allows in chat. ``mode`` None (unreadable) counts as
principal-only. The refusal is audited like the chat tool's, and
``detail`` does not spell out the rule.
"""
from openexecutive.workflows.base import principal_only_in
if not principal_only_in(workflow, mode):
return
if _caller_is_the_principal(request):
return
from openexecutive.api.routes.chat import _resolve_caller_person_id
from openexecutive.audit import log_event as audit_log
name = str(getattr(workflow, "name", "") or "")
try:
# For the audit row only; the refusal stands whatever this reads.
caller_person_id = _resolve_caller_person_id(request)
except Exception:
caller_person_id = None
audit_log(
"tool_invocation",
f"run_workflow {name} refused over HTTP ({surface}): not the principal",
actor=api_caller.actor(request),
details={
"tool": "run_workflow",
"kind": "write",
"ok": False,
"workflow": name,
"refused": True,
"workspace_mode": mode or "unknown",
"caller_person_id": caller_person_id,
"surface": surface,
**(extra or {}),
},
)
raise HTTPException(status_code=403, detail=detail)
def _caller_is_the_principal(request: Request) -> bool:
"""Whether this web caller is the principal, for starting a principal-only
run.
Stricter than ``chat._caller_is_principal_or_unclaimed`` (the
``PUT /workspace`` rule, which is unchanged): nobody gets in because no
principal is on the roster. That happens after the old principal is
archived to re-run onboarding, or when the roster was filled in before
anyone was flagged, and teammates can be signed in then. A request with
no ``x-caller-email`` is the principal (the CLI, local login, a direct
call behind the shared secret; the UI proxy stamps every other session's
email), so it passes without a roster read. Otherwise the email must be
the principal's own, on an entry that is not archived. Fails closed: a
roster that cannot be read answers no.
"""
who = api_caller.caller(request)
if who.defaults_to_principal:
return True
if not who.email: # a verified service call is never the principal
return False
from openexecutive.api.routes.chat import _resolve_caller_person_id
from openexecutive.people.store import is_principal_or_self
try:
return is_principal_or_self(_resolve_caller_person_id(request), None)
except Exception:
logger.exception("principal check failed — refusing the principal-only run")
return False
def _resume_progress(resume_state_json: str | None) -> dict[str, Any] | None:
"""The client-safe digest of a paused run's resume payload.
Enough for the UI to mark which steps are already done and which one is
waiting; none of the step text itself.
"""
if not resume_state_json:
return None
try:
state = json.loads(resume_state_json)
except (json.JSONDecodeError, TypeError):
return None
if not isinstance(state, dict):
return None
outputs = state.get("outputs")
return {
"gate_step_id": str(state.get("gate_step_id") or ""),
"completed_step_ids": list(outputs) if isinstance(outputs, dict) else [],
}
def _sse(payload: dict[str, Any]) -> str:
return f"data: {json.dumps(payload)}\n\n"
async def _parse_definition(request: Request) -> DynamicWorkflowDef:
"""Parse + shape-validate a DynamicWorkflowDef from a request body."""
try:
payload = await request.json()
except json.JSONDecodeError as e:
raise HTTPException(status_code=400, detail=f"Invalid JSON: {e}") from e
try:
return DynamicWorkflowDef.model_validate(payload)
except ValidationError as e:
raise HTTPException(status_code=422, detail=e.errors()) from e
def _sync_cadence(defn: DynamicWorkflowDef) -> None:
"""Reconcile the scheduler rows for a definition's cadence.
Cancels any existing pending dynamic_workflow rows for this workflow, then
enqueues the next occurrence if the (active) definition has a cadence. Used
on create/update/activate so the schedule always matches the stored def.
"""
from openexecutive.workflows.dynamic_cadence import (
cancel_cadence_rows,
schedule_dynamic_workflow_cadence,
)
cancel_cadence_rows(defn.name)
if defn.is_active and defn.cadence:
schedule_dynamic_workflow_cadence(defn)
_TITLE_MAX = 80
def _derive_title(workflow_name: str, payload: dict[str, Any]) -> str:
"""Best-effort short title for a run, surfaced in lists."""
# Resolve via get_workflow (not WORKFLOW_REGISTRY) so dynamic, user-created
# workflows get a real title instead of a KeyError.
try:
workflow = get_workflow(workflow_name)
except KeyError:
return workflow_name
# Prefer a payload field that looks like a period/quarter label.
for field in ("quarter_label", "period", "title", "topic"):
if field in payload and payload[field]:
base = f"{workflow.title} — {payload[field]}"
return base[:_TITLE_MAX]
return workflow.title