@guuey/agent-client 0.7.1 → 0.8.0

package/dist/web-adapters.js

@@ -135,6 +135,16 @@ export function __resetReaderEndpointWarning() {
 function toUiResourceUrl(endpointUrl) {
     return toInvokeUrl(endpointUrl).replace(/\/agent\/invoke$/, "/agent/ui-resource");
 }
+/** `<pod base>/agent/ui-action` — the live ACTION door (guuey#222), the read door's twin. */
+function toUiActionUrl(endpointUrl) {
+    return toInvokeUrl(endpointUrl).replace(/\/agent\/invoke$/, "/agent/ui-action");
+}
+/** Warn once per module load — sibling of the reader's flag; per-surface, not per-click. */
+let relayEndpointWarned = false;
+/** @internal test seam — the once-flag is module state; suites reset it between cases. */
+export function __resetRelayEndpointWarning() {
+    relayEndpointWarned = false;
+}
 /**
  * Build a `UiResourceReader` over guuey's authenticated resources/read
  * doors — the pod door for LIVE turns (guuey#209 C1:
@@ -261,8 +271,37 @@ export function createUiResourceReader(options) {
  */
 export function createUiActionRelay(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
-    const callTool = async (uri, name, args) => {
+    // A platform door without a pod door is almost always a live surface
+    // that forgot `endpointUrl` — its cards' clicks would go nowhere for the
+    // whole mid-turn window (guuey#222). `null` is the explicit "history-only
+    // viewer, there is no pod" opt-out; `undefined` is the forgotten case.
+    if (options.endpointUrl === undefined && !relayEndpointWarned) {
+        relayEndpointWarned = true;
+        console.warn("createUiActionRelay: no `endpointUrl` — a click on a card produced mid-turn cannot reach the agent until the turn completes (the pod door is the only authority while a turn streams; post-turn clicks reach the platform door). Pass the surface's invoke endpoint, or `endpointUrl: null` to declare a history-only viewer.");
+    }
+    /**
+     * One door: POST + the reader's 401-forceRefresh recovery. Returns the
+     * parsed result on 2xx, `"miss"` on 404 (the pod's "not live / not yours /
+     * past grace" — deny==miss, so the NEXT door may still answer), and
+     * `undefined` for every other failure (terminal: the host relay answers
+     * in-band as an `isError` result, never a thrown error into the sandbox
+     * bridge). A pod 502 UPSTREAM_UNAVAILABLE is a real failure, not a miss —
+     * the persisted door cannot relay a mid-turn click either, so falling
+     * through would only trade one honest error for a misleading 404.
+     */
+    const postDoor = async (requestUrl, body) => {
+        // Exactly ONE identity carrier per call — the reader's rule verbatim:
+        // bearer → guest header → else cookie credentials (the HttpOnly
+        // `guuey_guest` cookie the pod mints for anonymous browser callers).
+        // Without the third arm a cookie-mode guest POSTed identity-less and
+        // every click failed auth (the guuey#221 class, on the relay). A JSON
+        // POST is always preflighted, so unlike the reader's GET this arm can
+        // never be a CORS "simple request" — which is fine because both doors
+        // answer a credentialed preflight: the pod echoes origin +
+        // `Access-Control-Allow-Credentials` on OPTIONS and every status, and
+        // the platform door's own OPTIONS branch does the same (guuey#224).
         const headers = { "content-type": "application/json" };
+        const init = { method: "POST", headers, body };
         const token = options.getAccessToken ? await options.getAccessToken() : null;
         const guest = sendableGuestSecret(options.guestSecret);
         if (token) {
@@ -271,17 +310,19 @@ export function createUiActionRelay(options) {
         else if (guest) {
             headers[GUEST_HEADER] = guest;
         }
-        const requestUrl = `${options.apiBaseUrl}/threads/${encodeURIComponent(options.threadId)}/ui-action`;
-        const body = JSON.stringify({ uri, name, ...(args !== undefined ? { arguments: args } : {}) });
+        else {
+            init.credentials = "include";
+        }
         let res;
         try {
-            res = await fetchImpl(requestUrl, { method: "POST", headers, body });
+            res = await fetchImpl(requestUrl, init);
         }
         catch {
             return undefined; // transport failure — the host relay answers in-band
         }
         // One forceRefresh retry on 401 with a bearer in play — the same
-        // expired-but-refreshable recovery the reader performs.
+        // expired-but-refreshable recovery the reader performs. The retry
+        // carries the fresh bearer and nothing else (same one-carrier rule).
         if (res.status === 401 && options.getAccessToken) {
             const fresh = await options.getAccessToken({ forceRefresh: true }).catch(() => null);
             if (fresh) {
@@ -297,14 +338,120 @@ export function createUiActionRelay(options) {
                 }
             }
         }
+        if (res.status === 404)
+            return "miss";
         if (!res.ok)
             return undefined;
         try {
-            return (await res.json());
+            return { kind: "result", value: (await res.json()) };
         }
         catch {
             return undefined;
         }
     };
+    const podUrl = options.endpointUrl ? toUiActionUrl(options.endpointUrl) : null;
+    const callTool = async (uri, name, args) => {
+        // The kit sends only what the click carries; the pod overwrites any
+        // sessionId/appId from the authorized locator + its own binding.
+        const body = JSON.stringify({ uri, name, ...(args !== undefined ? { arguments: args } : {}) });
+        if (podUrl !== null) {
+            const live = await postDoor(podUrl, body);
+            if (live === undefined)
+                return undefined; // terminal on the pod — no fall-through
+            if (live !== "miss")
+                return live.value;
+            // 404 → not live here (completed turn past grace, or never live):
+            // the persisted door owns it.
+        }
+        const persisted = await postDoor(`${options.apiBaseUrl}/threads/${encodeURIComponent(options.threadId)}/ui-action`, body);
+        return persisted === undefined || persisted === "miss" ? undefined : persisted.value;
+    };
     return createMcpUiActionRelay({ callTool });
 }
+/** `<pod base>/agent/hitl-answer` — the AgJSON HITL answer door (guuey#207). */
+function toHitlAnswerUrl(endpointUrl) {
+    return toInvokeUrl(endpointUrl).replace(/\/agent\/invoke$/, "/agent/hitl-answer");
+}
+/**
+ * Build the client→pod channel for AgJSON HITL answers (guuey#207): `POST
+ * <pod>/agent/hitl-answer` with the spec {@link AgHitlAnswer} the kit's
+ * `answerHitlPrompt` constructed (already validated against the ask's
+ * persisted declaration). The pod owns EVERYTHING trust-shaped — caller
+ * identity (the same three families as the invoke), which ask it minted,
+ * the thread a `once` grant binds to, the access level written — this
+ * transport only carries the surface's existing credential under the
+ * one-carrier rule (bearer → guest header → cookie), with the card relays'
+ * single 401 forceRefresh retry.
+ *
+ * Today the only producer is the pod's cross-app profile consent ask (the
+ * three-mode grant), whose answer resolves into the caller's own
+ * `ProfileGrant` row; the channel is generic by construction — any future
+ * `hitl.ask` the runtime emits is answered through this same door.
+ */
+export function createHitlAnswerRelay(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const url = toHitlAnswerUrl(options.endpointUrl);
+    return async (answer) => {
+        const headers = { "content-type": "application/json" };
+        const body = JSON.stringify(answer);
+        const init = { method: "POST", headers, body };
+        const token = options.getAccessToken ? await options.getAccessToken() : null;
+        const guest = sendableGuestSecret(options.guestSecret);
+        if (token) {
+            headers["authorization"] = `Bearer ${token}`;
+        }
+        else if (guest) {
+            headers[GUEST_HEADER] = guest;
+        }
+        else {
+            init.credentials = "include";
+        }
+        let res;
+        try {
+            res = await fetchImpl(url, init);
+        }
+        catch (err) {
+            return { ok: false, status: 0, code: null, message: err instanceof Error ? err.message : String(err) };
+        }
+        if (res.status === 401 && options.getAccessToken) {
+            const fresh = await options.getAccessToken({ forceRefresh: true }).catch(() => null);
+            if (fresh) {
+                try {
+                    res = await fetchImpl(url, {
+                        method: "POST",
+                        headers: { ...headers, authorization: `Bearer ${fresh}` },
+                        body,
+                    });
+                }
+                catch (err) {
+                    return { ok: false, status: 0, code: null, message: err instanceof Error ? err.message : String(err) };
+                }
+            }
+        }
+        let parsed = undefined;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (res.ok) {
+            const b = (parsed ?? {});
+            return {
+                ok: true,
+                body: {
+                    askId: typeof b.askId === "string" ? b.askId : answer.askId,
+                    status: b.status === "resolved" || b.status === "declined" || b.status === "cancelled" ? b.status : answer.status,
+                    ...(typeof b.mode === "string" ? { mode: b.mode } : {}),
+                },
+            };
+        }
+        const env = (parsed ?? {});
+        return {
+            ok: false,
+            status: res.status,
+            code: typeof env.code === "string" ? env.code : null,
+            message: typeof env.message === "string" ? env.message : `hitl-answer failed (${res.status})`,
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/agent-client",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Client SDK for Guuey's agent runtime: the `useAgentInvoke` React hook + pure SSE helpers that speak the /agent/invoke streaming contract, plus the paginated thread-history read plane. Host adapters (storage / id / transport) are injected, so it runs on web (Next) and React Native alike.",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@silverprotocol/core": "0.5.0",
-    "@guuey/mcp-apps-host": "0.7.1"
+    "@guuey/mcp-apps-host": "0.8.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/error-codes.ts

@@ -53,6 +53,12 @@ export const AGENT_ERROR_CODES = {
   DRAINING: "DRAINING",
   /** Refused for this caller — e.g. the link-prompt dismiss route's byo-only rule. */
   FORBIDDEN: "FORBIDDEN",
+  /**
+   * The consent-answer door's deny==miss (guuey#207): the `AgHitlAnswer` names
+   * an ask this pod did not mint (wrong app, a thread the caller does not
+   * own, or a pod that takes no profile consent). Never an existence oracle.
+   */
+  NOT_FOUND: "NOT_FOUND",
   /** The turn ran past the pod's wall-clock budget. */
   TIMEOUT: "TIMEOUT",
   /** A guuey-side dependency failed (not the agent's own code). */

package/src/index.ts

@@ -3,7 +3,6 @@ export {
   extractAssistantText,
   reduceAssistantText,
   stringField,
-  parseConsentRequest,
   parseLinkRequest,
   type ParsedSseEvent,
 } from "./sse.js";
@@ -12,6 +11,9 @@ export { dismissLinkPrompt } from "./link-prompt.js";
 // wraps, for hosts that drive their own turn state machine (guuey#186 G5).
 export { invokeTurn, toInvokeUrl, type InvokeTurnEvent } from "./invoke-turn.js";
 export {
+  createHitlAnswerRelay,
+  type CreateHitlAnswerRelayOptions,
+  type HitlAnswerRelayResult,
   createUiActionRelay,
   type CreateUiActionRelayOptions,
   createUiResourceReader,
@@ -74,11 +76,20 @@ export { sortHistoryCards, toolNameFor } from "./history.js";
 // host folding `invokeTurn`'s agEvents outside the hook builds its transcript
 // on the same terms (the types alone forced the direct dep back, guuey#186 G4).
 export { Reducer } from "@silverprotocol/core";
-export type { AgEvent, AgReduceResult, AgMessage, AgBlock } from "@silverprotocol/core";
+export type {
+  AgEvent,
+  AgReduceResult,
+  AgMessage,
+  AgBlock,
+  // The client→pod capability advertisement + the HITL answer the relay
+  // delivers (guuey#207) — re-exported so a host names them without a direct
+  // `@silverprotocol/core` import.
+  AgClientCapabilities,
+  AgHitlAnswer,
+} from "@silverprotocol/core";
 export type {
   AgentMessage,
   HistoryCard,
-  ProfileConsentRequest,
   ProfileLinkRequest,
   ThreadIdStore,
   GenerateId,

package/src/invoke-turn.ts

@@ -23,21 +23,9 @@
  * fall-through, so new wire events are additive for every consumer.
  */
 import type { AgEvent } from "@silverprotocol/core";
-import {
-  parseConsentRequest,
-  parseLinkRequest,
-  parseSseEvents,
-  reduceAssistantText,
-  stringField,
-} from "./sse.js";
+import { parseLinkRequest, parseSseEvents, reduceAssistantText, stringField } from "./sse.js";
 import { ingestMessageFrame } from "./blocks.js";
-import type {
-  AgentInvokeStatus,
-  InvokeRequest,
-  InvokeTransport,
-  ProfileConsentRequest,
-  ProfileLinkRequest,
-} from "./types.js";
+import type { AgentInvokeStatus, InvokeRequest, InvokeTransport, ProfileLinkRequest } from "./types.js";
 
 /**
  * One semantic step of a turn. Field conventions:
@@ -63,7 +51,6 @@ export type InvokeTurnEvent =
       agEvents: AgEvent[];
     }
   | { kind: "error"; message: string; code: string | null }
-  | { kind: "profile-consent"; request: ProfileConsentRequest }
   | { kind: "profile-link"; request: ProfileLinkRequest }
   | { kind: "done"; stopReason: string | null };
 
@@ -164,15 +151,12 @@ export async function* invokeTurn(
           message: stringField(ev.data, "message") ?? "agent error",
           code: stringField(ev.data, "code") ?? null,
         };
-      } else if (ev.event === "profile-consent-needed") {
-        // Cross-app profile consent ask (T6). Only a well-formed payload
-        // yields; a malformed one is dropped, leaving any prior valid
-        // request untouched (never clobbered to null).
-        const parsed = parseConsentRequest(ev.data);
-        if (parsed) yield { kind: "profile-consent", request: parsed };
       } else if (ev.event === "profile-link-needed") {
         // Cross-app profile LINK invite (linkcoh T3) for an unlinked byo
-        // caller. Same drop-if-malformed contract as consent above.
+        // caller. Only a well-formed payload yields; a malformed one is
+        // dropped, leaving any prior valid request untouched (never clobbered
+        // to null). (Consent is NOT a bespoke event: it rides the AgJSON fold
+        // as `hitl.ask` + `turn.done outcome:"paused"` — guuey#207.)
         const parsed = parseLinkRequest(ev.data);
         if (parsed) yield { kind: "profile-link", request: parsed };
       } else if (ev.event === "done") {

package/src/react.ts

@@ -12,6 +12,7 @@ export {
   type HistoryApplication,
   stallProbeDecision,
   STALL_RECOVERY_DEFAULTS,
+  DEFAULT_BLOCK_PRESERVING_CAPABILITIES,
 } from "./useAgentInvoke.js";
 // The block-preserving transcript surfaces `AgReduceResult`; re-export it (and
 // `AgEvent`) here so `./react` consumers can type `reduceResult` without a

package/src/sse.ts

@@ -4,7 +4,7 @@
  * verbatim across web (Studio) and React-Native (Portal).
  */
 
-import type { ProfileConsentRequest, ProfileLinkRequest } from "./types.js";
+import type { ProfileLinkRequest } from "./types.js";
 
 export interface ParsedSseEvent {
   event: string;
@@ -140,30 +140,13 @@ export function stringField(data: unknown, key: string): string | undefined {
   return typeof v === "string" ? v : undefined;
 }
 
-/**
- * Parse a `profile-consent-needed` SSE payload into a typed
- * {@link ProfileConsentRequest}, or `null` if it does not conform. `appId`
- * must be a non-empty string and `requested` exactly `"read"` or
- * `"read-write"`; extra keys are tolerated (ignored). Returns a fresh
- * normalized object so callers get exactly the typed shape, never the raw
- * wire payload with unknown extras.
- */
-export function parseConsentRequest(data: unknown): ProfileConsentRequest | null {
-  if (typeof data !== "object" || data === null || Array.isArray(data)) return null;
-  const appId = (data as { appId?: unknown }).appId;
-  const requested = (data as { requested?: unknown }).requested;
-  if (typeof appId !== "string" || appId.length === 0) return null;
-  if (requested !== "read" && requested !== "read-write") return null;
-  return { appId, requested };
-}
-
 /**
  * Parse a `profile-link-needed` SSE payload into a typed
- * {@link ProfileLinkRequest}, or `null` if it does not conform. Same shape +
- * validation as {@link parseConsentRequest} (`appId` non-empty string,
- * `requested` exactly `"read"` or `"read-write"`, extra keys tolerated) — the
- * pod emits an identically-shaped payload for both events; only the event
- * NAME (and what it means to the consumer) differs.
+ * {@link ProfileLinkRequest}, or `null` if it does not conform. `appId` must
+ * be a non-empty string and `requested` exactly `"read"` or `"read-write"`;
+ * extra keys are tolerated (ignored). Returns a fresh normalized object so
+ * callers get exactly the typed shape, never the raw wire payload with
+ * unknown extras.
  */
 export function parseLinkRequest(data: unknown): ProfileLinkRequest | null {
   if (typeof data !== "object" || data === null || Array.isArray(data)) return null;

package/src/types.ts

@@ -13,7 +13,7 @@
  * `MessageStorageAdapter` injection pattern.
  */
 
-import type { AgReduceResult, JsonValue } from "@silverprotocol/core";
+import type { AgClientCapabilities, AgReduceResult, JsonValue } from "@silverprotocol/core";
 
 /** A flat chat turn as rendered by the consumer UI. */
 export interface AgentMessage {
@@ -28,20 +28,6 @@ export interface AgentMessage {
   clientMessageId?: string;
 }
 
-/**
- * A cross-app profile consent request surfaced mid-stream by the pod's
- * `profile-consent-needed` SSE event (nocode-runtime T6). Emitted when the
- * agent declares a profile intent the caller has NOT yet granted for this app,
- * so the consumer UI can prompt the user to authorize `read` or `read-write`
- * access. `requested` mirrors the pod's `ProfileAccess` posture verbatim; the
- * literal union is inlined rather than imported to keep this client SDK free of
- * any backend-package dependency.
- */
-export interface ProfileConsentRequest {
-  appId: string;
-  requested: "read" | "read-write";
-}
-
 /**
  * A cross-app profile LINK invite surfaced mid-stream by the pod's
  * `profile-link-needed` SSE event (nocode-runtime linkcoh T3). Emitted when an
@@ -49,8 +35,10 @@ export interface ProfileConsentRequest {
  * link their guuey account (via the named `/link` ceremony) so they earn the
  * guuey-wide cross-app profile. `requested` mirrors the pod's `ProfileAccess`
  * posture verbatim (the builder's declared access, not a live ask) — the
- * literal union is inlined rather than imported, same rationale as
- * {@link ProfileConsentRequest}.
+ * literal union is inlined rather than imported to keep this client SDK free
+ * of any backend-package dependency. (Consent itself is no longer a bespoke
+ * event: it rides AgJSON `hitl.ask` + `turn.done outcome:"paused"` in the
+ * fold and is answered through `createHitlAnswerRelay` — guuey#207.)
  */
 export interface ProfileLinkRequest {
   appId: string;
@@ -87,7 +75,7 @@ export type GenerateId = () => string;
 export interface InvokeRequest {
   /** Fully-resolved POST target (already normalised to end in `/agent/invoke`). */
   url: string;
-  /** JSON request body: `{ input, threadId?, clientMessageId }`. */
+  /** JSON request body: `{ input, threadId?, clientMessageId, capabilities? }`. */
   body: unknown;
   /** Aborts the in-flight stream. */
   signal: AbortSignal;
@@ -165,6 +153,18 @@ export interface UseAgentInvokeOptions {
    * reducer is never constructed and the text behaviour is byte-identical.
    */
   preserveBlocks?: boolean;
+  /**
+   * The AgJSON client capabilities advertised on every invoke body (spec §3
+   * `AgClientCapabilities`, guuey#207). The pod reads them to decide what it
+   * may ask: today it declares consent `grantModes` (the three-mode profile
+   * grant the `@guuey/chat` card renders) ONLY to a client that advertised
+   * `hitl.grantModes` — a client that cannot render the decision surface is
+   * simply not asked. Default: when {@link preserveBlocks} is on,
+   * `{ hitl: { ask: true, grantModes: true } }` (a block-preserving consumer
+   * folds the paused turn the ask rides on — the kit's exact path); when off,
+   * nothing is advertised. Pass an explicit object to override either way.
+   */
+  capabilities?: AgClientCapabilities;
   /**
    * Stall recovery for a half-dead stream (guuey#192). A connection that dies
    * WITHOUT erroring (TCP alive, zero bytes, no `done`) would otherwise leave
@@ -283,26 +283,16 @@ export interface UseAgentInvokeReturn {
    * `reset()` clears it back to `[]`.
    */
   historyCards: HistoryCard[];
-  /**
-   * The latest cross-app profile consent request the pod asked for on THIS
-   * conversation, or `null`. Set from a well-formed `profile-consent-needed`
-   * SSE event (see {@link ProfileConsentRequest}); malformed payloads are
-   * dropped and leave the field untouched. `reset()` and an app switch clear
-   * it back to `null`. Consumers that never render a consent prompt (e.g.
-   * Studio) simply ignore this field.
-   */
-  profileConsentRequest: ProfileConsentRequest | null;
-  /** Dismiss the pending {@link profileConsentRequest} (back to `null`). */
-  clearProfileConsentRequest: () => void;
   /**
    * The latest cross-app profile LINK invite the pod asked for on THIS
    * conversation, or `null`. Set from a well-formed `profile-link-needed`
    * SSE event (see {@link ProfileLinkRequest}); malformed payloads are
    * dropped and leave the field untouched. `reset()` and an app switch clear
    * it back to `null`. Consumers that never render a link prompt simply
-   * ignore this field. Distinct from {@link profileConsentRequest}: this one
-   * invites an UNLINKED byo user to link their account; consent asks an
-   * already-linked user to grant an app read/read-write access.
+   * ignore this field. Distinct from consent (an AgJSON `hitl.ask` in the
+   * fold, guuey#207): this one invites an UNLINKED byo user to link their
+   * account; consent asks an already-linked user to grant an app
+   * read/read-write access.
    */
   profileLinkRequest: ProfileLinkRequest | null;
   /** Dismiss the pending {@link profileLinkRequest} (back to `null`). */

package/src/useAgentInvoke.ts

@@ -5,7 +5,7 @@
  * ggui generative-UI protocol that `@ggui-ai/mcp-apps-react`'s useInvoke targets):
  *
  *   POST {endpointUrl}/agent/invoke
- *     body: { input, threadId?, clientMessageId }
+ *     body: { input, threadId?, clientMessageId, capabilities? }
  *   ← SSE:
  *     event: session  { sessionId, userId, threadId? }
  *     event: message  <SDKMessage JSON>          (assistant turns + result)
@@ -22,7 +22,7 @@
  * `./web-adapters` for the web (Studio) bundle; Portal supplies RN adapters.
  */
 import { useCallback, useEffect, useRef, useState } from "react";
-import { Reducer, type AgReduceResult } from "@silverprotocol/core";
+import { Reducer, type AgClientCapabilities, type AgReduceResult } from "@silverprotocol/core";
 import { invokeTurn, toInvokeUrl } from "./invoke-turn.js";
 import { AgentResponseError } from "./errors.js";
 import { withActivityObserver } from "./transport.js";
@@ -33,7 +33,6 @@ import type {
   AgentMessage,
   HistoryCard,
   HistoryLoadResult,
-  ProfileConsentRequest,
   ProfileLinkRequest,
   StallRecoveryOptions,
   UseAgentInvokeOptions,
@@ -44,6 +43,16 @@ function threadStorageKey(appId: string | undefined): string {
   return `guuey:thread:${appId ?? "default"}`;
 }
 
+/**
+ * What a block-preserving consumer advertises by default (guuey#207): it
+ * folds `turn.done outcome:"paused"` records, so it can render the AgJSON
+ * hitl card with declared grant modes — the `@guuey/chat` path. See
+ * `UseAgentInvokeOptions.capabilities`.
+ */
+export const DEFAULT_BLOCK_PRESERVING_CAPABILITIES: AgClientCapabilities = {
+  hitl: { ask: true, grantModes: true },
+};
+
 /** The decision `applyHistoryResult` reaches for a loaded transcript. */
 export type HistoryApplication =
   | { kind: "seed"; messages: AgentMessage[] }
@@ -136,14 +145,11 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   // contract). Independent of the live `reduceResult` fold — populated only
   // when a card-carrying history load seeds the transcript.
   const [historyCards, setHistoryCards] = useState<HistoryCard[]>([]);
-  // The pod's latest cross-app profile consent ask on this conversation (T6's
-  // `profile-consent-needed` SSE event), or null. Cleared on app switch /
-  // reset / explicit dismiss. Consumers with no consent UI just ignore it.
-  const [profileConsentRequest, setProfileConsentRequest] = useState<ProfileConsentRequest | null>(null);
   // The pod's latest cross-app profile LINK invite on this conversation (T3's
   // `profile-link-needed` SSE event), or null. Cleared on app switch / reset /
-  // explicit dismiss, same lifecycle as `profileConsentRequest` — the two are
-  // independent (an unlinked-invite vs an already-linked consent ask).
+  // explicit dismiss. (Consent is NOT hook state: it rides the AgJSON fold as
+  // a paused turn — `reduceResult` — and is answered through
+  // `createHitlAnswerRelay`, guuey#207.)
   const [profileLinkRequest, setProfileLinkRequest] = useState<ProfileLinkRequest | null>(null);
   // The last turn's ending posture + the optimistic-send ledger — the
   // transcript renderer's inputs (guuey#135 wave 3b; see the return-type
@@ -201,8 +207,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     reducerRef.current = null;
     setReduceResult(null);
     setHistoryCards([]);
-    // A prior app's consent ask must never leak into the new conversation.
-    setProfileConsentRequest(null);
+    // A prior app's link invite must never leak into the new conversation.
     setProfileLinkRequest(null);
     setAborted(false);
     setAdopted(false);
@@ -295,17 +300,12 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     reducerRef.current = null;
     setReduceResult(null);
     setHistoryCards([]);
-    setProfileConsentRequest(null);
     setProfileLinkRequest(null);
     setAborted(false);
     setAdopted(false);
     setSendStates({});
   }, [appId]);
 
-  const clearProfileConsentRequest = useCallback(() => {
-    setProfileConsentRequest(null);
-  }, []);
-
   const clearProfileLinkRequest = useCallback(() => {
     setProfileLinkRequest(null);
   }, []);
@@ -474,10 +474,17 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
 
       try {
         const invokeUrl = toInvokeUrl(endpointUrl);
+        // The advertised AgJSON client capabilities (spec §3, guuey#207): an
+        // explicit option wins; else a block-preserving consumer advertises
+        // the hitl grant-mode card it can render, and a text-only one nothing.
+        const capabilities =
+          opts.capabilities ??
+          (preserveBlocksRef.current ? DEFAULT_BLOCK_PRESERVING_CAPABILITIES : undefined);
         const body = {
           input,
           ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
           clientMessageId,
+          ...(capabilities !== undefined ? { capabilities } : {}),
         };
 
         // The wire walk lives in `invokeTurn` (the pure per-turn generator —
@@ -519,8 +526,6 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
             // a previous turn's code standing).
             setError(ev.message);
             setErrorCode(ev.code);
-          } else if (ev.kind === "profile-consent") {
-            setProfileConsentRequest(ev.request);
           } else if (ev.kind === "profile-link") {
             setProfileLinkRequest(ev.request);
           }
@@ -588,8 +593,6 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     reset,
     reduceResult,
     historyCards,
-    profileConsentRequest,
-    clearProfileConsentRequest,
     profileLinkRequest,
     clearProfileLinkRequest,
     aborted,