AGENTS.md@packages/flows-plugin/src/client git:20260703.e20cd5aA

Immutable. This exact content is served forever at /api/v1/blob/9cc1f9f3bc1cd2ee.

# DOX — packages/flows-plugin/src/client

Files in this directory. One row per source file.

| File | Purpose |
|------|---------|
| `flow-collapse-storage.ts` | Per-session persisted collapse state for flow panels. Exports `FlowCollapseKind`, `flowCollapseKey`, `usePersistedToggle`, `useFlowCollapsePersisted`, `FLOW_SHOW_ERROR_ROUTES_KEY`. localStorage keyed by session id; failures degrade to in-memory. Mirrors `useSidebarState.ts` try/catch-swallow. |
| `flow-edges.ts` | Shared flow-edge derivation. Exports `FlowEdgeKind`, `FlowEdgeStep`, `FlowEdge`, `deriveFlowEdges`. One rule for live `FlowGraph` + static `flow_write` Mermaid snapshot. Classes: `sequential`, `branch`, `route`, `implicit`. Tags `on_error` route topology (`returning`/`terminal`) via reachability. |
| `flow-yaml-parse.ts` | Shallow client YAML→steps parser (`parseFlowYaml`) + Mermaid generator (`flowToMermaid`). Extracts id/type/blockedBy/branches + counts. Node-shape glyphs per kind; forward edges from blockedBy, backward branch edges dashed. Graceful null on parse failure. See change: rework-flows-plugin-for-new-pi-flows. |
| `FlowActivityBadge.tsx` | Running-flow status pill. Exports `FlowActivityBadge`, `FlowActivityBadgeProps`. Maps `FlowStatus` → icon+color; shows agent count when running; renders inline Abort button when `onAbort` provided. Consumed by `SessionFlowActions`. |
| `FlowAgentCard.tsx` | Step card. nodeKind badge (⌗ code, ◈ code-decision, ◇ fork). Code Log preview from `flow_assistant_text` detailHistory. Outputs KV chips. Chosen-branch line + ↻ loop pill. Soft (amber)/hard (red) outcome. Handler target line. See change: rework-flows-plugin-for-new-pi-flows. Code/code-decision nodes now render `mdiCodeBraces` button (gated `isCodeKind && agent.codeTarget`) opening `ui:dialog`; fetches handler `.ts` via `GET /api/pi-resource-file?path=<codeTarget>` (codeTarget absolute, passed verbatim); renders content wrapped in fenced ```ts block via `ui:markdown-content` (Prism highlight). Mirrors agent `sourcePath` doc-icon path; `codeSourceOpen`/`codeSourceState` state. Keeps `‹› {codeTarget}` text line. See change: open-code-handler-from-flow-card. |
| `FlowAgentDetail.tsx` | Thin adapter shim over `MinimalChatView`. Exports `FlowAgentDetail`. Maps `FlowAgentState` → `MinimalChatViewProps` (status, `detailHistory` entries, summary footer). Preserves `agent`/`onBack` API for `FlowAgentCard` detail dialog. |
| `FlowAgentsToolRenderer.tsx` | `tool-renderer` for `flow_agents`. `list` → catalog names + count. `write` → success/failure from `{written,diagnostics,error}`. Args-backed "View agent file" toggle. See change: rework-flows-plugin-for-new-pi-flows. |
| `FlowAuthorPromptDialog.tsx` | Intent-capture dialog for `/skill:manage-flows` launcher. Exports `FlowAuthorPromptDialog`. Two-step pattern: asks what flow should do (new, required) or what to change (edit, optional). Forwards instruction to manage-flows prompt. |
| `FlowDashboard.tsx` | Live running-flow panel. Exports `FlowDashboard`, `FlowDashboardClaim`. Renders header (collapse/AUTO/Abort), `FlowTabBar` multi-flow nav, `BreadcrumbSlot`, `FlowQuestionsSection`, `FlowGraph` + expanded dialog, `FlowAgentCard` grid. Forwards to `FlowSummary` on completion. Claim self-derives state via `useFlowsSessionState`. |
| `FlowGraph.tsx` | dagre SVG graph. `mapStepType` → canonical set (agent/fork/code/code-decision/flow-ref); legacy conditional/agent-loop-decision/loop REMOVED. `architectStepsToGraphSteps` REMOVED. See change: rework-flows-plugin-for-new-pi-flows. |
| `FlowLaunchDialog.tsx` | Run-flow task-capture dialog. Exports `FlowLaunchDialog`. Renders `GateSlot` decorator; `aggregateGateState` disables Run button when extension gates flow unavailable. Forwards task to `onSubmit`. |
| `FlowQuestionCard.tsx` | Pending `flow-question` prompt card rendered in FlowDashboard upper slot. Exports `FlowQuestionCard`, `FlowQuestionCardProps`. Routes by `type` (`confirm`/`select`/`multiselect`/`input`/`editor`) to inline renderers. Dispatches `prompt_response`/`prompt_cancel` via callbacks. Shows queue-depth badge. |
| `FlowQuestionTranscriptPill.tsx` | Collapsed pill for answered/cancelled flow-question in upper-slot transcript. Exports `FlowQuestionTranscriptPill`, `FlowQuestionTranscriptPillProps`. Renders status icon + question + answer (multiselect JSON array compacted). Pending head rendered by `FlowQuestionCard`. |
| `flowsAvailability.ts` | Per-session sync availability cache. Module-level `subscribeSessionDataKey` listener. Exports `getFlowsAvailabilitySync`, `setFlowsAvailability`, `installFlowsAvailabilitySubscriber`, `__resetFlowsAvailabilityForTests`. Closed-by-default. See change: add-flows-subcard. |
| `FlowsCommandRoutes.tsx` | Slash-command route components for `/flows`, `/flows:new`, `/flows:edit`, `/flows:delete`. Exports `FlowsListRoute`, `FlowsNewRoute`, `FlowsEditRoute`, `FlowsDeleteRoute`. Each renders launcher/picker/dialog, dispatches `flow_management` via `usePluginSend`, calls `onClose` on dismissal. Replaces App.tsx flow dialog blocks. |
| `FlowsSessionStateContext.tsx` | Plugin-internal per-session flow state derivation. Exports `FlowsSessionState`, `reduceFlowsSessionState`, `useFlowsSessionState`. Reduces `useSessionEvents` stream via `reduceFlowEvent` into `{ flowState, flowStates }`. `useMemo`-stable; returns frozen `EMPTY_STATE` when no flow activity. Dev-only diagnostic counter. |
| `FlowsSettings.tsx` | `settings-section` (tab general, draft page plugins). Global edit-mode default via `usePluginConfig`/`plugin_config_write`/`useSettingsDraftSource`. Config `{ editFlow?: boolean }`, default off. See change: rework-flows-plugin-for-new-pi-flows. |
| `FlowsUiStateContext.tsx` | Plugin-internal UI selection state, module-level store + `useSyncExternalStore`. Exports `FlowsUiState`, `FlowsUiActions`, `getFlowsUiStateSnapshot`, `useFlowsUiState`, `useFlowsUiActions`, `__resetFlowsUiStateForTests`. Holds `sourceOpenAgent`, `flowYamlPreview`; `dismissAll` unifies cleanup. Snapshot used by manifest predicates. |
| `FlowSummary.tsx` | Completed-flow summary panel. Exports `FlowSummary`, `FlowSummaryClaim`. Renders status header (panel collapse persisted via `useFlowCollapsePersisted`), `FlowGraph` + expanded dialog, frozen `FlowAgentCard` grid, collapsible `FlowSummaryRow` summaries, next-step button. Claim self-derives state, dispatches `dismiss_summary`. |
| `FlowTabBar.tsx` | Multi-flow tab navigation bar. Exports `FlowTab`, `FlowTabBar`. Renders one tab per concurrent flow; FOLLOW toggle auto-switches to latest active flow. Returns null for single flow. |
| `FlowWriteToolRenderer.tsx` | `tool-renderer` for `flow_write`. Renders real result contract `{written,name,namespace,command,path,diagnostics}`. Success: command + counts + Mermaid snapshot (via `ui:markdown-content`) parsed from tool args. Failure: diagnostics verbatim. Args-backed "View flow YAML" toggle. See change: rework-flows-plugin-for-new-pi-flows. |
| `FlowYamlPopoverButton.tsx` | Paper-icon button opening popover with flow YAML. Exports `FlowYamlPopoverButton`. Fetches `/api/pi-resource-file?path=`, renders via `ui:markdown-content` in `yaml` fence. State machine `idle`/`loading`/`loaded`/`error`. Used by `FlowDashboard` + `FlowSummary`. |
| `FlowYamlPreview.tsx` | Content-view claim renderer for flow YAML preview, gated by `isFlowYamlPreviewActive` predicate. Exports `FlowYamlPreviewClaim`. Reads `flowYamlPreview` from `FlowsUiStateContext`; back action clears preview + `sourceOpenAgent` + calls `onClose`. Replaces App.tsx `MarkdownPreviewView` call site. |
| `index.tsx` | Re-export barrel: `FlowDashboard`, `FlowAgentCard`, `FlowAgentDetail`, `FlowSummary`, `FlowGraph`, `FlowActivityBadge`, `FlowLaunchDialog`, `FlowTabBar`, `SessionFlowActions`, `FlowWriteToolRenderer`, `FlowAgentsToolRenderer`, `FlowsSettings`. Architect exports REMOVED. See change: rework-flows-plugin-for-new-pi-flows. |
| `SessionFlowActions.tsx` | Subcard actions. Run / New-Edit (gated on editMode) / Delete / Abort. New/Edit launcher → `onEditFlow` → claim sends `send_prompt /skill:edit-flow [name]`. Claim reconciles global edit-mode default to session via `flow_management{action:set-edit-mode,enabled}` on availability. Architect/new/edit command deps REMOVED. See change: rework-flows-plugin-for-new-pi-flows. |
| `shouldRender.ts` | Manifest-level sync predicate `shouldRenderFlowsSubcard(session)` for `session-card-flows` claim. Reads `getFlowsAvailabilitySync(session.id)`. See change: add-flows-subcard. |