Pixir.Tools.CommandBoundary (pixir v0.1.17)

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()

presenter_liveness()

Functions

child_spec(init_arg)

Application child spec.

limits(raw)

Normalize user/app config into command-boundary limits.

presenter_liveness(session_id, opts \\ [])

Return live spawned-process presence and milliseconds remaining in its own cap.

presenter_liveness?(session_id, opts \\ [])

Whether a Session has a live spawned process still within its own execution cap.

register_process(map, session_id, port, timeout_ms, grace_ms)

Register the spawned process backing an active host-command lease.

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(), boundary: GenServer.server()}

limits()

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

presenter_liveness()

@type presenter_liveness() :: :dead | {:live, 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.

presenter_liveness(session_id, opts \\ [])

@spec presenter_liveness(
  String.t(),
  keyword()
) :: presenter_liveness()

Return live spawned-process presence and milliseconds remaining in its own cap.

presenter_liveness?(session_id, opts \\ [])

@spec presenter_liveness?(
  String.t(),
  keyword()
) :: boolean()

Whether a Session has a live spawned process still within its own execution cap.

register_process(map, session_id, port, timeout_ms, grace_ms)

@spec register_process(
  lease(),
  String.t(),
  port(),
  non_neg_integer(),
  non_neg_integer()
) :: :ok

Register the spawned process backing an active host-command lease.

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.