@plannotator/ui 0.22.0

package/hooks/useAIProviderConfig.ts

@@ -0,0 +1,115 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { Origin } from '@plannotator/core/agents';
+import {
+  getAIProviderSettings,
+  resolveAIProviderSelection,
+  resolveAIModelForProvider,
+  saveAIProviderSelection,
+  type AIProviderOption,
+} from '../utils/aiProvider';
+
+/**
+ * Shared AI provider/model/reasoning-effort selection state for the plan and
+ * code-review apps. Previously each App.tsx kept its own copy of this logic,
+ * which drifted (e.g. a per-model effort fix landed in one app but not the
+ * other). This owns the config logic in one place:
+ *
+ * - initial selection from saved settings,
+ * - auto-resolving provider/model once capabilities load,
+ * - per-model reasoning effort (a level set on one model never leaks to another),
+ * - persistence of the provider/model choice.
+ *
+ * It deliberately does NOT reset the AI session: `useAIChat` needs `aiConfig`,
+ * and its `resetSession` in turn would depend on this hook — a cycle. So the
+ * caller composes the reset (`applyConfigChange(c); resetSession()`), keeping
+ * session lifecycle with the app and config logic here.
+ */
+export interface AIProviderConfig {
+  providerId: string | null;
+  model: string | null;
+  reasoningEffort: string | null;
+}
+
+interface UseAIProviderConfigOptions {
+  providers: AIProviderOption[];
+  defaultProvider: string | null;
+  available: boolean;
+  origin: Origin | null | undefined;
+}
+
+export function useAIProviderConfig({
+  providers,
+  defaultProvider,
+  available,
+  origin,
+}: UseAIProviderConfigOptions) {
+  const [aiConfig, setAiConfig] = useState(() => {
+    const saved = getAIProviderSettings();
+    const pid = saved.providerId;
+    return {
+      providerId: pid,
+      model: pid ? (saved.preferredModels[pid] ?? null) : null,
+      reasoningEffort: null as string | null,
+      // Reasoning effort is tracked per model so switching models can't carry a
+      // stale (possibly unsupported) level across to a different model.
+      reasoningEffortByModel: {} as Record<string, string>,
+    };
+  });
+
+  // Auto-resolve provider/model once capabilities are known.
+  useEffect(() => {
+    if (!available || providers.length === 0) return;
+    setAiConfig(prev => {
+      const saved = getAIProviderSettings();
+      const selection = resolveAIProviderSelection({
+        providers,
+        origin,
+        settings: saved,
+        serverDefaultProvider: defaultProvider,
+      });
+      if (prev.providerId === selection.providerId && prev.model === selection.model) return prev;
+      return {
+        ...prev,
+        providerId: selection.providerId,
+        model: selection.model,
+        reasoningEffort: selection.model ? (prev.reasoningEffortByModel[selection.model] ?? null) : null,
+      };
+    });
+  }, [available, providers, defaultProvider, origin]);
+
+  // Update the selection (provider/model/effort). Does NOT reset the session —
+  // the caller composes that (see the cycle note above).
+  const applyConfigChange = useCallback(
+    (config: { providerId?: string | null; model?: string | null; reasoningEffort?: string | null }) => {
+      setAiConfig(prev => {
+        const saved = getAIProviderSettings();
+        const providerId = config.providerId !== undefined ? config.providerId : prev.providerId;
+        const providerChanged = config.providerId !== undefined && config.providerId !== prev.providerId;
+        const provider = providers.find(p => p.id === providerId) ?? null;
+        const model = providerChanged
+          ? (config.model !== undefined ? config.model : resolveAIModelForProvider(provider, saved.preferredModels))
+          : (config.model !== undefined ? config.model : prev.model);
+        // Per-model reasoning effort: record an explicit change against the
+        // current model, then derive the effective level from the (possibly new)
+        // model — so a provider/model switch never carries a stale level across.
+        const reasoningEffortByModel = { ...prev.reasoningEffortByModel };
+        if (config.reasoningEffort !== undefined && prev.model) {
+          if (config.reasoningEffort === null) delete reasoningEffortByModel[prev.model];
+          else reasoningEffortByModel[prev.model] = config.reasoningEffort;
+        }
+        const reasoningEffort = model ? (reasoningEffortByModel[model] ?? null) : null;
+        const next = { ...prev, providerId, model, reasoningEffort, reasoningEffortByModel };
+        saveAIProviderSelection({
+          providerId: next.providerId,
+          model: next.model,
+          origin,
+          settings: saved,
+        });
+        return next;
+      });
+    },
+    [providers, origin],
+  );
+
+  return { aiConfig, applyConfigChange };
+}

