@guuey/chat 0.4.0 → 0.6.0

package/src/corpus/drive.ts

@@ -7,7 +7,7 @@
  */
 import { Reducer, type AgEvent } from "@silverprotocol/core";
 import type { InvokeTurnEvent } from "@guuey/agent-client";
-import type { PromptItemInput, TranscriptInputs, TranscriptMessage } from "../types.js";
+import type { ProfilePromptInput, TranscriptInputs, TranscriptMessage } from "../types.js";
 
 export interface DriveOptions {
   userText?: string;
@@ -22,7 +22,7 @@ export interface DriveOptions {
   historyCards?: TranscriptInputs["historyCards"];
   historyState?: TranscriptInputs["historyState"];
   /** Resolve accumulated prompts to this state (fixture 4's answered leg). */
-  promptState?: PromptItemInput["state"];
+  promptState?: ProfilePromptInput["state"];
 }
 
 export function driveTurn(events: InvokeTurnEvent[], opts: DriveOptions = {}): TranscriptInputs {
@@ -32,7 +32,7 @@ export function driveTurn(events: InvokeTurnEvent[], opts: DriveOptions = {}): T
   let assistantText = "";
   let activeTool: string | null = null;
   let error: TranscriptInputs["error"] = null;
-  const prompts: PromptItemInput[] = [];
+  const prompts: ProfilePromptInput[] = [];
   let done = false;
 
   for (const ev of events) {

package/src/corpus/fixtures.ts

@@ -8,7 +8,7 @@
  * THE STANDING RULE (see README.md): a new weird transcript found in
  * production becomes a fixture BEFORE its fix lands. The corpus only grows.
  */
-import type { AgEvent } from "@silverprotocol/core";
+import { Reducer, type AgEvent } from "@silverprotocol/core";
 import type { InvokeTurnEvent } from "@guuey/agent-client";
 import type { TranscriptInputs } from "../types.js";
 import {
@@ -320,6 +320,99 @@ export function userSendFailure(): TranscriptInputs {
   });
 }
 
+/**
+ * 19. persisted-plus-live — the turn-scoped fold composition (portal's
+ * persisted-overlay data model): a persisted prefix the session's Reducer
+ * never saw + a session fold covering the trailing turns, one settled (its
+ * card ALSO persisted — the dedupe case) and one live with a running tool.
+ */
+export function persistedPlusLive(): TranscriptInputs {
+  const reducer = new Reducer();
+  let seq = 0;
+  const s = (): number => seq++;
+  const push = (events: AgEvent[]): void => {
+    for (const ev of events) reducer.push(ev);
+  };
+  // Session turn A (settled — turn.done carries the outcome):
+  push([
+    { type: "turn.start", threadId: "thread-corpus", turnId: "turn-a", seq: s() },
+    { type: "message.start", id: "msg-a", role: "assistant", turnId: "turn-a", threadId: "thread-corpus", seq: s() },
+    { type: "text.start", id: "ta", seq: s() },
+    { type: "text.delta", id: "ta", delta: "Booked the second option.", seq: s() },
+    { type: "text.end", id: "ta", seq: s() },
+    { type: "tool.start", toolCallId: "tA", name: "ggui_render", seq: s() },
+    {
+      type: "tool.done",
+      toolCallId: "tA",
+      content: [],
+      outcome: "ok",
+      uiData: { sessionId: GGUI_SLICE.sessionId, resourceUri: GGUI_RESOURCE_URI, action: "create" },
+      _meta: { [GGUI_META_KEY]: GGUI_SLICE },
+      seq: s(),
+    },
+    { type: "turn.done", turnId: "turn-a", outcome: { type: "success" }, seq: s() },
+  ]);
+  // Session turn B (live — no turn.done yet): one completed tool already in
+  // the fold, a second still active (the fold materializes a tool-call at
+  // `tool.done`; the ACTIVE call is the status line's job, not a row).
+  push([
+    { type: "turn.start", threadId: "thread-corpus", turnId: "turn-b", seq: s() },
+    { type: "message.start", id: "msg-b", role: "assistant", turnId: "turn-b", threadId: "thread-corpus", seq: s() },
+    { type: "tool.start", toolCallId: "tB", name: "load_booking", turnId: "turn-b", seq: s() },
+    { type: "tool.args.assembled", toolCallId: "tB", input: { id: "second" }, turnId: "turn-b", seq: s() },
+    {
+      type: "tool.done",
+      toolCallId: "tB",
+      content: [{ type: "text", text: "loaded" }],
+      outcome: "ok",
+      turnId: "turn-b",
+      seq: s(),
+    },
+  ]);
+  return {
+    result: reducer.result(),
+    assistantText: "",
+    status: "using-tool",
+    statusElapsedMs: 0,
+    activeTool: "check_calendar",
+    error: null,
+    prompts: [],
+    // The flat transcript: one PERSISTED turn the fold never saw, then the
+    // session turns (turn A's settled text row is present — the thread
+    // viewer's liveTail/refetch carries it; turn B is in flight, no row).
+    messages: [
+      { role: "user", text: "plan my trip" },
+      { role: "assistant", text: "Here are some options." },
+      { role: "user", text: "book the second one" },
+      { role: "assistant", text: "Booked the second option." },
+      { role: "user", text: "now move it to Thursday" },
+    ],
+    historyCards: [
+      // An OLD persisted card (pre-session) — must render.
+      {
+        seq: 1,
+        at: "2026-08-15T00:00:00Z",
+        cardSnapshot: {
+          parts: [
+            { type: "tool-result", toolCallId: "old1", content: [], uiData: { resourceUri: "ui://ggui/render/old/1" } },
+          ],
+        },
+      },
+      // Turn A's card, ALSO persisted by the read plane — the live fold's
+      // mount owns this identity; the snapshot must dedupe away.
+      {
+        seq: 5,
+        at: "2026-08-15T00:05:00Z",
+        cardSnapshot: {
+          parts: [
+            { type: "tool-result", toolCallId: "tA", content: [], uiData: { resourceUri: GGUI_RESOURCE_URI } },
+          ],
+        },
+      },
+    ],
+  };
+}
+
 /** 17. stalled-then-adopted — #192: calm identical, debug carries the marker. */
 export function stalledThenAdopted(): { adopted: TranscriptInputs; streamed: TranscriptInputs } {
   const build = (): InvokeTurnEvent[] => {
@@ -336,3 +429,129 @@ export function stalledThenAdopted(): { adopted: TranscriptInputs; streamed: Tra
     streamed: driveTurn(build(), { userText: "move my booking" }),
   };
 }
+
+/**
+ * 20. hitl-grant-modes (spec draft.2, silverprotocol#16) — a paused turn's
+ * PERSISTED ask declares three asker-scoped accept variants. Driven through
+ * the real Reducer: the declaration the card renders from is
+ * `turn.done.outcome:"paused".asks[]`, exactly what a late-joining client
+ * sees. Ids are deliberately arbitrary strings — display must key off
+ * label/description, never id semantics.
+ */
+export function hitlGrantModes(): TranscriptInputs {
+  const reducer = new Reducer();
+  let seq = 0;
+  const s = (): number => seq++;
+  const events: AgEvent[] = [
+    { type: "turn.start", threadId: "thread-hitl", turnId: "turn-h", seq: s() },
+    { type: "message.start", id: "msg-h", role: "assistant", turnId: "turn-h", threadId: "thread-hitl", seq: s() },
+    { type: "text.start", id: "th", seq: s() },
+    { type: "text.delta", id: "th", delta: "I can remember this preference.", seq: s() },
+    { type: "text.end", id: "th", seq: s() },
+    {
+      type: "turn.done",
+      turnId: "turn-h",
+      outcome: {
+        type: "paused",
+        asks: [
+          {
+            askId: "ask-remember-1",
+            kind: "approval",
+            message: "Remember your seating preference?",
+            grantModes: [
+              { id: "m.durable", label: "Always", description: "Keep it for every future chat" },
+              { id: "m.scoped", label: "Just this chat" },
+            ],
+            requestState: "rs-bytes-1",
+          },
+        ],
+      },
+      seq: s(),
+    },
+  ];
+  for (const ev of events) reducer.push(ev);
+  return {
+    result: reducer.result(),
+    assistantText: "",
+    status: "ready",
+    statusElapsedMs: 0,
+    activeTool: null,
+    error: null,
+    prompts: [], // the test composes these via hitlPromptsFromFold + the answer ledger
+    messages: [{ role: "user", text: "book my usual seat" }],
+  };
+}
+
+/**
+ * 21. notice-rows (spec draft.2) — both arrival paths: a flat adapter
+ * notice (the portal self-hosted mapping) and a fold-borne framework
+ * notice (the claude informational promotion). Labeled, non-conversational,
+ * never agent-voiced; provenance shows only under debug.
+ */
+export function noticeRows(): TranscriptInputs {
+  const reducer = new Reducer();
+  let seq = 0;
+  const s = (): number => seq++;
+  const events: AgEvent[] = [
+    { type: "turn.start", threadId: "thread-n", turnId: "turn-n", seq: s() },
+    {
+      type: "message.start",
+      id: "msg-n0",
+      role: "notice",
+      noticeSource: "framework",
+      turnId: "turn-n",
+      threadId: "thread-n",
+      seq: s(),
+    },
+    // The notice's text lands while it is the sole open message, so block
+    // routing is unambiguous; the assistant message opens after.
+    { type: "text.start", id: "tn0", seq: s() },
+    { type: "text.delta", id: "tn0", delta: "Model fell back to concise mode", seq: s() },
+    { type: "text.end", id: "tn0", seq: s() },
+    { type: "message.end", id: "msg-n0", turnId: "turn-n", seq: s() },
+    { type: "message.start", id: "msg-n1", role: "assistant", turnId: "turn-n", threadId: "thread-n", seq: s() },
+    { type: "text.start", id: "tn", seq: s() },
+    { type: "text.delta", id: "tn", delta: "Done.", seq: s() },
+    { type: "text.end", id: "tn", seq: s() },
+    { type: "turn.done", turnId: "turn-n", outcome: { type: "success" }, seq: s() },
+  ];
+  for (const ev of events) reducer.push(ev);
+  return {
+    result: reducer.result(),
+    assistantText: "",
+    status: "ready",
+    statusElapsedMs: 0,
+    activeTool: null,
+    error: null,
+    prompts: [],
+    messages: [
+      { role: "notice", text: "Session resumed on a new device", noticeSource: "adapter" },
+      { role: "user", text: "hi" },
+      { role: "assistant", text: "Done." },
+    ],
+  };
+}
+
+/**
+ * 22. promoted-view — guuey#204 "promote and reference": the mount a host
+ * stage shows chips in the transcript; every other mount stays full; no
+ * key (or a stale one) is byte-identical to today.
+ */
+export function promotedView(): { inputs: TranscriptInputs; promotedKey: string } {
+  const s = seqSource();
+  const events: InvokeTurnEvent[] = [session, frame(boot(s), { status: "thinking" })];
+  for (const id of ["t1", "t2"] as const) {
+    events.push(
+      frame(
+        toolPart(s, id, "ggui_render", {
+          uiData: { uri: `ui://cards/${id}`, mimeType: "text/html", text: `<div>${id}</div>` },
+          content: [],
+        }),
+        { status: "using-tool", activeTool: "ggui_render" },
+      ),
+    );
+  }
+  events.push(doneEvent);
+  const inputs = driveTurn(events, { userText: "show me two cards" });
+  return { inputs, promotedKey: "view.t2" };
+}

package/src/hitl.ts

@@ -0,0 +1,103 @@
+/**
+ * R10's AgJSON HITL half (spec draft.2, silverprotocol/typescript-sdk#16):
+ * lifting persisted asks out of the fold, and constructing validated
+ * answers.
+ *
+ * Two contract points are load-bearing here:
+ *
+ *  - **Asks render from the PERSISTED declaration** — `AgPausedAsk` in
+ *    `turn.done.outcome:"paused".asks[]`. The live `hitl.ask` event is
+ *    live-only by spec (§1.3); a client that joins a thread late renders
+ *    the paused record, so this module reads ONLY that record and both
+ *    paths converge.
+ *  - **Every answer is validated BEFORE dispatch** — `validateHitlAnswer`
+ *    from core enforces required-iff-declared, echo-must-be-declared, and
+ *    the `requestState` byte-echo MUST. `buildHitlAnswer` constructs
+ *    answers that pass by construction and THROWS if they don't: a failed
+ *    validation here is a kit bug, never a user-visible state.
+ *
+ * Answer states encode guuey's ratified dismissal ruling (#16): dismissal
+ * maps to `cancelled` (still-pending, re-askable — the card stays
+ * answerable), `declined` is the durable explicit deny.
+ */
+import {
+  validateHitlAnswer,
+  type AgGrantMode,
+  type AgHitlAnswer,
+  type AgPausedAsk,
+  type AgReduceResult,
+} from "@silverprotocol/core";
+import type { HitlPromptInput } from "./types.js";
+
+/** A host-side record of how an ask was answered (the assembler's ledger value). */
+export interface HitlAnswerRecord {
+  status: "resolved" | "declined" | "cancelled";
+  /** Present iff `status === "resolved"` and the ask declared modes. */
+  grantModeId?: string;
+}
+
+/** A user action on a HITL card: pick a declared mode, decline, or dismiss. */
+export type HitlPromptAction = { grantModeId: string } | "accept" | "decline" | "dismiss";
+
+/**
+ * Display text for a grant mode: the asker's `label`, else the id as
+ * LITERAL text. Mode semantics are asker-scoped (normative, spec §7):
+ * falling back to the id displays identity, never interpreted meaning —
+ * a renderer must not special-case id strings.
+ */
+export function grantModeDisplay(mode: AgGrantMode): string {
+  return mode.label ?? mode.id;
+}
+
+/**
+ * Lift every persisted ask in the fold into an R10 prompt input, merged
+ * with the host's answer ledger (keyed by askId). Pure; input order is the
+ * fold's turn order.
+ */
+export function hitlPromptsFromFold(
+  result: AgReduceResult | null,
+  answers: Readonly<Record<string, HitlAnswerRecord>> = {},
+): HitlPromptInput[] {
+  if (result === null) return [];
+  const prompts: HitlPromptInput[] = [];
+  for (const turn of result.turns) {
+    if (turn.outcome?.type !== "paused") continue;
+    for (const ask of turn.outcome.asks) {
+      const answer = answers[ask.askId];
+      prompts.push({
+        id: ask.askId,
+        kind: "hitl",
+        ask,
+        state: answer?.status ?? "pending",
+        ...(answer?.grantModeId !== undefined ? { grantModeId: answer.grantModeId } : {}),
+      });
+    }
+  }
+  return prompts;
+}
+
+/**
+ * Construct the wire answer for a card action and validate it against the
+ * ask's own persisted record before anything dispatches it.
+ *
+ * `"accept"` is the plain-ask affirmative (valid only when the ask
+ * declared no modes — with a declaration, accepting IS picking a mode).
+ * A validation failure throws: the inputs came from the declaration
+ * itself, so a mismatch is a construction bug, not a user error.
+ */
+export function buildHitlAnswer(ask: AgPausedAsk, action: HitlPromptAction): AgHitlAnswer {
+  const answer: AgHitlAnswer = {
+    askId: ask.askId,
+    status:
+      action === "decline" ? "declined" : action === "dismiss" ? "cancelled" : "resolved",
+    ...(typeof action === "object" ? { grantModeId: action.grantModeId } : {}),
+    // The pre-existing byte-echo MUST (spec §7): the answer carries the
+    // ask's requestState verbatim when one exists.
+    ...(ask.requestState !== undefined ? { requestState: ask.requestState } : {}),
+  };
+  const verdict = validateHitlAnswer(ask, answer);
+  if (!verdict.ok) {
+    throw new Error(`buildHitlAnswer constructed an invalid answer (${verdict.code}): ${verdict.message}`);
+  }
+  return answer;
+}

package/src/index.ts

@@ -11,6 +11,7 @@
  * rendering, tests, and RN bundlers consume the view-model directly.
  */
 export {
+  newestViewKey,
   planTranscript,
 } from "./plan.js";
 export {
@@ -24,6 +25,13 @@ export {
   type ChatStrings,
 } from "./strings.js";
 export { transcriptInputsFromHistory } from "./history-inputs.js";
+export {
+  buildHitlAnswer,
+  grantModeDisplay,
+  hitlPromptsFromFold,
+  type HitlAnswerRecord,
+  type HitlPromptAction,
+} from "./hitl.js";
 export {
   DEFAULT_CHAT_THEME,
   GUUEY_CHAT_THEME,
@@ -32,6 +40,7 @@ export {
   resolveTheme,
 } from "./theme.js";
 export type {
+  ChatDebugEvent,
   CitationsItem,
   CodeItem,
   CompactionItem,
@@ -40,7 +49,12 @@ export type {
   ErrorItem,
   HistoryBoundaryItem,
   ItemKey,
+  HitlPromptInput,
+  HitlPromptItem,
   MediaItem,
+  NoticeItem,
+  ProfilePromptInput,
+  ProfilePromptItem,
   PromptItem,
   PromptItemInput,
   ReasoningItem,
@@ -55,4 +69,5 @@ export type {
   UnknownItem,
   UserMessageItem,
   ViewMountItem,
+  ViewRefItem,
 } from "./types.js";