@agimon-ai/po-workflow 0.0.0-alpha.0

package/src/prompts/po-author-workflow/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: po-author-workflow
+description: Author Po workflow definitions. Use when creating or changing a *.workflow.yml graph, arranging job dependencies and host-executed steps, or deciding how a command requiring a TTY should run.
+---
+
+# Author Po workflows
+
+Create a `*.workflow.yml` file and keep its graph explicit:
+
+```yaml
+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
+```
+
+`needs` expresses job ordering. Keep steps small enough that failure evidence identifies the command that needs attention. Use runner-specific `interactiveRun` configuration when a command genuinely requires a TTY.
+
+For an agent step, declare the command once under `commands` (usually in an imported file) and let the step name it. A command is a Liquid template; `inProcess: true` lets the Po server run it as a child session instead of the shell, and the CLI and the TUI run the rendered command:
+
+```yaml
+imports: [commands.yml]
+choices:
+  default: { model: openai-codex/gpt-6-sol, thinking: medium }
+jobs:
+  develop:
+    steps:
+      - name: Develop
+        runConfig: { majorMode: dev, domains: [engineering] }
+        systemPrompt: ${{ env.JOB_SYSTEM_PROMPT }}
+        prompt: ${{ env.WORKFLOW_CONTEXT }}
+        interactiveRun: [{ command: po }, { command: terminal }]
+```
+
+`po` and `terminal` are the commands `commands.yml` declares; a step can only name a declared command. `runConfig` takes `majorMode`, `minorModes`, `profile`, `domains`, `model`, and `thinking`, plus any key the template reads; any other key fails the step, so a typo such as `majormode` never runs on workspace defaults. `choices` compose model and thinking, with per-command overrides such as `terminal: { model: openai-codex/gpt-6-luna }`; a step can pin `choice:`, and a launch picks `command=` and `choice=` for the rest. Templates must quote prompts with `{{ prompt | shell }}`.
+
+Before committing a workflow, run `workflow-mcp doctor <file-or-directory> --run-config-keys majorMode,minorModes,profile,domains,model,thinking` and fix every error it reports; the Po server refuses to launch a workflow with errors.
+
+An agent step ends by recording its outcome: `workflow-mcp step complete`, `step fix --restart-from <job> --reason ...`, or `step fail --reason ...`. The engine puts the instructions in the step's system prompt, and an agent that stops without deciding is sent back until it does. Write repair contracts in those terms, not as `fix.md`.
+
+What a step or job must leave is held the same way. A step's `artifacts` must be written during the step. A job must be the last to have written each run-directory entry it produces (`produced-by`): an entry an earlier job wrote must be written again, while a retry or a job that skips work it already did keeps its own output, and removing a file counts. `writes.ndjson` in the run directory records which job and step last wrote each entry. An agent step that ends its job is sent back until those entries are written, and the job fails when one was not. List a job under `produced-by` only when it writes the entry in every run. Write a `description` for every entry: the reminder tells the agent what the file holds from it.
+
+Put independent checks in a `parallel` group. A `run:` check with `restart-from: <job>` turns a failure into a fix request, and every fix request of the job merges into one repair, so one loop back fixes all of them. Keep steps that edit files out of a group: its steps share the checkout.
+
+Every `run` command executes on the workflow host with that process's environment and privileges. There is no VM, container, or sandbox. Review workflow changes as executable code, avoid embedding secrets, and make retry-sensitive external side effects explicit.
+
+Before relying on the graph, enable Workflow mode, discover it with `list_workflows`, launch a disposable run, and inspect job and step status with `workflow_run`. Test a failure path when recovery behavior matters.
+
+## 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.
+
+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.

