Cpf Workflow Runner

cpf-workflow-runner

Run checkpointflow workflows interactively, handling pause/resume cycles.

Core concept: Audience-driven dispatch

Checkpointflow workflows pause at await_event steps. Each pause has an audience field in the envelope's wait block that tells you who should act:

• audience: "agent" — The prompt is your work assignment. Do the work (read code, write files, run tools), produce JSON matching input_schema, and resume immediately. Never present agent pauses to the user.
• audience: "user" — Present the prompt and collect input from the user via structured prompts, then resume with their answers.

This is the only dispatch you need. The envelope tells you everything — no need to read the workflow YAML to figure out what to do.

Agent pause example

{
  "wait": {
    "audience": "agent",
    "event_name": "codebase_analysis",
    "prompt": "Analyze the codebase for feature \"run-delete\" in area \"gui\".\nScan src/checkpointflow/gui/ and identify source files, tests, dependencies...",
    "input_schema": {
      "type": "object",
      "required": ["area", "source_dir", "notes"],
      "properties": {
        "area": { "type": "string" },
        "source_dir": { "type": "string" },
        "notes": { "type": "string" }
      }
    }
  }
}

When you see this:

1. Read the prompt — it describes exactly what to do
2. Do the work (read files, explore code, run tools, etc.)
3. Build JSON matching input_schema with your real findings
4. Resume immediately: cpf resume --run-id <id> --event codebase_analysis --input '<json>'

User pause example

{
  "wait": {
    "audience": "user",
    "event_name": "scope_choice",
    "prompt": "Feature: run-delete\nHow should we scope this?\n- full: Complete implementation...\n- minimal: Core logic only...",
    "input_schema": {
      "type": "object",
      "required": ["scope"],
      "properties": {
        "scope": { "type": "string", "enum": ["full", "minimal", "spike", "cancel"] }
      }
    }
  }
}

When you see this:

1. Present the prompt context to the user
2. Collect their input via structured prompts
3. Resume: cpf resume --run-id <id> --event scope_choice --input '{"scope": "full"}'

Critical: Collect input through structured prompts, not chat

Every time the workflow needs input from the user — whether collecting workflow inputs before cpf run, gathering event data at an await_event pause, or confirming a cancellation — present structured choices using whatever interactive prompt tool is available in your environment (e.g., a question/answer UI, a selection picker, a form). The user should experience the workflow as a guided flow where they pick options and provide values through structured prompts, not by typing free-form messages into chat.

Do not say "what would you like to do?" and wait for a text reply. Always present choices and collect input through a structured prompt tool.

Running a workflow

Step 1: Discover and understand the flow

Use cpf flows to list available workflows, then cpf flows --detail <id> to see everything about a specific flow — description, required/optional inputs with types and descriptions, step overview, and a ready-to-use run command:

cpf flows                        # List all available workflows
cpf flows --detail <id>          # Full detail: inputs, steps, run command

The detail output tells you exactly what inputs to collect and gives you the cpf run command template. No need to read the workflow YAML.

Step 2: Collect inputs and execute

Use the inputs section from cpf flows --detail to collect values from the user via structured prompts. Read the description field on each input — it explains what the value should be and often includes examples or hints (e.g., "Directory containing the tools/ subdirectory").

For inputs you can infer from context, do so without asking:

• repo_dir → current working directory
• artifact_dir → create a temp directory
• author → git config user.name
• Paths referencing the current project → resolve from the working directory

Only prompt the user for inputs that are genuinely ambiguous. For each prompted input, build options using this priority:

1. enum values → one option per enum value (the user picks one)
2. type: boolean → two options: "Yes" / "No"
3. examples array → one option per example value (user picks one or types custom)
4. No examples → craft 2 realistic example values from the description

Never create placeholder options like "Type value" or "Enter value". Every option should be a real, plausible value the user might choose.

Then run:

cpf run -f <path> --input '<json>'

Parse the JSON envelope from stdout. The ok, status, and exit_code fields tell you what happened.

Step 3: Handle the result

Based on exit_code:

Interactive loop (await_event handling)

This is the core of the skill. When a workflow pauses (exit code 40), the envelope contains a wait block. Dispatch on wait.audience:

Agent audience (wait.audience == "agent")

The prompt is your work assignment. Do not present it to the user.

