Result of executing a PTC program or SubAgent mission.

Returned by both PtcRunner.Lisp.run/2 and PtcRunner.SubAgent.run/2.

Fields

return

The computed result value on success.

• Type: term() | nil

• Set when: Mission/program completed successfully
• Nil when: Execution failed (check fail field)

fail

Error information on failure. See fail/0 for the structure.

• Type: t:fail/0 | nil

• Set when: Execution failed
• Nil when: Execution succeeded

memory

Final memory state after execution.

• Type: map()
• Always set: Contains accumulated memory from all operations
• Access in PTC-Lisp: values available as plain symbols

signature

The contract used for validation.

• Type: String.t() | nil

• Set when: Signature was provided to run/2
• Used for: Type propagation when chaining steps

usage

Execution metrics. See usage/0 for available fields.

• Type: t:usage/0 | nil

• Set when: Execution completed (success or failure after running)
• Nil when: Early validation failure (before execution)

turns

List of Turn structs capturing each LLM interaction cycle. See PtcRunner.Turn.

• Type: [PtcRunner.Turn.t()] | nil

• Set when: SubAgent execution
• Nil when: Lisp execution

trace_id

Unique identifier for this execution (for tracing correlation).

• Type: String.t() | nil

• Set when: SubAgent execution (32-character hex string)
• Nil when: Lisp execution
• Used for: Correlating traces in parallel and nested agent executions

parent_trace_id

ID of parent trace for nested agent calls.

• Type: String.t() | nil

• Set when: This agent was spawned by another agent
• Nil when: Root-level execution (no parent)
• Used for: Linking child executions to their parent

See PtcRunner.Tracer for trace generation and management.

field_descriptions

Descriptions for signature fields, propagated from SubAgent.

• Type: map() | nil

• Set when: SubAgent had field_descriptions option
• Nil when: No field descriptions provided
• Used for: Passing field documentation through chained executions

messages

Full conversation history in OpenAI format.

• Type: [t:message/0] | nil

• Set when: collect_messages: true option passed to SubAgent.run/2
• Nil when: collect_messages: false (default)
• Used for: Debugging, persistence, and displaying the LLM conversation

summaries

Accumulated step-done summaries from semantic progress reporting.

• Type: %{String.t() => String.t()}
• Default: %{}
• Set when: LLM calls (step-done "id" "summary") during execution
• Used for: Progress checklist rendering when agent has a plan

Error Reasons

Complete list of error reasons in step.fail.reason:

Usage Patterns

Success Check

case SubAgent.run(prompt, opts) do
  {:ok, step} ->
    IO.puts("Result: #{inspect(step.return)}")
    IO.puts("Took #{step.usage.duration_ms}ms")

  {:error, step} ->
    IO.puts("Failed: #{step.fail.reason} - #{step.fail.message}")
end

Chaining Steps

Pass a successful step's return and signature to the next step:

{:ok, step1} = SubAgent.run("Find emails",
  signature: "() -> {count :int, _ids [:int]}",
  llm: llm
)

# Option 1: Explicit
{:ok, step2} = SubAgent.run("Process emails",
  context: step1.return,
  context_signature: step1.signature,
  llm: llm
)

# Option 2: Auto-extraction (SubAgent only)
{:ok, step2} = SubAgent.run("Process emails",
  context: step1,  # Extracts return and signature automatically
  llm: llm
)

Accessing Firewalled Data

Fields prefixed with _ are hidden from LLM history but available in return:

{:ok, step} = SubAgent.run("Find emails",
  signature: "() -> {count :int, _email_ids [:int]}",
  llm: llm
)

step.return.count      #=> 5 (visible to LLM)
step.return._email_ids #=> [101, 102, 103, 104, 105] (hidden from LLM)