@immediately-run/grove 0.1.2 → 0.1.3

package/src/components/GroveAgent.tsx

@@ -1,130 +1,243 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { useEffect, useRef, useState } from 'react';
-import { chat, useChatProvider } from '@immediately-run/sdk';
-import { useShell } from '../lib/shell';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import {
+  runAgent,
+  createChatModelClient,
+  useChatProviderState,
+  useCatalog,
+  useAllMetadata,
+  useAgentContext,
+  renderAgentContext,
+  type AgentMessage,
+} from '@immediately-run/sdk';
+import { useShell, EDIT_REFUSED_NOTICE } from '../lib/shell';
+import { useHeadings, useActiveHeading } from '../hooks/useHeadings';
+import { useOverlayFocusDismiss } from '../hooks/useOverlayFocusDismiss';
+import { getContentRoot } from '../lib/contentRoot';
+import { createReadEntryTool, createGroveMetadataTool, groveAgentTools, toolExecutor } from '../lib/agentTools';
+import { buildSystemPrompt } from '../lib/agentPrompt';
+import { computeReachRows, reachChips, showEgressDisclosure, EGRESS_DISCLOSURE } from '../lib/reachCard';
+import { transcriptToRows, toolActivityLine, type AgentRow } from '../lib/agentTranscript';
+import { safeSources } from '../lib/safeSources';
 import Icon from './Icon';
 
-interface Msg {
-  role: 'user' | 'assistant';
-  text: string;
-}
-
-type Banner = null | 'no-key' | 'forbidden' | 'read-only' | 'error';
-
-const CHIPS = [
-  'Add an entry…',
-  'Fix broken links here',
-  'Summarize this entry',
-  'Reorganize the sidebar',
-  'Add a timeline view',
-];
-
-// `.grove-agent` (brief 06) — Grove's own, always-present, capability-scoped agent.
-// Resting state: the thin "Ask Grove…" input line pinned to the bottom (approach 1,
-// the recommended posture — content stays fully visible until invoked). Expands into
-// a bottom dock (desktop) / sheet (mobile). Rides the host `llm.chat@1` slot via the
-// SDK `chat()` stream; degrades to the SP-7 connect-a-key / forbidden / read-only
-// banners rather than faking a host surface.
-export default function GroveAgent({ writable, entryKey, entryTitle }: { writable: boolean; entryKey: string; entryTitle: string }) {
-  const provider = useChatProvider();
-  const { openEditor } = useShell();
+// `.grove-agent` — Grove's own embedded agent (GROVE_AGENT_SPEC).
+//
+// The surface is a FUNCTION of the session's envelope (R-GA-1): the reach card in
+// the expanded header is computed from the provider three-state, the `llm:chat`
+// grant (the grant-filtered catalog), mount writability, and source trust — never
+// hand-written copy. The loop rides the workbench's seam — SDK `runAgent` over the
+// host `llm.chat` slot — and its two tools are the mount-chrooted `read_entry` and
+// the index query (R-GA-2). The widget never writes (R-GA-3): every change is a
+// hand-off to the editor / workbench. Read-only never blocks Q&A (R-GA-5). When a
+// provider is bound the egress line is shown unconditionally (R-GA-6). Every
+// corpus-derived byte entering the loop is fenced (R-GA-7).
+export default function GroveAgent({
+  writable,
+  entryKey,
+  entryTitle,
+}: {
+  writable: boolean;
+  entryKey: string;
+  entryTitle: string;
+}) {
+  const providerState = useChatProviderState();
+  const catalog = useCatalog();
+  const index = useAllMetadata();
+  const headings = useHeadings(entryKey);
+  const activeHeading = useActiveHeading(headings);
+  const { openEditor, editRefused } = useShell();
   const [open, setOpen] = useState(false);
   const [detent, setDetent] = useState<'half' | 'full'>('half');
   const [resting, setResting] = useState('');
   const [draft, setDraft] = useState('');
-  const [msgs, setMsgs] = useState<Msg[]>([]);
+  const [rows, setRows] = useState<AgentRow[]>([]);
   const [streaming, setStreaming] = useState(false);
-  const [sendBanner, setSendBanner] = useState<Banner>(null);
+  const [errorToast, setErrorToast] = useState<string | null>(null);
   const bodyRef = useRef<HTMLDivElement>(null);
   const footRef = useRef<HTMLInputElement>(null);
+  // One AbortController per run (R3-608): the composer's stop control aborts the
+  // in-flight run through the SDK signal the loop already honours.
+  const abortRef = useRef<AbortController | null>(null);
+  // The panel carries the dialog contract (R3-608): focus in, Tab trapped,
+  // Escape, focus return — the shared hook, stack-aware.
+  const dialogRef = useOverlayFocusDismiss(open, () => setOpen(false));
+
+  // The envelope, computed (R-GA-1). `llm:chat` appears in the grant-filtered
+  // catalog iff this app holds the consent — an ungranted fork reads a DISTINCT
+  // cause from a user without a key (G-GA-10).
+  const chatGranted = catalog.some((m) => m.name === 'llm:chat');
+  const context = useAgentContext({ entryPath: entryKey, entryTitle, heading: activeHeading || undefined });
+  const reachRows = useMemo(
+    () => computeReachRows({ providerState, chatGranted, writable, sourceShared: context.sourceShared }),
+    [providerState, chatGranted, writable, context.sourceShared],
+  );
+  const chips = useMemo(() => reachChips(reachRows), [reachRows]);
+  const canAsk = providerState.status === 'configured' && chatGranted;
+
+  // Read at CALL time (a scan may land, the reader may navigate) — refs kept fresh
+  // in an effect, never written during render (the react-hooks compiler rejects that).
+  const indexRef = useRef(index);
+  const contextRef = useRef(context);
+  const entryRef = useRef(entryKey);
+  const headingRef = useRef(activeHeading);
+  useEffect(() => {
+    indexRef.current = index;
+    contextRef.current = context;
+    entryRef.current = entryKey;
+    headingRef.current = activeHeading;
+  }, [index, context, entryKey, activeHeading]);
 
-  // Derived banner: read-only (no write grant) / no-key (no provider bound, SP-7)
-  // come straight from props+provider; send-time errors layer on top.
-  const staticBanner: Banner = !writable ? 'read-only' : provider === null ? 'no-key' : null;
-  const banner: Banner = sendBanner || staticBanner;
+  // The loop's transcript, kept so follow-up questions replay the tool-use chain.
+  const transcriptRef = useRef<AgentMessage[]>([]);
 
   useEffect(() => {
     if (open) requestAnimationFrame(() => footRef.current?.focus());
   }, [open]);
+  // The panel's only trigger (the resting input) UNMOUNTS when it opens, and
+  // its onFocus IS the open action — returning focus to it would reopen the
+  // panel. So the close path returns focus to the resting line's SUBMIT
+  // control (R-IX-1): a real stop in the same surface that never reopens
+  // anything, so Escape never strands the keyboard on <body>. On mount the
+  // effect stays quiet (was-open gate) or the panel would open itself.
+  const restingGoRef = useRef<HTMLButtonElement>(null);
+  const wasOpenRef = useRef(false);
+  useEffect(() => {
+    if (wasOpenRef.current && !open) requestAnimationFrame(() => restingGoRef.current?.focus());
+    wasOpenRef.current = open;
+  }, [open]);
   useEffect(() => {
     bodyRef.current?.scrollTo({ top: bodyRef.current.scrollHeight });
-  }, [msgs, streaming]);
+  }, [rows, streaming]);
 