package/src/prompts/po-use-workflow/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: po-use-workflow
+description: Use Po workflows. Use when discovering or launching workflows, monitoring or controlling asynchronous runs, interpreting terminal notifications, or recovering a failed run safely.
+---
+
+# Use Po workflows
+
+Enable model-visible Workflow tools with `SPC w e`. In a non-interactive harness, set `WORKFLOW_MCP_MODE=on` before starting the session.
+
+Use the tools in this order:
+
+1. `list_workflows` discovers available workflow definitions.
+2. `launch_workflow` registers and starts a run. A successful launch response does not mean the jobs have finished. For a workflow whose agent steps name commands, pass `command` (such as `po` or `claude`) and `choice` (a declared model choice); both default to what the workflow lists first and to `default`.
+3. `workflow_run` inspects status, follows progress, or applies a supported control action. In server/web sessions it supports status, pause, resume, and stop; `workflow_tools` carries `recovery-evidence` and `recover`.
+4. Wait for a terminal notification and verify the final job and step states before reporting success.
+
+In the TUI, `SPC w l` lists the repository's workflows and launches the one under the cursor with `r`, `SPC w r` inspects this session's runs, and `SPC w c` opens recovery. The root session can launch. Child sessions can inspect the catalog but do not receive an unrestricted workflow factory.
+
+Recover only a record already in a terminal failure state. Inspect its evidence first, then use the package's `workflow-recovery` runtime skill for the repair workflow. Recovery atomically adopts eligible work, but it cannot make non-idempotent external side effects safe or guarantee that in-process work survives parent shutdown.
+
+Workflow steps and model-backed repair can consume provider quota and repeat external effects. Do not relaunch or replay a run merely because progress is quiet. Inspect live ownership and persisted state first.

package/src/types/webWorkflowTerminal.ts

@@ -0,0 +1,114 @@
+/**
+ * The wire contract between this package's hub API and its cockpit client:
+ * one run's terminal, and the files its run directory holds.
+ *
+ * Both halves of the cockpit import these names, so the route strings and the
+ * event names live here rather than being spelled twice.
+ */
+
+/**
+ * Segment this package's API is mounted under, below /api/plugins/.
+ *
+ * The same word names `src/extensions/(backend)/api/workflow/`, which is where
+ * the build reads the mount for the browser's client, so the two cannot drift.
+ * The routes themselves are declared in `apiRoutes.ts`.
+ */
+export const WORKFLOW_API_BASE_PATH = 'workflow';
+
+/** The SSE event name the screen stream writes. */
+export const WORKFLOW_SCREEN_EVENT = 'screen';
+
+/** What a surface may do with one run's terminal, and why anything is missing. */
+export interface WorkflowTerminalCapabilitiesView {
+  readable: boolean;
+  writable: boolean;
+  resizable: boolean;
+  reason?: string;
+}
+
+/** One frame of a run's terminal, as the stream pushes it. */
+export interface WorkflowScreenEvent {
+  /** The visible screen, newest line last, carrying the colour the run printed. */
+  lines: string[];
+  capabilities: WorkflowTerminalCapabilitiesView;
+  /** True once the run has settled, after which the stream ends. */
+  ended?: boolean;
+}
+
+/** Answer to taking or releasing the keyboard for one run. */
+export interface WorkflowControlResponse {
+  /** True when this caller now holds the keyboard. */
+  held: boolean;
+  /** The token later writes must carry; absent when control was refused or released. */
+  token?: string;
+  /** Why control was refused, worded for a reader. */
+  reason?: string;
+}
+
+/** Answer after a settled run and its directory have been permanently removed. */
+export interface WorkflowDeleteResponse {
+  deleted: true;
+}
+
+/** Answer once a stop request is recorded; the engine ends the run at its next check. */
+export interface WorkflowStopResponse {
+  requested: true;
+}
+
+/** Answer once guidance reached the running step's agent session. */
+export interface WorkflowSteerResponse {
+  delivered: true;
+}
+
+/** What launching a workflow into a session answered, as the launch tool reports it. */
+export interface WorkflowLaunchResponse {
+  text: string;
+  isError?: boolean;
+}
+
+/** How a declared run-directory entry compares with what is on disk. */
+export type WorkflowArtifactState = 'written' | 'empty' | 'pending' | 'unreadable';
+
+/** One file or directory in a run's own folder. */
+export interface WorkflowArtifactView {
+  /** Path relative to the run directory, which is also the read route's parameter. */
+  path: string;
+  kind: 'file' | 'directory';
+  /** What the workflow says this file is for; empty for a file it never declared. */
+  description: string;
+  /** The jobs the workflow says write it. */
+  producedBy: string[];
+  /** True when the workflow's run-directory block names this entry. */
+  declared: boolean;
+  state: WorkflowArtifactState;
+  /** Bytes on disk, absent until the file exists. */
+  size?: number;
+  /** ISO 8601 of the last write, absent until the file exists. */
+  modifiedAt?: string;
+}
+
+export interface WorkflowArtifactsResponse {
+  /** Absolute path of the run's own directory, which the reader may want to open. */
+  runDir: string;
+  /** What the workflow says the directory is for. */
+  description: string;
+  artifacts: WorkflowArtifactView[];
+}
+
+/** One artifact's metadata and optional text, as the viewer tab reads it. */
+export interface WorkflowArtifactContentResponse {
+  path: string;
+  size: number;
+  modifiedAt: string;
+  /** Media type inferred from the file extension by the trusted hub. Absent on older hubs. */
+  mimeType?: string;
+  /** Present for text formats; binary files are streamed from the raw route instead. */
+  text?: string;
+  /** True when textual content was longer than the reader's byte budget. */
+  truncated: boolean;
+}
+
+/** Acknowledges opening the registered run folder in Finder. */
+export interface WorkflowOpenRunDirectoryResponse {
+  opened: true;
+}

