@guuey/chat 0.5.0 → 0.6.0

package/src/types.ts

@@ -11,7 +11,14 @@
  * events. A category this UI needs but AgJSON cannot express is an upstream
  * silverprotocol change, never a guuey-side extension.
  */
-import type { AgReduceResult, AgSource, JsonValue } from "@silverprotocol/core";
+import type {
+  AgGrantMode,
+  AgNoticeSource,
+  AgPausedAsk,
+  AgReduceResult,
+  AgSource,
+  JsonValue,
+} from "@silverprotocol/core";
 import type { AgentInvokeStatus, HistoryCard } from "@guuey/agent-client";
 import type { ViewHostPhase, ViewMount, ViewMountChannel } from "@guuey/mcp-apps-host";
 
@@ -20,12 +27,18 @@ import type { ViewHostPhase, ViewMount, ViewMountChannel } from "@guuey/mcp-apps
  * compatible with the hook's `AgentMessage`, plus the optional
  * `clientMessageId` the R0 send-lifecycle join needs (the 3b live assembler
  * threads it through; history entries and older callers simply omit it).
+ *
+ * `role: "notice"` (spec draft.2, silverprotocol#16) is a host/adapter/
+ * framework-injected session annotation — a PEER of user/assistant rows,
+ * never assistant content. `noticeSource` is its provenance label (R16).
  */
 export interface TranscriptMessage {
-  role: "user" | "assistant";
+  role: "user" | "assistant" | "notice";
   text: string;
   /** Present on live-sent user turns — the `sendStates` join key (R0). */
   clientMessageId?: string;
+  /** R16 provenance — meaningful only when `role === "notice"`. */
+  noticeSource?: AgNoticeSource;
 }
 
 /**
@@ -34,7 +47,7 @@ export interface TranscriptMessage {
  * The assembler (3b) accumulates these from `invokeTurn` events; `id` is
  * assembler-chosen and stable for the ask's lifetime.
  */
-export interface PromptItemInput {
+export interface ProfilePromptInput {
   id: string;
   kind: "consent" | "link";
   appId: string;
@@ -42,9 +55,49 @@ export interface PromptItemInput {
   state: "pending" | "answered" | "declined" | "dismissed";
 }
 
+/**
+ * An AgJSON HITL ask (spec draft.2, silverprotocol#16) lifted from the
+ * fold's PERSISTED declaration — the `AgPausedAsk` record in
+ * `turn.done.outcome:"paused".asks[]` (the ask event itself is live-only;
+ * the paused record is what a late-joining client renders from). Produced
+ * by `hitlPromptsFromFold`; `id === ask.askId`.
+ *
+ * States encode guuey's ratified dismissal ruling (issue #16): `cancelled`
+ * is still-pending-and-re-askable (the card stays answerable), `declined`
+ * is the durable explicit deny.
+ */
+export interface HitlPromptInput {
+  id: string;
+  kind: "hitl";
+  /** The persisted declaration — message, kind, and any declared grantModes. */
+  ask: AgPausedAsk;
+  state: "pending" | "resolved" | "declined" | "cancelled";
+  /** Echo of the chosen declared mode; present iff `state === "resolved"`. */
+  grantModeId?: string;
+}
+
+/**
+ * R10 prompt inputs — a discriminated union (narrow on `kind`). The
+ * profile arm is the original guuey-wire shape unchanged; `hitl` arrived
+ * with spec draft.2. (Direct un-narrowed reads of profile-only fields are
+ * the one shape this union retired — narrow first.)
+ */
+export type PromptItemInput = ProfilePromptInput | HitlPromptInput;
+
 /** Everything the plan derives from. All fields are data — no clocks, no DOM. */
 export interface TranscriptInputs {
-  /** The Reducer's fold (silver mode); null on bypass-frame streams. */
+  /**
+   * The Reducer's fold (silver mode); null on bypass-frame streams.
+   *
+   * TURN-SCOPED (guuey#135 kit refinement): the fold owns the TRAILING
+   * assistant turns it covers — its settled sources replace that many
+   * trailing flat assistant entries, and any earlier flat entries (a
+   * rehydrated/persisted prefix the session's Reducer never saw) render as
+   * text in front. A fold spanning the whole conversation plans exactly as
+   * before, so pure-live sessions are unaffected; persisted-overlay hosts
+   * (portal's thread views) can now pass the session fold beside their
+   * persisted rows instead of nulling it.
+   */
   result: AgReduceResult | null;
   /**
    * The in-flight turn's cumulative text fold (ALWAYS present; the sole
@@ -75,6 +128,19 @@ export interface TranscriptInputs {
   sendStates?: Readonly<Record<string, "sending" | "failed">>;
   /** mountKey → live phase (R6 states). Keys match `ViewMountItem.key`. */
   viewPhases?: Readonly<Record<string, ViewHostPhase>>;
+  /**
+   * The mount key a host-owned stage/canvas surface currently shows
+   * (guuey#204 "promote and reference") — renderer-supplied state, like
+   * `sendStates`. When set, the plan emits a compact {@link ViewRefItem}
+   * in that mount's transcript slot instead of the full
+   * {@link ViewMountItem}, so an interactive surface exists exactly ONCE.
+   * Absent (or matching nothing / an expired mount) = today's behavior —
+   * every mount renders inline. Hosts derive the key with
+   * {@link newestViewKey} rather than hand-building it; the issue's
+   * phase-2 (every card a chip, click-to-swap) is this same field set per
+   * host click, no further plan changes.
+   */
+  promotedViewKey?: string;
   /** The last turn ended by user abort (R1 aborted-partial + "Stopped."). */
   aborted?: boolean;
   /**
@@ -195,6 +261,21 @@ export interface ViewMountItem extends BaseItem {
   actionScope: string | null;
 }
 
+/**
+ * R6's "promote and reference" chip (guuey#204): stands in for the ONE
+ * {@link ViewMountItem} a host's stage/canvas currently shows
+ * (`TranscriptInputs.promotedViewKey`), so the interactive surface exists
+ * exactly once. `key` is the replaced mount's key — overrides and phase
+ * reports keep their identity if the item swaps back to a full mount.
+ */
+export interface ViewRefItem extends BaseItem {
+  kind: "viewRef";
+  /** The display title (the producing call's, or the strings fallback). */
+  title: string;
+  /** The full resolved chip text (`strings.viewPromoted(title)`). */
+  label: string;
+}
+
 /** R7 — media blocks. */
 export interface MediaItem extends BaseItem {
   kind: "media";
@@ -220,8 +301,8 @@ export interface CitationsItem extends BaseItem {
   style: "chips" | "list";
 }
 
-/** R10 — a consent/link prompt card. */
-export interface PromptItem extends BaseItem {
+/** R10 — the guuey-wire consent/link prompt card (the original arm). */
+export interface ProfilePromptItem extends BaseItem {
   kind: "prompt";
   /** The `PromptItemInput.id` this row records — the host's resolution key. */
   promptId: string;
@@ -233,6 +314,50 @@ export interface PromptItem extends BaseItem {
   raw: JsonValue | null;
 }
 
+/**
+ * R10 — an AgJSON HITL ask card (spec draft.2). Display keys off each
+ * mode's `label`/`description` ONLY — ids are echo-only identity, and
+ * mode SEMANTICS are asker-scoped (normative: never hard-code meaning
+ * onto an id string). `cancelled` renders as a dismissed record that is
+ * still answerable when expanded (guuey's re-askable ruling); `declined`
+ * and `resolved` are settled records.
+ */
+export interface HitlPromptItem extends BaseItem {
+  kind: "prompt";
+  promptId: string;
+  promptKind: "hitl";
+  /** The persisted declaration — carried so answer construction/validation has the record. */
+  ask: AgPausedAsk;
+  /** The asker's message, when it sent one. */
+  message: string | null;
+  askKind: AgPausedAsk["kind"];
+  /** Declared accept variants; empty = a plain accept/decline ask. */
+  grantModes: readonly AgGrantMode[];
+  state: "pending" | "resolved" | "declined" | "cancelled";
+  /** Echo of the chosen mode id (identity, never displayed as meaning). */
+  chosenModeId: string | null;
+  /** Resolved display text for the chosen mode (label, else the id as literal text). */
+  chosenModeLabel: string | null;
+  /** Raw ask payload, populated only under the debug policy. */
+  raw: JsonValue | null;
+}
+
+/** R10 union — narrow on `promptKind`. */
+export type PromptItem = ProfilePromptItem | HitlPromptItem;
+
+/**
+ * R16 — a `role:"notice"` session annotation (spec draft.2): a labeled,
+ * NON-conversational row that must never read as agent-authored.
+ */
+export interface NoticeItem extends BaseItem {
+  kind: "notice";
+  text: string;
+  /** Provenance facet; null when the producer omitted it. */
+  source: AgNoticeSource | null;
+  /** Resolved provenance display — the facet verbatim under debug, else null. */
+  sourceLabel: string | null;
+}
+
 /** R11 — a coded, human-worded error notice. */
 export interface ErrorItem extends BaseItem {
   kind: "error";
@@ -281,10 +406,12 @@ export type DisplayItem =
   | ToolGroupItem
   | DataResultItem
   | ViewMountItem
+  | ViewRefItem
   | MediaItem
   | CodeItem
   | CitationsItem
   | PromptItem
+  | NoticeItem
   | ErrorItem
   | HistoryBoundaryItem
   | CompactionItem
@@ -306,6 +433,25 @@ export interface StatusLineItem {
   detail: string | null;
 }
 
+/**
+ * The debug sink's event union (spec §5's `onDebugEvent`, shipped as real
+ * API in the #135 refinement wave) — built strictly from what the kit
+ * actually knows, never invented telemetry:
+ *
+ *  - `view-phase`: an R6 mount's host-phase transition (incl. the R13
+ *    `expired` verdict from a failed locator resolution);
+ *  - `unknown-block`: an R15 sighting — a block type this kit version does
+ *    not know rendered as a labeled row;
+ *  - `turn-recovered`: the #192 adopted-turn marker resolved on the plan.
+ *
+ * The sink only fires under the debug policy (`debugDetail`) — `calm`
+ * ignores it by design (spec §5's per-preset row).
+ */
+export type ChatDebugEvent =
+  | { type: "view-phase"; key: ItemKey; phase: ViewHostPhase | "expired" }
+  | { type: "unknown-block"; key: ItemKey; typeName: string; byteSize: number }
+  | { type: "turn-recovered"; marker: string };
+
 export interface TranscriptPlan {
   /** Ordered, stable keys (spec §7's determinism contract). */
   items: DisplayItem[];

package/styles.css

@@ -241,6 +241,27 @@
   font-size: 0.78em;
   border-top: 1px solid color-mix(in srgb, var(--guuey-chat-ink) 6%, transparent);
 }
+/* guuey#204: the promoted-view reference chip — compact, never a frame. */
+.guuey-chat-view-ref {
+  display: inline-block;
+  margin: 0;
+  padding: 6px 12px;
+  border: 1px solid color-mix(in srgb, var(--guuey-chat-ink) 12%, transparent);
+  border-radius: 999px;
+  background: var(--guuey-chat-surface);
+  color: var(--guuey-chat-ink-muted);
+  font-size: 0.85em;
+  line-height: 1.2;
+}
+.guuey-chat-view-ref-button {
+  cursor: pointer;
+  font: inherit;
+  font-size: 0.85em;
+}
+.guuey-chat-view-ref-button:hover {
+  color: var(--guuey-chat-ink);
+  border-color: color-mix(in srgb, var(--guuey-chat-ink) 24%, transparent);
+}
 
 /* ── R7 media ── */
 .guuey-chat-media-image img {