AGENTS.md@packages/automation-plugin/src/client git:20260821.b833325A

Immutable. This exact content is served forever at /api/v1/blob/8ebc707e6a47cc93.

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

Files in this directory. One row per source file.

| File | Purpose |
|------|---------|
| `api.ts` | REST client: listAutomations, listRuns, getRunResult, createAutomation, deleteAutomation. Adds listTriggerKinds, getAutomationDefinition, isGitCapable, updateAutomation, runAutomationNow. Targets `/api/plugins/automation/*`. Adds stopAutomationRun(scope,cwd,runId) → POST /api/plugins/automation/stop. See change: add-automation-plugin. See change: redesign-automation-editor-and-board. See change: automation-ui-mockup-parity. Adds `listActions(cwd)` → GET /actions. See change: register-plugin-automation-events. |
| `automation-card-visuals.ts` | Local replica of dashboard session-status visual language. Plugin cannot import @client session-status-visuals. Exports deriveCardState({valid,disabled,running}) → "running"\|"invalid"\|"disabled"\|"enabled" (precedence running>invalid>disabled>enabled). railBgClass, dotClass, pillLabel, pillClass, stripeFxClass (running → "card-stripes-fx card-stripes-running", else ""). headlessSourceIcon = mdiRobotOutline. GLOW_FX_CLASS/GLOW_FX_OUTER_CLASS/RING_FX_CLASS constants for selected card overlays. Applies host global FX classes by name; animations gated by prefers-reduced-motion in host CSS. See change: automation-ui-mockup-parity. |
| `AutomationBadge.tsx` | session-card-badge. Renders run name chip when `session.kind==="automation"`. See change: add-automation-plugin. |
| `AutomationBoard.tsx` | shell-overlay-route `/folder/:encodedCwd/automations`. Derives cwd from decoded `params.encodedCwd` via decodeFolderPath (not session.cwd). Renders page chrome; Back button wired to onBack. Lists definitions + Triage runs. Archived runs hidden unless "Show archived". Hosts "+ Create Automation" → CreateAutomationDialog. Redesigned board: per-automation cards (trigger summary, next-run, model, action, scope, enabled state); actions Run now/Edit/Enable-Disable/Delete (valid) or Edit/Delete (invalid); recent-runs table (status, runId, relative time, result link); delete confirm wired to DELETE route. Cards adopt session-card visuals via automation-card-visuals (status rail+dot, mdiRobotOutline source icon, status pill, card-stripes-fx running overlay, card-glow-fx/card-ring-fx on selected card). Per-card last-run summary (status pill + relative time + findings + result/log link) from fetched runs. Card meta adds `mode`. Board header adds repo crumb (basename of decoded cwd). Stop action replaces Run now on running card → stopAutomationRun. Edit/Delete under `⋯` overflow menu. Runs table adds findings column + status-specific link (running→watch, error→log, done→result) + stripe overlay on running row. See change: add-automation-plugin. See change: fix-automation-slot-parity-and-routing. See change: redesign-automation-editor-and-board. See change: automation-ui-mockup-parity. Fan-out: a parent run row (child count + aggregate findings + truncation `warning`) expands via `run-expand-<id>` to nested `automation-child-run-<id>` rows (action label, status, findings, result link); children never render as top-level rows; `stopped` status styling + label; `actionSummary` shows "N actions" for `actions:`. See change: add-automation-concurrent-spawn. |
| `AutomationRunMonitor.tsx` | shell-overlay-route `/folder/:encodedCwd/automations/run/:sid` (depth 2, parentPath `/folder/:encodedCwd/automations`). Shows run status; renders result.md via markdownContent primitive on end. Live transcript via standard ChatView for run session. Re-parented from `/automation/run/:sid`, which declared a `parentPath` needing `:encodedCwd` it never captured — `interpolateParentPath` returned null and back always degraded to `/`. No in-app producer navigates here; route is reachable by URL only. See change: add-automation-plugin, add-route-backed-overlay-dialogs. |
| `AutomationSettings.tsx` | settings-section general. Edits defaultVisibility, retentionPerAutomation, scanFolderScope, scanGlobalScope, defaultModel via buffered draft (useSettingsDraftSource). See change: add-automation-plugin. |
| `CreateAutomationDialog.tsx` | Editor dialog. Collects trigger cron, action prompt\|skill, model (@role or id), scope folder\|global, mode, sandbox, concurrency, visibility override. POSTs create route. Redesigned editor: grouped Identity/Trigger/Action/Advanced(collapsed); two-level trigger picker (category tabs → event checklist or cron helper + next-run preview); ModelSelector primitive + @role dropdown; sandbox inline help; worktree gated on git capability; edit mode via initialConfig (saves through update, name locked). Editor visual polish. Group boxes bordered (Identity/Trigger/Action; Advanced collapsed). Segmented controls for Scope + Action kind (replace select). Trigger category pills gain leading mdi icons; event checklist renders 2-col grid. Next-run preview shows relative duration ("in 18h 12m") via relativeFuture() + pulsing green dot; raw-cron escape kept. Header scope/path subtitle + pill-styled "armed on save" chip. Footer caption names files written (.pi/automation/<name>/automation.yaml [+ prompt.md]). See change: add-automation-plugin. See change: redesign-automation-editor-and-board. See change: automation-ui-mockup-parity. Replaces prompt\|skill segmented control with grouped+searchable `ActionPicker` (group-by-source, disabled-with-reason, zero-results) + schema-driven `ActionPayloadForm`; builds action {kind,payload} for plugin actions, core.prompt/core.skill keep prompt body/skill fields. See change: register-plugin-automation-events. ActionPayloadForm renders unknown field `type` as text-input fallback. See change: decouple-automation-action-registry. Multi-action fan-out editor: a primary entry + `add-action-entry` additional entries (per-entry action select, `entry-count-<i>`, skill field, remove) with a `create-action-count` primary count; `toActionBlock` builds each `AutomationAction` (count only when >1); submit writes `actions:` when >1 entry else the single `action:`; edit pre-loads primary+extras from a saved `actions:`. See change: add-automation-concurrent-spawn. Direct-model branch pairs `ui:model-selector` with `ui:thinking-level-selector`; level written as a `:<level>` suffix on the existing `model` field (`splitModelLevel`/`joinModelLevel`, `off`=no-override), split back when seeding an edit. `@role` branch renders NO level control, only `create-model-role-level-hint` naming the owning role. No server/schema change — resolveModel and sessionFlagsToArgv pass the suffix through verbatim. See change: add-default-thinking-level. |
| `folder-encoding.ts` | base64url encode/decode folder paths for shell-overlay-route URLs. Exports encodeFolderPath, decodeFolderPath. Mirrors packages/client/src/lib/folder-encoding.ts. See change: fix-automation-slot-parity-and-routing. |
| `FolderAutomationSection.tsx` | sidebar-folder-section. Re-skinned to FolderOpenSpecSection anatomy: 10px uppercase title `Automations (N)` + mdiArrowRight, mdiRefresh icon, flex-1 spacer, blue `+ New` chip. Title navigates to `/folder/:encodedCwd/automations` via encodeFolderPath. `+ New` opens CreateAutomationDialog directly. Preserves `⚠ N` invalid badge. Count unit label is `tasks` (i18n key automationsUnit; was `flows` — renamed to avoid collision with the distinct pi-flows concept). Renders after first load (incl N=0). Handlers call stopPropagation. See change: add-automation-plugin. See change: fix-automation-slot-parity-and-routing. See change: rename-automation-unit-tasks. |
| `index.tsx` | Client barrel. Exports slot components + isAutomationRun predicate referenced by manifest claims. See change: add-automation-plugin. |
| `predicates.ts` | `isAutomationRun(session)` → `session.kind==="automation"`. Gates session-card-badge. See change: add-automation-plugin. |