pm_workflow

Use pm_workflow to validate or save definitions, start and inspect runs, record supported wait outcomes, and apply explicit recovery actions.

Call help before building automation against a running Valdr installation:

pm_workflow { action: "help" }
pm_workflow { action: "help", topic: "start" }

Passing topic with one action name returns guidance and examples for that action alone; omitting it (or passing "all") returns the full help payload.

Actions

Find a definition and version

Discover installed versions before starting a run:

pm_workflow {
  action: "list",
  workflowKey: "valdr-workflow.task.deliver",
  lifecycleStatus: "active",
  detail: "summary"
}

Use packKey, capabilityKey, or query to narrow a larger catalog; add latestOnly: true when you need only the newest version per key. Lists support limit and cursor. Read one exact definition with get using workflowKey plus version, or use its contentHash. The get action also supports capabilityKey and the lifecycleStatus filter.

Validate a definition

validate accepts one of definitionJson, definitionYaml, or capabilityKey. Execution-ready validation is strict automatically:

pm_workflow {
  action: "validate",
  definitionYaml: "schemaVersion: 1.0\nworkflow:\n  key: example.simple\n  name: Example Simple\n  version: 0.1.0\n  start:\n    mode: manual\n  inputs: {}\n  steps: []"
}

Invalid content returns diagnostics without saving a definition.

Save a definition

save_definition accepts the same JSON or YAML source and applies strict validation automatically:

pm_workflow {
  action: "save_definition",
  definitionYaml: "<workflow YAML>"
}

Create a new version when behavior changes. If you intentionally update a definition at the same key and version, first reload it and supply overwrite: true with its current expectedContentHash. Keep its existing packKey and sourceRelpath values. Valdr rejects an outdated hash or changed source fields to prevent accidental overwrites.

You can also overwrite a definition installed from a pack, but it becomes a local definition. Prefer updating the source pack so a later import does not reintroduce the old definition. See Version changes deliberately for how edits affect existing runs, reruns, and manual Command retries.

Retire or restore a definition

Retire a workflow version when you no longer want it available for new runs. Its past runs remain available. An MCP client can preview what would prevent retirement:

pm_workflow {
  action: "delete_definition",
  workflowKey: "example.task.delivery-review",
  version: "0.1.0",
  expectedContentHash: "sha256:<content-hash>",
  preview: true
}

Valdr prevents retirement while another active workflow definition or an unfinished run depends on that version. Retired versions cannot start or rerun until restored.

To retire or restore a version, open the workflow catalog in Valdr UI. Choose Retire to remove it from active use. To bring it back, turn on Show retired and choose Restore. MCP clients can preview retirement; use the UI to make either change.

Test an unsaved definition

test_definition validates the supplied definition, starts a test run, and drives it until it reaches a wait or terminal state, or consumes its 50-transition test budget. It returns the durable run and step results without saving the definition to the catalog.

This is real execution: sessions can launch agents, commands and user tools run on the machine running Valdr, and steps can change data or publish work. Use validate when you only want diagnostics. A test run is retained in run history, but cannot be the source of rerun.

Provide one definition source, a clientRequestId, declared inputs, and any scope the workflow requires.

Start a run

Prefer selecting a workflow by key and version:

pm_workflow {
  action: "start",
  workflowKey: "example.task.delivery-review",
  version: "0.1.0",
  taskKey: "NOVA-42",
  actorHandle: "workflow-operator",
  inputs: {
    taskKey: "NOVA-42",
    executorHandle: "ember-executor",
    reviewerHandle: "sage-reviewer"
  },
  clientRequestId: "automation:start:01EXAMPLE"
}

The top-level taskKey selects the run’s optional association; inputs.taskKey supplies the declared workflow input. With no top-level task or project, declared taskKey or projectKey inputs can supply the association. Explicit step targets remain independent. See task and project targets for aliases, defaults, and project consistency.

contentHash is also available as an exact selector for automation that already recorded it. If both version and content hash are supplied, both must identify the same definition.

actorHandle must name a registered agent. If it is omitted and a step needs an actor, Valdr uses the registered pm agent.

Start, draft Test, and Rerun check inputs and any agent or provider-preset references known before the run starts. The same checks apply to MCP and UI calls. References calculated during the run are checked when their steps execute. Execution can still fail if a provider is disabled, credentials or a model are unavailable, the network is unreachable, the worktree is incompatible, or a session is already busy.

Reuse the same clientRequestId only when retrying the same start request after an interrupted response. Use a new request ID for a deliberately separate run.

Inspect and advance

Use get_run to read current status, steps, waits, declared results, evidence, and child workflows. The default response is compact — run status and loop progress only, which is the right shape for polling. Pass includeSteps: true, includeWaits: true, or includeChildren: true for the matching details, includeAcceptedInputs: true for accepted callback and gate evidence, includeDefinition: true for the exact definition revision used by the run, and includeDependencies: true for its selected child-workflow versions (useful before rerun).

