Structured event stream for recursive calls, capability calls, retries, and terminal states

[axel-havard]

Summary

For embedding predict-rlm into larger systems, human-readable logs are not enough. The runtime needs a structured event stream so hosts can drive live UI, telemetry, debugging, and orchestration decisions.

Problem

An embedding system often needs to observe a run while it is happening:

• what subcall is active
• what capability was just invoked
• whether the runtime retried
• whether validation failed
• whether the run is blocked or completed
• how far along the recursive execution is

Without a machine-readable event stream, hosts have to scrape logs or wait for the final output, which makes integration fragile.

Proposed direction

Expose structured runtime events via callback, iterator, or stream interface.

Suggested event categories:

• run_started
• step_started
• step_completed
• subcall_started
• subcall_completed
• capability_called
• capability_returned
• retry_scheduled
• validation_failed
• run_completed
• run_failed
• run_cancelled

Event properties

Each event should ideally include:

• event type
• run id
• parent step/subcall id if relevant
• timestamps
• status
• token counters if known
• error metadata if relevant

Why this matters

This unlocks:

• live progress UIs
• telemetry dashboards
• host-side logging and analytics
• cancellation heuristics
• approval workflows
• debugging recursive behaviors

Example embedding use case

A larger system could show:

• current recursive branch
• last capability call
• active step duration
• failure reason if a branch dies

without parsing freeform logs.

Acceptance criteria

• runtime exposes a documented machine-readable event stream/callback API
• events cover recursive execution and capability calls
• terminal states are explicit
• event schema is stable/documented
• one example shows live consumption from a host app