@guuey/chat 0.7.2 → 0.8.1

package/src/corpus/drive.ts

@@ -5,8 +5,9 @@
  * `@silverprotocol/core` Reducer). Test-only plumbing — excluded from the
  * build; the 3b live/history assemblers are the production twins.
  */
-import { Reducer, type AgEvent } from "@silverprotocol/core";
+import { Reducer, type AgEvent, type AgPausedAsk } from "@silverprotocol/core";
 import type { InvokeTurnEvent } from "@guuey/agent-client";
+import { hitlPromptsFromFold, type HitlAnswerRecord } from "../hitl.js";
 import type { ProfilePromptInput, TranscriptInputs, TranscriptMessage } from "../types.js";
 
 export interface DriveOptions {
@@ -21,8 +22,10 @@ export interface DriveOptions {
   viewPhases?: TranscriptInputs["viewPhases"];
   historyCards?: TranscriptInputs["historyCards"];
   historyState?: TranscriptInputs["historyState"];
-  /** Resolve accumulated prompts to this state (fixture 4's answered leg). */
+  /** Resolve accumulated link prompts to this state. */
   promptState?: ProfilePromptInput["state"];
+  /** The host-side answer ledger for AgJSON hitl asks (fixture 4's answered leg). */
+  hitlAnswers?: Readonly<Record<string, HitlAnswerRecord>>;
 }
 
 export function driveTurn(events: InvokeTurnEvent[], opts: DriveOptions = {}): TranscriptInputs {
@@ -53,15 +56,6 @@ export function driveTurn(events: InvokeTurnEvent[], opts: DriveOptions = {}): T
         error = { message: ev.message, code: ev.code };
         status = "ready";
         break;
-      case "profile-consent":
-        prompts.push({
-          id: `consent-${prompts.length}`,
-          kind: "consent",
-          appId: ev.request.appId,
-          requested: ev.request.requested,
-          state: opts.promptState ?? "pending",
-        });
-        break;
       case "profile-link":
         prompts.push({
           id: `link-${prompts.length}`,
@@ -101,7 +95,9 @@ export function driveTurn(events: InvokeTurnEvent[], opts: DriveOptions = {}): T
     statusElapsedMs: opts.statusElapsedMs ?? 0,
     activeTool,
     error,
-    prompts,
+    // The link ledger + the AgJSON hitl asks lifted from the fold — the
+    // live assembler's exact composition (use-transcript.ts).
+    prompts: [...prompts, ...hitlPromptsFromFold(sawAgEvents ? reducer.result() : null, opts.hitlAnswers ?? {})],
     messages,
     ...(opts.sendStates !== undefined ? { sendStates: opts.sendStates } : {}),
     ...(opts.viewPhases !== undefined ? { viewPhases: opts.viewPhases } : {}),
@@ -180,5 +176,40 @@ export function frame(
   };
 }
 
+/**
+ * The runtime's cross-app profile consent ask (guuey#207) — the paused turn
+ * the pod appends AFTER the agent's own turn: `turn.start` → `hitl.ask` →
+ * `turn.done outcome:"paused"` carrying the same `AgPausedAsk`. Mirrors
+ * `nocode-runtime/src/profile-consent.ts` byte-for-byte in shape.
+ */
+export const CONSENT_ASK: AgPausedAsk = {
+  askId: "profile-consent:app-1:thread-corpus",
+  kind: "approval",
+  message: "Trip Planner wants to read your guuey profile — the notes agents keep about you across apps.",
+  grantModes: [
+    { id: "always", label: "Always allow", description: "Every conversation with this agent" },
+    { id: "once", label: "Allow this chat", description: "Only this conversation" },
+  ],
+  metadata: { appId: "app-1", requested: "read" },
+};
+export function consentTurn(next: () => number, ask: AgPausedAsk = CONSENT_ASK): AgEvent[] {
+  const turnId = `${ask.askId}#turn`;
+  return [
+    { type: "turn.start", threadId: THREAD, turnId, seq: next() },
+    {
+      type: "hitl.ask",
+      turnId,
+      askId: ask.askId,
+      kind: ask.kind,
+      ...(ask.message !== undefined ? { message: ask.message } : {}),
+      ...(ask.grantModes !== undefined ? { grantModes: ask.grantModes } : {}),
+      ...(ask.metadata !== undefined ? { metadata: ask.metadata } : {}),
+      continuation: "turn",
+      seq: next(),
+    },
+    { type: "turn.done", turnId, finishReason: "paused", outcome: { type: "paused", asks: [ask] }, seq: next() },
+  ];
+}
+
 export const session: InvokeTurnEvent = { kind: "session", threadId: THREAD };
 export const doneEvent: InvokeTurnEvent = { kind: "done", stopReason: "end_turn" };

package/src/corpus/fixtures.ts

@@ -13,6 +13,8 @@ import type { InvokeTurnEvent } from "@guuey/agent-client";
 import type { TranscriptInputs } from "../types.js";
 import {
   boot,
+  CONSENT_ASK,
+  consentTurn,
   doneEvent,
   driveTurn,
   frame,
@@ -81,17 +83,29 @@ export function coldStart(elapsedMs: number): TranscriptInputs {
   return driveTurn([], { userText: "hi", finalStatus: "connecting", statusElapsedMs: elapsedMs });
 }
 
-/** 4. consent-gate — R10 pending → answered collapse. */
+/**
+ * 4. consent-gate — R10 pending grant-mode card → answered one-line collapse.
+ * The pod's real shape (guuey#207): the agent turn runs WITHOUT the profile
+ * and closes, then the paused consent turn rides after it; the answered leg
+ * is the host ledger recording the picked mode (`resolved` + `always`).
+ */
 export function consentGate(state: "pending" | "answered"): TranscriptInputs {
   const s = seqSource();
   const events: InvokeTurnEvent[] = [
     session,
     frame(boot(s), { status: "thinking" }),
-    { kind: "profile-consent", request: { appId: "app-1", requested: "read" } },
-    frame(textPart(s, "x", "May I use your profile?"), { status: "responding", text: "May I use your profile?" }),
+    frame(textPart(s, "x", "Booked your usual — I couldn't see your profile yet."), {
+      status: "responding",
+      text: "Booked your usual — I couldn't see your profile yet.",
+    }),
+    frame([{ type: "message.end", id: "msg-corpus", seq: s() }, { type: "turn.done", turnId: "turn-corpus", finishReason: "stop", outcome: { type: "success" }, seq: s() }]),
+    frame(consentTurn(s)),
     doneEvent,
   ];
-  return driveTurn(events, { userText: "book my usual", promptState: state });
+  return driveTurn(events, {
+    userText: "book my usual",
+    ...(state === "answered" ? { hitlAnswers: { [CONSENT_ASK.askId]: { status: "resolved", grantModeId: "always" } } } : {}),
+  });
 }
 
 /** 5. bypass-text-only — plan identical to a silver stream carrying only text. */
@@ -627,6 +641,83 @@ export function prodWireGguiRender(): TranscriptInputs {
   return driveTurn(events, { userText: "show me the board" });
 }
 
+/**
+ * 25. oauth-auth-ask (guuey#178 Slice 4) — the MCP OAuth broker's "authorize
+ * this server" card: a paused turn whose PERSISTED ask is `kind:"auth"` with
+ * `authConfig:{ scheme:"oauth2", authorizationUrl }` + the two grant modes
+ * (the exact wire `nocode-runtime/src/mcp-oauth-consent.ts` emits — askId
+ * `mcp-oauth:<appId>:<serverName>:<threadId>`, `metadata:{appId, serverName,
+ * expiresAt}`, top-level `expiresAt`). Unlike family 20 there is NO answer
+ * door: a mode pick opens `authorizationUrl&mode=<id>&returnTo=<here>`; the
+ * decline is a dismissal ("Not now"). Driven through the real Reducer.
+ */
+export const OAUTH_ASK_AUTHORIZE_URL = "https://mcp.dev.sandbox.guuey.com/oauth/start?state=" + "a".repeat(64);
+export function oauthAuthAsk(): TranscriptInputs {
+  const reducer = new Reducer();
+  let seq = 0;
+  const s = (): number => seq++;
+  const askId = "mcp-oauth:app_1:linear:thread-oauth";
+  const events: AgEvent[] = [
+    { type: "turn.start", threadId: "thread-oauth", turnId: "turn-o", seq: s() },
+    { type: "message.start", id: "msg-o", role: "assistant", turnId: "turn-o", threadId: "thread-oauth", seq: s() },
+    { type: "text.start", id: "to", seq: s() },
+    { type: "text.delta", id: "to", delta: "I can't reach Linear yet.", seq: s() },
+    { type: "text.end", id: "to", seq: s() },
+    { type: "turn.done", turnId: "turn-o", outcome: { type: "success" }, seq: s() },
+    { type: "turn.start", threadId: "thread-oauth", turnId: `${askId}#turn`, seq: s() },
+    {
+      type: "hitl.ask",
+      turnId: `${askId}#turn`,
+      askId,
+      kind: "auth",
+      message: "Trip Planner wants to use your Linear account",
+      authConfig: { scheme: "oauth2", authorizationUrl: OAUTH_ASK_AUTHORIZE_URL },
+      grantModes: [
+        { id: "always", label: "Always allow", description: "Every conversation with this agent" },
+        { id: "once", label: "Allow this chat", description: "Only this conversation" },
+      ],
+      metadata: { appId: "app_1", serverName: "linear", expiresAt: "2026-08-17T10:10:00.000Z" },
+      expiresAt: "2026-08-17T10:10:00.000Z",
+      continuation: "turn",
+      seq: s(),
+    },
+    {
+      type: "turn.done",
+      turnId: `${askId}#turn`,
+      finishReason: "paused",
+      outcome: {
+        type: "paused",
+        asks: [
+          {
+            askId,
+            kind: "auth",
+            message: "Trip Planner wants to use your Linear account",
+            authConfig: { scheme: "oauth2", authorizationUrl: OAUTH_ASK_AUTHORIZE_URL },
+            grantModes: [
+              { id: "always", label: "Always allow", description: "Every conversation with this agent" },
+              { id: "once", label: "Allow this chat", description: "Only this conversation" },
+            ],
+            metadata: { appId: "app_1", serverName: "linear", expiresAt: "2026-08-17T10:10:00.000Z" },
+            expiresAt: "2026-08-17T10:10:00.000Z",
+          },
+        ],
+      },
+      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: "what's on my Linear board?" }],
+  };
+}
+
 /**
  * What ggui's `resources/read` answers for a render locator (guuey#209 C2):
  * the shell that boots ggui's runtime with the live-channel material

package/src/hitl.ts

@@ -19,6 +19,11 @@
  * 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.
+ *
+ * The first producer is the guuey runtime's cross-app profile consent
+ * (guuey#207): the pod appends a paused turn whose ask declares
+ * `grantModes: [always, once?]`; the host delivers the built answer through
+ * `@guuey/agent-client`'s `createHitlAnswerRelay` (`POST <pod>/agent/hitl-answer`).
  */
 import {
   validateHitlAnswer,

package/src/index.ts

@@ -32,6 +32,17 @@ export {
   type HitlAnswerRecord,
   type HitlPromptAction,
 } from "./hitl.js";
+export {
+  OAUTH_LINK_PARAMS,
+  OAUTH_RETURN_PARAMS,
+  OAUTH_SCHEME,
+  oauthAuthorizeAsk,
+  oauthAuthorizeHref,
+  parseOAuthReturn,
+  stripOAuthReturn,
+  type OAuthAuthorizeAsk,
+  type OAuthReturn,
+} from "./oauth.js";
 export {
   DEFAULT_CHAT_THEME,
   GUUEY_CHAT_THEME,

package/src/native/components.tsx

@@ -492,7 +492,9 @@ export function NativePrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
         <MutedText ctx={ctx}>
           {item.state === "resolved"
             ? item.chosenModeLabel !== null
-              ? s.promptAnsweredWith(item.chosenModeLabel)
+              ? item.oauth !== null
+                ? s.promptOAuthSent(item.chosenModeLabel)
+                : s.promptAnsweredWith(item.chosenModeLabel)
               : s.promptAccept
             : s.promptDeclinedRecord}
         </MutedText>
@@ -540,9 +542,17 @@ export function NativePrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
                   </Pressable>
                 ))
               )}
-              <Pressable accessibilityRole="button" onPress={() => ctx.onPromptAction?.(item, "decline")}>
-                <Text style={{ color: tokens.palette.inkMuted, fontSize: tokens.fontSize }}>{s.promptDecline}</Text>
-              </Pressable>
+              {/* The OAuth arm has no durable deny — "Not now" dismisses
+                  (nothing written; the ask re-emits next turn). */}
+              {item.oauth !== null ? (
+                <Pressable accessibilityRole="button" onPress={() => ctx.onPromptAction?.(item, "dismiss")}>
+                  <Text style={{ color: tokens.palette.inkMuted, fontSize: tokens.fontSize }}>{s.promptNotNow}</Text>
+                </Pressable>
+              ) : (
+                <Pressable accessibilityRole="button" onPress={() => ctx.onPromptAction?.(item, "decline")}>
+                  <Text style={{ color: tokens.palette.inkMuted, fontSize: tokens.fontSize }}>{s.promptDecline}</Text>
+                </Pressable>
+              )}
             </View>
           </>
         )}
