@guuey/chat 0.5.0 → 0.6.0

package/dist/plan.js

@@ -1,4 +1,5 @@
 import { snapshotViewMount, toolResultViewMount, uiLocator } from "@guuey/mcp-apps-host";
+import { grantModeDisplay } from "./hitl.js";
 /** R5's giant threshold: above this byte count the state is `giant`. */
 const GIANT_RESULT_BYTES = 16_384;
 /** Approximate byte size of a JSON value — deterministic, allocation-bounded. */
@@ -28,6 +29,13 @@ function resolveExpanded(key, policyDefault, overrides) {
     const override = overrides[key]?.expanded;
     return override ?? policyDefault;
 }
+/** R16 notice text: the message's text blocks, joined (non-text blocks carry no notice prose). */
+function noticeText(content) {
+    return content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("\n");
+}
 function foldAssistantSources(result, inFlight, aborted) {
     // Real pod folds carry `tool-result` blocks in separate `role: "tool"`
     // messages between assistant turns (the production ggui-render capture is
@@ -35,21 +43,49 @@ function foldAssistantSources(result, inFlight, aborted) {
     // assistant-only filter orphans every call and drops every mount. A tool
     // message's blocks belong to the PRECEDING assistant slot's walk, exactly
     // the whole-fold message order the retired first-party renderers used.
+    //
+    // LIVE detection is turn-identity-based where the fold carries it: while
+    // a turn is in flight, an assistant message whose `turnId` maps to a turn
+    // record WITHOUT an `outcome` belongs to the open turn — settled earlier
+    // turns stay settled even mid-session (what makes the tail alignment
+    // below count them correctly). Nothing is live once the status is back to
+    // `ready`, whatever the records say (a fold that missed `turn.done` must
+    // not pin a settled turn open forever). Folds without turn identity (a
+    // hand-driven fold that never saw `turn.*` lifecycle) fall back to the
+    // last-source-is-live-iff-in-flight heuristic — the pre-refinement
+    // behaviour, kept so identity-less folds plan exactly as before.
+    const openTurns = new Set(result.turns.filter((t) => t.outcome === undefined).map((t) => t.turnId));
+    const hasTurnIdentity = result.messages.some((m) => m.role === "assistant" && m.turnId !== undefined);
     const sources = [];
+    const notices = [];
     for (const m of result.messages) {
         if (m.role === "assistant") {
-            sources.push({ blocks: [...m.content], live: false, stopped: false });
+            sources.push({
+                blocks: [...m.content],
+                live: inFlight && hasTurnIdentity && m.turnId !== undefined && openTurns.has(m.turnId),
+                stopped: false,
+            });
         }
         else if (m.role === "tool" && sources.length > 0) {
             sources[sources.length - 1].blocks.push(...m.content);
         }
+        else if (m.role === "notice") {
+            // R16 (spec draft.2): a session annotation — a PEER row, never folded
+            // into assistant content; it anchors after the source it followed.
+            notices.push({
+                text: noticeText(m.content),
+                source: m.noticeSource ?? null,
+                afterSourceIndex: sources.length - 1,
+            });
+        }
     }
     const last = sources[sources.length - 1];
     if (last) {
-        last.live = inFlight;
+        if (!hasTurnIdentity)
+            last.live = inFlight;
         last.stopped = aborted;
     }
-    return sources;
+    return { sources, notices };
 }
 function flatAssistantSources(inputs, inFlight) {
     const settled = inputs.messages
@@ -521,11 +557,74 @@ export function planTranscript(inputs, policy, overrides = {}) {
     }
     const inFlight = inputs.status !== "ready";
     const users = inputs.messages.filter((m) => m.role === "user");
-    const assistants = inputs.result
-        ? foldAssistantSources(inputs.result, inFlight, inputs.aborted === true)
-        : flatAssistantSources(inputs, inFlight);
+    // R16 — notice rows are session annotations anchored between turns: a
+    // flat notice renders after the conversation slot of the user turn it
+    // followed (usersSeen-1; -1 = before the conversation). They are PEER
+    // rows — excluded from both the user pairing and the assistant seam
+    // count, so the fold alignment below never sees them.
+    const notices = [];
+    if (policy.notice.show) {
+        let usersSeen = 0;
+        inputs.messages.forEach((m, i) => {
+            if (m.role === "user")
+                usersSeen += 1;
+            else if (m.role === "notice") {
+                notices.push({ key: `n${i}`, text: m.text, source: m.noticeSource ?? null, afterSlot: usersSeen - 1 });
+            }
+        });
+    }
+    // Turn-scoped fold composition (guuey#135 kit refinement): the fold owns
+    // the TRAILING assistant turns it actually covers — its settled sources
+    // replace that many trailing flat assistant entries; any EARLIER flat
+    // entries (a rehydrated/persisted prefix the session's Reducer never saw)
+    // keep rendering as flat text slots in front. When the fold spans the
+    // whole conversation (a pure-live session — the corpus's world), the kept
+    // prefix is empty and the plan is byte-identical to the old wholesale
+    // replace. Alignment is by COUNT (trailing flat entries ↔ settled fold
+    // sources): flat rows carry no turn identity, so a persisted CARD-ONLY
+    // turn inside the fold's span (an empty-text assistant row the assembler
+    // dropped) can offset the seam by one — a documented approximation, same
+    // class as the header's read-plane-seq note, resolved for the visible
+    // cards by the actionScope dedupe below.
+    let assistants;
+    if (inputs.result) {
+        const fold = foldAssistantSources(inputs.result, inFlight, inputs.aborted === true);
+        const foldSources = fold.sources;
+        const settledFoldCount = foldSources.filter((s) => !s.live).length;
+        const flatSettled = inputs.messages.filter((m) => m.role === "assistant");
+        const keep = Math.max(0, flatSettled.length - settledFoldCount);
+        assistants = [
+            ...flatSettled.slice(0, keep).map((m) => ({
+                blocks: [{ type: "text", text: m.text }],
+                live: false,
+                stopped: false,
+            })),
+            ...foldSources,
+        ];
+        if (policy.notice.show) {
+            // Fold-borne notices anchor to the fold source they followed, which
+            // sits at global slot `keep + afterSourceIndex` after the seam.
+            fold.notices.forEach((n, i) => {
+                notices.push({ key: `nf${i}`, text: n.text, source: n.source, afterSlot: keep + n.afterSourceIndex });
+            });
+        }
+    }
+    else {
+        assistants = flatAssistantSources(inputs, inFlight);
+    }
     const slots = Math.max(users.length, assistants.length);
     const conversation = [];
+    const noticeItem = (n) => ({
+        kind: "notice",
+        key: n.key,
+        expanded: true,
+        text: n.text,
+        source: n.source,
+        sourceLabel: policy.debugDetail && n.source !== null ? n.source : null,
+    });
+    for (const n of notices)
+        if (n.afterSlot < 0)
+            conversation.push(noticeItem(n));
     for (let slot = 0; slot < slots; slot++) {
         const user = users[slot];
         if (user) {
@@ -546,15 +645,37 @@ export function planTranscript(inputs, policy, overrides = {}) {
         if (assistant) {
             conversation.push(...planAssistantSource(assistant, slot, inputs, policy, overrides));
         }
+        for (const n of notices)
+            if (n.afterSlot === slot)
+                conversation.push(noticeItem(n));
     }
     items.push(...groupTools(conversation, policy, overrides));
     // R13 — persisted cards, seq order. (Position: after the settled
     // conversation; true in-turn interleave needs read-plane seqs the flat
     // surface lacks — the 3b assemblers own that refinement.)
+    //
+    // Dedupe against LIVE mounts by actionScope (the persisted `ui://`
+    // identity both sides carry): a session whose fold still holds a turn the
+    // read plane has ALSO persisted — the #192 adopted turn, a thread view's
+    // post-handoff refetch — would otherwise render the same card twice. The
+    // fold's view row owns it (richer phase state); the history snapshot
+    // renders only when no live mount claims its identity.
+    const liveViewScopes = new Set();
+    for (const item of items) {
+        if (item.kind === "view" && item.actionScope !== null)
+            liveViewScopes.add(item.actionScope);
+    }
     const cards = [...(inputs.historyCards ?? [])].sort((a, b) => a.seq - b.seq);
     for (const card of cards) {
         const key = `card.${card.seq}`;
         const mount = snapshotViewMount(card.cardSnapshot);
+        const scope = mount === undefined
+            ? null
+            : mount.channel === "locator"
+                ? mount.resourceUri
+                : mount.resource.uri;
+        if (scope !== null && liveViewScopes.has(scope))
+            continue; // live mount owns it
         const view = {
             kind: "view",
             key,
@@ -565,18 +686,40 @@ export function planTranscript(inputs, policy, overrides = {}) {
             label: null,
             attribution: null,
             toolTitle: null,
-            actionScope: mount === undefined
-                ? null
-                : mount.channel === "locator"
-                    ? mount.resourceUri
-                    : mount.resource.uri,
+            actionScope: scope,
         };
         view.label = viewLabel(view, policy);
         items.push(view);
     }
-    // R10 — prompts, in input order.
+    // R10 — prompts, in input order (narrow on `kind`: the guuey-wire
+    // profile arm vs the AgJSON hitl arm, spec draft.2).
     for (const prompt of inputs.prompts) {
         const key = `p.${prompt.id}`;
+        if (prompt.kind === "hitl") {
+            const chosen = prompt.grantModeId !== undefined
+                ? (prompt.ask.grantModes ?? []).find((m) => m.id === prompt.grantModeId)
+                : undefined;
+            items.push({
+                kind: "prompt",
+                key,
+                promptId: prompt.id,
+                // `cancelled` collapses to a dismissed record but stays expandable —
+                // guuey's re-askable ruling (silverprotocol#16); pending opens.
+                expanded: resolveExpanded(key, prompt.state === "pending", overrides),
+                promptKind: "hitl",
+                ask: prompt.ask,
+                message: prompt.ask.message ?? null,
+                askKind: prompt.ask.kind,
+                grantModes: prompt.ask.grantModes ?? [],
+                state: prompt.state,
+                chosenModeId: prompt.grantModeId ?? null,
+                chosenModeLabel: chosen !== undefined ? grantModeDisplay(chosen) : null,
+                raw: policy.prompt.rawPayload
+                    ? { askId: prompt.ask.askId, kind: prompt.ask.kind, state: prompt.state, grantModeId: prompt.grantModeId ?? null }
+                    : null,
+            });
+            continue;
+        }
         items.push({
             kind: "prompt",
             key,
@@ -621,9 +764,64 @@ export function planTranscript(inputs, policy, overrides = {}) {
             verbatim: policy.error.verbatim ? `${code ?? "uncoded"}: ${inputs.error.message}` : null,
         });
     }
+    // guuey#204 "promote and reference": the ONE mount a host-owned stage
+    // shows (`inputs.promotedViewKey`) renders as a compact reference chip
+    // instead of a second live app instance. A key matching nothing (stale
+    // host state) or an expired mount promotes nothing — the honest no-op;
+    // the next render's key corrects it. The chip keeps the mount's key, so
+    // overrides and phase reports survive a swap back to the full mount.
+    const promoted = inputs.promotedViewKey;
+    const finalItems = promoted === undefined
+        ? items
+        : items.map((item) => {
+            if (item.kind !== "view" || item.key !== promoted)
+                return item;
+            if (item.phase === "expired" || item.mount === null)
+                return item;
+            const title = item.toolTitle ?? policy.strings.viewRefFallbackTitle;
+            const ref = {
+                kind: "viewRef",
+                key: item.key,
+                expanded: false,
+                title,
+                label: policy.strings.viewPromoted(title),
+            };
+            return ref;
+        });
     return {
-        items,
+        items: finalItems,
         status: deriveStatus(inputs, policy),
         recovery: inputs.adopted === true && policy.debugDetail ? policy.strings.recoveredFromHistory : null,
     };
 }
+/**
+ * The plan key of the NEWEST mountable view — what a "most recent card"
+ * stage (the widget's CanvasPane) will show, derived in the same family
+ * the plan's own emission uses: live fold mounts (transcript order, last
+ * wins) outrank history cards (ascending `seq`). `undefined` when nothing
+ * narrows to a mountable resource. Hosts pass the key back as
+ * `TranscriptInputs.promotedViewKey`; `channel` lets a host decline to
+ * promote a bare locator when no reader is wired (the stage would show
+ * nothing, and a chip must never point at an empty canvas).
+ */
+export function newestViewKey(inputs) {
+    let newest;
+    const cards = [...(inputs.historyCards ?? [])].sort((a, b) => a.seq - b.seq);
+    for (const card of cards) {
+        const mount = snapshotViewMount(card.cardSnapshot);
+        if (mount === undefined)
+            continue;
+        newest = { key: `card.${card.seq}`, channel: mount.channel };
+    }
+    for (const message of inputs.result?.messages ?? []) {
+        for (const block of message.content) {
+            if (block.type !== "tool-result")
+                continue;
+            const mount = toolResultViewMount(block);
+            if (mount === undefined)
+                continue;
+            newest = { key: `view.${block.toolCallId}`, channel: mount.channel };
+        }
+    }
+    return newest;
+}

package/dist/policy.d.ts

@@ -93,6 +93,10 @@ export interface TranscriptPolicy {
         wakingMs: number;
         longStartMs: number;
     };
+    /** R16 (spec draft.2) — notice rows; provenance facet shows under debug. */
+    notice: {
+        show: boolean;
+    };
     /** R14. */
     compaction: {
         show: boolean;

package/dist/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,OAAO,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU;IACV,WAAW,EAAE;QAAE,eAAe,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1C,+EAA+E;IAC/E,IAAI,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5B,UAAU;IACV,SAAS,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,iBAAiB,EAAE,OAAO,CAAA;KAAE,CAAC;IACzD,UAAU;IACV,IAAI,EAAE;QACJ,eAAe,EAAE,OAAO,CAAC;QACzB,WAAW,EAAE,OAAO,CAAC;QACrB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;KAC7C,CAAC;IACF,iEAAiE;IACjE,SAAS,EAAE;QAAE,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAC;IACzC,UAAU;IACV,UAAU,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,OAAO,CAAC;QACrB,eAAe,EAAE,OAAO,CAAC;QACzB,+EAA+E;QAC/E,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,kEAAkE;IAClE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,UAAU;IACV,KAAK,EAAE;QAAE,iBAAiB,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IACxD,UAAU;IACV,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IACxC,UAAU;IACV,SAAS,EAAE;QAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC,WAAW;IACX,MAAM,EAAE;QAAE,SAAS,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/D;;;;;;;;;;;OAWG;IACH,KAAK,EAAE;QACL,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7C,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC;KAC1C,CAAC;IACF,oFAAoF;IACpF,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,WAAW;IACX,UAAU,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IAC9B,WAAW;IACX,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1C;AAkDD,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAElF;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAcnF"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,OAAO,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU;IACV,WAAW,EAAE;QAAE,eAAe,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1C,+EAA+E;IAC/E,IAAI,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5B,UAAU;IACV,SAAS,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,iBAAiB,EAAE,OAAO,CAAA;KAAE,CAAC;IACzD,UAAU;IACV,IAAI,EAAE;QACJ,eAAe,EAAE,OAAO,CAAC;QACzB,WAAW,EAAE,OAAO,CAAC;QACrB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;KAC7C,CAAC;IACF,iEAAiE;IACjE,SAAS,EAAE;QAAE,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAC;IACzC,UAAU;IACV,UAAU,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,OAAO,CAAC;QACrB,eAAe,EAAE,OAAO,CAAC;QACzB,+EAA+E;QAC/E,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,kEAAkE;IAClE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,UAAU;IACV,KAAK,EAAE;QAAE,iBAAiB,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IACxD,UAAU;IACV,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IACxC,UAAU;IACV,SAAS,EAAE;QAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC,WAAW;IACX,MAAM,EAAE;QAAE,SAAS,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/D;;;;;;;;;;;OAWG;IACH,KAAK,EAAE;QACL,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7C,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC;KAC1C,CAAC;IACF,oFAAoF;IACpF,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,4EAA4E;IAC5E,MAAM,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1B,WAAW;IACX,UAAU,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IAC9B,WAAW;IACX,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1C;AAoDD,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAElF;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAcnF"}

package/dist/policy.js

@@ -27,6 +27,7 @@ function withOverrides(base, overrides) {
         prompt: { ...base.prompt, ...(overrides.prompt ?? {}) },
         error: { ...base.error, ...(overrides.error ?? {}) },
         status: { ...base.status, ...(overrides.status ?? {}) },
+        notice: { ...base.notice, ...(overrides.notice ?? {}) },
         compaction: { ...base.compaction, ...(overrides.compaction ?? {}) },
         unknown: { ...base.unknown, ...(overrides.unknown ?? {}) },
     };
@@ -46,6 +47,7 @@ function calmBase() {
         media: { inlineImageCapRem: 20, chipOnly: false },
         code: { capRem: 16, wrap: false },
         citations: { style: "chips" },
+        notice: { show: true },
         prompt: { placement: "inline", rawPayload: false },
         error: { verbatim: false, copyByCode: {}, verbatimCodes: [] },
         status: { wakingMs: 2500, longStartMs: 15_000 },

package/dist/react/components.d.ts

@@ -22,7 +22,7 @@ import { type ComponentType, type ReactNode } from "react";
 import { type GuueyViewProps } from "@guuey/mcp-apps-host/react";
 import type { ResolvedViewMount, ViewHostPhase } from "@guuey/mcp-apps-host";
 import type { ChatStrings } from "../strings.js";
-import type { CitationsItem, CodeItem, CompactionItem, DataResultItem, DisplayItem, ErrorItem, HistoryBoundaryItem, ItemKey, MediaItem, PromptItem, ReasoningItem, StatusLineItem, ToolGroupItem, ToolItem, UnknownItem, UserMessageItem, TextItem, ViewMountItem } from "../types.js";
+import type { CitationsItem, CodeItem, CompactionItem, DataResultItem, DisplayItem, ErrorItem, HistoryBoundaryItem, ItemKey, MediaItem, NoticeItem, PromptItem, ReasoningItem, StatusLineItem, ToolGroupItem, ToolItem, UnknownItem, UserMessageItem, TextItem, ViewMountItem, ViewRefItem } from "../types.js";
 /** Everything a rendered item may need beyond itself. */
 export interface TranscriptItemContext {
     strings: ChatStrings;
@@ -30,17 +30,40 @@ export interface TranscriptItemContext {
     onToggle: (key: ItemKey) => void;
     /** R0 failed-send retry. */
     onRetry?: (item: UserMessageItem) => void;
-    /** R10 prompt actions — the host owns what accept/decline DO. */
-    onPromptAction?: (item: PromptItem, action: "accept" | "decline" | "dismiss") => void;
+    /**
+     * R10 prompt actions — the host owns what accept/decline DO. A hitl card
+     * with declared grant modes reports the pick as `{ grantModeId }` (spec
+     * draft.2); plain accepts stay the `"accept"` string.
+     */
+    onPromptAction?: (item: PromptItem, action: "accept" | "decline" | "dismiss" | {
+        grantModeId: string;
+    }) => void;
     /** R11 action slots (sign-in / upgrade / retry affordances). */
     onErrorAction?: (item: ErrorItem) => void;
     /** R6: locator mounts resolved by `useTranscript` ("expired" = failed). */
     resolvedMounts: ReadonlyMap<ItemKey, ResolvedViewMount | "expired">;
     /** R6: live phase reports wired back into the next plan. */
     onViewPhase: (key: ItemKey, phase: ViewHostPhase) => void;
-    /** R6 pass-through (sandbox overrides etc. — policy-gated by the host). */
-    viewProps?: Pick<GuueyViewProps, "hostCapabilities" | "hostInfo" | "hostContext" | "onCallTool" | "negotiationTimeoutMs" | "dangerouslyAddSandboxFlags" | "allow">;
+    /**
+     * guuey#204: a promoted-view reference chip was activated — the host
+     * focuses/reveals its stage (canvas). Absent ⇒ the chip renders as a
+     * non-interactive label.
+     */
+    onViewRef?: (item: ViewRefItem) => void;
+    /**
+     * R6 pass-through (sandbox overrides, the two-origin mount, relay hooks
+     * — policy-gated by the host). Static, or a FUNCTION of the mount being
+     * rendered: view configuration legitimately varies per mount — the
+     * relay-page URL picks a per-channel egress grant (`?channel=`), and a
+     * `tools/call` hook scopes to the item's persisted locator (guuey#158) —
+     * so the function form receives the item and its resolved mount and is
+     * called only when something actually mounts. Static keeps working
+     * unchanged.
+     */
+    viewProps?: ViewSlotProps | ((item: ViewMountItem, mount: ResolvedViewMount) => ViewSlotProps);
 }
+/** The per-view slice of `GuueyViewProps` a transcript may configure. */
+export type ViewSlotProps = Pick<GuueyViewProps, "hostCapabilities" | "hostInfo" | "hostContext" | "onCallTool" | "onReadResource" | "onSizeChanged" | "negotiationTimeoutMs" | "dangerouslyAddSandboxFlags" | "allow" | "sandboxPageUrl" | "autoResize">;
 interface ItemProps<T> {
     item: T;
     ctx: TranscriptItemContext;
@@ -52,10 +75,22 @@ export declare function DefaultDataResult({ item, ctx }: ItemProps<DataResultIte
 export declare function DefaultTool({ item, ctx }: ItemProps<ToolItem>): ReactNode;
 export declare function DefaultToolGroup({ item, ctx }: ItemProps<ToolGroupItem>): ReactNode;
 export declare function DefaultView({ item, ctx }: ItemProps<ViewMountItem>): ReactNode;
+/**
+ * guuey#204: the "promote and reference" chip — stands in for the one
+ * mount the host's stage shows. A real button when the host wires
+ * `onViewRef` (keyboard-accessible for free); a plain label otherwise.
+ */
+export declare function DefaultViewRef({ item, ctx }: ItemProps<ViewRefItem>): ReactNode;
 export declare function DefaultMedia({ item }: ItemProps<MediaItem>): ReactNode;
 export declare function DefaultCode({ item, ctx }: ItemProps<CodeItem>): ReactNode;
 export declare function DefaultCitations({ item, ctx }: ItemProps<CitationsItem>): ReactNode;
 export declare function DefaultPrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode;
+/**
+ * A `role:"notice"` session annotation (spec draft.2) — a labeled,
+ * non-conversational row that must never read as agent-authored. Calm
+ * shows the quiet label; debug appends the provenance facet verbatim.
+ */
+export declare function DefaultNotice({ item, ctx }: ItemProps<NoticeItem>): ReactNode;
 export declare function DefaultError({ item, ctx }: ItemProps<ErrorItem>): ReactNode;
 export declare function DefaultHistoryBoundary({ item }: ItemProps<HistoryBoundaryItem>): ReactNode;
 export declare function DefaultCompaction({ item }: ItemProps<CompactionItem>): ReactNode;
@@ -70,10 +105,12 @@ export interface TranscriptComponents {
     toolGroup: ComponentType<ItemProps<ToolGroupItem>>;
     dataResult: ComponentType<ItemProps<DataResultItem>>;
     view: ComponentType<ItemProps<ViewMountItem>>;
+    viewRef: ComponentType<ItemProps<ViewRefItem>>;
     media: ComponentType<ItemProps<MediaItem>>;
     code: ComponentType<ItemProps<CodeItem>>;
     citations: ComponentType<ItemProps<CitationsItem>>;
     prompt: ComponentType<ItemProps<PromptItem>>;
+    notice: ComponentType<ItemProps<NoticeItem>>;
     error: ComponentType<ItemProps<ErrorItem>>;
     history: ComponentType<ItemProps<HistoryBoundaryItem>>;
     compaction: ComponentType<ItemProps<CompactionItem>>;

package/dist/react/components.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/react/components.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EACd,cAAc,EACd,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,OAAO,EACP,SAAS,EACT,UAAU,EACV,aAAa,EACb,cAAc,EACd,aAAa,EACb,QAAQ,EACR,WAAW,EACX,eAAe,EACf,QAAQ,EACR,aAAa,EACd,MAAM,aAAa,CAAC;AAGrB,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,WAAW,CAAC;IACrB,wEAAwE;IACxE,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC,4BAA4B;IAC5B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,iEAAiE;IACjE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,KAAK,IAAI,CAAC;IACtF,gEAAgE;IAChE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAC1C,2EAA2E;IAC3E,cAAc,EAAE,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAAC,CAAC;IACpE,4DAA4D;IAC5D,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1D,2EAA2E;IAC3E,SAAS,CAAC,EAAE,IAAI,CACd,cAAc,EACd,kBAAkB,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,sBAAsB,GAAG,4BAA4B,GAAG,OAAO,CACjI,CAAC;CACH;AAED,UAAU,SAAS,CAAC,CAAC;IACnB,IAAI,EAAE,CAAC,CAAC;IACR,GAAG,EAAE,qBAAqB,CAAC;CAC5B;AAiED,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAiBvF;AAID,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,SAAS,CAmBzE;AAID,wBAAgB,gBAAgB,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,aAAa,CAAC,GAAG,SAAS,CAYnF;AAID,wBAAgB,iBAAiB,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG,SAAS,CAmBrF;AAWD,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,SAAS,CA+BzE;AAID,wBAAgB,gBAAgB,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,aAAa,CAAC,GAAG,SAAS,CAqBnF;AAID,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,aAAa,CAAC,GAAG,SAAS,CAwC9E;AAcD,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS,CAAC,SAAS,CAAC,GAAG,SAAS,CAqBtE;AAID,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,SAAS,CAUzE;AASD,wBAAgB,gBAAgB,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,aAAa,CAAC,GAAG,SAAS,CA4BnF;AAID,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,UAAU,CAAC,GAAG,SAAS,CAmD7E;AAID,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,SAAS,CAAC,GAAG,SAAS,CAY3E;AAID,wBAAgB,sBAAsB,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS,CAAC,mBAAmB,CAAC,GAAG,SAAS,CAS1F;AAED,wBAAgB,iBAAiB,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG,SAAS,CAMhF;AAED,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAoB/E;AAID,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG,SAAS,CAO5E;AAID,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,aAAa,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC;IACvD,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;IACnD,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;IACnD,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IACrD,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;IAC9C,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3C,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;IACnD,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAC7C,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3C,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACvD,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IACrD,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAC/C,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;CAClD;AAED,eAAO,MAAM,2BAA2B,EAAE,oBAiBzC,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,UAAU,CACxB,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,oBAAoB,EAChC,GAAG,EAAE,qBAAqB,GACzB,SAAS,CA+DX"}
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/react/components.tsx"],"names":[],"mappings":"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"}

package/dist/react/components.js

@@ -98,7 +98,22 @@ export function DefaultView({ item, ctx }) {
         // never blank.
         return (_jsx("div", { className: "guuey-chat-view guuey-chat-view-negotiating guuey-chat-shimmer", children: _jsx("p", { role: "status", children: item.label ?? ctx.strings.viewNegotiating }) }));
     }
-    return (_jsxs("div", { className: "guuey-chat-view", children: [_jsx(GuueyView, { mount: mount, ...(ctx.viewProps ?? {}), onPhaseChange: (phase) => ctx.onViewPhase(item.key, phase) }), item.attribution !== null ? (_jsx("p", { className: "guuey-chat-attribution", children: item.attribution })) : null] }));
+    // The function form resolves against the ACTUAL mount (per-channel relay
+    // URLs, per-locator action scoping); it runs only when something mounts.
+    const viewProps = typeof ctx.viewProps === "function" ? ctx.viewProps(item, mount) : (ctx.viewProps ?? {});
+    return (_jsxs("div", { className: "guuey-chat-view", children: [_jsx(GuueyView, { mount: mount, ...viewProps, onPhaseChange: (phase) => ctx.onViewPhase(item.key, phase) }), item.attribution !== null ? (_jsx("p", { className: "guuey-chat-attribution", children: item.attribution })) : null] }));
+}
+/**
+ * guuey#204: the "promote and reference" chip — stands in for the one
+ * mount the host's stage shows. A real button when the host wires
+ * `onViewRef` (keyboard-accessible for free); a plain label otherwise.
+ */
+export function DefaultViewRef({ item, ctx }) {
+    if (ctx.onViewRef === undefined) {
+        return (_jsx("p", { className: "guuey-chat-view-ref", role: "note", children: item.label }));
+    }
+    const onViewRef = ctx.onViewRef;
+    return (_jsx("button", { type: "button", className: "guuey-chat-view-ref guuey-chat-view-ref-button", onClick: () => onViewRef(item), children: item.label }));
 }
 // ─── R7 ────────────────────────────────────────────────────────────────────
 /** Inline images allow https URLs and image/* base64 data — nothing else. */
@@ -160,6 +175,22 @@ export function DefaultPrompt({ item, ctx }) {
         }
         wasPending.current = item.state === "pending";
     }, [item.state]);
+    if (item.promptKind === "hitl") {
+        const s = ctx.strings;
+        // Settled records: resolved shows the CHOSEN MODE'S LABEL (ids are
+        // echo-only identity — asker-scoped semantics, spec §7); declined is
+        // the durable deny. `cancelled` is guuey's re-askable dismissal: it
+        // collapses to a record but stays answerable when expanded.
+        if (item.state === "resolved" || item.state === "declined") {
+            return (_jsx("p", { className: `guuey-chat-prompt-record guuey-chat-prompt-${item.state}`, children: item.state === "resolved"
+                    ? item.chosenModeLabel !== null
+                        ? s.promptAnsweredWith(item.chosenModeLabel)
+                        : s.promptAccept
+                    : s.promptDeclinedRecord }));
+        }
+        const answerable = item.state === "pending" || (item.state === "cancelled" && item.expanded);
+        return (_jsxs("div", { className: "guuey-chat-prompt", role: "group", children: [item.state === "cancelled" && (_jsx("button", { type: "button", className: "guuey-chat-prompt-record guuey-chat-prompt-cancelled", "aria-expanded": item.expanded, onClick: () => ctx.onToggle(item.key), children: s.promptDismissed })), answerable && (_jsxs(_Fragment, { children: [item.message !== null && _jsx("p", { className: "guuey-chat-prompt-ask", children: item.message }), _jsxs("div", { className: "guuey-chat-prompt-actions", children: [item.grantModes.length === 0 ? (_jsx("button", { ref: firstAction, type: "button", className: "guuey-chat-prompt-accept", onClick: () => ctx.onPromptAction?.(item, "accept"), children: s.promptAccept })) : (item.grantModes.map((mode, i) => (_jsx("button", { ref: i === 0 ? firstAction : undefined, type: "button", className: "guuey-chat-prompt-accept", title: mode.description, onClick: () => ctx.onPromptAction?.(item, { grantModeId: mode.id }), children: mode.label ?? mode.id }, mode.id)))), _jsx("button", { type: "button", onClick: () => ctx.onPromptAction?.(item, "decline"), children: s.promptDecline })] })] }))] }));
+    }
     if (item.state !== "pending") {
         return (_jsxs("p", { className: `guuey-chat-prompt-record guuey-chat-prompt-${item.state}`, children: [item.promptKind, ": ", item.state] }));
     }
@@ -167,6 +198,15 @@ export function DefaultPrompt({ item, ctx }) {
                     ? `${item.appId} requests ${item.requested} access`
                     : `Link your account to ${item.appId}` }), _jsxs("div", { className: "guuey-chat-prompt-actions", children: [_jsx("button", { ref: firstAction, type: "button", className: "guuey-chat-prompt-accept", onClick: () => ctx.onPromptAction?.(item, "accept"), children: "Allow" }), _jsx("button", { type: "button", onClick: () => ctx.onPromptAction?.(item, "decline"), children: "Decline" })] }), item.raw !== null ? (_jsx("pre", { className: "guuey-chat-prompt-raw", children: JSON.stringify(item.raw, null, 2) })) : null] }));
 }
+// ─── R16 ──────────────────────────────────────────────────────────────────
+/**
+ * A `role:"notice"` session annotation (spec draft.2) — a labeled,
+ * non-conversational row that must never read as agent-authored. Calm
+ * shows the quiet label; debug appends the provenance facet verbatim.
+ */
+export function DefaultNotice({ item, ctx }) {
+    return (_jsxs("div", { className: "guuey-chat-notice", role: "note", children: [_jsxs("span", { className: "guuey-chat-notice-label", children: [ctx.strings.noticeLabel, item.sourceLabel !== null ? ` · ${item.sourceLabel}` : ""] }), item.text !== "" && _jsx("span", { className: "guuey-chat-notice-text", children: item.text })] }));
+}
 // ─── R11 ───────────────────────────────────────────────────────────────────
 export function DefaultError({ item, ctx }) {
     return (_jsxs("div", { className: `guuey-chat-error guuey-chat-error-${item.family}`, role: "alert", children: [_jsx("p", { children: item.copy }), ctx.onErrorAction !== undefined && (item.family === "transient" || item.family === "auth") ? (_jsx("button", { type: "button", className: "guuey-chat-error-action", onClick: () => ctx.onErrorAction?.(item), children: item.family === "auth" ? ctx.strings.errorAuth : ctx.strings.userRetry })) : null, item.verbatim !== null ? _jsx("pre", { className: "guuey-chat-error-verbatim", children: item.verbatim }) : null] }));
@@ -193,10 +233,12 @@ export const defaultTranscriptComponents = {
     toolGroup: DefaultToolGroup,
     dataResult: DefaultDataResult,
     view: DefaultView,
+    viewRef: DefaultViewRef,
     media: DefaultMedia,
     code: DefaultCode,
     citations: DefaultCitations,
     prompt: DefaultPrompt,
+    notice: DefaultNotice,
     error: DefaultError,
     history: DefaultHistoryBoundary,
     compaction: DefaultCompaction,
@@ -234,6 +276,10 @@ export function renderItem(item, components, ctx) {
             const C = components.view;
             return _jsx(C, { item: item, ctx: ctx }, item.key);
         }
+        case "viewRef": {
+            const C = components.viewRef;
+            return _jsx(C, { item: item, ctx: ctx }, item.key);
+        }
         case "media": {
             const C = components.media;
             return _jsx(C, { item: item, ctx: ctx }, item.key);
@@ -250,6 +296,10 @@ export function renderItem(item, components, ctx) {
             const C = components.prompt;
             return _jsx(C, { item: item, ctx: ctx }, item.key);
         }
+        case "notice": {
+            const C = components.notice;
+            return _jsx(C, { item: item, ctx: ctx }, item.key);
+        }
         case "error": {
             const C = components.error;
             return _jsx(C, { item: item, ctx: ctx }, item.key);

package/dist/react/guuey-chat.d.ts

@@ -31,17 +31,59 @@
  * 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 { type CSSProperties, type ReactNode } from "react";
+import { type CSSProperties } from "react";
 import { type AgentInvokeAdapters } from "@guuey/agent-client";
+import type { AgHitlAnswer, AgPausedAsk } from "@silverprotocol/core";
 import type { UiResourceReader } from "@guuey/mcp-apps-host";
 import { type TranscriptPolicy } from "../policy.js";
 import { type ChatStrings } from "../strings.js";
 import { type GuueyChatTheme } from "../theme.js";
-import type { ErrorItem, PromptItem } from "../types.js";
+import type { ChatDebugEvent, ErrorItem, PromptItem } from "../types.js";
 import type { ThemeMode } from "./theme-css.js";
 import { type TranscriptWindowing } from "./transcript.js";
 import type { TranscriptComponents, TranscriptItemContext } from "./components.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;
@@ -67,6 +109,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"];
     /**
@@ -74,11 +118,25 @@ 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;
 }
-export declare function GuueyChat(props: GuueyChatProps): ReactNode;
+export declare const GuueyChat: import("react").ForwardRefExoticComponent<GuueyChatProps & import("react").RefAttributes<GuueyChatHandle>>;
 //# sourceMappingURL=guuey-chat.d.ts.map