Pixir.Delegate.Runner (pixir v0.1.13)

Copy Markdown View Source

Attached runtime runner for pixir delegate.

This module is the first real implementation behind the Delegate CLI I/O Contract. It keeps Pixir.Delegate.CLIContract focused on parsing/rendering and uses existing Pixir runtime surfaces for work:

  • parent Session creation goes through Pixir.Conversation;
  • Subagent fanout goes through Pixir.Subagents;
  • read-only and bounded-write Workflow fanout goes through Pixir.Workflows;
  • terminal status comes from wait_outcome/4 or the Workflow result envelope;
  • durable truth remains the parent and child Session Logs plus Workflow Events.

It also exposes a start-only primitive for the current-runtime Delegate owner. Before either attached or start-only execution creates a parent Session, shared limit resolution and pure critical-path estimation enforce the caller horizon unless an explicit short-horizon override was requested. Workflow admission retains the normalized declared workflow timeout, whether that timeout was explicitly present in the normalized workflow spec before default injection, the caller wait horizon, and wait_horizon_explicit binding evidence as separate fields while runtime still receives their same effective minimum. The wait-horizon evidence is true only when the request or limits.wait_horizon_ms supplied it, and false when the horizon defaulted from the delegate timeout. The runner deliberately does not implement streaming attach, cross-invocation daemon residency, merge-back/apply, or any process-per-child shell fanout. Bounded-write Workflow support is attached-only, requires explicit per-step write sets, and reports where writes land.

Delegate task attachments are operator-supplied Session Resource links under ADR 0021; they are consumed by each child Session's first user message and are not echoed in the delegate envelope.

TODO(delegate-service-v1)

Keep the attached runner as the synchronous compatibility path. The service owner reuses the same normalization and start vocabulary, but owns current-runtime lifetime and active cancellation in OTP. Avoid adding caller-side loops here that would make pixir delegate --spec pretend to be a detached daemon.

Summary

Functions

Estimate the spec critical path using the same limits consumed by runtime.

Accepted keys inside one tasks[] object entry.

Resolve Delegate caller and child limits from the shared runtime precedence rules.

Run a validated Delegate spec through the attached runtime path.

Start a validated subagents Delegate spec without waiting for terminal completion.

Functions

critical_path(request, spec, spec_meta, opts)

@spec critical_path(map(), map(), map(), keyword()) :: {:ok, map()} | {:error, map()}

Estimate the spec critical path using the same limits consumed by runtime.

known_task_entry_keys()

@spec known_task_entry_keys() :: [String.t()]

Accepted keys inside one tasks[] object entry.

resolve_limits(request, spec)

@spec resolve_limits(map(), map()) :: {:ok, map()} | {:error, map()}

Resolve Delegate caller and child limits from the shared runtime precedence rules.

run(request, spec, spec_meta, opts \\ [])

@spec run(map(), map(), map(), keyword()) :: {:ok, map()} | {:error, map()}

Run a validated Delegate spec through the attached runtime path.

start(request, spec, spec_meta, opts \\ [])

@spec start(map(), map(), map(), keyword()) :: {:ok, map()} | {:error, map()}

Start a validated subagents Delegate spec without waiting for terminal completion.

This is the runtime primitive used by the current-BEAM Delegate owner. It creates the durable parent Session, spawns child Subagents through the normal Manager, and returns start evidence plus owner context. It does not start a daemon or a nested Pixir process.