@guuey/chat 0.5.0 → 0.6.0

package/src/react/guuey-chat.tsx

@@ -31,20 +31,70 @@
  * adapter (e.g. `createWebAdapters({ apiBaseUrl, … })`) and a persisted
  * threadId rehydrates on mount — text transcript + persisted cards, which
  * mount through the same R6 path as live views. Nothing here to configure.
+ *
+ * ## The imperative seam (guuey#210)
+ *
+ * Suggested-prompt chips and other host-driven sends stay on the
+ * batteries-included path via {@link GuueyChatHandle} — a ref handle
+ * (`forwardRef`) and/or the `onReady` callback, ONE stable object for the
+ * component's whole life. `send` runs through exactly the Send button's
+ * gate (never bypasses it; the typed draft is left untouched — a chip send
+ * must not eat a half-typed message); `prefill` mirrors the widget's
+ * staged-composer semantics (append joins with a space, never clobbers).
+ * Web-only for now: the native tier ships `<NativeTranscript>` without a
+ * native GuueyChat, so there is no native surface to put a handle on yet.
  */
-import { useCallback, useMemo, useState, type CSSProperties, type ReactNode } from "react";
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
 import { createWebAdapters, type AgentInvokeAdapters } from "@guuey/agent-client";
+import type { AgHitlAnswer, AgPausedAsk } from "@silverprotocol/core";
 import { useAgentInvoke } from "@guuey/agent-client/react";
 import type { UiResourceReader } from "@guuey/mcp-apps-host";
 import { calmPolicy, debugPolicy, type TranscriptPolicy } from "../policy.js";
 import { defaultChatStrings, type ChatStrings } from "../strings.js";
 import { DEFAULT_CHAT_THEME, type GuueyChatTheme } from "../theme.js";
-import type { ErrorItem, PromptItem, UserMessageItem } from "../types.js";
+import type { ChatDebugEvent, ErrorItem, PromptItem, UserMessageItem } from "../types.js";
 import type { ThemeMode } from "./theme-css.js";
 import { Transcript, type TranscriptWindowing } from "./transcript.js";
 import type { TranscriptComponents, TranscriptItemContext } from "./components.js";
 import { useTranscript, useTranscriptInputs } from "./use-transcript.js";
 
