@guuey/agent-client 0.3.1 → 0.5.0

package/src/useAgentInvoke.ts

@@ -2,7 +2,7 @@
  * useAgentInvoke — the base-platform chat client.
  *
  * Speaks the nocode-runtime pod's Bedrock-style SSE contract (NOT the parked
- * ggui generative-UI protocol that `@ggui-ai/react`'s useInvoke targets):
+ * ggui generative-UI protocol that `@ggui-ai/mcp-apps-react`'s useInvoke targets):
  *
  *   POST {endpointUrl}/agent/invoke
  *     body: { input, threadId?, clientMessageId }
@@ -23,14 +23,10 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Reducer, type AgReduceResult } from "@silverprotocol/core";
-import {
-  parseConsentRequest,
-  parseLinkRequest,
-  parseSseEvents,
-  reduceAssistantText,
-  stringField,
-} from "./sse";
-import { ingestMessageFrame } from "./blocks";
+import { invokeTurn, toInvokeUrl } from "./invoke-turn.js";
+import { AgentResponseError } from "./errors.js";
+import { withActivityObserver } from "./transport.js";
+import { CLIENT_ERROR_CODES } from "./error-codes.js";
 import type {
   AgentInvokeAdapters,
   AgentInvokeStatus,
@@ -39,9 +35,10 @@ import type {
   HistoryLoadResult,
   ProfileConsentRequest,
   ProfileLinkRequest,
+  StallRecoveryOptions,
   UseAgentInvokeOptions,
   UseAgentInvokeReturn,
-} from "./types";
+} from "./types.js";
 
 function threadStorageKey(appId: string | undefined): string {
   return `guuey:thread:${appId ?? "default"}`;
@@ -69,6 +66,53 @@ export function applyHistoryResult(
   return { kind: "seed", messages: result.messages };
 }
 
+/** The guuey#192 stall watchdog's resolved tuning (see {@link stallProbeDecision}). */
+export const STALL_RECOVERY_DEFAULTS = { windowMs: 25_000, probeAttempts: 4 } as const;
+
+function resolveStallRecovery(
+  option: false | StallRecoveryOptions | undefined,
+): { windowMs: number; probeAttempts: number } | null {
+  if (option === false) return null;
+  return {
+    windowMs: option?.windowMs ?? STALL_RECOVERY_DEFAULTS.windowMs,
+    probeAttempts: option?.probeAttempts ?? STALL_RECOVERY_DEFAULTS.probeAttempts,
+  };
+}
+
+/**
+ * Pure decision seam for the guuey#192 stall probe: does a freshly-loaded
+ * transcript already contain THIS turn's finished reply?
+ *
+ * `adopt` requires BOTH signals, because each alone lies in a real case:
+ *
+ *  - **user-count**: history must hold at least as many user turns as the
+ *    local transcript (which includes the just-sent optimistic one). Without
+ *    it, a thread whose PREVIOUS turn ended in a completed assistant reply
+ *    would adopt that OLD transcript and silently drop the in-flight turn.
+ *  - **finished tail**: history's last message must be a non-empty assistant
+ *    reply. Without it, a history read that caught the persisted user row
+ *    before the assistant row would adopt a reply-less transcript.
+ *
+ * KNOWN LIMIT (documented, accepted): the runtime persists a turn's rows at
+ * completion — the guuey#192 evidence (a reload mid-stall renders the FULL
+ * reply) is only possible under that model, and the read plane carries no
+ * per-row clientMessageId to match against. If persistence ever becomes
+ * progressive (partial assistant rows), this heuristic needs the read plane
+ * to grow a turn-completion marker — do not "fix" it client-side by text
+ * comparison, which cannot distinguish a partial row from a finished one.
+ */
+export function stallProbeDecision(
+  history: AgentMessage[],
+  localUserCount: number,
+): "adopt" | "in-flight" {
+  let historyUserCount = 0;
+  for (const m of history) if (m.role === "user") historyUserCount += 1;
+  if (historyUserCount < localUserCount) return "in-flight";
+  const last = history[history.length - 1];
+  if (!last || last.role !== "assistant" || last.text.trim() === "") return "in-flight";
+  return "adopt";
+}
+
 export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeReturn {
   const { endpointUrl, appId } = opts;
   const [messages, setMessages] = useState<AgentMessage[]>([]);
@@ -78,6 +122,10 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   const [status, setStatus] = useState<AgentInvokeStatus>("ready");
   const [activeTool, setActiveTool] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
+  // The pod's wire code for whatever put `error` there, when the failure
+  // carried one (see the return-type contract). Moves in lockstep with
+  // `error` — every set/clear of one touches the other.
+  const [errorCode, setErrorCode] = useState<string | null>(null);
   const [threadId, setThreadId] = useState<string | null>(null);
   // Opt-in block-preserving transcript. `reduceResult` follows the
   // null-until-first-valid-AgEvent contract documented on the return type: it
@@ -97,6 +145,13 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   // explicit dismiss, same lifecycle as `profileConsentRequest` — the two are
   // independent (an unlinked-invite vs an already-linked consent ask).
   const [profileLinkRequest, setProfileLinkRequest] = useState<ProfileLinkRequest | null>(null);
+  // The last turn's ending posture + the optimistic-send ledger — the
+  // transcript renderer's inputs (guuey#135 wave 3b; see the return-type
+  // contract for each). `aborted` is USER abort only — the #192 watchdog's
+  // internal stream abort never sets it.
+  const [aborted, setAborted] = useState(false);
+  const [adopted, setAdopted] = useState(false);
+  const [sendStates, setSendStates] = useState<Readonly<Record<string, "sending" | "failed">>>({});
 
   const abortRef = useRef<AbortController | null>(null);
   // Mirror the latest threadId + adapters into refs so `send` reads fresh
@@ -105,6 +160,13 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   const threadIdRef = useRef<string | null>(null);
   const adaptersRef = useRef<AgentInvokeAdapters>(opts.adapters);
   adaptersRef.current = opts.adapters;
+  // The stall probe (guuey#192) needs the committed transcript's user-turn
+  // count long after `send`'s closures captured state — same render-time
+  // mirror idiom as `adaptersRef`.
+  const messagesRef = useRef<AgentMessage[]>(messages);
+  messagesRef.current = messages;
+  const stallRecoveryRef = useRef(opts.stallRecovery);
+  stallRecoveryRef.current = opts.stallRecovery;
   // The per-conversation AgJSON fold (only built when `preserveBlocks`).
   // Lazily (re)created on the first valid AgEvent after a fresh start / reset,
   // so an off run never constructs one and a bypass run never allocates.
@@ -131,6 +193,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     setThreadId(null);
     setMessages([]);
     setError(null);
+    setErrorCode(null);
     setStatus("ready");
     setActiveTool(null);
     // Fresh conversation → drop the old fold; the reducer is rebuilt lazily on
@@ -141,6 +204,9 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     // A prior app's consent ask must never leak into the new conversation.
     setProfileConsentRequest(null);
     setProfileLinkRequest(null);
+    setAborted(false);
+    setAdopted(false);
+    setSendStates({});
 
     let cancelled = false;
     const key = threadStorageKey(appId);
@@ -221,6 +287,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     void adaptersRef.current.storage.save(threadStorageKey(appId), "");
     setMessages([]);
     setError(null);
+    setErrorCode(null);
     setStatus("ready");
     setActiveTool(null);
     // Re-create the reducer for the new conversation (rebuilt lazily on the
@@ -230,6 +297,9 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     setHistoryCards([]);
     setProfileConsentRequest(null);
     setProfileLinkRequest(null);
+    setAborted(false);
+    setAdopted(false);
+    setSendStates({});
   }, [appId]);
 
   const clearProfileConsentRequest = useCallback(() => {
@@ -242,13 +312,47 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
 
   const send = useCallback(
     async (input: string) => {
-      if (!endpointUrl || !input.trim() || status !== "ready") return;
+      // An already-aborted external signal refuses the send outright —
+      // before the optimistic transcript push, so nothing is left to undo.
+      if (!endpointUrl || !input.trim() || status !== "ready" || opts.signal?.aborted) return;
       setError(null);
+      setErrorCode(null);
+      setAborted(false);
+      setAdopted(false);
       setStatus("connecting");
-      setMessages((prev) => [...prev, { role: "user", text: input }, { role: "assistant", text: "" }]);
+      // ONE id for the whole turn: the optimistic user entry, the send-state
+      // ledger, and the invoke body all carry it — the R0 lifecycle join.
+      const clientMessageId = adaptersRef.current.generateId();
+      /** Move this turn's ledger entry; `null` removes it (absent = sent). */
+      const markSend = (state: "sending" | "failed" | null): void => {
+        setSendStates((prev) => {
+          if (state === null) {
+            if (!(clientMessageId in prev)) return prev;
+            const next: Record<string, "sending" | "failed"> = { ...prev };
+            delete next[clientMessageId];
+            return next;
+          }
+          if (prev[clientMessageId] === state) return prev;
+          return { ...prev, [clientMessageId]: state };
+        });
+      };
+      markSend("sending");
+      let admitted = false;
+      setMessages((prev) => [
+        ...prev,
+        { role: "user", text: input, clientMessageId },
+        { role: "assistant", text: "" },
+      ]);
 
       const controller = new AbortController();
       abortRef.current = controller;
+      // Compose the host's external abort authority (opts.signal) with the
+      // per-turn controller: an external abort stops this turn exactly as
+      // `abort()` would. Listener removed in `finally` — the signal outlives
+      // the turn, the subscription must not.
+      const externalSignal = opts.signal;
+      const onExternalAbort = (): void => controller.abort();
+      externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
       const adapters = adaptersRef.current;
       // Wait for the persisted threadId to load before deciding whether to
       // replay it — otherwise a fast first send mints a new orphan thread and
@@ -272,93 +376,180 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
         });
       };
 
+      // ── guuey#192 stall watchdog ─────────────────────────────────────
+      // A half-dead connection (TCP alive, zero bytes, no error, no `done`)
+      // never resolves the read below, so a parallel clock watches byte
+      // activity: armed by the FIRST chunk (so a silent cold start never
+      // trips it), reset by every chunk, and on expiry it probes history
+      // WITHOUT touching the stream — killing a live-but-quiet stream on a
+      // timer would trade a frozen cursor for a lost turn. Only two things
+      // end the turn early: adoption (history already holds the finished
+      // reply — the reload the user would have done, minus the reload) and
+      // the bounded give-up (STREAM_STALLED after `probeAttempts` fruitless
+      // probes with still-zero bytes).
+      const stall = resolveStallRecovery(stallRecoveryRef.current);
+      let turnEnded = false;
+      let probeInFlight = false;
+      let fruitlessProbes = 0;
+      let activityCount = 0;
+      let stallTimer: ReturnType<typeof setTimeout> | null = null;
+      const clearStallTimer = (): void => {
+        if (stallTimer !== null) {
+          clearTimeout(stallTimer);
+          stallTimer = null;
+        }
+      };
+      const armStallTimer = (): void => {
+        if (!stall || turnEnded || controller.signal.aborted) return;
+        clearStallTimer();
+        stallTimer = setTimeout(() => {
+          void onStallWindow();
+        }, stall.windowMs);
+      };
+      const endTurnWith = (apply: () => void): void => {
+        turnEnded = true;
+        clearStallTimer();
+        apply();
+        // Unwinds the suspended read; the catch sees `aborted` and stays
+        // silent, so whatever `apply` decided IS the turn's outcome.
+        controller.abort();
+      };
+      const onStallWindow = async (): Promise<void> => {
+        if (!stall || turnEnded || controller.signal.aborted || probeInFlight) return;
+        const tid = threadIdRef.current;
+        const history = adaptersRef.current.history;
+        if (tid && history) {
+          probeInFlight = true;
+          const countAtProbe = activityCount;
+          let result: HistoryLoadResult | null = null;
+          try {
+            result = await history.load(tid);
+          } catch {
+            result = null; // transient read failure = one fruitless probe
+          }
+          probeInFlight = false;
+          if (turnEnded || controller.signal.aborted) return;
+          // Bytes resumed while the probe was in flight: the stream is alive
+          // — discard the now-stale read; the chunk observer already reset
+          // the count and re-armed the clock.
+          if (activityCount !== countAtProbe) return;
+          if (result && !("gone" in result)) {
+            let localUserCount = 0;
+            for (const m of messagesRef.current) if (m.role === "user") localUserCount += 1;
+            if (stallProbeDecision(result.messages, localUserCount) === "adopt") {
+              const adoptedResult = result;
+              endTurnWith(() => {
+                setMessages(adoptedResult.messages);
+                if ("cards" in adoptedResult && adoptedResult.cards && adoptedResult.cards.length > 0) {
+                  setHistoryCards(adoptedResult.cards);
+                }
+                // The renderer's #192 signal: calm renders the adopted turn
+                // identically; debug may mark it (guuey#135 3b).
+                setAdopted(true);
+              });
+              return;
+            }
+          }
+        }
+        // No probe possible (no threadId yet / no history adapter), a failed
+        // read, or history says the turn is still in flight — all count the
+        // same: one fruitless window.
+        fruitlessProbes += 1;
+        if (fruitlessProbes >= stall.probeAttempts) {
+          endTurnWith(() => {
+            setError("The response stream stalled and the finished reply was not found in history.");
+            setErrorCode(CLIENT_ERROR_CODES.STREAM_STALLED);
+          });
+          return;
+        }
+        armStallTimer();
+      };
+      const transport = stall
+        ? withActivityObserver(adapters.transport, () => {
+            activityCount += 1;
+            fruitlessProbes = 0;
+            armStallTimer();
+          })
+        : adapters.transport;
+
       try {
-        // The endpointUrl may be a pod base (`https://host`) or the full
-        // invoke URL the deploy-controller records (`https://host/agent/invoke`).
-        // Normalize to exactly one `/agent/invoke`.
-        const base = endpointUrl.replace(/\/+$/, "");
-        const invokeUrl = base.endsWith("/agent/invoke") ? base : `${base}/agent/invoke`;
+        const invokeUrl = toInvokeUrl(endpointUrl);
         const body = {
           input,
           ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
-          clientMessageId: adapters.generateId(),
+          clientMessageId,
         };
 
-        let buffer = "";
-        for await (const chunk of adapters.transport({ url: invokeUrl, body, signal: controller.signal })) {
-          buffer += chunk;
-          const { events, rest } = parseSseEvents(buffer);
-          buffer = rest;
-          for (const ev of events) {
-            if (ev.event === "session") {
-              // The pod is awake and the turn is admitted — 'connecting' ends
-              // here (this frame arrives within ~1s of a warm pod; a cold
-              // scale-to-zero start is exactly the long 'connecting' phase).
-              setStatus("thinking");
-              const tid = stringField(ev.data, "threadId");
-              if (tid) {
-                threadIdRef.current = tid;
-                setThreadId(tid);
-                void adapters.storage.save(threadStorageKey(appId), tid);
-              }
-            } else if (ev.event === "message") {
-              // Status derivation (guuey#91) — read the frame's `type` before
-              // the text fold. Silver frames announce tools + text explicitly;
-              // bypass frames ('text' / 'assistant' SDKMessages) only ever
-              // carry assistant text, so they map to 'responding'. Unknown
-              // types deliberately leave the status untouched.
-              const frameType = stringField(ev.data, "type");
-              if (frameType === "tool.start") {
-                setStatus("using-tool");
-                setActiveTool(stringField(ev.data, "name") ?? null);
-              } else if (frameType === "tool.done") {
-                setStatus("thinking");
-                setActiveTool(null);
-              } else if (
-                frameType === "text.start" ||
-                frameType === "text.delta" ||
-                frameType === "text" ||
-                frameType === "assistant"
-              ) {
-                setStatus("responding");
-              }
-              renderAssistant(reduceAssistantText(assistantText, ev.data));
-              // Additively fold the SAME frame into the AgJSON reducer when
-              // opted in. The text surface above is untouched; only VALID
-              // AgEvents advance the reducer (bypass frames ingest to [] and
-              // leave `reduceResult` null — see the return-type contract).
-              if (preserveBlocksRef.current) {
-                const agEvents = ingestMessageFrame(ev.data);
-                if (agEvents.length > 0) {
-                  if (!reducerRef.current) reducerRef.current = new Reducer();
-                  for (const agEvent of agEvents) reducerRef.current.push(agEvent);
-                  setReduceResult(reducerRef.current.result());
-                }
-              }
-            } else if (ev.event === "error") {
-              setError(stringField(ev.data, "message") ?? "agent error");
-            } else if (ev.event === "profile-consent-needed") {
-              // Cross-app profile consent ask (T6). Only a well-formed payload
-              // updates state; a malformed one is dropped, leaving any prior
-              // valid request untouched (never clobbered to null).
-              const parsed = parseConsentRequest(ev.data);
-              if (parsed) setProfileConsentRequest(parsed);
-            } else if (ev.event === "profile-link-needed") {
-              // Cross-app profile LINK invite (linkcoh T3) for an unlinked byo
-              // caller. Same drop-if-malformed contract as consent above.
-              const parsed = parseLinkRequest(ev.data);
-              if (parsed) setProfileLinkRequest(parsed);
+        // The wire walk lives in `invokeTurn` (the pure per-turn generator —
+        // its docblock owns the switch semantics); this hook only maps each
+        // semantic event onto React state.
+        for await (const ev of invokeTurn(
+          { url: invokeUrl, body, signal: controller.signal },
+          transport,
+        )) {
+          if (ev.kind === "session") {
+            // The pod is awake and the turn is admitted — 'connecting' ends
+            // here, and so does the R0 "sending" state (absent = sent).
+            admitted = true;
+            markSend(null);
+            setStatus("thinking");
+            if (ev.threadId) {
+              threadIdRef.current = ev.threadId;
+              setThreadId(ev.threadId);
+              void adapters.storage.save(threadStorageKey(appId), ev.threadId);
+            }
+          } else if (ev.kind === "message") {
+            // Absent status/activeTool mean "no change" — never touched, so
+            // an unknown frame type leaves both standing (guuey#91 rule).
+            if (ev.status !== undefined) setStatus(ev.status);
+            if (ev.activeTool !== undefined) setActiveTool(ev.activeTool);
+            renderAssistant(ev.assistantText);
+            // Additively fold the frame's AgEvents into the AgJSON reducer
+            // when opted in. The text surface above is untouched; only VALID
+            // AgEvents advance the reducer (bypass frames carry [] and leave
+            // `reduceResult` null — see the return-type contract).
+            if (preserveBlocksRef.current && ev.agEvents.length > 0) {
+              if (!reducerRef.current) reducerRef.current = new Reducer();
+              for (const agEvent of ev.agEvents) reducerRef.current.push(agEvent);
+              setReduceResult(reducerRef.current.result());
             }
-            // `done` needs no handling — the stream closes after it. Any other
-            // (unknown) event falls through silently — there is no default
-            // branch, so a consumer that never renders a field is unaffected.
+          } else if (ev.kind === "error") {
+            // In-band failure frame — the code moves in lockstep with the
+            // message (an event without one carries null rather than leaving
+            // a previous turn's code standing).
+            setError(ev.message);
+            setErrorCode(ev.code);
+          } else if (ev.kind === "profile-consent") {
+            setProfileConsentRequest(ev.request);
+          } else if (ev.kind === "profile-link") {
+            setProfileLinkRequest(ev.request);
           }
+          // `done` needs no handling here — the stream closes after it.
         }
       } catch (e) {
         if (!controller.signal.aborted) {
           setError(e instanceof Error ? e.message : "failed to reach agent");
+          // Pre-stream refusals arrive as a thrown AgentResponseError carrying
+          // the pod's structured code (a transport-level saturation retry has
+          // already happened and failed by the time one surfaces here). Any
+          // other throw — a network drop, a host-adapter failure — has no wire
+          // code, so the field stays null beside the message.
+          setErrorCode(e instanceof AgentResponseError ? (e.code ?? null) : null);
+          // A failure BEFORE admission means the message never reached the
+          // agent — the R0 failed-to-send state. Post-admission failures
+          // leave the entry removed (the send itself succeeded).
+          if (!admitted) markSend("failed");
         }
       } finally {
+        // The turn is over however it ended — no probe may fire after this,
+        // and the pending timer must not leak past the turn. `turnEnded`
+        // already true here ⟺ the #192 watchdog ended the turn (adoption or
+        // stall give-up) — its internal `controller.abort()` must not read
+        // as a USER abort below.
+        const endedByWatchdog = turnEnded;
+        turnEnded = true;
+        clearStallTimer();
+        externalSignal?.removeEventListener("abort", onExternalAbort);
         setStatus("ready");
         setActiveTool(null);
         abortRef.current = null;
@@ -373,9 +564,16 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
               : prev;
           });
         }
+        if (controller.signal.aborted && !endedByWatchdog) {
+          // USER abort (abort() or the external signal): surface it, and a
+          // pre-admission cancel clears the "sending" entry — a turn the
+          // user stopped is not a failed send.
+          setAborted(true);
+          if (!admitted) markSend(null);
+        }
       }
     },
-    [endpointUrl, appId, status],
+    [endpointUrl, appId, status, opts.signal],
   );
 
   return {
@@ -384,6 +582,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     status,
     activeTool,
     error,
+    errorCode,
     threadId,
     abort,
     reset,
@@ -393,5 +592,8 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     clearProfileConsentRequest,
     profileLinkRequest,
     clearProfileLinkRequest,
+    aborted,
+    adopted,
+    sendStates,
   };
 }