@type compaction_opts() :: nil | false | true | keyword()

Compaction configuration for multi-turn agents.

Pressure-triggered context compaction. Compaction reduces the LLM-input message list when turn count or estimated token usage crosses a threshold.

Can be:

• nil or false - Compaction disabled (default)
• true - Use the :trim strategy with default options
• keyword() - Use the :trim strategy with custom options

See PtcRunner.SubAgent.Compaction for option details and validation rules. Phase 1 supports strategy: :trim only; custom strategy modules and :summarize are deferred.

@type completion_mode() :: :implicit | :explicit

Completion contract for PTC-Lisp SubAgents.

• :implicit preserves historic behavior: a final bare expression can complete single-shot agents.
• :explicit is reserved for hosts that require (return ...) or (fail ...) terminal forms. Phase 0 defines the contract; Worker A owns full explicit-mode enforcement.

@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(),
  mission_log_in: :system_prompt | :user_message
]

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)
• mission_log_in - Where to inject the mission log: :system_prompt (default) or :user_message

@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

@type ptc_reference() :: :compact

PTC-Lisp reference card mode for combined-mode (output: :text, ptc_transport: :tool_call) system prompts.

• :compact — bounded reference card (≤300 tokens), default in combined mode. Describes the core forms (def, tool/, return, println) and the full_result_cached: true cache-reuse pattern.

v1 supports only :compact; :full is deferred (the validator raises ArgumentError on :full). See Addendum #1 of Plans/text-mode-ptc-compute-tool.md.

@type ptc_transport() :: :content | :tool_call

Transport mode for output: :ptc_lisp agents.

• :content - Default. LLM emits a markdown-fenced PTC-Lisp program in the assistant message content; the loop parses and executes it.
• :tool_call - LLM invokes the internal lisp_eval native tool with a program argument; final answers are returned as direct content and validated against signature:. Valid only with output: :ptc_lisp.

See docs/plans/ptc-lisp-tool-call-transport.md for the full design.