diff --git a/apps/api/src/opendirector_api/agent.py b/apps/api/src/opendirector_api/agent.py
index 7ef36a60b..8be7c4665 100644
--- a/apps/api/src/opendirector_api/agent.py
+++ b/apps/api/src/opendirector_api/agent.py
@@ -14,6 +14,7 @@
from opendirector.agent.catalog import model_choices
from opendirector.agent.context import RunContext, RuntimeId
+from opendirector.domain.creation.base import agent_command_id
from opendirector.agent.citations import referenced_sources, with_trace_sources
from opendirector.agent.runtime import AgentRuntimes, runtime_available, configured_runtimes, runtime_spec, runtime_catalog, runtime_status
from opendirector.agent.skills import skills
@@ -257,6 +258,18 @@ def trace(project_id: UUID, turn_id: UUID,
raise ProjectError('轨迹文件不存在。', 404)
return FileResponse(file, media_type='text/plain', headers={'Cache-Control': 'no-store'})
+ @router.get('/turns/{turn_id}/jobs')
+ def turn_jobs(project_id: UUID, turn_id: UUID):
+ # Read-only like the trace routes: no session lease, and the Agent trace is not consulted.
+ # It reads the committed snapshot and never starts, resumes or replays a command.
+ jobs = sorted((job for job in projects.snapshot(project_id).jobs if job.agentRunId == turn_id),
+ key=lambda job: (job.createdAt, str(job.id)))
+ return [dict(jobId=job.id, callId=job.agentCallId, commandId=agent_command_id(turn_id, job.agentCallId),
+ status=job.status, phase=job.phase, recovery=job.recovery, resumeAllowed=job.resumeAllowed,
+ cancelRequested=job.cancelRequested, remoteCancellation=job.remoteCancellation,
+ errorDetails=job.errorDetails, asset=job.asset, adopted=job.adopted)
+ for job in jobs]
+
active: dict[UUID, tuple[UUID, asyncio.Task, RunEvents]] = {}
admission: dict[UUID, asyncio.Lock] = {}
diff --git a/docs/README.md b/docs/README.md
index cc14c4725..4d13e5f83 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -30,7 +30,7 @@ This directory is the entry point for the repository's shared documentation. The
| [BigModel video](guides/bigmodel-video.md) ([中文](guides/bigmodel-video.zh-CN.md)) | CogVideoX-3 text, single-image and first/last-frame generation, task recovery and adoption | BigModel protocol, inputs, output sizes or recovery behavior change |
| [BigModel GLM-Image](guides/bigmodel-image.md) ([中文](guides/bigmodel-image.zh-CN.md)) | Account setup, text-to-image generation, adoption and recovery | BigModel integration fields or behavior change |
| [GLM-Image validation](development/glm-image-validation.md) | Real provider workflow screenshots and automated checks | GLM-Image acceptance is repeated |
-| [Agent runtime](architecture/agent-runtime.md) | Agent runtime architecture | Runtime architecture changes |
+| [Agent runtime](architecture/agent-runtime.md) | Agent runtime architecture and Job origin tracing | Runtime architecture or Job origin semantics change |
The root [README](../README.md) introduces the product and examples and links to quick-start and documentation. See [installation and updates](guides/installation.md) ([中文](guides/installation.zh-CN.md)) for installation, and the [user guide](guides/user-guide.md) ([中文](guides/user-guide.zh-CN.md)) for configuration, creation, and troubleshooting. The README does not contain the full manual, implementation architecture, development tests, research sources, or iteration history. Source code and generated contracts describe the implementation; architecture and roadmap documents describe goals and do not establish that a capability is already available.
diff --git a/docs/architecture/agent-runtime.md b/docs/architecture/agent-runtime.md
index 3f86072af..113e13d87 100644
--- a/docs/architecture/agent-runtime.md
+++ b/docs/architecture/agent-runtime.md
@@ -57,6 +57,31 @@ Default 的模型网关在 `agent-runs/.model.jsonl` 记录实际转发
停止或流连接断开时,适配层终止进程组,Gateway 关闭新调用入口并等待已接受操作结束;API 保存部分回复并释放运行占用。业务操作以各自回执确认,远端生成任务仍通过任务取消命令处理。
+## Agent 来源追溯
+
+Agent 的 `generation.submit` 接受任务时,把本轮标识和工具调用标识写入 Job 自身:
+
+| 字段 | 含义 |
+| --- | --- |
+| `agentRunId` | 提交该任务的 Agent 轮次(turn)ID |
+| `agentCallId` | 该轮内的工具调用 ID,CLI 调用形如 `cli:` |
+
+两个字段同时存在或同时缺失,缺失时不出现在序列化结果中,旧数据的序列化不变。命令 ID 仍由 `agent_command_id(agentRunId, agentCallId)`(即 UUID5)推导,也是幂等键;Command 本身没有新增字段,指纹和幂等规则不变。来源与 Job、回执、快照、事件在同一次提交中落盘,经提交日志恢复后仍在。`job.cancel`、`job.recover` 不改写来源。
+
+两个方向的查询都只读取已提交的工程数据,不读取 Agent 轨迹:
+
+- Job → 轮次:`job.get` 或工程快照中的 `agentRunId`、`agentCallId`。
+- 轮次 → Job:`GET /api/creation/projects/{project_id}/assistant/turns/{turn_id}/jobs`,返回该轮提交的 Job(按创建时间、ID 排序):`jobId`、`callId`、`commandId`、`status`、`phase`、`recovery`、`resumeAllowed`、`cancelRequested`、`remoteCancellation`、`errorDetails`、`asset`、`adopted`。工程不存在按既有错误语义返回 404;轮次没有任务返回空列表。该路由与轨迹路由一样不申请编辑会话,不执行、不重放命令,也不启动 Provider。
+
+兼容性:
+
+- 此前创建的 Job 没有来源,只能通过 Agent 轨迹追溯;不回填。
+- 旧工程在新版本中可正常打开。
+- 含来源字段的工程不能被更早的 OpenDirector 版本打开:Job 模型禁止未知字段,旧版会以存储不可用拒绝该工程。项目格式没有版本号或降级机制,按 [AGENTS.md](../../AGENTS.md) 的约定不静默忽略字段,也不提供兼容层。需要回退版本时,先备份工程目录。
+- Agent 轨迹是调试文件,不是业务事实来源,删除它不影响上述查询。
+
+English summary: a Job created by an Agent `generation.submit` records `agentRunId` (turn) and `agentCallId` (tool call), both or neither, and omits them when absent so existing jobs serialize unchanged. The command ID is still `uuid5(run id, call id)` and no Command field was added. Job to turn uses `job.get` or the snapshot. Turn to jobs uses the read-only `GET .../assistant/turns/{turn_id}/jobs`, which reads the committed snapshot, needs no editing session, never replays a command and does not read the Agent trace. Jobs created before this change have no origin and remain traceable only through the trace. Older OpenDirector builds reject a project containing these fields because Job forbids unknown fields; the project format has no version or downgrade mechanism, so back up a project before opening it with an older build.
+
## 原生工具权限
| Harness | 执行约束 |
diff --git a/packages/core/src/opendirector/agent/tools.py b/packages/core/src/opendirector/agent/tools.py
index 64da5bd17..bd91e9041 100644
--- a/packages/core/src/opendirector/agent/tools.py
+++ b/packages/core/src/opendirector/agent/tools.py
@@ -7,6 +7,7 @@
from uuid import UUID, uuid5
from pydantic import JsonValue, TypeAdapter, ValidationError
+from opendirector.domain.creation.base import agent_command_id
from opendirector.application.creation_artifacts import publish_artifact
from opendirector.application.creation_assets import CreationAssets
from opendirector.application.creation_timeline_packages import CreationTimelinePackages
@@ -407,10 +408,12 @@ def narrow(value: JsonValue) -> None:
if name != 'execute_command':
raise ProjectError('未知业务工具。')
command = parse_command({**arguments, 'projectId': str(project_id),
- 'commandId': str(uuid5(turn_id, call_id))})
+ 'commandId': str(agent_command_id(turn_id, call_id))})
if command.type == 'creation.batch' and any(operation.type not in COMMANDS for operation in command.payload.operations):
raise ProjectError('批量命令包含未开放的 Agent 操作。', 403)
- if command.type in {'generation.submit', 'job.cancel', 'job.recover'}:
+ if command.type == 'generation.submit':
+ receipt = await self.generation.execute(command, session=session, source='agent', agent_origin=(turn_id, call_id))
+ elif command.type in {'job.cancel', 'job.recover'}:
receipt = await self.generation.execute(command, session=session, source='agent')
elif command.type in {'asset.writeText', 'artifact.publish'}:
if config is not None:
@@ -429,4 +432,3 @@ def narrow(value: JsonValue) -> None:
else:
receipt = await asyncio.to_thread(self.projects.execute, command, session=session, source='agent')
return receipt.model_dump(mode='json')
-
diff --git a/packages/core/src/opendirector/application/creation_generation.py b/packages/core/src/opendirector/application/creation_generation.py
index fb5fb207e..2e58106b8 100644
--- a/packages/core/src/opendirector/application/creation_generation.py
+++ b/packages/core/src/opendirector/application/creation_generation.py
@@ -318,7 +318,7 @@ async def _run(self, task, pinned, config, mode='submit'):
remote.release()
claim.release()
- def prepare(self, command, *, session=None, source='ui'):
+ def prepare(self, command, *, session=None, source='ui', agent_origin=None):
replay = self.projects.replay(command)
if replay is not None:
return replay
@@ -394,6 +394,7 @@ def accept(before):
createdAt=datetime.now(timezone.utc),
inputFingerprint=snapshot.fingerprint(), execution={'kind': spec.kind, **({'size': '2K'} if spec.kind == 'image' else {'format': 'mp3', 'sampleRate': 24000} if spec.kind == 'audio' else {})},
originItemId=origin, previousJobId=command.payload.previousJobId,
+ **({'agentRunId': agent_origin[0], 'agentCallId': agent_origin[1]} if agent_origin else {}),
adoptionPolicy=command.payload.adoptionPolicy, adoptionResultId=old.currentResultId, adoptionMaterial=material,
batchId=command.payload.batchId, showAdditionalResult=command.payload.showAdditionalResult)
task = self.task(stub)
@@ -409,9 +410,9 @@ def accept(before):
return ProjectSnapshot.model_validate(data)
return self.projects.commit(command, accept, session=session, source=source)
- async def execute(self, command, *, session=None, source='ui'):
+ async def execute(self, command, *, session=None, source='ui', agent_origin=None):
if command.type == 'generation.submit':
- pending = asyncio.create_task(asyncio.to_thread(self.prepare, command, session=session, source=source))
+ pending = asyncio.create_task(asyncio.to_thread(self.prepare, command, session=session, source=source, agent_origin=agent_origin))
async def finish():
try:
receipt = await pending
diff --git a/packages/core/src/opendirector/domain/creation/base.py b/packages/core/src/opendirector/domain/creation/base.py
index 100c4275e..6e71c6895 100644
--- a/packages/core/src/opendirector/domain/creation/base.py
+++ b/packages/core/src/opendirector/domain/creation/base.py
@@ -1,6 +1,6 @@
"""Versioned JSON contracts for the new project format; no storage or UI code."""
from typing import Annotated, Literal
-from uuid import UUID
+from uuid import UUID, uuid5
import hashlib
import json
@@ -72,6 +72,11 @@ def digest(value: Contract, *, exclude=None) -> str:
return hashlib.sha256(encoded).hexdigest()
+def agent_command_id(run_id: UUID, call_id: str) -> UUID:
+ """Command identity the host derives for one Agent tool call; it is also the idempotency key."""
+ return uuid5(run_id, call_id)
+
+
def unique(values, label):
if len(values) != len(set(values)):
raise ValueError(f'Duplicate {label}')
diff --git a/packages/core/src/opendirector/domain/creation/generation.py b/packages/core/src/opendirector/domain/creation/generation.py
index 91b6f0b40..cccd178f5 100644
--- a/packages/core/src/opendirector/domain/creation/generation.py
+++ b/packages/core/src/opendirector/domain/creation/generation.py
@@ -301,9 +301,13 @@ class Job(ProjectEntity):
adoptionMaterial: AssetRef | None = Field(default=None, description='Material version reserved for adoption.')
adopted: bool = Field(default=False, description='Whether the generated result was adopted.')
adapterParameters: dict[str, JsonValue] = Field(default_factory=dict, description='Fixed provider-specific execution parameters.')
+ agentRunId: UUID | None = Field(default=None, exclude_if=lambda value: value is None, description='Agent turn that submitted this job; omitted for jobs not submitted by an Agent.')
+ agentCallId: str | None = Field(default=None, min_length=1, max_length=512, exclude_if=lambda value: value is None, description='Tool call within that turn that submitted this job; the command ID derives from both.')
@model_validator(mode='after')
def execution_identity(self):
+ if (self.agentRunId is None) != (self.agentCallId is None):
+ raise ValueError('Agent run and call identity are recorded together')
if self.showAdditionalResult and (self.originItemId is None or self.adoptionPolicy != 'candidate_only'):
raise ValueError('Additional result display requires an origin and candidate-only adoption')
if self.inputSnapshot.spec.projectId != self.projectId:
diff --git a/src/canvas/AssistantTracePage.tsx b/src/canvas/AssistantTracePage.tsx
index 664972120..e1560dca8 100644
--- a/src/canvas/AssistantTracePage.tsx
+++ b/src/canvas/AssistantTracePage.tsx
@@ -8,6 +8,8 @@ import { normalizeClaudeTrace } from "./claudeTrace.ts";
import { normalizeCodexTrace } from "./codexTrace.ts";
import { normalizeDeepseekTrace } from "./deepseekTrace.ts";
+import { readTurnJobs, turnJobView, type TurnJob } from "./traceJobs.ts";
+
import "./assistant-trace.css";
type TraceRecord = {
@@ -183,6 +185,28 @@ function TraceEntries({ traces, rawModel }: { traces: string[]; rawModel: boolea
});
}
+function TraceJobs({ jobs }: { jobs: TurnJob[] }) {
+ const t = useT();
+ return (
+
+ {t("trace.jobs.title")}
+ {jobs.map((job) => {
+ const view = turnJobView(job, t);
+ return (
+
+ {view.statusText}
+
+ {job.jobId}
+ {[view.assetText, view.adoptedText, view.cancelText, view.errorText]
+ .filter(Boolean).map((text) => ` · ${text}`).join("")}
+
+
+ );
+ })}
+
+ );
+}
+
export default function AssistantTracePage({ params }: { params: URLSearchParams }) {
const project = params.get("traceProject") ?? "";
const turn = params.get("turn") ?? "";
@@ -193,6 +217,7 @@ export default function AssistantTracePage({ params }: { params: URLSearchParams
const [showModel, setShowModel] = useState(false);
const rawModel = runtime === "opencode" && showModel;
const [status, setStatus] = useState(null);
+ const [jobs, setJobs] = useState([]);
const t = useT();
useEffect(() => {
@@ -209,18 +234,23 @@ export default function AssistantTracePage({ params }: { params: URLSearchParams
}).catch(() => {});
setStatus(null);
setTraces([]);
+ setJobs([]);
let timer: number | undefined;
async function refresh() {
try {
if (live && document.hidden) return;
+ const jobsRequest = fetch(`/api/creation/projects/${projectPath}/assistant/turns/${turnPath}/jobs`, options)
+ .then(readTurnJobs, () => [] as TurnJob[]);
const snapshots = await Promise.all(sources.map(async (name) => {
const response = await fetch(`${traceUrl}/${encodeURIComponent(name)}`, options);
const body = response.ok ? await response.text() : "";
return { status: response.status, body: name === "deepseek" ? normalizeDeepseekTrace(body) : name === "codex" ? normalizeCodexTrace(body) : name === "claude" ? normalizeClaudeTrace(body) : body };
}));
+ const nextJobs = await jobsRequest;
const status = snapshots.some((item) => item.status === 200) ? 200 : snapshots[0].status;
if (controller.signal.aborted) return;
setStatus(status);
+ setJobs((previous) => JSON.stringify(previous) === JSON.stringify(nextJobs) ? previous : nextJobs);
const bodies = snapshots.map((item) => item.body);
setTraces((previous) => bodies.every((body, index) => body === previous[index]) ? previous : bodies);
} catch {
@@ -265,6 +295,7 @@ export default function AssistantTracePage({ params }: { params: URLSearchParams
status === 404 ? t("trace.notFound") :
t("trace.loadFailed")}
)}
+ {jobs.length > 0 && }
);
}
diff --git a/src/canvas/assistant-trace.css b/src/canvas/assistant-trace.css
index ded0a451d..665cb1662 100644
--- a/src/canvas/assistant-trace.css
+++ b/src/canvas/assistant-trace.css
@@ -75,3 +75,9 @@
.cw-trace-command-detail pre { margin: 0; padding: 10px 12px; border-radius: 6px; background: #191919; white-space: pre-wrap; overflow-wrap: anywhere; }
.cw-trace-command-detail p { font-size: 12px; color: #aaa; }
@media (max-width: 600px) { .cw-trace-command-detail { padding-left: 20px; } }
+.cw-trace-job { display: grid; grid-template-columns: 76px minmax(0, 1fr); gap: 12px; padding: 6px 20px; align-items: center; }
+.cw-trace-jobs { margin-top: 16px; border-top: 1px solid #333; }
+.cw-trace-jobs h2 { margin: 0; padding: 10px 20px 6px; font-size: 14px; }
+.cw-trace-job .cw-trace-preview { white-space: normal; overflow-wrap: anywhere; }
+.cw-trace-badge.is-job-succeeded { background: #254034; color: #91d6ab; }
+.cw-trace-badge.is-job-failed, .cw-trace-badge.is-job-interrupted { background: #4d2a2a; color: #f0a3a3; }
diff --git a/src/canvas/traceJobs.ts b/src/canvas/traceJobs.ts
new file mode 100644
index 000000000..67f52272e
--- /dev/null
+++ b/src/canvas/traceJobs.ts
@@ -0,0 +1,68 @@
+/** Display fields for the Jobs a Turn submitted, shown on the Trace page. */
+import type { AssetRef, GenerationFailure } from "../contracts/generated.ts";
+import type { Translate } from "../i18n/I18nProvider.tsx";
+import type { MessageKey } from "../i18n/types.ts";
+import { generationFailureMessage } from "./generationFailureText.ts";
+
+export type TurnJobStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "interrupted";
+
+/** One item of GET /assistant/turns/{turn}/jobs. */
+export type TurnJob = {
+ jobId: string;
+ callId: string;
+ commandId: string;
+ status: TurnJobStatus;
+ phase?: string | null;
+ recovery?: string | null;
+ resumeAllowed?: boolean;
+ cancelRequested?: boolean;
+ remoteCancellation?: string | null;
+ errorDetails: GenerationFailure | null;
+ asset: AssetRef | null;
+ adopted: boolean;
+};
+
+const STATUS_KEYS: Record = {
+ queued: "trace.jobs.status.queued",
+ running: "trace.jobs.status.running",
+ succeeded: "trace.jobs.status.succeeded",
+ failed: "trace.jobs.status.failed",
+ cancelled: "trace.jobs.status.cancelled",
+ interrupted: "trace.jobs.status.interrupted",
+};
+
+export type TurnJobView = {
+ key: string;
+ status: TurnJobStatus;
+ statusText: string;
+ assetText: string | null;
+ errorText: string | null;
+ adoptedText: string | null;
+ cancelText: string | null;
+};
+
+export function turnJobView(job: TurnJob, t: Translate): TurnJobView {
+ const status = job.status in STATUS_KEYS ? job.status : "failed";
+ return {
+ key: job.jobId,
+ status,
+ statusText: t(STATUS_KEYS[status]),
+ assetText: job.asset
+ ? t("trace.jobs.asset", { kind: job.asset.kind, assetId: job.asset.assetId, revision: job.asset.revision })
+ : null,
+ errorText: job.errorDetails ? generationFailureMessage(job.errorDetails, t) : null,
+ adoptedText: job.asset ? t(job.adopted ? "trace.jobs.adopted" : "trace.jobs.notAdopted") : null,
+ cancelText: job.cancelRequested && status !== "cancelled" ? t("trace.jobs.cancelRequested") : null,
+ };
+}
+
+/** Parse a jobs response; any failure yields no jobs so the trace is unaffected. */
+export async function readTurnJobs(response: Pick): Promise {
+ if (!response.ok) return [];
+ try {
+ const body: unknown = await response.json();
+ return Array.isArray(body) ? body.filter((job) => job && typeof job.jobId === "string") : [];
+ } catch {
+ return [];
+ }
+}
diff --git a/src/contracts/creation.schema.json b/src/contracts/creation.schema.json
index 5eb935515..f4d80b7de 100644
--- a/src/contracts/creation.schema.json
+++ b/src/contracts/creation.schema.json
@@ -7182,6 +7182,35 @@
"description": "Fixed provider-specific execution parameters.",
"title": "Adapterparameters",
"type": "object"
+ },
+ "agentRunId": {
+ "anyOf": [
+ {
+ "format": "uuid",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Agent turn that submitted this job; omitted for jobs not submitted by an Agent.",
+ "title": "Agentrunid"
+ },
+ "agentCallId": {
+ "anyOf": [
+ {
+ "maxLength": 512,
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Tool call within that turn that submitted this job; the command ID derives from both.",
+ "title": "Agentcallid"
}
},
"required": [
@@ -22551,6 +22580,35 @@
"description": "Fixed provider-specific execution parameters.",
"title": "Adapterparameters",
"type": "object"
+ },
+ "agentRunId": {
+ "anyOf": [
+ {
+ "format": "uuid",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Agent turn that submitted this job; omitted for jobs not submitted by an Agent.",
+ "title": "Agentrunid"
+ },
+ "agentCallId": {
+ "anyOf": [
+ {
+ "maxLength": 512,
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Tool call within that turn that submitted this job; the command ID derives from both.",
+ "title": "Agentcallid"
}
},
"required": [
diff --git a/src/contracts/generated.ts b/src/contracts/generated.ts
index 3e5a30968..a5090d528 100644
--- a/src/contracts/generated.ts
+++ b/src/contracts/generated.ts
@@ -720,6 +720,8 @@ export interface JobInput extends ProjectEntityInput {
readonly adoptionMaterial?: AssetRefInput | null;
readonly adopted?: boolean;
readonly adapterParameters?: Readonly>;
+ readonly agentRunId?: string | null;
+ readonly agentCallId?: string | null;
}
export interface JobCancelCommandInput extends CommandBaseInput {
@@ -2295,6 +2297,8 @@ export interface Job extends ProjectEntity {
readonly adoptionMaterial: AssetRef | null;
readonly adopted: boolean;
readonly adapterParameters: Readonly>;
+ readonly agentRunId?: string | null;
+ readonly agentCallId?: string | null;
}
export interface JobCancelCommand extends CommandBase {
diff --git a/src/i18n/messages/en-US/trace.ts b/src/i18n/messages/en-US/trace.ts
index bee2395d6..f372cd081 100644
--- a/src/i18n/messages/en-US/trace.ts
+++ b/src/i18n/messages/en-US/trace.ts
@@ -24,6 +24,17 @@ export const trace = {
"trace.views": "Trace views",
"trace.rawRequests": "Raw model requests",
"trace.noModelRequests": "No model requests recorded for this turn.",
+ "trace.jobs.title": "Linked jobs",
+ "trace.jobs.status.queued": "Queued",
+ "trace.jobs.status.running": "Running",
+ "trace.jobs.status.succeeded": "Completed",
+ "trace.jobs.status.failed": "Failed",
+ "trace.jobs.status.cancelled": "Cancelled",
+ "trace.jobs.status.interrupted": "Interrupted",
+ "trace.jobs.asset": "Result: {kind} {assetId} r{revision}",
+ "trace.jobs.adopted": "Adopted",
+ "trace.jobs.notAdopted": "Not adopted",
+ "trace.jobs.cancelRequested": "Cancel requested",
"trace.loading": "Loading…",
"trace.waiting": "Waiting for trace events…",
"trace.notFound": "No trace of this type for this turn.",
diff --git a/src/i18n/messages/zh-CN/trace.ts b/src/i18n/messages/zh-CN/trace.ts
index 2ba9f661b..f57d9c508 100644
--- a/src/i18n/messages/zh-CN/trace.ts
+++ b/src/i18n/messages/zh-CN/trace.ts
@@ -24,6 +24,17 @@ export const trace = {
"trace.views": "轨迹视图",
"trace.rawRequests": "模型原始请求",
"trace.noModelRequests": "该轮暂无模型请求记录。",
+ "trace.jobs.title": "关联任务",
+ "trace.jobs.status.queued": "排队中",
+ "trace.jobs.status.running": "运行中",
+ "trace.jobs.status.succeeded": "已完成",
+ "trace.jobs.status.failed": "失败",
+ "trace.jobs.status.cancelled": "已取消",
+ "trace.jobs.status.interrupted": "已中断",
+ "trace.jobs.asset": "结果:{kind} {assetId} r{revision}",
+ "trace.jobs.adopted": "已采用",
+ "trace.jobs.notAdopted": "未采用",
+ "trace.jobs.cancelRequested": "已请求取消",
"trace.loading": "加载中…",
"trace.waiting": "等待首条轨迹…",
"trace.notFound": "该轮没有此类轨迹。",
diff --git a/tests/test_agent_job_lineage.py b/tests/test_agent_job_lineage.py
new file mode 100644
index 000000000..e0fe0f3a4
--- /dev/null
+++ b/tests/test_agent_job_lineage.py
@@ -0,0 +1,319 @@
+"""A job accepted for an Agent tool call keeps that call's identity in its own committed record.
+
+The Agent trace is a debugging artifact. These tests never read it: the originating turn, call
+and command are recovered from the project's committed state alone, including after a crash and
+a restart. Provider doubles only; nothing leaves the process.
+"""
+import asyncio
+import json
+from uuid import UUID, uuid4, uuid5
+
+from fastapi.testclient import TestClient
+import pytest
+
+from opendirector.agent.tools import AgentTools
+from opendirector.application.creation_generation import CreationGeneration
+from opendirector.domain.creation.base import agent_command_id
+from opendirector.domain.creation.commands import parse_command
+from opendirector.domain.creation.generation import Job
+from opendirector.domain.projects import ProjectError
+from opendirector.infrastructure.creation_projects import CreationProjects
+from opendirector.infrastructure.local_projects import LocalProjects
+from opendirector.infrastructure.model_configs import ModelConfigs
+from opendirector_api.agent import Conversations
+from opendirector_api.main import create_app
+from test_creation_canvas_service import media, project, send, ver # noqa: F401 (project is a fixture)
+
+
+@pytest.fixture
+def anyio_backend():
+ return 'asyncio'
+
+
+class Provider:
+ def __init__(self, mode='ok'):
+ self.mode, self.calls, self.started = mode, [], asyncio.Event()
+
+ def validate(self, kind, config):
+ pass
+
+ async def generate(self, config, task, submitted):
+ self.calls.append(task['id'])
+ self.started.set()
+ if self.mode == 'hang':
+ await asyncio.Event().wait()
+ if self.mode == 'fail':
+ raise ProjectError('provider exploded', 400)
+ return 'md', b'generated'
+
+
+def stack(project, provider):
+ store, pid, session = project
+ configs = ModelConfigs(store.local.repository)
+ config = configs.save('agent', 'http://127.0.0.1:12345/v1', 'gen', '', connection_type='self_hosted',
+ protocol='openai', auth_mode='none')
+ runner = CreationGeneration(store, configs, provider)
+ return runner, AgentTools(store, runner, configs), config
+
+
+async def submit(tools, project, config, turn, call, before=None):
+ store, pid, session = project
+ item, spec = media(project, 'text')
+ changed = spec.model_copy(update={'prompt': call, 'modelConfigId': UUID(config['id'])})
+ assert send(store, pid, 'generationSpec.update', session=session, versions=[ver('generation_spec', spec)], spec=changed).status == 'applied'
+ snapshot = store.snapshot(pid)
+ spec = next(s for s in snapshot.generationSpecs if s.id == spec.id)
+ item = next(i for i in snapshot.canvasItems if i.id == item.id)
+ arguments = dict(type='generation.submit',
+ payload=dict(specId=str(spec.id), expectedSpecRevision=spec.revision, originItemId=str(item.id)),
+ expectedVersions=json.loads(json.dumps([ver('generation_spec', spec), ver('canvas_item', item)], default=str)))
+ if before:
+ before()
+ return await tools.execute(pid, turn, session, call, 'execute_command', arguments, [], None)
+
+
+def lineage_client(store):
+ # The real application, so ProjectError and the other handlers apply. No `with`: lifespan (job recovery) never starts.
+ return TestClient(create_app(store.local), headers={'X-OpenDirector-Request': '1'})
+
+
+def jobs_url(pid, turn):
+ return f'/api/creation/projects/{pid}/assistant/turns/{turn}/jobs'
+
+
+def turn_jobs(client, pid, turn):
+ response = client.get(jobs_url(pid, turn))
+ assert response.status_code == 200, response.text
+ return response.json()
+
+
+def commit_files(store):
+ return sorted((f.name, f.stat().st_mtime_ns) for f in store.local.root.rglob('commits/*.json'))
+
+
+async def settled(runner):
+ await asyncio.gather(*(job.future for job in list(runner.jobs.values())))
+
+
+@pytest.mark.anyio
+async def test_agent_job_origin_matches_the_committed_receipt(project):
+ store, pid, session = project
+ provider = Provider()
+ runner, tools, config = stack(project, provider)
+ turn, call = uuid4(), 'cli:' + str(uuid4())
+ receipt = await submit(tools, project, config, turn, call)
+ await settled(runner)
+ await runner.close()
+ assert receipt['status'] == 'accepted'
+ command_id = agent_command_id(turn, call)
+ assert UUID(receipt['commandId']) == command_id
+ job = store.snapshot(pid).jobs[0]
+ # Job -> Turn: stored on the job itself.
+ assert (job.agentRunId, job.agentCallId) == (turn, call)
+ # Turn -> Job and the derived identities agree with the committed receipt.
+ assert receipt['jobIds'] == [str(job.id)] == [str(j) for j in store.receipt(pid, command_id).jobIds]
+ assert job.id == uuid5(command_id, 'job')
+ assert job.status == 'succeeded'
+
+
+@pytest.mark.anyio
+async def test_background_failure_is_reported_as_failure_with_the_original_identity(project):
+ store, pid, session = project
+ runner, tools, config = stack(project, Provider('fail'))
+ turn = uuid4()
+ receipt = await submit(tools, project, config, turn, 'call-1')
+ await settled(runner)
+ await runner.close()
+ assert receipt['status'] == 'accepted' # the tool call succeeded; the job did not
+ [job] = store.snapshot(pid).jobs
+ assert str(job.id) == receipt['jobIds'][0] and job.status == 'failed'
+ assert (job.agentRunId, job.agentCallId) == (turn, 'call-1')
+ assert job.errorDetails.message == 'provider exploded' and job.asset is None
+ assert (job.recovery, job.resumeAllowed) == ('review', False)
+
+
+@pytest.mark.anyio
+async def test_one_turn_records_every_job_it_accepted_and_nothing_else(project):
+ store, pid, session = project
+ runner, tools, config = stack(project, Provider())
+ turn, other = uuid4(), uuid4()
+ first = await submit(tools, project, config, turn, 'call-a')
+ second = await submit(tools, project, config, turn, 'call-b')
+ await submit(tools, project, config, other, 'call-a') # same call id, different turn
+ item, spec = media(project, 'text') # a job nobody's Agent submitted
+ spec = spec.model_copy(update={'prompt': 'ui', 'modelConfigId': UUID(config['id'])})
+ current = store.snapshot(pid)
+ base = next(s for s in current.generationSpecs if s.id == spec.id)
+ assert send(store, pid, 'generationSpec.update', session=session, versions=[ver('generation_spec', base)], spec=spec).status == 'applied'
+ current = store.snapshot(pid)
+ spec, item = next(s for s in current.generationSpecs if s.id == spec.id), next(i for i in current.canvasItems if i.id == item.id)
+ ui = await runner.execute(parse_command(dict(commandId=uuid4(), projectId=pid, type='generation.submit',
+ expectedVersions=[ver('generation_spec', spec), ver('canvas_item', item)],
+ payload=dict(specId=spec.id, expectedSpecRevision=spec.revision, originItemId=item.id))), session=session)
+ await settled(runner)
+ await runner.close()
+ jobs = store.snapshot(pid).jobs
+ mine = [j for j in jobs if j.agentRunId == turn]
+ assert sorted(str(j.id) for j in mine) == sorted([first['jobIds'][0], second['jobIds'][0]])
+ assert {j.agentCallId for j in mine} == {'call-a', 'call-b'}
+ assert sorted(j.agentCallId for j in jobs if j.agentRunId == other) == ['call-a']
+ ui_job = next(j for j in store.snapshot(pid).jobs if str(j.id) == str(ui.jobIds[0]))
+ assert ui_job.agentRunId is None and ui_job.status == 'succeeded'
+ assert 'agentRunId' not in ui_job.model_dump(mode='json') and 'agentCallId' not in ui_job.model_dump(mode='json')
+
+
+@pytest.mark.anyio
+async def test_origin_survives_a_crash_after_the_commit_intent_is_durable(project):
+ store, pid, session = project
+ runner, tools, config = stack(project, Provider())
+ def crash(stage):
+ if stage == 'journaled':
+ raise RuntimeError('process died')
+ def arm(): # only the submit commit is interrupted, not the fixture setup
+ store._checkpoint = crash
+ turn = uuid4()
+ with pytest.raises(RuntimeError):
+ await submit(tools, project, config, turn, 'call-1', before=arm)
+ await runner.close()
+ # New process: opening the project rolls the journaled commit forward.
+ reopened = CreationProjects(LocalProjects(store.local.repository))
+ provider = Provider()
+ restarted = CreationGeneration(reopened, ModelConfigs(store.local.repository), provider)
+ [job] = reopened.snapshot(pid).jobs
+ assert (job.status, job.agentRunId, job.agentCallId) == ('queued', turn, 'call-1')
+ assert reopened.receipt(pid, agent_command_id(turn, 'call-1')).jobIds == (job.id,)
+ await restarted.start()
+ await settled(restarted)
+ await restarted.close()
+ assert len(provider.calls) == 1
+ assert reopened.snapshot(pid).jobs[0].status == 'succeeded'
+
+
+@pytest.mark.anyio
+async def test_interrupted_job_keeps_origin_and_a_restart_does_not_resubmit_it(project):
+ store, pid, session = project
+ provider = Provider('hang')
+ runner, tools, config = stack(project, provider)
+ turn = uuid4()
+ await submit(tools, project, config, turn, 'call-1')
+ await asyncio.wait_for(provider.started.wait(), 3)
+ await runner.close() # the service stops while the provider call is open
+ reopened = CreationProjects(LocalProjects(store.local.repository))
+ after = Provider()
+ restarted = CreationGeneration(reopened, ModelConfigs(store.local.repository), after)
+ await restarted.start()
+ await restarted.close()
+ [job] = reopened.snapshot(pid).jobs
+ assert (job.status, job.agentRunId, job.agentCallId) == ('interrupted', turn, 'call-1')
+ assert job.recovery == 'review' and not job.resumeAllowed
+ assert after.calls == [] # no second paid submission
+
+
+@pytest.mark.anyio
+async def test_origin_is_recorded_whole_or_not_at_all_and_old_records_still_validate(project):
+ store, pid, session = project
+ runner, tools, config = stack(project, Provider())
+ await submit(tools, project, config, uuid4(), 'call-1')
+ await settled(runner)
+ await runner.close()
+ recorded = store.snapshot(pid).jobs[0].model_dump(mode='json')
+ half = {key: value for key, value in recorded.items() if key != 'agentCallId'}
+ with pytest.raises(ValueError):
+ Job.model_validate(half)
+ legacy = {key: value for key, value in recorded.items() if key not in {'agentRunId', 'agentCallId'}}
+ assert Job.model_validate(legacy).agentRunId is None # a record written before this field existed
+ assert 'agentRunId' not in Job.model_validate(legacy).model_dump(mode='json')
+
+
+def test_origin_can_only_be_written_by_submit_never_by_an_agent_checkpoint():
+ from opendirector.agent.tools import COMMANDS
+ assert 'job.checkpoint' not in COMMANDS and 'generation.submit' in COMMANDS
+
+
+@pytest.mark.anyio
+async def test_turn_jobs_route_resolves_job_receipt_and_failure_without_the_trace(project):
+ store, pid, session = project
+ runner, tools, config = stack(project, Provider())
+ turn, call = uuid4(), 'cli:' + str(uuid4())
+ receipt = await submit(tools, project, config, turn, call)
+ await settled(runner)
+ await runner.close()
+ failing, failing_tools, failing_config = stack(project, Provider('fail'))
+ failed_turn = uuid4()
+ failed_receipt = await submit(failing_tools, project, failing_config, failed_turn, 'call-1')
+ await settled(failing)
+ await failing.close()
+ client = lineage_client(store)
+ [row] = turn_jobs(client, pid, turn)
+ assert (row['jobId'], row['commandId'], row['callId'], row['status']) == (receipt['jobIds'][0], receipt['commandId'], call, 'succeeded')
+ assert row['asset']['assetId'] and row['errorDetails'] is None
+ assert turn_jobs(client, pid, uuid4()) == []
+ [bad] = turn_jobs(client, pid, failed_turn)
+ assert bad['jobId'] == failed_receipt['jobIds'][0] and bad['status'] == 'failed'
+ assert bad['errorDetails']['message'] == 'provider exploded' and bad['asset'] is None
+ assert (bad['recovery'], bad['resumeAllowed']) == ('review', False)
+
+
+@pytest.mark.anyio
+async def test_job_is_still_traced_after_the_agent_trace_file_is_deleted(project):
+ store, pid, session = project
+ runner, tools, config = stack(project, Provider())
+ turn = uuid4()
+ receipt = await submit(tools, project, config, turn, 'call-1')
+ await settled(runner)
+ await runner.close()
+ trace = Conversations(store).path(pid) / 'agent-runs' / f'{turn}.opencode.jsonl'
+ trace.parent.mkdir(parents=True, exist_ok=True)
+ trace.write_text('{"debug": "tool call"}\n', encoding='utf-8')
+ client = lineage_client(store)
+ assert client.get(f'/api/creation/projects/{pid}/assistant/traces/{turn}/opencode').status_code == 200
+ trace.unlink()
+ assert client.get(f'/api/creation/projects/{pid}/assistant/traces/{turn}/opencode').status_code == 404
+ [row] = turn_jobs(client, pid, turn)
+ assert (row['jobId'], row['callId'], row['commandId']) == (receipt['jobIds'][0], 'call-1', receipt['commandId'])
+ job = store.snapshot(pid).jobs[0]
+ assert (job.agentRunId, job.agentCallId) == (turn, 'call-1')
+ assert store.receipt(pid, agent_command_id(turn, 'call-1')).jobIds == (job.id,)
+
+
+@pytest.mark.anyio
+async def test_turn_jobs_route_order_does_not_depend_on_stored_order(project, monkeypatch):
+ store, pid, session = project
+ runner, tools, config = stack(project, Provider())
+ turn = uuid4()
+ for call in ('call-a', 'call-b', 'call-c'):
+ await submit(tools, project, config, turn, call)
+ await settled(runner)
+ await runner.close()
+ client = lineage_client(store)
+ expected = [row['callId'] for row in turn_jobs(client, pid, turn)]
+ assert expected == ['call-a', 'call-b', 'call-c'] # creation order
+ original = CreationProjects.snapshot
+ monkeypatch.setattr(CreationProjects, 'snapshot',
+ lambda self, project_id: (lambda s: s.model_copy(update={'jobs': tuple(reversed(s.jobs))}))(original(self, project_id)))
+ assert [row['callId'] for row in turn_jobs(client, pid, turn)] == expected
+
+
+def test_turn_jobs_route_uses_the_application_error_for_an_unknown_project(project):
+ store, pid, session = project
+ response = lineage_client(store).get(jobs_url(uuid4(), uuid4()))
+ assert response.status_code == 404
+ assert response.json()['code']
+
+
+@pytest.mark.anyio
+async def test_lineage_reads_never_write_or_start_work(project):
+ store, pid, session = project
+ provider = Provider()
+ runner, tools, config = stack(project, provider)
+ turn = uuid4()
+ await submit(tools, project, config, turn, 'call-1')
+ await settled(runner)
+ await runner.close()
+ client = lineage_client(store)
+ before, calls, cursor = commit_files(store), len(provider.calls), store.snapshot(pid).eventCursor
+ for _ in range(3):
+ turn_jobs(client, pid, turn)
+ store.receipt(pid, agent_command_id(turn, 'call-1'))
+ assert (commit_files(store), len(provider.calls), store.snapshot(pid).eventCursor) == (before, calls, cursor)
+ assert runner.jobs == {}
diff --git a/tests/traceJobs.test.ts b/tests/traceJobs.test.ts
new file mode 100644
index 000000000..30e8130d6
--- /dev/null
+++ b/tests/traceJobs.test.ts
@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readTurnJobs, turnJobView, type TurnJob } from "../src/canvas/traceJobs.ts";
+import { setActiveLocale } from "../src/i18n/messages.ts";
+import { defaultTranslate } from "../src/canvas/assistantTranslate.ts";
+
+const t = defaultTranslate;
+setActiveLocale("en-US");
+const base = { callId: "c", commandId: "k", errorDetails: null, asset: null, adopted: false };
+const job = (over: Partial): TurnJob => ({ jobId: "j", status: "running", ...base, ...over });
+const ok = (body: unknown) => ({ ok: true, json: async () => body });
+
+test("multiple jobs keep order and localized status", async () => {
+ const jobs = await readTurnJobs(ok([job({ jobId: "a", status: "queued" }), job({ jobId: "b" })]));
+ assert.deepEqual(jobs.map((j) => turnJobView(j, t).key), ["a", "b"]);
+ assert.equal(turnJobView(jobs[0], t).statusText, "Queued");
+ assert.equal(turnJobView(jobs[1], t).statusText, "Running");
+});
+
+test("succeeded job shows its asset and adoption", () => {
+ const view = turnJobView(job({
+ status: "succeeded", adopted: true,
+ asset: { assetId: "a1", revision: 2, fingerprint: "f", kind: "image" } as TurnJob["asset"],
+ }), t);
+ assert.equal(view.assetText, "Result: image a1 r2");
+ assert.equal(view.adoptedText, "Adopted");
+ assert.equal(view.errorText, null);
+});
+
+test("failed job shows the localized failure", () => {
+ const view = turnJobView(job({
+ status: "failed",
+ errorDetails: { message: "生成服务暂时不可用。", category: "provider" } as TurnJob["errorDetails"],
+ }), t);
+ assert.equal(view.statusText, "Failed");
+ assert.ok(view.errorText && !/[\u4e00-\u9fff]/.test(view.errorText));
+});
+
+test("empty response yields no jobs", async () => {
+ assert.deepEqual(await readTurnJobs(ok([])), []);
+});
+
+test("non-ok, malformed or throwing responses yield no jobs", async () => {
+ assert.deepEqual(await readTurnJobs({ ok: false, json: async () => [job({})] }), []);
+ assert.deepEqual(await readTurnJobs(ok({ detail: "x" })), []);
+ assert.deepEqual(await readTurnJobs({ ok: true, json: async () => { throw new Error("bad"); } }), []);
+});
+
+test("status and asset text follow the active locale", () => {
+ setActiveLocale("zh-CN");
+ try {
+ const view = turnJobView(job({ status: "succeeded", asset: { assetId: "a1", revision: 2, fingerprint: "f", kind: "image" } as TurnJob["asset"] }), t);
+ assert.equal(view.statusText, "已完成");
+ assert.equal(view.assetText, "结果:image a1 r2");
+ } finally {
+ setActiveLocale("en-US");
+ }
+});