pm_automation

Use pm_automation to make recurring work repeatable from configuration. An agent can validate a declaration, preview its schedule, apply it, and inspect the resulting activity without recreating the rule by hand.

This reference covers declarations, MCP calls, update guards, checkpoint state, and recovery. Start with Automations for UI instructions and complete YAML examples.

Call shape and permissions

Every call uses action plus a nested params object:

pm_automation {
  action: "get",
  params: { key: "local.hourly-summary" }
}

Discover the tool through your connected MCP client’s tool list and input schema. pm_automation does not accept a help action. Your session must allow the automation actions it needs. A workflow or tool launched by a rule also needs its normal execution prerequisites.

Successful calls return action, ok: true, and data. For validate and preview, also check data.valid: a completed check can return ok: true with valid: false and diagnostics. Domain failures return ok: false with error.code, error.message, and optional error.details. Invalid call shapes can instead arrive as an MCP error.

Actions

For paginated actions, limit defaults to 25 and accepts 1–100. Pass the returned nextCursor unchanged for the next page. list.status accepts active, paused, removed, source_disabled, or dependency_blocked.

Declaration fields

Supply either a JSON object in definition or a YAML string in definitionYaml, never both. Unknown fields are rejected.

The optional resource is descriptive context for your automation. It is not an event filter or an action input.

Event filters and mappings can use taskId, taskKey, projectId, projectKey, and status. All supplied filters must match.

inputs is a JSON object and defaults to {}. Values are literal; automation declarations do not evaluate workflow reference strings. For event triggers, eventInputs maps a target input name to an event field. The destination must accept a string, and cannot also be supplied in inputs.

Omitting a workflow version follows the highest active release. Omitting a tool revision follows the most recently installed visible revision. Use an explicit version or revision when you want to review target changes before adopting them.

For tools, timeoutSeconds accepts 1–300 and can shorten the configured execution limit. It cannot extend the tool’s allowed limit. Use pm_user_tool describe to inspect the action before scheduling it.

Declarations and input objects are limited to 256 KiB of JSON; checkpoint state is limited to 64 KiB.

Validate and preview

This example requires the installed Node text summary from the starter pack. Replace cwd with an existing absolute directory.

pm_automation {
  action: "validate",
  params: {
    definition: {
      schemaVersion: "1.0",
      automation: {
        key: "local.hourly-summary",
        trigger: { type: "interval", every: "1h" },
        action: {
          type: "user_tool.run",
          toolId: "valdr-tools.user.node",
          toolAction: "summarize",
          cwd: "/absolute/path/to/your/project",
          inputs: { text: "Scheduled text summary" }
        }
      }
    }
  }
}

Validation checks the currently installed target and supplied inputs. When data.valid is true, validation returns the normalized data.definition; preview also returns the selected data.target. Read data.diagnostics when validation fails. A valid declaration does not prove future credentials, network access, or execution will succeed.

Call preview with the same declaration. For a schedule, count selects 1–20 upcoming times and defaults to 5; inspect data.upcoming, whose entries include scheduledAtMs.

For an event declaration, supply sampleEvent containing the fields needed by its mappings:

pm_automation {
  action: "preview",
  params: {
    definitionYaml: "<complete event automation YAML>",
    sampleEvent: {
      taskKey: "EXAMPLE-42",
      projectKey: "example",
      status: "open"
    }
  }
}

Inspect data.resolvedInputs. This previews mapped inputs without creating a task or running the action. It does not check whether the sample matches your event filters; compare those values separately. Replace the YAML placeholder with your complete declaration.

Apply and update a rule

1. Generate a fresh ULID with pm_generate_ulid {}.
2. Keep that ID with the exact declaration you intend to apply.
3. Call apply with the declaration and clientRequestId.

pm_automation {
  action: "apply",
  params: {
    definitionYaml: "<complete automation YAML>",
    clientRequestId: "<fresh ULID>"
  }
}

A newly applied automation is enabled. Validate and preview first. The acknowledgement includes key, activationId, revisionId, contentHash, stateVersion, effectiveStatus, and changed.

