Skip to content

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

Merged
FayeSpica merged 4 commits into
ThinkFlowLab:mainfrom
yefuyou:feat/372-agent-job-lineage
Nov 19, 2026
Merged

FayeSpica merged 4 commits into
ThinkFlowLab:mainfrom
yefuyou:feat/372-agent-job-lineage

Conversation

@yefuyou

@yefuyou yefuyou commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

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.

Comment thread apps/api/src/opendirector_api/agent.py Resolved
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

@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.

Tested manually. LGTM!

As a follow-up, could we show all turns in a conversation on one trace page, like DSH does?

@FayeSpica
FayeSpica merged commit ab3f058 into ThinkFlowLab:main Nov 19, 2026
12 checks passed
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