@@ -565,9 +575,7 @@ export function NativePrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
       style={{ backgroundColor: tokens.palette.surface, borderRadius: tokens.radius, padding: tokens.pad, gap: 8 }}
     >
       <Text style={{ color: tokens.palette.ink, fontSize: tokens.fontSize, fontFamily: tokens.fontFamily }}>
-        {item.promptKind === "consent"
-          ? `${item.appId} requests ${item.requested} access`
-          : `Link your account to ${item.appId}`}
+        {`Link your account to ${item.appId}`}
       </Text>
       <View style={{ flexDirection: "row", gap: 12 }}>
         <Pressable accessibilityRole="button" onPress={() => ctx.onPromptAction?.(item, "accept")}>

package/src/oauth.ts

@@ -0,0 +1,157 @@
+/**
+ * The "authorize this server" arm of R10 (guuey#178 Slice 4) — the pure
+ * helpers every surface (web kit, widget, studio, portal native) uses for a
+ * `hitl.ask kind:"auth"` whose `authConfig.scheme` is `oauth2`.
+ *
+ * The producer is the guuey runtime's MCP OAuth broker: the pod appends a
+ * paused turn (`turn.done outcome:"paused"`) whose ask declares
+ * `authConfig:{ scheme:"oauth2", authorizationUrl }` + `grantModes:
+ * [always, once?]`. Unlike the profile-consent ask there is **no answer
+ * door**: the answer IS the redirect. Picking a mode opens
+ * `authorizationUrl` with two query params appended by THIS client —
+ *
+ *   - `mode=<grantModeId>` — the pre-chosen grant (recorded by the broker's
+ *     callback; the mode is fixed BEFORE the identity-provider hop), and
+ *   - `returnTo=<the surface's own location>` — where the broker 302s back
+ *     to when the dance ends (`?connected=<serverName>` on success,
+ *     `?error=<reason>` on failure). The broker allowlists it; the client
+ *     just says where it lives.
+ *
+ * On return the surface strips the two params, shows a one-line notice, and
+ * does nothing else: the NEXT turn's pre-turn preflight on the pod resolves
+ * `connected` (or asks again). No client-side state survives the redirect
+ * on purpose. "Not now" is a plain dismissal (`cancelled` — still pending,
+ * re-askable); nothing is written anywhere and the ask re-emits next turn.
+ *
+ * Everything here is string-level (no `URL`/`URLSearchParams`) so it runs
+ * identically on React Native, whose URL polyfill is partial.
+ */
+import type { AgPausedAsk } from "@silverprotocol/core";
+
+/** The `authConfig.scheme` this arm recognises (the spec's OAuth 2 vocabulary). */
+export const OAUTH_SCHEME = "oauth2";
+
+/** The query params THIS client appends to the authorize link. */
+export const OAUTH_LINK_PARAMS = { mode: "mode", returnTo: "returnTo" } as const;
+
+/** The query params the broker's callback appends to `returnTo`. */
+export const OAUTH_RETURN_PARAMS = { connected: "connected", error: "error" } as const;
+
+/** What an auth ask declares once narrowed to the OAuth arm. */
+export interface OAuthAuthorizeAsk {
+  authorizationUrl: string;
+  scopes: readonly string[];
+}
+
+/**
+ * Narrow an ask to the OAuth arm: `kind:"auth"` + `authConfig.scheme ===
+ * "oauth2"` + an `authorizationUrl` to open. Anything else (a plain
+ * approval, an auth ask with another scheme, a URL-less declaration) is
+ * `null` and renders as an ordinary hitl card.
+ */
+export function oauthAuthorizeAsk(ask: AgPausedAsk): OAuthAuthorizeAsk | null {
+  if (ask.kind !== "auth" || ask.authConfig === undefined) return null;
+  const { scheme, authorizationUrl, scopes } = ask.authConfig;
+  if (scheme !== OAUTH_SCHEME || authorizationUrl === undefined || authorizationUrl === "") return null;
+  return { authorizationUrl, scopes: scopes ?? [] };
+}
+
+/**
+ * The link to open for a mode pick: `authorizationUrl` + `&mode=<grantModeId>`
+ * + `&returnTo=<returnTo>` (each value URI-encoded; `?` vs `&` chosen from
+ * the URL as declared). `grantModeId` is required iff the ask declares
+ * modes (`null` = a plain accept on a mode-less auth ask — no `mode` param).
+ * Throws on a mode the ask did not declare — the inputs came from the
+ * declaration itself, so a mismatch is a construction bug, never a user
+ * state.
+ */
+export function oauthAuthorizeHref(ask: AgPausedAsk, grantModeId: string | null, returnTo: string): string {
+  const oauth = oauthAuthorizeAsk(ask);
+  if (oauth === null) throw new Error("oauthAuthorizeHref: the ask is not an oauth2 auth ask");
+  const declared = ask.grantModes ?? [];
+  if (grantModeId === null && declared.length > 0) {
+    throw new Error(`oauthAuthorizeHref: ${ask.askId} declares grant modes — a mode is required`);
+  }
+  if (grantModeId !== null && !declared.some((m) => m.id === grantModeId)) {
+    throw new Error(`oauthAuthorizeHref: grant mode "${grantModeId}" is not declared on ${ask.askId}`);
+  }
+  if (returnTo === "") throw new Error("oauthAuthorizeHref: returnTo is required");
+  const sep = oauth.authorizationUrl.includes("?") ? "&" : "?";
+  const mode = grantModeId === null ? "" : `${OAUTH_LINK_PARAMS.mode}=${encodeURIComponent(grantModeId)}&`;
+  return `${oauth.authorizationUrl}${sep}${mode}${OAUTH_LINK_PARAMS.returnTo}=${encodeURIComponent(returnTo)}`;
+}
+
+/** The broker's answer, lifted off the return location. */
+export type OAuthReturn =
+  | { kind: "connected"; serverName: string }
+  | { kind: "error"; reason: string };
+
+/** `decodeURIComponent` that yields the raw text for a malformed escape (a foreign param is not ours to fail on). */
+function safeDecode(s: string): string {
+  try {
+    return decodeURIComponent(s.replace(/\+/g, " "));
+  } catch {
+    return s;
+  }
+}
+
+/** Split a URL (or bare query) into its query pairs — RN-safe, no `URLSearchParams`. */
+function queryPairs(urlOrQuery: string): Array<[string, string]> {
+  const q = urlOrQuery.indexOf("?");
+  let query = q === -1 ? (urlOrQuery.startsWith("&") || !urlOrQuery.includes("=") ? "" : urlOrQuery) : urlOrQuery.slice(q + 1);
+  const hash = query.indexOf("#");
+  if (hash !== -1) query = query.slice(0, hash);
+  const pairs: Array<[string, string]> = [];
+  for (const part of query.split("&")) {
+    if (part === "") continue;
+    const eq = part.indexOf("=");
+    const k = eq === -1 ? part : part.slice(0, eq);
+    const v = eq === -1 ? "" : part.slice(eq + 1);
+    pairs.push([safeDecode(k), safeDecode(v)]);
+  }
+  return pairs;
+}
+
+/**
+ * Read the broker's return params off a location (a full URL, a deep link
+ * like `guuey://oauth/done?connected=linear`, or a bare `?connected=…`
+ * query). `null` when neither param is present. `connected` wins when both
+ * appear (the broker never sends both).
+ */
+export function parseOAuthReturn(urlOrQuery: string): OAuthReturn | null {
+  let connected: string | undefined;
+  let error: string | undefined;
+  for (const [k, v] of queryPairs(urlOrQuery)) {
+    if (k === OAUTH_RETURN_PARAMS.connected && v !== "") connected ??= v;
+    else if (k === OAUTH_RETURN_PARAMS.error && v !== "") error ??= v;
+  }
+  if (connected !== undefined) return { kind: "connected", serverName: connected };
+  if (error !== undefined) return { kind: "error", reason: error };
+  return null;
+}
+
+/**
+ * The same location with the broker's return params removed (every other
+ * param, and the hash, preserved). Idempotent; a URL without them is
+ * returned unchanged. This is what a surface writes back into its address
+ * bar (`history.replaceState`) so a reload never re-shows the notice — and
+ * what it passes as `returnTo` for the next dance.
+ */
+export function stripOAuthReturn(url: string): string {
+  const q = url.indexOf("?");
+  if (q === -1) return url;
+  const hashAt = url.indexOf("#", q);
+  const base = url.slice(0, q);
+  const hash = hashAt === -1 ? "" : url.slice(hashAt);
+  const query = hashAt === -1 ? url.slice(q + 1) : url.slice(q + 1, hashAt);
+  const kept = query
+    .split("&")
+    .filter((part) => {
+      if (part === "") return false;
+      const eq = part.indexOf("=");
+      const key = safeDecode(eq === -1 ? part : part.slice(0, eq));
+      return key !== OAUTH_RETURN_PARAMS.connected && key !== OAUTH_RETURN_PARAMS.error;
+    })
+    .join("&");
+  return kept === "" ? `${base}${hash}` : `${base}?${kept}${hash}`;
+}

