Pixir.Tools.CommandBoundary (pixir v0.1.5)

Copy Markdown View Source

Bounded host-command boundary for local Tool execution (ADR 0027).

This process is deliberately smaller than a product CommandBroker: it only accounts for external process capacity, bounded queueing, and read-only runtime snapshots. Tool lifecycle, permissions, and canonical tool_call/tool_result Events remain owned by Pixir.Tools.Executor.

Summary

Types

lease()
limits()

Functions

child_spec(init_arg)

Application child spec.

limits(raw)

Normalize user/app config into command-boundary limits.

snapshot(opts \\ [])

Return a read-only snapshot of host-command pressure.

start_link(opts \\ [])

Start a command boundary. Omitting :name starts the application singleton.

with_slot(tool, opts, fun)

Acquire a host-command slot, run fun, and release the slot in all normal return/raise/throw/exit paths.

Types

lease()

@type lease() :: %{id: reference(), host_command: map()}

limits()

@type limits() :: %{
  max_concurrent: pos_integer(),
  queue_limit: non_neg_integer(),
  queue_timeout_ms: non_neg_integer()
}

Functions

child_spec(init_arg)

Application child spec.

limits(raw)

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

Normalize user/app config into command-boundary limits.

snapshot(opts \\ [])

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

Return a read-only snapshot of host-command pressure.

start_link(opts \\ [])

Start a command boundary. Omitting :name starts the application singleton.

with_slot(tool, opts, fun)

@spec with_slot(String.t(), keyword(), (lease() -> term()) | (-> term())) ::
  term() | {:error, map()}

Acquire a host-command slot, run fun, and release the slot in all normal return/raise/throw/exit paths.