Skip to content

[feat] agent: correlate Agent turns, tool calls, generation jobs and receipts #372

Open

Description

@yefuyou

Parent roadmap: #261 (Q4 Agent reliability and recovery), refs #107. This is a scoped first slice of the run/tool/job/receipt correlation item discussed under #107, not the entire stop-and-resume effort.

Problem / 现状

OpenDirector already has several useful identities and records:

  • RunContext.turn_id and per-turn harness traces;
  • ToolGateway.call_id and command IDs derived from turn_id + call_id;
  • generation job IDs, command receipts and asset provenance (including agentRunId for some outputs).

However, these pieces are exposed through different paths. The Q4 acceptance goal is to trace a specific Agent turn through its tool/command calls to accepted background jobs and their final business outcomes, including after reopening the project. The first step is to audit what can already be reconstructed and fill only demonstrable gaps. We should not add a parallel tracing system.

Scope / 目标与范围

Start with the Default (bundled OpenCode) single-Agent path and shared business services.

  1. Establish the existing identity chain: turn_id → call_id / commandId → accepted jobId → final job status/result/receipt.
  2. Reuse authoritative identifiers, stored job state, existing traces and read/query APIs wherever sufficient. Add only the minimal missing correlation/persistence or read-only lookup needed for an end-to-end query.
  3. Ensure accepted asynchronous work remains traceable after an Agent turn ends, or after project reload/reopen.
  4. Keep successful, failed, cancelled and interrupted job outcomes distinguishable; do not equate a successful query/tool transport with successful job execution.

Acceptance / 验收标准

  • A deterministic, no-paid-provider test drives a single Agent command that accepts a background generation job, and shows how to locate the corresponding command and job from the originating Agent turn.
  • The same chain resolves to the job's terminal state and existing business receipt/output; IDs remain stable across project reload/reopen.
  • Failed/interrupted outcomes preserve the original accepted job identity and do not appear as successful generation.
  • Existing replay/idempotency semantics are preserved: identical accepted commands are not submitted as new paid jobs merely to reconstruct their outcome.
  • Tests cover the previous gap (fail before a fix where applicable); document the specific read/query path and remaining limitations.

Likely touchpoints / 影响模块

  • packages/core/src/opendirector/agent/{context,gateway,tools}.py
  • packages/core/src/opendirector/application/creation_generation.py and existing job/project queries
  • apps/api/src/opendirector_api/agent.py only if a minimal read endpoint is actually necessary
  • Focused Python regression tests and relevant architecture/CLI docs

Exact files and contract changes depend on the initial audit. Reuse existing job IDs, command receipts and asset provenance rather than introducing speculative new fields.

Out of scope / 不在本次范围

Validation and coordination / 验证与协作

I would like to take this Q4 slice and contribute the implementation.

Metadata

Metadata

Assignees

Labels

area:agentAgent runtime, assistant chat and tools

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions