@agimon-ai/po-workflow

Discover, launch, monitor, control, and recover asynchronous Po workflows.

Part of the Po distribution.

This package owns the workflow engine and the workflow-mcp CLI (po-workflow-mcp is an alias). Workflow files describe job dependencies and host-executed steps, while Po provides session-scoped tools.

Alpha: workflow and recovery contracts may change between releases.

Requirements

• Node.js 24 or newer

Install

The seeded modes.yaml selects Workflow in default.packages. Keep it there or select it through a layer; its tools remain inactive until Workflow mode is enabled.

Define a workflow

Create a *.workflow.yml file:

name: verify

jobs:
  test:
    steps:
      - name: Run tests
        run: pnpm test

  summarize:
    needs: test
    steps:
      - name: Record result
        run: node scripts/write-verification-summary.mjs

run commands execute on the host with the workflow process's environment and privileges. There is no VM, container, or sandbox. Review workflow files as executable code. Runner-specific interactiveRun mappings are available for commands that require a TTY.

A step can also declare runConfig (major mode, minor modes, profile, domains, model, thinking) and customRun (a prompt). Launched from the Po server, a customRun step runs as a child session of the launching session with those settings, until the agent has recorded what the step needs, and run and interactiveRun steps each get their own RMUX pane. Each run keeps its engine log in engine.log in its run directory. See docs/automation.md for the full contract and the CLI fallback.

Launch and monitor

Core tools are:

• list_workflows: discover workflows.
• launch_workflow: register and start an asynchronous run.
• workflow_run: inspect or control a run through supported actions.
• workflow_tools (server/web sessions): read failed-run recovery evidence or resume the existing run.

Launch returns after the run is registered, not after all jobs complete. Use status for progress and wait for a completion notification.

Storage, concurrency, and lifecycle

Registry data defaults to $HOME/.workflow-mcp; set WORKFLOW_MCP_HOME to relocate it. Persisted records contain workflow and run identity, job and step state, ownership, output locations, and recovery evidence. The default concurrency ceiling is five runs.

Runs launched through a terminal host such as tmux or cmux can have a different lifetime and remain manageable from the CLI. When Team is loaded, Workflow contributes active session runs through Team's po/background-work service. That contribution reconnects after Team is replaced and is removed when Workflow unloads. Reconciliation distinguishes stale registry records from live processes; do not assume every run outlives its parent session.

Each workflow or repair step can launch commands and model-backed agents, consuming provider quota and repeating external side effects.

Recovery

Recovery is available only for records in a terminal failure state. A recovery claim atomically adopts the eligible failure, validates the evidence, and transfers ownership to the replay session. Live controls remain scoped to the owning session. Recovery does not launch a second copy beside a still-running job and does not guarantee that parent-session work survives shutdown.

The package publishes workflow-recovery, po-author-workflow for writing workflow definitions, and po-use-workflow for launching, monitoring, and recovering runs while Workflow mode is active. Deactivating Workflow mode hides them; cached files may remain.

Workflow sessions

In a server (web cockpit) session, a launch does not run in the session that asked for it. The session creates a child workflow session (provenance workflow-session), nested under it in the rail, and hands it the launch. The workflow session owns the run (PI_SESSION_ID), runs its step sessions, and has Workflow mode on, so its agent can troubleshoot and recover the run. The run's environment also carries PO_WORKFLOW_LAUNCHER_SESSION_ID, naming the launching session, which lists the run in its Activity group, is told when it ends, and may read its status.

• The workflow session's rail row shows the run (workflow · build › test · 4m, or a failure or pause marked like a pending question) through the host's per-session activity line.
• Success is posted without starting a turn. Failure wakes the workflow owner for local diagnosis; the launcher receives a notification only. The owner gets a live brief on every turn.
• After a success, a workflow session nobody interacted with asks its launcher to release it, and it becomes stopped · open to wake. A session whose run failed or paused, or whose agent you prompted, stays live until you remove it. Removing or restarting a live workflow session stops its run.
• Recovery is refused from any session other than the owner while the owner is live.

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint

Maintained by Agimon.

Web cockpit plugin

The .web routed files under src/extensions/workspaces/sessions/(frontend) are this package's Po web cockpit plugin: the workflow dock face beside Activity and Context (the owned run's jobs, active steps and artifacts, each opening its own tab), the workflow catalog and launch dialog in the overlay slot, the Activity group's run rows (a handed-off run opens its workflow session), their stores, and the workflow_runs session channel, compiled into the cockpit bundle by po-web's build. Each surface keeps its components in a colocated _components folder and its stores and helpers in _lib. The hub-side data source lives in the package's backend API and reads the workflow registry (run.json plus progress.ndjson) exactly as the engine writes it. The poServer and poWeb blocks in package.json declare the backend and browser contributions.

Upgrading from the separate engine

The engine now ships inside @agimon-ai/po-workflow. Both workflow-mcp and po-workflow-mcp invoke that package's CLI. Storage paths and registry records are unchanged.

Let active runs finish before replacing an installation, or retain their exact old Node and CLI payloads until they finish. A run-local bin/workflow-mcp launcher contains absolute paths to the engine that created it. Never rewrite a live launcher or hot-swap its engine.

In repositories with canonical .po/hooks.yaml, replace the old package's CLI path with node_modules/@agimon-ai/po-workflow/dist/cli.mjs, then regenerate the frontend settings with that repository's hook emitter. Installation alone does not migrate existing hook registries.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

Native execution contract

Agent steps require an effective runConfig.majorMode; delegated workflows require top-level runConfig.majorMode before their owner child is created. Selection projects major mode, minor modes, profile and domains, adding the workflow minor mode once. subagentModel and subagentThinking set Team preferences independently of the step model.

The native host requires execution-state inspection before creating agent steps. After settlement it waits for idle, no pending messages and a known background snapshot without core holds or holding-provider errors before checking decisions. Unknown ownership waits closed without consuming reminders; stops interrupt reads and retry delays. Running commands stop holding an inline step after five idle minutes, but its decision gate still runs before session release.

Delegated successes are informational. Errors wake the workflow owner through durable custom-message admission; the launcher gets an error notification, not an agent-waking failure completion. Diagnosis stays local. Recovery, pause, resume and stop are request-driven. User-requested stops do not trigger diagnosis or automatic restart.