package/hooks/useActiveSection.ts

@@ -0,0 +1,78 @@
+import { useEffect, useState, useRef } from 'react';
+
+/**
+ * Track which heading section is currently visible in the viewport
+ * Uses Intersection Observer to detect when headings enter/leave view
+ */
+export function useActiveSection(
+  containerRef: React.RefObject<HTMLElement | null>,
+  headingCount: number,
+  /** Optional explicit scroll element. When provided, takes precedence over
+   *  containerRef.current and re-runs the effect when it changes — needed
+   *  for OverlayScrollArea, whose viewport is only available after mount. */
+  scrollElement?: HTMLElement | null,
+) {
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const observerRef = useRef<IntersectionObserver | null>(null);
+
+  useEffect(() => {
+    const container = scrollElement ?? containerRef.current;
+    if (!container) return;
+    
+    // Find all heading elements with data-block-id
+    const headings = container.querySelectorAll('[data-block-type="heading"]');
+    if (headings.length === 0) return;
+    
+    // Track which headings are currently intersecting
+    const intersectingHeadings = new Map<Element, boolean>();
+    
+    // Create observer with configuration to detect headings near top of viewport
+    observerRef.current = new IntersectionObserver(
+      (entries) => {
+        // Update intersection state
+        entries.forEach(entry => {
+          intersectingHeadings.set(entry.target, entry.isIntersecting);
+        });
+        
+        // Find the first intersecting heading (topmost in viewport)
+        let topHeading: Element | null = null;
+        let topPosition = Infinity;
+        
+        for (const [heading, isIntersecting] of intersectingHeadings) {
+          if (isIntersecting) {
+            const rect = heading.getBoundingClientRect();
+            if (rect.top < topPosition) {
+              topPosition = rect.top;
+              topHeading = heading;
+            }
+          }
+        }
+        
+        // Update active ID
+        if (topHeading) {
+          const blockId = topHeading.getAttribute('data-block-id');
+          if (blockId) {
+            setActiveId(blockId);
+          }
+        }
+      },
+      {
+        root: container,
+        rootMargin: '-80px 0px -80% 0px', // Activate when heading is near top
+        threshold: [0, 0.1, 0.5, 1.0],
+      }
+    );
+    
+    // Observe all headings
+    headings.forEach(heading => {
+      observerRef.current?.observe(heading);
+    });
+    
+    // Cleanup
+    return () => {
+      observerRef.current?.disconnect();
+    };
+  }, [containerRef, headingCount, scrollElement]);
+  
+  return activeId;
+}

package/hooks/useAgentJobs.ts

