@athenaintel/react 0.59.0 → 0.60.1

package/dist/chat/client-tool-write-consent.d.ts

@@ -0,0 +1,71 @@
+import type { ClientToolWriteConsentDecision } from '../agent-runtime/src/index';
+/** One write tool of a batch waiting on the person. */
+export interface ClientToolWriteConsentTool {
+    /** The tool's name, as the model calls it. */
+    name: string;
+    /** What it does, when the tool said (`requiresWriteConsent(…, { summary })`). */
+    summary?: string;
+}
+/** The question a parked batch of write calls puts to the person. */
+export interface ClientToolWriteConsentRequest {
+    /** The parked request the answer resumes. */
+    requestId: string;
+    /** The conversation the answer covers. */
+    threadId: string;
+    /** The batch's write tools, each once. */
+    tools: readonly ClientToolWriteConsentTool[];
+}
+/**
+ * A host's own consent UI (`AthenaProviderProps.confirmClientToolWrites`).
+ * Resolve `true` to allow the conversation's writes, `false` to decline this
+ * batch. `signal` aborts when the question no longer has a call to answer
+ * (the run was stopped): close the dialog then; the value is ignored.
+ */
+export type ClientToolWriteConfirmer = (request: ClientToolWriteConsentRequest & {
+    signal: AbortSignal;
+}) => Promise<boolean>;
+export interface ClientToolWriteConsentStore {
+    /** The question on screen, or `null`. */
+    getPending(): ClientToolWriteConsentRequest | null;
+    subscribe(listener: () => void): () => void;
+    /** Whether the person already allowed writes in this conversation. */
+    isGranted(threadId: string): boolean;
+    /** Put the question to the person; resolves with their answer, or `abandoned`. */
+    ask(request: ClientToolWriteConsentRequest): Promise<ClientToolWriteConsentDecision>;
+    /** The person's answer to the pending question. */
+    answer(args: {
+        requestId: string;
+        allow: boolean;
+    }): void;
+    /** The pending question lost its call (stop, another conversation): close it. */
+    abandon(requestId: string): void;
+    /** Record a consent the host's own UI collected. */
+    grant(threadId: string): void;
+    /** A mounted card registers itself, so a question nobody can see is reported. */
+    registerCard(): () => void;
+    /** The store's person is gone: close the pending question and forget every yes. */
+    dispose(): void;
+}
+export declare function createClientToolWriteConsentStore(): ClientToolWriteConsentStore;
+/**
+ * The consent store for one signed-in person on one Athena. `scope` names
+ * both (the provider passes the session principal and the sync host): when it
+ * changes, the previous person's store is disposed (its question closed, its
+ * yeses forgotten) and the next person starts with none.
+ */
+export declare function useClientToolWriteConsentStore(scope: string): ClientToolWriteConsentStore;
+/** Provided by `AthenaProvider`; `null` outside one. */
+export declare const ClientToolWriteConsentContext: import("react").Context<ClientToolWriteConsentStore | null>;
+export interface ClientToolWriteConsent {
+    /** The question waiting on the person, or `null`. */
+    request: ClientToolWriteConsentRequest | null;
+    /** Allow the conversation's writes and run the waiting calls. */
+    allow: () => void;
+    /** Decline the waiting calls; the agent is told, and a later call asks again. */
+    decline: () => void;
+}
+/**
+ * The write-consent question for the chat the nearest `AthenaProvider` shows,
+ * for a host that draws its own card. Calling it marks the question as shown.
+ */
+export declare function useClientToolWriteConsent(): ClientToolWriteConsent;

package/dist/chat/client-tool-write-consent.js

@@ -0,0 +1,111 @@
+import { useContext, useSyncExternalStore, useEffect, useCallback, createContext, useState } from "react";
+import { athenaDiagnostics } from "../diagnostics/athena-diagnostics.js";
+import { AthenaSdkError } from "../diagnostics/errors.js";
+function createClientToolWriteConsentStore() {
+  let pending = null;
+  let cards = 0;
+  const granted = /* @__PURE__ */ new Set();
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => {
+    for (const listener of Array.from(listeners)) listener();
+  };
+  const settle = (decision) => {
+    const settled = pending;
+    pending = null;
+    settled == null ? void 0 : settled.resolve(decision);
+    notify();
+  };
+  return {
+    getPending: () => (pending == null ? void 0 : pending.request) ?? null,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    isGranted: (threadId) => granted.has(threadId),
+    ask(request) {
+      if (granted.has(request.threadId)) return Promise.resolve("proceed");
+      if (pending) settle("abandoned");
+      if (cards === 0) {
+        athenaDiagnostics.emit("sdk.config.warning", {
+          level: "warn",
+          error: new AthenaSdkError({
+            code: "config_invalid",
+            message: "A frontend tool is waiting for the person to allow it, and nothing on screen asks them.",
+            hint: "Render <AthenaChat> (it draws the question), mount <StatewireClientToolConsentCard>, or pass confirmClientToolWrites on <AthenaProvider>. The run stays parked until the question is answered.",
+            context: { tools: request.tools.map((tool) => tool.name) }
+          }),
+          data: { tools: request.tools.map((tool) => tool.name) }
+        });
+      }
+      return new Promise((resolve) => {
+        pending = { request, resolve };
+        notify();
+      });
+    },
+    answer({ requestId, allow }) {
+      if ((pending == null ? void 0 : pending.request.requestId) !== requestId) return;
+      if (allow) granted.add(pending.request.threadId);
+      settle(allow ? "proceed" : "declined");
+    },
+    abandon(requestId) {
+      if ((pending == null ? void 0 : pending.request.requestId) !== requestId) return;
+      settle("abandoned");
+    },
+    grant(threadId) {
+      granted.add(threadId);
+    },
+    registerCard() {
+      cards += 1;
+      return () => {
+        cards -= 1;
+      };
+    },
+    dispose() {
+      granted.clear();
+      if (pending) settle("abandoned");
+    }
+  };
+}
+function useClientToolWriteConsentStore(scope) {
+  const [held, setHeld] = useState(() => ({ scope, store: createClientToolWriteConsentStore() }));
+  let current = held;
+  if (held.scope !== scope) {
+    current = { scope, store: createClientToolWriteConsentStore() };
+    setHeld(current);
+  }
+  const { store } = current;
+  useEffect(() => () => store.dispose(), [store]);
+  return store;
+}
+const ClientToolWriteConsentContext = createContext(
+  null
+);
+const NO_SUBSCRIPTION = () => () => {
+};
+const NO_PENDING = () => null;
+function useClientToolWriteConsent() {
+  const store = useContext(ClientToolWriteConsentContext);
+  const request = useSyncExternalStore(
+    (store == null ? void 0 : store.subscribe) ?? NO_SUBSCRIPTION,
+    (store == null ? void 0 : store.getPending) ?? NO_PENDING,
+    NO_PENDING
+  );
+  useEffect(() => store == null ? void 0 : store.registerCard(), [store]);
+  const requestId = request == null ? void 0 : request.requestId;
+  const allow = useCallback(() => {
+    if (requestId !== void 0) store == null ? void 0 : store.answer({ requestId, allow: true });
+  }, [requestId, store]);
+  const decline = useCallback(() => {
+    if (requestId !== void 0) store == null ? void 0 : store.answer({ requestId, allow: false });
+  }, [requestId, store]);
+  return { request, allow, decline };
+}
+export {
+  ClientToolWriteConsentContext,
+  createClientToolWriteConsentStore,
+  useClientToolWriteConsent,
+  useClientToolWriteConsentStore
+};
+//# sourceMappingURL=client-tool-write-consent.js.map

