diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 8e6f9c9e..343119ad 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -17,7 +17,7 @@ - [任务控制面统一主线](./task-control-plane-unification.md) - [任务线程 Session Key 隔离（2026-03-29）](./task-thread-session-key-isolation-20260329.md) - [Task Dialog Provider 选择主线](./task-dialog-provider-selection-mainline.md) -- [跨仓库任务状态工作流](./cross-repo-task-state-workflow.md) +- [TaskThread 跨仓库主流程与状态图](./cross-repo-task-state-workflow.md) ## 设置与配置 diff --git a/docs/architecture/cross-repo-task-state-workflow.md b/docs/architecture/cross-repo-task-state-workflow.md index 8e1f5bb8..fdc8bce7 100644 --- a/docs/architecture/cross-repo-task-state-workflow.md +++ b/docs/architecture/cross-repo-task-state-workflow.md @@ -1,188 +1,262 @@ -# Cross-Repo Task State Workflow +# Cross-Repo TaskThread Workflow -This document records the task-state workflow across: +This document is the current TaskThread workflow record across: - `xworkmate-app` - `xworkmate-bridge` - `openclaw-multi-session-plugins` -The core ownership split is: +It replaces older local-classification and app-side artifact fallback descriptions. The current rule is: -- `xworkmate-app` owns task UI state, `TaskThread` persistence, local thread workspaces, and the OpenClaw submit queue. -- `xworkmate-bridge` owns public session/routing contracts, provider compatibility, normalized results, and OpenClaw task-submit routing. -- `openclaw-multi-session-plugins` owns OpenClaw task-scoped artifact preparation, export, and artifact-scope isolation. +> The app owns TaskThread state and local sync. The bridge/OpenClaw terminal task snapshot is the truth source for final artifacts. -## Overall Flow +## Ownership + +### xworkmate-app + +The app owns local state and UI only: + +- Resolve or create the current `TaskThread` by `sessionKey` / `threadId`. +- Ensure the local workspace at `$HOME/.xworkmate/threads/`. +- Build the external `TaskThread workspace context` prompt prefix. +- Send `metadata.xworkmateTaskArtifactContract`. +- Queue OpenClaw gateway work locally when the constrained OpenClaw lane is busy. +- Apply normalized bridge results to `TaskThread.lifecycleState`. +- Sync bridge-provided artifacts into the local TaskThread workspace. + +The app must not infer required final file types from user text. It must not treat partial artifacts as final deliverables. + +### xworkmate-bridge + +The bridge owns the public protocol boundary: + +- Expose the unified `/acp/rpc` entrypoint. +- Resolve routing for agent providers and gateway/OpenClaw. +- Normalize provider/OpenClaw results into a stable result shape. +- Stream `session.update` events. +- Serve `xworkmate.tasks.get` snapshots for asynchronous recovery and terminal result lookup. +- Serve `xworkmate.tasks.cancel` for OpenClaw task cancellation. + +The bridge should return standard contract fields such as `artifacts`, `artifacts.items`, `files`, or `attachments`. App-side support for ad hoc final-artifact field names is not a compatibility layer. + +### openclaw-multi-session-plugins + +OpenClaw plugins own execution-time artifact scope: + +- Create a run. +- Allocate `runId`. +- Prepare `artifactScope = tasks//`. +- Execute the user task. +- Export real final deliverables into the current task artifact scope. +- Validate that artifact scope matches the current session and run. +- Return artifact refs/files to the bridge. + +Text-only file claims, placeholder files, global workspace files, previous-run files, and partial/intermediate artifacts are not final deliverables. + +## Main Flow ```mermaid -flowchart LR - U["User input / follow-up"] --> APP["xworkmate-app
TaskThread + UI state"] - APP -->|session.start / session.message| BR["xworkmate-bridge
/acp/rpc"] - BR -->|xworkmate.routing.resolve| ROUTE{"Execution target"} - ROUTE -->|single-agent| AG["codex / opencode / gemini / hermes"] - ROUTE -->|gateway=openclaw| OC["OpenClaw Gateway Runtime"] - OC --> PLUG["openclaw-multi-session-plugins
task-scoped artifacts"] - PLUG -->|artifactRef / files / downloadUrl| BR - BR -->|normalized result / SSE update| APP - APP -->|write files| LOCAL["$HOME/.xworkmate/threads/"] - APP -->|persist index| STORE["~/Library/Application Support/xworkmate/tasks/threads.json"] +flowchart TD + U["User input / follow-up"] --> UI["Assistant UI"] + UI --> APP["AppController / TaskThread"] + + APP --> T0{"Current TaskThread exists?"} + T0 -->|No| T1["Create draft TaskThread
sessionKey / threadId"] + T0 -->|Yes| T2["Load current TaskThread"] + T1 --> W["Prepare local workspace
$HOME/.xworkmate/threads/"] + T2 --> W + + W --> C["Build external task context
TaskThread workspace context"] + C --> M["Attach metadata
xworkmateTaskArtifactContract"] + + M --> R{"Execution target"} + R -->|Agent: codex / opencode / gemini / hermes| B1["bridge /acp/rpc
session.start or session.message"] + R -->|Gateway: OpenClaw| Q{"OpenClaw local lane idle?"} + + Q -->|Idle| B2["bridge /acp/rpc
session.start or session.message"] + Q -->|Busy| Q1["Local OpenClaw queue
lifecycleStatus=queued"] + Q1 --> Q2["drainOpenClawGatewayQueue"] + Q2 --> B2 + + B1 --> BR["xworkmate-bridge
routing + protocol normalization"] + B2 --> BR + + BR --> P{"Provider / runtime"} + P -->|Agent provider| A["Codex / Opencode / Gemini / Hermes"] + P -->|OpenClaw| O["OpenClaw runtime"] + O --> OS["OpenClaw task artifact scope
tasks//"] + + A --> N["Bridge normalized result"] + OS --> N + + N --> S{"Return path"} + S -->|Final response| APP2["APP applyGatewayChatResult"] + S -->|SSE update| SSE["APP receives session.update"] + S -->|SSE closed / no final envelope| POLL["Transport calls xworkmate.tasks.get
until terminal snapshot"] + + SSE --> H{"Running task handle?"} + H -->|Yes| POLL + H -->|No| APP2 + POLL --> APP2 + + APP2 --> OK{"success=true and artifacts present?"} + OK -->|Yes| SYNC["Sync artifacts to local TaskThread workspace"] + OK -->|No, failure| FAIL["Record lastResultCode
lastArtifactSyncStatus=failed"] + OK -->|No exported artifacts guard| NOART["lastArtifactSyncStatus=no-exported-artifacts"] + + SYNC --> READY["TaskThread ready"] + FAIL --> READY + NOART --> READY ``` -## App TaskThread State Machine +## TaskThread State Machine -`TaskThread.lifecycleState.status` is intentionally small. Most terminal outcomes return to `ready`; the specific terminal result is stored in `lastResultCode`. +`TaskThread.lifecycleState.status` is intentionally small. Most terminal outcomes return to `ready`; result detail is stored in `lastResultCode`. ```mermaid stateDiagram-v2 - [*] --> Ready: create task / restore persisted task + [*] --> Ready: create / restore TaskThread - Ready --> Queued: OpenClaw gateway active slot is full + Ready --> Running: sendChatMessage + Ready --> Queued: OpenClaw lane busy Queued --> Running: drainOpenClawGatewayQueue - Queued --> Ready: abortRun\nlastResultCode=aborted - Queued --> Ready: queue full\nlastResultCode=OPENCLAW_GATEWAY_QUEUE_FULL + Queued --> Ready: abort / queue full - Ready --> Running: sendChatMessage\nmarkGatewayChatRun - Running --> Ready: GoTaskServiceResult.success=true\nlastResultCode=success - Running --> Ready: result.status / result.code\nlastResultCode= - Running --> Ready: no displayable output\nlastResultCode=failed - Running --> Ready: ACP interrupted / timeout\nlastResultCode=ACP_* - Running --> Ready: abortRun\nlastResultCode=aborted + Running --> Running: SSE delta / session.update + Running --> Running: OpenClaw running handle + Running --> Running: xworkmate.tasks.get polling + + Running --> Ready: success + Running --> Ready: failed / artifact_missing + Running --> Ready: ACP_HTTP_* / unrecovered SSE interruption + Running --> Ready: abort Ready --> Archived: user archives task Archived --> Ready: user restores task note right of Ready - lifecycleStatus terminal state is usually ready. - Read lastResultCode for result detail: - success / failed / error / aborted / - artifact_missing / ACP_HTTP_* + lifecycleStatus=ready does not mean success. + Read lastResultCode for terminal detail: + success / failed / aborted / + artifact_missing / ACP_HTTP_* / + OPENCLAW_REQUIRED_ARTIFACT_MISSING. + end note + + note right of Running + Running does not mean final files exist. + An OpenClaw running handle is only an async task handle. + The transport must continue polling the bridge task snapshot. end note ``` -## Task Workspace Context Injection - -Every app-owned task has a local workspace under `$HOME/.xworkmate/threads/`. For remote execution, the bridge/runtime may also resolve a remote task workspace hint. The app passes the task workspace in two ways: - -- Structured request fields: `workingDirectory` and, when available, `remoteWorkingDirectoryHint`. -- External conversation context: a `TaskThread workspace context` prefix is added to the prompt sent to Bridge/OpenClaw. - -The local chat transcript still stores the user's original text. Only the external task prompt is enriched, so the UI does not show internal workspace rules as user content. - -```mermaid -sequenceDiagram - participant UI as "XWorkmate UI" - participant APP as "TaskThread runtime" - participant BR as "Bridge session" - participant OC as "OpenClaw / provider" - participant WS as "Task workspace" - - UI->>APP: "user message" - APP->>WS: "ensure $HOME/.xworkmate/threads/" - APP->>APP: "build TaskThread workspace context" - APP->>BR: "taskPrompt + workingDirectory + remoteWorkingDirectoryHint" - BR->>OC: "session.start / session.message" - OC->>WS: "final files must be exported into task scope" - BR-->>APP: "result + artifact refs" - APP->>WS: "sync inline/downloaded artifacts" -``` - -Prompt-level workspace rules are deliberately strict. `remoteWorkingDirectoryHint` is the writable task workspace for remote OpenClaw/provider execution when present; otherwise `workingDirectory` is used. - -- Treat the current task workspace as the only writable workspace for the task execution. -- Create, modify, and export task files inside that workspace or its task artifact scope. -- Do not use global OpenClaw media/cache paths, `/tmp`, Downloads, Desktop, or other arbitrary directories as final deliverable locations. -- If a tool creates output outside the task workspace, copy/export the final deliverables into the task workspace before claiming completion. -- Prefer local task-workspace paths, or paths relative to that workspace, when reporting files back to the user. - -## OpenClaw Gateway Queue - -The app serializes OpenClaw gateway execution locally because OpenClaw task execution is treated as a constrained gateway lane. - -```mermaid -flowchart TD - A["APP selects Gateway + OpenClaw"] --> B{"active < 1 ?"} - B -->|yes| C["Run immediately
lifecycleStatus=running"] - B -->|no| D{"queue < 20 ?"} - D -->|yes| E["Enqueue
lifecycleStatus=queued
lastArtifactSyncStatus=queued"] - D -->|no| F["Queue full
lastResultCode=OPENCLAW_GATEWAY_QUEUE_FULL"] - - E --> G["drain queue"] - G --> C - C --> H["Bridge /acp/rpc
routing=gateway/openclaw"] - H --> I["OpenClaw execution"] - I --> J{"Result"} - J -->|success + output/files| K["APP ready
lastResultCode=success
sync artifacts"] - J -->|artifact guard| L["APP ready
lastResultCode=artifact_missing"] - J -->|failure/interruption| M["APP ready
lastResultCode=failed/error/ACP_*"] -``` - -## Bridge Session And Routing Workflow - -The bridge exposes one public session contract while keeping provider-specific behavior behind bridge-owned routing. OpenClaw task submit uses `/acp/rpc` with explicit gateway routing metadata, not a separate app-facing path. - -```mermaid -flowchart TD - REQ["APP request"] --> EP{"HTTP / WS entry"} - EP -->|/acp or /acp/rpc| RPC["General JSON-RPC"] - - RPC --> METHOD{"method"} - METHOD -->|acp.capabilities| CAP["Return agent providers + gatewayProviders=openclaw"] - METHOD -->|xworkmate.routing.resolve| ROUTE["Resolve single-agent / gateway"] - METHOD -->|session.start| START["Create / start session turn"] - METHOD -->|session.message| MSG["Continue existing session"] - METHOD -->|session.cancel / session.close| CTRL["Cancel / close session"] - - START --> ORCH["session_orchestrator"] - MSG --> ORCH - ORCH --> PROVIDER{"provider compat"} - PROVIDER -->|single-agent| SA["codex / opencode / gemini / hermes"] - PROVIDER -->|gateway| OCG["OpenClaw runtime"] - - SA --> NORM["normalized result"] - OCG --> NORM - NORM --> OUT["success / status / turnId / output / artifacts / resolved*"] -``` - -## OpenClaw Plugin Artifact Scope - -OpenClaw artifacts are scoped by task session and run. This prevents one task or turn from borrowing files from another. - -```mermaid -flowchart TD - CTX["OpenClaw plugin context
sessionKey + runId + workspaceDir"] --> PREP["prepareXWorkmateArtifacts"] - PREP --> SCOPE["artifactScope = tasks//"] - SCOPE --> DIR["artifactDirectory"] - DIR --> RUN["OpenClaw writes files"] - RUN --> EXPORT["exportXWorkmateArtifacts"] - EXPORT --> VALIDATE{"scope matches sessionKey/runId ?"} - VALIDATE -->|no| ERR["Reject cross-task / cross-run artifact"] - VALIDATE -->|yes| MANIFEST["manifest + artifactRef + files"] - MANIFEST --> BR["Bridge result"] - BR --> APP["APP downloads or inlines into local thread workspace"] - - note right of SCOPE - Concurrent task isolation is based on: - tasks// - Do not reuse other sessions or previous run files. - end note -``` - -## Status Field Mapping +## State Field Relationship ```mermaid flowchart LR - APP1["APP TaskThread.lifecycleState.status"] --> A1["queued / running / ready / archived"] - APP2["APP TaskThread.lifecycleState.lastResultCode"] --> A2["queued / running / success / failed / error / aborted / artifact_missing / ACP_HTTP_*"] - APP3["APP lastArtifactSyncStatus"] --> A3["queued / running / synced / no-artifacts / failed"] - BR1["Bridge result.status"] --> B1["available / success / failed / provider status"] - BR2["Bridge result.success"] --> B2["true / false"] - PL1["Plugin artifact export"] --> P1["scopeKind=task
artifactScope=tasks/session/run"] + LS["TaskThread.lifecycleStatus"] --> LS2["ready / queued / running / archived"] + RC["TaskThread.lastResultCode"] --> RC2["success / failed / aborted / artifact_missing / ACP_HTTP_* / OPENCLAW_*"] + AS["TaskThread.lastArtifactSyncStatus"] --> AS2["queued / running / syncing / synced / partial / failed / no-artifacts / no-exported-artifacts"] + AP["TaskThread.lastTaskArtifactRelativePaths"] --> AP2["Only files synced from the current run"] +``` + +Rules: + +- `lifecycleStatus=ready` only means no task is currently running. +- Success or failure is read from `lastResultCode`. +- The artifact panel reads `lastArtifactSyncStatus` and `lastTaskArtifactRelativePaths`. +- `lastTaskArtifactRelativePaths` must only contain artifacts from the current run. + +## App Request Contract + +App requests to bridge use the unified ACP entrypoint. OpenClaw is selected with routing metadata, not with an app-facing OpenClaw URL. + +The app sends: + +- `sessionId` +- `threadId` +- `prompt` +- `workingDirectory` +- `remoteWorkingDirectoryHint` +- `routing` +- `metadata.xworkmateTaskArtifactContract` + +For Gateway/OpenClaw, the app injects `currentTaskWorkspace` into both prompt context and metadata. The remote runtime must export final files into the current task artifact scope before returning success. + +The prompt context contains: + +- `sessionKey` +- local workspace +- remote workspace hint when available +- current task workspace +- workspace isolation rules +- final artifact contract rules + +The local transcript stores the user's original text. Internal workspace context is only sent to the external task runtime. + +## Bridge / OpenClaw Async Contract + +The transport handles these bridge methods: + +- `session.start`: start a new turn. +- `session.message`: continue an existing TaskThread. +- `xworkmate.tasks.get`: recover or query terminal task snapshot. +- `xworkmate.tasks.cancel`: cancel a running OpenClaw task. + +Important recovery rule: + +> A running OpenClaw task handle is never a final result. + +When `session.update` contains `status=running` with `runId` and `artifactScope`, the app transport must use those fields only as query parameters for `xworkmate.tasks.get`. It must continue polling until the bridge returns a terminal snapshot: + +- `completed` with artifacts -> success path. +- `failed`, `artifact_missing`, `cancelled`, or `canceled` -> failure path. +- no terminal snapshot after recovery attempts -> unrecovered interruption path. + +## Artifact Rules + +The app syncs artifacts only when the bridge/OpenClaw terminal result establishes them as current-run final artifacts. + +Valid success: + +- `success=true` +- terminal bridge/OpenClaw snapshot +- standard artifact contract fields are present +- artifact scope belongs to the current session and run + +Failure / no-sync cases: + +- `success=false` with partial artifacts +- `OPENCLAW_REQUIRED_ARTIFACT_MISSING` +- `artifact_missing` +- `no-exported-artifacts` +- text-only file/path claims +- files from previous runs +- files from global OpenClaw workspace/cache +- placeholder artifacts generated by a guard + +`openclaw returned partial artifacts without required final deliverables` means the remote artifact contract was not satisfied. It is not an app-side UI classification failure. + +## OpenClaw Artifact Scope + +```mermaid +flowchart TD + CTX["OpenClaw context
sessionKey + runId + workspaceDir"] --> PREP["prepareXWorkmateArtifacts"] + PREP --> SCOPE["artifactScope = tasks//"] + SCOPE --> DIR["artifactDirectory"] + DIR --> RUN["OpenClaw writes files"] + RUN --> EXPORT["exportXWorkmateArtifacts"] + EXPORT --> VALIDATE{"scope matches session/run?"} + VALIDATE -->|No| ERR["Reject cross-session / cross-run artifact"] + VALIDATE -->|Yes| MANIFEST["manifest + artifact refs/files"] + MANIFEST --> BR["Bridge terminal snapshot"] + BR --> APP["App syncs current-run artifacts"] ``` ## Boundary Rules -- The app does not store OpenClaw URLs. It only consumes bridge capabilities where `gatewayProviders` includes `openclaw`. -- OpenClaw `session.start` and `session.message` use `/acp/rpc` with explicit OpenClaw gateway routing metadata; `/gateway/openclaw` is not an app-facing endpoint. -- Follow-up conversation uses the same `sessionKey` / `threadId`. Bridge `session.message` must continue the provider session state or return a structured continuation error. -- Artifact ownership is enforced by `openclaw-multi-session-plugins` with `tasks//` scope. The app syncs only the current run's artifacts into the local thread workspace. -- Upgrade/install flows must preserve real local history. Cleanup must only remove explicitly known test-pollution session keys. +- The app does not store or construct OpenClaw runtime URLs. +- OpenClaw `session.start` and `session.message` use `/acp/rpc` with explicit routing metadata. +- `/gateway/openclaw` and provider-specific paths are not app-facing paths. +- The bridge/OpenClaw terminal task snapshot is the final artifact truth source. +- App local workspace contents are not used to decide whether a remote run produced final deliverables. +- Compatibility/fallback fields for final artifacts are not allowed unless an explicit bridge contract requires them.