@dudousxd/nestjs-agent-react 0.31.5 → 0.33.0

package/dist/index.cjs

@@ -78,8 +78,10 @@ __export(src_exports, {
   onThreadsEvent: () => onThreadsEvent,
   persistSpeechLang: () => persistSpeechLang,
   phraseFor: () => phraseFor,
+  proposalNeedsPolling: () => proposalNeedsPolling,
   readPath: () => readPath,
   readReasoningMs: () => readReasoningMs,
+  reconcileProposalMessages: () => reconcileProposalMessages,
   reframeAgUiStream: () => reframeAgUiStream,
   requireBackendMethod: () => requireBackendMethod,
   resolveResultView: () => resolveResultView,
@@ -87,6 +89,7 @@ __export(src_exports, {
   storedThreadToUiMessages: () => storedThreadToUiMessages,
   toolCallState: () => toolCallState,
   toolCatalogFrom: () => toolCatalogFrom,
+  useActionProposals: () => useActionProposals,
   useAgentBackend: () => useAgentBackend,
   useAgentChat: () => useAgentChat,
   useAgentConfig: () => useAgentConfig,
@@ -121,9 +124,9 @@ function readErrorAnswer(text) {
   }
   if (body === null || typeof body !== "object")
     return { body, message: void 0, code: void 0 };
-  const record = body;
-  const message = typeof record.message === "string" && record.message !== "" ? record.message : Array.isArray(record.message) && record.message.length > 0 && record.message.every((each) => typeof each === "string") ? record.message.join("; ") : void 0;
-  const code = typeof record.code === "string" && record.code !== "" ? record.code : void 0;
+  const record2 = body;
+  const message = typeof record2.message === "string" && record2.message !== "" ? record2.message : Array.isArray(record2.message) && record2.message.length > 0 && record2.message.every((each) => typeof each === "string") ? record2.message.join("; ") : void 0;
+  const code = typeof record2.code === "string" && record2.code !== "" ? record2.code : void 0;
   return { body, message, code };
 }
 async function readErrorResponse(response) {
@@ -200,6 +203,12 @@ var AgentClient = class {
     if (response.status === 202) {
       return { body: emptyStream(), queued: await response.json() };
     }
+    if (response.ok && response.headers.get("content-type")?.includes("application/json")) {
+      const decision = await response.json();
+      if (decision.proposalDecision !== void 0 && typeof decision.threadId === "string")
+        return { body: emptyStream(), threadId: decision.threadId, proposalDecision: decision };
+      throw new Error("Unexpected JSON chat response");
+    }
     if (!response.ok || !response.body) {
       throw await this.failure(response, "POST", `${this.agentPath()}/chat`);
     }
@@ -432,6 +441,54 @@ var AgentClient = class {
    * `remember` approves later calls of the same tool in the same thread; `via` names the surface
    * the decision came through (the server records `'web'` when omitted).
    */
+  async listActionProposals({ threadId }) {
+    const proposals = /* @__PURE__ */ new Map();
+    let after;
+    for (; ; ) {
+      const route = `/threads/${encodeURIComponent(threadId)}/action-proposals${after === void 0 ? "" : `?after=${encodeURIComponent(JSON.stringify(after))}`}`;
+      const response = await this.requestResponse("GET", route);
+      const page = await this.handleResponse(
+        response,
+        "GET",
+        `${this.agentPath()}${route}`
+      );
+      if (!Array.isArray(page)) throw new TypeError("Invalid action proposal page");
+      for (const proposal of page) proposals.set(proposal.id, proposal);
+      const header = response.headers.get("X-Action-Proposals-Next");
+      if (header === null) return [...proposals.values()];
+      let next;
+      try {
+        next = JSON.parse(decodeURIComponent(header));
+      } catch {
+        throw new TypeError("Invalid action proposal cursor");
+      }
+      if (typeof next !== "object" || next === null || !("createdAt" in next) || typeof next.createdAt !== "number" || !Number.isSafeInteger(next.createdAt) || !("id" in next) || typeof next.id !== "string" || next.id.length === 0 || next.id.length > 255 || after !== void 0 && (next.createdAt < after.createdAt || next.createdAt === after.createdAt && next.id <= after.id))
+        throw new TypeError("Invalid or non-advancing action proposal cursor");
+      after = { createdAt: next.createdAt, id: next.id };
+    }
+  }
+  approveActionProposal({
+    threadId,
+    proposalId,
+    remember
+  }) {
+    return this.request(
+      "POST",
+      `/threads/${encodeURIComponent(threadId)}/action-proposals/${encodeURIComponent(proposalId)}/approve`,
+      remember === void 0 ? {} : { remember }
+    );
+  }
+  rejectActionProposal({
+    threadId,
+    proposalId,
+    reason
+  }) {
+    return this.request(
+      "POST",
+      `/threads/${encodeURIComponent(threadId)}/action-proposals/${encodeURIComponent(proposalId)}/reject`,
+      reason === void 0 ? {} : { reason }
+    );
+  }
   approveToolCall(input) {
     return this.request("POST", "/tool-call/approve", input);
   }
@@ -488,6 +545,10 @@ var AgentClient = class {
     return this.options.credentials !== void 0 ? { credentials: this.options.credentials } : {};
   }
   async request(method, route, body) {
+    const response = await this.requestResponse(method, route, body);
+    return this.handleResponse(response, method, `${this.agentPath()}${route}`);
+  }
+  async requestResponse(method, route, body) {
     const path = `${this.agentPath()}${route}`;
     const response = await this.fetchImpl()(`${this.baseUrl()}${path}`, {
       method,
@@ -499,7 +560,7 @@ var AgentClient = class {
       ...body !== void 0 ? { body: JSON.stringify(body) } : {},
       ...this.credentials()
     });
-    return this.handleResponse(response, method, path);
+    return response;
   }
   /** The error for a refused `response`, already reported to `onHttpError`. */
   async failure(response, method, path) {
@@ -639,6 +700,7 @@ var AgentChatTransport = class {
       const message = lastMessage ? extractText(lastMessage) : "";
       const body = {
         ...this.options.agent !== void 0 ? { agent: this.options.agent } : {},
+        ...this.options.persona !== void 0 ? { persona: this.options.persona } : {},
         ...this.options.getBody?.() ?? {},
         ...options.body ?? {},
         message
@@ -654,6 +716,10 @@ var AgentChatTransport = class {
         return queuedChunkStream(response.queued);
       }
       this.captureHeaderMeta(response);
+      if (response.proposalDecision !== void 0) {
+        this.attemptLive = false;
+        return proposalDecisionChunkStream(response.proposalDecision);
+      }
       return this.toChunkStream(response, {
         ...headers !== void 0 ? { headers } : {},
         ...options.abortSignal ? { signal: options.abortSignal } : {}
@@ -780,7 +846,7 @@ var AgentChatTransport = class {
     let reasoningSeq = 0;
     const announced = /* @__PURE__ */ new Set();
     const toolMetadata = /* @__PURE__ */ new Map();
-    const record = (meta) => {
+    const record2 = (meta) => {
       streamRunId = meta.runId;
       this.recordMeta(meta);
     };
@@ -1068,7 +1134,7 @@ var AgentChatTransport = class {
               }
               if (frame.event === "meta") {
                 const meta = parseMeta(frame.data);
-                if (meta) record(meta);
+                if (meta) record2(meta);
               } else if (frame.data) {
                 const event = parseEvent(frame.data);
                 if (event) emit(event);
@@ -1136,10 +1202,10 @@ function parseErrorFrame(data) {
   try {
     const parsed = JSON.parse(data);
     if (parsed !== null && typeof parsed === "object") {
-      const record = parsed;
+      const record2 = parsed;
       return {
-        code: typeof record.code === "string" && record.code !== "" ? record.code : void 0,
-        message: typeof record.message === "string" && record.message !== "" ? record.message : fallback2.message
+        code: typeof record2.code === "string" && record2.code !== "" ? record2.code : void 0,
+        message: typeof record2.message === "string" && record2.message !== "" ? record2.message : fallback2.message
       };
     }
   } catch {
@@ -1179,6 +1245,21 @@ function delay(ms, signal) {
     signal?.addEventListener("abort", done, { once: true });
   });
 }
+function proposalDecisionChunkStream(decision) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue({ type: "start", messageId: `decision:${crypto.randomUUID()}` });
+      controller.enqueue({ type: "data-proposal-decision", data: decision, transient: true });
+      if (decision.text !== void 0 && decision.text.length > 0) {
+        controller.enqueue({ type: "text-start", id: "decision" });
+        controller.enqueue({ type: "text-delta", id: "decision", delta: decision.text });
+        controller.enqueue({ type: "text-end", id: "decision" });
+      }
+      controller.enqueue({ type: "finish", finishReason: "stop" });
+      controller.close();
+    }
+  });
+}
 
 // src/attachments/files.ts
 function fileKind(mediaType) {
@@ -1311,6 +1392,10 @@ function toGenerativeUIItem(part) {
   return {
     id,
     component: source.component,
+    ...isRecord(source.componentVersions) && Object.values(source.componentVersions).every(
+      (version) => typeof version === "number" && Number.isSafeInteger(version) && version > 0
+    ) ? { componentVersions: { ...source.componentVersions } } : {},
+    ...typeof source.fallbackText === "string" ? { fallbackText: source.fallbackText } : {},
     props: isRecord(source.props) ? source.props : {},
     version: typeof source.version === "number" ? source.version : null,
     toolCallId: typeof source.toolCallId === "string" ? source.toolCallId : null
@@ -1416,20 +1501,29 @@ function useValidatedProps(catalog, name, props) {
 function useGenerativeUIState(part, options, fallbackTree) {
   const item = (0, import_react3.useMemo)(() => toGenerativeUIItem(part), [part]);
   const name = item?.component ?? "";
+  const definition = options.catalog?.get?.(name);
+  const incompatible = item?.fallbackText !== void 0 && item.version !== null && definition !== void 0 && item.version !== (definition.version ?? 1);
   const resolution = useResolvedComponent(
     name,
     item?.version ?? null,
-    options.registry,
+    incompatible ? {} : options.registry,
     item === null ? void 0 : options.resolveComponent,
     fallbackTree
   );
   const empty = (0, import_react3.useMemo)(() => ({}), []);
   const validation = useValidatedProps(
-    item === null || name === GENUI_TREE_COMPONENT ? void 0 : options.catalog,
+    item === null || name === GENUI_TREE_COMPONENT || incompatible ? void 0 : options.catalog,
     name,
     item?.props ?? empty
   );
   if (item === null) return null;
+  if (name === GENUI_TREE_COMPONENT && item.fallbackText !== void 0 && (!isRecord(item.props.root) || typeof item.props.root.type !== "string"))
+    return {
+      status: "problem",
+      reason: "invalid",
+      item,
+      issues: [{ path: ["root"], message: "Invalid UI tree root" }]
+    };
   if (resolution.status === "loading") return { status: "loading", item };
   if (resolution.status === "unknown") return { status: "problem", reason: "unknown", item };
   if (resolution.status === "error") {
@@ -1447,7 +1541,8 @@ var import_jsx_runtime = require("react/jsx-runtime");
 var TreeScopeContext = (0, import_react4.createContext)(null);
 function renderFallback(fallback2, problem) {
   if (typeof fallback2 === "function") return fallback2(problem);
-  return fallback2 ?? null;
+  if (fallback2 !== void 0) return fallback2;
+  return problem.item.fallbackText !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: { whiteSpace: "pre-wrap" }, children: problem.item.fallbackText }) : null;
 }
 var ItemBoundary = class extends import_react4.Component {
   state = { error: void 0, failed: false };
@@ -1479,28 +1574,42 @@ function nodeItem(node, id) {
 function TreeNode({ node, id }) {
   const scope = (0, import_react4.useContext)(TreeScopeContext);
   const item = (0, import_react4.useMemo)(() => nodeItem(node, id), [node, id]);
+  const storedVersion = scope?.componentVersions?.[node.type];
+  const definition = scope?.options.catalog?.get?.(node.type);
+  const incompatible = storedVersion !== void 0 && definition !== void 0 && storedVersion !== (definition.version ?? 1);
   const resolution = useResolvedComponent(
     node.type,
-    null,
-    scope?.options.registry ?? {},
+    storedVersion ?? null,
+    incompatible ? {} : scope?.options.registry ?? {},
     scope?.options.resolveComponent
   );
-  const validation = useValidatedProps(scope?.options.catalog, node.type, item.props);
+  const validation = useValidatedProps(
+    incompatible ? void 0 : scope?.options.catalog,
+    node.type,
+    item.props
+  );
   if (scope === null) return null;
   if (resolution.status === "loading" || validation.status === "pending") return scope.loading;
   if (resolution.status === "unknown") {
+    if (scope.fallback === void 0 && scope.fallbackText !== void 0)
+      throw new Error("Unknown tree component");
     return renderFallback(scope.fallback, { reason: "unknown", item });
   }
   if (resolution.status === "error") {
+    if (scope.fallback === void 0 && scope.fallbackText !== void 0) throw resolution.error;
     return renderFallback(scope.fallback, { reason: "error", item, error: resolution.error });
   }
   if (validation.status === "invalid") {
+    if (scope.fallback === void 0 && scope.fallbackText !== void 0)
+      throw new Error("Invalid tree component");
     return renderFallback(scope.fallback, { reason: "invalid", item, issues: validation.issues });
   }
   const Renderer = resolution.Component;
   const children = Array.isArray(node.children) ? node.children : [];
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Renderer, { ...validation.props, children: children.length > 0 ? children.map((child, index) => {
     const childId = `${id}.${index}`;
+    if (scope.fallback === void 0 && scope.fallbackText !== void 0)
+      return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TreeNode, { node: child, id: childId }, childId);
     return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       ItemBoundary,
       {
@@ -1522,6 +1631,8 @@ function GenerativeUIScope({
   catalog,
   resolveComponent,
   fallback: fallback2,
+  fallbackText,
+  componentVersions,
   loading = null,
   onError,
   children
@@ -1534,10 +1645,21 @@ function GenerativeUIScope({
         ...resolveComponent !== void 0 ? { resolveComponent } : {}
       },
       fallback: fallback2,
+      ...componentVersions !== void 0 ? { componentVersions } : {},
+      ...fallbackText !== void 0 ? { fallbackText } : {},
       loading,
       onError
     }),
-    [registry, catalog, resolveComponent, fallback2, loading, onError]
+    [
+      registry,
+      catalog,
+      resolveComponent,
+      fallback2,
+      fallbackText,
+      componentVersions,
+      loading,
+      onError
+    ]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TreeScopeContext.Provider, { value: scope, children });
 }
@@ -1597,7 +1719,7 @@ function GenerativeUI({
   onError: ownOnError
 }) {
   const provided = (0, import_react4.useContext)(GenuiContext);
-  const fallback2 = ownFallback ?? provided?.fallback;
+  const fallback2 = ownFallback !== void 0 ? ownFallback : provided?.fallback;
   const loading = ownLoading ?? provided?.loading ?? null;
   const onError = ownOnError ?? provided?.onError;
   const options = useMergedOptions({
@@ -1622,6 +1744,8 @@ function GenerativeUI({
     GenerativeUIScope,
     {
       ...options,
+      ...state.item.componentVersions !== void 0 ? { componentVersions: state.item.componentVersions } : {},
+      ...state.item.fallbackText !== void 0 ? { fallbackText: state.item.fallbackText } : {},
       fallback: fallback2,
       loading,
       ...onError !== void 0 ? { onError } : {},
@@ -1637,6 +1761,7 @@ var AgentBackendContext = sharedContext(
 );
 function AgentProvider({
   backend,
+  uiCapabilities,
   baseUrl,
   path,
   headers,
@@ -1668,7 +1793,7 @@ function AgentProvider({
     [backend, baseUrl, path, credentials, fetch, upload]
   );
   const content = genui !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(GenuiProvider, { ...genui, children }) : children;
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(AgentBackendContext.Provider, { value, children: content });
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(AgentUiCapabilitiesContext.Provider, { value: uiCapabilities ?? null, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(AgentBackendContext.Provider, { value, children: content }) });
 }
 var fallback;
 function defaultBackend() {
@@ -1679,6 +1804,12 @@ function useAgentBackend(own) {
   const provided = (0, import_react5.useContext)(AgentBackendContext);
   return own ?? provided ?? defaultBackend();
 }
+var AgentUiCapabilitiesContext = sharedContext(
+  "@dudousxd/nestjs-agent-react:ui-capabilities"
+);
+function useAgentUiCapabilities() {
+  return (0, import_react5.useContext)(AgentUiCapabilitiesContext) ?? void 0;
+}
 
 // src/config/use-agent-config.ts
 var shared = /* @__PURE__ */ new WeakMap();
@@ -1944,7 +2075,7 @@ async function defaultRefusal(response) {
 }
 function defaultForwardedProps(body) {
   const out = {};
-  for (const key of ["pageContext", "agent", "model"]) {
+  for (const key of ["pageContext", "agent", "model", "persona", "uiCapabilities"]) {
     if (body[key] !== void 0 && body[key] !== null) out[key] = body[key];
   }
   return Object.keys(out).length > 0 ? out : void 0;
@@ -2303,16 +2434,24 @@ function useAgents(options = {}) {
     "",
     enabled
   );
+  const find = (0, import_react9.useCallback)(
+    (name) => (data ?? []).find(
+      (agent) => name === void 0 ? agent.isDefault === true : agent.name === name
+    ),
+    [data]
+  );
   return (0, import_react9.useMemo)(() => {
     const agents = data ?? [];
     return {
       agents,
       defaultAgent: agents.find((agent) => agent.isDefault === true)?.name ?? null,
+      personasOf: (agent) => find(agent)?.personas ?? [],
+      defaultPersonaOf: (agent) => find(agent)?.defaultPersona ?? null,
       isLoading,
       error,
       refresh
     };
-  }, [data, isLoading, error, refresh]);
+  }, [data, find, isLoading, error, refresh]);
 }
 
 // src/catalog/use-models.ts
@@ -2970,6 +3109,15 @@ function isActionCall(part) {
 }
 function toolCallState(part) {
   const output = "output" in part ? part.output : void 0;
+  if (output !== null && typeof output === "object" && "proposalId" in output && "executed" in output && output.executed === false)
+    return {
+      status: "awaiting-approval",
+      isSettled: false,
+      isFailed: false,
+      isDenied: false,
+      output,
+      error: null
+    };
   const errorText = "errorText" in part ? part.errorText : void 0;
   const outputError = output !== null && typeof output === "object" && "error" in output ? String(output.error) : void 0;
   const isDenied = part.state === "output-denied";
@@ -3014,7 +3162,11 @@ function describeToolCall(part, catalog, options = {}) {
     icon: presentation?.icon ?? null,
     tone: presentation?.tone ?? "neutral",
     detail: presentation?.detail ?? null,
-    confirm: confirm === void 0 ? null : {
+    confirm: options.confirmation !== void 0 ? {
+      title: options.confirmation.title,
+      verb: options.confirmation.verb,
+      detail: options.confirmation.detail ?? null
+    } : confirm === void 0 ? null : {
       title: fillTemplate(confirm.title, input),
       verb: confirm.verb,
       detail: confirm.detail !== void 0 ? fillTemplate(confirm.detail, input) : null
@@ -3028,6 +3180,9 @@ function describeToolCall(part, catalog, options = {}) {
 }
 var STATUS_WEIGHT = {
   running: 4,
+  queued: 4,
+  executing: 4,
+  succeeded: 0,
   "awaiting-approval": 3,
   failed: 2,
   denied: 1,
@@ -3047,7 +3202,7 @@ function groupToolActivity(calls, options = {}) {
     if (corrected.has(call.toolCallId)) continue;
     const presentation = options.catalog?.[call.name];
     const key = options.keyOf?.(call, presentation) ?? presentation?.label ?? call.name;
-    const status = toolCallState(call.part).status;
+    const status = call.description.status;
     const phrase = phraseFor(
       presentation,
       call.part.input,
@@ -3289,7 +3444,7 @@ function isAncestor(call, candidate, byId) {
 }
 function buildToolCall(part, options, approval, catalog) {
   const toolCallId = part.toolCallId;
-  const awaiting = isAwaitingApproval(part);
+  const awaiting = approval?.target?.kind === "proposal" ? approval.status === "pending" : isAwaitingApproval(part);
   const sending = awaiting ? options?.submitting(toolCallId) ?? null : null;
   return {
     part,
@@ -3299,19 +3454,30 @@ function buildToolCall(part, options, approval, catalog) {
     parentId: toolParentId(part),
     children: [],
     approval,
-    description: describeToolCall(part, catalog),
+    description: proposalDescription(
+      describeToolCall(
+        part,
+        catalog,
+        approval?.confirmation === void 0 ? {} : { confirmation: approval.confirmation }
+      ),
+      approval
+    ),
     isAwaitingApproval: awaiting,
     approve: {
       available: awaiting && options?.canApprove === true,
       isSubmitting: sending === "approve",
       // Read by field, not passed through: `onClick={call.approve.run}` hands this a click event,
       // and a host's handler must not receive that as its options.
-      run: (approveOptions) => approveOptions?.remember === true ? options?.approve(toolCallId, { remember: true }) : options?.approve(toolCallId)
+      run: (approveOptions) => approval?.target === void 0 ? approveOptions?.remember === true ? options?.approve(toolCallId, { remember: true }) : options?.approve(toolCallId) : options?.approve(
+        toolCallId,
+        approveOptions?.remember === true ? { remember: true } : void 0,
+        approval.target
+      )
     },
     reject: {
       available: awaiting && options?.canReject === true,
       isSubmitting: sending === "reject",
-      run: () => options?.reject(toolCallId)
+      run: () => approval?.target === void 0 ? options?.reject(toolCallId) : options?.reject(toolCallId, approval.target)
     },
     error: options?.errorOf(toolCallId) ?? null,
     errorCode: options?.errorCodeOf?.(toolCallId) ?? null
@@ -3461,7 +3627,7 @@ function buildElicitationBlock(key, part, request, options) {
 var UI_PART = "data-ui";
 var APPROVAL_PART = "data-approval-requested";
 var SETTLED_PART = "data-approval-settled";
-var SETTLED_STATUSES = ["approved", "rejected", "expired"];
+var SETTLED_STATUSES = ["approved", "rejected", "expired", "superseded"];
 function readApprovals(parts) {
   const out = /* @__PURE__ */ new Map();
   const entry = (id) => {
@@ -3482,7 +3648,7 @@ function readApprovals(parts) {
     return found;
   };
   for (const part of parts) {
-    if (part.type !== APPROVAL_PART && part.type !== SETTLED_PART) {
+    if (part.type !== APPROVAL_PART && part.type !== SETTLED_PART && part.type !== "data-action-proposal") {
       continue;
     }
     const data = part.data;
@@ -3490,12 +3656,35 @@ function readApprovals(parts) {
       continue;
     }
     const approval = entry(data.id);
-    if (part.type === APPROVAL_PART) {
+    if (part.type === APPROVAL_PART || part.type === "data-action-proposal") {
+      if (isRecord4(data.target) && data.target.kind === "proposal" && typeof data.target.proposalId === "string") {
+        approval.target = {
+          kind: "proposal",
+          proposalId: data.target.proposalId,
+          ...typeof data.target.threadId === "string" ? { threadId: data.target.threadId } : {}
+        };
+      }
+      if (part.type === "data-action-proposal") {
+        if (typeof data.status === "string" && ["pending", "approved", "rejected", "expired", "superseded"].includes(data.status))
+          approval.status = data.status === "pending" ? null : data.status;
+        if (data.executionStatus === null || data.executionStatus === "queued" || data.executionStatus === "executing" || data.executionStatus === "succeeded" || data.executionStatus === "failed")
+          approval.executionStatus = data.executionStatus;
+        approval.remember = data.remember === true;
+        approval.decidedBy = typeof data.decidedBy === "string" ? data.decidedBy : null;
+        approval.decidedVia = typeof data.decidedVia === "string" ? data.decidedVia : null;
+      }
       if (typeof data.approver !== "string") {
         continue;
       }
       approval.approver = data.approver;
       approval.expiresAt = typeof data.expiresAt === "string" ? data.expiresAt : null;
+      if (isRecord4(data.confirmation) && typeof data.confirmation.title === "string" && typeof data.confirmation.verb === "string" && (data.confirmation.detail === void 0 || typeof data.confirmation.detail === "string")) {
+        approval.confirmation = {
+          title: data.confirmation.title,
+          verb: data.confirmation.verb,
+          ...typeof data.confirmation.detail === "string" ? { detail: data.confirmation.detail } : {}
+        };
+      }
       approval.reason = typeof data.reason === "string" ? data.reason : null;
       continue;
     }
@@ -3519,9 +3708,12 @@ function approvalOf(parts, call) {
   }
   return {
     approver: parts.approver,
+    ...parts.target === void 0 ? {} : { target: parts.target },
+    ...parts.executionStatus === void 0 ? {} : { executionStatus: parts.executionStatus },
+    ...parts.confirmation !== void 0 ? { confirmation: parts.confirmation } : {},
     expiresAt: parts.expiresAt,
     reason: parts.reason,
-    status: parts.status ?? statusFromPart(call),
+    status: parts.status ?? (parts.target?.kind === "proposal" ? "pending" : statusFromPart(call)),
     remember: parts.remember,
     decidedBy: parts.decidedBy,
     decidedVia: parts.decidedVia,
@@ -3551,6 +3743,10 @@ function readUiComponent(part) {
     component: data.component,
     props: isRecord4(data.props) ? data.props : {},
     version: typeof data.version === "number" ? data.version : null,
+    ...isRecord4(data.componentVersions) && Object.values(data.componentVersions).every(
+      (version) => typeof version === "number" && Number.isSafeInteger(version) && version > 0
+    ) ? { componentVersions: { ...data.componentVersions } } : {},
+    ...typeof data.fallbackText === "string" ? { fallbackText: data.fallbackText } : {},
     toolCallId: typeof data.toolCallId === "string" ? data.toolCallId : null
   };
 }
@@ -3661,6 +3857,12 @@ function formatCostUsd(cost) {
   }
   return `$${cost.toFixed(2)}`;
 }
+function proposalDescription(description, approval) {
+  if (approval?.target?.kind !== "proposal") return description;
+  const status = approval.status === "pending" ? "awaiting-approval" : approval.status === "approved" ? approval.executionStatus ?? "queued" : "denied";
+  const phrase = status === "awaiting-approval" ? "Awaiting approval" : status === "queued" ? "Queued" : status === "executing" ? "Executing" : status === "succeeded" ? "Succeeded" : status === "failed" ? "Failed" : approval.status === "expired" ? "Expired" : approval.status === "superseded" ? "Replaced" : "Rejected";
+  return { ...description, status, phrase, result: null };
+}
 
 // src/transcript/use-stick-to-bottom.ts
 var import_react16 = require("react");
@@ -3953,23 +4155,31 @@ function useTranscriptItems({
     [settle]
   );
   const approve = (0, import_react17.useCallback)(
-    (toolCallId, options2) => {
+    (toolCallId, options2, target) => {
       const onApprove = latest.current.handlers.onApprove;
       if (onApprove) {
         settle(
           toolCallId,
           "approve",
-          () => onApprove({ toolCallId, ...options2?.remember === true ? { remember: true } : {} })
+          () => onApprove({
+            toolCallId,
+            ...target === void 0 ? {} : { target },
+            ...options2?.remember === true ? { remember: true } : {}
+          })
         );
       }
     },
     [settle]
   );
   const reject = (0, import_react17.useCallback)(
-    (toolCallId) => {
+    (toolCallId, target) => {
       const onReject = latest.current.handlers.onReject;
       if (onReject) {
-        settle(toolCallId, "reject", () => onReject({ toolCallId }));
+        settle(
+          toolCallId,
+          "reject",
+          () => onReject({ toolCallId, ...target === void 0 ? {} : { target } })
+        );
       }
     },
     [settle]
@@ -4167,14 +4377,36 @@ function settleHandlers(options, backend) {
     ),
     onApprove: pick(
       options.onApprove,
-      backend.approveToolCall ? async (input) => {
-        await backend.approveToolCall?.(input);
+      backend.approveToolCall || backend.approveActionProposal ? async (input) => {
+        if (input.target?.kind === "proposal") {
+          if (input.target.threadId === void 0)
+            throw new Error("A proposal decision requires its thread scope");
+          await requireBackendMethod(
+            backend,
+            "approveActionProposal"
+          )({
+            threadId: input.target.threadId,
+            proposalId: input.target.proposalId,
+            ...input.remember === void 0 ? {} : { remember: input.remember }
+          });
+        } else await requireBackendMethod(backend, "approveToolCall")(input);
       } : void 0
     ),
     onReject: pick(
       options.onReject,
-      backend.rejectToolCall ? async (input) => {
-        await backend.rejectToolCall?.(input);
+      backend.rejectToolCall || backend.rejectActionProposal ? async (input) => {
+        if (input.target?.kind === "proposal") {
+          if (input.target.threadId === void 0)
+            throw new Error("A proposal decision requires its thread scope");
+          await requireBackendMethod(
+            backend,
+            "rejectActionProposal"
+          )({
+            threadId: input.target.threadId,
+            proposalId: input.target.proposalId,
+            ...input.reason === void 0 ? {} : { reason: input.reason }
+          });
+        } else await requireBackendMethod(backend, "rejectToolCall")(input);
       } : void 0
     )
   };
@@ -5079,6 +5311,8 @@ function storedMessageToUiMessage(message) {
         id: component.id,
         component: component.component,
         props: component.props,
+        ...component.componentVersions !== void 0 ? { componentVersions: component.componentVersions } : {},
+        ...component.fallbackText !== void 0 ? { fallbackText: component.fallbackText } : {},
         ...component.version !== void 0 ? { version: component.version } : {},
         ...component.toolCallId !== void 0 ? { toolCallId: component.toolCallId } : {}
       }
@@ -5098,6 +5332,8 @@ function storedMessageToUiMessage(message) {
       data: {
         id: approval.toolCallId,
         approver: approval.approver,
+        ...approval.target !== void 0 ? { target: approval.target } : approval.proposalId !== void 0 ? { target: { kind: "proposal", proposalId: approval.proposalId } } : {},
+        ...approval.confirmation !== void 0 ? { confirmation: approval.confirmation } : {},
         ...approval.expiresAt !== void 0 ? { expiresAt: approval.expiresAt } : {}
       }
     });
@@ -5154,8 +5390,11 @@ function storedMessageToUiMessage(message) {
   const metadata = {
     // The host's own facts first: the library's keys win on a clash.
     ...message.metadata,
+    ...message.actionProposalOutcome === void 0 ? {} : { actionProposalOutcomeId: message.actionProposalOutcome.id },
     ...message.feedback !== void 0 ? { feedback: message.feedback } : {},
     ...message.createdAt ? { createdAt: message.createdAt } : {},
+    ...message.agentName !== void 0 ? { agentName: message.agentName } : {},
+    ...message.persona !== void 0 ? { persona: message.persona } : {},
     ...message.usage !== void 0 ? {
       usage: {
         inputTokens: message.usage.inputTokens,
@@ -5187,6 +5426,8 @@ function storedThreadToUiMessages(messages) {
   return turns.map(mergeTurn);
 }
 function sameRun(previous, next) {
+  if (previous.actionProposalOutcome !== void 0 || next.actionProposalOutcome !== void 0)
+    return false;
   return previous.runId === void 0 || next.runId === void 0 || previous.runId === next.runId;
 }
 function mergeTurn(rows) {
@@ -5206,7 +5447,9 @@ function mergeTurn(rows) {
     ...Object.assign({}, ...rows.map((row) => row.metadata ?? {})),
     ...usage !== void 0 ? { usage } : {},
     ...feedback !== void 0 ? { feedback } : {},
-    ...createdAt ? { createdAt } : {}
+    ...createdAt ? { createdAt } : {},
+    ...lastRow.agentName !== void 0 ? { agentName: lastRow.agentName } : {},
+    ...lastRow.persona !== void 0 ? { persona: lastRow.persona } : {}
   };
   return {
     id: lastRow.id,
@@ -5231,8 +5474,163 @@ function sumUsage(rows) {
 }
 
 // src/use-agent-chat.ts
-var import_react22 = require("@ai-sdk/react");
-var import_react23 = require("react");
+var import_react23 = require("@ai-sdk/react");
+var import_react24 = require("react");
+
+// src/approvals/use-action-proposals.ts
+var import_react22 = require("react");
+
+// src/approvals/proposals.ts
+function proposalNeedsPolling(proposal) {
+  return proposal.decision === "pending" || proposal.execution?.status === "queued" || proposal.execution?.status === "executing" || proposal.outcomeDelivery?.status === "pending";
+}
+function reconcileProposalMessages(current, proposals, facts) {
+  const messages = current.map((message) => {
+    const relevant = proposals.filter(
+      (proposal) => message.parts.some((part) => {
+        if ("data" in part && record(part.data) && record(part.data.target) && part.data.target.kind === "proposal")
+          return part.data.target.proposalId === proposal.id;
+        if ("toolCallId" in part && part.toolCallId === proposal.originToolCallId) {
+          if ("output" in part && record(part.output) && typeof part.output.proposalId === "string")
+            return part.output.proposalId === proposal.id;
+          return record(message.metadata) && message.metadata.runId === proposal.originRunId;
+        }
+        return false;
+      })
+    );
+    if (relevant.length === 0) return message;
+    const ids = new Set(relevant.map((proposal) => proposal.originToolCallId));
+    const parts = message.parts.filter(
+      (part) => !(part.type === "data-action-proposal" && "id" in part && typeof part.id === "string" && ids.has(part.id))
+    );
+    for (const proposal of relevant)
+      parts.push({
+        type: "data-action-proposal",
+        id: proposal.originToolCallId,
+        data: {
+          id: proposal.originToolCallId,
+          target: { kind: "proposal", proposalId: proposal.id, threadId: proposal.threadId },
+          approver: proposal.approver,
+          confirmation: proposal.confirmation,
+          expiresAt: proposal.expiresAt === null ? null : Math.abs(proposal.expiresAt) <= 864e13 ? new Date(proposal.expiresAt).toISOString() : null,
+          status: proposal.decision,
+          executionStatus: proposal.execution?.status ?? null,
+          remember: proposal.decisionAudit?.remember === true,
+          decidedBy: proposal.decisionAudit?.actorRef ?? null,
+          decidedVia: proposal.decisionAudit?.via ?? null,
+          reason: proposal.decisionAudit?.reason ?? null
+        }
+      });
+    return { ...message, parts };
+  });
+  const knownMessages = new Set(messages.map((message) => message.id));
+  const knownOutcomes = new Set(
+    messages.map((message) => outcomeId(message.metadata)).filter(Boolean)
+  );
+  for (const fact of facts) {
+    const id = fact.actionProposalOutcome?.id;
+    if (id === void 0 || knownMessages.has(fact.id) || knownOutcomes.has(id)) continue;
+    const message = storedMessageToUiMessage(fact);
+    messages.push({
+      ...message,
+      metadata: {
+        ...record(message.metadata) ? message.metadata : {},
+        actionProposalOutcomeId: id
+      }
+    });
+    knownMessages.add(fact.id);
+    knownOutcomes.add(id);
+  }
+  return messages;
+}
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function outcomeId(value) {
+  return record(value) && typeof value.actionProposalOutcomeId === "string" ? value.actionProposalOutcomeId : void 0;
+}
+
+// src/approvals/use-action-proposals.ts
+function useActionProposals(backend, threadId, setMessages, refreshKey, pollMs = 1e3) {
+  const [items, setItems] = (0, import_react22.useState)([]);
+  const [error, setError] = (0, import_react22.useState)(null);
+  const latest = (0, import_react22.useRef)({ threadId, setMessages });
+  latest.current = { threadId, setMessages };
+  const mounted = (0, import_react22.useRef)(true);
+  const requests = (0, import_react22.useRef)(/* @__PURE__ */ new Map());
+  (0, import_react22.useEffect)(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const refresh = (0, import_react22.useCallback)(async () => {
+    if (threadId === void 0 || backend.listActionProposals === void 0) return;
+    const pending = requests.current.get(threadId);
+    if (pending) return pending;
+    const request = (async () => {
+      try {
+        const proposals = await backend.listActionProposals?.({ threadId });
+        if (!mounted.current || latest.current.threadId !== threadId || !Array.isArray(proposals))
+          return;
+        const admitted = proposals.some(
+          (proposal) => proposal.outcomeDelivery?.status === "admitted"
+        );
+        const facts = admitted ? (await backend.getThread(threadId)).messages.filter(
+          (message) => message.actionProposalOutcome !== void 0
+        ) : [];
+        if (!mounted.current || latest.current.threadId !== threadId) return;
+        setItems(proposals);
+        setError(null);
+        latest.current.setMessages(
+          (current) => reconcileProposalMessages(current, proposals, facts)
+        );
+      } catch (cause) {
+        if (mounted.current && latest.current.threadId === threadId)
+          setError(cause instanceof Error ? cause : new Error(String(cause)));
+      }
+    })();
+    requests.current.set(threadId, request);
+    try {
+      await request;
+    } finally {
+      requests.current.delete(threadId);
+    }
+  }, [backend, threadId]);
+  (0, import_react22.useEffect)(() => {
+    setItems([]);
+    setError(null);
+  }, [threadId]);
+  (0, import_react22.useEffect)(() => {
+    void refresh();
+  }, [refresh, refreshKey]);
+  (0, import_react22.useEffect)(() => {
+    if (!items.some(proposalNeedsPolling) || pollMs <= 0) return;
+    const timer = setInterval(() => {
+      void refresh();
+    }, pollMs);
+    return () => clearInterval(timer);
+  }, [items, pollMs, refresh]);
+  (0, import_react22.useEffect)(() => {
+    const refetch = () => {
+      void refresh();
+    };
+    const visible = () => {
+      if (document.visibilityState === "visible") refetch();
+    };
+    window.addEventListener("focus", refetch);
+    window.addEventListener("online", refetch);
+    document.addEventListener("visibilitychange", visible);
+    return () => {
+      window.removeEventListener("focus", refetch);
+      window.removeEventListener("online", refetch);
+      document.removeEventListener("visibilitychange", visible);
+    };
+  }, [refresh]);
+  return { items, error, refresh };
+}
+
+// src/use-agent-chat.ts
 var EMPTY_QUEUE = { items: [], paused: null };
 var localQueueSequence = 0;
 function queuedUserMessage(turn) {
@@ -5287,13 +5685,16 @@ function localChatId() {
   return `local-chat-${localChatSequence}`;
 }
 function useAgentChat(options = {}) {
-  const latest = (0, import_react23.useRef)(options);
+  const providerCapabilities = useAgentUiCapabilities();
+  const capabilitiesRef = (0, import_react24.useRef)(providerCapabilities);
+  capabilitiesRef.current = providerCapabilities;
+  const latest = (0, import_react24.useRef)(options);
   latest.current = options;
   const resolved = useAgentBackend(options.backend);
-  const client = (0, import_react23.useRef)(resolved).current;
-  const createdThreadId = (0, import_react23.useRef)(void 0);
-  const chatIdRef = (0, import_react23.useRef)(options.threadId ?? localChatId());
-  const boundThreadRef = (0, import_react23.useRef)(options.threadId);
+  const client = (0, import_react24.useRef)(resolved).current;
+  const createdThreadId = (0, import_react24.useRef)(void 0);
+  const chatIdRef = (0, import_react24.useRef)(options.threadId ?? localChatId());
+  const boundThreadRef = (0, import_react24.useRef)(options.threadId);
   if (options.threadId !== boundThreadRef.current) {
     boundThreadRef.current = options.threadId;
     const adopting = options.threadId !== void 0 && options.threadId === createdThreadId.current;
@@ -5303,39 +5704,43 @@ function useAgentChat(options = {}) {
     }
   }
   const chatId = chatIdRef.current;
-  const [runId, setRunId] = (0, import_react23.useState)(options.resumeRunId);
-  const runIdRef = (0, import_react23.useRef)(runId);
+  const [runId, setRunId] = (0, import_react24.useState)(options.resumeRunId);
+  const runIdRef = (0, import_react24.useRef)(runId);
   runIdRef.current = runId;
-  const settlingRunIdRef = (0, import_react23.useRef)(void 0);
-  const autoResumeRunIdRef = (0, import_react23.useRef)(void 0);
-  const [activeRunId, setActiveRunId] = (0, import_react23.useState)(null);
-  const [historyFor, setHistoryFor] = (0, import_react23.useState)(void 0);
-  const [historyError, setHistoryError] = (0, import_react23.useState)(null);
-  const [runError, setRunError] = (0, import_react23.useState)(null);
-  const [threadModel, setThreadModel] = (0, import_react23.useState)(null);
-  const [pickedModel, setPickedModel] = (0, import_react23.useState)(void 0);
-  const pickedModelRef = (0, import_react23.useRef)(pickedModel);
+  const settlingRunIdRef = (0, import_react24.useRef)(void 0);
+  const autoResumeRunIdRef = (0, import_react24.useRef)(void 0);
+  const [activeRunId, setActiveRunId] = (0, import_react24.useState)(null);
+  const [historyFor, setHistoryFor] = (0, import_react24.useState)(void 0);
+  const [historyError, setHistoryError] = (0, import_react24.useState)(null);
+  const [runError, setRunError] = (0, import_react24.useState)(null);
+  const [threadModel, setThreadModel] = (0, import_react24.useState)(null);
+  const [threadPersona, setThreadPersona] = (0, import_react24.useState)(null);
+  const [pickedModel, setPickedModel] = (0, import_react24.useState)(void 0);
+  const pickedModelRef = (0, import_react24.useRef)(pickedModel);
   pickedModelRef.current = pickedModel;
-  const lockedRef = (0, import_react23.useRef)(false);
-  const pendingPin = (0, import_react23.useRef)(void 0);
-  const regenerateNext = (0, import_react23.useRef)(false);
-  const currentThreadId = (0, import_react23.useCallback)(
+  const lockedRef = (0, import_react24.useRef)(false);
+  const pendingPin = (0, import_react24.useRef)(void 0);
+  const regenerateNext = (0, import_react24.useRef)(false);
+  const currentThreadId = (0, import_react24.useCallback)(
     () => latest.current.threadId ?? createdThreadId.current,
     []
   );
-  const [queueState, setQueueState] = (0, import_react23.useState)(EMPTY_QUEUE);
-  const queueStateRef = (0, import_react23.useRef)(queueState);
-  const applyQueue = (0, import_react23.useCallback)((next) => {
+  const [queueState, setQueueState] = (0, import_react24.useState)(EMPTY_QUEUE);
+  const queueStateRef = (0, import_react24.useRef)(queueState);
+  const applyQueue = (0, import_react24.useCallback)((next) => {
     queueStateRef.current = next;
     setQueueState(next);
   }, []);
-  const [pendingSends, setPendingSends] = (0, import_react23.useState)([]);
-  const [queueError, setQueueError] = (0, import_react23.useState)(null);
-  const handoff = (0, import_react23.useRef)(void 0);
-  const queuedSend = (0, import_react23.useRef)(void 0);
-  const threadWaiters = (0, import_react23.useRef)([]);
-  const turnBody = (0, import_react23.useCallback)(() => {
+  const [pendingSends, setPendingSends] = (0, import_react24.useState)([]);
+  const [queueError, setQueueError] = (0, import_react24.useState)(null);
+  const handoff = (0, import_react24.useRef)(void 0);
+  const queuedSend = (0, import_react24.useRef)(void 0);
+  const proposalRefreshRef = (0, import_react24.useRef)(async () => {
+  });
+  const threadWaiters = (0, import_react24.useRef)([]);
+  const turnBody = (0, import_react24.useCallback)(() => {
     const current = latest.current;
+    if (current.persona !== void 0) setThreadPersona(current.persona);
     const pageContext = current.getPageContext?.() ?? null;
     const threadId = currentThreadId();
     const model = current.model ?? (lockedRef.current ? void 0 : pickedModelRef.current);
@@ -5343,14 +5748,16 @@ function useAgentChat(options = {}) {
       // Read per send: a host that switches agents before the first message (a picker on a new
       // chat) sends the one picked now, not the one this chat mounted with.
       ...current.agent !== void 0 ? { agent: current.agent } : {},
+      ...current.persona !== void 0 ? { persona: current.persona } : {},
       ...threadId !== void 0 ? { threadId } : {},
       ...model !== void 0 ? { model } : {},
-      ...pageContext ? { pageContext } : {}
+      ...pageContext ? { pageContext } : {},
+      ...(current.uiCapabilities ?? capabilitiesRef.current) === void 0 ? {} : { uiCapabilities: current.uiCapabilities ?? capabilitiesRef.current }
     };
   }, [currentThreadId]);
-  const [connection, setConnection] = (0, import_react23.useState)({ status: "live" });
-  const resyncAfterSettle = (0, import_react23.useRef)(false);
-  const transport = (0, import_react23.useMemo)(() => {
+  const [connection, setConnection] = (0, import_react24.useState)({ status: "live" });
+  const resyncAfterSettle = (0, import_react24.useRef)(false);
+  const transport = (0, import_react24.useMemo)(() => {
     function onMeta(meta) {
       settlingRunIdRef.current = meta.runId;
       setRunId(meta.runId);
@@ -5402,14 +5809,15 @@ function useAgentChat(options = {}) {
       }
     });
   }, []);
-  const backgroundRef = (0, import_react23.useRef)(() => Promise.resolve());
-  const chat = (0, import_react22.useChat)({
+  const backgroundRef = (0, import_react24.useRef)(() => Promise.resolve());
+  const chat = (0, import_react23.useChat)({
     transport,
     id: chatId,
     resume: options.resumeRunId !== void 0,
     ...options.initialMessages !== void 0 ? { messages: options.initialMessages } : {},
     onData: (part) => {
       latest.current.onData?.(part);
+      if (part.type === "data-proposal-decision") void proposalRefreshRef.current();
       if (part.type === "data-queue") {
         onQueueData(part.data);
       }
@@ -5456,7 +5864,7 @@ function useAgentChat(options = {}) {
       }
     }
   });
-  const chatRef = (0, import_react23.useRef)(chat);
+  const chatRef = (0, import_react24.useRef)(chat);
   chatRef.current = chat;
   function onQueueData(data) {
     const frame = data ?? {};
@@ -5504,13 +5912,14 @@ function useAgentChat(options = {}) {
     } catch {
     }
   }
-  const firstChatId = (0, import_react23.useRef)(chatId);
-  (0, import_react23.useEffect)(() => {
+  const firstChatId = (0, import_react24.useRef)(chatId);
+  (0, import_react24.useEffect)(() => {
     if (chatId === firstChatId.current) return;
     firstChatId.current = chatId;
     setRunId(void 0);
     setActiveRunId(null);
     setThreadModel(null);
+    setThreadPersona(null);
     setPickedModel(void 0);
     setBackgroundRuns([]);
     setHistoryError(null);
@@ -5523,7 +5932,7 @@ function useAgentChat(options = {}) {
     handoff.current = void 0;
     queuedSend.current = void 0;
   }, [chatId]);
-  (0, import_react23.useEffect)(() => {
+  (0, import_react24.useEffect)(() => {
     const threadId = options.threadId;
     if (threadId === void 0) return;
     if (threadId === createdThreadId.current) return;
@@ -5539,6 +5948,7 @@ function useAgentChat(options = {}) {
         const stored = Array.isArray(thread.messages) ? thread.messages : [];
         setActiveRunId(active);
         setThreadModel(thread.model ?? null);
+        setThreadPersona(thread.persona ?? null);
         setHistoryError(null);
         const queue2 = thread.queue ?? EMPTY_QUEUE;
         applyQueue(queue2);
@@ -5569,8 +5979,8 @@ function useAgentChat(options = {}) {
     };
   }, [client, chatId, options.threadId]);
   const isLoadingHistory = options.threadId !== void 0 && options.threadId !== createdThreadId.current && options.history !== false && options.initialMessages === void 0 && historyFor !== options.threadId;
-  const turnInFlight = (0, import_react23.useRef)(false);
-  const isTurnInFlight = (0, import_react23.useCallback)(
+  const turnInFlight = (0, import_react24.useRef)(false);
+  const isTurnInFlight = (0, import_react24.useCallback)(
     () => turnInFlight.current || transport.isAttemptLive,
     [transport]
   );
@@ -5579,20 +5989,20 @@ function useAgentChat(options = {}) {
     enabled: options.quota !== false && typeof client.getQuota === "function"
   });
   const blocked = options.blocked !== void 0 ? options.blocked : quota.blocked;
-  const blockedRef = (0, import_react23.useRef)(blocked);
+  const blockedRef = (0, import_react24.useRef)(blocked);
   blockedRef.current = blocked;
   const whileRunning = typeof client.enqueueMessage === "function" ? options.whileRunning ?? "queue" : "block";
-  const whileRunningRef = (0, import_react23.useRef)(whileRunning);
+  const whileRunningRef = (0, import_react24.useRef)(whileRunning);
   whileRunningRef.current = whileRunning;
-  const canQueueRef = (0, import_react23.useRef)(false);
+  const canQueueRef = (0, import_react24.useRef)(false);
   canQueueRef.current = typeof client.enqueueMessage === "function";
-  const threadForQueue = (0, import_react23.useCallback)(async () => {
+  const threadForQueue = (0, import_react24.useCallback)(async () => {
     const known = currentThreadId();
     if (known !== void 0) return known;
     if (!isTurnInFlight()) throw new Error("queue: this chat has no thread yet");
     return new Promise((resolve) => threadWaiters.current.push(resolve));
   }, [currentThreadId, isTurnInFlight]);
-  const queueCall = (0, import_react23.useCallback)(async (run) => {
+  const queueCall = (0, import_react24.useCallback)(async (run) => {
     try {
       const result = await run();
       setQueueError(null);
@@ -5602,7 +6012,7 @@ function useAgentChat(options = {}) {
       throw error;
     }
   }, []);
-  const enqueue = (0, import_react23.useCallback)(
+  const enqueue = (0, import_react24.useCallback)(
     async (text2, {
       attachments = [],
       mode = "queue"
@@ -5650,7 +6060,7 @@ function useAgentChat(options = {}) {
     },
     [client, queueCall, threadForQueue, turnBody, applyQueue, isTurnInFlight]
   );
-  const sendMessage = (0, import_react23.useCallback)(
+  const sendMessage = (0, import_react24.useCallback)(
     async (message, options2) => {
       const block = blockedRef.current;
       if (block != null) throw new QuotaBlockedError(block);
@@ -5674,7 +6084,7 @@ function useAgentChat(options = {}) {
     },
     [isTurnInFlight, enqueue]
   );
-  const removeQueued = (0, import_react23.useCallback)(
+  const removeQueued = (0, import_react24.useCallback)(
     async (id) => {
       const previous = queueStateRef.current;
       applyQueue({ ...previous, items: previous.items.filter((item) => item.id !== id) });
@@ -5687,7 +6097,7 @@ function useAgentChat(options = {}) {
     },
     [client, queueCall, applyQueue]
   );
-  const interruptQueued = (0, import_react23.useCallback)(
+  const interruptQueued = (0, import_react24.useCallback)(
     async (id) => {
       const previous = queueStateRef.current;
       const moving = previous.items.find((item) => item.id === id);
@@ -5722,7 +6132,7 @@ function useAgentChat(options = {}) {
     },
     [client, queueCall, applyQueue, isTurnInFlight]
   );
-  const editQueued = (0, import_react23.useCallback)(
+  const editQueued = (0, import_react24.useCallback)(
     async (id, text2) => {
       applyQueue(
         await queueCall(
@@ -5732,7 +6142,7 @@ function useAgentChat(options = {}) {
     },
     [client, queueCall, applyQueue]
   );
-  const moveQueued = (0, import_react23.useCallback)(
+  const moveQueued = (0, import_react24.useCallback)(
     async (id, index) => {
       const previous = queueStateRef.current;
       const moving = previous.items.find((item) => item.id === id);
@@ -5754,12 +6164,12 @@ function useAgentChat(options = {}) {
     },
     [client, queueCall, applyQueue]
   );
-  const clearQueue = (0, import_react23.useCallback)(async () => {
+  const clearQueue = (0, import_react24.useCallback)(async () => {
     const threadId = currentThreadId();
     if (threadId === void 0) return;
     applyQueue(await queueCall(() => requireBackendMethod(client, "clearQueue")(threadId)));
   }, [client, queueCall, currentThreadId, applyQueue]);
-  const resumeQueue = (0, import_react23.useCallback)(async () => {
+  const resumeQueue = (0, import_react24.useCallback)(async () => {
     const threadId = currentThreadId();
     if (threadId === void 0) return;
     const before = queueStateRef.current;
@@ -5777,7 +6187,7 @@ function useAgentChat(options = {}) {
       else attachTo(turn);
     }
   }, [client, queueCall, currentThreadId, applyQueue, isTurnInFlight]);
-  const resumeQueueRef = (0, import_react23.useRef)(resumeQueue);
+  const resumeQueueRef = (0, import_react24.useRef)(resumeQueue);
   resumeQueueRef.current = resumeQueue;
   const queuedItems = [
     ...pendingSends.filter((item) => item.interrupt),
@@ -5807,7 +6217,7 @@ function useAgentChat(options = {}) {
     resume: resumeQueue,
     error: queueError
   };
-  const addToolResult = (0, import_react23.useCallback)(
+  const addToolResult = (0, import_react24.useCallback)(
     ({ tool, toolCallId, output }) => chatRef.current.addToolResult({
       tool,
       toolCallId,
@@ -5815,8 +6225,8 @@ function useAgentChat(options = {}) {
     }),
     []
   );
-  const [backgroundRuns, setBackgroundRuns] = (0, import_react23.useState)([]);
-  const refreshBackground = (0, import_react23.useCallback)(async () => {
+  const [backgroundRuns, setBackgroundRuns] = (0, import_react24.useState)([]);
+  const refreshBackground = (0, import_react24.useCallback)(async () => {
     const threadId = currentThreadId();
     if (threadId === void 0) {
       return;
@@ -5836,13 +6246,13 @@ function useAgentChat(options = {}) {
   }, [client, currentThreadId]);
   backgroundRef.current = refreshBackground;
   const isWorking = backgroundRuns.some((run) => run.status === "running");
-  (0, import_react23.useEffect)(() => {
+  (0, import_react24.useEffect)(() => {
     if (options.background !== true || options.threadId === void 0) {
       return;
     }
     void refreshBackground();
   }, [options.background, options.threadId, chatId, refreshBackground]);
-  (0, import_react23.useEffect)(() => {
+  (0, import_react24.useEffect)(() => {
     const every = latest.current.backgroundPollMs ?? 5e3;
     if (latest.current.background !== true || !isWorking || every <= 0) {
       return;
@@ -5850,7 +6260,15 @@ function useAgentChat(options = {}) {
     const timer = setInterval(() => void refreshBackground(), every);
     return () => clearInterval(timer);
   }, [isWorking, refreshBackground]);
-  const cancel = (0, import_react23.useCallback)(async () => {
+  const proposals = useActionProposals(
+    client,
+    options.proposals === false || options.proposals !== true && options.history === false && options.resume === false ? void 0 : currentThreadId(),
+    (update) => chatRef.current.setMessages(update),
+    `${chat.status}:${connection.status}`,
+    options.proposalPollMs
+  );
+  proposalRefreshRef.current = proposals.refresh;
+  const cancel = (0, import_react24.useCallback)(async () => {
     chatRef.current.stop();
     const active = runIdRef.current;
     if (active) {
@@ -5867,8 +6285,23 @@ function useAgentChat(options = {}) {
       }
     }
   }, [client, currentThreadId, applyQueue]);
-  const approve = (0, import_react23.useCallback)(
-    async ({ toolCallId, remember, via }) => {
+  const approve = (0, import_react24.useCallback)(
+    async ({ toolCallId, target, remember, via }) => {
+      if (target?.kind === "proposal") {
+        const threadId = target.threadId ?? currentThreadId();
+        if (threadId === void 0)
+          throw new Error("A proposal decision requires its thread scope");
+        await requireBackendMethod(
+          client,
+          "approveActionProposal"
+        )({
+          threadId,
+          proposalId: target.proposalId,
+          ...remember === true ? { remember: true } : {}
+        });
+        await proposals.refresh();
+        return;
+      }
       await requireBackendMethod(
         client,
         "approveToolCall"
@@ -5878,10 +6311,25 @@ function useAgentChat(options = {}) {
         ...via !== void 0 ? { via } : {}
       });
     },
-    [client]
+    [client, currentThreadId, proposals.refresh]
   );
-  const reject = (0, import_react23.useCallback)(
-    async ({ toolCallId, reason, via }) => {
+  const reject = (0, import_react24.useCallback)(
+    async ({ toolCallId, target, reason, via }) => {
+      if (target?.kind === "proposal") {
+        const threadId = target.threadId ?? currentThreadId();
+        if (threadId === void 0)
+          throw new Error("A proposal decision requires its thread scope");
+        await requireBackendMethod(
+          client,
+          "rejectActionProposal"
+        )({
+          threadId,
+          proposalId: target.proposalId,
+          ...reason === void 0 ? {} : { reason }
+        });
+        await proposals.refresh();
+        return;
+      }
       await requireBackendMethod(
         client,
         "rejectToolCall"
@@ -5891,9 +6339,9 @@ function useAgentChat(options = {}) {
         ...via !== void 0 ? { via } : {}
       });
     },
-    [client]
+    [client, currentThreadId, proposals.refresh]
   );
-  const answer = (0, import_react23.useCallback)(
+  const answer = (0, import_react24.useCallback)(
     async ({ toolCallId, answers, via }) => {
       await requireBackendMethod(
         client,
@@ -5906,7 +6354,7 @@ function useAgentChat(options = {}) {
     },
     [client]
   );
-  const skip = (0, import_react23.useCallback)(
+  const skip = (0, import_react24.useCallback)(
     async ({ toolCallId, via }) => {
       await requireBackendMethod(
         client,
@@ -5915,7 +6363,7 @@ function useAgentChat(options = {}) {
     },
     [client]
   );
-  const regenerate = (0, import_react23.useCallback)(
+  const regenerate = (0, import_react24.useCallback)(
     (_input) => {
       const block = blockedRef.current;
       if (block != null) throw new QuotaBlockedError(block);
@@ -5928,7 +6376,7 @@ function useAgentChat(options = {}) {
     },
     [isTurnInFlight]
   );
-  const storedIdOf = (0, import_react23.useCallback)(
+  const storedIdOf = (0, import_react24.useCallback)(
     async (messageId, threadId) => {
       const message = chatRef.current.messages.find((candidate) => candidate.id === messageId);
       const runOf = message?.metadata?.runId;
@@ -5939,7 +6387,7 @@ function useAgentChat(options = {}) {
     },
     [client]
   );
-  const fork = (0, import_react23.useCallback)(
+  const fork = (0, import_react24.useCallback)(
     async ({
       messageId,
       threadId
@@ -5954,7 +6402,7 @@ function useAgentChat(options = {}) {
     },
     [client, currentThreadId, storedIdOf]
   );
-  const truncateFrom = (0, import_react23.useCallback)(
+  const truncateFrom = (0, import_react24.useCallback)(
     async ({ messageId, threadId }) => {
       const target = threadId ?? currentThreadId();
       if (target === void 0) throw new Error("truncateFrom: this chat has no thread yet");
@@ -5963,7 +6411,7 @@ function useAgentChat(options = {}) {
     },
     [client, currentThreadId, storedIdOf]
   );
-  const promote = (0, import_react23.useCallback)(
+  const promote = (0, import_react24.useCallback)(
     async ({ threadId } = {}) => {
       const target = threadId ?? currentThreadId();
       if (target === void 0) throw new Error("promote: this chat has no thread yet");
@@ -5972,24 +6420,24 @@ function useAgentChat(options = {}) {
     },
     [client, currentThreadId]
   );
-  const [modelsWanted, setModelsWanted] = (0, import_react23.useState)(false);
-  const modelsWantedRef = (0, import_react23.useRef)(modelsWanted);
+  const [modelsWanted, setModelsWanted] = (0, import_react24.useState)(false);
+  const modelsWantedRef = (0, import_react24.useRef)(modelsWanted);
   modelsWantedRef.current = modelsWanted;
   const catalog = useModels({
     backend: client,
     ...options.agent !== void 0 ? { agent: options.agent } : {},
     enabled: modelsWanted && typeof client.listModels === "function"
   });
-  const wantModels = (0, import_react23.useCallback)(() => {
+  const wantModels = (0, import_react24.useCallback)(() => {
     if (modelsWantedRef.current) return;
     modelsWantedRef.current = true;
     queueMicrotask(() => setModelsWanted(true));
   }, []);
   lockedRef.current = catalog.locked !== null;
-  const selectModel = (0, import_react23.useCallback)((id) => {
+  const selectModel = (0, import_react24.useCallback)((id) => {
     if (!lockedRef.current) setPickedModel(id);
   }, []);
-  const pinToThread = (0, import_react23.useCallback)(
+  const pinToThread = (0, import_react24.useCallback)(
     async (model) => {
       const threadId = currentThreadId();
       setThreadModel(model);
@@ -6029,14 +6477,14 @@ function useAgentChat(options = {}) {
   };
   const status = connection.status === "reconnecting" ? "reconnecting" : chat.status;
   const isBusy = status === "submitted" || status === "streaming" || status === "reconnecting";
-  const isBusyRef = (0, import_react23.useRef)(isBusy);
+  const isBusyRef = (0, import_react24.useRef)(isBusy);
   isBusyRef.current = isBusy;
   const files = useAttachments({ ...options.composer, backend: client });
-  const [text, setText] = (0, import_react23.useState)("");
+  const [text, setText] = (0, import_react24.useState)("");
   const blockedBy = blocked != null ? "quota" : files.isUploading ? "uploading" : isBusy && whileRunning === "block" ? "busy" : text.trim().length === 0 && files.refs.length === 0 ? "empty" : null;
-  const composerRef = (0, import_react23.useRef)({ text, files, blockedBy });
+  const composerRef = (0, import_react24.useRef)({ text, files, blockedBy });
   composerRef.current = { text, files, blockedBy };
-  const submit = (0, import_react23.useCallback)(
+  const submit = (0, import_react24.useCallback)(
     async (options2) => {
       const current = composerRef.current;
       const asked = canQueueRef.current ? options2?.mode : void 0;
@@ -6118,6 +6566,7 @@ function useAgentChat(options = {}) {
     addToolResult,
     /** Sub-agents this conversation started and did not wait for. */
     background,
+    proposals,
     runId,
     /** The loaded thread's running turn, or `null` once read with none. */
     activeRunId,
@@ -6150,6 +6599,11 @@ function useAgentChat(options = {}) {
     queue,
     /** The model picker: `list`, `selected`, `select(id)`, `pinToThread(id)`. */
     models,
+    /**
+     * The persona pinned on this thread (`ThreadSummary.persona`), or `null` when none is — what a
+     * persona picker on a reopened thread starts from (`?? agent.defaultPersona`).
+     */
+    threadPersona,
     /** The caller's budget (`GET <base>/quota`); `quota.blocked` gates sends. */
     quota,
     /** The window blocking sends right now (the `blocked` option, else the quota report's). */
@@ -6237,8 +6691,10 @@ function isRunNotActiveError(error) {
   onThreadsEvent,
   persistSpeechLang,
   phraseFor,
+  proposalNeedsPolling,
   readPath,
   readReasoningMs,
+  reconcileProposalMessages,
   reframeAgUiStream,
   requireBackendMethod,
   resolveResultView,
@@ -6246,6 +6702,7 @@ function isRunNotActiveError(error) {
   storedThreadToUiMessages,
   toolCallState,
   toolCatalogFrom,
+  useActionProposals,
   useAgentBackend,
   useAgentChat,
   useAgentConfig,