package/src/types/webWorkflows.ts

@@ -0,0 +1,208 @@
+/**
+ * Workflow run view types shared by this package's hub channel and its web
+ * plugin. The shapes mirror what the embedded workflow-mcp engine records;
+ * the cockpit renders them as 'workflow_runs' channel payloads.
+ */
+
+/** workflow-mcp's own stage vocabulary; the registry bucket a run record sits in. */
+export type WorkflowStage = 'running' | 'completed' | 'error';
+
+/** workflow-mcp's terminal outcome for a finished run. */
+export type WorkflowOutcome = 'success' | 'skipped' | 'failed' | 'interrupted';
+
+/** Recorded job/step states, plus pending entries from the workflow definition. */
+export type WorkflowProgressState =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'skipped'
+  | 'failed'
+  | 'pause_requested'
+  | 'paused'
+  | 'resumed';
+
+/** A customRun step ran as this child session. */
+export const STEP_SESSION_REF_KIND = 'session';
+/** A command step ran in this terminal pane. */
+export const STEP_PANE_REF_KIND = 'pane';
+
+/** Where a host executor ran a step: `session` for a customRun agent, `pane` for a command. */
+export interface WorkflowStepRefView {
+  kind: string;
+  id: string;
+  label?: string;
+}
+
+export interface WorkflowStepView {
+  name: string;
+  status: WorkflowProgressState;
+  /** Kept after the step ends, so a finished agent step still opens its conversation. */
+  ref?: WorkflowStepRefView;
+  /** Why the step is in its state, when the engine recorded one (e.g. a skip condition). */
+  reason?: string;
+  /** The parallel group the step ran in, beside the group's other steps. */
+  group?: string;
+  /** ISO 8601 of the step's first running event. */
+  startedAt?: string;
+  /** ISO 8601 of the step's terminal event. */
+  endedAt?: string;
+}
+
+/** 'pre' and 'post' are the engine's pseudo-jobs for its pre:/post: blocks. */
+export type WorkflowJobPhase = 'pre' | 'job' | 'post';
+
+export interface WorkflowJobView {
+  name: string;
+  phase: WorkflowJobPhase;
+  status: WorkflowProgressState;
+  reason?: string;
+  /** Position among the run's jobs, when the engine recorded one. */
+  index?: number;
+  total?: number;
+  startedAt?: string;
+  endedAt?: string;
+  steps: WorkflowStepView[];
+}
+
+/** The job and step a run is on right now; drives the NOW breadcrumb. */
+export interface WorkflowPosition {
+  job: string;
+  step?: string;
+  index?: number;
+  total?: number;
+}
+
+/**
+ * One workflow run of a session, read from workflow-mcp's registry: the
+ * run.json record plus the folded progress.ndjson job tree.
+ */
+export interface WorkflowRunView {
+  /** Engine generation identity, distinct from a reused run key. */
+  runId?: string;
+  /** Registry identity within its workspace; unique per workspace+stage. */
+  runKey: string;
+  workspace: string;
+  displayName: string;
+  workflowName?: string;
+  workflowPath: string;
+  stage: WorkflowStage;
+  outcome?: WorkflowOutcome;
+  /** Present while the engine is pausing or paused; absent for plain running. */
+  executionState?: 'running' | 'pause_requested' | 'paused' | 'resume_requested';
+  /** The prompt the run was launched with, when one was recorded. */
+  prompt?: string;
+  /** ISO 8601, from the run record. */
+  startedAt: string;
+  finishedAt?: string;
+  /** Failure cause with ANSI escapes stripped, present when the run errored. */
+  errorMessage?: string;
+  /** The job the engine blamed for the failure, when it recorded one. */
+  failedJob?: string;
+  /** True when reconciliation decided the recorded pid is no longer alive. */
+  stale?: boolean;
+  staleReason?: string;
+  worktreeBranch?: string;
+  /** The session that owns the run (its PI_SESSION_ID); absent on records that carry none. */
+  ownerSessionId?: string;
+  /** The session that launched the run into its own workflow session, when it was handed off. */
+  launcherSessionId?: string;
+  position?: WorkflowPosition;
+  jobs: WorkflowJobView[];
+}
+
+/** What the workflow runs channel publishes for one session. */
+export interface WorkflowRunsPayload {
+  runs: WorkflowRunView[];
+}
+
+export const WORKFLOW_RUNS_TYPE = 'workflow_runs';
+
+/**
+ * One workflow the session's directory can launch, as the catalog drawer
+ * lists it: the engine's own catalog entry plus the parsed detail the drawer
+ * unfolds and the launch dialog turns into fields.
+ */
+export interface WorkflowCatalogEntryView {
+  /** Absolute path, the row's stable identity. */
+  path: string;
+  relativePath: string;
+  name: string;
+  description: string;
+  tags: string[];
+  /** The trigger names the file declares, such as workflow_dispatch. */
+  triggers: string[];
+  inputs: WorkflowCatalogInputView[];
+  jobs: WorkflowCatalogJobView[];
+  artifacts: WorkflowCatalogArtifactView[];
+  /** Absent when the workflow names no runner map, which means any runner will do. */
+  runners?: string[];
+  /** Commands every templated step offers; absent when no step is templated. */
+  commands?: string[];
+  /** Declared model choices; `default` is used when a launch names none. */
+  choices?: string[];
+  /** Set when the file could not be parsed; the row shows this instead of guessing. */
+  error?: string;
+}
+
+export interface WorkflowCatalogInputView {
+  name: string;
+  description?: string;
+  required?: boolean;
+  default?: string;
+  type?: string;
+  options?: string[];
+}
+
+export interface WorkflowCatalogJobView {
+  name: string;
+  steps: string[];
+}
+
+export interface WorkflowCatalogArtifactView {
+  path: string;
+  kind: 'file' | 'directory';
+  description: string;
+  producedBy: string[];
+}
+
+/** What the catalog channel publishes for one session. */
+export interface WorkflowCatalogPayload {
+  /** The directory the catalog was read from, which is the session's own. */
+  cwd: string;
+  workflows: WorkflowCatalogEntryView[];
+  /** Present when the directory could not be read at all. */
+  warning?: string;
+}
+
+export const WORKFLOW_CATALOG_TYPE = 'workflow_catalog';
+
+export interface WorkflowInputSummary {
+  name: string;
+  description?: string;
+  required?: boolean;
+  default?: string;
+  options?: readonly string[];
+}
+
+export interface WorkflowJobSummary {
+  name: string;
+  steps: readonly string[];
+}
+
+/**
+ * What the detail pane shows for one workflow. `runners` is undefined when the
+ * workflow names no runner map at all, which is not the same as naming an empty
+ * one - see `compatibleRunners`.
+ */
+export interface WorkflowCatalogDetail {
+  triggers: readonly string[];
+  inputs: readonly WorkflowInputSummary[];
+  jobs: readonly WorkflowJobSummary[];
+  runners?: readonly string[];
+  /** Commands every templated step offers; absent when no step is templated. */
+  commands?: readonly string[];
+  /** Declared model choices. */
+  choices?: readonly string[];
+  /** Set when the file could not be parsed; the pane shows this instead of guessing. */
+  error?: string;
+}