@type compression_opts() :: nil | false | true | module() | {module(), keyword()}

Compression strategy configuration.

Can be:

• nil or false - Compression disabled (default)
• true - Use default strategy (SingleUserCoalesced) with default options
• Module - Use custom strategy module with default options
• {Module, opts} - Use custom strategy module with custom options

See PtcRunner.SubAgent.Compression for details.

@type format_options() :: [
  feedback_limit: pos_integer(),
  feedback_max_chars: pos_integer(),
  history_max_bytes: pos_integer(),
  result_limit: pos_integer(),
  result_max_chars: pos_integer(),
  max_print_length: pos_integer()
]

Output format options for truncation and display.

Fields:

• feedback_limit - Max collection items in turn feedback (default: 10)
• feedback_max_chars - Max chars in turn feedback (default: 512)
• history_max_bytes - Truncation limit for *1/*2/*3 history (default: 512)
• result_limit - Inspect :limit for final result (default: 50)
• result_max_chars - Final string truncation (default: 500)
• max_print_length - Max chars per println call (default: 2000)

@type language_spec() ::
  String.t()
  | atom()
  | {:profile, atom()}
  | {:profile, atom(), keyword()}
  | (map() -> String.t())

Language spec for system prompts.

Can be:

• String: used as-is
• Atom: resolved via PtcRunner.Lisp.LanguageSpec.get!/1 (e.g., :explicit_return, :single_shot)
• Tuple: structured profile {:profile, behavior, opts} — see PtcRunner.Lisp.LanguageSpec.resolve_profile/1
• Function: callback receiving context map with :turn, :model, :memory, :messages

@type llm_ref() :: String.t() | atom() | llm_callback()

LLM reference for SubAgent execution.

Can be:

• String.t() — Model alias (e.g., "haiku") or full ID (e.g., "openrouter:anthropic/claude-haiku-4.5")
• atom() — Registry key (e.g., :haiku) that looks up in llm_registry
• llm_callback() — Direct callback function

@type llm_response() ::
  String.t()
  | %{
      :content => String.t(),
      optional(:tokens) => %{
        optional(:input) => pos_integer(),
        optional(:output) => pos_integer()
      }
    }
  | %{
      :tool_calls => [map()],
      optional(:content) => String.t() | nil,
      optional(:tokens) => map()
    }

LLM response format.

Can be either a plain string (backward compatible) or a map with content and optional tokens. When tokens are provided, they are included in telemetry measurements and accumulated in Step.usage.

For :tool_calling mode, the LLM callback may also return tool calls: %{tool_calls: [%{id: "call_1", name: "search", args: %{"q" => "foo"}}], content: nil | "...", tokens: %{...}}

@type output_mode() :: :ptc_lisp | :text

Output mode for SubAgent execution.

• :ptc_lisp - Default. LLM generates PTC-Lisp code that is executed.
• :text - Auto-detects behavior from tools and signature return type:
  • No tools + :string/no signature → raw text response
  • No tools + complex return type → JSON response (validated)
  • Tools + :string/no signature → tool loop → text answer
  • Tools + complex return type → tool loop → JSON answer

@type plan_step() :: {String.t(), String.t()}

Plan step definition.

Each step is a {id, description} tuple where:

• id is a string identifier (used as key in summaries)
• description is a human-readable description of the step