package/src/plan.ts

@@ -41,6 +41,7 @@ import {
 } from "@guuey/mcp-apps-host";
 import type { TranscriptPolicy } from "./policy.js";
 import { grantModeDisplay } from "./hitl.js";
+import { oauthAuthorizeAsk } from "./oauth.js";
 import type {
   CitationsItem,
   DataResultItem,
@@ -838,7 +839,8 @@ export function planTranscript(
   }
 
   // R10 — prompts, in input order (narrow on `kind`: the guuey-wire
-  // profile arm vs the AgJSON hitl arm, spec draft.2).
+  // link-invite arm vs the AgJSON hitl arm — spec draft.2; consent rides
+  // hitl since guuey#207).
   for (const prompt of inputs.prompts) {
     const key = `p.${prompt.id}`;
     if (prompt.kind === "hitl") {
@@ -858,6 +860,7 @@ export function planTranscript(
         message: prompt.ask.message ?? null,
         askKind: prompt.ask.kind,
         grantModes: prompt.ask.grantModes ?? [],
+        oauth: oauthAuthorizeAsk(prompt.ask),
         state: prompt.state,
         chosenModeId: prompt.grantModeId ?? null,
         chosenModeLabel: chosen !== undefined ? grantModeDisplay(chosen) : null,

package/src/react/components.tsx

@@ -520,11 +520,15 @@ export function DefaultPrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
     // 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") {
+      // The OAuth arm's resolved record: the pick SENT the user to the
+      // provider (no answer door) — the grant lands on the next turn.
       return (
         <p className={`guuey-chat-prompt-record guuey-chat-prompt-${item.state}`}>
           {item.state === "resolved"
             ? item.chosenModeLabel !== null
-              ? s.promptAnsweredWith(item.chosenModeLabel)
+              ? item.oauth !== null
+                ? s.promptOAuthSent(item.chosenModeLabel)
+                : s.promptAnsweredWith(item.chosenModeLabel)
               : s.promptAccept
             : s.promptDeclinedRecord}
         </p>
@@ -570,9 +574,17 @@ export function DefaultPrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
                   </button>
                 ))
               )}
-              <button type="button" onClick={() => ctx.onPromptAction?.(item, "decline")}>
-                {s.promptDecline}
-              </button>
+              {/* The OAuth arm has no durable deny — "Not now" dismisses
+                  (nothing written; the ask re-emits next turn). */}
+              {item.oauth !== null ? (
+                <button type="button" onClick={() => ctx.onPromptAction?.(item, "dismiss")}>
+                  {s.promptNotNow}
+                </button>
+              ) : (
+                <button type="button" onClick={() => ctx.onPromptAction?.(item, "decline")}>
+                  {s.promptDecline}
+                </button>
+              )}
             </div>
           </>
         )}
@@ -588,11 +600,7 @@ export function DefaultPrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
   }
   return (
     <div className="guuey-chat-prompt" role="group">
-      <p className="guuey-chat-prompt-ask">
-        {item.promptKind === "consent"
-          ? `${item.appId} requests ${item.requested} access`
-          : `Link your account to ${item.appId}`}
-      </p>
+      <p className="guuey-chat-prompt-ask">{`Link your account to ${item.appId}`}</p>
       <div className="guuey-chat-prompt-actions">
         <button
           ref={firstAction}

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) => {