Skip to content

[feat] agent: persist Agent turn and tool-call lineage for generation Jobs - #374

Open
yefuyou wants to merge 4 commits into
ThinkFlowLab:mainfrom
yefuyou:feat/372-agent-job-lineage
Open

yefuyou wants to merge 4 commits into
ThinkFlowLab:mainfrom
yefuyou:feat/372-agent-job-lineage

Conversation

@yefuyou

@yefuyou yefuyou commented Nov 16, 2026 •

Copy link
Copy Markdown

Summary

  • Persist the originating Agent turn and tool-call identity on Agent-submitted generation Jobs as optional agentRunId and agentCallId fields. Both are set together and omitted when unset, preserving existing non-Agent Job serialization.
  • Centralize the existing uuid5(run_id, call_id) Command ID derivation without changing Command payloads, fingerprints, idempotency or recovery decisions.
  • Add read-only GET /api/creation/projects/{project_id}/assistant/turns/{turn_id}/jobs to list Jobs submitted by a turn from committed project state. It does not read Agent traces, replay commands, acquire an editing lease, or invoke a provider.
  • Connect the turn-to-Jobs endpoint to the existing Agent Trace page, showing linked Job status, results and errors in English and Chinese; document the lineage and compatibility limits and cover the behavior with regression tests.

Linked issue

Fixes #372
Refs #261, #107

  • Fixes #N or Refs #N is included, or no issue applies

Labels

Requested: type:feat, area:agent.

  • Labels applied

Test plan

  • Local: tests/test_agent_job_lineage.py: 12 passed using provider doubles. Mutation check: 9 of 12 fail when the production-origin write is removed. Tests cover trace deletion, multiple Jobs, terminal failures, commit-journal crash recovery, restart without duplicate submission, legacy records, and read-only querying.
  • Local: scripts/generate_contracts.py --check passed; lint-imports passed (4 contracts, 0 broken); git diff --check passed.
  • Full Python suite was run against both this branch and an upstream baseline in the same test environment. Branch: 1,953 passed / 164 failed / 84 errors; baseline: 1,942 passed / 163 failed / 84 errors. The additional failing test also fails when run individually against the baseline. The remaining failures/errors were not individually root-caused; this is not a claim that the full suite passes, or that every failure is environmental.
  • Trace UI follow-up (commit 4c6c6a56): 6 new frontend pure-function tests; TypeScript check (tsc --noEmit), npm run build, npm run check:i18n, and browser verification were reported as passing. npm test: 824 passed, 2 failed; the same two tests also fail without this change. npm ci --ignore-scripts was used because the install scripts failed in the local environment.
  • Not run locally: pre-commit (hook repo could not be cloned), live provider tests, and a complete FFmpeg-enabled suite. CI was waiting for maintainer approval at last report.

Evidence that it works

  • Real browser screenshots attached below. OpenDirector's backend API and Vite frontend were running locally; these screenshots were captured in headless Chromium from the actual Trace page, not mockups. The example explicitly uses DEMO data and a local provider double, not a real model/provider.
  • The Trace page displays Linked jobs under the relevant Agent turn. It shows the Job ID, status, generated asset type/ID/revision and adoption state for completed Jobs, and the error message for failed Jobs. Turns with no Jobs have no extra section; a failed Job lookup does not break the trace.
  • Browser verification reported for en-US, zh-CN, a 420px narrow viewport, and refresh after API restart. Images are stored on a separate evidence branch, not included in this PR's code diff.

English, Agent Trace with linked completed and failed Jobs

OpenDirector Agent trace: linked jobs, English DEMO

简体中文,助手轨迹及关联任务状态

OpenDirector 助手轨迹:关联任务,中文演示数据

Provider verification

  • No real-provider calls were made. Generation was tested with local model/provider doubles; live-provider behavior remains unverified.

Bilingual UI

  • Trace page UI copy was added in both en-US and zh-CN.

Design and compatibility notes

  • Origin is written only when the Agent host accepts generation.submit; Job checkpoint, cancellation and result publication preserve the fields. job.cancel, job.recover, HTTP Command payloads and non-Agent Jobs do not introduce an origin.
  • Job-to-turn lookup uses the existing Job read/snapshot data. The new turn-to-Jobs endpoint filters persisted Jobs and never needs runtime traces.
  • Forward compatibility: newer code can load legacy projects, and Jobs without origin serialize unchanged. Older OpenDirector builds cannot open projects containing the new Job origin fields and may return storage_unavailable because their Job model rejects unknown fields. The repository currently has no general project downgrade mechanism. Please confirm that this format-upgrade behavior is acceptable; users should back up project data before attempting to open it with an older build.
  • Previously created Agent Jobs do not receive an origin retroactively. This change does not implement automatic recovery orchestration, multi-Agent scheduling, or a separate tracing platform.

… Jobs

Job gains optional agentRunId and agentCallId, written together when an Agent
generation.submit creates the job, so a job can be traced to its turn and
call from committed project data without the Agent trace. Command fields and
fingerprints are unchanged; jobs without an origin serialize as before.
GET .../assistant/turns/{turn_id}/jobs reads the project snapshot only and
returns the Jobs whose agentRunId matches, ordered by creation time. It never
reads the Agent trace and never starts, resumes or replays a command.

@FayeSpica FayeSpica left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for making Agent-submitted jobs traceable across restarts—please fix the CI formatting failure so the remaining checks can run.

raise ProjectError('轨迹文件不存在。', 404)
return FileResponse(file, media_type='text/plain', headers={'Cache-Control': 'no-store'})

@router.get('/turns/{turn_id}/jobs')

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a follow-up, could we connect this endpoint to the trace page so each turn shows its linked Jobs, their status, results and errors?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion! I've included the Trace page integration in this PR in commit 4c6c6a56. Each turn now shows its linked Jobs with IDs, statuses, generated asset details (kind, ID, revision) and failure messages. The section stays hidden when no Jobs are linked, and a lookup failure doesn't disrupt the trace. Both en-US and zh-CN are covered.

I also fixed the EOF formatting issue in tools.py and added real browser screenshots (using clearly labeled demo/provider-double data) to the PR's Evidence that it works section. The new CI run is awaiting maintainer approval, so the full checks are not yet confirmed. Would appreciate another look when you have a chance!

Fetch /assistant/turns/{turn}/jobs on the Trace page and list status, result and
error per Job. Also remove the extra blank line at EOF of agent/tools.py that
failed the end-of-file pre-commit hook.
@github-actions github-actions Bot added area:agent Agent runtime, assistant chat and tools type:feat New capability or behaviour labels Nov 17, 2026
@github-actions
github-actions Bot requested a review from wuzhf9 November 17, 2026 01:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:agent Agent runtime, assistant chat and tools type:feat New capability or behaviour

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

3 participants