action.yml

name: 'CueAPI'
description: 'Schedule and verify AI agent jobs from your GitHub Actions workflows using CueAPI.'
author: 'CueAPI'
branding:
  icon: 'clock'
  color: 'purple'

inputs:
  command:
    description: |
      CueAPI CLI command to run. Cue management:
        create, list, get, update, delete, bulk-delete (max 100 IDs;
        always passes --yes since CI has no interactive confirm),
        pause, resume, whoami, usage, fire
      Worker-execution lifecycle (introduced in cueapi 0.2.0):
        executions-list, executions-list-claimable, executions-get,
        executions-claim, executions-claim-next, executions-heartbeat,
        executions-report-outcome
      Agent identity (Surface 6 messaging primitive, cueapi-cli 0.3.0+):
        agents-create, agents-list, agents-get (alias: agents-describe),
        agents-update, agents-delete, agents-webhook-secret-get,
        agents-webhook-secret-regenerate (destructive — rotates the secret;
        always passes --yes since CI has no interactive confirm)
      Messaging primitive (Surface 6, cueapi-cli 0.3.0+):
        messages-send, messages-get, messages-read, messages-ack,
        message-to (top-level ergonomic alias — accepts a recipient
        by name/slug/agent_id; CLI does roster lookup before sending.
        Distinct from messages-send which requires a fully-qualified
        to-agent. Wraps cueapi-cli #40.)
      Workers (worker registration / cleanup):
        workers-list, workers-delete
      Execution verify-class (replay terminal executions + manual verify
      pipeline, cueapi-cli 0.3.0+):
        executions-replay, executions-verification-pending, executions-verify
    required: true

  # Cue management inputs (existing).
  name:
    description: 'Cue name (for create/update)'
    required: false
  cron:
    description: 'Cron expression for recurring cue (for create/update)'
    required: false
  at:
    description: 'ISO timestamp for one-time cue (for create)'
    required: false
  url:
    description: 'Callback URL (for create/update)'
    required: false
  method:
    description: 'HTTP method (default: POST)'
    required: false
    default: 'POST'
  timezone:
    description: 'Timezone (default: UTC)'
    required: false
    default: 'UTC'
  payload:
    description: 'JSON payload string (for create/update)'
    required: false
  description:
    description: 'Cue description (for create/update)'
    required: false
  worker:
    description: 'Use worker transport (no public URL needed). Set to "true" to enable.'
    required: false
    default: 'false'
  cue-id:
    description: 'Target cue ID (for get/update/delete/pause/resume/fire/executions-list)'
    required: false
  cue-ids:
    description: |
      Multiple cue IDs for `bulk-delete` (whitespace or newline separated;
      max 100 per call). Per-ID atomic, NOT batch atomic — IDs that don't
      exist OR aren't owned by the caller land in the response's `skipped`
      array (silent skip on miss; no info leak about other tenants' cues).
      Action always passes --yes (no interactive confirm in CI); CLI sends
      the X-Confirm-Destructive: true header server-side.
    required: false
  status:
    description: 'Filter by status (active/paused for list; execution status for executions-list)'
    required: false
  limit:
    description: 'Max results for list / executions-list'
    required: false
  offset:
    description: 'Offset for list / executions-list pagination'
    required: false
  api-key:
    description: 'CueAPI API key. Prefer passing via CUEAPI_API_KEY env var from a secret.'
    required: false
  cli-version:
    description: 'Pin a specific cueapi CLI version (e.g. "0.2.0"). Default: latest.'
    required: false

  # Fire inputs (cueapi 0.2.0+).
  payload-override:
    description: 'JSON payload override for `fire` (overrides the cue stored payload for this fire only)'
    required: false
  merge-strategy:
    description: 'How payload-override combines with the cue stored payload: merge (default, server-side) or replace'
    required: false
  send-at:
    description: |
      Optional ISO 8601 timestamp to schedule a future fire (used by `fire` — hosted PR #618)
      OR a future message send (used by `messages-send` — hosted PR #623, §13).
      Omitted = run-now/send-now (server default). Past timestamps are forgiving fallback
      (treated as run/send now). Same semantics across cue-fire and messages-send.
    required: false
  exit-criteria:
    description: |
      Required-assertion keys for §14 work-verification-light on `fire` (hosted PR #632).
      Whitespace-separated list (e.g. "key1 key2 key3"). Receiver MUST report values
      for every key under outcome.assertions; missing keys mark the execution
      verification_failed. Pass an empty string to opt out of cue-level
      required_assertions for this fire. Max 20 keys.
    required: false
  verify:
    description: |
      Set "true" to OPT IN to Phase 2 body-verify on `fire` (parity with
      cueapi-cli #55 + cueapi-python #41, Mike body-verify directive
      2026-05-11). When set, cueapi-cli sends X-CueAPI-Verify-Echo header
      + checks substrate-echoed body matches sent body, failing the Action
      step (exit 7) on drift. Default OFF for fire because substrate
      /v1/cues/{id}/fire echoes a pydantic-after-parse body that may
      include server-side default-population, causing spurious diff vs
      the CLI's canonical-JSON serialization. Opt in when you know your
      payload-override serialization matches substrate echo semantics.
      NOTE: distinct from `no-verify` (which is for messages — default-on
      opt-out); fire is default-off opt-in.
    required: false

  # Executions lifecycle inputs (cueapi 0.2.0+).
  execution-id:
    description: 'Target execution ID (for executions-get/claim/heartbeat/report-outcome)'
    required: false
  worker-id:
    description: 'Stable worker identifier (required for executions-claim, executions-claim-next, executions-heartbeat)'
    required: false
  task:
    description: 'Task filter for executions-list-claimable / executions-claim-next (server-side SQL filter)'
    required: false
  agent:
    description: 'Agent filter for executions-list-claimable (server-side SQL filter)'
    required: false

  # executions-list filter inputs (cueapi-cli PR #27).
  outcome-state:
    description: |
      Filter `executions-list` by outcome_state (server-side filter).
      One of: reported_success / reported_failure / verified_success /
      verification_pending / verification_failed / unknown.
    required: false
  result-type:
    description: |
      Filter `executions-list` by evidence result_type (server-side filter).
      Free-form string matched against the execution's `evidence_result_type`
      column (e.g. "pr", "issue", "comment", "doc").
    required: false
  has-evidence:
    description: |
      Filter `executions-list` to executions that reported evidence (i.e.
      `evidence_external_id IS NOT NULL`). Set to "true" to enable;
      omit/false to apply no filter. The flag is meaningful only when true
      (server-side `has_evidence=false` is the same as omitting it, just
      with URL noise).
    required: false
    default: 'false'
  triggered-by:
    description: |
      Filter `executions-list` by triggered_by (server-side filter).
      One of: scheduled / manual_fire / chain.
    required: false

  success:
    description: |
      Outcome success flag — "true" or "false". Used for:
        - executions-report-outcome (translates to --success / --failure)
        - executions-verify (translates to --valid / --invalid; omit for server default valid=true)
    required: false
  external-id:
    description: 'External system ID for executions-report-outcome (e.g. PR number, doc ID)'
    required: false
  result-url:
    description: 'Public URL for executions-report-outcome evidence (e.g. tweet, PR, doc)'
    required: false
  summary:
    description: |
      Short human-readable note (max 500 chars). Used for:
        - executions-report-outcome (--summary)
        - executions-verify (--reason; most useful with success=false to record why verification failed)
    required: false

  # Agent commands inputs (Surface 6 messaging primitive identity).
  ref:
    description: 'Agent slug or opaque id (for agents-get/update/delete/webhook-secret-get/describe)'
    required: false
  slug:
    description: 'Agent slug (for agents-create; URL-safe identifier)'
    required: false
  display-name:
    description: 'Agent display name (for agents-create/update)'
    required: false
  webhook-url:
    description: 'Agent webhook callback URL (for agents-create/update). Pass empty string + clear-webhook-url=true to remove on update.'
    required: false
  clear-webhook-url:
    description: 'Set to "true" on agents-update to remove the agent webhook URL (sentinel for unsetting). Default false.'
    required: false
    default: 'false'
  online-only:
    description: 'Set to "true" on agents-list to filter to currently-online agents only (mutually exclusive with status). Default false.'
    required: false
    default: 'false'

  # Messaging primitive inputs (Surface 6, cueapi-cli 0.3.0+).
  msg-id:
    description: 'Target message ID (msg_<12 alnum>) for messages-get/read/ack'
    required: false
  from-agent:
    description: 'Sender agent — opaque agent_id or slug-form (agent@user). Required for messages-send.'
    required: false
  to-agent:
    description: |
      Recipient agent. For `messages-send`: opaque agent_id (agt_xxx) or slug-form (agent@user) — must be fully qualified.
      For `message-to`: also accepts a bare display name or slug; CLI does roster lookup before sending (case-insensitive
      match against display_name and slug). Required for messages-send and message-to.
    required: false
  body:
    description: |
      Message body (1-32768 chars) for messages-send / message-to.
      Inline; auto-rejected by cueapi-cli when content contains shell metacharacters
      ($(...), backticks, ${VAR}) — use `message-file` or `body-stdin` instead.
      Provide exactly one of body / message-file / body-stdin.
    required: false
  message-file:
    description: |
      RECOMMENDED for content with shell metacharacters. Path to a file
      containing the message body. cueapi-cli reads byte-identical (zero
      shell interpolation). Mint pattern: heredoc with single-quoted EOF
      marker → file → pass path. Phase 3 of body-verify defense (Mike
      directive 2026-05-11).
    required: false
  body-stdin:
    description: |
      Set "true" to read message body from stdin instead of inline.
      Use with a preceding step that writes the body to a file + then
      pipes via `< $FILE` in your workflow.
    required: false
  allow-inline-metachars:
    description: |
      Set "true" to override cueapi-cli's Layer 3 force-file guard. Use
      ONLY when the inline `body` is verified-literal (e.g., shell-tutorial
      example legitimately containing $(...) text).
    required: false
  no-verify:
    description: |
      Set "true" to opt out of Phase 2 body-verify auto-echo (Mike body-
      verify directive 2026-05-11). Default is verify-on: cueapi-cli sends
      X-CueAPI-Verify-Echo header + checks substrate-echoed body matches
      sent body, failing the Action step on drift. Use --no-verify when
      perf-sensitive flows make the extra response-payload byte-overhead
      undesirable (rare; one substrate roundtrip already includes the echo).
    required: false
  subject:
    description: 'Optional message subject (max 255 chars) for messages-send'
    required: false
  reply-to-message:
    description: 'Previous message ID this reply chains to (msg_<12 alnum>). thread_id inherits.'
    required: false
  priority:
    description: 'Message priority 1-5 (server default 3). Receiver-pair limits may downgrade >3 to 3.'
    required: false
  expects-reply:
    description: 'Set "true" on messages-send to mark this message as expecting a reply.'
    required: false
    default: 'false'
  reply-to-agent:
    description: 'Decoupled reply target (defaults to the sender). Override when reply should route to a different agent.'
    required: false
  metadata:
    description: 'JSON metadata blob for messages-send'
    required: false
  idempotency-key:
    description: |
      Optional Idempotency-Key (≤256 chars). Different transports per command:
        - For `messages-send` / `message-to`: sent as the `Idempotency-Key` request header.
        - For `fire`: sent as the `idempotency_key` body field on cues fire (server FireRequest schema, hosted PR #683).
          Same key on the same cue within 24h returns the cached execution; same key + DIFFERENT body
          returns 409 idempotency_key_conflict. Sent as a BODY field, NOT a header — matches the server's
          FireRequest contract.
      Same key + same body within 24h returns the existing record HTTP 200 instead of 201.
    required: false
  mode:
    description: |
      Delivery mode hint for `messages-send` and `message-to` (Surface 6 v2 delivery_mode;
      cueapi-cli #41 added it to `message-to`; cueapi-cli #49 added it to `messages send` for parity).
      One of: live | bg | inbox | webhook | auto (default).
        live = recipient's attached Live session
        bg = spawn a fresh background session for the recipient
        inbox = leave in inbox for pull
        webhook = POST to the recipient's configured webhook
        auto = server picks the best supported mode
      Server may downgrade if the requested mode isn't supported. Defaulting to `auto`
      matches the CLI's default; the action omits the flag entirely when set to `auto`
      to keep wire-format identical to pre-Surface-6 senders.
    required: false
  notify:
    description: |
      §17 BCC-light (hosted PR #619) — whitespace-separated list of agent refs (max 10).
      Used by `messages-send` and `message-to`. Each ref gets a stripped notification copy
      (subject + sender + recipient + 1-line summary, no full body) alongside the main
      delivery, sharing the main message's thread_id. Each entry must be a fully-qualified
      agent ref (opaque agt_xxx or slug-form agent@user). Self-bcc is silently de-duped
      server-side. Notifications skip the monthly quota and are pinned to priority=3.
    required: false
  live-fallback-mode:
    description: |
      Agent-id-split refactor (2026-05-12) — controls behavior when the recipient is a
      Live-sibling agent and its Live session is silent (no fresh heartbeat).
      Used by `messages-send` and `message-to`. One of:
        live_only = message queues against the Live agent until that specific Live session attaches
        fallback_to_background (default) = substrate looks up the BG sibling via parent_agent_id and routes there
      The action omits the flag entirely when set to `fallback_to_background` (or unset)
      to keep wire-format identical to pre-refactor senders.
      Parity with cueapi-cli `messages send --live-fallback-mode` (#56).
      Design Dock: https://trydock.ai/workspaces/agent-id-split-refactor-2026-05-12
    required: false
  parent-agent-id:
    description: |
      Agent-id-split refactor (2026-05-12) — link this new agent as a sibling of the given
      parent agent (`agt_xxx` opaque ID). Used by `agents-create` when creating a Live
      sibling for an existing BG agent: pass the BG agent's id and substrate stores the FK
      so the router can fall back from Live to BG when the Live session is silent (see
      `live-fallback-mode`). Omit for standalone (parent) agents. Substrate enforces FK
      validity. Parity with cueapi-cli `agents create --parent-agent-id` (#56).
    required: false

outputs:
  result:
    description: 'Raw stdout from the cueapi CLI invocation'
    value: ${{ steps.run.outputs.result }}

runs:
  using: 'composite'
  steps:
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'

    # Inputs are passed via env vars (not direct ${{ inputs.X }}
    # interpolation into the shell script) to avoid GitHub Actions'
    # documented shell-injection vector. With direct interpolation, a
    # workflow caller passing e.g. `name: '"; rm -rf /; #'` would get
    # arbitrary shell execution at the runner. Bash quotes env-var
    # expansions automatically, so `"$NAME"` is safe regardless of the
    # caller's input. See:
    # https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable

    - name: Install cueapi CLI
      shell: bash
      env:
        CLI_VERSION: ${{ inputs.cli-version }}
      run: |
        if [ -n "$CLI_VERSION" ]; then
          python -m pip install --quiet "cueapi==$CLI_VERSION"
        else
          python -m pip install --quiet cueapi
        fi
        cueapi --version

    - name: Run cueapi ${{ inputs.command }}
      id: run
      shell: bash
      env:
        CUEAPI_API_KEY: ${{ inputs.api-key || env.CUEAPI_API_KEY }}
        # All caller-supplied inputs flow through env vars from here on.
        # Adding a new input? Declare it here AND reference it as $VAR_NAME
        # in the script — never as ${{ inputs.X }} inside `run:`.
        COMMAND: ${{ inputs.command }}
        NAME: ${{ inputs.name }}
        CRON: ${{ inputs.cron }}
        AT: ${{ inputs.at }}
        URL: ${{ inputs.url }}
        METHOD: ${{ inputs.method }}
        TIMEZONE: ${{ inputs.timezone }}
        PAYLOAD: ${{ inputs.payload }}
        DESCRIPTION: ${{ inputs.description }}
        WORKER: ${{ inputs.worker }}
        CUE_ID: ${{ inputs.cue-id }}
        CUE_IDS: ${{ inputs.cue-ids }}
        STATUS: ${{ inputs.status }}
        LIMIT: ${{ inputs.limit }}
        OFFSET: ${{ inputs.offset }}
        # Fire + executions inputs (cueapi 0.2.0+).
        PAYLOAD_OVERRIDE: ${{ inputs.payload-override }}
        MERGE_STRATEGY: ${{ inputs.merge-strategy }}
        # Per-fire/per-message scheduling + work-verification (PR #618 / #623 / #632).
        SEND_AT: ${{ inputs.send-at }}
        EXIT_CRITERIA: ${{ inputs.exit-criteria }}
        VERIFY: ${{ inputs.verify }}
        EXECUTION_ID: ${{ inputs.execution-id }}
        WORKER_ID: ${{ inputs.worker-id }}
        TASK: ${{ inputs.task }}
        AGENT: ${{ inputs.agent }}
        # executions-list filter inputs (cueapi-cli PR #27).
        OUTCOME_STATE: ${{ inputs.outcome-state }}
        RESULT_TYPE: ${{ inputs.result-type }}
        HAS_EVIDENCE: ${{ inputs.has-evidence }}
        TRIGGERED_BY: ${{ inputs.triggered-by }}
        SUCCESS: ${{ inputs.success }}
        EXTERNAL_ID: ${{ inputs.external-id }}
        RESULT_URL: ${{ inputs.result-url }}
        SUMMARY: ${{ inputs.summary }}
        # Agent commands inputs (Surface 6 messaging primitive identity).
        REF: ${{ inputs.ref }}
        SLUG: ${{ inputs.slug }}
        DISPLAY_NAME: ${{ inputs.display-name }}
        WEBHOOK_URL: ${{ inputs.webhook-url }}
        CLEAR_WEBHOOK_URL: ${{ inputs.clear-webhook-url }}
        ONLINE_ONLY: ${{ inputs.online-only }}
        # Messaging primitive inputs (Surface 6).
        MSG_ID: ${{ inputs.msg-id }}
        FROM_AGENT: ${{ inputs.from-agent }}
        TO_AGENT: ${{ inputs.to-agent }}
        BODY: ${{ inputs.body }}
        MESSAGE_FILE: ${{ inputs.message-file }}
        BODY_STDIN: ${{ inputs.body-stdin }}
        ALLOW_INLINE_METACHARS: ${{ inputs.allow-inline-metachars }}
        NO_VERIFY: ${{ inputs.no-verify }}
        SUBJECT: ${{ inputs.subject }}
        REPLY_TO_MESSAGE: ${{ inputs.reply-to-message }}
        PRIORITY: ${{ inputs.priority }}
        EXPECTS_REPLY: ${{ inputs.expects-reply }}
        REPLY_TO_AGENT: ${{ inputs.reply-to-agent }}
        METADATA: ${{ inputs.metadata }}
        IDEMPOTENCY_KEY: ${{ inputs.idempotency-key }}
        MODE: ${{ inputs.mode }}
        NOTIFY: ${{ inputs.notify }}
        LIVE_FALLBACK_MODE: ${{ inputs.live-fallback-mode }}
        PARENT_AGENT_ID: ${{ inputs.parent-agent-id }}
      run: |
        set -euo pipefail
        cmd=(cueapi "$COMMAND")

        case "$COMMAND" in
          create)
            [ -n "$NAME" ]        && cmd+=(--name "$NAME")
            [ -n "$CRON" ]        && cmd+=(--cron "$CRON")
            [ -n "$AT" ]          && cmd+=(--at "$AT")
            [ -n "$URL" ]         && cmd+=(--url "$URL")
            [ -n "$METHOD" ]      && cmd+=(--method "$METHOD")
            [ -n "$TIMEZONE" ]    && cmd+=(--timezone "$TIMEZONE")
            [ -n "$PAYLOAD" ]     && cmd+=(--payload "$PAYLOAD")
            [ -n "$DESCRIPTION" ] && cmd+=(--description "$DESCRIPTION")
            [ "$WORKER" = "true" ] && cmd+=(--worker)
            ;;
          update)
            [ -n "$CUE_ID" ]      && cmd+=("$CUE_ID")
            [ -n "$NAME" ]        && cmd+=(--name "$NAME")
            [ -n "$CRON" ]        && cmd+=(--cron "$CRON")
            [ -n "$URL" ]         && cmd+=(--url "$URL")
            [ -n "$PAYLOAD" ]     && cmd+=(--payload "$PAYLOAD")
            [ -n "$DESCRIPTION" ] && cmd+=(--description "$DESCRIPTION")
            ;;
          get|delete|pause|resume)
            [ -n "$CUE_ID" ]      && cmd+=("$CUE_ID")
            ;;
          bulk-delete)
            # Whitespace/newline-separated list of cue IDs. Splits via
            # `read -ra`. Caps at 100 to match server + cli #46. Always
            # passes --yes (no interactive confirm in CI); CLI sends
            # X-Confirm-Destructive: true server-side.
            if [ -z "$CUE_IDS" ]; then
              echo "::error::bulk-delete requires cue-ids input (whitespace-separated cue IDs)."
              exit 1
            fi
            read -ra _IDS <<< "$CUE_IDS"
            if [ ${#_IDS[@]} -gt 100 ]; then
              echo "::error::bulk-delete max 100 IDs per call; got ${#_IDS[@]}. Split into batches."
              exit 1
            fi
            cmd+=("${_IDS[@]}")
            cmd+=(--yes)
            ;;
          list)
            [ -n "$STATUS" ]      && cmd+=(--status "$STATUS")
            [ -n "$LIMIT" ]       && cmd+=(--limit "$LIMIT")
            [ -n "$OFFSET" ]      && cmd+=(--offset "$OFFSET")
            ;;
          whoami|usage)
            ;;
          fire)
            [ -n "$CUE_ID" ]           && cmd+=("$CUE_ID")
            [ -n "$PAYLOAD_OVERRIDE" ] && cmd+=(--payload-override "$PAYLOAD_OVERRIDE")
            [ -n "$MERGE_STRATEGY" ]   && cmd+=(--merge-strategy "$MERGE_STRATEGY")
            [ -n "$SEND_AT" ]          && cmd+=(--send-at "$SEND_AT")
            [ -n "$IDEMPOTENCY_KEY" ]  && cmd+=(--idempotency-key "$IDEMPOTENCY_KEY")
            # Phase 2 body-verify opt-in for fire (cueapi-cli #55, Mike directive
            # 2026-05-11). Default OFF — substrate echoes parsed-after-default body
            # that would cause spurious mismatches for the typical caller. Opt in
            # when the caller knows substrate echo matches their serialization.
            [ "$VERIFY" = "true" ]     && cmd+=(--verify)
            # Whitespace-separated list of assertion keys → repeated --exit-criteria
            # flags (the CLI uses click's `multiple=True`, so each key needs its own
            # flag invocation). Empty string === field not passed, in which case
            # the cue-level required_assertions apply unchanged. To clear cue-level
            # requirements for this fire from the action, you'd need to invoke the
            # CLI directly (the GitHub Actions input layer cannot pass an explicit
            # empty string distinct from "not set").
            if [ -n "$EXIT_CRITERIA" ]; then
              # shellcheck disable=SC2086 # intentional word-splitting on whitespace
              for key in $EXIT_CRITERIA; do
                cmd+=(--exit-criteria "$key")
              done
            fi
            ;;
          # Executions subgroup (cueapi 0.2.0+) — these commands map to
          # ``cueapi executions <sub>`` (group + subcommand). Override
          # the default ``cmd=(cueapi "$COMMAND")`` because COMMAND
          # carries a hyphenated name (e.g. "executions-list") and the
          # CLI expects the words separated.
          executions-list)
            cmd=(cueapi executions list)
            [ -n "$CUE_ID" ]        && cmd+=(--cue-id "$CUE_ID")
            [ -n "$STATUS" ]        && cmd+=(--status "$STATUS")
            [ -n "$OUTCOME_STATE" ] && cmd+=(--outcome-state "$OUTCOME_STATE")
            [ -n "$RESULT_TYPE" ]   && cmd+=(--result-type "$RESULT_TYPE")
            # has-evidence is a boolean flag on the CLI — only emit when true.
            # Server-side has_evidence=false is equivalent to omitting the
            # filter entirely, so we drop it on the false case to keep the
            # CLI invocation clean.
            [ "$HAS_EVIDENCE" = "true" ] && cmd+=(--has-evidence)
            [ -n "$TRIGGERED_BY" ]  && cmd+=(--triggered-by "$TRIGGERED_BY")
            [ -n "$LIMIT" ]         && cmd+=(--limit "$LIMIT")
            [ -n "$OFFSET" ]        && cmd+=(--offset "$OFFSET")
            ;;
          executions-list-claimable)
            cmd=(cueapi executions list-claimable)
            [ -n "$TASK" ]        && cmd+=(--task "$TASK")
            [ -n "$AGENT" ]       && cmd+=(--agent "$AGENT")
            ;;
          executions-get)
            cmd=(cueapi executions get)
            [ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
            ;;
          executions-claim)
            cmd=(cueapi executions claim)
            [ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
            [ -n "$WORKER_ID" ]    && cmd+=(--worker-id "$WORKER_ID")
            ;;
          executions-claim-next)
            cmd=(cueapi executions claim-next)
            [ -n "$WORKER_ID" ]    && cmd+=(--worker-id "$WORKER_ID")
            [ -n "$TASK" ]         && cmd+=(--task "$TASK")
            ;;
          executions-heartbeat)
            cmd=(cueapi executions heartbeat)
            [ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
            [ -n "$WORKER_ID" ]    && cmd+=(--worker-id "$WORKER_ID")
            ;;
          executions-report-outcome)
            cmd=(cueapi executions report-outcome)
            [ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
            if [ "$SUCCESS" = "true" ]; then
              cmd+=(--success)
            elif [ "$SUCCESS" = "false" ]; then
              cmd+=(--failure)
            fi
            [ -n "$EXTERNAL_ID" ] && cmd+=(--external-id "$EXTERNAL_ID")
            [ -n "$RESULT_URL" ]  && cmd+=(--result-url "$RESULT_URL")
            [ -n "$SUMMARY" ]     && cmd+=(--summary "$SUMMARY")
            ;;
          # Agents subgroup (Surface 6 messaging primitive identity, cueapi-cli
          # PR #28 + #40). Each maps to ``cueapi agents <sub>``. Override the
          # default ``cmd=(cueapi "$COMMAND")`` because COMMAND carries a
          # hyphenated name and the CLI expects words separated.
          agents-create)
            cmd=(cueapi agents create)
            [ -n "$SLUG" ]         && cmd+=(--slug "$SLUG")
            [ -n "$DISPLAY_NAME" ] && cmd+=(--display-name "$DISPLAY_NAME")
            [ -n "$DESCRIPTION" ]  && cmd+=(--description "$DESCRIPTION")
            [ -n "$WEBHOOK_URL" ]  && cmd+=(--webhook-url "$WEBHOOK_URL")
            # Agent-id-split refactor (2026-05-12) — pass-through FK
            # for Live-sibling creates. Default-omit when unset; standalone
            # (parent) agents create with unchanged wire format.
            [ -n "$PARENT_AGENT_ID" ] && cmd+=(--parent-agent-id "$PARENT_AGENT_ID")
            ;;
          agents-list)
            cmd=(cueapi agents list)
            if [ "$ONLINE_ONLY" = "true" ]; then
              # --online-only is mutually exclusive with --status; only one passes.
              cmd+=(--online-only)
            elif [ -n "$STATUS" ]; then
              cmd+=(--status "$STATUS")
            fi
            [ -n "$LIMIT" ]  && cmd+=(--limit "$LIMIT")
            [ -n "$OFFSET" ] && cmd+=(--offset "$OFFSET")
            ;;
          agents-get|agents-describe)
            # ``describe`` is a verb alias for ``get`` (cueapi-cli PR #40).
            cmd=(cueapi agents get)
            [ -n "$REF" ] && cmd+=("$REF")
            ;;
          agents-update)
            cmd=(cueapi agents update)
            [ -n "$REF" ]          && cmd+=("$REF")
            [ -n "$DISPLAY_NAME" ] && cmd+=(--display-name "$DISPLAY_NAME")
            [ -n "$DESCRIPTION" ]  && cmd+=(--description "$DESCRIPTION")
            if [ "$CLEAR_WEBHOOK_URL" = "true" ]; then
              cmd+=(--clear-webhook-url)
            elif [ -n "$WEBHOOK_URL" ]; then
              cmd+=(--webhook-url "$WEBHOOK_URL")
            fi
            ;;
          agents-delete)
            cmd=(cueapi agents delete)
            [ -n "$REF" ] && cmd+=("$REF")
            ;;
          agents-webhook-secret-get)
            cmd=(cueapi agents webhook-secret get)
            [ -n "$REF" ] && cmd+=("$REF")
            ;;
          agents-webhook-secret-regenerate)
            # Destructive: rotates the agent's webhook signing secret and
            # drops the old one immediately. Any in-flight webhook
            # deliveries already signed with the old secret will fail
            # signature verification on the consumer side. The CLI sends
            # the X-Confirm-Destructive: true header automatically;
            # we always pass --yes since CI has no interactive confirm.
            cmd=(cueapi agents webhook-secret regenerate)
            [ -n "$REF" ] && cmd+=("$REF")
            cmd+=(--yes)
            ;;
          # Messaging primitive subgroup (Surface 6, cueapi-cli 0.3.0+).
          messages-send)
            cmd=(cueapi messages send)
            [ -n "$FROM_AGENT" ]       && cmd+=(--from "$FROM_AGENT")
            [ -n "$TO_AGENT" ]         && cmd+=(--to "$TO_AGENT")
            # Phase 3 body sources (force-file mode in cueapi-cli, Mike
            # directive 2026-05-11). Exactly one of: --message-file (recommended;
            # zero shell interpolation), --body-stdin, --body inline (auto-
            # rejected by cueapi-cli if it contains $(...) / backticks / ${VAR}).
            [ -n "$MESSAGE_FILE" ]     && cmd+=(--message-file "$MESSAGE_FILE")
            [ "$BODY_STDIN" = "true" ] && cmd+=(--body-stdin)
            [ "$ALLOW_INLINE_METACHARS" = "true" ] && cmd+=(--allow-inline-metachars)
            [ "$NO_VERIFY" = "true" ] && cmd+=(--no-verify)
            [ -n "$BODY" ]             && cmd+=(--body "$BODY")
            [ -n "$SUBJECT" ]          && cmd+=(--subject "$SUBJECT")
            [ -n "$REPLY_TO_MESSAGE" ] && cmd+=(--reply-to "$REPLY_TO_MESSAGE")
            [ -n "$PRIORITY" ]         && cmd+=(--priority "$PRIORITY")
            [ "$EXPECTS_REPLY" = "true" ] && cmd+=(--expects-reply)
            [ -n "$REPLY_TO_AGENT" ]   && cmd+=(--reply-to-agent "$REPLY_TO_AGENT")
            [ -n "$METADATA" ]         && cmd+=(--metadata "$METADATA")
            [ -n "$IDEMPOTENCY_KEY" ]  && cmd+=(--idempotency-key "$IDEMPOTENCY_KEY")
            [ -n "$SEND_AT" ]          && cmd+=(--send-at "$SEND_AT")
            # Default-omit `--mode auto` to keep wire format identical to
            # pre-Surface-6 senders (server treats absent === auto).
            if [ -n "$MODE" ] && [ "$MODE" != "auto" ]; then
              cmd+=(--mode "$MODE")
            fi
            # §17 BCC-light: whitespace-separated agent refs → repeated
            # --notify flags (CLI uses click `multiple=True`, max 10).
            if [ -n "$NOTIFY" ]; then
              # shellcheck disable=SC2086 # intentional word-splitting on whitespace
              for ref in $NOTIFY; do
                cmd+=(--notify "$ref")
              done
            fi
            # Agent-id-split refactor (2026-05-12) — default-omit when
            # value matches the substrate default (fallback_to_background).
            # Same default-omit pattern as --mode auto.
            if [ -n "$LIVE_FALLBACK_MODE" ] && [ "$LIVE_FALLBACK_MODE" != "fallback_to_background" ]; then
              cmd+=(--live-fallback-mode "$LIVE_FALLBACK_MODE")
            fi
            ;;
          message-to)
            # Top-level ergonomic alias for messaging primitive sends. Accepts
            # a recipient by bare name, slug, or fully-qualified agent_id;
            # CLI does case-insensitive roster lookup before sending. Wraps
            # cueapi-cli #40. Distinct from `messages-send` (which requires
            # a fully-qualified to-agent).
            cmd=(cueapi message-to)
            [ -n "$TO_AGENT" ]         && cmd+=("$TO_AGENT")  # positional recipient
            [ -n "$FROM_AGENT" ]       && cmd+=(--from "$FROM_AGENT")
            # Phase 3 body sources — parity with messages-send.
            [ -n "$MESSAGE_FILE" ]     && cmd+=(--message-file "$MESSAGE_FILE")
            [ "$BODY_STDIN" = "true" ] && cmd+=(--body-stdin)
            [ "$ALLOW_INLINE_METACHARS" = "true" ] && cmd+=(--allow-inline-metachars)
            [ "$NO_VERIFY" = "true" ] && cmd+=(--no-verify)
            [ -n "$BODY" ]             && cmd+=(--body "$BODY")
            [ -n "$SUBJECT" ]          && cmd+=(--subject "$SUBJECT")
            [ -n "$REPLY_TO_MESSAGE" ] && cmd+=(--reply-to "$REPLY_TO_MESSAGE")
            [ -n "$PRIORITY" ]         && cmd+=(--priority "$PRIORITY")
            [ "$EXPECTS_REPLY" = "true" ] && cmd+=(--expects-reply)
            [ -n "$REPLY_TO_AGENT" ]   && cmd+=(--reply-to-agent "$REPLY_TO_AGENT")
            [ -n "$METADATA" ]         && cmd+=(--metadata "$METADATA")
            [ -n "$IDEMPOTENCY_KEY" ]  && cmd+=(--idempotency-key "$IDEMPOTENCY_KEY")
            [ -n "$SEND_AT" ]          && cmd+=(--send-at "$SEND_AT")
            # Default-omit `--mode auto` to keep wire format identical to
            # pre-Surface-6 senders (server treats absent === auto).
            if [ -n "$MODE" ] && [ "$MODE" != "auto" ]; then
              cmd+=(--mode "$MODE")
            fi
            # §17 BCC-light: whitespace-separated agent refs → repeated
            # --notify flags (CLI uses click `multiple=True`, max 10).
            if [ -n "$NOTIFY" ]; then
              # shellcheck disable=SC2086 # intentional word-splitting on whitespace
              for ref in $NOTIFY; do
                cmd+=(--notify "$ref")
              done
            fi
            # Agent-id-split refactor (2026-05-12) — parity with
            # messages-send. Default-omit when matching substrate default.
            if [ -n "$LIVE_FALLBACK_MODE" ] && [ "$LIVE_FALLBACK_MODE" != "fallback_to_background" ]; then
              cmd+=(--live-fallback-mode "$LIVE_FALLBACK_MODE")
            fi
            ;;
          messages-get)
            cmd=(cueapi messages get)
            [ -n "$MSG_ID" ] && cmd+=("$MSG_ID")
            ;;
          messages-read)
            cmd=(cueapi messages read)
            [ -n "$MSG_ID" ] && cmd+=("$MSG_ID")
            ;;
          messages-ack)
            cmd=(cueapi messages ack)
            [ -n "$MSG_ID" ] && cmd+=("$MSG_ID")
            ;;
          # Workers subgroup — registered worker query + cleanup.
          workers-list)
            cmd=(cueapi workers list)
            ;;
          workers-delete)
            cmd=(cueapi workers delete)
            [ -n "$WORKER_ID" ] && cmd+=("$WORKER_ID")
            cmd+=(--yes)
            ;;
          # Verify-class subgroup — replay terminal executions + manual
          # verification pipeline. Reuses execution-id input + success
          # (as --valid/--invalid) + summary (as --reason).
          executions-replay)
            cmd=(cueapi executions replay)
            [ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
            ;;
          executions-verification-pending)
            cmd=(cueapi executions verification-pending)
            [ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
            ;;
          executions-verify)
            cmd=(cueapi executions verify)
            [ -n "$EXECUTION_ID" ] && cmd+=("$EXECUTION_ID")
            if [ "$SUCCESS" = "true" ]; then
              cmd+=(--valid)
            elif [ "$SUCCESS" = "false" ]; then
              cmd+=(--invalid)
            fi
            [ -n "$SUMMARY" ] && cmd+=(--reason "$SUMMARY")
            ;;
          *)
            echo "::error::Unsupported command '$COMMAND'. Supported: create, list, get, update, delete, bulk-delete, pause, resume, whoami, usage, fire, executions-list, executions-list-claimable, executions-get, executions-claim, executions-claim-next, executions-heartbeat, executions-report-outcome, agents-create, agents-list, agents-get, agents-describe, agents-update, agents-delete, agents-webhook-secret-get, agents-webhook-secret-regenerate, messages-send, messages-get, messages-read, messages-ack, message-to, workers-list, workers-delete, executions-replay, executions-verification-pending, executions-verify."
            exit 1
            ;;
        esac

        echo "Running: ${cmd[*]}"
        output=$("${cmd[@]}" 2>&1)
        echo "$output"
        {
          echo 'result<<CUEAPI_EOF'
          echo "$output"
          echo 'CUEAPI_EOF'
        } >> "$GITHUB_OUTPUT"