Pixir.Delegate.CLIContract (pixir v0.1.13)

Copy Markdown View Source

Delegate CLI I/O Contract v1.

This module owns the machine-facing contract for pixir delegate. It is intentionally small and testable: parse CLI flags, read a JSON spec, validate the contract, and emit a stable dry-run result, attached runtime result, or structured error. Runtime execution is delegated to Pixir.Delegate.Runner after the same parser accepts the request. Dry-runs expose a non-fatal critical-path horizon advisory with additive workflow binding-source evidence, including whether the wait horizon was explicit or defaulted from the delegate timeout, without changing the stable four-field override projection. When they would reject, their next actions are the same recovery actions as a real rejection rather than misleading run actions. Real attached and start requests reject before runtime dispatch when that floor exceeds the caller horizon, unless the explicit --allow-short-horizon override is present.

The scaling rule is part of the contract: delegate should enter Pixir once and let BEAM coordinate fanout. Caller-side polling loops and process-per-child shell fanout are explicitly outside this surface.

Task object attachments are operator-supplied file paths that become ADR 0021 Session Resources in child Turns; the envelope records counts for dry-run planning but never echoes attachment contents or paths.

TODO(delegate-service-v1)

The start, status, attach, and cancel subcommands attempt daemon/IPC Delegate service work when a manual workspace daemon is reachable. start requires that resident owner so returned running work survives the short-lived CLI process; status, attach, and cancel can fall back to durable Delegate snapshots. attach is snapshot-first, and attach --progress=stderr-jsonl --wait-horizon-ms N requests a daemon/owner follow stream rather than a caller-side polling loop. Keep the CLI shape agent-useful:

  • --json responses should always expose delegate_id, parent session_id, diagnostics commands, and host-boundary metadata;
  • attach --progress=stderr-jsonl should emit bounded live/snapshot progress frames to stderr while stdout remains exactly one final JSON envelope;
  • long-running snapshots should distinguish accepted/running/incomplete from terminal success/failure;
  • pixir delegate help should become a supported alias for the delegate section of pixir help;
  • command_ok means the Delegate command itself was accepted and rendered a structured response; work_complete reports whether delegated work reached a clean terminal success, so consumers must not collapse them into one boolean;
  • service mode should still start exactly one Pixir entrypoint and let OTP own Subagent/Workflow fanout.

Summary

Types

rendered()
result()

Functions

contract_version()

Return the supported Delegate contract version.

run(argv, opts \\ [])

Parse and execute Delegate CLI Contract v1 dry-run or attached runtime behavior.

Types

rendered()

@type rendered() :: %{
  :exit_code => non_neg_integer(),
  :json? => boolean(),
  :payload => map(),
  :text => String.t(),
  optional(:after_render) => (-> :ok)
}

result()

@type result() :: {:ok, rendered()} | {:error, rendered()}

Functions

contract_version()

@spec contract_version() :: pos_integer()

Return the supported Delegate contract version.

run(argv, opts \\ [])

@spec run(
  [String.t()],
  keyword()
) :: result()

Parse and execute Delegate CLI Contract v1 dry-run or attached runtime behavior.