Repository navigation
Description
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_idand per-turn harness traces;ToolGateway.call_idand command IDs derived fromturn_id + call_id;- generation job IDs, command receipts and asset provenance (including
agentRunIdfor 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.
- Establish the existing identity chain:
turn_id→call_id / commandId→ acceptedjobId→ final job status/result/receipt. - 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.
- Ensure accepted asynchronous work remains traceable after an Agent turn ends, or after project reload/reopen.
- 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}.pypackages/core/src/opendirector/application/creation_generation.pyand existing job/project queriesapps/api/src/opendirector_api/agent.pyonly 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 / 不在本次范围
- Implementing all stop/cancel/recovery orchestration in [roadmap] Q4 2026 Agent: reliable execution and recoverable collaboration / 可靠执行与可恢复协作 #261, multi-Agent scheduling, or a new OpenTelemetry/trace platform;
- Reworking every harness adapter or adding a new provider;
- Expanding the frontend activity UI;
- Duplicating in-flight work in [bugfix] agent: show one job wait as one activity and fail it when the job fails (#131) #324 (job-wait activity), [feat] agent: publish stage and timeline outputs via shared commands #331 (delivery/provenance), [feat] agent: record token usage, compact project views, and precheck #341 (usage telemetry), or [bugfix] agent: preserve writes across project navigation #322 (project edit leases).
Validation and coordination / 验证与协作
- Audit latest
mainand the overlapping open PRs before changing interfaces. - Prefer local stubs and existing tests; no real GPU or paid provider is required.
- Keep the initial PR small and self-contained, with explicit evidence for the before/after behavior.
- Happy to adjust the slice if maintainers already have work in progress. If possible, please attach this issue as a formal sub-issue of [roadmap] Q4 2026 Agent: reliable execution and recoverable collaboration / 可靠执行与可恢复协作 #261.
I would like to take this Q4 slice and contribute the implementation.
Activity