1. Read wait.prompt — it describes the work to do, with full context from previous steps already interpolated in.
2. Do the work — read code, write files, run tools, explore the codebase — whatever the prompt asks for.
3. Build event JSON matching wait.input_schema with your real results.
4. Resume immediately:

   cpf resume --run-id <run_id> --event <event_name> --input '<event_json>'
   

5. Parse the new envelope and loop back.

User audience (wait.audience == "user")

Present the checkpoint to the user and collect their input.

1. Read the wait block — extract prompt, input_schema, event_name, and run_id.

2. Collect input — map each field in input_schema to a structured prompt using the same option-building rules from Step 2 above.

   Multiple fields: If input_schema has multiple required fields, ask them together in a single prompt call when possible. Optional fields can be asked in a follow-up or skipped.

   Use the prompt from the wait block as context when presenting the questions — it explains what the user is deciding on.

3. Build the event JSON from the user's answers. Map each answer back to the field name in input_schema. Make sure the result matches the schema types (strings stay strings, numbers get parsed).

4. Resume the workflow:

   cpf resume --run-id <run_id> --event <event_name> --input '<event_json>'
   

5. Parse the new envelope and loop back:

   • If exit code 0 → done, show result
   • If exit code 40 → another await_event, dispatch on audience again
   • If error → show it

Keep looping until the workflow completes, fails, or the user wants to stop.

Status and inspection

When the user asks about a run:

cpf status --run-id <run_id>    # Quick status check
cpf inspect --run-id <run_id>   # Full execution history

If the user doesn't remember the run ID, check recent output from previous commands in the conversation — the run_id is in every envelope.

Cancelling a run

When the user wants to cancel a waiting run:

cpf cancel --run-id <run_id> --reason "<reason>"

Use a structured prompt to confirm before cancelling, and ask for a reason if not provided.

Web dashboard

Launch the GUI to browse workflows and runs visually:

cpf gui                    # opens http://localhost:8420
cpf gui --port 9000        # custom port

Never modify workflow files during an active run

cpf checksums the workflow YAML when a run starts and verifies it on every resume. If you edit the workflow file while a run is in progress, the next cpf resume will fail with ERR_VALIDATION_WORKFLOW ("Workflow file has changed since the run started"). This forces you to abandon the run and start over.

If you need to fix the workflow YAML mid-session, finish or cancel the active run first.

Parallel agents with sequential callbacks

Some workflows have multiple sequential await_event steps that are all audience: "agent" — for example, 4 specialist reviews that each get their own callback. The optimal pattern:

1. Launch all agents in parallel (background agents) when you first see the sequence.
2. Write event JSON files as each agent completes — don't hold results in memory.
3. Resume callbacks sequentially as the workflow reaches each one, using the pre-written files.

Agents may finish out of order. That's fine — queue their results in files and feed them to the workflow in the order it expects.

Windows path handling

On Windows, backslashes in file paths break inline JSON (--input '{"file": "C:\\..."}' causes JSON parse errors). Two options:

• Use @file references (preferred): write event JSON to a file, then --input @path/to/event.json
• Use forward slashes in inline JSON: "C:/Users/thoma/..." — cpf and Python accept these on Windows

When using @file, make sure you know the actual Windows path — different tools may resolve /tmp/ to different locations (e.g., C:\tmp\ vs C:\Users\...\AppData\Local\Temp\).

Tips

• Agent pauses are auto-resume — never present them to the user. Do the work silently and resume.
• The prompt has full context via interpolation — you do not need to read the workflow YAML to understand the work. The prompt already references previous step outputs.
• If you can't complete agent work, still provide valid JSON with honest status fields (e.g., lint_ok: false, implemented: false). The workflow's branching logic handles failure paths.
• Always parse the JSON envelope — don't rely on exit codes alone. The envelope has richer information.
• Exit code 40 is not an error. Don't treat it as a failure or apologize for it.
• When showing results to the user, format them nicely — don't dump raw JSON unless they ask for it.
• If a workflow has multiple sequential await_event steps (like a quiz), keep the loop going smoothly without re-explaining the process each time.
• The --input flag accepts either inline JSON ('{"key": "value"}') or a file reference (@path/to/file.json). Prefer @file for any input containing file paths or long strings.