@guuey/chat 0.7.2 → 0.8.1

package/src/react/oauth-return.ts

@@ -0,0 +1,129 @@
+/**
+ * The web half of the OAuth "authorize this server" arm (guuey#178 Slice 4)
+ * — the DOM-touching pieces the pure `../oauth.js` helpers deliberately
+ * leave out. Every web surface (the `<GuueyChat>` composite, the widget, the
+ * studio agent page) shares these three so the redirect + return behave the
+ * same everywhere:
+ *
+ *   - {@link oauthReturnToHere} — the surface's own location, with a stale
+ *     `?connected=`/`?error=` from a PREVIOUS dance stripped, ready to be
+ *     the next `returnTo`.
+ *   - {@link openOAuthAuthorize} — how the link is opened: a top-level page
+ *     navigates in place (the broker 302s straight back to `returnTo`); a
+ *     FRAMED page (the widget inside a customer origin) opens a new tab,
+ *     because identity providers refuse to render inside a third-party
+ *     frame (`X-Frame-Options` / `frame-ancestors`).
+ *   - {@link useOAuthReturn} — on mount, read the broker's return params off
+ *     the address bar, REPLACE the URL without them (a reload never re-shows
+ *     the notice), and hand the surface a one-shot notice to render.
+ */
+import { useCallback, useEffect, useState } from "react";
+import type { AgHitlAnswer, AgPausedAsk } from "@silverprotocol/core";
+import type { HitlPromptAction } from "../hitl.js";
+import { oauthAuthorizeHref, parseOAuthReturn, stripOAuthReturn, type OAuthReturn } from "../oauth.js";
+import type { HitlPromptItem } from "../types.js";
+
+/** The surface's own location as the next `returnTo` (stale return params stripped). */
+export function oauthReturnToHere(): string {
+  return stripOAuthReturn(window.location.href);
+}
+
+/** The slice of `window` the opener touches (injectable — jsdom's `location.assign` cannot be spied). */
+export interface OAuthWindow {
+  self: object;
+  top: object | null;
+  open: (url: string, target: string, features: string) => unknown;
+  location: { assign: (url: string) => void };
+}
+
+/** Whether this document is rendered inside another origin's frame. */
+function isFramed(win: OAuthWindow): boolean {
+  try {
+    return win.top !== win.self;
+  } catch {
+    // A cross-origin `window.top` read throws in some browsers — that IS framed.
+    return true;
+  }
+}
+
+/**
+ * Open the authorize link. In place when top-level (the dance ends back on
+ * this page); a new tab when framed (the IdP will not render in a frame —
+ * `returnTo` then lands the SAME page top-level in that tab, where
+ * {@link useOAuthReturn} shows the notice; the embedded chat picks the
+ * connection up on its next turn).
+ */
+export function openOAuthAuthorize(href: string, win: OAuthWindow = window): void {
+  if (isFramed(win)) {
+    win.open(href, "_blank", "noopener,noreferrer");
+    return;
+  }
+  win.location.assign(href);
+}
+
+export interface UseOAuthReturnResult {
+  /** The broker's answer found on the address bar at mount, until dismissed. */
+  notice: OAuthReturn | null;
+  dismiss: () => void;
+}
+
+/**
+ * Read `?connected=<serverName>` / `?error=<reason>` off the current
+ * location ONCE (on mount), strip them from the address bar via
+ * `history.replaceState`, and expose the result as a dismissible notice.
+ * SSR-safe: nothing runs until the effect.
+ */
+export function useOAuthReturn(): UseOAuthReturnResult {
+  const [notice, setNotice] = useState<OAuthReturn | null>(null);
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const href = window.location.href;
+    const found = parseOAuthReturn(href);
+    if (found === null) return;
+    const clean = stripOAuthReturn(href);
+    if (clean !== href) window.history.replaceState(window.history.state, "", clean);
+    setNotice(found);
+  }, []);
+  const dismiss = useCallback(() => setNotice(null), []);
+  return { notice, dismiss };
+}
+
+export interface OAuthPromptActionArgs {
+  item: HitlPromptItem;
+  action: HitlPromptAction;
+  /** The kit's ledger (`useTranscriptInputs().answerHitlPrompt`) — records the pick locally; nothing is delivered. */
+  answerHitlPrompt: (ask: AgPausedAsk, action: HitlPromptAction) => AgHitlAnswer;
+  /** Where the broker should send the user back; defaults to {@link oauthReturnToHere}. */
+  returnTo?: string;
+  /** How to open the link; defaults to {@link openOAuthAuthorize}. */
+  open?: (href: string, ask: AgPausedAsk) => void;
+}
+
+/**
+ * The OAuth arm of a prompt action, shared by every web surface. Returns
+ * `false` (nothing done) when the item is not an OAuth ask, so a host's
+ * #207 hitl branch (build the answer, POST it to the pod door) runs as
+ * before. For an OAuth ask:
+ *
+ *   - a mode pick (or a plain accept on a mode-less ask) records the pick in
+ *     the ledger — the card shows "Connecting — <mode>" — and OPENS
+ *     `authorizationUrl&mode=<id>&returnTo=<here>`; NOTHING is posted to the
+ *     pod (there is no answer door — the answer is the redirect);
+ *   - "Not now" / decline / dismiss all record `cancelled` (still pending,
+ *     re-askable): nothing is written anywhere and the pod asks again next
+ *     turn.
+ */
+export function oauthPromptAction(args: OAuthPromptActionArgs): boolean {
+  const { item, action, answerHitlPrompt } = args;
+  if (item.oauth === null) return false;
+  if (typeof action === "object" || action === "accept") {
+    const grantModeId = typeof action === "object" ? action.grantModeId : null;
+    answerHitlPrompt(item.ask, action);
+    const href = oauthAuthorizeHref(item.ask, grantModeId, args.returnTo ?? oauthReturnToHere());
+    if (args.open !== undefined) args.open(href, item.ask);
+    else openOAuthAuthorize(href);
+    return true;
+  }
+  answerHitlPrompt(item.ask, "dismiss");
+  return true;
+}

