@guuey/chat 0.8.0 → 0.8.1

package/src/react/guuey-chat.tsx

@@ -71,6 +71,7 @@ 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";
+import { oauthPromptAction, useOAuthReturn } from "./oauth-return.js";
 
 /**
  * The imperative seam (guuey#210): programmatic send/prefill/focus for
@@ -177,6 +178,20 @@ export interface GuueyChatProps {
    * transport). Fired after the transcript record moves.
    */
   onHitlAnswer?: (answer: AgHitlAnswer, ask: AgPausedAsk) => void;
+  /**
+   * The OAuth "authorize this server" arm (guuey#178): where the broker
+   * sends the user back after the provider dance. Defaults to this page's
+   * own location (stale return params stripped). Pass a value when the
+   * chat lives at a URL that is not where the user should land.
+   */
+  oauthReturnTo?: string;
+  /**
+   * How the authorize link is opened. Defaults to `openOAuthAuthorize`
+   * (in-place navigation; a new tab when framed). The composite ALSO shows
+   * the return notice itself (`useOAuthReturn`) — a host that overrides
+   * `open` and lands elsewhere renders its own.
+   */
+  onOAuthAuthorize?: (href: string, ask: AgPausedAsk) => void;
   /** R11 action slot (sign-in / retry affordances). */
   onErrorAction?: (item: ErrorItem) => void;
   /**
@@ -226,6 +241,8 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
     viewProps,
     onPromptAction,
     onHitlAnswer,
+    oauthReturnTo,
+    onOAuthAuthorize,
     onErrorAction,
     onReady,
     onThread,
@@ -388,9 +405,27 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
     [invoke],
   );
 
+  // guuey#178: the broker's return notice (`?connected=` / `?error=`), read
+  // + stripped off the address bar once on mount.
+  const oauthReturn = useOAuthReturn();
+
   const handlePromptAction = useCallback(
     (item: PromptItem, action: "accept" | "decline" | "dismiss" | { grantModeId: string }) => {
       if (item.promptKind === "hitl") {
+        // The OAuth arm: the answer is the redirect (no pod door, no
+        // `onHitlAnswer`); the ledger records the pick and the link opens.
+        if (
+          oauthPromptAction({
+            item,
+            action,
+            answerHitlPrompt,
+            ...(oauthReturnTo !== undefined ? { returnTo: oauthReturnTo } : {}),
+            ...(onOAuthAuthorize !== undefined ? { open: onOAuthAuthorize } : {}),
+          })
+        ) {
+          onPromptAction?.(item, action);
+          return;
+        }
         const answer = answerHitlPrompt(
           item.ask,
           typeof action === "object" ? action : action === "accept" ? "accept" : action,
@@ -404,7 +439,7 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
       if (typeof action !== "object") resolvePrompt(item.promptId, PROMPT_STATE[action]);
       onPromptAction?.(item, action);
     },
-    [resolvePrompt, answerHitlPrompt, onHitlAnswer, onPromptAction],
+    [resolvePrompt, answerHitlPrompt, onHitlAnswer, onPromptAction, oauthReturnTo, onOAuthAuthorize],
   );
 
   const strings = policy.strings;
@@ -430,6 +465,19 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
         onViewDiagnosis={onViewDiagnosis}
         {...(viewProps !== undefined ? { viewProps } : {})}
       />
+      {oauthReturn.notice !== null && (
+        <p
+          role="status"
+          className={`guuey-chat-oauth-notice guuey-chat-oauth-${oauthReturn.notice.kind}`}
+        >
+          {oauthReturn.notice.kind === "connected"
+            ? strings.oauthConnected(oauthReturn.notice.serverName)
+            : strings.oauthFailed(oauthReturn.notice.reason)}
+          <button type="button" className="guuey-chat-oauth-dismiss" onClick={oauthReturn.dismiss}>
+            {strings.promptDismissed}
+          </button>
+        </p>
+      )}
       <form
         className="guuey-chat-composer"
         onSubmit={(e) => {

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.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

@@ -355,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);