Use list_runs for discovery; it supports workflow, task, project, context, status, parent/root, rootOnly, query, limit, and cursor filters. Use events for the timeline. Events omit payload bodies by default and support afterSeq or cursor, eventTypes, and limit up to 500; add includePayload: true only for targeted detail.

advance performs one ready transition:

pm_workflow {
  action: "advance",
  runUlid: "01EXAMPLERUN"
}

Repeat only while the returned run has ready work. Stop when it waits, blocks, fails, completes, or is cancelled.

Record callback input

Direct input is for an open await-condition step that exposes a callback token. It cannot be used to impersonate an operator at a human approval gate.

pm_workflow {
  action: "input",
  runUlid: "01EXAMPLERUN",
  stepKey: "await_executor",
  waitUlid: "01EXAMPLEWAIT",
  kind: "callback",
  origin: "agent_session",
  outcome: "executor_completed",
  sourceSessionUlid: "01EXAMPLESESSION",
  callbackToken: "<token returned for this wait>",
  clientRequestId: "agent:input:01EXAMPLE"
}

The outcome and any supplied task, review, or session references must match the open wait. Resolve human gates in Valdr UI using the authored decision controls.

Retry a step

Read the latest run detail first, then use the current attempt number shown for an eligible step:

pm_workflow {
  action: "retry_step",
  runUlid: "01EXAMPLERUN",
  stepKey: "load_task",
  expectedAttempt: 2,
  actorHandle: "workflow-operator",
  reason: "Retry after correcting the task reference.",
  clientRequestId: "automation:retry:01EXAMPLE"
}

Retrying creates another attempt and preserves the earlier history. Completed and cancelled runs are closed; failed runs remain retryable when the latest failed or blocked attempt has a safe error category. Valdr also rejects outdated attempt numbers. Authored retry.maxAttempts is a reported attempt count; it neither caps manual recovery nor schedules automatic retries or backoff.

For a Command step, read get_run with includeSteps: true and inspect commandRetryPreviewByStepKey[stepKey]. The preview shows expectedAttempt, the saved definition’s expectedContentHash, and changed Command fields. Environment changes list added, changed, or removed variable names. Review those settings, then pass the preview’s expectedContentHash with retry_step so Valdr rejects the retry if the settings have changed since your review. The retry can use updated command, cwd, timeoutSeconds, and env values; the step sequence, output mappings, and source session remain those of the original run.

Run again

rerun creates a separate run from a completed, failed, or cancelled root run:

pm_workflow {
  action: "rerun",
  sourceRunUlid: "01EXAMPLESOURCERUN",
  inputs: { validationCommand: "npm test" },
  clientRequestId: "automation:rerun:01EXAMPLE"
}

The new run uses the same workflow versions, task/project association, and context. Omit inputs to reuse the source run’s inputs; when you supply inputs, provide the complete declared input set for the new run. You can change declared taskKey and projectKey inputs without changing the run’s association; a declared contextRef remains fixed. To change the association or use updated workflow behavior, start a separate run with start.

Cancel or delete a run

Whole-run cancel stops workflow orchestration; see cancellation scope for which sessions and commands it stops. Active child runs are cancelled by default. cascade: false is accepted only when no active child runs exist.

To stop one running Command attempt without cancelling the workflow run, supply both stepKey and its current expectedAttempt. Do not supply cascade for a step-scoped cancellation:

pm_workflow {
  action: "cancel",
  runUlid: "01EXAMPLERUN",
  stepKey: "verify_change",
  expectedAttempt: 1,
  reason: "Stop the long-running validation command.",
  clientRequestId: "automation:stop-command:01EXAMPLE"
}

delete_run removes a root or child run tree only when every run in it is blocked, failed, completed, or cancelled. Pending, running, and waiting runs must be cancelled first. Valdr does not provide a restore action for deleted runs. Supply the run ULID, a registered actorHandle, a non-empty reason, and a clientRequestId; externally referenced child runs are rejected.

In Valdr UI, Delete run also deletes linked session records, events, transcripts, and session-owned worktrees by default. Select Keep linked sessions to preserve them before confirming. Direct pm_workflow delete_run removes workflow history only; session cleanup is a separate UI operation.

Handle detailed results carefully

get_run and events return compact records unless you opt into detail, so the default calls are already safe for routine polling. Request only the detail collections your automation needs, avoid logging callback tokens or sensitive agent output, and prefer declared workflow results for ordinary integrations.

Next step

Use the Workflow Steps reference to author supported nodes, or ask Verdandi to author, operate, or diagnose a workflow through the same MCP surface. Keep Workflow Troubleshooting nearby for recovery.