@@ -0,0 +1,306 @@
+/**
+ * Real-time agent job state via SSE with polling fallback.
+ *
+ * Primary transport: EventSource on /api/agents/jobs/stream.
+ * Fallback: version-gated GET polling if SSE fails.
+ *
+ * Mirrors packages/ui/hooks/useExternalAnnotations.ts in structure.
+ *
+ * Gated by an `enabled` option — callers pass their API-mode signal
+ * to avoid SSE/polling in static or demo contexts where there is no server.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type { AgentJobInfo, AgentJobEvent, AgentCapabilities } from '../types';
+
+const POLL_INTERVAL_MS = 500;
+const STREAM_URL = '/api/agents/jobs/stream';
+const JOBS_URL = '/api/agents/jobs';
+const CAPABILITIES_URL = '/api/agents/capabilities';
+const DEFAULT_LAUNCH_ERROR = 'Could not start agent job.';
+const AGENT_JOB_STATUSES = new Set(['starting', 'running', 'done', 'failed', 'killed']);
+
+export type AgentLaunchParams = {
+  provider?: string;
+  command?: string[];
+  label?: string;
+  engine?: string;
+  model?: string;
+  reasoningEffort?: string;
+  effort?: string;
+  /** Pi's unified reasoning level (`--thinking off|minimal|low|medium|high|xhigh`). */
+  thinking?: string;
+  fastMode?: boolean;
+  reviewProfileId?: string;
+  /** Launches a guide-repair job against a failed guide job's captured output
+   *  (see GuideEmptyState's failure-recovery panel). The server resolves a
+   *  schema-capable engine and starts a new, normal guide job rather than
+   *  mutating the failed one in place. */
+  repairOf?: string;
+};
+
+/** Does a job belong to the given review context? Jobs launched against a PR
+ *  are stamped with that PR's url; local-diff jobs carry none. Used to scope
+ *  guide/tour auto-opens, the guide takeover, and "Open guide" affordances so
+ *  an artifact from PR A never opens (or offers to open) while reviewing PR B.
+ *  `currentPrUrl` undefined ⇒ local-diff mode.
+ *
+ *  prUrl + worktreePath define WHERE the review is (the context — matched
+ *  strictly below); mode/base/scope define WHAT VIEW of that context is on
+ *  screen. In PR mode only prUrl is compared (a PR checkout has no separate
+ *  worktree axis). In local-diff mode, `currentWorktreePath` distinguishes a
+ *  review retargeted at a git worktree (`worktree:<path>:<subType>` diff
+ *  types — see parseWorktreeDiffType) from the main tree, so a guide/tour
+ *  launched against worktree A never opens while reviewing worktree B. Jobs
+ *  launched before this field existed, and jobs from providers that never set
+ *  `diffContext`, coalesce to the main tree (`null`) — deliberate, so old jobs
+ *  keep matching the common case instead of going permanently unmatchable.
+ *
+ *  DELIBERATELY matches by prUrl/worktreePath only — NOT diffScope/mode/base,
+ *  even though jobs carry them. Annotations scope by diffScope because they
+ *  pin exact line positions in a specific patch; guides/tours reference FILES
+ *  and degrade per-file ("no longer in the current diff") when the diff
+ *  shifts underneath them. Layer→full-stack is a superset (the artifact
+ *  fully resolves — hiding it would be hostile); full-stack→layer and local
+ *  base/mode switches degrade honestly. Scope-strict matching here would
+ *  vaporize a useful guide because the reviewer toggled since-base →
+ *  uncommitted. Do not "tighten" this without a UX decision. */
+export function jobMatchesReviewContext(
+  job: Pick<AgentJobInfo, 'prUrl' | 'diffContext'>,
+  currentPrUrl: string | undefined,
+  currentWorktreePath?: string | null,
+): boolean {
+  if (currentPrUrl) return job.prUrl === currentPrUrl;
+  if (job.prUrl) return false;
+  return (job.diffContext?.worktreePath ?? null) === (currentWorktreePath ?? null);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+function isAgentJobInfo(value: unknown): value is AgentJobInfo {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.id === 'string' &&
+    typeof value.source === 'string' &&
+    typeof value.provider === 'string' &&
+    typeof value.label === 'string' &&
+    typeof value.status === 'string' &&
+    AGENT_JOB_STATUSES.has(value.status) &&
+    typeof value.startedAt === 'number' &&
+    isStringArray(value.command)
+  );
+}
+
+function upsertJob(jobs: AgentJobInfo[], job: AgentJobInfo): AgentJobInfo[] {
+  const existing = jobs.findIndex((current) => current.id === job.id);
+  if (existing === -1) return [...jobs, job];
+  const next = [...jobs];
+  next[existing] = job;
+  return next;
+}
+
+async function readResponseError(response: Response): Promise<string> {
+  try {
+    const body: unknown = await response.json();
+    if (body && typeof body === 'object' && 'error' in body) {
+      const error = (body as { readonly error?: unknown }).error;
+      if (typeof error === 'string' && error.trim()) return error;
+    }
+  } catch {
+    // Fall through to the generic launch message.
+  }
+  return DEFAULT_LAUNCH_ERROR;
+}
+
+function parseLaunchJob(body: unknown): AgentJobInfo | null {
+  if (!isRecord(body)) return null;
+  const job = body.job;
+  return isAgentJobInfo(job) ? job : null;
+}
+
+interface UseAgentJobsReturn {
+  jobs: AgentJobInfo[];
+  jobLogs: Map<string, string>;
+  capabilities: AgentCapabilities | null;
+  /** Rejects with a user-facing message when the server refuses the launch. */
+  launchJob: (params: AgentLaunchParams) => Promise<AgentJobInfo | null>;
+  killJob: (id: string) => Promise<void>;
+  killAll: () => Promise<void>;
+}
+
+export function useAgentJobs(
+  options?: { enabled?: boolean },
+): UseAgentJobsReturn {
+  const enabled = options?.enabled ?? true;
+  const [jobs, setJobs] = useState<AgentJobInfo[]>([]);
+  const [jobLogs, setJobLogs] = useState<Map<string, string>>(new Map());
+  const [capabilities, setCapabilities] = useState<AgentCapabilities | null>(null);
+  const versionRef = useRef(0);
+  const fallbackRef = useRef(false);
+  const pollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const receivedSnapshotRef = useRef(false);
+
+  // Fetch capabilities once on mount
+  useEffect(() => {
+    if (!enabled) return;
+
+    fetch(CAPABILITIES_URL)
+      .then((res) => res.json())
+      .then((data) => {
+        if (data && Array.isArray(data.providers)) {
+          setCapabilities(data as AgentCapabilities);
+        }
+      })
+      .catch(() => {
+        // Silent — capabilities unavailable
+      });
+  }, [enabled]);
+
+  // SSE + polling for job state
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    receivedSnapshotRef.current = false;
+    fallbackRef.current = false;
+
+    // --- SSE primary transport ---
+    const es = new EventSource(STREAM_URL);
+
+    es.onmessage = (event) => {
+      if (cancelled) return;
+
+      try {
+        const parsed: AgentJobEvent = JSON.parse(event.data);
+
+        switch (parsed.type) {
+          case 'snapshot':
+            receivedSnapshotRef.current = true;
+            setJobs(parsed.jobs);
+            break;
+          case 'job:started':
+            setJobs((prev) => upsertJob(prev, parsed.job));
+            break;
+          case 'job:updated':
+          case 'job:completed':
+            setJobs((prev) =>
+              prev.map((j) => (j.id === parsed.job.id ? parsed.job : j)),
+            );
+            break;
+          case 'job:log':
+            setJobLogs((prev) => {
+              const next = new Map(prev);
+              next.set(parsed.jobId, (prev.get(parsed.jobId) ?? '') + parsed.delta);
+              return next;
+            });
+            break;
+          case 'jobs:cleared':
+            // No-op: killAll() already broadcasts individual job:completed events
+            // for each killed job, so the UI updates incrementally.
+            break;
+        }
+      } catch {
+        // Ignore malformed events (e.g., heartbeat comments)
+      }
+    };
+
+    es.onerror = () => {
+      // If we never received a snapshot, SSE isn't working — fall back to polling
+      if (!receivedSnapshotRef.current && !fallbackRef.current) {
+        fallbackRef.current = true;
+        es.close();
+        startPolling();
+      }
+      // Otherwise, EventSource will auto-reconnect and we'll get a fresh snapshot
+    };
+
+    // --- Polling fallback ---
+    function startPolling() {
+      if (cancelled) return;
+
+      fetchSnapshot();
+
+      pollTimerRef.current = setInterval(() => {
+        if (cancelled) return;
+        fetchSnapshot();
+      }, POLL_INTERVAL_MS);
+    }
+
+    async function fetchSnapshot() {
+      try {
+        const url =
+          versionRef.current > 0
+            ? `${JOBS_URL}?since=${versionRef.current}`
+            : JOBS_URL;
+
+        const res = await fetch(url);
+
+        if (res.status === 304) return;
+        if (!res.ok) return;
+
+        const data = await res.json();
+        if (Array.isArray(data.jobs)) {
+          setJobs(data.jobs);
+        }
+        if (typeof data.version === 'number') {
+          versionRef.current = data.version;
+        }
+      } catch {
+        // Silent — next poll will retry
+      }
+    }
+
+    return () => {
+      cancelled = true;
+      es.close();
+      if (pollTimerRef.current) {
+        clearInterval(pollTimerRef.current);
+        pollTimerRef.current = null;
+      }
+    };
+  }, [enabled]);
+
+  const launchJob = useCallback(
+    async (params: AgentLaunchParams): Promise<AgentJobInfo | null> => {
+      const res = await fetch(JOBS_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(params),
+      });
+      if (!res.ok) {
+        throw new Error(await readResponseError(res));
+      }
+
+      const data: unknown = await res.json();
+      const job = parseLaunchJob(data);
+      if (job) setJobs((prev) => upsertJob(prev, job));
+      return job;
+    },
+    [],
+  );
+
+  const killJob = useCallback(async (id: string) => {
+    try {
+      await fetch(`${JOBS_URL}/${encodeURIComponent(id)}`, {
+        method: 'DELETE',
+      });
+    } catch {
+      // SSE will reconcile
+    }
+  }, []);
+
+  const killAll = useCallback(async () => {
+    try {
+      await fetch(JOBS_URL, { method: 'DELETE' });
+    } catch {
+      // SSE will reconcile
+    }
+  }, []);
+
+  return { jobs, jobLogs, capabilities, launchJob, killJob, killAll };
+}