feat(trajectory): live trajectories for trajectory/v1

[canersoz-scaleai]

What and why

Today a trajectory only exists after its task ends, so every runtime that wants a live view builds its own read. This moves live trajectories into the framework, and the live view is guaranteed to match the final trajectory.

Protocol

• enable(TRAJECTORY_V1, live=True) adds two cursor reads to get: by task_id or by context_id, each with after and an optional limit. The existing reads are unchanged.
• Agents get a TrajectoryLog on request.trajectory. They call set_format(...) once, then append(event) as events happen; the format can't change after the first event.
• The framework keeps each task's log and state, plus each context's turns in order. The store is bounded to 1,024 contexts, and running ones are never evicted.
• If an agent appends and returns no native_trajectory, the log is its final trajectory. native_trajectory still works for agents that only have one at the end.

Kernel

• follow_trajectory: a reusable follower that polls one task's cursor and hands each batch to a sink until the task ends.
• prompt_agent gets live_trajectory: bool = False. When it's on and the agent supports it, each turn's events are written as chunks under the turn's trajectory prefix while the turn runs, and end.json records how the turn ended, including when the step is cancelled or the follower stops early. When it's off, nothing changes.
• Each turn's next.json names the turn that followed it, or null after the step's last, so a reader can follow a multi-turn step in order and knows when it is over.

How it was tested

• CI's unit, integration-local and integration-local-slow jobs pass. New unit tests cover the cursor reads, states, eviction, cancel, the follower, the chunk, end and link writes, and a check that the log's final trajectory is byte-identical to the equivalent native_trajectory.
• A new integration test runs a two-turn prompt_agent conversation with a deployed agent on the local defaults: each turn is stored under its own prefix while it runs, its chunks join to its final trajectory, and the turns link in order.
• End to end with a CLI agent on a deployed stack, single-turn and two-turn: chunks appeared during each turn, the joined chunks matched each turn's final trajectory byte for byte, and the two turns linked in order.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge, with only the previously reported oversized echo-agent prompt issue remaining.

Findings

1.  Long step count fails turn ▶

Fix with agent prompt

### Issue 1
tst/data/a2a_agent/agent.py:undefined-84
A prompt containing `live-steps ` followed by more than 4,300 digits makes `int()` raise before `MAX_LIVE_STEPS` can cap the count. The echo agent then fails the turn instead of replying. Check the digit count before converting it.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR adds live trajectory logs and cursor reads to the agent framework, then lets prompt_agent save supported agents’ events while each turn runs.

• Agents can append trajectory events while tasks run.
• Prompt runs can save each supported turn’s trajectory as it happens.

Diagram

sequenceDiagram
  participant Step as prompt_agent
  participant Agent as A2A agent
  participant Log as TrajectoryLog
  participant Store as Object store
  Step->>Agent: Send turn
  Agent->>Log: Append events
  loop While the turn runs
    Step->>Agent: Read trajectory cursor
    Agent->>Log: Read next events
    Step->>Store: Write event chunk
  end
  Agent-->>Step: Final task result
  Step->>Store: Write end and next markers

Loading

_{Reviews (7) · Last reviewed commit: "test(a2a_agent): bound the echo agent's ..." · Reviewed by Greptile}

[greptile-apps]

Long step count fails turn

A prompt containing live-steps followed by more than 4,300 digits makes int() raise before MAX_LIVE_STEPS can cap the count. The echo agent then fails the turn instead of replying. Check the digit count before converting it.

Prompt To Fix With AI

This is a comment left during a code review.
Path: tst/data/a2a_agent/agent.py
Line: 84

Comment:
**Long step count fails turn**

A prompt containing `live-steps ` followed by more than 4,300 digits makes `int()` raise before `MAX_LIVE_STEPS` can cap the count. The echo agent then fails the turn instead of replying. Check the digit count before converting it.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[canersoz-scaleai]

Not changing this one: the echo agent is test-only, and the only prompt that sends live-steps is our integration test, with a single digit. MAX_LIVE_STEPS already bounds any realistic count.

[greptile-apps]

That context makes this non-actionable. Since this is a test-only echo agent and the integration input uses a single-digit count, MAX_LIVE_STEPS bounds the exercised behavior as intended. I’m withdrawing the finding; no change is needed for this PR.