[zzheng-aiplay]

Summary

Adds a Session tab to the Dex Web v2 run page for Flows with the Dex Agents session schema (O2 session view of #1324, layout S1).

• One conversation in message order. Each tool call is a compact card where the agent made it: tool name, effect class, arguments, and state. The states read differently: waiting for approval, waiting for an answer, queued for a Worker (from the Step's pending reason; "it has not run" only on a first attempt), running (attempt n of m from the retry policy), retrying, recording the result (a recovery Step is pending, so the call may have run), done, failed, outcome unknown (with Tell the agent), skipped, rejected, and not run.
• One approval card per pending call (Approve, Reject with an optional reason for the model) and one question card per pending question. Steer and Stop turn at the bottom. Usage tokens from AgentUsage.
• Every control goes through POST /api/v2/actions with its own input, so nobody copies an interrupt ID. A false result or a lock conflict from resolve_interrupt or answer_question reads as "Already handled" and reloads.
• Controls are disabled with a reason when the graph declares no such Action, the session is closed, Working as lacks the permission (a Work as button covers phones, where the run list is hidden), or an active Step has waited over 15 s for a Worker.
• Past turns: a call inside the loaded Flow history window shows the last record history holds; an older call shows only what its message text keeps and the card says effect not kept. The tab says so plainly.
• A read error lists each missing Attribute or message instead of an empty conversation.
• At 640 px and below, the Session tab takes the full width.
• v2SessionPath(flowType, flowId) opens a session on its tab.

Shared pieces for the Work Queue inbox live in web/app/v2/agents/: ToolCallCard.tsx, ApprovalCard.tsx (ApprovalCard, QuestionCard), sessionActions.ts (invokeSessionAction, resolveInterruptInput, actionBlockedReason), sessionModel.ts, sessionSchema.ts, and useAgentSession.ts.

Docs: a new Agent session view section in the Dex Web reference with a screenshot, and a paragraph in the agent deployment guide in English and Simplified Chinese. The Dex Web reference is a Developer reference page and is English only by the repository's docs rules.

Why

#1324 (O2) asks for a Dex Web agent view an operator can use to see what an agent did and what waits for a person, built on the session graph from #1383 and the Action route changes from #1352. Before this change an operator approved a call by typing its interrupt ID into the generic Action form. The view must work when Workers are down, because that is when an operator most needs it, so it reads Attributes rather than calling get_agent_snapshot.

Compatibility

No API, wire, or server change. The tab appears only for a valid Flow Definition Graph 2.0 that declares AgentState, AgentMessages (AttributeMap), AgentToolCalls (AttributeMap), and PendingInterrupts; every other Flow keeps the run page unchanged.

Schema rule for Dex Web (also in the reference): Dex Web reads the session schema by name — the Attributes above plus AgentMessageChunks, AgentMessageIndex, and AgentUsage; the Step types CallTool, CallSingleAttemptTool, PollToolTask, RecordToolFailure, and RecordToolOutcomeUnknown, whose input is a tool call ID; and the Actions resolve_interrupt, answer_question, steer_user_message, and cancel_turn. The rule is additive: Dex Agents may add fields, enum values, Steps, and Actions, and Dex Web ignores what it does not know. Renaming or removing one of these names, or changing a field's meaning, needs a matching Dex Web release. A unit test reads agents/conformance/session_graph.json, so a rename there fails Web CI.

Python and TypeScript sessions get the full tab. A Go session has no questions, steering, or stopping; its tab shows messages, tool calls, approvals, and usage, and each undeclared control is disabled with its reason.

Testing

• cd web && npm run check: typecheck and Vitest pass (34 new tests in web/app/v2/agents/ plus one contract test; 488 web tests in all).
• make copyright-check and make docs-prose-check pass. cd docs && npm run check passes. Read the changed agent deployment guide section in English and Simplified Chinese, and the new reference section, in the built site.
• End to end against a real Python session on dexcli 1.38.0 with this branch's UI in Vite: the session graph rendered by dex-agents-session-graph and loaded with --flow-rendering-dir; a Stepwise agent with a scripted model reached AwaitToolApproval with two pending calls. From their cards, approved one and rejected the other with a reason; the turn continued, and the agent's final message contained the refund result and the rejection reason. A second browser page loaded before the approval clicked Approve on the same call and showed "Already handled".
• Workers down: with both calls running, killed the Worker. The tab still read the session; the retrying call showed queued for a Worker with attempt 2 of 3, the crashed single-attempt write showed recording the result, and the controls were disabled with the Worker reason. After a Worker restart the calls showed done and outcome unknown.
• Read errors: with the state route or blob loading failing, the tab showed the failure or the list of unreadable values, not an empty conversation.
• CI covers Web CI and Docs CI.