-  async function send(text: string) {
-    const q = text.trim();
+  async function ask(question: string) {
+    const q = question.trim();
     if (!q || streaming) return;
     setOpen(true);
     setDraft('');
     setResting('');
-    const history = [...msgs, { role: 'user' as const, text: q }];
-    setMsgs([...history, { role: 'assistant', text: '' }]);
+    setErrorToast(null);
+    setRows((prev) => [...prev, { kind: 'user', text: q }]);
     setStreaming(true);
-    setSendBanner(null);
 
+    // G-GA-8: a provider without `features.tools` degrades to context-stuffing —
+    // the deixis block, an index summary, and the current entry body ride the
+    // prompt; the request carries ZERO tools.
+    const toolsSupported = providerState.status === 'configured' && providerState.provider.features.tools === true;
+    const chroot = getContentRoot();
+    const currentKey = entryRef.current;
+    const contextBlock = renderAgentContext({
+      ...contextRef.current,
+      entryPath: currentKey,
+      heading: headingRef.current || undefined,
+    });
+    let stuffedBody: string | undefined;
+    if (!toolsSupported) {
+      stuffedBody = await safeSources.read(currentKey).catch(() => undefined);
+    }
+    const system = buildSystemPrompt({
+      contextBlock,
+      toolsSupported,
+      ...(toolsSupported ? {} : { entryBody: stuffedBody, entryPath: currentKey, index: indexRef.current, chroot }),
+    });
+    const entryTool = createReadEntryTool(chroot);
+    const metaTool = createGroveMetadataTool(chroot, () => indexRef.current);
+    const execute = toolExecutor([entryTool, metaTool]);
+    const tools = toolsSupported ? groveAgentTools(chroot, () => indexRef.current) : [];
+
+    let acc = '';
+    const pushAssistant = (text: string) =>
+      setRows((prev) => {
+        const next = prev.slice();
+        if (next.length && next[next.length - 1].kind === 'assistant') next[next.length - 1] = { kind: 'assistant', text };
+        else next.push({ kind: 'assistant', text });
+        return next;
+      });
+    const controller = new AbortController();
+    abortRef.current = controller;
     try {
-      const req = {
-        messages: [
-          {
-            role: 'system' as const,
-            content: [
-              {
-                type: 'text' as const,
-                text: `You are Grove, the embedded agent for this MDX wiki. Entries live as .mdx files under /content and interlink with markdown links and frontmatter tags. The reader is currently on "${entryTitle}". Be concise and wiki-fluent; when you propose changes, describe them plainly. You never see secrets and privileged writes are confirmed by the host.`,
-              },
-            ],
+      const final = await runAgent({
+        client: createChatModelClient(),
+        tools,
+        execute,
+        system,
+        prompt: q,
+        history: transcriptRef.current,
+        maxTurns: 8,
+        signal: controller.signal,
+        events: {
+          onAssistantDelta: (t) => {
+            acc += t;
+            pushAssistant(acc);
+          },
+          onToolUse: (name, input) => {
+            acc = '';
+            setRows((prev) => {
+              const next = prev.slice();
+              if (next.length && next[next.length - 1].kind === 'assistant' && !next[next.length - 1].text) next.pop();
+              next.push({ kind: 'activity', text: toolActivityLine(name, input) });
+              return next;
+            });
           },
-          ...history.map((m) => ({
-            role: m.role,
-            content: [{ type: 'text' as const, text: m.text }],
-          })),
-        ],
-        modelHint: 'smart' as const,
-      };
-      let acc = '';
-      for await (const d of chat(req)) {
-        if (d.type === 'text-delta') {
-          acc += d.text;
-          setMsgs((prev) => {
-            const next = prev.slice();
-            next[next.length - 1] = { role: 'assistant', text: acc };
-            return next;
-          });
-        }
+        },
+      });
+      const rendered = transcriptToRows(final);
+      // The real loop RESOLVES an aborted run with the partial transcript (a
+      // clean stop, never a thrown error) — so the abort check lives here too,
+      // not only in the catch: a stopped run keeps what streamed and appends a
+      // named Stopped row (R3-608).
+      if (controller.signal.aborted) {
+        setRows((prev) => [...prev, { kind: 'activity', text: 'Stopped' }]);
+        return;
+      }
+      if (!rendered.some((r) => r.kind === 'assistant')) throw new Error('empty');
+      transcriptRef.current = final.slice();
+      setRows(rendered);
+    } catch (e) {
+      // A stop is not an error (R3-608): the aborted run settles with a named
+      // "Stopped" row, and the transcript keeps what streamed so far.
+      if (controller.signal.aborted) {
+        setRows((prev) => [...prev, { kind: 'activity', text: 'Stopped' }]);
+        return;
       }
-      if (!acc) throw new Error('empty');
-    } catch (e: any) {
-      const code = e?.code || e?.message;
-      setSendBanner(code === 'auth-required' ? 'no-key' : code === 'forbidden' ? 'forbidden' : 'error');
-      // Drop the empty assistant placeholder.
-      setMsgs((prev) => (prev.length && prev[prev.length - 1].text === '' ? prev.slice(0, -1) : prev));
+      const code = (e as { code?: string })?.code || (e as Error).message;
+      setErrorToast(
+        code === 'auth-required'
+          ? 'no model key connected — add one in Settings'
+          : code === 'forbidden'
+            ? "this Grove wasn't granted chat — reading works as normal"
+            : 'the model or backend errored — try again in a moment',
+      );
+      setRows((prev) =>
+        prev.length && prev[prev.length - 1].kind === 'assistant' && !prev[prev.length - 1].text ? prev.slice(0, -1) : prev,
+      );
     } finally {
       setStreaming(false);
+      if (abortRef.current === controller) abortRef.current = null;
     }
   }
 
-  const restingDisabled = banner === 'read-only';
-
   return (
     <div className="grove-agent">
-      {/* Resting: the always-present thin input line (approach 1). */}
+      {/* Resting: the always-present thin input line. Q&A is never disabled by
+          read-only (R-GA-5) — only by the envelope genuinely lacking a provider. */}
       {!open && (
         <form
           className="ga-line"
           onSubmit={(e) => {
             e.preventDefault();
-            if (restingDisabled) setOpen(true);
-            else send(resting);
+            if (canAsk) void ask(resting);
+            else setOpen(true);
           }}
         >
           <span className="mk" />
           <input
             value={resting}
-            placeholder={restingDisabled ? 'Ask Grove about this wiki…' : `Ask Grove to change "${entryTitle}"…`}
+            placeholder={`Ask Grove about “${entryTitle}”…`}
             onChange={(e) => setResting(e.target.value)}
             onFocus={() => setOpen(true)}
             aria-label="Ask Grove"
           />
-          <button className="go" type="submit" aria-label="Ask Grove">
+          <button ref={restingGoRef} className="go" type="submit" aria-label="Ask Grove">
             <Icon name="send" />
           </button>
         </form>
@@ -134,16 +247,20 @@ export default function GroveAgent({ writable, entryKey, entryTitle }: { writabl
       {open && (
         <>
           <div className="ga-scrim" onClick={() => setOpen(false)} />
-          <div className="ga-panel" data-detent={detent}>
+          <div
+            className="ga-panel"
+            data-detent={detent}
+            ref={dialogRef}
+            tabIndex={-1}
+            role="dialog"
+            aria-modal="true"
+            aria-label="Ask Grove"
+          >
             <div className="ga-panel-inner">
               <div className="ga-head">
                 <span className="grip" onClick={() => setDetent((d) => (d === 'half' ? 'full' : 'half'))} />
                 <span className="mk" />
                 <span className="id">Grove</span>
-                <span className="scope">
-                  <Icon name="shield" />
-                  scoped to this wiki
-                </span>
                 <span className="grow">
                   <button className="ic" aria-label={detent === 'half' ? 'Expand' : 'Collapse'} onClick={() => setDetent((d) => (d === 'half' ? 'full' : 'half'))}>
                     <Icon name={detent === 'half' ? 'chevron-down' : 'chevron-right'} />
@@ -154,19 +271,36 @@ export default function GroveAgent({ writable, entryKey, entryTitle }: { writabl
                 </span>
               </div>
 
-              {banner && <AgentBanner banner={banner} />}
+              {/* The reach card — the envelope, computed (R-GA-1). */}
+              <div className="ga-reach" role="list" aria-label="What the agent can do here">
+                {reachRows.map((r) => (
+                  <div className={`ga-reach__row ga-reach__row--${r.state}`} role="listitem" key={r.key}>
+                    <span className="ga-reach__mark" aria-hidden>
+                      {r.state === 'ok' ? '✓' : r.state === 'blocked' ? '✗' : '·'}
+                    </span>
+                    <span className="ga-reach__label">{r.label}</span>
+                    {r.cause && <span className="ga-reach__cause">{r.cause}</span>}
+                  </div>
+                ))}
+              </div>
+              {showEgressDisclosure(providerState) && <p className="ga-egress">{EGRESS_DISCLOSURE}</p>}
+              {errorToast && (
+                <div className="ga-toast" role="status">
+                  {errorToast}
+                </div>
+              )}
 
               <div className="ga-body" ref={bodyRef}>
-                {msgs.length === 0 ? (
+                {rows.length === 0 ? (
                   <>
                     <div className="ga-explain">
-                      <b>Grove's agent</b> knows this wiki's entries, tags, and components. Ask it to add or
-                      change content in plain language — it proposes the edit, and the host confirms the write.
+                      <b>Grove's agent</b> answers questions about this wiki — its entries, tags, and structure — from the
+                      page you're on.
                     </div>
-                    {!restingDisabled && (
+                    {chips.length > 0 && (
                       <div className="ga-chips">
-                        {CHIPS.map((c) => (
-                          <button key={c} className="ga-chip" onClick={() => send(c)}>
+                        {chips.map((c) => (
+                          <button key={c} className="ga-chip" onClick={() => void ask(c)}>
                             {c}
                           </button>
                         ))}
@@ -174,20 +308,27 @@ export default function GroveAgent({ writable, entryKey, entryTitle }: { writabl
                     )}
                   </>
                 ) : (
-                  msgs.map((m, i) => (
-                    <div key={i} className={`ga-msg ${m.role}`}>
-                      <span className={`ga-msg__av ${m.role === 'assistant' ? 'grove' : 'user'}`}>
-                        {m.role === 'user' ? 'you' : ''}
-                      </span>
-                      <div className="ga-msg__b">
-                        <div className="ga-msg__who">{m.role === 'assistant' ? 'Grove' : 'You'}</div>
-                        <div className="ga-msg__txt">
-                          {m.text}
-                          {streaming && i === msgs.length - 1 && m.role === 'assistant' ? <span className="ga-cursor" /> : null}
+                  rows.map((r, i) =>
+                    r.kind === 'activity' ? (
+                      <div key={i} className="ga-activity">
+                        <Icon name="file" />
+                        {r.text}
+                      </div>
+                    ) : (
+                      <div key={i} className={`ga-msg ${r.kind}`}>
+                        <span className={`ga-msg__av ${r.kind === 'assistant' ? 'grove' : 'user'}`}>
+                          {r.kind === 'assistant' ? '' : 'you'}
+                        </span>
+                        <div className="ga-msg__b">
+                          <div className="ga-msg__who">{r.kind === 'assistant' ? 'Grove' : 'You'}</div>
+                          <div className="ga-msg__txt">
+                            {r.text}
+                            {streaming && i === rows.length - 1 && r.kind === 'assistant' ? <span className="ga-cursor" /> : null}
+                          </div>
                         </div>
                       </div>
-                    </div>
-                  ))
+                    ),
+                  )
                 )}
               </div>
 
@@ -196,30 +337,42 @@ export default function GroveAgent({ writable, entryKey, entryTitle }: { writabl
                   className="ga-foot__row"
                   onSubmit={(e) => {
                     e.preventDefault();
-                    send(draft);
+                    void ask(draft);
                   }}
                 >
                   <input
                     ref={footRef}
                     value={draft}
                     placeholder="Ask Grove…"
-                    disabled={streaming || restingDisabled}
+                    disabled={streaming || !canAsk}
                     onChange={(e) => setDraft(e.target.value)}
                   />
-                  <button className="go" type="submit" disabled={streaming || restingDisabled || !draft.trim()} aria-label="Send">
-                    <Icon name={streaming ? 'stop' : 'send'} />
+                  {streaming ? (
+                    <button
+                      className="stop"
+                      type="button"
+                      aria-label="Stop"
+                      title="Stop"
+                      onClick={() => abortRef.current?.abort()}
+                    >
+                      <Icon name="x" />
+                    </button>
+                  ) : null}
+                  <button className="go" type="submit" disabled={streaming || !canAsk || !draft.trim()} aria-label={streaming ? 'Answering…' : 'Send'} title={streaming ? 'Answering…' : 'Send'}>
+                    <Icon name="send" />
                   </button>
                 </form>
                 <div className="ga-foot__hand">
-                  <span>Grove's own agent · scoped to your grants</span>
-                  <a
-                    onClick={() => openEditor(entryKey)}
-                    role="button"
-                    tabIndex={0}
-                  >
+                  <span>{EGRESS_DISCLOSURE}</span>
+                  {editRefused && (
+                    <span className="ga-edit-refused" role="status">
+                      {EDIT_REFUSED_NOTICE}
+                    </span>
+                  )}
+                  <button type="button" onClick={() => openEditor(entryKey)}>
                     <Icon name="external" />
-                    Open in the workbench
-                  </a>
+                    Open in the editor
+                  </button>
                 </div>
               </div>
             </div>
@@ -229,37 +382,3 @@ export default function GroveAgent({ writable, entryKey, entryTitle }: { writabl
     </div>
   );
 }
-
-// The no-key / forbidden / read-only / error states — calm explanations that hand
-// to the host secret flow rather than faking a key prompt.
-function AgentBanner({ banner }: { banner: Banner }) {
-  const copy: Record<string, { t: string; d: React.ReactNode }> = {
-    'no-key': {
-      t: 'Connect a key to use the agent.',
-      d: 'Grove rides whichever model provider you connect in the host. Add a key to start asking.',
-    },
-    forbidden: {
-      t: 'The agent isn’t available here.',
-      d: "This Grove wasn't granted the chat capability. Reading still works as normal.",
-    },
-    'read-only': {
-      t: 'You’re viewing read-only.',
-      d: 'The agent can explain this wiki, but changes need write access to this space.',
-    },
-    error: {
-      t: 'The agent hit a snag.',
-      d: 'The model or backend errored. Try again in a moment.',
-    },
-  };
-  const c = copy[banner as string];
-  if (!c) return null;
-  return (
-    <div className="ga-banner">
-      <Icon name="alert" />
-      <div>
-        <div className="ga-banner__t">{c.t}</div>
-        <div className="ga-banner__d">{c.d}</div>
-      </div>
-    </div>
-  );
-}