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"); + } +});