AGENTS.md@packages/goal-plugin/src/client · git:20260703.e20cd5a · 2026-07-03 · sha256 9fe078dd0e044bc2
AGENTS.md@packages/goal-plugin/src/client git:20260703.e20cd5aA

Name: AGENTS.md@packages/goal-plugin/src/client
Author: blackbelttechnology
Immutable. This exact content is served forever at /api/v1/blob/9fe078dd0e044bc2.
# DOX — packages/goal-plugin/src/client

Files in this directory. One row per source file.

| File | Purpose |
|------|---------|
| `CreateGoalDialog.tsx` | Shared goal create modal. Wraps `GoalForm`. Overlay `fixed inset-0 z-50 bg-black/40`, card `max-w-lg max-h-[90vh] bg-[var(--bg-primary)]` — verbatim from automation `CreateAutomationDialog` for plugin parity. Owns `createGoal(cwd,payload)` POST; fires `onCreated` then `onClose`. Backdrop click + ✕ (`goal-create-dialog-close`, aria-label) close. testids `goal-create-dialog`, `goal-create-dialog-title`. Opened by FolderGoalsSection + GoalsBoardClaim. See change: redesign-goal-create-dialog. |
| `FolderGoalsSection.tsx` | `sidebar-folder-section` slot. Shows `Goals (N) →` (opens goals board) + mdiRefresh + `+ Goal` inline objective input → createGoal → navigate goalsBoardUrl(cwd). Reads useGoals(folder.cwd). Navigates via wouter useLocation. See change: add-goals-folder-page. `+ Goal` now renders `GoalForm` (was single objective input) → createGoal → navigate board. See change: sophisticate-goal-authoring-and-control. `+ Goal` now opens shared `CreateGoalDialog` modal (was inline `folder-goal-create` panel); onCreated → refetch + navigate board. See change: redesign-goal-create-dialog. |
| `goal-state.ts` | `deriveSnapshot(events)` folds plugin per-session event store to latest `goal_status` event. Returns null when none or status cleared. Last write wins. See change: add-goal-continuation-plugin. |
| `GoalChip.tsx` | `session-card-badge` slot. Reads `useSessionEvents`, folds `deriveSnapshot`. Renders `● Pursuing n/m` (active), `⏸ Paused · reason` (paused), `✓ Achieved` (done). Theme-reactive palette via `useIsLightTheme` MutationObserver on `<html data-theme>`. Null when no snapshot. See change: add-goal-continuation-plugin. |
| `GoalControl.tsx` | `session-card-action-bar` slot. Screen D rich chip: live `⚑ turns/maxTurns · verdict` from deriveSnapshot, inline Pause (sendPluginAction pause, only when active), open-detail button (testid goal-control-link). Null when no goalId/cwd. `Set a goal…` input + set/pause/resume/done/clear controls removed; creation/controls moved to folder level. See change: add-goal-continuation-plugin. See change: add-goals-folder-page. See change: sophisticate-goal-authoring-and-control. |
| `GoalDetailClaim.tsx` | `shell-overlay-route` `/folder/:encodedCwd/goals/:goalId`. Goal detail: definition panel (objective, pursuing/paused/achieved status buttons, criteria) + linked-sessions list. Controls: `+ New session` (spawnSession + goalId stamp at register), `Link existing…` (linkSession), unlink, ⚑ driver tag. Opens linked chat via navigate `/session/:id`. Derives cwd from decodeFolderPath(params.encodedCwd). Reads useGoals + useAllSessions. See change: add-goals-folder-page. Adds loop-control bar (pause/resume/done/clear/subgoal via `sendPluginAction(GOAL_PLUGIN_ID, driverSessionId, action)`), dual budget gauges (turns live + spend cap), editable criteria (toggle done, add subgoal), newest-first verdict timeline from `goal.verdicts` (empty state), delete (confirm → deleteGoal → navigate board). See change: sophisticate-goal-authoring-and-control. |
| `GoalForm.tsx` | Screen A authoring form. Captures objective, editable criteria, judge picker (from `useJudgeModels`), budget (maxTurns/maxSpendUsd), self-judge toggle, cross-model/self-judge badge. Emits `GoalFormPayload` via onSubmit. Reused by FolderGoalsSection + GoalsBoardClaim. See change: sophisticate-goal-authoring-and-control. |
| `GoalPluginSettings.tsx` | `settings-section` general tab. Static panel. States loop/judge/budget owned by `@ricoyudog/pi-goal-hermes` extension; install to activate. See change: add-goal-continuation-plugin. |
| `goals-api.ts` | REST client + base64url folder-path codec. Relative `/api/folders/goals*` URLs (same-origin, ApiResponse `{success,data,error}`). Exports encodeFolderPath/decodeFolderPath (UTF-8 safe), goalsBoardUrl/goalDetailUrl, fetchGoals/createGoal/updateGoal/deleteGoal, linkSession/spawnSession/unlinkSession. See change: add-goals-folder-page. `createGoal`/`updateGoal` bodies gain `judge?`. Adds `fetchJudgeModels(signal)` (GET /api/favorite-models), `parseModelLabel(label)` → {provider,modelId}. See change: sophisticate-goal-authoring-and-control. |
| `GoalsBoardClaim.tsx` | `shell-overlay-route` `/folder/:encodedCwd/goals`. Goals board: header (back / refresh / `+ New Goal` objective input), All/Pursuing/Paused/Achieved filter tabs, goal cards (objective, status badge, live turns n/m via deriveSnapshot, criteria, expandable linked sessions). Derives cwd from decodeFolderPath(params.encodedCwd). Opens detail via goalDetailUrl. See change: add-goals-folder-page. `+ New Goal` renders `GoalForm`. Enriched `GoalCard`: `TurnRing` (live turns), live/record verdict pill, criteria progress, spend bar. Card delete overflow (window.confirm → deleteGoal → refetch). See change: sophisticate-goal-authoring-and-control. `+ New Goal` now opens shared `CreateGoalDialog` modal (was inline `goals-board-create` panel); onCreated → refetch. See change: redesign-goal-create-dialog. |
| `index.tsx` | Client barrel. Exports `GoalChip`, `GoalControl`, `GoalPluginSettings`, `FolderGoalsSection`, `GoalsBoardClaim`, `GoalDetailClaim`, `hasGoal`, `deriveSnapshot`. Generated plugin-registry imports these. See change: add-goal-continuation-plugin. See change: add-goals-folder-page. |
| `predicates.ts` | `hasGoal(session)` slot predicate. Reads `getSessionEvents(session.id)` sync, returns `deriveSnapshot !== null`. Gates `session-card-badge` claim. See change: add-goal-continuation-plugin. |
| `useGoals.ts` | `useGoals(cwd)` hook. Fetches folder GoalRecords on mount via fetchGoals + exposes refetch (nonce bump). No live WS subscription; refetch after mutations / Refresh button. Exports `statusMeta(status)` → label/dot/cls palette (achieved/paused/cleared/pursuing). See change: add-goals-folder-page. |
| `useJudgeModels.ts` | `useJudgeModels()` fetches `/api/favorite-models` labels for judge picker. Failures degrade to empty list. See change: sophisticate-goal-authoring-and-control. |