package/src/react/use-transcript.ts

@@ -227,9 +227,9 @@ export interface UseTranscriptInputsResult {
    * 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).
+   * for the HOST to deliver — the kit renders and validates; the transport
+   * is the host's (`@guuey/agent-client`'s `createHitlAnswerRelay` posts it
+   * to `<pod>/agent/hitl-answer`, guuey#207).
    */
   answerHitlPrompt: (ask: AgPausedAsk, action: HitlPromptAction) => AgHitlAnswer;
 }
@@ -250,36 +250,12 @@ export function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscript
     return () => clearInterval(timer);
   }, [invoke.status]);
 
-  // R10 ledger: the hook exposes only the LATEST pending ask; the
-  // transcript keeps the record of every ask and its resolution.
+  // R10 ledger (the LINK invite): the hook exposes only the LATEST pending
+  // invite; the transcript keeps the record of every ask and its resolution.
+  // Consent is NOT ledgered here — it is an AgJSON paused turn in the fold
+  // (`hitlPromptsFromFold` below, guuey#207).
   const [prompts, setPrompts] = useState<ProfilePromptInput[]>([]);
   const promptSeq = useRef(0);
-  useEffect(() => {
-    const request = invoke.profileConsentRequest;
-    if (request === null) {
-      setPrompts((prev) =>
-        prev.some((p) => p.kind === "consent" && p.state === "pending")
-          ? prev.map((p) =>
-              p.kind === "consent" && p.state === "pending" ? { ...p, state: "dismissed" } : p,
-            )
-          : prev,
-      );
-      return;
-    }
-    setPrompts((prev) => {
-      if (prev.some((p) => p.kind === "consent" && p.state === "pending")) return prev;
-      return [
-        ...prev,
-        {
-          id: `consent.${promptSeq.current++}`,
-          kind: "consent",
-          appId: request.appId,
-          requested: request.requested,
-          state: "pending",
-        },
-      ];
-    });
-  }, [invoke.profileConsentRequest]);
   useEffect(() => {
     const request = invoke.profileLinkRequest;
     if (request === null) {
@@ -313,7 +289,6 @@ export function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscript
       // Clearing the hook's pending request AFTER the ledger moved keeps the
       // dismissal effect above from double-transitioning it.
       const pending = prompts.find((p) => p.id === id);
-      if (pending?.kind === "consent") invoke.clearProfileConsentRequest();
       if (pending?.kind === "link") invoke.clearProfileLinkRequest();
     },
     [invoke, prompts],

package/src/react.tsx

@@ -49,5 +49,14 @@ export {
   type UseTranscriptInputsResult,
 } from "./react/use-transcript.js";
 export { GuueyChat, type GuueyChatProps, type GuueyChatHandle } from "./react/guuey-chat.js";
+export {
+  oauthPromptAction,
+  oauthReturnToHere,
+  openOAuthAuthorize,
+  useOAuthReturn,
+  type OAuthPromptActionArgs,
+  type OAuthWindow,
+  type UseOAuthReturnResult,
+} from "./react/oauth-return.js";
 export { Markdown } from "./react/markdown.js";
 export { themeCssVars, type ThemeMode } from "./react/theme-css.js";

package/src/strings.ts

@@ -96,6 +96,16 @@ export interface ChatStrings {
   /** The answered record line, e.g. `Allowed — Always`. */
   promptAnsweredWith: (modeLabel: string) => string;
   promptDeclinedRecord: string;
+  /**
+   * The OAuth arm (guuey#178): the dismiss action ("Not now" — nothing is
+   * written, the ask re-emits next turn), the answered record (the user was
+   * sent to the provider), and the return notices the surface shows after
+   * the broker 302s back with `?connected=<serverName>` / `?error=<reason>`.
+   */
+  promptNotNow: string;
+  promptOAuthSent: (modeLabel: string) => string;
+  oauthConnected: (serverName: string) => string;
+  oauthFailed: (reason: string) => string;
 
   /** R16 — the notice row's label (provenance shows only under debug). */
   noticeLabel: string;
@@ -171,6 +181,10 @@ export const defaultChatStrings: ChatStrings = {
   promptDismissed: "Dismissed",
   promptAnsweredWith: (modeLabel) => `Allowed — ${modeLabel}`,
   promptDeclinedRecord: "Not allowed",
+  promptNotNow: "Not now",
+  promptOAuthSent: (modeLabel) => `Connecting — ${modeLabel}`,
+  oauthConnected: (serverName) => `Connected ${serverName}. The agent can use it from your next message.`,
+  oauthFailed: (reason) => `Couldn't connect: ${reason}`,
 
   noticeLabel: "Note",
 

package/src/types.ts

@@ -47,14 +47,17 @@ export interface TranscriptMessage {
 }
 
 /**
- * A pending/resolved consent or link ask (R10) — the turn-level
- * `profile-consent` / `profile-link` events lifted into renderable state.
- * The assembler (3b) accumulates these from `invokeTurn` events; `id` is
- * assembler-chosen and stable for the ask's lifetime.
+ * A pending/resolved account-LINK invite (R10) — the turn-level
+ * `profile-link` event lifted into renderable state. The assembler (3b)
+ * accumulates these from `invokeTurn` events; `id` is assembler-chosen and
+ * stable for the ask's lifetime. (Consent is NOT a profile arm any more:
+ * since guuey#207 the pod asks over AgJSON `hitl.ask` + `turn.done
+ * outcome:"paused"` with declared `grantModes`, and it renders through
+ * {@link HitlPromptInput}.)
  */
 export interface ProfilePromptInput {
   id: string;
-  kind: "consent" | "link";
+  kind: "link";
   appId: string;
   requested: "read" | "read-write";
   state: "pending" | "answered" | "declined" | "dismissed";
@@ -83,9 +86,9 @@ export interface HitlPromptInput {
 
 /**
  * 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.)
+ * profile arm is the guuey-wire LINK invite; `hitl` (spec draft.2) carries
+ * every AgJSON ask, consent included. (Direct un-narrowed reads of
+ * profile-only fields are the one shape this union retired — narrow first.)
  */
 export type PromptItemInput = ProfilePromptInput | HitlPromptInput;
 
@@ -117,7 +120,7 @@ export interface TranscriptInputs {
   statusElapsedMs: number;
   activeTool: string | null;
   error: { message: string; code: string | null } | null;
-  /** Pending/answered consent + link asks (R10). */
+  /** Pending/answered asks (R10): the link invite + AgJSON hitl asks (consent). */
   prompts: PromptItemInput[];
   /**
    * The settled conversation, both roles, in order. Assistant entries are
@@ -320,12 +323,12 @@ export interface CitationsItem extends BaseItem {
   style: "chips" | "list";
 }
 
-/** R10 — the guuey-wire consent/link prompt card (the original arm). */
+/** R10 — the guuey-wire account-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;
-  promptKind: "consent" | "link";
+  promptKind: "link";
   appId: string;
   requested: "read" | "read-write";
   state: "pending" | "answered" | "declined" | "dismissed";
@@ -352,6 +355,14 @@ export interface HitlPromptItem extends BaseItem {
   askKind: AgPausedAsk["kind"];
   /** Declared accept variants; empty = a plain accept/decline ask. */
   grantModes: readonly AgGrantMode[];
+  /**
+   * The OAuth arm (guuey#178): set when the ask is `kind:"auth"` with
+   * `authConfig.scheme:"oauth2"` + an `authorizationUrl`. There is no
+   * answer door for this ask — a mode pick OPENS `authorizationUrl` with
+   * `&mode=` + `&returnTo=` appended (`oauthAuthorizeHref`); "Not now" is a
+   * plain dismissal. `null` for every other ask.
+   */
+  oauth: { authorizationUrl: string; scopes: readonly string[] } | null;
   state: "pending" | "resolved" | "declined" | "cancelled";
   /** Echo of the chosen mode id (identity, never displayed as meaning). */
   chosenModeId: string | null;

package/styles.css

@@ -349,6 +349,32 @@
   margin: 0;
 }
 
+/* The OAuth "authorize this server" return notice (guuey#178) — shown by
+   <GuueyChat> after the broker sends the user back with ?connected= / ?error=. */
+.guuey-chat-oauth-notice {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin: 0;
+  padding: 8px 12px;
+  font-size: 0.85em;
+  color: var(--guuey-chat-ink);
+  background: color-mix(in srgb, var(--guuey-chat-accent) 10%, var(--guuey-chat-surface));
+  border-top: 1px solid var(--guuey-chat-canvas-muted);
+}
+.guuey-chat-oauth-error {
+  background: color-mix(in srgb, var(--guuey-chat-error) 7%, var(--guuey-chat-surface));
+}
+.guuey-chat-oauth-dismiss {
+  font: inherit;
+  cursor: pointer;
+  border: 0;
+  background: transparent;
+  color: var(--guuey-chat-ink-muted);
+  text-decoration: underline;
+}
+
 /* ── R11 errors ── */
 .guuey-chat-error {
   border: 1px solid color-mix(in srgb, var(--guuey-chat-error) 45%, transparent);