Before updating an existing local rule, call get. Supply its current activationId as expectedActivationId and its current contentHash as expectedContentHash, alongside the replacement declaration and a fresh request ID. These values keep an update from silently overwriting a rule that changed since you read it.

Changing the declaration preserves the operator pause and checkpoint state. A changed trigger resets its cadence; input-only changes do not.

For every mutation, retry a lost response with the same request ID and same arguments. Do not reuse an ID for a different operation, or generate a new ID merely to bypass a conflict.

Read activity and pause execution

pm_automation { action: "list", params: { status: "active", limit: 25 } }
pm_automation { action: "get", params: { key: "local.hourly-summary" } }
pm_automation { action: "occurrences", params: { key: "local.hourly-summary", limit: 25 } }

get includes effectiveStatus, the declaration, selected target, nextDueAtMs, engineEnabled, and any attention requiring reconciliation. Times ending in Ms are Unix timestamps in milliseconds.

Each occurrence is one scheduled or event-triggered execution. History identifies its status, selected target, summary, and any workflow run. Pass occurrenceId to inspect one direct tool’s available execution diagnostics.

Use the activationId from get when changing its status:

pm_automation {
  action: "pause",
  params: {
    key: "local.hourly-summary",
    expectedActivationId: "<activationId from get>",
    clientRequestId: "<fresh ULID>"
  }
}

Use resume with the same field names and a new request ID for a deliberate resume. Pausing does not cancel started work. See overlap and missed schedules before resuming.

remove uses the same required fields and is available for local rules. To recreate a removed local rule, use apply with recreate: true, its old expectedActivationId, a complete declaration, and a fresh request ID. Recreation starts enabled with a new activation and empty checkpoint state.

For pack-managed rules, change or withdraw the declaration in its owning pack and reimport it. Local apply and remove reject pack ownership conflicts.

Keep state between executions

Use checkpoint state for a small cursor or the last item your automation processed. Call get_state with key and expectedActivationId, then replace the state with checkpoint:

pm_automation {
  action: "checkpoint",
  params: {
    key: "local.hourly-summary",
    expectedActivationId: "<activationId from get>",
    expectedStateVersion: 0,
    state: { lastProcessedKey: "EXAMPLE-42" },
    clientRequestId: "<fresh ULID>"
  }
}

Replace 0 with the stateVersion returned by get_state. A checkpoint replaces the entire JSON value. On stale_state_version, read the latest state and recompute your update.

Workflow Valdr Tool steps can call pm_automation too. Set tool.id: pm_automation, select the action in tool.action, and place its parameters under inputs.params. This lets a setup workflow create a rule or a recurring workflow record progress and pause itself.

Generate the mutation ID in a preceding pm_generate_ulid step and capture $.raw.ulid as a named output. Pass that output as clientRequestId; ${runtime.clientRequestId} is not a ULID. Keep the generated ID stable when retrying the same operation.

To find the rule that launched the current workflow, call pm_workflow get_run with ${runtime.runUlid}. Its run.automationOrigin supplies automationKey and activationId. Use those values for get_state, then use the returned state version for checkpoint. In workflow output mappings, pm_automation data is available directly under $.raw, such as $.raw.stateVersion and $.raw.state. See Valdr Tool steps for output mapping syntax.

Recover a user-tool automation

Some tool failures pause the automation because execution may already have affected an external system. Read get.attention, then inspect the identified occurrence. Check the tool’s result and external effects before resuming.

After reconciliation, call resume with acknowledgeOccurrenceId set to that occurrence:

pm_automation {
  action: "resume",
  params: {
    key: "local.hourly-summary",
    expectedActivationId: "<activationId from get>",
    acknowledgeOccurrenceId: "<attention.occurrenceId from get>",
    clientRequestId: "<fresh ULID>"
  }
}

Acknowledging confirms that you have checked the outcome; it does not undo external effects or rerun that occurrence. After successful acknowledgement, the occurrence can still show outcome_unknown in its history. That retained result does not itself block future executions; check the resume response and the rule’s current status.

If resume returns invocation_in_flight, the tool is still executing. Wait for it to finish before acknowledging its outcome. For another rejected resume, resolve the reported error before trying again.

Next step

Ask your agent to prepare a rule from a workflow or tool you already trust: