@athenaintel/react 0.28.1 → 0.30.0

package/dist/runtime/useAthenaStatewireRuntime.js

@@ -7,9 +7,10 @@ import { resolveStatewireAuthHeaders } from "./statewire-auth-headers.js";
 import { statewireSessionKey } from "./statewire-session-key.js";
 import { resolveAgentProp, buildStatewireRunConfig } from "./statewire-run-config.js";
 import { DEFAULT_STATEWIRE_MODEL } from "./statewire-run-config.js";
-import { DEEP_AGENT_DEFAULT_MESSAGE_WINDOW } from "../packages/agent-runtime/src/generated/runconfig-contract.js";
-import { useDeepAgentRuntime, logUnhandledStatewireError } from "../packages/agent-runtime/src/use-deep-agent-runtime.js";
-import { isStatewireChannelTeardown } from "../packages/agent-runtime/src/errors.js";
+import { DEEP_AGENT_DEFAULT_MESSAGE_WINDOW } from "../agent-runtime/src/generated/runconfig-contract.js";
+import { useDeepAgentRuntime, logUnhandledStatewireError } from "../agent-runtime/src/use-deep-agent-runtime.js";
+import { isStatewireChannelTeardown } from "../agent-runtime/src/errors.js";
+import { withStagedComposerMarkdown } from "../agent-runtime/src/composer-markdown.js";
 const ATHENA_SDK_MESSAGE_WINDOW = {
   size: DEEP_AGENT_DEFAULT_MESSAGE_WINDOW
 };
@@ -95,6 +96,10 @@ function useAthenaStatewireRuntime(config) {
     messageWindow,
     toolOutputs,
     capabilities: { edit: true, reload: true, continue: true },
+    // The composer stages the draft each send came from right before it
+    // sends; the message carries it as its composer markdown, so its bubble
+    // shows the text exactly as typed (`UserMessageText`).
+    getMessageMetadata: withStagedComposerMarkdown({ threadId }),
     useClient: useSdkClient,
     onStateChange: () => {
       const endSpan = attachSpanRef.current;
@@ -119,10 +124,9 @@ function useAthenaStatewireRuntime(config) {
     },
     onRawConnectionChange,
     onRunningChange,
-    // The runConfig getter is pulled at command-send time through the core's
-    // per-render ref, so it reads the latest props — consumers commonly pass
-    // fresh array literals per render, which must not thrash the registration
-    // (no `key`: the provider registers once per client).
+    // Each model-context notification pulls the latest getter through the
+    // core's per-render ref. Consumers commonly pass fresh array literals per
+    // render, which must not thrash registration (no `key`: once per client).
     runConfig: {
       get: () => buildStatewireRunConfig({
         model,

package/dist/runtime/useAthenaStatewireRuntime.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAthenaStatewireRuntime.js","sources":["../../src/runtime/useAthenaStatewireRuntime.ts"],"sourcesContent":["import type { AssistantClient, Toolkit } from '@assistant-ui/react';\nimport { Tools, useAui } from '@assistant-ui/react';\nimport {\n  DEEP_AGENT_DEFAULT_MESSAGE_WINDOW,\n  type DeepAgentMessageWindowDeclaration,\n  type DeepAgentThreadElement,\n  type DeepAgentThreadSnapshotCache,\n  type DeepAgentToolOutputStore,\n  isStatewireChannelTeardown,\n  logUnhandledStatewireError,\n  type RegisteredClientTool,\n  useDeepAgentRuntime,\n  type UseDeepAgentThreadOptions,\n} from '@athenaintel/agent-runtime';\nimport { useContext, useMemo, useRef } from 'react';\nimport { AthenaAuthContext } from '../auth/AthenaAuthContext';\nimport {\n  collectStatewireClientTools,\n  statewireClientToolWireEntries,\n} from '../chat/statewire-client-tools';\nimport { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport {\n  type AthenaStatewireTokenGetter,\n  resolveStatewireAuthHeaders,\n} from './statewire-auth-headers';\nimport { statewireSessionKey } from './statewire-session-key';\n\ntype AthenaDiagnosticsSpanStarter = typeof athenaDiagnostics.span;\nimport {\n  buildStatewireRunConfig,\n  DEFAULT_STATEWIRE_MODEL,\n  resolveAgentProp,\n} from './statewire-run-config';\n\nexport { DEFAULT_STATEWIRE_MODEL };\n\n/**\n * The head interest every SDK attach states (`athena/interest`): the host\n * mounts the transcript's tail as message documents instead of every message\n * — megabytes on long threads, over the 1 MiB frame limit of stock websocket\n * clients. Older pages load from the `StatewireHistoryEdge` row the chat UI\n * mounts above the messages, and cut tool outputs are fetched back for the\n * cards that show them.\n */\nexport const ATHENA_SDK_MESSAGE_WINDOW: DeepAgentMessageWindowDeclaration = {\n  size: DEEP_AGENT_DEFAULT_MESSAGE_WINDOW,\n};\n\nexport interface AthenaStatewireRuntimeConfig {\n  /** Base URL of the statewire sync host (the `…/v2/threads` mount). */\n  syncUrl: string;\n  /** Thread ID the statewire session attaches to. */\n  threadId: string;\n  /** True only for a never-started local chat. Existing (or pre-assigned)\n   *  threads load until their server snapshot arrives. */\n  isNewChat?: boolean;\n  /** API key for authentication. Used when no auth token is provided. */\n  apiKey?: string;\n  /** Auth token. Takes priority over apiKey. */\n  token?: string | null;\n  /** Resolve the latest token immediately before a request (for expiring\n   *  clients). Called with `{ force: true }` right after the host refused the\n   *  previous credential (the transport's `staleAuth`), so a caching getter\n   *  mints a fresh token instead of returning the refused one. */\n  getToken?: AthenaStatewireTokenGetter;\n  /**\n   * Per-provider LRU of each thread's last wire state. A switch back to a\n   * remembered thread mounts with that snapshot and projects ready on the\n   * first frame instead of a loading treatment; the attach snapshot then\n   * replaces it. Owned above the per-thread mount so it survives switches.\n   */\n  snapshotCache?: DeepAgentThreadSnapshotCache;\n  /** The head interest stated on the attach (see {@link ATHENA_SDK_MESSAGE_WINDOW}, the default). */\n  messageWindow?: DeepAgentMessageWindowDeclaration;\n  /**\n   * Full tool outputs fetched back for a windowed wire's cut tool messages;\n   * the thread re-converts when one lands. `AthenaProvider` owns one per\n   * provider and hands the same store to `StatewireHistoryEdge`.\n   */\n  toolOutputs?: DeepAgentToolOutputStore;\n  /** LLM model identifier. Defaults to the deep-agent default model. */\n  model?: string;\n  /** Agent selector: only `collab_agent:<asset_id>` refs are accepted (the run\n   *  executes AS that published collab agent). Any other non-empty value\n   *  throws — see `resolveAgentProp`. */\n  agent?: string;\n  /** Collab-agent channel id selecting that channel's overrides. */\n  channel?: string;\n  /** Backend toolkit IDs to enable. */\n  tools?: string[];\n  /** Frontend tool IDs to include in enabled_tools. */\n  frontendToolIds?: string[];\n  /** Frontend tools registered on the assistant client. Tools with a local\n   *  `execute` are also declared as `client_tools` and executed through the\n   *  statewire client-tool bridge. */\n  frontendToolkit?: Toolkit;\n  /** Asset IDs to include in the workbench. */\n  workbench?: string[];\n  /** Knowledge base IDs for RAG context. */\n  knowledgeBase?: string[];\n  /** System prompt override. */\n  systemPrompt?: string;\n  /** Client app identifier for session filtering. Sent as app_id in runConfig.custom. */\n  appId?: string;\n  /** Additional fields merged into runConfig.custom. */\n  extraRunConfig?: Record<string, unknown>;\n  /** Called on statewire transport errors (send rejections, stream failures). */\n  onError?: (error: Error) => void;\n  /** Projected connection status changes (deduped; null on unmount). */\n  onConnectionChange?: UseDeepAgentThreadOptions['onConnectionChange'];\n  /** Raw connection observer — carries the transport's reconnect handle. */\n  onRawConnectionChange?: UseDeepAgentThreadOptions['onRawConnectionChange'];\n  /** Notified when a run starts/stops. */\n  onRunningChange?: UseDeepAgentThreadOptions['onRunningChange'];\n}\n\nconst EMPTY_TOOLKIT: Toolkit = {};\nconst EMPTY_TOOL_IDS: string[] = [];\n\n/** The client tools derived from the runtime's frontend toolkit — exposed so\n *  the provider can mount the client-tool bridge with the same set. */\nexport function useStatewireClientTools(\n  frontendToolkit: Toolkit | undefined,\n): RegisteredClientTool[] {\n  return useMemo(\n    () => collectStatewireClientTools(frontendToolkit ?? EMPTY_TOOLKIT),\n    [frontendToolkit],\n  );\n}\n\n/**\n * Statewire runtime for the Athena SDK — a thin shim over the shared\n * `@athenaintel/agent-runtime` `useDeepAgentRuntime`: it attaches to the\n * agora-hosted deep-agent thread at `${syncUrl}/${threadId}` and returns the\n * `AssistantClient` to mount via `AuiProvider` — the same integration shape as\n * the Olympus, Chrome extension, Office, and mobile statewire hosts.\n *\n * Auth: a token (resolved live through `getToken` when provided) rides\n * `Authorization: Bearer`, and an API key falls back to `X-API-KEY` — both\n * accepted by the statewire host.\n */\nexport function useAthenaStatewireRuntime(\n  config: AthenaStatewireRuntimeConfig,\n): AssistantClient {\n  const {\n    syncUrl,\n    threadId,\n    isNewChat = false,\n    apiKey,\n    token,\n    getToken,\n    model,\n    agent,\n    channel,\n    tools = EMPTY_TOOL_IDS,\n    frontendToolIds = EMPTY_TOOL_IDS,\n    frontendToolkit = EMPTY_TOOLKIT,\n    workbench,\n    knowledgeBase,\n    systemPrompt,\n    appId,\n    extraRunConfig,\n    snapshotCache,\n    messageWindow = ATHENA_SDK_MESSAGE_WINDOW,\n    toolOutputs,\n    onError,\n    onConnectionChange,\n    onRawConnectionChange,\n    onRunningChange,\n  } = config;\n\n  // Fail loud at mount, not at first send: the statewire host always runs the\n  // Athena deep agent, so an `agent` outside the collab_agent namespace can\n  // never apply. Throwing here (render time) is what makes a misconfigured\n  // integration visible instead of quietly answering as the wrong agent.\n  resolveAgentProp({ agent });\n\n  const clientTools = useStatewireClientTools(frontendToolkit);\n\n  // The persisted command lane is keyed by WHO is signed in as well as by host\n  // and thread (see `statewireSessionKey`).\n  const authContext = useContext(AthenaAuthContext);\n  const principal = authContext?.user?.userId ?? '';\n\n  // Attach → first server snapshot span, keyed per thread attach.\n  const attachSpanRef = useRef<ReturnType<AthenaDiagnosticsSpanStarter> | null>(null);\n  const attachThreadRef = useRef<string | null>(null);\n  if (attachThreadRef.current !== threadId) {\n    attachThreadRef.current = threadId;\n    attachSpanRef.current = athenaDiagnostics.span(\n      `statewire.attach:${threadId}`,\n      'statewire.attach.start',\n      { thread_id: threadId, is_new_chat: isNewChat },\n    );\n  }\n\n  const auiTools = useMemo(() => Tools({ toolkit: frontendToolkit }), [frontendToolkit]);\n  // Web client for the shared runtime core (a `use*` name so the\n  // rules-of-hooks lint sees the `useAui` call inside a custom hook; the core\n  // invokes it unconditionally every render).\n  const useSdkClient = (thread: DeepAgentThreadElement) => useAui({ thread, tools: auiTools });\n\n  return useDeepAgentRuntime({\n    surface: 'AthenaSDK',\n    threadId,\n    baseUrl: syncUrl,\n    // Option closures are re-read per render by the core, so credential\n    // rotation (new `token`/`getToken`/`apiKey` props) reaches the next\n    // request without remounting the thread. The transport's `staleAuth`\n    // (true right after a refused credential) is forwarded as `force`.\n    headers: (ctx) => resolveStatewireAuthHeaders({ apiKey, token, getToken }, ctx),\n    isNewChat,\n    // Queued entries render in the SDK's queue panel, so only the steer lane\n    // projects into the message tail.\n    laneProjection: 'steer-only',\n    // Durable session: a reload resumes the lane and resends whatever the\n    // server has not marked durable. Scoped by host AND principal — a thread\n    // id is only meaningful against the backend that minted it, and a stored\n    // lane must never resend against another signed-in user. (Consumers\n    // server-render this SDK; the core's availability probe keeps those\n    // sessions process-local, as before the seam existed.)\n    session: {\n      kind: 'local-storage',\n      key: (id) => statewireSessionKey({ syncUrl, principal, threadId: id }),\n    },\n    snapshotCache,\n    // Head interest (see `ATHENA_SDK_MESSAGE_WINDOW`): the tail of the\n    // transcript instead of every message; the chat UI's history edge pages\n    // older ranges in and fetches cut tool outputs into `toolOutputs`.\n    messageWindow,\n    toolOutputs,\n    capabilities: { edit: true, reload: true, continue: true },\n    useClient: useSdkClient,\n    onStateChange: () => {\n      // First snapshot for this attach ends the attach span (time-to-history).\n      const endSpan = attachSpanRef.current;\n      if (endSpan) {\n        attachSpanRef.current = null;\n        endSpan('statewire.snapshot', { data: { thread_id: threadId } });\n      }\n    },\n    onConnectionChange: (connection) => {\n      athenaDiagnostics.gauge('statewire.connection', connection?.status ?? null);\n      if (connection?.status === 'stopped') {\n        athenaDiagnostics.emit('statewire.connection', {\n          level: 'warn',\n          data: {\n            status: connection.status,\n            reason: connection.reason,\n            message: connection.message,\n          },\n        });\n      }\n      onConnectionChange?.(connection);\n    },\n    onRawConnectionChange,\n    onRunningChange,\n    // The runConfig getter is pulled at command-send time through the core's\n    // per-render ref, so it reads the latest props — consumers commonly pass\n    // fresh array literals per render, which must not thrash the registration\n    // (no `key`: the provider registers once per client).\n    runConfig: {\n      get: () =>\n        buildStatewireRunConfig({\n          model,\n          agent,\n          channel,\n          tools,\n          frontendToolIds,\n          workbench,\n          knowledgeBase,\n          systemPrompt,\n          appId,\n          extraRunConfig,\n          clientTools: statewireClientToolWireEntries(clientTools),\n        }),\n    },\n    onError: (error) => {\n      if (!isStatewireChannelTeardown(error)) {\n        athenaDiagnostics.error(\n          'statewire.error',\n          error,\n          {\n            code: 'statewire_rejected',\n            message: 'The statewire host rejected a command',\n            hint: 'Inspect error.detail — agora rejections carry a structured {code, message}.',\n          },\n          { thread_id: threadId },\n        );\n      }\n      if (onError) {\n        onError(error);\n        return;\n      }\n      logUnhandledStatewireError('AthenaSDK', error);\n    },\n  });\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"useAthenaStatewireRuntime.js","sources":["../../src/runtime/useAthenaStatewireRuntime.ts"],"sourcesContent":["import type { AssistantClient, Toolkit } from '@assistant-ui/react';\nimport { Tools, useAui } from '@assistant-ui/react';\nimport {\n  DEEP_AGENT_DEFAULT_MESSAGE_WINDOW,\n  type DeepAgentMessageWindowDeclaration,\n  type DeepAgentThreadElement,\n  type DeepAgentThreadSnapshotCache,\n  type DeepAgentToolOutputStore,\n  isStatewireChannelTeardown,\n  logUnhandledStatewireError,\n  type RegisteredClientTool,\n  useDeepAgentRuntime,\n  type UseDeepAgentThreadOptions,\n  withStagedComposerMarkdown,\n} from '@athenaintel/agent-runtime';\nimport { useContext, useMemo, useRef } from 'react';\nimport { AthenaAuthContext } from '../auth/AthenaAuthContext';\nimport {\n  collectStatewireClientTools,\n  statewireClientToolWireEntries,\n} from '../chat/statewire-client-tools';\nimport { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport {\n  type AthenaStatewireTokenGetter,\n  resolveStatewireAuthHeaders,\n} from './statewire-auth-headers';\nimport { statewireSessionKey } from './statewire-session-key';\n\ntype AthenaDiagnosticsSpanStarter = typeof athenaDiagnostics.span;\nimport {\n  buildStatewireRunConfig,\n  DEFAULT_STATEWIRE_MODEL,\n  resolveAgentProp,\n} from './statewire-run-config';\n\nexport { DEFAULT_STATEWIRE_MODEL };\n\n/**\n * The head interest every SDK attach states (`athena/interest`): the host\n * mounts the transcript's tail as message documents instead of every message\n * — megabytes on long threads, over the 1 MiB frame limit of stock websocket\n * clients. Older pages load from the `StatewireHistoryEdge` row the chat UI\n * mounts above the messages, and cut tool outputs are fetched back for the\n * cards that show them.\n */\nexport const ATHENA_SDK_MESSAGE_WINDOW: DeepAgentMessageWindowDeclaration = {\n  size: DEEP_AGENT_DEFAULT_MESSAGE_WINDOW,\n};\n\nexport interface AthenaStatewireRuntimeConfig {\n  /** Base URL of the statewire sync host (the `…/v2/threads` mount). */\n  syncUrl: string;\n  /** Thread ID the statewire session attaches to. */\n  threadId: string;\n  /** True only for a never-started local chat. Existing (or pre-assigned)\n   *  threads load until their server snapshot arrives. */\n  isNewChat?: boolean;\n  /** API key for authentication. Used when no auth token is provided. */\n  apiKey?: string;\n  /** Auth token. Takes priority over apiKey. */\n  token?: string | null;\n  /** Resolve the latest token immediately before a request (for expiring\n   *  clients). Called with `{ force: true }` right after the host refused the\n   *  previous credential (the transport's `staleAuth`), so a caching getter\n   *  mints a fresh token instead of returning the refused one. */\n  getToken?: AthenaStatewireTokenGetter;\n  /**\n   * Per-provider LRU of each thread's last wire state. A switch back to a\n   * remembered thread mounts with that snapshot and projects ready on the\n   * first frame instead of a loading treatment; the attach snapshot then\n   * replaces it. Owned above the per-thread mount so it survives switches.\n   */\n  snapshotCache?: DeepAgentThreadSnapshotCache;\n  /** The head interest stated on the attach (see {@link ATHENA_SDK_MESSAGE_WINDOW}, the default). */\n  messageWindow?: DeepAgentMessageWindowDeclaration;\n  /**\n   * Full tool outputs fetched back for a windowed wire's cut tool messages;\n   * the thread re-converts when one lands. `AthenaProvider` owns one per\n   * provider and hands the same store to `StatewireHistoryEdge`.\n   */\n  toolOutputs?: DeepAgentToolOutputStore;\n  /** LLM model identifier. Defaults to the deep-agent default model. */\n  model?: string;\n  /** Agent selector: only `collab_agent:<asset_id>` refs are accepted (the run\n   *  executes AS that published collab agent). Any other non-empty value\n   *  throws — see `resolveAgentProp`. */\n  agent?: string;\n  /** Collab-agent channel id selecting that channel's overrides. */\n  channel?: string;\n  /** Backend toolkit IDs to enable. */\n  tools?: string[];\n  /** Frontend tool IDs to include in enabled_tools. */\n  frontendToolIds?: string[];\n  /** Frontend tools registered on the assistant client. Tools with a local\n   *  `execute` are also declared as `client_tools` and executed through the\n   *  statewire client-tool bridge. */\n  frontendToolkit?: Toolkit;\n  /** Asset IDs to include in the workbench. */\n  workbench?: string[];\n  /** Knowledge base IDs for RAG context. */\n  knowledgeBase?: string[];\n  /** System prompt override. */\n  systemPrompt?: string;\n  /** Client app identifier for session filtering. Sent as app_id in runConfig.custom. */\n  appId?: string;\n  /** Additional fields merged into runConfig.custom. */\n  extraRunConfig?: Record<string, unknown>;\n  /** Called on statewire transport errors (send rejections, stream failures). */\n  onError?: (error: Error) => void;\n  /** Projected connection status changes (deduped; null on unmount). */\n  onConnectionChange?: UseDeepAgentThreadOptions['onConnectionChange'];\n  /** Raw connection observer — carries the transport's reconnect handle. */\n  onRawConnectionChange?: UseDeepAgentThreadOptions['onRawConnectionChange'];\n  /** Notified when a run starts/stops. */\n  onRunningChange?: UseDeepAgentThreadOptions['onRunningChange'];\n}\n\nconst EMPTY_TOOLKIT: Toolkit = {};\nconst EMPTY_TOOL_IDS: string[] = [];\n\n/** The client tools derived from the runtime's frontend toolkit — exposed so\n *  the provider can mount the client-tool bridge with the same set. */\nexport function useStatewireClientTools(\n  frontendToolkit: Toolkit | undefined,\n): RegisteredClientTool[] {\n  return useMemo(\n    () => collectStatewireClientTools(frontendToolkit ?? EMPTY_TOOLKIT),\n    [frontendToolkit],\n  );\n}\n\n/**\n * Statewire runtime for the Athena SDK — a thin shim over the shared\n * `@athenaintel/agent-runtime` `useDeepAgentRuntime`: it attaches to the\n * agora-hosted deep-agent thread at `${syncUrl}/${threadId}` and returns the\n * `AssistantClient` to mount via `AuiProvider` — the same integration shape as\n * the Olympus, Chrome extension, Office, and mobile statewire hosts.\n *\n * Auth: a token (resolved live through `getToken` when provided) rides\n * `Authorization: Bearer`, and an API key falls back to `X-API-KEY` — both\n * accepted by the statewire host.\n */\nexport function useAthenaStatewireRuntime(\n  config: AthenaStatewireRuntimeConfig,\n): AssistantClient {\n  const {\n    syncUrl,\n    threadId,\n    isNewChat = false,\n    apiKey,\n    token,\n    getToken,\n    model,\n    agent,\n    channel,\n    tools = EMPTY_TOOL_IDS,\n    frontendToolIds = EMPTY_TOOL_IDS,\n    frontendToolkit = EMPTY_TOOLKIT,\n    workbench,\n    knowledgeBase,\n    systemPrompt,\n    appId,\n    extraRunConfig,\n    snapshotCache,\n    messageWindow = ATHENA_SDK_MESSAGE_WINDOW,\n    toolOutputs,\n    onError,\n    onConnectionChange,\n    onRawConnectionChange,\n    onRunningChange,\n  } = config;\n\n  // Fail loud at mount, not at first send: the statewire host always runs the\n  // Athena deep agent, so an `agent` outside the collab_agent namespace can\n  // never apply. Throwing here (render time) is what makes a misconfigured\n  // integration visible instead of quietly answering as the wrong agent.\n  resolveAgentProp({ agent });\n\n  const clientTools = useStatewireClientTools(frontendToolkit);\n\n  // The persisted command lane is keyed by WHO is signed in as well as by host\n  // and thread (see `statewireSessionKey`).\n  const authContext = useContext(AthenaAuthContext);\n  const principal = authContext?.user?.userId ?? '';\n\n  // Attach → first server snapshot span, keyed per thread attach.\n  const attachSpanRef = useRef<ReturnType<AthenaDiagnosticsSpanStarter> | null>(null);\n  const attachThreadRef = useRef<string | null>(null);\n  if (attachThreadRef.current !== threadId) {\n    attachThreadRef.current = threadId;\n    attachSpanRef.current = athenaDiagnostics.span(\n      `statewire.attach:${threadId}`,\n      'statewire.attach.start',\n      { thread_id: threadId, is_new_chat: isNewChat },\n    );\n  }\n\n  const auiTools = useMemo(() => Tools({ toolkit: frontendToolkit }), [frontendToolkit]);\n  // Web client for the shared runtime core (a `use*` name so the\n  // rules-of-hooks lint sees the `useAui` call inside a custom hook; the core\n  // invokes it unconditionally every render).\n  const useSdkClient = (thread: DeepAgentThreadElement) => useAui({ thread, tools: auiTools });\n\n  return useDeepAgentRuntime({\n    surface: 'AthenaSDK',\n    threadId,\n    baseUrl: syncUrl,\n    // Option closures are re-read per render by the core, so credential\n    // rotation (new `token`/`getToken`/`apiKey` props) reaches the next\n    // request without remounting the thread. The transport's `staleAuth`\n    // (true right after a refused credential) is forwarded as `force`.\n    headers: (ctx) => resolveStatewireAuthHeaders({ apiKey, token, getToken }, ctx),\n    isNewChat,\n    // Queued entries render in the SDK's queue panel, so only the steer lane\n    // projects into the message tail.\n    laneProjection: 'steer-only',\n    // Durable session: a reload resumes the lane and resends whatever the\n    // server has not marked durable. Scoped by host AND principal — a thread\n    // id is only meaningful against the backend that minted it, and a stored\n    // lane must never resend against another signed-in user. (Consumers\n    // server-render this SDK; the core's availability probe keeps those\n    // sessions process-local, as before the seam existed.)\n    session: {\n      kind: 'local-storage',\n      key: (id) => statewireSessionKey({ syncUrl, principal, threadId: id }),\n    },\n    snapshotCache,\n    // Head interest (see `ATHENA_SDK_MESSAGE_WINDOW`): the tail of the\n    // transcript instead of every message; the chat UI's history edge pages\n    // older ranges in and fetches cut tool outputs into `toolOutputs`.\n    messageWindow,\n    toolOutputs,\n    capabilities: { edit: true, reload: true, continue: true },\n    // The composer stages the draft each send came from right before it\n    // sends; the message carries it as its composer markdown, so its bubble\n    // shows the text exactly as typed (`UserMessageText`).\n    getMessageMetadata: withStagedComposerMarkdown({ threadId }),\n    useClient: useSdkClient,\n    onStateChange: () => {\n      // First snapshot for this attach ends the attach span (time-to-history).\n      const endSpan = attachSpanRef.current;\n      if (endSpan) {\n        attachSpanRef.current = null;\n        endSpan('statewire.snapshot', { data: { thread_id: threadId } });\n      }\n    },\n    onConnectionChange: (connection) => {\n      athenaDiagnostics.gauge('statewire.connection', connection?.status ?? null);\n      if (connection?.status === 'stopped') {\n        athenaDiagnostics.emit('statewire.connection', {\n          level: 'warn',\n          data: {\n            status: connection.status,\n            reason: connection.reason,\n            message: connection.message,\n          },\n        });\n      }\n      onConnectionChange?.(connection);\n    },\n    onRawConnectionChange,\n    onRunningChange,\n    // Each model-context notification pulls the latest getter through the\n    // core's per-render ref. Consumers commonly pass fresh array literals per\n    // render, which must not thrash registration (no `key`: once per client).\n    runConfig: {\n      get: () =>\n        buildStatewireRunConfig({\n          model,\n          agent,\n          channel,\n          tools,\n          frontendToolIds,\n          workbench,\n          knowledgeBase,\n          systemPrompt,\n          appId,\n          extraRunConfig,\n          clientTools: statewireClientToolWireEntries(clientTools),\n        }),\n    },\n    onError: (error) => {\n      if (!isStatewireChannelTeardown(error)) {\n        athenaDiagnostics.error(\n          'statewire.error',\n          error,\n          {\n            code: 'statewire_rejected',\n            message: 'The statewire host rejected a command',\n            hint: 'Inspect error.detail — agora rejections carry a structured {code, message}.',\n          },\n          { thread_id: threadId },\n        );\n      }\n      if (onError) {\n        onError(error);\n        return;\n      }\n      logUnhandledStatewireError('AthenaSDK', error);\n    },\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/search/useAthenaRepoSearch.cjs

@@ -1,12 +1,11 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const reactQuery = require("@tanstack/react-query");
-const react = require("react");
 const mint = require("../collab/mint.cjs");
 const errors = require("../diagnostics/errors.cjs");
+const useAthenaRestQuery = require("../lib/use-athena-rest-query.cjs");
 const AthenaContext = require("../provider/AthenaContext.cjs");
 const credentialRenewal = require("../runtime/credential-renewal.cjs");
-const credentialShape = require("../threads/credential-shape.cjs");
 const ATHENA_REPO_SEARCH_PATH = "/api/search/repositories";
 function repoSearchRequestBody(params) {
   var _a, _b, _c;
@@ -61,19 +60,12 @@ function useAthenaRepoSearch({
 }) {
   const config = AthenaContext.useAthenaConfig();
   const { backendUrl, apiKey, getToken } = config;
-  const credentialsRef = react.useRef(credentialShape.credentialShape({ apiKey, token: config.token, getToken }));
-  const generationRef = react.useRef(0);
-  const currentCredentials = credentialShape.credentialShape({ apiKey, token: config.token, getToken });
-  if (!credentialShape.sameCredentialShape(credentialsRef.current, currentCredentials)) {
-    credentialsRef.current = currentCredentials;
-    generationRef.current += 1;
-  }
+  const identity = useAthenaRestQuery.useAthenaQueryIdentity({ apiKey, token: config.token, getToken });
   const body = repoSearchRequestBody(params);
-  const contextClient = react.useContext(reactQuery.QueryClientContext);
-  const [fallbackClient] = react.useState(() => contextClient ? void 0 : new reactQuery.QueryClient());
+  const queryClient = useAthenaRestQuery.useAthenaQueryClient();
   return reactQuery.useQuery(
     {
-      queryKey: ["athena-sdk", "repo-search", backendUrl, generationRef.current, body],
+      queryKey: ["athena-sdk", "repo-search", backendUrl, ...identity, body],
       // `config.token` is read at fetch time: the provider serves the latest
       // token through a getter, so rotations reach the request.
       queryFn: ({ signal }) => fetchRepoSearch(backendUrl, { apiKey, token: config.token, getToken }, params, { signal }),
@@ -82,7 +74,7 @@ function useAthenaRepoSearch({
       placeholderData: reactQuery.keepPreviousData,
       refetchOnWindowFocus: false
     },
-    contextClient ?? fallbackClient
+    queryClient
   );
 }
 exports.ATHENA_REPO_SEARCH_PATH = ATHENA_REPO_SEARCH_PATH;

package/dist/search/useAthenaRepoSearch.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useAthenaRepoSearch.cjs","sources":["../../src/search/useAthenaRepoSearch.ts"],"sourcesContent":["/**\n * Code search over the workspace's indexed repositories —\n * `POST /api/search/repositories` (agora `web/api/search/repositories.py`),\n * the HTTP face of Clio's repository source for a Devin-style \"Ask\" surface\n * that searches the monorepo without an agent turn. Athena platform staff\n * only (the account-level `is_admin`, not a workspace role) on the managed\n * cloud today: a non-staff caller reads `403`, a private deployment `404`.\n */\nimport {\n  keepPreviousData,\n  QueryClient,\n  QueryClientContext,\n  useQuery,\n  type UseQueryResult,\n} from '@tanstack/react-query';\nimport { useContext, useRef, useState } from 'react';\nimport { getAthenaApiBaseUrl } from '../collab/mint';\nimport { AthenaSdkError } from '../diagnostics/errors';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport { sendWithCredentialRenewal } from '../runtime/credential-renewal';\nimport type { StatewireAuthSource } from '../runtime/statewire-auth-headers';\nimport { credentialShape, sameCredentialShape } from '../threads/credential-shape';\n\nexport type AthenaRepoSearchMode = 'hybrid' | 'lexical';\n\n/** One file range of one indexed repository, as the route serves it. */\nexport interface AthenaRepoSearchHit {\n  /** The GitHub catalog asset the repository is connected through. */\n  catalogAssetId: string;\n  /** `owner/repo`; `null` when the catalog names no repository. */\n  repoFullName: string | null;\n  /** Repo-relative, `/`-separated. */\n  path: string;\n  /** 1-based, inclusive. */\n  startLine: number;\n  endLine: number;\n  /** The enclosing declaration (`Class.method`) when the chunk's header named one. */\n  symbol: string | null;\n  /** Clio's language name for the file (`python`, `typescript`, …). */\n  language: string | null;\n  /** `code` (an AST chunk) or `window` (a Markdown heading window). */\n  unitType: string;\n  score: number;\n  /** The indexed commit the hit was read at. */\n  commitSha: string | null;\n  /** `{origin}/{owner}/{repo}/blob/{sha}/{path}#L{a}-L{b}`, GHES-aware. */\n  githubUrl: string | null;\n  /** The chunk's lines, header line removed, line breaks preserved. */\n  snippet: string;\n  /** `asset_<catalog>?anchor=file_line_range&…` — what `read_asset` and a citation take. */\n  readAssetReference: string;\n}\n\nexport interface AthenaRepoSearchResponse {\n  /** Best first, at most `limit`. */\n  hits: AthenaRepoSearchHit[];\n  tookMs: number;\n  mode: AthenaRepoSearchMode;\n}\n\nexport interface AthenaRepoSearchParams {\n  query: string;\n  /** 1–25; the route's default is 10. */\n  limit?: number;\n  /** `hybrid` (default) or `lexical`. */\n  mode?: AthenaRepoSearchMode;\n  /** Search these GitHub catalog assets only; empty means every indexed repository. */\n  repositoryAssetIds?: string[];\n  /** gitignore-style globs a hit's path must match (`agora/**\\/*.py`, `docs/`). */\n  paths?: string[];\n  /** Clio language names a hit's file must be indexed as. */\n  languages?: string[];\n}\n\nexport interface UseAthenaRepoSearchOptions extends AthenaRepoSearchParams {\n  /** `false` holds the query idle (a blank `query` does too). Default `true`. */\n  enabled?: boolean;\n}\n\n/** The route's JSON body — snake_case, unset filters omitted. */\nexport interface AthenaRepoSearchRequestBody {\n  query: string;\n  limit?: number;\n  mode?: AthenaRepoSearchMode;\n  repository_asset_ids?: string[];\n  paths?: string[];\n  languages?: string[];\n}\n\nexport const ATHENA_REPO_SEARCH_PATH = '/api/search/repositories';\n\nexport function repoSearchRequestBody(params: AthenaRepoSearchParams): AthenaRepoSearchRequestBody {\n  const body: AthenaRepoSearchRequestBody = { query: params.query.trim() };\n  if (params.limit !== undefined) body.limit = params.limit;\n  if (params.mode !== undefined) body.mode = params.mode;\n  if (params.repositoryAssetIds?.length) body.repository_asset_ids = params.repositoryAssetIds;\n  if (params.paths?.length) body.paths = params.paths;\n  if (params.languages?.length) body.languages = params.languages;\n  return body;\n}\n\n/** A `fetch` the caller cancelled (unmount, a newer query): lifecycle, not failure. */\nfunction isAbortError(error: unknown): boolean {\n  return (error instanceof DOMException || error instanceof Error) && error.name === 'AbortError';\n}\n\n/**\n * One search request. The credential rides `Authorization: Bearer` (a token,\n * resolved live through `getToken` when the host provided one) or\n * `X-API-KEY`; with neither, a same-origin host's session cookie rides\n * automatically, as the SDK's other REST helpers allow. A refused bearer\n * (`401`) gets one forced re-mint through `getToken` (`force: true`, the\n * statewire transport's `staleAuth` contract; `sendWithCredentialRenewal`) — a\n * getter that caches until forced would otherwise resend the same expired\n * token on every retry. Every failure is an `AthenaSdkError`, transport\n * rejections included; only an abort keeps its own identity.\n */\nexport async function fetchRepoSearch(\n  backendUrl: string,\n  auth: StatewireAuthSource,\n  params: AthenaRepoSearchParams,\n  opts: { signal?: AbortSignal } = {},\n): Promise<AthenaRepoSearchResponse> {\n  const url = `${getAthenaApiBaseUrl(backendUrl)}${ATHENA_REPO_SEARCH_PATH}`;\n  const body = JSON.stringify(repoSearchRequestBody(params));\n  const post = async (headers: Record<string, string>): Promise<Response> => {\n    try {\n      return await fetch(url, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json', ...headers },\n        body,\n        signal: opts.signal ?? null,\n      });\n    } catch (error) {\n      if (isAbortError(error)) throw error;\n      throw new AthenaSdkError({\n        code: 'repo_search_failed',\n        message: 'Repository search could not reach the Agora API.',\n        cause: error,\n        hint: 'Check the network and that backendUrl points at the Agora API base.',\n      });\n    }\n  };\n  const res = await sendWithCredentialRenewal(auth, post);\n  if (!res.ok) {\n    const refused = res.status === 401 || res.status === 403;\n    throw new AthenaSdkError({\n      code: refused ? 'auth_rejected' : 'repo_search_failed',\n      message: `Repository search failed: ${res.status}`,\n      status: res.status,\n      detail: await res.json().catch(() => undefined),\n      hint: refused\n        ? 'Repository search is limited to Athena platform staff on the managed cloud; check the credential.'\n        : res.status === 404\n          ? 'Repository search is not offered on this deployment (managed cloud only).'\n          : 'Check backendUrl points at the Agora API base and that Clio is available.',\n    });\n  }\n  return (await res.json()) as AthenaRepoSearchResponse;\n}\n\n/**\n * Search the indexed repositories through TanStack Query with the provider's\n * `backendUrl` and credentials. Keyed by the non-secret request and a\n * credential generation (a counter that advances when the host's credentials\n * change), never by the credential itself. Uses the host's `QueryClient` when\n * one is in context (`enableThreadList` mounts the SDK's own) and a\n * hook-scoped client otherwise, so it works under any `<AthenaProvider>`.\n */\nexport function useAthenaRepoSearch({\n  enabled = true,\n  ...params\n}: UseAthenaRepoSearchOptions): UseQueryResult<AthenaRepoSearchResponse, Error> {\n  const config = useAthenaConfig();\n  const { backendUrl, apiKey, getToken } = config;\n  const credentialsRef = useRef(credentialShape({ apiKey, token: config.token, getToken }));\n  const generationRef = useRef(0);\n  const currentCredentials = credentialShape({ apiKey, token: config.token, getToken });\n  if (!sameCredentialShape(credentialsRef.current, currentCredentials)) {\n    credentialsRef.current = currentCredentials;\n    generationRef.current += 1;\n  }\n  const body = repoSearchRequestBody(params);\n  const contextClient = useContext(QueryClientContext);\n  const [fallbackClient] = useState(() => (contextClient ? undefined : new QueryClient()));\n  return useQuery(\n    {\n      queryKey: ['athena-sdk', 'repo-search', backendUrl, generationRef.current, body],\n      // `config.token` is read at fetch time: the provider serves the latest\n      // token through a getter, so rotations reach the request.\n      queryFn: ({ signal }) =>\n        fetchRepoSearch(backendUrl, { apiKey, token: config.token, getToken }, params, { signal }),\n      enabled: enabled && body.query.length > 0 && backendUrl.length > 0,\n      staleTime: 30_000,\n      placeholderData: keepPreviousData,\n      refetchOnWindowFocus: false,\n    },\n    contextClient ?? fallbackClient,\n  );\n}\n"],"names":["getAthenaApiBaseUrl","AthenaSdkError","sendWithCredentialRenewal","useAthenaConfig","useRef","credentialShape","sameCredentialShape","useContext","QueryClientContext","useState","QueryClient","useQuery","keepPreviousData"],"mappings":"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"}
+{"version":3,"file":"useAthenaRepoSearch.cjs","sources":["../../src/search/useAthenaRepoSearch.ts"],"sourcesContent":["/**\n * Code search over the workspace's indexed repositories —\n * `POST /api/search/repositories` (agora `web/api/search/repositories.py`),\n * the HTTP face of Clio's repository source for a Devin-style \"Ask\" surface\n * that searches the monorepo without an agent turn. Athena platform staff\n * only (the account-level `is_admin`, not a workspace role) on the managed\n * cloud today: a non-staff caller reads `403`, a private deployment `404`.\n */\nimport { keepPreviousData, useQuery, type UseQueryResult } from '@tanstack/react-query';\nimport { getAthenaApiBaseUrl } from '../collab/mint';\nimport { AthenaSdkError } from '../diagnostics/errors';\nimport { useAthenaQueryClient, useAthenaQueryIdentity } from '../lib/use-athena-rest-query';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport { sendWithCredentialRenewal } from '../runtime/credential-renewal';\nimport type { StatewireAuthSource } from '../runtime/statewire-auth-headers';\n\nexport type AthenaRepoSearchMode = 'hybrid' | 'lexical';\n\n/** One file range of one indexed repository, as the route serves it. */\nexport interface AthenaRepoSearchHit {\n  /** The GitHub catalog asset the repository is connected through. */\n  catalogAssetId: string;\n  /** `owner/repo`; `null` when the catalog names no repository. */\n  repoFullName: string | null;\n  /** Repo-relative, `/`-separated. */\n  path: string;\n  /** 1-based, inclusive. */\n  startLine: number;\n  endLine: number;\n  /** The enclosing declaration (`Class.method`) when the chunk's header named one. */\n  symbol: string | null;\n  /** Clio's language name for the file (`python`, `typescript`, …). */\n  language: string | null;\n  /** `code` (an AST chunk) or `window` (a Markdown heading window). */\n  unitType: string;\n  score: number;\n  /** The indexed commit the hit was read at. */\n  commitSha: string | null;\n  /** `{origin}/{owner}/{repo}/blob/{sha}/{path}#L{a}-L{b}`, GHES-aware. */\n  githubUrl: string | null;\n  /** The chunk's lines, header line removed, line breaks preserved. */\n  snippet: string;\n  /** `asset_<catalog>?anchor=file_line_range&…` — what `read_asset` and a citation take. */\n  readAssetReference: string;\n}\n\nexport interface AthenaRepoSearchResponse {\n  /** Best first, at most `limit`. */\n  hits: AthenaRepoSearchHit[];\n  tookMs: number;\n  mode: AthenaRepoSearchMode;\n}\n\nexport interface AthenaRepoSearchParams {\n  query: string;\n  /** 1–25; the route's default is 10. */\n  limit?: number;\n  /** `hybrid` (default) or `lexical`. */\n  mode?: AthenaRepoSearchMode;\n  /** Search these GitHub catalog assets only; empty means every indexed repository. */\n  repositoryAssetIds?: string[];\n  /** gitignore-style globs a hit's path must match (`agora/**\\/*.py`, `docs/`). */\n  paths?: string[];\n  /** Clio language names a hit's file must be indexed as. */\n  languages?: string[];\n}\n\nexport interface UseAthenaRepoSearchOptions extends AthenaRepoSearchParams {\n  /** `false` holds the query idle (a blank `query` does too). Default `true`. */\n  enabled?: boolean;\n}\n\n/** The route's JSON body — snake_case, unset filters omitted. */\nexport interface AthenaRepoSearchRequestBody {\n  query: string;\n  limit?: number;\n  mode?: AthenaRepoSearchMode;\n  repository_asset_ids?: string[];\n  paths?: string[];\n  languages?: string[];\n}\n\nexport const ATHENA_REPO_SEARCH_PATH = '/api/search/repositories';\n\nexport function repoSearchRequestBody(params: AthenaRepoSearchParams): AthenaRepoSearchRequestBody {\n  const body: AthenaRepoSearchRequestBody = { query: params.query.trim() };\n  if (params.limit !== undefined) body.limit = params.limit;\n  if (params.mode !== undefined) body.mode = params.mode;\n  if (params.repositoryAssetIds?.length) body.repository_asset_ids = params.repositoryAssetIds;\n  if (params.paths?.length) body.paths = params.paths;\n  if (params.languages?.length) body.languages = params.languages;\n  return body;\n}\n\n/** A `fetch` the caller cancelled (unmount, a newer query): lifecycle, not failure. */\nfunction isAbortError(error: unknown): boolean {\n  return (error instanceof DOMException || error instanceof Error) && error.name === 'AbortError';\n}\n\n/**\n * One search request. The credential rides `Authorization: Bearer` (a token,\n * resolved live through `getToken` when the host provided one) or\n * `X-API-KEY`; with neither, a same-origin host's session cookie rides\n * automatically, as the SDK's other REST helpers allow. A refused bearer\n * (`401`) gets one forced re-mint through `getToken` (`force: true`, the\n * statewire transport's `staleAuth` contract; `sendWithCredentialRenewal`) — a\n * getter that caches until forced would otherwise resend the same expired\n * token on every retry. Every failure is an `AthenaSdkError`, transport\n * rejections included; only an abort keeps its own identity.\n */\nexport async function fetchRepoSearch(\n  backendUrl: string,\n  auth: StatewireAuthSource,\n  params: AthenaRepoSearchParams,\n  opts: { signal?: AbortSignal } = {},\n): Promise<AthenaRepoSearchResponse> {\n  const url = `${getAthenaApiBaseUrl(backendUrl)}${ATHENA_REPO_SEARCH_PATH}`;\n  const body = JSON.stringify(repoSearchRequestBody(params));\n  const post = async (headers: Record<string, string>): Promise<Response> => {\n    try {\n      return await fetch(url, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json', ...headers },\n        body,\n        signal: opts.signal ?? null,\n      });\n    } catch (error) {\n      if (isAbortError(error)) throw error;\n      throw new AthenaSdkError({\n        code: 'repo_search_failed',\n        message: 'Repository search could not reach the Agora API.',\n        cause: error,\n        hint: 'Check the network and that backendUrl points at the Agora API base.',\n      });\n    }\n  };\n  const res = await sendWithCredentialRenewal(auth, post);\n  if (!res.ok) {\n    const refused = res.status === 401 || res.status === 403;\n    throw new AthenaSdkError({\n      code: refused ? 'auth_rejected' : 'repo_search_failed',\n      message: `Repository search failed: ${res.status}`,\n      status: res.status,\n      detail: await res.json().catch(() => undefined),\n      hint: refused\n        ? 'Repository search is limited to Athena platform staff on the managed cloud; check the credential.'\n        : res.status === 404\n          ? 'Repository search is not offered on this deployment (managed cloud only).'\n          : 'Check backendUrl points at the Agora API base and that Clio is available.',\n    });\n  }\n  return (await res.json()) as AthenaRepoSearchResponse;\n}\n\n/**\n * Search the indexed repositories through TanStack Query with the provider's\n * `backendUrl` and credentials. Keyed by the non-secret request, the signed-in\n * principal and a credential generation (a counter that advances when the\n * host's credentials change), never by the credential itself. Uses the host's `QueryClient` when\n * one is in context (`enableThreadList` mounts the SDK's own) and a\n * hook-scoped client otherwise, so it works under any `<AthenaProvider>`.\n */\nexport function useAthenaRepoSearch({\n  enabled = true,\n  ...params\n}: UseAthenaRepoSearchOptions): UseQueryResult<AthenaRepoSearchResponse, Error> {\n  const config = useAthenaConfig();\n  const { backendUrl, apiKey, getToken } = config;\n  const identity = useAthenaQueryIdentity({ apiKey, token: config.token, getToken });\n  const body = repoSearchRequestBody(params);\n  const queryClient = useAthenaQueryClient();\n  return useQuery(\n    {\n      queryKey: ['athena-sdk', 'repo-search', backendUrl, ...identity, body],\n      // `config.token` is read at fetch time: the provider serves the latest\n      // token through a getter, so rotations reach the request.\n      queryFn: ({ signal }) =>\n        fetchRepoSearch(backendUrl, { apiKey, token: config.token, getToken }, params, { signal }),\n      enabled: enabled && body.query.length > 0 && backendUrl.length > 0,\n      staleTime: 30_000,\n      placeholderData: keepPreviousData,\n      refetchOnWindowFocus: false,\n    },\n    queryClient,\n  );\n}\n"],"names":["getAthenaApiBaseUrl","AthenaSdkError","sendWithCredentialRenewal","useAthenaConfig","useAthenaQueryIdentity","useAthenaQueryClient","useQuery","keepPreviousData"],"mappings":";;;;;;;;AAkFO,MAAM,0BAA0B;AAEhC,SAAS,sBAAsB,QAA6D;;AACjG,QAAM,OAAoC,EAAE,OAAO,OAAO,MAAM,OAAK;AACrE,MAAI,OAAO,UAAU,OAAW,MAAK,QAAQ,OAAO;AACpD,MAAI,OAAO,SAAS,OAAW,MAAK,OAAO,OAAO;AAClD,OAAI,YAAO,uBAAP,mBAA2B,OAAQ,MAAK,uBAAuB,OAAO;AAC1E,OAAI,YAAO,UAAP,mBAAc,OAAQ,MAAK,QAAQ,OAAO;AAC9C,OAAI,YAAO,cAAP,mBAAkB,OAAQ,MAAK,YAAY,OAAO;AACtD,SAAO;AACT;AAGA,SAAS,aAAa,OAAyB;AAC7C,UAAQ,iBAAiB,gBAAgB,iBAAiB,UAAU,MAAM,SAAS;AACrF;AAaA,eAAsB,gBACpB,YACA,MACA,QACA,OAAiC,CAAA,GACE;AACnC,QAAM,MAAM,GAAGA,KAAAA,oBAAoB,UAAU,CAAC,GAAG,uBAAuB;AACxE,QAAM,OAAO,KAAK,UAAU,sBAAsB,MAAM,CAAC;AACzD,QAAM,OAAO,OAAO,YAAuD;AACzE,QAAI;AACF,aAAO,MAAM,MAAM,KAAK;AAAA,QACtB,QAAQ;AAAA,QACR,SAAS,EAAE,gBAAgB,oBAAoB,GAAG,QAAA;AAAA,QAClD;AAAA,QACA,QAAQ,KAAK,UAAU;AAAA,MAAA,CACxB;AAAA,IACH,SAAS,OAAO;AACd,UAAI,aAAa,KAAK,EAAG,OAAM;AAC/B,YAAM,IAAIC,OAAAA,eAAe;AAAA,QACvB,MAAM;AAAA,QACN,SAAS;AAAA,QACT,OAAO;AAAA,QACP,MAAM;AAAA,MAAA,CACP;AAAA,IACH;AAAA,EACF;AACA,QAAM,MAAM,MAAMC,4CAA0B,MAAM,IAAI;AACtD,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,UAAU,IAAI,WAAW,OAAO,IAAI,WAAW;AACrD,UAAM,IAAID,OAAAA,eAAe;AAAA,MACvB,MAAM,UAAU,kBAAkB;AAAA,MAClC,SAAS,6BAA6B,IAAI,MAAM;AAAA,MAChD,QAAQ,IAAI;AAAA,MACZ,QAAQ,MAAM,IAAI,OAAO,MAAM,MAAM,MAAS;AAAA,MAC9C,MAAM,UACF,sGACA,IAAI,WAAW,MACb,8EACA;AAAA,IAAA,CACP;AAAA,EACH;AACA,SAAQ,MAAM,IAAI,KAAA;AACpB;AAUO,SAAS,oBAAoB;AAAA,EAClC,UAAU;AAAA,EACV,GAAG;AACL,GAAgF;AAC9E,QAAM,SAASE,cAAAA,gBAAA;AACf,QAAM,EAAE,YAAY,QAAQ,SAAA,IAAa;AACzC,QAAM,WAAWC,mBAAAA,uBAAuB,EAAE,QAAQ,OAAO,OAAO,OAAO,UAAU;AACjF,QAAM,OAAO,sBAAsB,MAAM;AACzC,QAAM,cAAcC,mBAAAA,qBAAA;AACpB,SAAOC,WAAAA;AAAAA,IACL;AAAA,MACE,UAAU,CAAC,cAAc,eAAe,YAAY,GAAG,UAAU,IAAI;AAAA;AAAA;AAAA,MAGrE,SAAS,CAAC,EAAE,OAAA,MACV,gBAAgB,YAAY,EAAE,QAAQ,OAAO,OAAO,OAAO,SAAA,GAAY,QAAQ,EAAE,QAAQ;AAAA,MAC3F,SAAS,WAAW,KAAK,MAAM,SAAS,KAAK,WAAW,SAAS;AAAA,MACjE,WAAW;AAAA,MACX,iBAAiBC,WAAAA;AAAAA,MACjB,sBAAsB;AAAA,IAAA;AAAA,IAExB;AAAA,EAAA;AAEJ;;;;;"}

package/dist/search/useAthenaRepoSearch.d.ts

@@ -86,9 +86,9 @@ export declare function fetchRepoSearch(backendUrl: string, auth: StatewireAuthS
 }): Promise<AthenaRepoSearchResponse>;
 /**
  * Search the indexed repositories through TanStack Query with the provider's
- * `backendUrl` and credentials. Keyed by the non-secret request and a
- * credential generation (a counter that advances when the host's credentials
- * change), never by the credential itself. Uses the host's `QueryClient` when
+ * `backendUrl` and credentials. Keyed by the non-secret request, the signed-in
+ * principal and a credential generation (a counter that advances when the
+ * host's credentials change), never by the credential itself. Uses the host's `QueryClient` when
  * one is in context (`enableThreadList` mounts the SDK's own) and a
  * hook-scoped client otherwise, so it works under any `<AthenaProvider>`.
  */

package/dist/search/useAthenaRepoSearch.js

@@ -1,10 +1,9 @@
-import { QueryClientContext, QueryClient, useQuery, keepPreviousData } from "@tanstack/react-query";
-import { useRef, useContext, useState } from "react";
+import { useQuery, keepPreviousData } from "@tanstack/react-query";
 import { getAthenaApiBaseUrl } from "../collab/mint.js";
 import { AthenaSdkError } from "../diagnostics/errors.js";
+import { useAthenaQueryIdentity, useAthenaQueryClient } from "../lib/use-athena-rest-query.js";
 import { useAthenaConfig } from "../provider/AthenaContext.js";
 import { sendWithCredentialRenewal } from "../runtime/credential-renewal.js";
-import { credentialShape, sameCredentialShape } from "../threads/credential-shape.js";
 const ATHENA_REPO_SEARCH_PATH = "/api/search/repositories";
 function repoSearchRequestBody(params) {
   var _a, _b, _c;
@@ -59,19 +58,12 @@ function useAthenaRepoSearch({
 }) {
   const config = useAthenaConfig();
   const { backendUrl, apiKey, getToken } = config;
-  const credentialsRef = useRef(credentialShape({ apiKey, token: config.token, getToken }));
-  const generationRef = useRef(0);
-  const currentCredentials = credentialShape({ apiKey, token: config.token, getToken });
-  if (!sameCredentialShape(credentialsRef.current, currentCredentials)) {
-    credentialsRef.current = currentCredentials;
-    generationRef.current += 1;
-  }
+  const identity = useAthenaQueryIdentity({ apiKey, token: config.token, getToken });
   const body = repoSearchRequestBody(params);
-  const contextClient = useContext(QueryClientContext);
-  const [fallbackClient] = useState(() => contextClient ? void 0 : new QueryClient());
+  const queryClient = useAthenaQueryClient();
   return useQuery(
     {
-      queryKey: ["athena-sdk", "repo-search", backendUrl, generationRef.current, body],
+      queryKey: ["athena-sdk", "repo-search", backendUrl, ...identity, body],
       // `config.token` is read at fetch time: the provider serves the latest
       // token through a getter, so rotations reach the request.
       queryFn: ({ signal }) => fetchRepoSearch(backendUrl, { apiKey, token: config.token, getToken }, params, { signal }),
@@ -80,7 +72,7 @@ function useAthenaRepoSearch({
       placeholderData: keepPreviousData,
       refetchOnWindowFocus: false
     },
-    contextClient ?? fallbackClient
+    queryClient
   );
 }
 export {

package/dist/search/useAthenaRepoSearch.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAthenaRepoSearch.js","sources":["../../src/search/useAthenaRepoSearch.ts"],"sourcesContent":["/**\n * Code search over the workspace's indexed repositories —\n * `POST /api/search/repositories` (agora `web/api/search/repositories.py`),\n * the HTTP face of Clio's repository source for a Devin-style \"Ask\" surface\n * that searches the monorepo without an agent turn. Athena platform staff\n * only (the account-level `is_admin`, not a workspace role) on the managed\n * cloud today: a non-staff caller reads `403`, a private deployment `404`.\n */\nimport {\n  keepPreviousData,\n  QueryClient,\n  QueryClientContext,\n  useQuery,\n  type UseQueryResult,\n} from '@tanstack/react-query';\nimport { useContext, useRef, useState } from 'react';\nimport { getAthenaApiBaseUrl } from '../collab/mint';\nimport { AthenaSdkError } from '../diagnostics/errors';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport { sendWithCredentialRenewal } from '../runtime/credential-renewal';\nimport type { StatewireAuthSource } from '../runtime/statewire-auth-headers';\nimport { credentialShape, sameCredentialShape } from '../threads/credential-shape';\n\nexport type AthenaRepoSearchMode = 'hybrid' | 'lexical';\n\n/** One file range of one indexed repository, as the route serves it. */\nexport interface AthenaRepoSearchHit {\n  /** The GitHub catalog asset the repository is connected through. */\n  catalogAssetId: string;\n  /** `owner/repo`; `null` when the catalog names no repository. */\n  repoFullName: string | null;\n  /** Repo-relative, `/`-separated. */\n  path: string;\n  /** 1-based, inclusive. */\n  startLine: number;\n  endLine: number;\n  /** The enclosing declaration (`Class.method`) when the chunk's header named one. */\n  symbol: string | null;\n  /** Clio's language name for the file (`python`, `typescript`, …). */\n  language: string | null;\n  /** `code` (an AST chunk) or `window` (a Markdown heading window). */\n  unitType: string;\n  score: number;\n  /** The indexed commit the hit was read at. */\n  commitSha: string | null;\n  /** `{origin}/{owner}/{repo}/blob/{sha}/{path}#L{a}-L{b}`, GHES-aware. */\n  githubUrl: string | null;\n  /** The chunk's lines, header line removed, line breaks preserved. */\n  snippet: string;\n  /** `asset_<catalog>?anchor=file_line_range&…` — what `read_asset` and a citation take. */\n  readAssetReference: string;\n}\n\nexport interface AthenaRepoSearchResponse {\n  /** Best first, at most `limit`. */\n  hits: AthenaRepoSearchHit[];\n  tookMs: number;\n  mode: AthenaRepoSearchMode;\n}\n\nexport interface AthenaRepoSearchParams {\n  query: string;\n  /** 1–25; the route's default is 10. */\n  limit?: number;\n  /** `hybrid` (default) or `lexical`. */\n  mode?: AthenaRepoSearchMode;\n  /** Search these GitHub catalog assets only; empty means every indexed repository. */\n  repositoryAssetIds?: string[];\n  /** gitignore-style globs a hit's path must match (`agora/**\\/*.py`, `docs/`). */\n  paths?: string[];\n  /** Clio language names a hit's file must be indexed as. */\n  languages?: string[];\n}\n\nexport interface UseAthenaRepoSearchOptions extends AthenaRepoSearchParams {\n  /** `false` holds the query idle (a blank `query` does too). Default `true`. */\n  enabled?: boolean;\n}\n\n/** The route's JSON body — snake_case, unset filters omitted. */\nexport interface AthenaRepoSearchRequestBody {\n  query: string;\n  limit?: number;\n  mode?: AthenaRepoSearchMode;\n  repository_asset_ids?: string[];\n  paths?: string[];\n  languages?: string[];\n}\n\nexport const ATHENA_REPO_SEARCH_PATH = '/api/search/repositories';\n\nexport function repoSearchRequestBody(params: AthenaRepoSearchParams): AthenaRepoSearchRequestBody {\n  const body: AthenaRepoSearchRequestBody = { query: params.query.trim() };\n  if (params.limit !== undefined) body.limit = params.limit;\n  if (params.mode !== undefined) body.mode = params.mode;\n  if (params.repositoryAssetIds?.length) body.repository_asset_ids = params.repositoryAssetIds;\n  if (params.paths?.length) body.paths = params.paths;\n  if (params.languages?.length) body.languages = params.languages;\n  return body;\n}\n\n/** A `fetch` the caller cancelled (unmount, a newer query): lifecycle, not failure. */\nfunction isAbortError(error: unknown): boolean {\n  return (error instanceof DOMException || error instanceof Error) && error.name === 'AbortError';\n}\n\n/**\n * One search request. The credential rides `Authorization: Bearer` (a token,\n * resolved live through `getToken` when the host provided one) or\n * `X-API-KEY`; with neither, a same-origin host's session cookie rides\n * automatically, as the SDK's other REST helpers allow. A refused bearer\n * (`401`) gets one forced re-mint through `getToken` (`force: true`, the\n * statewire transport's `staleAuth` contract; `sendWithCredentialRenewal`) — a\n * getter that caches until forced would otherwise resend the same expired\n * token on every retry. Every failure is an `AthenaSdkError`, transport\n * rejections included; only an abort keeps its own identity.\n */\nexport async function fetchRepoSearch(\n  backendUrl: string,\n  auth: StatewireAuthSource,\n  params: AthenaRepoSearchParams,\n  opts: { signal?: AbortSignal } = {},\n): Promise<AthenaRepoSearchResponse> {\n  const url = `${getAthenaApiBaseUrl(backendUrl)}${ATHENA_REPO_SEARCH_PATH}`;\n  const body = JSON.stringify(repoSearchRequestBody(params));\n  const post = async (headers: Record<string, string>): Promise<Response> => {\n    try {\n      return await fetch(url, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json', ...headers },\n        body,\n        signal: opts.signal ?? null,\n      });\n    } catch (error) {\n      if (isAbortError(error)) throw error;\n      throw new AthenaSdkError({\n        code: 'repo_search_failed',\n        message: 'Repository search could not reach the Agora API.',\n        cause: error,\n        hint: 'Check the network and that backendUrl points at the Agora API base.',\n      });\n    }\n  };\n  const res = await sendWithCredentialRenewal(auth, post);\n  if (!res.ok) {\n    const refused = res.status === 401 || res.status === 403;\n    throw new AthenaSdkError({\n      code: refused ? 'auth_rejected' : 'repo_search_failed',\n      message: `Repository search failed: ${res.status}`,\n      status: res.status,\n      detail: await res.json().catch(() => undefined),\n      hint: refused\n        ? 'Repository search is limited to Athena platform staff on the managed cloud; check the credential.'\n        : res.status === 404\n          ? 'Repository search is not offered on this deployment (managed cloud only).'\n          : 'Check backendUrl points at the Agora API base and that Clio is available.',\n    });\n  }\n  return (await res.json()) as AthenaRepoSearchResponse;\n}\n\n/**\n * Search the indexed repositories through TanStack Query with the provider's\n * `backendUrl` and credentials. Keyed by the non-secret request and a\n * credential generation (a counter that advances when the host's credentials\n * change), never by the credential itself. Uses the host's `QueryClient` when\n * one is in context (`enableThreadList` mounts the SDK's own) and a\n * hook-scoped client otherwise, so it works under any `<AthenaProvider>`.\n */\nexport function useAthenaRepoSearch({\n  enabled = true,\n  ...params\n}: UseAthenaRepoSearchOptions): UseQueryResult<AthenaRepoSearchResponse, Error> {\n  const config = useAthenaConfig();\n  const { backendUrl, apiKey, getToken } = config;\n  const credentialsRef = useRef(credentialShape({ apiKey, token: config.token, getToken }));\n  const generationRef = useRef(0);\n  const currentCredentials = credentialShape({ apiKey, token: config.token, getToken });\n  if (!sameCredentialShape(credentialsRef.current, currentCredentials)) {\n    credentialsRef.current = currentCredentials;\n    generationRef.current += 1;\n  }\n  const body = repoSearchRequestBody(params);\n  const contextClient = useContext(QueryClientContext);\n  const [fallbackClient] = useState(() => (contextClient ? undefined : new QueryClient()));\n  return useQuery(\n    {\n      queryKey: ['athena-sdk', 'repo-search', backendUrl, generationRef.current, body],\n      // `config.token` is read at fetch time: the provider serves the latest\n      // token through a getter, so rotations reach the request.\n      queryFn: ({ signal }) =>\n        fetchRepoSearch(backendUrl, { apiKey, token: config.token, getToken }, params, { signal }),\n      enabled: enabled && body.query.length > 0 && backendUrl.length > 0,\n      staleTime: 30_000,\n      placeholderData: keepPreviousData,\n      refetchOnWindowFocus: false,\n    },\n    contextClient ?? fallbackClient,\n  );\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"useAthenaRepoSearch.js","sources":["../../src/search/useAthenaRepoSearch.ts"],"sourcesContent":["/**\n * Code search over the workspace's indexed repositories —\n * `POST /api/search/repositories` (agora `web/api/search/repositories.py`),\n * the HTTP face of Clio's repository source for a Devin-style \"Ask\" surface\n * that searches the monorepo without an agent turn. Athena platform staff\n * only (the account-level `is_admin`, not a workspace role) on the managed\n * cloud today: a non-staff caller reads `403`, a private deployment `404`.\n */\nimport { keepPreviousData, useQuery, type UseQueryResult } from '@tanstack/react-query';\nimport { getAthenaApiBaseUrl } from '../collab/mint';\nimport { AthenaSdkError } from '../diagnostics/errors';\nimport { useAthenaQueryClient, useAthenaQueryIdentity } from '../lib/use-athena-rest-query';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport { sendWithCredentialRenewal } from '../runtime/credential-renewal';\nimport type { StatewireAuthSource } from '../runtime/statewire-auth-headers';\n\nexport type AthenaRepoSearchMode = 'hybrid' | 'lexical';\n\n/** One file range of one indexed repository, as the route serves it. */\nexport interface AthenaRepoSearchHit {\n  /** The GitHub catalog asset the repository is connected through. */\n  catalogAssetId: string;\n  /** `owner/repo`; `null` when the catalog names no repository. */\n  repoFullName: string | null;\n  /** Repo-relative, `/`-separated. */\n  path: string;\n  /** 1-based, inclusive. */\n  startLine: number;\n  endLine: number;\n  /** The enclosing declaration (`Class.method`) when the chunk's header named one. */\n  symbol: string | null;\n  /** Clio's language name for the file (`python`, `typescript`, …). */\n  language: string | null;\n  /** `code` (an AST chunk) or `window` (a Markdown heading window). */\n  unitType: string;\n  score: number;\n  /** The indexed commit the hit was read at. */\n  commitSha: string | null;\n  /** `{origin}/{owner}/{repo}/blob/{sha}/{path}#L{a}-L{b}`, GHES-aware. */\n  githubUrl: string | null;\n  /** The chunk's lines, header line removed, line breaks preserved. */\n  snippet: string;\n  /** `asset_<catalog>?anchor=file_line_range&…` — what `read_asset` and a citation take. */\n  readAssetReference: string;\n}\n\nexport interface AthenaRepoSearchResponse {\n  /** Best first, at most `limit`. */\n  hits: AthenaRepoSearchHit[];\n  tookMs: number;\n  mode: AthenaRepoSearchMode;\n}\n\nexport interface AthenaRepoSearchParams {\n  query: string;\n  /** 1–25; the route's default is 10. */\n  limit?: number;\n  /** `hybrid` (default) or `lexical`. */\n  mode?: AthenaRepoSearchMode;\n  /** Search these GitHub catalog assets only; empty means every indexed repository. */\n  repositoryAssetIds?: string[];\n  /** gitignore-style globs a hit's path must match (`agora/**\\/*.py`, `docs/`). */\n  paths?: string[];\n  /** Clio language names a hit's file must be indexed as. */\n  languages?: string[];\n}\n\nexport interface UseAthenaRepoSearchOptions extends AthenaRepoSearchParams {\n  /** `false` holds the query idle (a blank `query` does too). Default `true`. */\n  enabled?: boolean;\n}\n\n/** The route's JSON body — snake_case, unset filters omitted. */\nexport interface AthenaRepoSearchRequestBody {\n  query: string;\n  limit?: number;\n  mode?: AthenaRepoSearchMode;\n  repository_asset_ids?: string[];\n  paths?: string[];\n  languages?: string[];\n}\n\nexport const ATHENA_REPO_SEARCH_PATH = '/api/search/repositories';\n\nexport function repoSearchRequestBody(params: AthenaRepoSearchParams): AthenaRepoSearchRequestBody {\n  const body: AthenaRepoSearchRequestBody = { query: params.query.trim() };\n  if (params.limit !== undefined) body.limit = params.limit;\n  if (params.mode !== undefined) body.mode = params.mode;\n  if (params.repositoryAssetIds?.length) body.repository_asset_ids = params.repositoryAssetIds;\n  if (params.paths?.length) body.paths = params.paths;\n  if (params.languages?.length) body.languages = params.languages;\n  return body;\n}\n\n/** A `fetch` the caller cancelled (unmount, a newer query): lifecycle, not failure. */\nfunction isAbortError(error: unknown): boolean {\n  return (error instanceof DOMException || error instanceof Error) && error.name === 'AbortError';\n}\n\n/**\n * One search request. The credential rides `Authorization: Bearer` (a token,\n * resolved live through `getToken` when the host provided one) or\n * `X-API-KEY`; with neither, a same-origin host's session cookie rides\n * automatically, as the SDK's other REST helpers allow. A refused bearer\n * (`401`) gets one forced re-mint through `getToken` (`force: true`, the\n * statewire transport's `staleAuth` contract; `sendWithCredentialRenewal`) — a\n * getter that caches until forced would otherwise resend the same expired\n * token on every retry. Every failure is an `AthenaSdkError`, transport\n * rejections included; only an abort keeps its own identity.\n */\nexport async function fetchRepoSearch(\n  backendUrl: string,\n  auth: StatewireAuthSource,\n  params: AthenaRepoSearchParams,\n  opts: { signal?: AbortSignal } = {},\n): Promise<AthenaRepoSearchResponse> {\n  const url = `${getAthenaApiBaseUrl(backendUrl)}${ATHENA_REPO_SEARCH_PATH}`;\n  const body = JSON.stringify(repoSearchRequestBody(params));\n  const post = async (headers: Record<string, string>): Promise<Response> => {\n    try {\n      return await fetch(url, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json', ...headers },\n        body,\n        signal: opts.signal ?? null,\n      });\n    } catch (error) {\n      if (isAbortError(error)) throw error;\n      throw new AthenaSdkError({\n        code: 'repo_search_failed',\n        message: 'Repository search could not reach the Agora API.',\n        cause: error,\n        hint: 'Check the network and that backendUrl points at the Agora API base.',\n      });\n    }\n  };\n  const res = await sendWithCredentialRenewal(auth, post);\n  if (!res.ok) {\n    const refused = res.status === 401 || res.status === 403;\n    throw new AthenaSdkError({\n      code: refused ? 'auth_rejected' : 'repo_search_failed',\n      message: `Repository search failed: ${res.status}`,\n      status: res.status,\n      detail: await res.json().catch(() => undefined),\n      hint: refused\n        ? 'Repository search is limited to Athena platform staff on the managed cloud; check the credential.'\n        : res.status === 404\n          ? 'Repository search is not offered on this deployment (managed cloud only).'\n          : 'Check backendUrl points at the Agora API base and that Clio is available.',\n    });\n  }\n  return (await res.json()) as AthenaRepoSearchResponse;\n}\n\n/**\n * Search the indexed repositories through TanStack Query with the provider's\n * `backendUrl` and credentials. Keyed by the non-secret request, the signed-in\n * principal and a credential generation (a counter that advances when the\n * host's credentials change), never by the credential itself. Uses the host's `QueryClient` when\n * one is in context (`enableThreadList` mounts the SDK's own) and a\n * hook-scoped client otherwise, so it works under any `<AthenaProvider>`.\n */\nexport function useAthenaRepoSearch({\n  enabled = true,\n  ...params\n}: UseAthenaRepoSearchOptions): UseQueryResult<AthenaRepoSearchResponse, Error> {\n  const config = useAthenaConfig();\n  const { backendUrl, apiKey, getToken } = config;\n  const identity = useAthenaQueryIdentity({ apiKey, token: config.token, getToken });\n  const body = repoSearchRequestBody(params);\n  const queryClient = useAthenaQueryClient();\n  return useQuery(\n    {\n      queryKey: ['athena-sdk', 'repo-search', backendUrl, ...identity, body],\n      // `config.token` is read at fetch time: the provider serves the latest\n      // token through a getter, so rotations reach the request.\n      queryFn: ({ signal }) =>\n        fetchRepoSearch(backendUrl, { apiKey, token: config.token, getToken }, params, { signal }),\n      enabled: enabled && body.query.length > 0 && backendUrl.length > 0,\n      staleTime: 30_000,\n      placeholderData: keepPreviousData,\n      refetchOnWindowFocus: false,\n    },\n    queryClient,\n  );\n}\n"],"names":[],"mappings":";;;;;;AAkFO,MAAM,0BAA0B;AAEhC,SAAS,sBAAsB,QAA6D;;AACjG,QAAM,OAAoC,EAAE,OAAO,OAAO,MAAM,OAAK;AACrE,MAAI,OAAO,UAAU,OAAW,MAAK,QAAQ,OAAO;AACpD,MAAI,OAAO,SAAS,OAAW,MAAK,OAAO,OAAO;AAClD,OAAI,YAAO,uBAAP,mBAA2B,OAAQ,MAAK,uBAAuB,OAAO;AAC1E,OAAI,YAAO,UAAP,mBAAc,OAAQ,MAAK,QAAQ,OAAO;AAC9C,OAAI,YAAO,cAAP,mBAAkB,OAAQ,MAAK,YAAY,OAAO;AACtD,SAAO;AACT;AAGA,SAAS,aAAa,OAAyB;AAC7C,UAAQ,iBAAiB,gBAAgB,iBAAiB,UAAU,MAAM,SAAS;AACrF;AAaA,eAAsB,gBACpB,YACA,MACA,QACA,OAAiC,CAAA,GACE;AACnC,QAAM,MAAM,GAAG,oBAAoB,UAAU,CAAC,GAAG,uBAAuB;AACxE,QAAM,OAAO,KAAK,UAAU,sBAAsB,MAAM,CAAC;AACzD,QAAM,OAAO,OAAO,YAAuD;AACzE,QAAI;AACF,aAAO,MAAM,MAAM,KAAK;AAAA,QACtB,QAAQ;AAAA,QACR,SAAS,EAAE,gBAAgB,oBAAoB,GAAG,QAAA;AAAA,QAClD;AAAA,QACA,QAAQ,KAAK,UAAU;AAAA,MAAA,CACxB;AAAA,IACH,SAAS,OAAO;AACd,UAAI,aAAa,KAAK,EAAG,OAAM;AAC/B,YAAM,IAAI,eAAe;AAAA,QACvB,MAAM;AAAA,QACN,SAAS;AAAA,QACT,OAAO;AAAA,QACP,MAAM;AAAA,MAAA,CACP;AAAA,IACH;AAAA,EACF;AACA,QAAM,MAAM,MAAM,0BAA0B,MAAM,IAAI;AACtD,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,UAAU,IAAI,WAAW,OAAO,IAAI,WAAW;AACrD,UAAM,IAAI,eAAe;AAAA,MACvB,MAAM,UAAU,kBAAkB;AAAA,MAClC,SAAS,6BAA6B,IAAI,MAAM;AAAA,MAChD,QAAQ,IAAI;AAAA,MACZ,QAAQ,MAAM,IAAI,OAAO,MAAM,MAAM,MAAS;AAAA,MAC9C,MAAM,UACF,sGACA,IAAI,WAAW,MACb,8EACA;AAAA,IAAA,CACP;AAAA,EACH;AACA,SAAQ,MAAM,IAAI,KAAA;AACpB;AAUO,SAAS,oBAAoB;AAAA,EAClC,UAAU;AAAA,EACV,GAAG;AACL,GAAgF;AAC9E,QAAM,SAAS,gBAAA;AACf,QAAM,EAAE,YAAY,QAAQ,SAAA,IAAa;AACzC,QAAM,WAAW,uBAAuB,EAAE,QAAQ,OAAO,OAAO,OAAO,UAAU;AACjF,QAAM,OAAO,sBAAsB,MAAM;AACzC,QAAM,cAAc,qBAAA;AACpB,SAAO;AAAA,IACL;AAAA,MACE,UAAU,CAAC,cAAc,eAAe,YAAY,GAAG,UAAU,IAAI;AAAA;AAAA;AAAA,MAGrE,SAAS,CAAC,EAAE,OAAA,MACV,gBAAgB,YAAY,EAAE,QAAQ,OAAO,OAAO,OAAO,SAAA,GAAY,QAAQ,EAAE,QAAQ;AAAA,MAC3F,SAAS,WAAW,KAAK,MAAM,SAAS,KAAK,WAAW,SAAS;AAAA,MACjE,WAAW;AAAA,MACX,iBAAiB;AAAA,MACjB,sBAAsB;AAAA,IAAA;AAAA,IAExB;AAAA,EAAA;AAEJ;"}

package/dist/sheet-range/a1.cjs

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const SHEET_MAX_ROW = 1048576;
+const SHEET_MAX_COLUMN = 16384;
+const CELL_REFERENCE = /^\$?([A-Za-z]{1,3})\$?(\d{1,7})$/;
+const COLUMN_REFERENCE = /^\$?([A-Za-z]{1,3})$/;
+const ROW_REFERENCE = /^\$?(\d{1,7})$/;
+function columnLettersToNumber(letters) {
+  if (!/^[A-Za-z]{1,3}$/.test(letters)) return null;
+  let column = 0;
+  for (const letter of letters.toUpperCase()) column = column * 26 + (letter.charCodeAt(0) - 64);
+  return column <= SHEET_MAX_COLUMN ? column : null;
+}
+function columnNumberToLetters(column) {
+  if (!Number.isInteger(column) || column < 1) return "";
+  let letters = "";
+  for (let rest = column; rest > 0; rest = Math.floor((rest - 1) / 26)) {
+    letters = String.fromCharCode(65 + (rest - 1) % 26) + letters;
+  }
+  return letters;
+}
+function formatA1Cell({ row, column }) {
+  return `${columnNumberToLetters(column)}${row}`;
+}
+function formatA1Range({ startRow, endRow, startColumn, endColumn }) {
+  const start = formatA1Cell({ row: startRow, column: startColumn });
+  if (startRow === endRow && startColumn === endColumn) return start;
+  return `${start}:${formatA1Cell({ row: endRow, column: endColumn })}`;
+}
+function splitSheetPrefix(reference) {
+  if (reference.startsWith("'")) {
+    let name2 = "";
+    let index = 1;
+    while (index < reference.length) {
+      const char = reference[index];
+      if (char === "'") {
+        if (reference[index + 1] !== "'") break;
+        name2 += "'";
+        index += 2;
+        continue;
+      }
+      name2 += char;
+      index += 1;
+    }
+    if (name2 === "" || reference[index] !== "'" || reference[index + 1] !== "!") return null;
+    return { sheetName: name2, address: reference.slice(index + 2) };
+  }
+  const bang = reference.indexOf("!");
+  if (bang === -1) return { sheetName: null, address: reference };
+  const name = reference.slice(0, bang);
+  if (name === "" || name.includes("'")) return null;
+  return { sheetName: name, address: reference.slice(bang + 1) };
+}
+function parseRow(digits) {
+  const row = Number(digits);
+  return Number.isInteger(row) && row >= 1 && row <= SHEET_MAX_ROW ? row : null;
+}
+function parseCell(part) {
+  const match = CELL_REFERENCE.exec(part);
+  if (!match) return null;
+  const column = columnLettersToNumber(match[1]);
+  const row = parseRow(match[2]);
+  return column === null || row === null ? null : { row, column };
+}
+function parseColumn(part) {
+  const match = COLUMN_REFERENCE.exec(part);
+  return match ? columnLettersToNumber(match[1]) : null;
+}
+function parseWholeRow(part) {
+  const match = ROW_REFERENCE.exec(part);
+  return match ? parseRow(match[1]) : null;
+}
+function parseA1Range(reference) {
+  if (typeof reference !== "string") return null;
+  const qualified = splitSheetPrefix(reference.trim());
+  if (!qualified) return null;
+  const { sheetName } = qualified;
+  const parts = qualified.address.split(":").map((part) => part.trim());
+  if (parts.length > 2 || parts.some((part) => part === "")) return null;
+  if (parts.length === 1) {
+    const cell = parseCell(parts[0]);
+    if (!cell) return null;
+    return {
+      kind: "cell",
+      sheetName,
+      startRow: cell.row,
+      endRow: cell.row,
+      startColumn: cell.column,
+      endColumn: cell.column
+    };
+  }
+  const [first, second] = parts;
+  const startCell = parseCell(first);
+  const endCell = parseCell(second);
+  if (startCell && endCell) {
+    return {
+      kind: "range",
+      sheetName,
+      startRow: Math.min(startCell.row, endCell.row),
+      endRow: Math.max(startCell.row, endCell.row),
+      startColumn: Math.min(startCell.column, endCell.column),
+      endColumn: Math.max(startCell.column, endCell.column)
+    };
+  }
+  const startColumn = parseColumn(first);
+  const endColumn = parseColumn(second);
+  if (startColumn !== null && endColumn !== null) {
+    return {
+      kind: "columns",
+      sheetName,
+      startRow: null,
+      endRow: null,
+      startColumn: Math.min(startColumn, endColumn),
+      endColumn: Math.max(startColumn, endColumn)
+    };
+  }
+  const startRow = parseWholeRow(first);
+  const endRow = parseWholeRow(second);
+  if (startRow !== null && endRow !== null) {
+    return {
+      kind: "rows",
+      sheetName,
+      startRow: Math.min(startRow, endRow),
+      endRow: Math.max(startRow, endRow),
+      startColumn: null,
+      endColumn: null
+    };
+  }
+  return null;
+}
+function a1AnchorCell(reference) {
+  if (typeof reference !== "string" || !parseA1Range(reference)) return null;
+  const qualified = splitSheetPrefix(reference.trim());
+  const first = (qualified == null ? void 0 : qualified.address.split(":")[0].trim()) ?? "";
+  const cell = parseCell(first);
+  if (cell) return cell;
+  const column = parseColumn(first);
+  if (column !== null) return { row: 1, column };
+  const row = parseWholeRow(first);
+  return row === null ? null : { row, column: 1 };
+}
+function a1RangeBounds(reference) {
+  const range = parseA1Range(reference);
+  if (!range || range.kind !== "cell" && range.kind !== "range") return null;
+  return {
+    startRow: range.startRow,
+    endRow: range.endRow,
+    startColumn: range.startColumn,
+    endColumn: range.endColumn
+  };
+}
+exports.SHEET_MAX_COLUMN = SHEET_MAX_COLUMN;
+exports.SHEET_MAX_ROW = SHEET_MAX_ROW;
+exports.a1AnchorCell = a1AnchorCell;
+exports.a1RangeBounds = a1RangeBounds;
+exports.columnLettersToNumber = columnLettersToNumber;
+exports.columnNumberToLetters = columnNumberToLetters;
+exports.formatA1Cell = formatA1Cell;
+exports.formatA1Range = formatA1Range;
+exports.parseA1Range = parseA1Range;
+exports.splitSheetPrefix = splitSheetPrefix;
+//# sourceMappingURL=a1.cjs.map

package/dist/sheet-range/a1.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"a1.cjs","sources":["../../src/sheet-range/a1.ts"],"sourcesContent":["/**\n * A1 references, read and written the way every spreadsheet surface outside\n * the grid reads them: the SDK's sheet tool cards, and Olympus's sheet tool\n * cards, citation previews and citation navigation. Pure: no React, no engine.\n *\n * Rows and columns are 1-based, as the sheets engine counts them: `A1` is row\n * 1, column 1.\n */\n\n/** The last row a sheet addresses (Excel and the sheets engine). */\nexport const SHEET_MAX_ROW = 1_048_576;\n/** The last column a sheet addresses: XFD. */\nexport const SHEET_MAX_COLUMN = 16_384;\n\n/** A rectangle of cells, 1-based and inclusive on both ends. */\nexport interface SheetRangeBounds {\n  startRow: number;\n  endRow: number;\n  startColumn: number;\n  endColumn: number;\n}\n\ninterface SheetQualifier {\n  /** The sheet a `Sales!` or `'Q1 Plan'!` prefix names (quotes removed, `''` read as `'`); null without one. */\n  sheetName: string | null;\n}\n\n/**\n * A parsed A1 reference. A cell or a rectangle carries all four bounds\n * (normalized so start ≤ end, as `C5:A1` means `A1:C5`); whole columns (`A:C`)\n * leave the rows open and whole rows (`3:5`) the columns.\n */\nexport type A1Range =\n  | (SheetQualifier & SheetRangeBounds & { kind: 'cell' | 'range' })\n  | (SheetQualifier & {\n      kind: 'columns';\n      startRow: null;\n      endRow: null;\n      startColumn: number;\n      endColumn: number;\n    })\n  | (SheetQualifier & {\n      kind: 'rows';\n      startRow: number;\n      endRow: number;\n      startColumn: null;\n      endColumn: null;\n    });\n\n/** A cell (`B7`, `$B$7`); the column is 1–3 letters, the row 1–7 digits. */\nconst CELL_REFERENCE = /^\\$?([A-Za-z]{1,3})\\$?(\\d{1,7})$/;\n/** One side of whole columns (`A`, `$A`). */\nconst COLUMN_REFERENCE = /^\\$?([A-Za-z]{1,3})$/;\n/** One side of whole rows (`3`, `$3`). */\nconst ROW_REFERENCE = /^\\$?(\\d{1,7})$/;\n\n/** Column letters to the 1-based column (`A` → 1, `AA` → 27); null past XFD or for anything but letters. */\nexport function columnLettersToNumber(letters: string): number | null {\n  if (!/^[A-Za-z]{1,3}$/.test(letters)) return null;\n  let column = 0;\n  for (const letter of letters.toUpperCase()) column = column * 26 + (letter.charCodeAt(0) - 64);\n  return column <= SHEET_MAX_COLUMN ? column : null;\n}\n\n/** A 1-based column to its letters (1 → `A`, 27 → `AA`); empty for anything below 1 or fractional. */\nexport function columnNumberToLetters(column: number): string {\n  if (!Number.isInteger(column) || column < 1) return '';\n  let letters = '';\n  for (let rest = column; rest > 0; rest = Math.floor((rest - 1) / 26)) {\n    letters = String.fromCharCode(65 + ((rest - 1) % 26)) + letters;\n  }\n  return letters;\n}\n\n/** A cell's A1 address: `{ row: 7, column: 2 }` → `B7`. */\nexport function formatA1Cell({ row, column }: { row: number; column: number }): string {\n  return `${columnNumberToLetters(column)}${row}`;\n}\n\n/** A rectangle's A1 address: `A1:C5`, or `A1` alone when it is one cell. */\nexport function formatA1Range({ startRow, endRow, startColumn, endColumn }: SheetRangeBounds): string {\n  const start = formatA1Cell({ row: startRow, column: startColumn });\n  if (startRow === endRow && startColumn === endColumn) return start;\n  return `${start}:${formatA1Cell({ row: endRow, column: endColumn })}`;\n}\n\n/**\n * Split the sheet prefix off a reference: `'Q1 Plan'!A1:B2` → `Q1 Plan` and\n * `A1:B2`, `Sales!B7` → `Sales` and `B7`, `B7` → no sheet and `B7`. A quoted\n * name runs to the first quote that is not doubled (`'Bob''s'!A1` names\n * `Bob's`); an unquoted one runs to the first `!` and holds no quote. Null for\n * a prefix that is not one (an empty name, an unclosed quote, a quote without\n * its `!`).\n */\nexport function splitSheetPrefix(reference: string): { sheetName: string | null; address: string } | null {\n  if (reference.startsWith(\"'\")) {\n    let name = '';\n    let index = 1;\n    while (index < reference.length) {\n      const char = reference[index];\n      if (char === \"'\") {\n        if (reference[index + 1] !== \"'\") break;\n        name += \"'\";\n        index += 2;\n        continue;\n      }\n      name += char;\n      index += 1;\n    }\n    if (name === '' || reference[index] !== \"'\" || reference[index + 1] !== '!') return null;\n    return { sheetName: name, address: reference.slice(index + 2) };\n  }\n  const bang = reference.indexOf('!');\n  if (bang === -1) return { sheetName: null, address: reference };\n  const name = reference.slice(0, bang);\n  if (name === '' || name.includes(\"'\")) return null;\n  return { sheetName: name, address: reference.slice(bang + 1) };\n}\n\nfunction parseRow(digits: string): number | null {\n  const row = Number(digits);\n  return Number.isInteger(row) && row >= 1 && row <= SHEET_MAX_ROW ? row : null;\n}\n\nfunction parseCell(part: string): { row: number; column: number } | null {\n  const match = CELL_REFERENCE.exec(part);\n  if (!match) return null;\n  const column = columnLettersToNumber(match[1]);\n  const row = parseRow(match[2]);\n  return column === null || row === null ? null : { row, column };\n}\n\nfunction parseColumn(part: string): number | null {\n  const match = COLUMN_REFERENCE.exec(part);\n  return match ? columnLettersToNumber(match[1]) : null;\n}\n\nfunction parseWholeRow(part: string): number | null {\n  const match = ROW_REFERENCE.exec(part);\n  return match ? parseRow(match[1]) : null;\n}\n\n/**\n * Read an A1 reference: a cell (`B7`), a rectangle (`A1:C5`), whole columns\n * (`A:C`) or whole rows (`3:5`), with an optional sheet prefix (`Sales!`,\n * `'Q1 Plan'!`), `$` absolute markers and any letter case. Whitespace around\n * the reference and around its `:` is ignored. Null for anything else: a named\n * range, a column past XFD, row 0 or a row past 1,048,576, a lone column or\n * row, mixed sides (`A1:C`), three parts.\n */\nexport function parseA1Range(reference: string | null | undefined): A1Range | null {\n  if (typeof reference !== 'string') return null;\n  const qualified = splitSheetPrefix(reference.trim());\n  if (!qualified) return null;\n  const { sheetName } = qualified;\n  const parts = qualified.address.split(':').map((part) => part.trim());\n  if (parts.length > 2 || parts.some((part) => part === '')) return null;\n\n  if (parts.length === 1) {\n    const cell = parseCell(parts[0]);\n    if (!cell) return null;\n    return {\n      kind: 'cell',\n      sheetName,\n      startRow: cell.row,\n      endRow: cell.row,\n      startColumn: cell.column,\n      endColumn: cell.column,\n    };\n  }\n\n  const [first, second] = parts;\n  const startCell = parseCell(first);\n  const endCell = parseCell(second);\n  if (startCell && endCell) {\n    return {\n      kind: 'range',\n      sheetName,\n      startRow: Math.min(startCell.row, endCell.row),\n      endRow: Math.max(startCell.row, endCell.row),\n      startColumn: Math.min(startCell.column, endCell.column),\n      endColumn: Math.max(startCell.column, endCell.column),\n    };\n  }\n  const startColumn = parseColumn(first);\n  const endColumn = parseColumn(second);\n  if (startColumn !== null && endColumn !== null) {\n    return {\n      kind: 'columns',\n      sheetName,\n      startRow: null,\n      endRow: null,\n      startColumn: Math.min(startColumn, endColumn),\n      endColumn: Math.max(startColumn, endColumn),\n    };\n  }\n  const startRow = parseWholeRow(first);\n  const endRow = parseWholeRow(second);\n  if (startRow !== null && endRow !== null) {\n    return {\n      kind: 'rows',\n      sheetName,\n      startRow: Math.min(startRow, endRow),\n      endRow: Math.max(startRow, endRow),\n      startColumn: null,\n      endColumn: null,\n    };\n  }\n  return null;\n}\n\n/**\n * The cell a reference starts from as written, its first part: `D6` for\n * `D6:C5`, row 1 of column C for `C:A`, column A of row 5 for `5:3`. A write\n * anchored at a range starts there; the backend does not reorder a range\n * written backwards. Null for anything `parseA1Range` cannot read.\n */\nexport function a1AnchorCell(reference: string | null | undefined): { row: number; column: number } | null {\n  if (typeof reference !== 'string' || !parseA1Range(reference)) return null;\n  const qualified = splitSheetPrefix(reference.trim());\n  const first = qualified?.address.split(':')[0].trim() ?? '';\n  const cell = parseCell(first);\n  if (cell) return cell;\n  const column = parseColumn(first);\n  if (column !== null) return { row: 1, column };\n  const row = parseWholeRow(first);\n  return row === null ? null : { row, column: 1 };\n}\n\n/**\n * The rectangle a cell or rectangle reference covers. Null for whole columns\n * or rows, whose extent is open, and for anything `parseA1Range` cannot read.\n */\nexport function a1RangeBounds(reference: string | null | undefined): SheetRangeBounds | null {\n  const range = parseA1Range(reference);\n  if (!range || (range.kind !== 'cell' && range.kind !== 'range')) return null;\n  return {\n    startRow: range.startRow,\n    endRow: range.endRow,\n    startColumn: range.startColumn,\n    endColumn: range.endColumn,\n  };\n}\n"],"names":["name"],"mappings":"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"}

package/dist/sheet-range/a1.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A1 references, read and written the way every spreadsheet surface outside
+ * the grid reads them: the SDK's sheet tool cards, and Olympus's sheet tool
+ * cards, citation previews and citation navigation. Pure: no React, no engine.
+ *
+ * Rows and columns are 1-based, as the sheets engine counts them: `A1` is row
+ * 1, column 1.
+ */
+/** The last row a sheet addresses (Excel and the sheets engine). */
+export declare const SHEET_MAX_ROW = 1048576;
+/** The last column a sheet addresses: XFD. */
+export declare const SHEET_MAX_COLUMN = 16384;
+/** A rectangle of cells, 1-based and inclusive on both ends. */
+export interface SheetRangeBounds {
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+}
+interface SheetQualifier {
+    /** The sheet a `Sales!` or `'Q1 Plan'!` prefix names (quotes removed, `''` read as `'`); null without one. */
+    sheetName: string | null;
+}
+/**
+ * A parsed A1 reference. A cell or a rectangle carries all four bounds
+ * (normalized so start ≤ end, as `C5:A1` means `A1:C5`); whole columns (`A:C`)
+ * leave the rows open and whole rows (`3:5`) the columns.
+ */
+export type A1Range = (SheetQualifier & SheetRangeBounds & {
+    kind: 'cell' | 'range';
+}) | (SheetQualifier & {
+    kind: 'columns';
+    startRow: null;
+    endRow: null;
+    startColumn: number;
+    endColumn: number;
+}) | (SheetQualifier & {
+    kind: 'rows';
+    startRow: number;
+    endRow: number;
+    startColumn: null;
+    endColumn: null;
+});
+/** Column letters to the 1-based column (`A` → 1, `AA` → 27); null past XFD or for anything but letters. */
+export declare function columnLettersToNumber(letters: string): number | null;
+/** A 1-based column to its letters (1 → `A`, 27 → `AA`); empty for anything below 1 or fractional. */
+export declare function columnNumberToLetters(column: number): string;
+/** A cell's A1 address: `{ row: 7, column: 2 }` → `B7`. */
+export declare function formatA1Cell({ row, column }: {
+    row: number;
+    column: number;
+}): string;
+/** A rectangle's A1 address: `A1:C5`, or `A1` alone when it is one cell. */
+export declare function formatA1Range({ startRow, endRow, startColumn, endColumn }: SheetRangeBounds): string;
+/**
+ * Split the sheet prefix off a reference: `'Q1 Plan'!A1:B2` → `Q1 Plan` and
+ * `A1:B2`, `Sales!B7` → `Sales` and `B7`, `B7` → no sheet and `B7`. A quoted
+ * name runs to the first quote that is not doubled (`'Bob''s'!A1` names
+ * `Bob's`); an unquoted one runs to the first `!` and holds no quote. Null for
+ * a prefix that is not one (an empty name, an unclosed quote, a quote without
+ * its `!`).
+ */
+export declare function splitSheetPrefix(reference: string): {
+    sheetName: string | null;
+    address: string;
+} | null;
+/**
+ * Read an A1 reference: a cell (`B7`), a rectangle (`A1:C5`), whole columns
+ * (`A:C`) or whole rows (`3:5`), with an optional sheet prefix (`Sales!`,
+ * `'Q1 Plan'!`), `$` absolute markers and any letter case. Whitespace around
+ * the reference and around its `:` is ignored. Null for anything else: a named
+ * range, a column past XFD, row 0 or a row past 1,048,576, a lone column or
+ * row, mixed sides (`A1:C`), three parts.
+ */
+export declare function parseA1Range(reference: string | null | undefined): A1Range | null;
+/**
+ * The cell a reference starts from as written, its first part: `D6` for
+ * `D6:C5`, row 1 of column C for `C:A`, column A of row 5 for `5:3`. A write
+ * anchored at a range starts there; the backend does not reorder a range
+ * written backwards. Null for anything `parseA1Range` cannot read.
+ */
+export declare function a1AnchorCell(reference: string | null | undefined): {
+    row: number;
+    column: number;
+} | null;
+/**
+ * The rectangle a cell or rectangle reference covers. Null for whole columns
+ * or rows, whose extent is open, and for anything `parseA1Range` cannot read.
+ */
+export declare function a1RangeBounds(reference: string | null | undefined): SheetRangeBounds | null;
+export {};