package/dist/chat/client-tool-write-consent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tool-write-consent.js","sources":["../../src/chat/client-tool-write-consent.ts"],"sourcesContent":["'use client';\n\nimport type { ClientToolWriteConsentDecision } from '@athenaintel/agent-runtime';\nimport {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useState,\n  useSyncExternalStore,\n} from 'react';\nimport { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport { AthenaSdkError } from '../diagnostics/errors';\n\n/*\n * Write consent for the app's own frontend tools. A tool marked with\n * `requiresWriteConsent` parks its first call in a conversation until the\n * person answers; this store holds that question between the client-tool\n * bridge (which asks) and whatever draws it (`StatewireClientToolConsentCard`\n * in `AthenaChat`, or a host's own card on `useClientToolWriteConsent`).\n *\n * Allowing covers the rest of the conversation, as Athena's own apps do, for\n * the person who allowed it: a store belongs to one signed-in person on one\n * Athena (`useClientToolWriteConsentStore`), so someone else signing in to the\n * same mounted chat is asked for themselves. Nothing is remembered across a\n * reload: the next call asks again.\n */\n\n/** One write tool of a batch waiting on the person. */\nexport interface ClientToolWriteConsentTool {\n  /** The tool's name, as the model calls it. */\n  name: string;\n  /** What it does, when the tool said (`requiresWriteConsent(…, { summary })`). */\n  summary?: string;\n}\n\n/** The question a parked batch of write calls puts to the person. */\nexport interface ClientToolWriteConsentRequest {\n  /** The parked request the answer resumes. */\n  requestId: string;\n  /** The conversation the answer covers. */\n  threadId: string;\n  /** The batch's write tools, each once. */\n  tools: readonly ClientToolWriteConsentTool[];\n}\n\n/**\n * A host's own consent UI (`AthenaProviderProps.confirmClientToolWrites`).\n * Resolve `true` to allow the conversation's writes, `false` to decline this\n * batch. `signal` aborts when the question no longer has a call to answer\n * (the run was stopped): close the dialog then; the value is ignored.\n */\nexport type ClientToolWriteConfirmer = (\n  request: ClientToolWriteConsentRequest & { signal: AbortSignal },\n) => Promise<boolean>;\n\nexport interface ClientToolWriteConsentStore {\n  /** The question on screen, or `null`. */\n  getPending(): ClientToolWriteConsentRequest | null;\n  subscribe(listener: () => void): () => void;\n  /** Whether the person already allowed writes in this conversation. */\n  isGranted(threadId: string): boolean;\n  /** Put the question to the person; resolves with their answer, or `abandoned`. */\n  ask(request: ClientToolWriteConsentRequest): Promise<ClientToolWriteConsentDecision>;\n  /** The person's answer to the pending question. */\n  answer(args: { requestId: string; allow: boolean }): void;\n  /** The pending question lost its call (stop, another conversation): close it. */\n  abandon(requestId: string): void;\n  /** Record a consent the host's own UI collected. */\n  grant(threadId: string): void;\n  /** A mounted card registers itself, so a question nobody can see is reported. */\n  registerCard(): () => void;\n  /** The store's person is gone: close the pending question and forget every yes. */\n  dispose(): void;\n}\n\ninterface PendingConsent {\n  request: ClientToolWriteConsentRequest;\n  resolve: (decision: ClientToolWriteConsentDecision) => void;\n}\n\nexport function createClientToolWriteConsentStore(): ClientToolWriteConsentStore {\n  let pending: PendingConsent | null = null;\n  let cards = 0;\n  const granted = new Set<string>();\n  const listeners = new Set<() => void>();\n  const notify = () => {\n    for (const listener of Array.from(listeners)) listener();\n  };\n  const settle = (decision: ClientToolWriteConsentDecision) => {\n    const settled = pending;\n    pending = null;\n    settled?.resolve(decision);\n    notify();\n  };\n\n  return {\n    getPending: () => pending?.request ?? null,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    isGranted: (threadId) => granted.has(threadId),\n    ask(request) {\n      if (granted.has(request.threadId)) return Promise.resolve('proceed');\n      // One question at a time: a newer batch replaces a question whose call\n      // the bridge has already given up on.\n      if (pending) settle('abandoned');\n      if (cards === 0) {\n        athenaDiagnostics.emit('sdk.config.warning', {\n          level: 'warn',\n          error: new AthenaSdkError({\n            code: 'config_invalid',\n            message:\n              'A frontend tool is waiting for the person to allow it, and nothing on screen asks them.',\n            hint: 'Render <AthenaChat> (it draws the question), mount <StatewireClientToolConsentCard>, or pass confirmClientToolWrites on <AthenaProvider>. The run stays parked until the question is answered.',\n            context: { tools: request.tools.map((tool) => tool.name) },\n          }),\n          data: { tools: request.tools.map((tool) => tool.name) },\n        });\n      }\n      return new Promise<ClientToolWriteConsentDecision>((resolve) => {\n        pending = { request, resolve };\n        notify();\n      });\n    },\n    answer({ requestId, allow }) {\n      if (pending?.request.requestId !== requestId) return;\n      if (allow) granted.add(pending.request.threadId);\n      settle(allow ? 'proceed' : 'declined');\n    },\n    abandon(requestId) {\n      if (pending?.request.requestId !== requestId) return;\n      settle('abandoned');\n    },\n    grant(threadId) {\n      granted.add(threadId);\n    },\n    registerCard() {\n      cards += 1;\n      return () => {\n        cards -= 1;\n      };\n    },\n    dispose() {\n      granted.clear();\n      if (pending) settle('abandoned');\n    },\n  };\n}\n\n/**\n * The consent store for one signed-in person on one Athena. `scope` names\n * both (the provider passes the session principal and the sync host): when it\n * changes, the previous person's store is disposed (its question closed, its\n * yeses forgotten) and the next person starts with none.\n */\nexport function useClientToolWriteConsentStore(scope: string): ClientToolWriteConsentStore {\n  const [held, setHeld] = useState(() => ({ scope, store: createClientToolWriteConsentStore() }));\n  let current = held;\n  if (held.scope !== scope) {\n    // Replaced during render, so no commit ever pairs the new person with the\n    // previous person's store.\n    current = { scope, store: createClientToolWriteConsentStore() };\n    setHeld(current);\n  }\n  const { store } = current;\n  useEffect(() => () => store.dispose(), [store]);\n  return store;\n}\n\n/** Provided by `AthenaProvider`; `null` outside one. */\nexport const ClientToolWriteConsentContext = createContext<ClientToolWriteConsentStore | null>(\n  null,\n);\n\nconst NO_SUBSCRIPTION = () => () => {};\nconst NO_PENDING = () => null;\n\nexport interface ClientToolWriteConsent {\n  /** The question waiting on the person, or `null`. */\n  request: ClientToolWriteConsentRequest | null;\n  /** Allow the conversation's writes and run the waiting calls. */\n  allow: () => void;\n  /** Decline the waiting calls; the agent is told, and a later call asks again. */\n  decline: () => void;\n}\n\n/**\n * The write-consent question for the chat the nearest `AthenaProvider` shows,\n * for a host that draws its own card. Calling it marks the question as shown.\n */\nexport function useClientToolWriteConsent(): ClientToolWriteConsent {\n  const store = useContext(ClientToolWriteConsentContext);\n  const request = useSyncExternalStore(\n    store?.subscribe ?? NO_SUBSCRIPTION,\n    store?.getPending ?? NO_PENDING,\n    NO_PENDING,\n  );\n  useEffect(() => store?.registerCard(), [store]);\n  const requestId = request?.requestId;\n  const allow = useCallback(() => {\n    if (requestId !== undefined) store?.answer({ requestId, allow: true });\n  }, [requestId, store]);\n  const decline = useCallback(() => {\n    if (requestId !== undefined) store?.answer({ requestId, allow: false });\n  }, [requestId, store]);\n  return { request, allow, decline };\n}\n"],"names":[],"mappings":"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"}

package/dist/chat/statewire-client-tools.cjs

@@ -3,6 +3,28 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const athenaDiagnostics = require("../diagnostics/athena-diagnostics.cjs");
 const assistantStream = require("assistant-stream");
 const clientTools = require("../agent-runtime/src/client-tools.cjs");
+const CLIENT_TOOL_WRITE_CONSENT = Symbol.for("athena.clientTool.writeConsent");
+function requiresWriteConsent(tool, options = {}) {
+  var _a;
+  const summary = (_a = options.summary) == null ? void 0 : _a.trim();
+  return { ...tool, [CLIENT_TOOL_WRITE_CONSENT]: summary ? { summary } : {} };
+}
+function clientToolWriteConsent(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  const mark = entry[CLIENT_TOOL_WRITE_CONSENT];
+  if (!mark || typeof mark !== "object") return null;
+  const summary = mark.summary;
+  return typeof summary === "string" && summary ? { summary } : {};
+}
+function clientToolWriteConsentSummaries(toolkit) {
+  var _a;
+  const summaries = {};
+  for (const [name, entry] of Object.entries(toolkit ?? {})) {
+    const summary = (_a = clientToolWriteConsent(entry)) == null ? void 0 : _a.summary;
+    if (summary) summaries[name] = summary;
+  }
+  return summaries;
+}
 function hasCallableExecute(entry) {
   return !!entry && typeof entry === "object" && typeof entry.execute === "function";
 }
@@ -32,15 +54,15 @@ function collectStatewireClientTools(toolkit) {
           name,
           description: entry.description ?? "",
           parameters,
-          requiresWrite: false
+          requiresWrite: clientToolWriteConsent(entry) !== null
         },
         handler: async (args, context) => {
-          const controller = new AbortController();
           const output = await execute(args, {
-            // The bridge always supplies the parked call's id; a host invoking
-            // the handler directly has no call to correlate.
+            // The bridge always supplies the parked call's id and its signal,
+            // which aborts when the call's request goes away (the run was
+            // stopped); a host invoking the handler directly has neither.
             toolCallId: (context == null ? void 0 : context.toolCallId) ?? "",
-            abortSignal: controller.signal,
+            abortSignal: (context == null ? void 0 : context.signal) ?? new AbortController().signal,
             human: () => Promise.reject(
               new Error("Human input is not supported for statewire client tools.")
             )
@@ -73,7 +95,10 @@ function resolveClientToolSurface(appId) {
 }
 exports.CLIENT_TOOL_SURFACE_APP_IDS = CLIENT_TOOL_SURFACE_APP_IDS;
 exports.backendDeclaredFrontendToolIds = backendDeclaredFrontendToolIds;
+exports.clientToolWriteConsent = clientToolWriteConsent;
+exports.clientToolWriteConsentSummaries = clientToolWriteConsentSummaries;
 exports.collectStatewireClientTools = collectStatewireClientTools;
+exports.requiresWriteConsent = requiresWriteConsent;
 exports.resolveClientToolSurface = resolveClientToolSurface;
 exports.statewireClientToolWireEntries = statewireClientToolWireEntries;
 //# sourceMappingURL=statewire-client-tools.cjs.map

package/dist/chat/statewire-client-tools.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-client-tools.cjs","sources":["../../src/chat/statewire-client-tools.ts"],"sourcesContent":["import { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport type { Toolkit } from '@assistant-ui/react';\nimport {\n  type ClientToolHandlerContext,\n  clientToolRunConfigEntries,\n  type RegisteredClientTool,\n} from '@athenaintel/agent-runtime';\nimport { ToolResponse, toJSONSchema } from 'assistant-stream';\n\n/**\n * @deprecated The SDK's client tools ARE the shared `RegisteredClientTool`\n * shape from `@athenaintel/agent-runtime` (`definition` + `handler`); import\n * that type instead. Retained for one release so existing imports type-check.\n */\nexport type StatewireClientTool = RegisteredClientTool;\n\nfunction hasCallableExecute(\n  entry: unknown,\n): entry is { execute: (args: Record<string, unknown>, context: unknown) => unknown } {\n  return (\n    !!entry &&\n    typeof entry === 'object' &&\n    typeof (entry as { execute?: unknown }).execute === 'function'\n  );\n}\n\n/**\n * Collect the client-executable tools from a frontend toolkit, in the shared\n * `RegisteredClientTool` shape every statewire surface declares and executes.\n *\n * The deep-agent runtime drops frontend (`ui_*`) tool definitions, so tools\n * with a local `execute` must instead be declared through\n * `runConfig.custom.client_tools` and answered by the statewire client-tool\n * bridge. Schema conversion reuses `toJSONSchema` — the same conversion\n * primitive as the legacy assistant-transport — and a tool whose schema cannot\n * be converted is skipped with a warning rather than failing the whole set.\n * SDK tools never gate on write consent (`requiresWrite: false`): a toolkit\n * `execute` is the host app's own code.\n */\nexport function collectStatewireClientTools(toolkit: Toolkit): RegisteredClientTool[] {\n  const executable = Object.entries(toolkit).filter(([, entry]) => hasCallableExecute(entry));\n  if (executable.length === 0) return [];\n\n  return executable.flatMap(([name, entry]) => {\n    if (entry.parameters === undefined) return [];\n\n    let parameters: Record<string, unknown>;\n    try {\n      parameters = { ...toJSONSchema(entry.parameters) };\n    } catch (error) {\n      athenaDiagnostics.emit('tools.schema.warning', {\n        level: 'warn',\n        data: {\n          tool: name,\n          message: 'Frontend tool schema could not be converted for statewire; the tool is not registered',\n          error: error instanceof Error ? error.message : String(error),\n        },\n      });\n      return [];\n    }\n\n    const execute = (entry as {\n      execute: (args: Record<string, unknown>, context: unknown) => unknown;\n    }).execute;\n    return [\n      {\n        definition: {\n          name,\n          description: entry.description ?? '',\n          parameters,\n          requiresWrite: false,\n        },\n        handler: async (args, context?: ClientToolHandlerContext) => {\n          const controller = new AbortController();\n          const output = await execute(args, {\n            // The bridge always supplies the parked call's id; a host invoking\n            // the handler directly has no call to correlate.\n            toolCallId: context?.toolCallId ?? '',\n            abortSignal: controller.signal,\n            human: () =>\n              Promise.reject(\n                new Error('Human input is not supported for statewire client tools.'),\n              ),\n          });\n          return output instanceof ToolResponse ? output.result : output;\n        },\n      },\n    ];\n  });\n}\n\n/** Wire entries for `runConfig.custom.client_tools` — the shared contract from\n *  `@athenaintel/agent-runtime`, so the SDK cannot drift from the other surfaces. */\nexport function statewireClientToolWireEntries(\n  tools: readonly RegisteredClientTool[],\n): Record<string, unknown>[] {\n  return clientToolRunConfigEntries(tools);\n}\n\n/**\n * The frontend-toolkit entries that must ride `enabled_tools`: declarations\n * WITHOUT a local `execute`, which name registry tools the backend already\n * knows how to bind (Olympus's frontend-executed tool ids).\n *\n * Executable entries are deliberately left out. They are declared through\n * `client_tools`, and the run binds them by name; putting the same name into\n * `enabled_tools` would also switch on any backend toolkit that happens to\n * own a tool of that name, and the backend wins the resulting collision —\n * the client tool is dropped and the model calls the backend one instead.\n */\nexport function backendDeclaredFrontendToolIds(toolkit: Toolkit): string[] {\n  return Object.entries(toolkit)\n    .filter(([, entry]) => !hasCallableExecute(entry))\n    .map(([name]) => name);\n}\n\n/**\n * The `app_id` values the deep-agent runtime accepts as a client-tool surface.\n * Mirrors `agora/agora/graphs/athena_deep_agent/client_tools.py`: the fixed\n * first-party ids plus the `computer_asset_<uuid>` shape Athena's provisioning\n * injects into a computer-asset app. Any other `app_id` (or none) gets no\n * surface, and the runtime drops every `client_tools` declaration for the run.\n */\nexport const CLIENT_TOOL_SURFACE_APP_IDS = {\n  olympus: 'olympus',\n  officeAddin: 'athena-office-addin',\n  mobile: 'athena-mobile',\n} as const;\n\nconst SDK_APP_ID_PATTERN = /^computer_asset_[0-9a-f-]{8,64}$/;\n\nexport type ClientToolSurface = 'web' | 'office' | 'mobile' | 'sdk';\n\n/** The surface an `app_id` selects, or null when the runtime would refuse it. */\nexport function resolveClientToolSurface(appId: string | undefined | null): ClientToolSurface | null {\n  if (typeof appId !== 'string' || appId.length === 0) return null;\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.olympus) return 'web';\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.officeAddin) return 'office';\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.mobile) return 'mobile';\n  if (SDK_APP_ID_PATTERN.test(appId)) return 'sdk';\n  return null;\n}\n"],"names":["toJSONSchema","athenaDiagnostics","ToolResponse","clientToolRunConfigEntries"],"mappings":";;;;;AAgBA,SAAS,mBACP,OACoF;AACpF,SACE,CAAC,CAAC,SACF,OAAO,UAAU,YACjB,OAAQ,MAAgC,YAAY;AAExD;AAeO,SAAS,4BAA4B,SAA0C;AACpF,QAAM,aAAa,OAAO,QAAQ,OAAO,EAAE,OAAO,CAAC,GAAG,KAAK,MAAM,mBAAmB,KAAK,CAAC;AAC1F,MAAI,WAAW,WAAW,EAAG,QAAO,CAAA;AAEpC,SAAO,WAAW,QAAQ,CAAC,CAAC,MAAM,KAAK,MAAM;AAC3C,QAAI,MAAM,eAAe,OAAW,QAAO,CAAA;AAE3C,QAAI;AACJ,QAAI;AACF,mBAAa,EAAE,GAAGA,gBAAAA,aAAa,MAAM,UAAU,EAAA;AAAA,IACjD,SAAS,OAAO;AACdC,wBAAAA,kBAAkB,KAAK,wBAAwB;AAAA,QAC7C,OAAO;AAAA,QACP,MAAM;AAAA,UACJ,MAAM;AAAA,UACN,SAAS;AAAA,UACT,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,QAAA;AAAA,MAC9D,CACD;AACD,aAAO,CAAA;AAAA,IACT;AAEA,UAAM,UAAW,MAEd;AACH,WAAO;AAAA,MACL;AAAA,QACE,YAAY;AAAA,UACV;AAAA,UACA,aAAa,MAAM,eAAe;AAAA,UAClC;AAAA,UACA,eAAe;AAAA,QAAA;AAAA,QAEjB,SAAS,OAAO,MAAM,YAAuC;AAC3D,gBAAM,aAAa,IAAI,gBAAA;AACvB,gBAAM,SAAS,MAAM,QAAQ,MAAM;AAAA;AAAA;AAAA,YAGjC,aAAY,mCAAS,eAAc;AAAA,YACnC,aAAa,WAAW;AAAA,YACxB,OAAO,MACL,QAAQ;AAAA,cACN,IAAI,MAAM,0DAA0D;AAAA,YAAA;AAAA,UACtE,CACH;AACD,iBAAO,kBAAkBC,gBAAAA,eAAe,OAAO,SAAS;AAAA,QAC1D;AAAA,MAAA;AAAA,IACF;AAAA,EAEJ,CAAC;AACH;AAIO,SAAS,+BACd,OAC2B;AAC3B,SAAOC,YAAAA,2BAA2B,KAAK;AACzC;AAaO,SAAS,+BAA+B,SAA4B;AACzE,SAAO,OAAO,QAAQ,OAAO,EAC1B,OAAO,CAAC,CAAA,EAAG,KAAK,MAAM,CAAC,mBAAmB,KAAK,CAAC,EAChD,IAAI,CAAC,CAAC,IAAI,MAAM,IAAI;AACzB;AASO,MAAM,8BAA8B;AAAA,EACzC,SAAS;AAAA,EACT,aAAa;AAAA,EACb,QAAQ;AACV;AAEA,MAAM,qBAAqB;AAKpB,SAAS,yBAAyB,OAA4D;AACnG,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAAG,QAAO;AAC5D,MAAI,UAAU,4BAA4B,QAAS,QAAO;AAC1D,MAAI,UAAU,4BAA4B,YAAa,QAAO;AAC9D,MAAI,UAAU,4BAA4B,OAAQ,QAAO;AACzD,MAAI,mBAAmB,KAAK,KAAK,EAAG,QAAO;AAC3C,SAAO;AACT;;;;;;"}
+{"version":3,"file":"statewire-client-tools.cjs","sources":["../../src/chat/statewire-client-tools.ts"],"sourcesContent":["import { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport type { Toolkit } from '@assistant-ui/react';\nimport {\n  type ClientToolHandlerContext,\n  clientToolRunConfigEntries,\n  type RegisteredClientTool,\n} from '@athenaintel/agent-runtime';\nimport { ToolResponse, toJSONSchema } from 'assistant-stream';\n\n/**\n * @deprecated The SDK's client tools ARE the shared `RegisteredClientTool`\n * shape from `@athenaintel/agent-runtime` (`definition` + `handler`); import\n * that type instead. Retained for one release so existing imports type-check.\n */\nexport type StatewireClientTool = RegisteredClientTool;\n\n/**\n * Marks a frontend tool as one that changes something for the person, so its\n * calls wait for their consent. Set by {@link requiresWriteConsent}. A\n * registered symbol (not a module-local one), so the mark is read by whichever\n * copy of the SDK collects the toolkit.\n */\nconst CLIENT_TOOL_WRITE_CONSENT = Symbol.for('athena.clientTool.writeConsent');\n\nexport interface ClientToolWriteConsentOptions {\n  /**\n   * What the tool does, as the rest of the sentence \"… wants to ___\" on the\n   * consent card (e.g. `\"click and type on this page\"`). The card names the\n   * tool when this is absent.\n   */\n  summary?: string;\n}\n\n/**\n * Mark a `frontendTools` entry as a write: the person is asked before its\n * first call in a conversation runs, the answer covers the rest of that\n * conversation, and a declined call answers the model with an error instead\n * of running. Unmarked tools run without asking, as before.\n *\n * ```ts\n * const frontendTools = {\n *   save_note: requiresWriteConsent(\n *     { description: '…', parameters, execute: saveNote },\n *     { summary: 'save a note on this record' },\n *   ),\n * };\n * ```\n *\n * The mark also travels to Athena (`requires_write`), which then never\n * answers the call on the person's behalf while their tab is away.\n */\nexport function requiresWriteConsent<T extends object>(\n  tool: T,\n  options: ClientToolWriteConsentOptions = {},\n): T {\n  const summary = options.summary?.trim();\n  return { ...tool, [CLIENT_TOOL_WRITE_CONSENT]: summary ? { summary } : {} };\n}\n\n/** The consent mark on a toolkit entry, or `null` for a tool that never asks. */\nexport function clientToolWriteConsent(entry: unknown): ClientToolWriteConsentOptions | null {\n  if (!entry || typeof entry !== 'object') return null;\n  const mark = (entry as Record<symbol, unknown>)[CLIENT_TOOL_WRITE_CONSENT];\n  if (!mark || typeof mark !== 'object') return null;\n  const summary = (mark as { summary?: unknown }).summary;\n  return typeof summary === 'string' && summary ? { summary } : {};\n}\n\n/** Each consent-marked tool's own words for what it does, by tool name. */\nexport function clientToolWriteConsentSummaries(\n  toolkit: Toolkit | undefined,\n): Readonly<Record<string, string>> {\n  const summaries: Record<string, string> = {};\n  for (const [name, entry] of Object.entries(toolkit ?? {})) {\n    const summary = clientToolWriteConsent(entry)?.summary;\n    if (summary) summaries[name] = summary;\n  }\n  return summaries;\n}\n\nfunction hasCallableExecute(\n  entry: unknown,\n): entry is { execute: (args: Record<string, unknown>, context: unknown) => unknown } {\n  return (\n    !!entry &&\n    typeof entry === 'object' &&\n    typeof (entry as { execute?: unknown }).execute === 'function'\n  );\n}\n\n/**\n * Collect the client-executable tools from a frontend toolkit, in the shared\n * `RegisteredClientTool` shape every statewire surface declares and executes.\n *\n * The deep-agent runtime drops frontend (`ui_*`) tool definitions, so tools\n * with a local `execute` must instead be declared through\n * `runConfig.custom.client_tools` and answered by the statewire client-tool\n * bridge. Schema conversion reuses `toJSONSchema` — the same conversion\n * primitive as the legacy assistant-transport — and a tool whose schema cannot\n * be converted is skipped with a warning rather than failing the whole set.\n * A tool gates on write consent only when its entry is marked with\n * `requiresWriteConsent`: an unmarked toolkit `execute` is the host app's own\n * code and runs without asking.\n */\nexport function collectStatewireClientTools(toolkit: Toolkit): RegisteredClientTool[] {\n  const executable = Object.entries(toolkit).filter(([, entry]) => hasCallableExecute(entry));\n  if (executable.length === 0) return [];\n\n  return executable.flatMap(([name, entry]) => {\n    if (entry.parameters === undefined) return [];\n\n    let parameters: Record<string, unknown>;\n    try {\n      parameters = { ...toJSONSchema(entry.parameters) };\n    } catch (error) {\n      athenaDiagnostics.emit('tools.schema.warning', {\n        level: 'warn',\n        data: {\n          tool: name,\n          message: 'Frontend tool schema could not be converted for statewire; the tool is not registered',\n          error: error instanceof Error ? error.message : String(error),\n        },\n      });\n      return [];\n    }\n\n    const execute = (entry as {\n      execute: (args: Record<string, unknown>, context: unknown) => unknown;\n    }).execute;\n    return [\n      {\n        definition: {\n          name,\n          description: entry.description ?? '',\n          parameters,\n          requiresWrite: clientToolWriteConsent(entry) !== null,\n        },\n        handler: async (args, context?: ClientToolHandlerContext) => {\n          const output = await execute(args, {\n            // The bridge always supplies the parked call's id and its signal,\n            // which aborts when the call's request goes away (the run was\n            // stopped); a host invoking the handler directly has neither.\n            toolCallId: context?.toolCallId ?? '',\n            abortSignal: context?.signal ?? new AbortController().signal,\n            human: () =>\n              Promise.reject(\n                new Error('Human input is not supported for statewire client tools.'),\n              ),\n          });\n          return output instanceof ToolResponse ? output.result : output;\n        },\n      },\n    ];\n  });\n}\n\n/** Wire entries for `runConfig.custom.client_tools` — the shared contract from\n *  `@athenaintel/agent-runtime`, so the SDK cannot drift from the other surfaces. */\nexport function statewireClientToolWireEntries(\n  tools: readonly RegisteredClientTool[],\n): Record<string, unknown>[] {\n  return clientToolRunConfigEntries(tools);\n}\n\n/**\n * The frontend-toolkit entries that must ride `enabled_tools`: declarations\n * WITHOUT a local `execute`, which name registry tools the backend already\n * knows how to bind (Olympus's frontend-executed tool ids).\n *\n * Executable entries are deliberately left out. They are declared through\n * `client_tools`, and the run binds them by name; putting the same name into\n * `enabled_tools` would also switch on any backend toolkit that happens to\n * own a tool of that name, and the backend wins the resulting collision —\n * the client tool is dropped and the model calls the backend one instead.\n */\nexport function backendDeclaredFrontendToolIds(toolkit: Toolkit): string[] {\n  return Object.entries(toolkit)\n    .filter(([, entry]) => !hasCallableExecute(entry))\n    .map(([name]) => name);\n}\n\n/**\n * The `app_id` values the deep-agent runtime accepts as a client-tool surface.\n * Mirrors `agora/agora/graphs/athena_deep_agent/client_tools.py`: the fixed\n * first-party ids plus the `computer_asset_<uuid>` shape Athena's provisioning\n * injects into a computer-asset app. Any other `app_id` (or none) gets no\n * surface, and the runtime drops every `client_tools` declaration for the run.\n */\nexport const CLIENT_TOOL_SURFACE_APP_IDS = {\n  olympus: 'olympus',\n  officeAddin: 'athena-office-addin',\n  mobile: 'athena-mobile',\n} as const;\n\nconst SDK_APP_ID_PATTERN = /^computer_asset_[0-9a-f-]{8,64}$/;\n\nexport type ClientToolSurface = 'web' | 'office' | 'mobile' | 'sdk';\n\n/** The surface an `app_id` selects, or null when the runtime would refuse it. */\nexport function resolveClientToolSurface(appId: string | undefined | null): ClientToolSurface | null {\n  if (typeof appId !== 'string' || appId.length === 0) return null;\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.olympus) return 'web';\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.officeAddin) return 'office';\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.mobile) return 'mobile';\n  if (SDK_APP_ID_PATTERN.test(appId)) return 'sdk';\n  return null;\n}\n"],"names":["toJSONSchema","athenaDiagnostics","ToolResponse","clientToolRunConfigEntries"],"mappings":"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"}

package/dist/chat/statewire-client-tools.d.ts

@@ -6,6 +6,37 @@ import { type RegisteredClientTool } from '../agent-runtime/src/index';
  * that type instead. Retained for one release so existing imports type-check.
  */
 export type StatewireClientTool = RegisteredClientTool;
+export interface ClientToolWriteConsentOptions {
+    /**
+     * What the tool does, as the rest of the sentence "… wants to ___" on the
+     * consent card (e.g. `"click and type on this page"`). The card names the
+     * tool when this is absent.
+     */
+    summary?: string;
+}
+/**
+ * Mark a `frontendTools` entry as a write: the person is asked before its
+ * first call in a conversation runs, the answer covers the rest of that
+ * conversation, and a declined call answers the model with an error instead
+ * of running. Unmarked tools run without asking, as before.
+ *
+ * ```ts
+ * const frontendTools = {
+ *   save_note: requiresWriteConsent(
+ *     { description: '…', parameters, execute: saveNote },
+ *     { summary: 'save a note on this record' },
+ *   ),
+ * };
+ * ```
+ *
+ * The mark also travels to Athena (`requires_write`), which then never
+ * answers the call on the person's behalf while their tab is away.
+ */
+export declare function requiresWriteConsent<T extends object>(tool: T, options?: ClientToolWriteConsentOptions): T;
+/** The consent mark on a toolkit entry, or `null` for a tool that never asks. */
+export declare function clientToolWriteConsent(entry: unknown): ClientToolWriteConsentOptions | null;
+/** Each consent-marked tool's own words for what it does, by tool name. */
+export declare function clientToolWriteConsentSummaries(toolkit: Toolkit | undefined): Readonly<Record<string, string>>;
 /**
  * Collect the client-executable tools from a frontend toolkit, in the shared
  * `RegisteredClientTool` shape every statewire surface declares and executes.
@@ -16,8 +47,9 @@ export type StatewireClientTool = RegisteredClientTool;
  * bridge. Schema conversion reuses `toJSONSchema` — the same conversion
  * primitive as the legacy assistant-transport — and a tool whose schema cannot
  * be converted is skipped with a warning rather than failing the whole set.
- * SDK tools never gate on write consent (`requiresWrite: false`): a toolkit
- * `execute` is the host app's own code.
+ * A tool gates on write consent only when its entry is marked with
+ * `requiresWriteConsent`: an unmarked toolkit `execute` is the host app's own
+ * code and runs without asking.
  */
 export declare function collectStatewireClientTools(toolkit: Toolkit): RegisteredClientTool[];
 /** Wire entries for `runConfig.custom.client_tools` — the shared contract from

package/dist/chat/statewire-client-tools.js

@@ -1,6 +1,28 @@
 import { athenaDiagnostics } from "../diagnostics/athena-diagnostics.js";
 import { toJSONSchema, ToolResponse } from "assistant-stream";
 import { clientToolRunConfigEntries } from "../agent-runtime/src/client-tools.js";
+const CLIENT_TOOL_WRITE_CONSENT = Symbol.for("athena.clientTool.writeConsent");
+function requiresWriteConsent(tool, options = {}) {
+  var _a;
+  const summary = (_a = options.summary) == null ? void 0 : _a.trim();
+  return { ...tool, [CLIENT_TOOL_WRITE_CONSENT]: summary ? { summary } : {} };
+}
+function clientToolWriteConsent(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  const mark = entry[CLIENT_TOOL_WRITE_CONSENT];
+  if (!mark || typeof mark !== "object") return null;
+  const summary = mark.summary;
+  return typeof summary === "string" && summary ? { summary } : {};
+}
+function clientToolWriteConsentSummaries(toolkit) {
+  var _a;
+  const summaries = {};
+  for (const [name, entry] of Object.entries(toolkit ?? {})) {
+    const summary = (_a = clientToolWriteConsent(entry)) == null ? void 0 : _a.summary;
+    if (summary) summaries[name] = summary;
+  }
+  return summaries;
+}
 function hasCallableExecute(entry) {
   return !!entry && typeof entry === "object" && typeof entry.execute === "function";
 }
@@ -30,15 +52,15 @@ function collectStatewireClientTools(toolkit) {
           name,
           description: entry.description ?? "",
           parameters,
-          requiresWrite: false
+          requiresWrite: clientToolWriteConsent(entry) !== null
         },
         handler: async (args, context) => {
-          const controller = new AbortController();
           const output = await execute(args, {
-            // The bridge always supplies the parked call's id; a host invoking
-            // the handler directly has no call to correlate.
+            // The bridge always supplies the parked call's id and its signal,
+            // which aborts when the call's request goes away (the run was
+            // stopped); a host invoking the handler directly has neither.
             toolCallId: (context == null ? void 0 : context.toolCallId) ?? "",
-            abortSignal: controller.signal,
+            abortSignal: (context == null ? void 0 : context.signal) ?? new AbortController().signal,
             human: () => Promise.reject(
               new Error("Human input is not supported for statewire client tools.")
             )
@@ -72,7 +94,10 @@ function resolveClientToolSurface(appId) {
 export {
   CLIENT_TOOL_SURFACE_APP_IDS,
   backendDeclaredFrontendToolIds,
+  clientToolWriteConsent,
+  clientToolWriteConsentSummaries,
   collectStatewireClientTools,
+  requiresWriteConsent,
   resolveClientToolSurface,
   statewireClientToolWireEntries
 };

package/dist/chat/statewire-client-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-client-tools.js","sources":["../../src/chat/statewire-client-tools.ts"],"sourcesContent":["import { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport type { Toolkit } from '@assistant-ui/react';\nimport {\n  type ClientToolHandlerContext,\n  clientToolRunConfigEntries,\n  type RegisteredClientTool,\n} from '@athenaintel/agent-runtime';\nimport { ToolResponse, toJSONSchema } from 'assistant-stream';\n\n/**\n * @deprecated The SDK's client tools ARE the shared `RegisteredClientTool`\n * shape from `@athenaintel/agent-runtime` (`definition` + `handler`); import\n * that type instead. Retained for one release so existing imports type-check.\n */\nexport type StatewireClientTool = RegisteredClientTool;\n\nfunction hasCallableExecute(\n  entry: unknown,\n): entry is { execute: (args: Record<string, unknown>, context: unknown) => unknown } {\n  return (\n    !!entry &&\n    typeof entry === 'object' &&\n    typeof (entry as { execute?: unknown }).execute === 'function'\n  );\n}\n\n/**\n * Collect the client-executable tools from a frontend toolkit, in the shared\n * `RegisteredClientTool` shape every statewire surface declares and executes.\n *\n * The deep-agent runtime drops frontend (`ui_*`) tool definitions, so tools\n * with a local `execute` must instead be declared through\n * `runConfig.custom.client_tools` and answered by the statewire client-tool\n * bridge. Schema conversion reuses `toJSONSchema` — the same conversion\n * primitive as the legacy assistant-transport — and a tool whose schema cannot\n * be converted is skipped with a warning rather than failing the whole set.\n * SDK tools never gate on write consent (`requiresWrite: false`): a toolkit\n * `execute` is the host app's own code.\n */\nexport function collectStatewireClientTools(toolkit: Toolkit): RegisteredClientTool[] {\n  const executable = Object.entries(toolkit).filter(([, entry]) => hasCallableExecute(entry));\n  if (executable.length === 0) return [];\n\n  return executable.flatMap(([name, entry]) => {\n    if (entry.parameters === undefined) return [];\n\n    let parameters: Record<string, unknown>;\n    try {\n      parameters = { ...toJSONSchema(entry.parameters) };\n    } catch (error) {\n      athenaDiagnostics.emit('tools.schema.warning', {\n        level: 'warn',\n        data: {\n          tool: name,\n          message: 'Frontend tool schema could not be converted for statewire; the tool is not registered',\n          error: error instanceof Error ? error.message : String(error),\n        },\n      });\n      return [];\n    }\n\n    const execute = (entry as {\n      execute: (args: Record<string, unknown>, context: unknown) => unknown;\n    }).execute;\n    return [\n      {\n        definition: {\n          name,\n          description: entry.description ?? '',\n          parameters,\n          requiresWrite: false,\n        },\n        handler: async (args, context?: ClientToolHandlerContext) => {\n          const controller = new AbortController();\n          const output = await execute(args, {\n            // The bridge always supplies the parked call's id; a host invoking\n            // the handler directly has no call to correlate.\n            toolCallId: context?.toolCallId ?? '',\n            abortSignal: controller.signal,\n            human: () =>\n              Promise.reject(\n                new Error('Human input is not supported for statewire client tools.'),\n              ),\n          });\n          return output instanceof ToolResponse ? output.result : output;\n        },\n      },\n    ];\n  });\n}\n\n/** Wire entries for `runConfig.custom.client_tools` — the shared contract from\n *  `@athenaintel/agent-runtime`, so the SDK cannot drift from the other surfaces. */\nexport function statewireClientToolWireEntries(\n  tools: readonly RegisteredClientTool[],\n): Record<string, unknown>[] {\n  return clientToolRunConfigEntries(tools);\n}\n\n/**\n * The frontend-toolkit entries that must ride `enabled_tools`: declarations\n * WITHOUT a local `execute`, which name registry tools the backend already\n * knows how to bind (Olympus's frontend-executed tool ids).\n *\n * Executable entries are deliberately left out. They are declared through\n * `client_tools`, and the run binds them by name; putting the same name into\n * `enabled_tools` would also switch on any backend toolkit that happens to\n * own a tool of that name, and the backend wins the resulting collision —\n * the client tool is dropped and the model calls the backend one instead.\n */\nexport function backendDeclaredFrontendToolIds(toolkit: Toolkit): string[] {\n  return Object.entries(toolkit)\n    .filter(([, entry]) => !hasCallableExecute(entry))\n    .map(([name]) => name);\n}\n\n/**\n * The `app_id` values the deep-agent runtime accepts as a client-tool surface.\n * Mirrors `agora/agora/graphs/athena_deep_agent/client_tools.py`: the fixed\n * first-party ids plus the `computer_asset_<uuid>` shape Athena's provisioning\n * injects into a computer-asset app. Any other `app_id` (or none) gets no\n * surface, and the runtime drops every `client_tools` declaration for the run.\n */\nexport const CLIENT_TOOL_SURFACE_APP_IDS = {\n  olympus: 'olympus',\n  officeAddin: 'athena-office-addin',\n  mobile: 'athena-mobile',\n} as const;\n\nconst SDK_APP_ID_PATTERN = /^computer_asset_[0-9a-f-]{8,64}$/;\n\nexport type ClientToolSurface = 'web' | 'office' | 'mobile' | 'sdk';\n\n/** The surface an `app_id` selects, or null when the runtime would refuse it. */\nexport function resolveClientToolSurface(appId: string | undefined | null): ClientToolSurface | null {\n  if (typeof appId !== 'string' || appId.length === 0) return null;\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.olympus) return 'web';\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.officeAddin) return 'office';\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.mobile) return 'mobile';\n  if (SDK_APP_ID_PATTERN.test(appId)) return 'sdk';\n  return null;\n}\n"],"names":[],"mappings":";;;AAgBA,SAAS,mBACP,OACoF;AACpF,SACE,CAAC,CAAC,SACF,OAAO,UAAU,YACjB,OAAQ,MAAgC,YAAY;AAExD;AAeO,SAAS,4BAA4B,SAA0C;AACpF,QAAM,aAAa,OAAO,QAAQ,OAAO,EAAE,OAAO,CAAC,GAAG,KAAK,MAAM,mBAAmB,KAAK,CAAC;AAC1F,MAAI,WAAW,WAAW,EAAG,QAAO,CAAA;AAEpC,SAAO,WAAW,QAAQ,CAAC,CAAC,MAAM,KAAK,MAAM;AAC3C,QAAI,MAAM,eAAe,OAAW,QAAO,CAAA;AAE3C,QAAI;AACJ,QAAI;AACF,mBAAa,EAAE,GAAG,aAAa,MAAM,UAAU,EAAA;AAAA,IACjD,SAAS,OAAO;AACd,wBAAkB,KAAK,wBAAwB;AAAA,QAC7C,OAAO;AAAA,QACP,MAAM;AAAA,UACJ,MAAM;AAAA,UACN,SAAS;AAAA,UACT,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,QAAA;AAAA,MAC9D,CACD;AACD,aAAO,CAAA;AAAA,IACT;AAEA,UAAM,UAAW,MAEd;AACH,WAAO;AAAA,MACL;AAAA,QACE,YAAY;AAAA,UACV;AAAA,UACA,aAAa,MAAM,eAAe;AAAA,UAClC;AAAA,UACA,eAAe;AAAA,QAAA;AAAA,QAEjB,SAAS,OAAO,MAAM,YAAuC;AAC3D,gBAAM,aAAa,IAAI,gBAAA;AACvB,gBAAM,SAAS,MAAM,QAAQ,MAAM;AAAA;AAAA;AAAA,YAGjC,aAAY,mCAAS,eAAc;AAAA,YACnC,aAAa,WAAW;AAAA,YACxB,OAAO,MACL,QAAQ;AAAA,cACN,IAAI,MAAM,0DAA0D;AAAA,YAAA;AAAA,UACtE,CACH;AACD,iBAAO,kBAAkB,eAAe,OAAO,SAAS;AAAA,QAC1D;AAAA,MAAA;AAAA,IACF;AAAA,EAEJ,CAAC;AACH;AAIO,SAAS,+BACd,OAC2B;AAC3B,SAAO,2BAA2B,KAAK;AACzC;AAaO,SAAS,+BAA+B,SAA4B;AACzE,SAAO,OAAO,QAAQ,OAAO,EAC1B,OAAO,CAAC,CAAA,EAAG,KAAK,MAAM,CAAC,mBAAmB,KAAK,CAAC,EAChD,IAAI,CAAC,CAAC,IAAI,MAAM,IAAI;AACzB;AASO,MAAM,8BAA8B;AAAA,EACzC,SAAS;AAAA,EACT,aAAa;AAAA,EACb,QAAQ;AACV;AAEA,MAAM,qBAAqB;AAKpB,SAAS,yBAAyB,OAA4D;AACnG,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAAG,QAAO;AAC5D,MAAI,UAAU,4BAA4B,QAAS,QAAO;AAC1D,MAAI,UAAU,4BAA4B,YAAa,QAAO;AAC9D,MAAI,UAAU,4BAA4B,OAAQ,QAAO;AACzD,MAAI,mBAAmB,KAAK,KAAK,EAAG,QAAO;AAC3C,SAAO;AACT;"}
+{"version":3,"file":"statewire-client-tools.js","sources":["../../src/chat/statewire-client-tools.ts"],"sourcesContent":["import { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport type { Toolkit } from '@assistant-ui/react';\nimport {\n  type ClientToolHandlerContext,\n  clientToolRunConfigEntries,\n  type RegisteredClientTool,\n} from '@athenaintel/agent-runtime';\nimport { ToolResponse, toJSONSchema } from 'assistant-stream';\n\n/**\n * @deprecated The SDK's client tools ARE the shared `RegisteredClientTool`\n * shape from `@athenaintel/agent-runtime` (`definition` + `handler`); import\n * that type instead. Retained for one release so existing imports type-check.\n */\nexport type StatewireClientTool = RegisteredClientTool;\n\n/**\n * Marks a frontend tool as one that changes something for the person, so its\n * calls wait for their consent. Set by {@link requiresWriteConsent}. A\n * registered symbol (not a module-local one), so the mark is read by whichever\n * copy of the SDK collects the toolkit.\n */\nconst CLIENT_TOOL_WRITE_CONSENT = Symbol.for('athena.clientTool.writeConsent');\n\nexport interface ClientToolWriteConsentOptions {\n  /**\n   * What the tool does, as the rest of the sentence \"… wants to ___\" on the\n   * consent card (e.g. `\"click and type on this page\"`). The card names the\n   * tool when this is absent.\n   */\n  summary?: string;\n}\n\n/**\n * Mark a `frontendTools` entry as a write: the person is asked before its\n * first call in a conversation runs, the answer covers the rest of that\n * conversation, and a declined call answers the model with an error instead\n * of running. Unmarked tools run without asking, as before.\n *\n * ```ts\n * const frontendTools = {\n *   save_note: requiresWriteConsent(\n *     { description: '…', parameters, execute: saveNote },\n *     { summary: 'save a note on this record' },\n *   ),\n * };\n * ```\n *\n * The mark also travels to Athena (`requires_write`), which then never\n * answers the call on the person's behalf while their tab is away.\n */\nexport function requiresWriteConsent<T extends object>(\n  tool: T,\n  options: ClientToolWriteConsentOptions = {},\n): T {\n  const summary = options.summary?.trim();\n  return { ...tool, [CLIENT_TOOL_WRITE_CONSENT]: summary ? { summary } : {} };\n}\n\n/** The consent mark on a toolkit entry, or `null` for a tool that never asks. */\nexport function clientToolWriteConsent(entry: unknown): ClientToolWriteConsentOptions | null {\n  if (!entry || typeof entry !== 'object') return null;\n  const mark = (entry as Record<symbol, unknown>)[CLIENT_TOOL_WRITE_CONSENT];\n  if (!mark || typeof mark !== 'object') return null;\n  const summary = (mark as { summary?: unknown }).summary;\n  return typeof summary === 'string' && summary ? { summary } : {};\n}\n\n/** Each consent-marked tool's own words for what it does, by tool name. */\nexport function clientToolWriteConsentSummaries(\n  toolkit: Toolkit | undefined,\n): Readonly<Record<string, string>> {\n  const summaries: Record<string, string> = {};\n  for (const [name, entry] of Object.entries(toolkit ?? {})) {\n    const summary = clientToolWriteConsent(entry)?.summary;\n    if (summary) summaries[name] = summary;\n  }\n  return summaries;\n}\n\nfunction hasCallableExecute(\n  entry: unknown,\n): entry is { execute: (args: Record<string, unknown>, context: unknown) => unknown } {\n  return (\n    !!entry &&\n    typeof entry === 'object' &&\n    typeof (entry as { execute?: unknown }).execute === 'function'\n  );\n}\n\n/**\n * Collect the client-executable tools from a frontend toolkit, in the shared\n * `RegisteredClientTool` shape every statewire surface declares and executes.\n *\n * The deep-agent runtime drops frontend (`ui_*`) tool definitions, so tools\n * with a local `execute` must instead be declared through\n * `runConfig.custom.client_tools` and answered by the statewire client-tool\n * bridge. Schema conversion reuses `toJSONSchema` — the same conversion\n * primitive as the legacy assistant-transport — and a tool whose schema cannot\n * be converted is skipped with a warning rather than failing the whole set.\n * A tool gates on write consent only when its entry is marked with\n * `requiresWriteConsent`: an unmarked toolkit `execute` is the host app's own\n * code and runs without asking.\n */\nexport function collectStatewireClientTools(toolkit: Toolkit): RegisteredClientTool[] {\n  const executable = Object.entries(toolkit).filter(([, entry]) => hasCallableExecute(entry));\n  if (executable.length === 0) return [];\n\n  return executable.flatMap(([name, entry]) => {\n    if (entry.parameters === undefined) return [];\n\n    let parameters: Record<string, unknown>;\n    try {\n      parameters = { ...toJSONSchema(entry.parameters) };\n    } catch (error) {\n      athenaDiagnostics.emit('tools.schema.warning', {\n        level: 'warn',\n        data: {\n          tool: name,\n          message: 'Frontend tool schema could not be converted for statewire; the tool is not registered',\n          error: error instanceof Error ? error.message : String(error),\n        },\n      });\n      return [];\n    }\n\n    const execute = (entry as {\n      execute: (args: Record<string, unknown>, context: unknown) => unknown;\n    }).execute;\n    return [\n      {\n        definition: {\n          name,\n          description: entry.description ?? '',\n          parameters,\n          requiresWrite: clientToolWriteConsent(entry) !== null,\n        },\n        handler: async (args, context?: ClientToolHandlerContext) => {\n          const output = await execute(args, {\n            // The bridge always supplies the parked call's id and its signal,\n            // which aborts when the call's request goes away (the run was\n            // stopped); a host invoking the handler directly has neither.\n            toolCallId: context?.toolCallId ?? '',\n            abortSignal: context?.signal ?? new AbortController().signal,\n            human: () =>\n              Promise.reject(\n                new Error('Human input is not supported for statewire client tools.'),\n              ),\n          });\n          return output instanceof ToolResponse ? output.result : output;\n        },\n      },\n    ];\n  });\n}\n\n/** Wire entries for `runConfig.custom.client_tools` — the shared contract from\n *  `@athenaintel/agent-runtime`, so the SDK cannot drift from the other surfaces. */\nexport function statewireClientToolWireEntries(\n  tools: readonly RegisteredClientTool[],\n): Record<string, unknown>[] {\n  return clientToolRunConfigEntries(tools);\n}\n\n/**\n * The frontend-toolkit entries that must ride `enabled_tools`: declarations\n * WITHOUT a local `execute`, which name registry tools the backend already\n * knows how to bind (Olympus's frontend-executed tool ids).\n *\n * Executable entries are deliberately left out. They are declared through\n * `client_tools`, and the run binds them by name; putting the same name into\n * `enabled_tools` would also switch on any backend toolkit that happens to\n * own a tool of that name, and the backend wins the resulting collision —\n * the client tool is dropped and the model calls the backend one instead.\n */\nexport function backendDeclaredFrontendToolIds(toolkit: Toolkit): string[] {\n  return Object.entries(toolkit)\n    .filter(([, entry]) => !hasCallableExecute(entry))\n    .map(([name]) => name);\n}\n\n/**\n * The `app_id` values the deep-agent runtime accepts as a client-tool surface.\n * Mirrors `agora/agora/graphs/athena_deep_agent/client_tools.py`: the fixed\n * first-party ids plus the `computer_asset_<uuid>` shape Athena's provisioning\n * injects into a computer-asset app. Any other `app_id` (or none) gets no\n * surface, and the runtime drops every `client_tools` declaration for the run.\n */\nexport const CLIENT_TOOL_SURFACE_APP_IDS = {\n  olympus: 'olympus',\n  officeAddin: 'athena-office-addin',\n  mobile: 'athena-mobile',\n} as const;\n\nconst SDK_APP_ID_PATTERN = /^computer_asset_[0-9a-f-]{8,64}$/;\n\nexport type ClientToolSurface = 'web' | 'office' | 'mobile' | 'sdk';\n\n/** The surface an `app_id` selects, or null when the runtime would refuse it. */\nexport function resolveClientToolSurface(appId: string | undefined | null): ClientToolSurface | null {\n  if (typeof appId !== 'string' || appId.length === 0) return null;\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.olympus) return 'web';\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.officeAddin) return 'office';\n  if (appId === CLIENT_TOOL_SURFACE_APP_IDS.mobile) return 'mobile';\n  if (SDK_APP_ID_PATTERN.test(appId)) return 'sdk';\n  return null;\n}\n"],"names":[],"mappings":"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"}

package/dist/chat-ui/index.cjs

@@ -25,6 +25,7 @@ const apiClient = require("./mentions/suggestions/data/api-client.cjs");
 const useMentionSuggestions = require("./mentions/suggestions/data/use-mention-suggestions.cjs");
 const index = require("./mentions/suggestions/data/sources/index.cjs");
 const assetTypeIcons = require("./mentions/suggestions/data/sources/asset-type-icons.cjs");
+const useAssetIconAppUrl = require("./mentions/use-asset-icon-app-url.cjs");
 const types = require("./mentions/suggestions/data/types.cjs");
 const assetUrls = require("./lib/asset-urls.cjs");
 const messageComponents = require("./messages/message-components.cjs");
@@ -108,6 +109,7 @@ exports.buildRootMenuItems = index.buildRootMenuItems;
 exports.assetTypeToIcon = assetTypeIcons.assetTypeToIcon;
 exports.assetTypeToThumb = assetTypeIcons.assetTypeToThumb;
 exports.configureAssetIconBasePath = assetTypeIcons.configureAssetIconBasePath;
+exports.useAssetIconAppUrl = useAssetIconAppUrl.useAssetIconAppUrl;
 exports.MentionMenuSection = types.MentionMenuSection;
 exports.createOlympusAssetUrl = assetUrls.createOlympusAssetUrl;
 exports.BranchPicker = messageComponents.BranchPicker;

package/dist/chat-ui/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/chat-ui/index.d.ts

@@ -35,6 +35,7 @@ export { AthenaGraphQLError, MentionAuthCtx, fetchGraphQL, SIMPLE_SEARCH_QUERY,
 export { ROOT_MENTION_CATEGORIES, useMentionSuggestions, webpageMentionFingerprint, type MentionRootCategory, type MentionSuggestionsStore, } from "./mentions/suggestions/data/use-mention-suggestions";
 export { buildRootMenuItems } from "./mentions/suggestions/data/sources";
 export { assetTypeToIcon, assetTypeToThumb, configureAssetIconBasePath, } from "./mentions/suggestions/data/sources/asset-type-icons";
+export { useAssetIconAppUrl } from "./mentions/use-asset-icon-app-url";
 export { MentionMenuSection, type MentionChatAgent, type MentionChatAgents, type MentionTool, type MenuItem, type MenuScope, type WebpageMention, type WebpageMentionScope, } from "./mentions/suggestions/data/types";
 export { createOlympusAssetUrl } from "./lib/asset-urls";
 export { COMPOSER_DOCK_CLASS, COMPOSER_EDITOR_ROW_CLASS, COMPOSER_PAPER_DOCK_CLASS, COMPOSER_PAPER_EDITOR_ROW_CLASS, COMPOSER_PAPER_SURFACE_CLASS, COMPOSER_PAPER_TOOLBAR_CLASS, COMPOSER_SURFACE_CLASS, COMPOSER_TOOLBAR_CLASS, BranchPicker, ComposerSendButton, ComposerStopButton, type ComposerSendButtonProps, type ComposerStopButtonProps, MarkdownText, THREAD_SCROLL_TO_BOTTOM_CLASS, UserMessage, UserMessageText, createAssistantMessage, type CreateAssistantMessageOptions, } from "./messages/message-components";

package/dist/chat-ui/index.js

@@ -23,6 +23,7 @@ import { AthenaGraphQLError, MentionAuthCtx, SIMPLE_SEARCH_QUERY, fetchGraphQL,
 import { ROOT_MENTION_CATEGORIES, useMentionSuggestions, webpageMentionFingerprint } from "./mentions/suggestions/data/use-mention-suggestions.js";
 import { buildRootMenuItems } from "./mentions/suggestions/data/sources/index.js";
 import { assetTypeToIcon, assetTypeToThumb, configureAssetIconBasePath } from "./mentions/suggestions/data/sources/asset-type-icons.js";
+import { useAssetIconAppUrl } from "./mentions/use-asset-icon-app-url.js";
 import { MentionMenuSection } from "./mentions/suggestions/data/types.js";
 import { createOlympusAssetUrl } from "./lib/asset-urls.js";
 import { BranchPicker, COMPOSER_DOCK_CLASS, COMPOSER_EDITOR_ROW_CLASS, COMPOSER_PAPER_DOCK_CLASS, COMPOSER_PAPER_EDITOR_ROW_CLASS, COMPOSER_PAPER_SURFACE_CLASS, COMPOSER_PAPER_TOOLBAR_CLASS, COMPOSER_SURFACE_CLASS, COMPOSER_TOOLBAR_CLASS, ComposerSendButton, ComposerStopButton, MarkdownText, THREAD_SCROLL_TO_BOTTOM_CLASS, UserMessage, UserMessageText, createAssistantMessage } from "./messages/message-components.js";
@@ -164,6 +165,7 @@ export {
   serializeMention,
   slashCommandRows,
   startHandoffCursorReveal,
+  useAssetIconAppUrl,
   useAthenaBrowserDecisionConfirmer,
   useBrowserDecisionConfirmer,
   useMentionAuth,

package/dist/chat-ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/chat-ui/mentions/mention-chip.cjs

@@ -9,6 +9,8 @@ const lucideReact = require("lucide-react");
 const assetUrls = require("../lib/asset-urls.cjs");
 const apiClient = require("./suggestions/data/api-client.cjs");
 const assetTypeIcons = require("./suggestions/data/sources/asset-type-icons.cjs");
+const useAssetIconAppUrl = require("./use-asset-icon-app-url.cjs");
+const mentionIcon = require("./suggestions/components/mention-icon.cjs");
 const useMemberAvatar = require("./use-member-avatar.cjs");
 const useMentionAsset = require("./use-mention-asset.cjs");
 const screenPoint = require("../../agent-runtime/src/screen-point.cjs");
@@ -211,6 +213,7 @@ const MentionChip = ({
   interactive = true
 }) => {
   const auth = require$$0.useContext(apiClient.MentionAuthCtx);
+  const iconAppUrl = useAssetIconAppUrl.useAssetIconAppUrl();
   const memberAvatarUrl = useMemberAvatar.useMemberAvatarUrl(personEmail);
   const [erroredAvatarUrl, setErroredAvatarUrl] = require$$0.useState();
   const excerpt = sourceHref ? readSourceExcerpt(sourceHref) : null;
@@ -249,20 +252,23 @@ const MentionChip = ({
     }
   })();
   const className = cnfast.cn(CHIP_PILL_CLASS, "max-w-[275px]", href && CHIP_LINK_CLASS);
-  const chipThumbnailUrl = repositoryFile ? void 0 : (asset == null ? void 0 : asset.assetType) && assetTypeIcons.assetTypeToThumb(asset.assetType) || thumbnailUrl;
+  const typeThumbnailUrl = repositoryFile ? void 0 : (asset == null ? void 0 : asset.assetType) && assetTypeIcons.assetTypeToThumb(asset.assetType, { appUrl: iconAppUrl }) || thumbnailUrl || (type === "asset" || type === "folder" ? assetTypeIcons.assetTypeToThumb(type === "folder" ? "folder" : assetType, { appUrl: iconAppUrl }) : void 0);
+  const typeThumbnail = mentionIcon.useThumbnailLoadFailure(typeThumbnailUrl);
+  const chipThumbnailUrl = typeThumbnail.failed ? void 0 : typeThumbnailUrl;
   const AssetIcon = assetChipIcon((asset == null ? void 0 : asset.assetType) || assetType);
   const contents = /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
     repositoryFile ? /* @__PURE__ */ jsxRuntime.jsx(GitHubMarkIcon, { className: CHIP_ICON_CLASS }) : chipThumbnailUrl ? /* @__PURE__ */ jsxRuntime.jsx(
       "img",
       {
+        ref: typeThumbnail.imageRef,
         src: chipThumbnailUrl,
         alt: "",
         className: CHIP_ICON_CLASS,
         draggable: false
       }
     ) : type === "asset" || type === "folder" ? (
-      // A host that bundles no asset-type SVGs (computer apps, most SDK
-      // apps) still gets the type's icon.
+      // Outside a provider with no host copy of the SVGs, or when one
+      // cannot load, the chip still draws the type's icon.
       /* @__PURE__ */ jsxRuntime.jsx(AssetIcon, { className: CHIP_ICON_CLASS, "aria-hidden": "true" })
     ) : type === "webpage" ? /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Globe2Icon, { className: CHIP_ICON_CLASS, "aria-hidden": "true" }) : type === "person" ? memberAvatarUrl && erroredAvatarUrl !== memberAvatarUrl ? /* @__PURE__ */ jsxRuntime.jsx(
       "img",