+/**
+ * The imperative seam (guuey#210): programmatic send/prefill/focus for
+ * hosts that stay on the batteries-included path (suggested-prompt chips
+ * being the filing use case). Reach it via `ref` or `onReady` — both
+ * deliver the SAME stable object, valid for the component's whole life.
+ */
+export interface GuueyChatHandle {
+  /**
+   * Send `text` through exactly the Send button's gate: returns `false`
+   * and does nothing when chat is unavailable (`endpointUrl === null`), a
+   * turn is in flight, or the text is blank — it NEVER bypasses the
+   * composer's rules. The typed draft is left untouched (a programmatic
+   * send must not eat a half-typed message). Failures surface the same
+   * way a composer send's do (the hook's `error` / R0 failed-send).
+   */
+  send(text: string): boolean;
+  /**
+   * Put `text` into the composer draft. `append: true` joins onto a
+   * non-empty draft with a single space (the widget's staged-composer
+   * semantic — never clobbers); default replaces. Focuses the input
+   * unless `focus: false`.
+   */
+  prefill(text: string, opts?: { focus?: boolean; append?: boolean }): void;
+  /** Focus the composer input. */
+  focusComposer(): void;
+}
+
 export interface GuueyChatProps {
   /** Pod base URL (with or without `/agent/invoke`). `null` disables chat. */
   endpointUrl: string | null;
@@ -70,6 +120,8 @@ export interface GuueyChatProps {
   window?: TranscriptWindowing | false;
   /** R6 locator resolution (history cards). See `useTranscript`. */
   reader?: UiResourceReader;
+  /** The debug sink (spec §5) — fires only under the debug policy. */
+  onDebugEvent?: (event: ChatDebugEvent) => void;
   /** R6 pass-through (relay hook, sandbox page/flags, host context…). */
   viewProps?: TranscriptItemContext["viewProps"];
   /**
@@ -77,9 +129,24 @@ export interface GuueyChatProps {
    * The transcript record moves regardless; without a handler the prompt
    * card is record-only.
    */
-  onPromptAction?: (item: PromptItem, action: "accept" | "decline" | "dismiss") => void;
+  onPromptAction?: (
+    item: PromptItem,
+    action: "accept" | "decline" | "dismiss" | { grantModeId: string },
+  ) => void;
+  /**
+   * Receives the VALIDATED wire answer for an AgJSON HITL ask (spec
+   * draft.2) — the host owns delivering it (the kit has no answer
+   * transport). Fired after the transcript record moves.
+   */
+  onHitlAnswer?: (answer: AgHitlAnswer, ask: AgPausedAsk) => void;
   /** R11 action slot (sign-in / retry affordances). */
   onErrorAction?: (item: ErrorItem) => void;
+  /**
+   * Callback route to the {@link GuueyChatHandle} for hosts that prefer
+   * wiring over refs. Fires ONCE per component instance, on mount, with
+   * the same stable handle the ref receives.
+   */
+  onReady?: (handle: GuueyChatHandle) => void;
   className?: string;
   style?: CSSProperties;
 }
@@ -90,7 +157,10 @@ const PROMPT_STATE = {
   dismiss: "dismissed",
 } as const;
 
-export function GuueyChat(props: GuueyChatProps): ReactNode {
+export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function GuueyChat(
+  props: GuueyChatProps,
+  ref,
+): ReactNode {
   const {
     endpointUrl,
     appId,
@@ -103,9 +173,12 @@ export function GuueyChat(props: GuueyChatProps): ReactNode {
     mode = "light",
     window: windowing,
     reader,
+    onDebugEvent,
     viewProps,
     onPromptAction,
+    onHitlAnswer,
     onErrorAction,
+    onReady,
     className,
     style,
   } = props;
@@ -123,19 +196,68 @@ export function GuueyChat(props: GuueyChatProps): ReactNode {
     return factory({ ...policyOverrides, strings });
   }, [preset, policyOverrides, stringOverrides]);
 
-  const { inputs, resolvePrompt } = useTranscriptInputs(invoke);
+  const { inputs, resolvePrompt, answerHitlPrompt } = useTranscriptInputs(invoke);
   const { plan, toggle, resolvedMounts, onViewPhase } = useTranscript({
     inputs,
     policy,
     ...(reader !== undefined ? { reader } : {}),
+    ...(onDebugEvent !== undefined ? { onDebugEvent } : {}),
   });
 
   // ── Composer ─────────────────────────────────────────────────────────
   const [input, setInput] = useState("");
+  const inputRef = useRef<HTMLTextAreaElement | null>(null);
   const busy = invoke.status !== "ready";
   const available = endpointUrl !== null;
   const canSend = available && !busy && input.trim() !== "";
 
+  // ── The imperative seam (guuey#210) ──────────────────────────────────
+  // ONE stable handle for the component's whole life (hosts capture it in
+  // `onReady` and keep it), reading live truth through a ref so a call
+  // always sees the CURRENT gate — never a stale closure's.
+  const liveRef = useRef({ available, busy, invoke, onReady });
+  useEffect(() => {
+    liveRef.current = { available, busy, invoke, onReady };
+  });
+
+  const handle = useMemo<GuueyChatHandle>(
+    () => ({
+      send: (text: string): boolean => {
+        const live = liveRef.current;
+        const trimmed = text.trim();
+        // Exactly the Send button's gate — a handle send never bypasses it.
+        if (!live.available || live.busy || trimmed === "") return false;
+        void live.invoke.send(trimmed).catch(() => {
+          // Same contract as submit: the hook owns failure surfacing.
+        });
+        return true;
+      },
+      prefill: (text: string, opts?: { focus?: boolean; append?: boolean }): void => {
+        setInput((prev) =>
+          // The widget's staged-composer semantic: append joins with a
+          // space onto a non-empty draft, never clobbers it.
+          opts?.append === true && prev.trim() !== "" ? `${prev.trimEnd()} ${text}` : text,
+        );
+        if (opts?.focus !== false) inputRef.current?.focus();
+      },
+      focusComposer: (): void => {
+        inputRef.current?.focus();
+      },
+    }),
+    [],
+  );
+
+  useImperativeHandle(ref, () => handle, [handle]);
+
+  // `onReady` fires once per instance, on mount, with the stable handle
+  // (guarded ref: StrictMode's remount cycle must not double-fire it).
+  const readyFiredRef = useRef(false);
+  useEffect(() => {
+    if (readyFiredRef.current) return;
+    readyFiredRef.current = true;
+    liveRef.current.onReady?.(handle);
+  }, [handle]);
+
   const submit = useCallback((): void => {
     const text = input.trim();
     if (text === "" || !available || busy) return;
@@ -155,11 +277,22 @@ export function GuueyChat(props: GuueyChatProps): ReactNode {
   );
 
   const handlePromptAction = useCallback(
-    (item: PromptItem, action: "accept" | "decline" | "dismiss") => {
-      resolvePrompt(item.promptId, PROMPT_STATE[action]);
+    (item: PromptItem, action: "accept" | "decline" | "dismiss" | { grantModeId: string }) => {
+      if (item.promptKind === "hitl") {
+        const answer = answerHitlPrompt(
+          item.ask,
+          typeof action === "object" ? action : action === "accept" ? "accept" : action,
+        );
+        onHitlAnswer?.(answer, item.ask);
+        onPromptAction?.(item, action);
+        return;
+      }
+      // Profile prompts only ever receive the string actions (the default
+      // card renders no mode buttons for them).
+      if (typeof action !== "object") resolvePrompt(item.promptId, PROMPT_STATE[action]);
       onPromptAction?.(item, action);
     },
-    [resolvePrompt, onPromptAction],
+    [resolvePrompt, answerHitlPrompt, onHitlAnswer, onPromptAction],
   );
 
   const strings = policy.strings;
@@ -192,6 +325,7 @@ export function GuueyChat(props: GuueyChatProps): ReactNode {
         }}
       >
         <textarea
+          ref={inputRef}
           className="guuey-chat-composer-input"
           rows={1}
           value={input}
@@ -224,4 +358,4 @@ export function GuueyChat(props: GuueyChatProps): ReactNode {
       </form>
     </div>
   );
-}
+});

package/src/react/transcript.tsx

@@ -46,7 +46,7 @@ export interface TranscriptWindowing {
 export interface TranscriptProps
   extends Pick<
     TranscriptItemContext,
-    "onToggle" | "onRetry" | "onPromptAction" | "onErrorAction" | "resolvedMounts" | "onViewPhase" | "viewProps"
+    "onToggle" | "onRetry" | "onPromptAction" | "onErrorAction" | "resolvedMounts" | "onViewPhase" | "onViewRef" | "viewProps"
   > {
   plan: TranscriptPlan;
   /** Per-slot component overrides (spec §3's override column). */
@@ -77,6 +77,7 @@ export function Transcript(props: TranscriptProps): ReactNode {
     onErrorAction,
     resolvedMounts,
     onViewPhase,
+    onViewRef,
     viewProps,
   } = props;
 
@@ -85,8 +86,8 @@ export function Transcript(props: TranscriptProps): ReactNode {
     [components],
   );
   const ctx: TranscriptItemContext = useMemo(
-    () => ({ strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps }),
-    [strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps],
+    () => ({ strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef, viewProps }),
+    [strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef, viewProps],
   );
 
   // ── Windowing ────────────────────────────────────────────────────────

package/src/react/use-transcript.ts

@@ -13,17 +13,20 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { UseAgentInvokeReturn } from "@guuey/agent-client";
+import type { AgHitlAnswer, AgPausedAsk } from "@silverprotocol/core";
 import {
   resolveViewMount,
   type ResolvedViewMount,
   type UiResourceReader,
   type ViewHostPhase,
 } from "@guuey/mcp-apps-host";
+import { buildHitlAnswer, hitlPromptsFromFold, type HitlAnswerRecord, type HitlPromptAction } from "../hitl.js";
 import { planTranscript } from "../plan.js";
 import type { TranscriptPolicy } from "../policy.js";
 import type {
+  ChatDebugEvent,
   ItemKey,
-  PromptItemInput,
+  ProfilePromptInput,
   TranscriptInputs,
   TranscriptMessage,
   TranscriptOverrides,
@@ -42,6 +45,13 @@ export interface UseTranscriptArgs {
    * resolution — labeled, never blank.
    */
   reader?: UiResourceReader;
+  /**
+   * The debug sink (spec §5, real API since the #135 refinement wave):
+   * receives {@link ChatDebugEvent}s — view-phase transitions, R15
+   * unknown-block sightings, the #192 recovered-turn marker. Fires ONLY
+   * under the debug policy (`debugDetail`); `calm` ignores it by design.
+   */
+  onDebugEvent?: (event: ChatDebugEvent) => void;
 }
 
 export interface UseTranscriptResult {
@@ -56,13 +66,22 @@ export interface UseTranscriptResult {
   resolvedMounts: ReadonlyMap<ItemKey, ResolvedViewMount | "expired">;
 }
 
-export function useTranscript({ inputs, policy, reader }: UseTranscriptArgs): UseTranscriptResult {
+export function useTranscript({
+  inputs,
+  policy,
+  reader,
+  onDebugEvent,
+}: UseTranscriptArgs): UseTranscriptResult {
   const [overrides, setOverrides] = useState<TranscriptOverrides>({});
   const [phases, setPhases] = useState<Readonly<Record<string, ViewHostPhase>>>({});
   const [resolvedMounts, setResolvedMounts] = useState<
     ReadonlyMap<ItemKey, ResolvedViewMount | "expired">
   >(new Map());
 
+  // The debug sink (gated on the debug policy — calm ignores it, spec §5).
+  const debugSink = useRef<((event: ChatDebugEvent) => void) | null>(null);
+  debugSink.current = policy.debugDetail && onDebugEvent !== undefined ? onDebugEvent : null;
+
   const merged = useMemo<TranscriptInputs>(
     () => ({ ...inputs, viewPhases: { ...inputs.viewPhases, ...phases } }),
     [inputs, phases],
@@ -92,10 +111,37 @@ export function useTranscript({ inputs, policy, reader }: UseTranscriptArgs): Us
     setOverrides((prev) => ({ ...prev, [key]: { expanded: !current } }));
   }, []);
 
+  // Mirror of `phases` for the change check OUTSIDE the state updater — a
+  // sink call inside an updater would double-fire under StrictMode.
+  const phasesRef = useRef<Readonly<Record<string, ViewHostPhase>>>({});
   const onViewPhase = useCallback((key: ItemKey, phase: ViewHostPhase) => {
+    if (phasesRef.current[key] !== phase) {
+      phasesRef.current = { ...phasesRef.current, [key]: phase };
+      debugSink.current?.({ type: "view-phase", key, phase });
+    }
     setPhases((prev) => (prev[key] === phase ? prev : { ...prev, [key]: phase }));
   }, []);
 
+  // Plan-derived debug events, emitted once per sighting (post-render — the
+  // plan itself stays pure data).
+  const emittedUnknowns = useRef(new Set<ItemKey>());
+  const recoveryEmitted = useRef(false);
+  useEffect(() => {
+    const sink = debugSink.current;
+    if (sink === null) return;
+    for (const item of plan.items) {
+      if (item.kind !== "unknown" || emittedUnknowns.current.has(item.key)) continue;
+      emittedUnknowns.current.add(item.key);
+      sink({ type: "unknown-block", key: item.key, typeName: item.typeName, byteSize: item.byteSize });
+    }
+    if (plan.recovery !== null && !recoveryEmitted.current) {
+      recoveryEmitted.current = true;
+      sink({ type: "turn-recovered", marker: plan.recovery });
+    } else if (plan.recovery === null) {
+      recoveryEmitted.current = false;
+    }
+  }, [plan]);
+
   // Locator resolution — one read per locator key, misses become "expired".
   const readerRef = useRef(reader);
   readerRef.current = reader;
@@ -110,6 +156,10 @@ export function useTranscript({ inputs, policy, reader }: UseTranscriptArgs): Us
       inFlight.current.add(item.key);
       const settle = (value: ResolvedViewMount | "expired"): void => {
         inFlight.current.delete(item.key);
+        // The R13 expired verdict is a phase transition too (debug sink).
+        if (value === "expired") {
+          debugSink.current?.({ type: "view-phase", key: item.key, phase: "expired" });
+        }
         setResolvedMounts((prev) => {
           const next = new Map(prev);
           next.set(item.key, value);
@@ -141,6 +191,16 @@ export interface UseTranscriptInputsResult {
    * without a recorded action reads as `dismissed`.
    */
   resolvePrompt: (id: string, state: "answered" | "declined" | "dismissed") => void;
+  /**
+   * Answer an AgJSON HITL ask (spec draft.2): constructs the wire answer,
+   * VALIDATES it against the ask's persisted record (`validateHitlAnswer`
+   * — required-iff-declared, echo-must-be-declared, requestState byte-echo)
+   * BEFORE anything dispatches, records it in the ledger, and returns it
+   * for the HOST to deliver — the kit renders and validates; the answer
+   * transport is the host's (no client→pod hitl-answer channel exists on
+   * the guuey wire today; see the #16 producer flag).
+   */
+  answerHitlPrompt: (ask: AgPausedAsk, action: HitlPromptAction) => AgHitlAnswer;
 }
 
 /** How often the escalation clock ticks while a status needs one. */
@@ -161,7 +221,7 @@ export function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscript
 
   // R10 ledger: the hook exposes only the LATEST pending ask; the
   // transcript keeps the record of every ask and its resolution.
-  const [prompts, setPrompts] = useState<PromptItemInput[]>([]);
+  const [prompts, setPrompts] = useState<ProfilePromptInput[]>([]);
   const promptSeq = useRef(0);
   useEffect(() => {
     const request = invoke.profileConsentRequest;
@@ -228,6 +288,23 @@ export function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscript
     [invoke, prompts],
   );
 
+  // HITL ledger (spec draft.2): asks come from the FOLD's persisted
+  // records; this ledger holds only the host-side answers, keyed by askId.
+  // A `cancelled` record keeps the card re-askable (guuey's #16 ruling) —
+  // a later action on the same ask simply overwrites it.
+  const [hitlAnswers, setHitlAnswers] = useState<Readonly<Record<string, HitlAnswerRecord>>>({});
+  const answerHitlPrompt = useCallback((ask: AgPausedAsk, action: HitlPromptAction): AgHitlAnswer => {
+    const answer = buildHitlAnswer(ask, action);
+    setHitlAnswers((prev) => ({
+      ...prev,
+      [ask.askId]: {
+        status: answer.status,
+        ...(answer.grantModeId !== undefined ? { grantModeId: answer.grantModeId } : {}),
+      },
+    }));
+    return answer;
+  }, []);
+
   const inputs = useMemo<TranscriptInputs>(() => {
     // Source-ownership split (plan.ts's rules): the trailing assistant
     // entry is the IN-FLIGHT fold (or the abort-kept partial) — it moves to
@@ -248,7 +325,7 @@ export function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscript
       statusElapsedMs: elapsedMs,
       activeTool: invoke.activeTool,
       error: invoke.error !== null ? { message: invoke.error, code: invoke.errorCode } : null,
-      prompts,
+      prompts: [...prompts, ...hitlPromptsFromFold(invoke.reduceResult, hitlAnswers)],
       messages,
       ...(invoke.historyCards.length > 0 ? { historyCards: invoke.historyCards } : {}),
       sendStates: invoke.sendStates,
@@ -268,7 +345,8 @@ export function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscript
     invoke.adopted,
     elapsedMs,
     prompts,
+    hitlAnswers,
   ]);
 
-  return { inputs, resolvePrompt };
+  return { inputs, resolvePrompt, answerHitlPrompt };
 }

package/src/react.tsx

@@ -27,6 +27,7 @@ export {
   DefaultToolGroup,
   DefaultDataResult,
   DefaultView,
+  DefaultViewRef,
   DefaultMedia,
   DefaultCode,
   DefaultCitations,
@@ -38,6 +39,7 @@ export {
   DefaultStatus,
   type TranscriptComponents,
   type TranscriptItemContext,
+  type ViewSlotProps,
 } from "./react/components.js";
 export {
   useTranscript,
@@ -46,6 +48,6 @@ export {
   type UseTranscriptResult,
   type UseTranscriptInputsResult,
 } from "./react/use-transcript.js";
-export { GuueyChat, type GuueyChatProps } from "./react/guuey-chat.js";
+export { GuueyChat, type GuueyChatProps, type GuueyChatHandle } from "./react/guuey-chat.js";
 export { Markdown } from "./react/markdown.js";
 export { themeCssVars, type ThemeMode } from "./react/theme-css.js";

package/src/strings.ts

@@ -55,6 +55,10 @@ export interface ChatStrings {
   viewInlineFallback: string;
   viewExpired: string;
   viewSandboxUnavailable: string;
+  /** guuey#204: the chip text for a mount promoted to a host stage/canvas. */
+  viewPromoted: (title: string) => string;
+  /** Chip title when the mount has no producing-call title (history cards). */
+  viewRefFallbackTitle: string;
 
   /** #192 debug-preset marker (calm never shows it — spec §3, F10). */
   recoveredFromHistory: string;
@@ -74,6 +78,17 @@ export interface ChatStrings {
   copy: string;
   copied: string;
 
+  /** R10 hitl actions (spec draft.2) — mode buttons use the ASKER's labels. */
+  promptAccept: string;
+  promptDecline: string;
+  promptDismissed: string;
+  /** The answered record line, e.g. `Allowed — Always`. */
+  promptAnsweredWith: (modeLabel: string) => string;
+  promptDeclinedRecord: string;
+
+  /** R16 — the notice row's label (provenance shows only under debug). */
+  noticeLabel: string;
+
   /** The 3c composer (`<GuueyChat>`). */
   composerPlaceholder: string;
   composerUnavailable: string;
@@ -121,6 +136,8 @@ export const defaultChatStrings: ChatStrings = {
   viewInlineFallback: "Showing plain content",
   viewExpired: "This view expired",
   viewSandboxUnavailable: "Interactive view unavailable",
+  viewPromoted: (title) => `${title} — on canvas`,
+  viewRefFallbackTitle: "Card",
 
   recoveredFromHistory: "recovered from history",
 
@@ -136,6 +153,14 @@ export const defaultChatStrings: ChatStrings = {
   copy: "Copy",
   copied: "Copied",
 
+  promptAccept: "Allow",
+  promptDecline: "Don't allow",
+  promptDismissed: "Dismissed",
+  promptAnsweredWith: (modeLabel) => `Allowed — ${modeLabel}`,
+  promptDeclinedRecord: "Not allowed",
+
+  noticeLabel: "Note",
+
   composerPlaceholder: "Message the agent…",
   composerUnavailable: "Chat is unavailable.",
   composerLabel: "Message",