@athenaintel/react 0.48.0 → 0.52.1

package/dist/agent-runtime/src/edit-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"edit-command.js","sources":["../../../../agent-runtime/src/edit-command.ts"],"sourcesContent":["import type { StatewireThread } from '@assistant-ui/react-statewire';\nimport { DEEP_AGENT_INTEREST_PROTOCOL } from './generated/runconfig-contract';\nimport {\n  type DeepAgentMessageWindow,\n  pageInterestRequests,\n  readDeepAgentMessageWindow,\n} from './message-window';\nimport { hasStatewireThreadExtras } from './thread-extras';\n\n/**\n * Wire-accurate `run/edit` construction for deep-agent retry/edit, shared by\n * every surface that resubmits a user message.\n *\n * assistant-ui builds the command's `runAnchorMessageId` from the CONVERTED\n * thread messages (`resolveEditCommand`: `messages[index - 1].id`), but the\n * deep-agent host validates that anchor against the edited message's parent in\n * its RAW message list (`harness_sdk.linear_thread`: the entry before it in\n * `state[\"messages\"]`). Those two lists do not line up:\n *\n * - the converter chunks an assistant turn and its tool messages into ONE\n *   thread message carrying only the FIRST wire id, so the anchor names the\n *   head of the previous turn instead of its last tool message;\n * - `sanitizeLangChainMessages` drops hidden-from-frontend and unconvertible\n *   entries, so a dropped tail message is invisible to the anchor too.\n *\n * Either way the host rejects the command with `wrong-anchor`\n * (`runAnchorMessageId … is not the source's parent`) AFTER the composer's\n * synchronous `send()` returned, so the retry/edit silently does nothing.\n *\n * Building the command here off the replicated raw state makes the anchor the\n * same value the host computes.\n *\n * The raw list is the loaded interest window, so the first loaded message's\n * parent is not in it while older messages exist — an edit there must not\n * anchor on `null` (the root, rejected `wrong-anchor`); a message below the\n * window has no parent on this client at all. {@link resolveDeepAgentEditCommand}\n * states older page interests until the parent is loaded.\n */\n\n/**\n * Host metadata frozen at submission, settling once the async capture does.\n * The message-metadata preparation surface — `prepareMessageMetadata`,\n * `discardPreparedMessageMetadata`, `sendPreparedEdit` and `sendCommand`'s\n * `preparedMetadata` option — is what the monorepo patches into\n * `@assistant-ui/react-statewire@0.31.0` (`patches/`). It is declared\n * structurally here rather than as `StatewireThread.Extras[...]` so that the\n * published sources also compile against the unpatched upstream typings, where\n * those members are absent and the edit path's optional calls never run.\n */\nexport type DeepAgentPreparedMessageMetadata = Promise<Record<string, unknown> | undefined>;\n\n/** The pieces of the statewire thread extras the edit path reads. */\nexport interface DeepAgentStatewireExtras {\n  /** The library's dispatch; it resolves with the host's reply to the command. */\n  sendCommand: (\n    command: StatewireThread.Command,\n    options?: { preparedMetadata?: DeepAgentPreparedMessageMetadata | undefined },\n  ) => Promise<unknown> | void;\n  /** Optional on older hosts; capture before loading an edit's history anchor. */\n  prepareMessageMetadata?: (() => DeepAgentPreparedMessageMetadata) | undefined;\n  discardPreparedMessageMetadata?:\n    | ((prepared: DeepAgentPreparedMessageMetadata) => void)\n    | undefined;\n  sendPreparedEdit?:\n    | ((sourceId: string, prepared: DeepAgentPreparedMessageMetadata) => void)\n    | undefined;\n  isPreparingSubmission?: boolean;\n  /** The composed thread state — its `messages` are the raw wire messages of the loaded window. */\n  state: { messages?: readonly { id?: unknown }[] } | null;\n  /** The mounted documents (the interest window), absent on a wire without documents. */\n  documents?: StatewireThread.Extras['documents'];\n  invoke?: StatewireThread.Extras['invoke'];\n  /** The live run, when one is in flight; `epoch` advances on each dispatch. */\n  runs: { runId?: string | null; epoch?: number };\n  /** The host's replicated run status; absent on a surface that predates it. */\n  status?: StatewireThread.ThreadStatus;\n}\n\n/**\n * The statewire extras of the nearest aui thread, or `null` when the thread is\n * not a statewire thread (e.g. a read-only subagent transcript runtime).\n * Gated on {@link hasStatewireThreadExtras} for the same reason the approval\n * card is: the library's own hooks throw on a non-statewire thread.\n */\nexport function readDeepAgentStatewireExtras(extras: unknown): DeepAgentStatewireExtras | null {\n  if (!hasStatewireThreadExtras(extras)) return null;\n  return extras as DeepAgentStatewireExtras;\n}\n\n/**\n * The host's parent of `sourceId`: the raw wire message directly before it\n * (`null` when it is the first of the whole transcript). Returns `undefined`\n * when `sourceId` is not in the raw list at all — an optimistic bubble the\n * host has not settled yet, a message below the loaded window, or a surface\n * whose state this module cannot read — or when it is the first loaded\n * message while older ones exist (`hasOlder`), so the caller can load more or\n * fall back to the library's own path instead of asserting a wrong anchor.\n */\nexport function resolveWireAnchorMessageId({\n  wireMessages,\n  sourceId,\n  hasOlder = false,\n}: {\n  wireMessages: readonly { id?: unknown }[] | undefined;\n  sourceId: string;\n  hasOlder?: boolean;\n}): string | null | undefined {\n  if (!wireMessages) return undefined;\n  const index = wireMessages.findIndex((message) => message?.id === sourceId);\n  if (index < 0) return undefined;\n  if (index === 0) return hasOlder ? undefined : null;\n  const parentId = wireMessages[index - 1]?.id;\n  return typeof parentId === 'string' ? parentId : undefined;\n}\n\n/**\n * Whether `sourceId`'s parent lies below the loaded window: the message is\n * absent from the raw list, or its first entry, while older messages exist.\n * The caller loads older history before an edit can be anchored.\n */\nexport function isSourceBelowLoadedWindow({\n  wireMessages,\n  sourceId,\n  window,\n}: {\n  wireMessages: readonly { id?: unknown }[] | undefined;\n  sourceId: string;\n  window: DeepAgentMessageWindow | null;\n}): boolean {\n  if (!wireMessages || window === null || !window.hasOlder) return false;\n  const index = wireMessages.findIndex((message) => message?.id === sourceId);\n  return index <= 0;\n}\n\nconst readWindow = (extras: DeepAgentStatewireExtras) =>\n  readDeepAgentMessageWindow(extras.documents?.list());\n\n/**\n * A fresh command / message id (uniqueness, not secrecy). `crypto.randomUUID`\n * where the host runtime has it — every browser, Bun, Node and Hermes with\n * webcrypto — and a v4-shaped fallback elsewhere, so the shared path never\n * throws on a runtime without full webcrypto.\n */\nfunction mintCommandId(): string {\n  const webcrypto = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;\n  if (typeof webcrypto?.randomUUID === 'function') return webcrypto.randomUUID();\n  const hex = (): string => Math.floor(Math.random() * 0x10000).toString(16).padStart(4, '0');\n  return `${hex()}${hex()}-${hex()}-4${hex().slice(1)}-${hex()}-${hex()}${hex()}${hex()}`;\n}\n\n/**\n * The `run/edit` command for resubmitting `sourceId` with `text`, anchored on\n * the host's own parent. `null` when the anchor cannot be resolved from the\n * replicated state.\n */\nexport function buildDeepAgentEditCommand({\n  extras,\n  sourceId,\n  text,\n}: {\n  extras: DeepAgentStatewireExtras;\n  sourceId: string;\n  text: string;\n}): StatewireThread.RunEditCommand | null {\n  const runAnchorMessageId = resolveWireAnchorMessageId({\n    wireMessages: extras.state?.messages,\n    sourceId,\n    hasOlder: readWindow(extras)?.hasOlder ?? false,\n  });\n  if (runAnchorMessageId === undefined) return null;\n  return {\n    type: 'run/edit',\n    runId: extras.runs.runId ?? mintCommandId(),\n    message: { id: mintCommandId(), role: 'user', parts: [{ type: 'text', text }] },\n    sourceId,\n    runAnchorMessageId,\n  };\n}\n\n/**\n * State one more page of older history for a windowed thread: the next page\n * past the loaded window's oldest message. Resolves `true` once the host has\n * mounted it (it answers the statement after mounting), `false` when there is\n * nothing older, the thread is not a windowed statewire thread, or no page can\n * be stated. For a reader that needs a message below the loaded window — a\n * search result revealing an older turn of a long conversation — and pages\n * until it renders.\n */\nexport async function loadOlderDeepAgentHistoryPage({\n  readExtras,\n  pageSize,\n}: {\n  readExtras: () => DeepAgentStatewireExtras | null;\n  pageSize?: number;\n}): Promise<boolean> {\n  const extras = readExtras();\n  if (!extras?.invoke) return false;\n  const window = readWindow(extras);\n  if (window === null || !window.hasOlder) return false;\n  const requests = pageInterestRequests(window, pageSize);\n  if (requests === null) return false;\n  await extras.invoke(DEEP_AGENT_INTEREST_PROTOCOL, 'set', [requests]);\n  return true;\n}\n\n/**\n * Pages of older history stated while looking for an edited message's host\n * parent. Each page is up to a window's worth of messages, so an edit reaches\n * this many windows below what was loaded before it gives up.\n */\nexport const MAX_EDIT_ANCHOR_HISTORY_LOADS = 5;\n\n/**\n * The anchored `run/edit` for `sourceId`, stating older page interests one at\n * a time when the message's parent lies below the loaded window. Every page\n * is read back from the live documents (`readExtras` — the host mounts them\n * before it answers the statement), so the anchor is always the host's own\n * parent id.\n *\n * Resolves `null` — the caller's cue for the library's composer path, whose\n * failure it reports — when the thread is not a statewire thread, the host has\n * not settled the message, the history is exhausted without it, or the page\n * budget ({@link MAX_EDIT_ANCHOR_HISTORY_LOADS}) is spent. A synchronous\n * resolution never awaits: the first read either anchors at once or decides\n * that pages are needed.\n */\nexport async function resolveDeepAgentEditCommand({\n  readExtras,\n  sourceId,\n  text,\n  pageSize,\n  maxHistoryLoads = MAX_EDIT_ANCHOR_HISTORY_LOADS,\n}: {\n  /** The live thread extras — re-read per page so each anchor attempt sees the widened window. */\n  readExtras: () => DeepAgentStatewireExtras | null;\n  sourceId: string;\n  text: string;\n  pageSize?: number;\n  maxHistoryLoads?: number;\n}): Promise<StatewireThread.RunEditCommand | null> {\n  for (let page = 0; page <= maxHistoryLoads; page += 1) {\n    const extras = readExtras();\n    if (!extras) return null;\n    const command = buildDeepAgentEditCommand({ extras, sourceId, text });\n    if (command) return command;\n    if (page === maxHistoryLoads || !extras.invoke) return null;\n    const window = readWindow(extras);\n    if (!isSourceBelowLoadedWindow({ wireMessages: extras.state?.messages, sourceId, window })) {\n      return null;\n    }\n    const requests = window === null ? null : pageInterestRequests(window, pageSize);\n    if (requests === null) return null;\n    await extras.invoke(DEEP_AGENT_INTEREST_PROTOCOL, 'set', [requests]);\n  }\n  return null;\n}\n"],"names":[],"mappings":";;;AAoFO,SAAS,6BAA6B,QAAkD;AAC7F,MAAI,CAAC,yBAAyB,MAAM,EAAG,QAAO;AAC9C,SAAO;AACT;AAWO,SAAS,2BAA2B;AAAA,EACzC;AAAA,EACA;AAAA,EACA,WAAW;AACb,GAI8B;;AAC5B,MAAI,CAAC,aAAc,QAAO;AAC1B,QAAM,QAAQ,aAAa,UAAU,CAAC,aAAY,mCAAS,QAAO,QAAQ;AAC1E,MAAI,QAAQ,EAAG,QAAO;AACtB,MAAI,UAAU,EAAG,QAAO,WAAW,SAAY;AAC/C,QAAM,YAAW,kBAAa,QAAQ,CAAC,MAAtB,mBAAyB;AAC1C,SAAO,OAAO,aAAa,WAAW,WAAW;AACnD;AAOO,SAAS,0BAA0B;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AACF,GAIY;AACV,MAAI,CAAC,gBAAgB,WAAW,QAAQ,CAAC,OAAO,SAAU,QAAO;AACjE,QAAM,QAAQ,aAAa,UAAU,CAAC,aAAY,mCAAS,QAAO,QAAQ;AAC1E,SAAO,SAAS;AAClB;AAEA,MAAM,aAAa,CAAC,WAAA;;AAClB,qCAA2B,YAAO,cAAP,mBAAkB,MAAM;AAAA;AAQrD,SAAS,gBAAwB;AAC/B,QAAM,YAAa,WAA0D;AAC7E,MAAI,QAAO,uCAAW,gBAAe,WAAY,QAAO,UAAU,WAAA;AAClE,QAAM,MAAM,MAAc,KAAK,MAAM,KAAK,OAAA,IAAW,KAAO,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG;AAC1F,SAAO,GAAG,IAAA,CAAK,GAAG,IAAA,CAAK,IAAI,IAAA,CAAK,KAAK,MAAM,MAAM,CAAC,CAAC,IAAI,IAAA,CAAK,IAAI,KAAK,GAAG,IAAA,CAAK,GAAG,IAAA,CAAK;AACvF;AAOO,SAAS,0BAA0B;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AACF,GAI0C;;AACxC,QAAM,qBAAqB,2BAA2B;AAAA,IACpD,eAAc,YAAO,UAAP,mBAAc;AAAA,IAC5B;AAAA,IACA,YAAU,gBAAW,MAAM,MAAjB,mBAAoB,aAAY;AAAA,EAAA,CAC3C;AACD,MAAI,uBAAuB,OAAW,QAAO;AAC7C,SAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO,OAAO,KAAK,SAAS,cAAA;AAAA,IAC5B,SAAS,EAAE,IAAI,cAAA,GAAiB,MAAM,QAAQ,OAAO,CAAC,EAAE,MAAM,QAAQ,KAAA,CAAM,EAAA;AAAA,IAC5E;AAAA,IACA;AAAA,EAAA;AAEJ;AAiCO,MAAM,gCAAgC;AAgB7C,eAAsB,4BAA4B;AAAA,EAChD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,kBAAkB;AACpB,GAOmD;;AACjD,WAAS,OAAO,GAAG,QAAQ,iBAAiB,QAAQ,GAAG;AACrD,UAAM,SAAS,WAAA;AACf,QAAI,CAAC,OAAQ,QAAO;AACpB,UAAM,UAAU,0BAA0B,EAAE,QAAQ,UAAU,MAAM;AACpE,QAAI,QAAS,QAAO;AACpB,QAAI,SAAS,mBAAmB,CAAC,OAAO,OAAQ,QAAO;AACvD,UAAM,SAAS,WAAW,MAAM;AAChC,QAAI,CAAC,0BAA0B,EAAE,eAAc,YAAO,UAAP,mBAAc,UAAU,UAAU,OAAA,CAAQ,GAAG;AAC1F,aAAO;AAAA,IACT;AACA,UAAM,WAAW,WAAW,OAAO,OAAO,qBAAqB,QAAQ,QAAQ;AAC/E,QAAI,aAAa,KAAM,QAAO;AAC9B,UAAM,OAAO,OAAO,8BAA8B,OAAO,CAAC,QAAQ,CAAC;AAAA,EACrE;AACA,SAAO;AACT;"}
+{"version":3,"file":"edit-command.js","sources":["../../../../agent-runtime/src/edit-command.ts"],"sourcesContent":["import type { StatewireThread } from '@assistant-ui/react-statewire';\nimport { DEEP_AGENT_INTEREST_PROTOCOL } from './generated/runconfig-contract';\nimport {\n  type DeepAgentMessageWindow,\n  pageInterestRequests,\n  readDeepAgentMessageWindow,\n} from './message-window';\nimport { hasStatewireThreadExtras } from './thread-extras';\n\n/**\n * Wire-accurate `run/edit` construction for deep-agent retry/edit, shared by\n * every surface that resubmits a user message.\n *\n * assistant-ui builds the command's `runAnchorMessageId` from the CONVERTED\n * thread messages (`resolveEditCommand`: `messages[index - 1].id`), but the\n * deep-agent host validates that anchor against the edited message's parent in\n * its RAW message list (`harness_sdk.linear_thread`: the entry before it in\n * `state[\"messages\"]`). Those two lists do not line up:\n *\n * - the converter chunks an assistant turn and its tool messages into ONE\n *   thread message carrying only the FIRST wire id, so the anchor names the\n *   head of the previous turn instead of its last tool message;\n * - `sanitizeLangChainMessages` drops hidden-from-frontend and unconvertible\n *   entries, so a dropped tail message is invisible to the anchor too.\n *\n * Either way the host rejects the command with `wrong-anchor`\n * (`runAnchorMessageId … is not the source's parent`) AFTER the composer's\n * synchronous `send()` returned, so the retry/edit silently does nothing.\n *\n * Building the command here off the replicated raw state makes the anchor the\n * same value the host computes.\n *\n * The raw list is the loaded interest window, so the first loaded message's\n * parent is not in it while older messages exist — an edit there must not\n * anchor on `null` (the root, rejected `wrong-anchor`); a message below the\n * window has no parent on this client at all. {@link resolveDeepAgentEditCommand}\n * states older page interests until the parent is loaded.\n */\n\n/**\n * Host metadata frozen at submission, settling once the async capture does.\n * The message-metadata preparation surface — `prepareMessageMetadata`,\n * `discardPreparedMessageMetadata`, `sendPreparedEdit` and `sendCommand`'s\n * `preparedMetadata` option — is what the monorepo patches into\n * `@assistant-ui/react-statewire@0.31.0` (`patches/`). It is declared\n * structurally here rather than as `StatewireThread.Extras[...]` so that the\n * published sources also compile against the unpatched upstream typings, where\n * those members are absent and the edit path's optional calls never run.\n */\nexport type DeepAgentPreparedMessageMetadata = Promise<Record<string, unknown> | undefined>;\n\n/** The pieces of the statewire thread extras the edit path reads. */\nexport interface DeepAgentStatewireExtras {\n  /** The library's dispatch; it resolves with the host's reply to the command. */\n  sendCommand: (\n    command: StatewireThread.Command,\n    options?: { preparedMetadata?: DeepAgentPreparedMessageMetadata | undefined },\n  ) => Promise<unknown> | void;\n  /** Optional on older hosts; capture before loading an edit's history anchor. */\n  prepareMessageMetadata?: (() => DeepAgentPreparedMessageMetadata) | undefined;\n  discardPreparedMessageMetadata?:\n    | ((prepared: DeepAgentPreparedMessageMetadata) => void)\n    | undefined;\n  sendPreparedEdit?:\n    | ((sourceId: string, prepared: DeepAgentPreparedMessageMetadata) => void)\n    | undefined;\n  isPreparingSubmission?: boolean;\n  /** The composed thread state — its `messages` are the raw wire messages of the loaded window. */\n  state: { messages?: readonly { id?: unknown }[] } | null;\n  /** The mounted documents (the interest window), absent on a wire without documents. */\n  documents?: StatewireThread.Extras['documents'];\n  invoke?: StatewireThread.Extras['invoke'];\n  /** The live run, when one is in flight; `epoch` advances on each dispatch. */\n  runs: { runId?: string | null; epoch?: number };\n  /** The host's replicated run status; absent on a surface that predates it. */\n  status?: StatewireThread.ThreadStatus;\n}\n\n/**\n * The statewire extras of the nearest aui thread, or `null` when the thread is\n * not a statewire thread (e.g. a read-only subagent transcript runtime).\n * Gated on {@link hasStatewireThreadExtras} for the same reason the approval\n * card is: the library's own hooks throw on a non-statewire thread.\n */\nexport function readDeepAgentStatewireExtras(extras: unknown): DeepAgentStatewireExtras | null {\n  if (!hasStatewireThreadExtras(extras)) return null;\n  return extras as DeepAgentStatewireExtras;\n}\n\n/**\n * The host's parent of `sourceId`: the raw wire message directly before it\n * (`null` when it is the first of the whole transcript). Returns `undefined`\n * when `sourceId` is not in the raw list at all — an optimistic bubble the\n * host has not settled yet, a message below the loaded window, or a surface\n * whose state this module cannot read — or when it is the first loaded\n * message while older ones exist (`hasOlder`), so the caller can load more or\n * fall back to the library's own path instead of asserting a wrong anchor.\n */\nexport function resolveWireAnchorMessageId({\n  wireMessages,\n  sourceId,\n  hasOlder = false,\n}: {\n  wireMessages: readonly { id?: unknown }[] | undefined;\n  sourceId: string;\n  hasOlder?: boolean;\n}): string | null | undefined {\n  if (!wireMessages) return undefined;\n  const index = wireMessages.findIndex((message) => message?.id === sourceId);\n  if (index < 0) return undefined;\n  if (index === 0) return hasOlder ? undefined : null;\n  const parentId = wireMessages[index - 1]?.id;\n  return typeof parentId === 'string' ? parentId : undefined;\n}\n\n/**\n * Whether `sourceId`'s parent lies below the loaded window: the message is\n * absent from the raw list, or its first entry, while older messages exist.\n * The caller loads older history before an edit can be anchored.\n */\nexport function isSourceBelowLoadedWindow({\n  wireMessages,\n  sourceId,\n  window,\n}: {\n  wireMessages: readonly { id?: unknown }[] | undefined;\n  sourceId: string;\n  window: DeepAgentMessageWindow | null;\n}): boolean {\n  if (!wireMessages || window === null || !window.hasOlder) return false;\n  const index = wireMessages.findIndex((message) => message?.id === sourceId);\n  return index <= 0;\n}\n\nconst readWindow = (extras: DeepAgentStatewireExtras) =>\n  readDeepAgentMessageWindow(extras.documents?.list());\n\n/**\n * A fresh command / message id (uniqueness, not secrecy). `crypto.randomUUID`\n * where the host runtime has it — every browser, Bun, Node and Hermes with\n * webcrypto — and a v4-shaped fallback elsewhere, so the shared path never\n * throws on a runtime without full webcrypto.\n */\nfunction mintCommandId(): string {\n  const webcrypto = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;\n  if (typeof webcrypto?.randomUUID === 'function') return webcrypto.randomUUID();\n  const hex = (): string => Math.floor(Math.random() * 0x10000).toString(16).padStart(4, '0');\n  return `${hex()}${hex()}-${hex()}-4${hex().slice(1)}-${hex()}-${hex()}${hex()}${hex()}`;\n}\n\n/**\n * The `run/edit` command for resubmitting `sourceId` with `text`, anchored on\n * the host's own parent. `null` when the anchor cannot be resolved from the\n * replicated state.\n */\nexport function buildDeepAgentEditCommand({\n  extras,\n  sourceId,\n  text,\n}: {\n  extras: DeepAgentStatewireExtras;\n  sourceId: string;\n  text: string;\n}): StatewireThread.RunEditCommand | null {\n  const runAnchorMessageId = resolveWireAnchorMessageId({\n    wireMessages: extras.state?.messages,\n    sourceId,\n    hasOlder: readWindow(extras)?.hasOlder ?? false,\n  });\n  if (runAnchorMessageId === undefined) return null;\n  return {\n    type: 'run/edit',\n    runId: extras.runs.runId ?? mintCommandId(),\n    message: { id: mintCommandId(), role: 'user', parts: [{ type: 'text', text }] },\n    sourceId,\n    runAnchorMessageId,\n  };\n}\n\n/**\n * Whether a windowed statewire thread has older history than it has loaded:\n * `null` while that is not known yet (the head interest has not resolved; a\n * remembered transcript can show from cache before it does), and `false` for\n * a thread that is not a statewire thread, so a reader looking for an older\n * message waits for the window, or stops.\n */\nexport function deepAgentHistoryHasOlder(extras: unknown): boolean | null {\n  const typed = readDeepAgentStatewireExtras(extras);\n  if (typed === null) return false;\n  return readWindow(typed)?.hasOlder ?? null;\n}\n\n/**\n * State one more page of older history for a windowed thread: the next page\n * past the loaded window's oldest message. Resolves `true` once the host has\n * mounted it (it answers the statement after mounting), `false` when there is\n * nothing older, the thread is not a windowed statewire thread, or no page can\n * be stated. For a reader that needs a message below the loaded window — a\n * search result revealing an older turn of a long conversation — and pages\n * until it renders.\n */\nexport async function loadOlderDeepAgentHistoryPage({\n  readExtras,\n  pageSize,\n}: {\n  readExtras: () => DeepAgentStatewireExtras | null;\n  pageSize?: number;\n}): Promise<boolean> {\n  const extras = readExtras();\n  if (!extras?.invoke) return false;\n  const window = readWindow(extras);\n  if (window === null || !window.hasOlder) return false;\n  const requests = pageInterestRequests(window, pageSize);\n  if (requests === null) return false;\n  await extras.invoke(DEEP_AGENT_INTEREST_PROTOCOL, 'set', [requests]);\n  return true;\n}\n\n/**\n * Pages of older history stated while looking for an edited message's host\n * parent. Each page is up to a window's worth of messages, so an edit reaches\n * this many windows below what was loaded before it gives up.\n */\nexport const MAX_EDIT_ANCHOR_HISTORY_LOADS = 5;\n\n/**\n * The anchored `run/edit` for `sourceId`, stating older page interests one at\n * a time when the message's parent lies below the loaded window. Every page\n * is read back from the live documents (`readExtras` — the host mounts them\n * before it answers the statement), so the anchor is always the host's own\n * parent id.\n *\n * Resolves `null` — the caller's cue for the library's composer path, whose\n * failure it reports — when the thread is not a statewire thread, the host has\n * not settled the message, the history is exhausted without it, or the page\n * budget ({@link MAX_EDIT_ANCHOR_HISTORY_LOADS}) is spent. A synchronous\n * resolution never awaits: the first read either anchors at once or decides\n * that pages are needed.\n */\nexport async function resolveDeepAgentEditCommand({\n  readExtras,\n  sourceId,\n  text,\n  pageSize,\n  maxHistoryLoads = MAX_EDIT_ANCHOR_HISTORY_LOADS,\n}: {\n  /** The live thread extras — re-read per page so each anchor attempt sees the widened window. */\n  readExtras: () => DeepAgentStatewireExtras | null;\n  sourceId: string;\n  text: string;\n  pageSize?: number;\n  maxHistoryLoads?: number;\n}): Promise<StatewireThread.RunEditCommand | null> {\n  for (let page = 0; page <= maxHistoryLoads; page += 1) {\n    const extras = readExtras();\n    if (!extras) return null;\n    const command = buildDeepAgentEditCommand({ extras, sourceId, text });\n    if (command) return command;\n    if (page === maxHistoryLoads || !extras.invoke) return null;\n    const window = readWindow(extras);\n    if (!isSourceBelowLoadedWindow({ wireMessages: extras.state?.messages, sourceId, window })) {\n      return null;\n    }\n    const requests = window === null ? null : pageInterestRequests(window, pageSize);\n    if (requests === null) return null;\n    await extras.invoke(DEEP_AGENT_INTEREST_PROTOCOL, 'set', [requests]);\n  }\n  return null;\n}\n"],"names":[],"mappings":";;;AAoFO,SAAS,6BAA6B,QAAkD;AAC7F,MAAI,CAAC,yBAAyB,MAAM,EAAG,QAAO;AAC9C,SAAO;AACT;AAWO,SAAS,2BAA2B;AAAA,EACzC;AAAA,EACA;AAAA,EACA,WAAW;AACb,GAI8B;;AAC5B,MAAI,CAAC,aAAc,QAAO;AAC1B,QAAM,QAAQ,aAAa,UAAU,CAAC,aAAY,mCAAS,QAAO,QAAQ;AAC1E,MAAI,QAAQ,EAAG,QAAO;AACtB,MAAI,UAAU,EAAG,QAAO,WAAW,SAAY;AAC/C,QAAM,YAAW,kBAAa,QAAQ,CAAC,MAAtB,mBAAyB;AAC1C,SAAO,OAAO,aAAa,WAAW,WAAW;AACnD;AAOO,SAAS,0BAA0B;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AACF,GAIY;AACV,MAAI,CAAC,gBAAgB,WAAW,QAAQ,CAAC,OAAO,SAAU,QAAO;AACjE,QAAM,QAAQ,aAAa,UAAU,CAAC,aAAY,mCAAS,QAAO,QAAQ;AAC1E,SAAO,SAAS;AAClB;AAEA,MAAM,aAAa,CAAC,WAAA;;AAClB,qCAA2B,YAAO,cAAP,mBAAkB,MAAM;AAAA;AAQrD,SAAS,gBAAwB;AAC/B,QAAM,YAAa,WAA0D;AAC7E,MAAI,QAAO,uCAAW,gBAAe,WAAY,QAAO,UAAU,WAAA;AAClE,QAAM,MAAM,MAAc,KAAK,MAAM,KAAK,OAAA,IAAW,KAAO,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG;AAC1F,SAAO,GAAG,IAAA,CAAK,GAAG,IAAA,CAAK,IAAI,IAAA,CAAK,KAAK,MAAM,MAAM,CAAC,CAAC,IAAI,IAAA,CAAK,IAAI,KAAK,GAAG,IAAA,CAAK,GAAG,IAAA,CAAK;AACvF;AAOO,SAAS,0BAA0B;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AACF,GAI0C;;AACxC,QAAM,qBAAqB,2BAA2B;AAAA,IACpD,eAAc,YAAO,UAAP,mBAAc;AAAA,IAC5B;AAAA,IACA,YAAU,gBAAW,MAAM,MAAjB,mBAAoB,aAAY;AAAA,EAAA,CAC3C;AACD,MAAI,uBAAuB,OAAW,QAAO;AAC7C,SAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO,OAAO,KAAK,SAAS,cAAA;AAAA,IAC5B,SAAS,EAAE,IAAI,cAAA,GAAiB,MAAM,QAAQ,OAAO,CAAC,EAAE,MAAM,QAAQ,KAAA,CAAM,EAAA;AAAA,IAC5E;AAAA,IACA;AAAA,EAAA;AAEJ;AASO,SAAS,yBAAyB,QAAiC;;AACxE,QAAM,QAAQ,6BAA6B,MAAM;AACjD,MAAI,UAAU,KAAM,QAAO;AAC3B,WAAO,gBAAW,KAAK,MAAhB,mBAAmB,aAAY;AACxC;AAWA,eAAsB,8BAA8B;AAAA,EAClD;AAAA,EACA;AACF,GAGqB;AACnB,QAAM,SAAS,WAAA;AACf,MAAI,EAAC,iCAAQ,QAAQ,QAAO;AAC5B,QAAM,SAAS,WAAW,MAAM;AAChC,MAAI,WAAW,QAAQ,CAAC,OAAO,SAAU,QAAO;AAChD,QAAM,WAAW,qBAAqB,QAAQ,QAAQ;AACtD,MAAI,aAAa,KAAM,QAAO;AAC9B,QAAM,OAAO,OAAO,8BAA8B,OAAO,CAAC,QAAQ,CAAC;AACnE,SAAO;AACT;AAOO,MAAM,gCAAgC;AAgB7C,eAAsB,4BAA4B;AAAA,EAChD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,kBAAkB;AACpB,GAOmD;;AACjD,WAAS,OAAO,GAAG,QAAQ,iBAAiB,QAAQ,GAAG;AACrD,UAAM,SAAS,WAAA;AACf,QAAI,CAAC,OAAQ,QAAO;AACpB,UAAM,UAAU,0BAA0B,EAAE,QAAQ,UAAU,MAAM;AACpE,QAAI,QAAS,QAAO;AACpB,QAAI,SAAS,mBAAmB,CAAC,OAAO,OAAQ,QAAO;AACvD,UAAM,SAAS,WAAW,MAAM;AAChC,QAAI,CAAC,0BAA0B,EAAE,eAAc,YAAO,UAAP,mBAAc,UAAU,UAAU,OAAA,CAAQ,GAAG;AAC1F,aAAO;AAAA,IACT;AACA,UAAM,WAAW,WAAW,OAAO,OAAO,qBAAqB,QAAQ,QAAQ;AAC/E,QAAI,aAAa,KAAM,QAAO;AAC9B,UAAM,OAAO,OAAO,8BAA8B,OAAO,CAAC,QAAQ,CAAC;AAAA,EACrE;AACA,SAAO;AACT;"}

package/dist/agent-runtime/src/handoff-arrival.cjs

@@ -19,6 +19,23 @@ function subscribeHandoffArrivals(listener) {
     listeners.delete(listener);
   };
 }
+function settleHandoffArrivalCursor(threadId) {
+  const { arrivals } = registry();
+  const arrival = arrivals.get(threadId);
+  if (!arrival || arrival.cursor === null) return;
+  arrivals.set(threadId, { ...arrival, cursor: null });
+  publish();
+}
+function useHandoffArrivalCursor(threadId) {
+  return require$$0.useSyncExternalStore(
+    subscribeHandoffArrivals,
+    () => {
+      var _a;
+      return ((_a = readHandoffArrival(threadId)) == null ? void 0 : _a.cursor) ?? null;
+    },
+    () => null
+  );
+}
 function anchorHandoffArrival({
   threadId,
   afterMessageId
@@ -54,7 +71,9 @@ function useHandoffArrivalAfter(messageId) {
 exports.HandoffArrivalContext = HandoffArrivalContext;
 exports.anchorHandoffArrival = anchorHandoffArrival;
 exports.readHandoffArrival = readHandoffArrival;
+exports.settleHandoffArrivalCursor = settleHandoffArrivalCursor;
 exports.subscribeHandoffArrivals = subscribeHandoffArrivals;
 exports.useHandoffArrival = useHandoffArrival;
 exports.useHandoffArrivalAfter = useHandoffArrivalAfter;
+exports.useHandoffArrivalCursor = useHandoffArrivalCursor;
 //# sourceMappingURL=handoff-arrival.cjs.map

package/dist/agent-runtime/src/handoff-arrival.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"handoff-arrival.cjs","sources":["../../../../agent-runtime/src/handoff-arrival.ts"],"sourcesContent":["/**\n * Where a handed-off conversation arrived on this surface: a transcript divider\n * (\"Continued from your phone\") after the last message that was already there\n * when the person picked it up.\n *\n * Ephemeral and client-side. A host records an arrival when its pick-up lands\n * (`recordHandoffArrival`); its transcript anchors it to the thread's last\n * message once that history has loaded (`useHandoffArrival`) and renders the\n * divider after that message (`useHandoffArrivalAfter`). Nothing is sent to\n * Athena or persisted; a reload forgets it.\n */\nimport { createContext, useContext, useEffect, useSyncExternalStore } from 'react';\nimport { continuedFromLabel } from './thread-handoff-protocol';\n\nexport interface HandoffArrival {\n  threadId: string;\n  /** \"Continued from your phone\". */\n  label: string;\n  /**\n   * The last message present when the conversation arrived; the divider goes\n   * right after it. `null` until the transcript has anchored it.\n   */\n  afterMessageId: string | null;\n}\n\n/** Enough for every conversation one person picks up in a session. */\nexport const MAX_HANDOFF_ARRIVALS = 20;\n\n/**\n * The arrivals live on `globalThis`, not in module scope, because two copies of\n * this module can run in one page: the SDK bundles agent-runtime into its dist\n * while a host (Spaces, the Chrome extension, Midas) imports it directly. The\n * host records through its copy and the SDK transcript reads through its own.\n */\nconst HANDOFF_ARRIVALS = Symbol.for('@athenaintel/agent-runtime/handoff-arrivals');\n\ninterface ArrivalRegistry {\n  arrivals: Map<string, HandoffArrival>;\n  listeners: Set<() => void>;\n}\n\ntype ArrivalRegistryHost = typeof globalThis & { [HANDOFF_ARRIVALS]?: ArrivalRegistry };\n\n// process-local: this client only — what this surface picked up; nothing is persisted\nfunction registry(): ArrivalRegistry {\n  const host = globalThis as ArrivalRegistryHost;\n  return (host[HANDOFF_ARRIVALS] ??= { arrivals: new Map(), listeners: new Set() });\n}\n\nfunction publish(): void {\n  for (const listener of registry().listeners) listener();\n}\n\n/**\n * A pick-up landed `threadId` here from `source` (`mobile`, `chrome`, …). A\n * second pick-up of the same thread moves the divider to the new arrival.\n */\nexport function recordHandoffArrival({\n  threadId,\n  source,\n}: {\n  threadId: string;\n  source: string;\n}): void {\n  if (!threadId) return;\n  const { arrivals } = registry();\n  arrivals.delete(threadId);\n  arrivals.set(threadId, { threadId, label: continuedFromLabel(source), afterMessageId: null });\n  while (arrivals.size > MAX_HANDOFF_ARRIVALS) {\n    const oldest = arrivals.keys().next().value;\n    if (oldest === undefined) break;\n    arrivals.delete(oldest);\n  }\n  publish();\n}\n\n/** The arrival recorded for `threadId`, anchored or not. */\nexport function readHandoffArrival(threadId: string | null | undefined): HandoffArrival | null {\n  return (threadId && registry().arrivals.get(threadId)) || null;\n}\n\nexport function subscribeHandoffArrivals(listener: () => void): () => void {\n  const { listeners } = registry();\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** Forgets the arrival of `threadId`: the pick-up never opened the conversation here. */\nexport function clearHandoffArrival(threadId: string): void {\n  if (!registry().arrivals.delete(threadId)) return;\n  publish();\n}\n\n/** The first anchor wins: later messages are what came after the arrival. */\nexport function anchorHandoffArrival({\n  threadId,\n  afterMessageId,\n}: {\n  threadId: string;\n  afterMessageId: string;\n}): void {\n  const { arrivals } = registry();\n  const arrival = arrivals.get(threadId);\n  if (!arrival || arrival.afterMessageId !== null) return;\n  arrivals.set(threadId, { ...arrival, afterMessageId });\n  publish();\n}\n\n/**\n * The divider for the transcript of `threadId`, once anchored. The transcript\n * passes its last message id and whether its history is still loading; the\n * first time history has loaded with a message in it, the arrival anchors\n * after that message. A thread already on screen anchors at once.\n */\nexport function useHandoffArrival({\n  threadId,\n  lastMessageId,\n  loading,\n}: {\n  threadId: string | null | undefined;\n  lastMessageId: string | null | undefined;\n  loading: boolean;\n}): HandoffArrival | null {\n  const arrival = useSyncExternalStore(\n    subscribeHandoffArrivals,\n    () => readHandoffArrival(threadId),\n    () => null\n  );\n  const unanchored = arrival !== null && arrival.afterMessageId === null;\n  useEffect(() => {\n    if (!threadId || !unanchored || loading || !lastMessageId) return;\n    anchorHandoffArrival({ threadId, afterMessageId: lastMessageId });\n  }, [threadId, unanchored, loading, lastMessageId]);\n  return arrival?.afterMessageId ? arrival : null;\n}\n\n/** The anchored arrival of the transcript being rendered, for its messages. */\nexport const HandoffArrivalContext = createContext<HandoffArrival | null>(null);\n\n/** The divider label when it goes right after `messageId`; `null` otherwise. */\nexport function useHandoffArrivalAfter(messageId: string | null | undefined): string | null {\n  const arrival = useContext(HandoffArrivalContext);\n  return arrival && messageId && arrival.afterMessageId === messageId ? arrival.label : null;\n}\n\nexport function resetHandoffArrivalsForTests(): void {\n  registry().arrivals.clear();\n  publish();\n}\n"],"names":["useSyncExternalStore","useEffect","createContext","useContext"],"mappings":";;;AAkCA,MAAM,mBAAmB,OAAO,IAAI,6CAA6C;AAUjF,SAAS,WAA4B;AACnC,QAAM,OAAO;AACb,SAAQ,oDAA2B,EAAE,UAAU,oBAAI,OAAO,WAAW,oBAAI,MAAI;AAC/E;AAEA,SAAS,UAAgB;AACvB,aAAW,YAAY,WAAW,UAAW,UAAA;AAC/C;AA0BO,SAAS,mBAAmB,UAA4D;AAC7F,SAAQ,YAAY,SAAA,EAAW,SAAS,IAAI,QAAQ,KAAM;AAC5D;AAEO,SAAS,yBAAyB,UAAkC;AACzE,QAAM,EAAE,UAAA,IAAc,SAAA;AACtB,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AASO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAGS;AACP,QAAM,EAAE,SAAA,IAAa,SAAA;AACrB,QAAM,UAAU,SAAS,IAAI,QAAQ;AACrC,MAAI,CAAC,WAAW,QAAQ,mBAAmB,KAAM;AACjD,WAAS,IAAI,UAAU,EAAE,GAAG,SAAS,gBAAgB;AACrD,UAAA;AACF;AAQO,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AACF,GAI0B;AACxB,QAAM,UAAUA,WAAAA;AAAAA,IACd;AAAA,IACA,MAAM,mBAAmB,QAAQ;AAAA,IACjC,MAAM;AAAA,EAAA;AAER,QAAM,aAAa,YAAY,QAAQ,QAAQ,mBAAmB;AAClEC,aAAAA,UAAU,MAAM;AACd,QAAI,CAAC,YAAY,CAAC,cAAc,WAAW,CAAC,cAAe;AAC3D,yBAAqB,EAAE,UAAU,gBAAgB,cAAA,CAAe;AAAA,EAClE,GAAG,CAAC,UAAU,YAAY,SAAS,aAAa,CAAC;AACjD,UAAO,mCAAS,kBAAiB,UAAU;AAC7C;AAGO,MAAM,wBAAwBC,WAAAA,cAAqC,IAAI;AAGvE,SAAS,uBAAuB,WAAqD;AAC1F,QAAM,UAAUC,WAAAA,WAAW,qBAAqB;AAChD,SAAO,WAAW,aAAa,QAAQ,mBAAmB,YAAY,QAAQ,QAAQ;AACxF;;;;;;;"}
+{"version":3,"file":"handoff-arrival.cjs","sources":["../../../../agent-runtime/src/handoff-arrival.ts"],"sourcesContent":["/**\n * Where a handed-off conversation arrived on this surface: a transcript divider\n * (\"Continued from your phone\") after the last message that was already there\n * when the person picked it up.\n *\n * Ephemeral and client-side. A host records an arrival when its pick-up lands\n * (`recordHandoffArrival`); its transcript anchors it to the thread's last\n * message once that history has loaded (`useHandoffArrival`) and renders the\n * divider after that message (`useHandoffArrivalAfter`). Nothing is sent to\n * Athena or persisted; a reload forgets it.\n *\n * The arrival also carries where the source was reading (`cursor`, a message\n * id): the transcript opens at that message instead of the bottom, then\n * settles it (`settleHandoffArrivalCursor`) so a remount never scrolls again.\n */\nimport { createContext, useContext, useEffect, useSyncExternalStore } from 'react';\nimport { continuedFromLabel, parseHandoffCursor } from './thread-handoff-protocol';\n\nexport interface HandoffArrival {\n  threadId: string;\n  /** \"Continued from your phone\". */\n  label: string;\n  /**\n   * The last message present when the conversation arrived; the divider goes\n   * right after it. `null` until the transcript has anchored it.\n   */\n  afterMessageId: string | null;\n  /**\n   * The message the source was reading, which the transcript opens at. `null`\n   * when the source was at the bottom, or once the transcript settled it.\n   */\n  cursor: string | null;\n}\n\n/** Enough for every conversation one person picks up in a session. */\nexport const MAX_HANDOFF_ARRIVALS = 20;\n\n/**\n * The arrivals live on `globalThis`, not in module scope, because two copies of\n * this module can run in one page: the SDK bundles agent-runtime into its dist\n * while a host (Spaces, the Chrome extension, Midas) imports it directly. The\n * host records through its copy and the SDK transcript reads through its own.\n */\nconst HANDOFF_ARRIVALS = Symbol.for('@athenaintel/agent-runtime/handoff-arrivals');\n\ninterface ArrivalRegistry {\n  arrivals: Map<string, HandoffArrival>;\n  listeners: Set<() => void>;\n}\n\ntype ArrivalRegistryHost = typeof globalThis & { [HANDOFF_ARRIVALS]?: ArrivalRegistry };\n\n// process-local: this client only — what this surface picked up; nothing is persisted\nfunction registry(): ArrivalRegistry {\n  const host = globalThis as ArrivalRegistryHost;\n  return (host[HANDOFF_ARRIVALS] ??= { arrivals: new Map(), listeners: new Set() });\n}\n\nfunction publish(): void {\n  for (const listener of registry().listeners) listener();\n}\n\n/**\n * A pick-up landed `threadId` here from `source` (`mobile`, `chrome`, …),\n * where the source was reading `cursor` (a message id; absent or `null` at the\n * bottom). A second pick-up of the same thread moves the divider to the new\n * arrival and replaces the cursor.\n */\nexport function recordHandoffArrival({\n  threadId,\n  source,\n  cursor,\n}: {\n  threadId: string;\n  source: string;\n  cursor?: string | null;\n}): void {\n  if (!threadId) return;\n  const { arrivals } = registry();\n  arrivals.delete(threadId);\n  arrivals.set(threadId, {\n    threadId,\n    label: continuedFromLabel(source),\n    afterMessageId: null,\n    cursor: parseHandoffCursor(cursor),\n  });\n  while (arrivals.size > MAX_HANDOFF_ARRIVALS) {\n    const oldest = arrivals.keys().next().value;\n    if (oldest === undefined) break;\n    arrivals.delete(oldest);\n  }\n  publish();\n}\n\n/** The arrival recorded for `threadId`, anchored or not. */\nexport function readHandoffArrival(threadId: string | null | undefined): HandoffArrival | null {\n  return (threadId && registry().arrivals.get(threadId)) || null;\n}\n\nexport function subscribeHandoffArrivals(listener: () => void): () => void {\n  const { listeners } = registry();\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** Forgets the arrival of `threadId`: the pick-up never opened the conversation here. */\nexport function clearHandoffArrival(threadId: string): void {\n  if (!registry().arrivals.delete(threadId)) return;\n  publish();\n}\n\n/**\n * The transcript of `threadId` opened at its cursor (or gave up and stayed at\n * the bottom): forget the cursor so a remount never scrolls there again.\n */\nexport function settleHandoffArrivalCursor(threadId: string): void {\n  const { arrivals } = registry();\n  const arrival = arrivals.get(threadId);\n  if (!arrival || arrival.cursor === null) return;\n  arrivals.set(threadId, { ...arrival, cursor: null });\n  publish();\n}\n\n/** Where the transcript of `threadId` should open: the cursor not yet settled, or `null`. */\nexport function useHandoffArrivalCursor(threadId: string | null | undefined): string | null {\n  return useSyncExternalStore(\n    subscribeHandoffArrivals,\n    () => readHandoffArrival(threadId)?.cursor ?? null,\n    () => null\n  );\n}\n\n/** The first anchor wins: later messages are what came after the arrival. */\nexport function anchorHandoffArrival({\n  threadId,\n  afterMessageId,\n}: {\n  threadId: string;\n  afterMessageId: string;\n}): void {\n  const { arrivals } = registry();\n  const arrival = arrivals.get(threadId);\n  if (!arrival || arrival.afterMessageId !== null) return;\n  arrivals.set(threadId, { ...arrival, afterMessageId });\n  publish();\n}\n\n/**\n * The divider for the transcript of `threadId`, once anchored. The transcript\n * passes its last message id and whether its history is still loading; the\n * first time history has loaded with a message in it, the arrival anchors\n * after that message. A thread already on screen anchors at once.\n */\nexport function useHandoffArrival({\n  threadId,\n  lastMessageId,\n  loading,\n}: {\n  threadId: string | null | undefined;\n  lastMessageId: string | null | undefined;\n  loading: boolean;\n}): HandoffArrival | null {\n  const arrival = useSyncExternalStore(\n    subscribeHandoffArrivals,\n    () => readHandoffArrival(threadId),\n    () => null\n  );\n  const unanchored = arrival !== null && arrival.afterMessageId === null;\n  useEffect(() => {\n    if (!threadId || !unanchored || loading || !lastMessageId) return;\n    anchorHandoffArrival({ threadId, afterMessageId: lastMessageId });\n  }, [threadId, unanchored, loading, lastMessageId]);\n  return arrival?.afterMessageId ? arrival : null;\n}\n\n/** The anchored arrival of the transcript being rendered, for its messages. */\nexport const HandoffArrivalContext = createContext<HandoffArrival | null>(null);\n\n/** The divider label when it goes right after `messageId`; `null` otherwise. */\nexport function useHandoffArrivalAfter(messageId: string | null | undefined): string | null {\n  const arrival = useContext(HandoffArrivalContext);\n  return arrival && messageId && arrival.afterMessageId === messageId ? arrival.label : null;\n}\n\nexport function resetHandoffArrivalsForTests(): void {\n  registry().arrivals.clear();\n  publish();\n}\n"],"names":["useSyncExternalStore","useEffect","createContext","useContext"],"mappings":";;;AA2CA,MAAM,mBAAmB,OAAO,IAAI,6CAA6C;AAUjF,SAAS,WAA4B;AACnC,QAAM,OAAO;AACb,SAAQ,oDAA2B,EAAE,UAAU,oBAAI,OAAO,WAAW,oBAAI,MAAI;AAC/E;AAEA,SAAS,UAAgB;AACvB,aAAW,YAAY,WAAW,UAAW,UAAA;AAC/C;AAmCO,SAAS,mBAAmB,UAA4D;AAC7F,SAAQ,YAAY,SAAA,EAAW,SAAS,IAAI,QAAQ,KAAM;AAC5D;AAEO,SAAS,yBAAyB,UAAkC;AACzE,QAAM,EAAE,UAAA,IAAc,SAAA;AACtB,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAYO,SAAS,2BAA2B,UAAwB;AACjE,QAAM,EAAE,SAAA,IAAa,SAAA;AACrB,QAAM,UAAU,SAAS,IAAI,QAAQ;AACrC,MAAI,CAAC,WAAW,QAAQ,WAAW,KAAM;AACzC,WAAS,IAAI,UAAU,EAAE,GAAG,SAAS,QAAQ,MAAM;AACnD,UAAA;AACF;AAGO,SAAS,wBAAwB,UAAoD;AAC1F,SAAOA,WAAAA;AAAAA,IACL;AAAA,IACA,MAAA;;AAAM,uCAAmB,QAAQ,MAA3B,mBAA8B,WAAU;AAAA;AAAA,IAC9C,MAAM;AAAA,EAAA;AAEV;AAGO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAGS;AACP,QAAM,EAAE,SAAA,IAAa,SAAA;AACrB,QAAM,UAAU,SAAS,IAAI,QAAQ;AACrC,MAAI,CAAC,WAAW,QAAQ,mBAAmB,KAAM;AACjD,WAAS,IAAI,UAAU,EAAE,GAAG,SAAS,gBAAgB;AACrD,UAAA;AACF;AAQO,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AACF,GAI0B;AACxB,QAAM,UAAUA,WAAAA;AAAAA,IACd;AAAA,IACA,MAAM,mBAAmB,QAAQ;AAAA,IACjC,MAAM;AAAA,EAAA;AAER,QAAM,aAAa,YAAY,QAAQ,QAAQ,mBAAmB;AAClEC,aAAAA,UAAU,MAAM;AACd,QAAI,CAAC,YAAY,CAAC,cAAc,WAAW,CAAC,cAAe;AAC3D,yBAAqB,EAAE,UAAU,gBAAgB,cAAA,CAAe;AAAA,EAClE,GAAG,CAAC,UAAU,YAAY,SAAS,aAAa,CAAC;AACjD,UAAO,mCAAS,kBAAiB,UAAU;AAC7C;AAGO,MAAM,wBAAwBC,WAAAA,cAAqC,IAAI;AAGvE,SAAS,uBAAuB,WAAqD;AAC1F,QAAM,UAAUC,WAAAA,WAAW,qBAAqB;AAChD,SAAO,WAAW,aAAa,QAAQ,mBAAmB,YAAY,QAAQ,QAAQ;AACxF;;;;;;;;;"}

package/dist/agent-runtime/src/handoff-arrival.d.ts

@@ -7,22 +7,37 @@ export interface HandoffArrival {
      * right after it. `null` until the transcript has anchored it.
      */
     afterMessageId: string | null;
+    /**
+     * The message the source was reading, which the transcript opens at. `null`
+     * when the source was at the bottom, or once the transcript settled it.
+     */
+    cursor: string | null;
 }
 /** Enough for every conversation one person picks up in a session. */
 export declare const MAX_HANDOFF_ARRIVALS = 20;
 /**
- * A pick-up landed `threadId` here from `source` (`mobile`, `chrome`, …). A
- * second pick-up of the same thread moves the divider to the new arrival.
+ * A pick-up landed `threadId` here from `source` (`mobile`, `chrome`, …),
+ * where the source was reading `cursor` (a message id; absent or `null` at the
+ * bottom). A second pick-up of the same thread moves the divider to the new
+ * arrival and replaces the cursor.
  */
-export declare function recordHandoffArrival({ threadId, source, }: {
+export declare function recordHandoffArrival({ threadId, source, cursor, }: {
     threadId: string;
     source: string;
+    cursor?: string | null;
 }): void;
 /** The arrival recorded for `threadId`, anchored or not. */
 export declare function readHandoffArrival(threadId: string | null | undefined): HandoffArrival | null;
 export declare function subscribeHandoffArrivals(listener: () => void): () => void;
 /** Forgets the arrival of `threadId`: the pick-up never opened the conversation here. */
 export declare function clearHandoffArrival(threadId: string): void;
+/**
+ * The transcript of `threadId` opened at its cursor (or gave up and stayed at
+ * the bottom): forget the cursor so a remount never scrolls there again.
+ */
+export declare function settleHandoffArrivalCursor(threadId: string): void;
+/** Where the transcript of `threadId` should open: the cursor not yet settled, or `null`. */
+export declare function useHandoffArrivalCursor(threadId: string | null | undefined): string | null;
 /** The first anchor wins: later messages are what came after the arrival. */
 export declare function anchorHandoffArrival({ threadId, afterMessageId, }: {
     threadId: string;

package/dist/agent-runtime/src/handoff-arrival.js

@@ -17,6 +17,23 @@ function subscribeHandoffArrivals(listener) {
     listeners.delete(listener);
   };
 }
+function settleHandoffArrivalCursor(threadId) {
+  const { arrivals } = registry();
+  const arrival = arrivals.get(threadId);
+  if (!arrival || arrival.cursor === null) return;
+  arrivals.set(threadId, { ...arrival, cursor: null });
+  publish();
+}
+function useHandoffArrivalCursor(threadId) {
+  return useSyncExternalStore(
+    subscribeHandoffArrivals,
+    () => {
+      var _a;
+      return ((_a = readHandoffArrival(threadId)) == null ? void 0 : _a.cursor) ?? null;
+    },
+    () => null
+  );
+}
 function anchorHandoffArrival({
   threadId,
   afterMessageId
@@ -53,8 +70,10 @@ export {
   HandoffArrivalContext,
   anchorHandoffArrival,
   readHandoffArrival,
+  settleHandoffArrivalCursor,
   subscribeHandoffArrivals,
   useHandoffArrival,
-  useHandoffArrivalAfter
+  useHandoffArrivalAfter,
+  useHandoffArrivalCursor
 };
 //# sourceMappingURL=handoff-arrival.js.map

package/dist/agent-runtime/src/handoff-arrival.js.map

@@ -1 +1 @@
-{"version":3,"file":"handoff-arrival.js","sources":["../../../../agent-runtime/src/handoff-arrival.ts"],"sourcesContent":["/**\n * Where a handed-off conversation arrived on this surface: a transcript divider\n * (\"Continued from your phone\") after the last message that was already there\n * when the person picked it up.\n *\n * Ephemeral and client-side. A host records an arrival when its pick-up lands\n * (`recordHandoffArrival`); its transcript anchors it to the thread's last\n * message once that history has loaded (`useHandoffArrival`) and renders the\n * divider after that message (`useHandoffArrivalAfter`). Nothing is sent to\n * Athena or persisted; a reload forgets it.\n */\nimport { createContext, useContext, useEffect, useSyncExternalStore } from 'react';\nimport { continuedFromLabel } from './thread-handoff-protocol';\n\nexport interface HandoffArrival {\n  threadId: string;\n  /** \"Continued from your phone\". */\n  label: string;\n  /**\n   * The last message present when the conversation arrived; the divider goes\n   * right after it. `null` until the transcript has anchored it.\n   */\n  afterMessageId: string | null;\n}\n\n/** Enough for every conversation one person picks up in a session. */\nexport const MAX_HANDOFF_ARRIVALS = 20;\n\n/**\n * The arrivals live on `globalThis`, not in module scope, because two copies of\n * this module can run in one page: the SDK bundles agent-runtime into its dist\n * while a host (Spaces, the Chrome extension, Midas) imports it directly. The\n * host records through its copy and the SDK transcript reads through its own.\n */\nconst HANDOFF_ARRIVALS = Symbol.for('@athenaintel/agent-runtime/handoff-arrivals');\n\ninterface ArrivalRegistry {\n  arrivals: Map<string, HandoffArrival>;\n  listeners: Set<() => void>;\n}\n\ntype ArrivalRegistryHost = typeof globalThis & { [HANDOFF_ARRIVALS]?: ArrivalRegistry };\n\n// process-local: this client only — what this surface picked up; nothing is persisted\nfunction registry(): ArrivalRegistry {\n  const host = globalThis as ArrivalRegistryHost;\n  return (host[HANDOFF_ARRIVALS] ??= { arrivals: new Map(), listeners: new Set() });\n}\n\nfunction publish(): void {\n  for (const listener of registry().listeners) listener();\n}\n\n/**\n * A pick-up landed `threadId` here from `source` (`mobile`, `chrome`, …). A\n * second pick-up of the same thread moves the divider to the new arrival.\n */\nexport function recordHandoffArrival({\n  threadId,\n  source,\n}: {\n  threadId: string;\n  source: string;\n}): void {\n  if (!threadId) return;\n  const { arrivals } = registry();\n  arrivals.delete(threadId);\n  arrivals.set(threadId, { threadId, label: continuedFromLabel(source), afterMessageId: null });\n  while (arrivals.size > MAX_HANDOFF_ARRIVALS) {\n    const oldest = arrivals.keys().next().value;\n    if (oldest === undefined) break;\n    arrivals.delete(oldest);\n  }\n  publish();\n}\n\n/** The arrival recorded for `threadId`, anchored or not. */\nexport function readHandoffArrival(threadId: string | null | undefined): HandoffArrival | null {\n  return (threadId && registry().arrivals.get(threadId)) || null;\n}\n\nexport function subscribeHandoffArrivals(listener: () => void): () => void {\n  const { listeners } = registry();\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** Forgets the arrival of `threadId`: the pick-up never opened the conversation here. */\nexport function clearHandoffArrival(threadId: string): void {\n  if (!registry().arrivals.delete(threadId)) return;\n  publish();\n}\n\n/** The first anchor wins: later messages are what came after the arrival. */\nexport function anchorHandoffArrival({\n  threadId,\n  afterMessageId,\n}: {\n  threadId: string;\n  afterMessageId: string;\n}): void {\n  const { arrivals } = registry();\n  const arrival = arrivals.get(threadId);\n  if (!arrival || arrival.afterMessageId !== null) return;\n  arrivals.set(threadId, { ...arrival, afterMessageId });\n  publish();\n}\n\n/**\n * The divider for the transcript of `threadId`, once anchored. The transcript\n * passes its last message id and whether its history is still loading; the\n * first time history has loaded with a message in it, the arrival anchors\n * after that message. A thread already on screen anchors at once.\n */\nexport function useHandoffArrival({\n  threadId,\n  lastMessageId,\n  loading,\n}: {\n  threadId: string | null | undefined;\n  lastMessageId: string | null | undefined;\n  loading: boolean;\n}): HandoffArrival | null {\n  const arrival = useSyncExternalStore(\n    subscribeHandoffArrivals,\n    () => readHandoffArrival(threadId),\n    () => null\n  );\n  const unanchored = arrival !== null && arrival.afterMessageId === null;\n  useEffect(() => {\n    if (!threadId || !unanchored || loading || !lastMessageId) return;\n    anchorHandoffArrival({ threadId, afterMessageId: lastMessageId });\n  }, [threadId, unanchored, loading, lastMessageId]);\n  return arrival?.afterMessageId ? arrival : null;\n}\n\n/** The anchored arrival of the transcript being rendered, for its messages. */\nexport const HandoffArrivalContext = createContext<HandoffArrival | null>(null);\n\n/** The divider label when it goes right after `messageId`; `null` otherwise. */\nexport function useHandoffArrivalAfter(messageId: string | null | undefined): string | null {\n  const arrival = useContext(HandoffArrivalContext);\n  return arrival && messageId && arrival.afterMessageId === messageId ? arrival.label : null;\n}\n\nexport function resetHandoffArrivalsForTests(): void {\n  registry().arrivals.clear();\n  publish();\n}\n"],"names":[],"mappings":";AAkCA,MAAM,mBAAmB,OAAO,IAAI,6CAA6C;AAUjF,SAAS,WAA4B;AACnC,QAAM,OAAO;AACb,SAAQ,oDAA2B,EAAE,UAAU,oBAAI,OAAO,WAAW,oBAAI,MAAI;AAC/E;AAEA,SAAS,UAAgB;AACvB,aAAW,YAAY,WAAW,UAAW,UAAA;AAC/C;AA0BO,SAAS,mBAAmB,UAA4D;AAC7F,SAAQ,YAAY,SAAA,EAAW,SAAS,IAAI,QAAQ,KAAM;AAC5D;AAEO,SAAS,yBAAyB,UAAkC;AACzE,QAAM,EAAE,UAAA,IAAc,SAAA;AACtB,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AASO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAGS;AACP,QAAM,EAAE,SAAA,IAAa,SAAA;AACrB,QAAM,UAAU,SAAS,IAAI,QAAQ;AACrC,MAAI,CAAC,WAAW,QAAQ,mBAAmB,KAAM;AACjD,WAAS,IAAI,UAAU,EAAE,GAAG,SAAS,gBAAgB;AACrD,UAAA;AACF;AAQO,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AACF,GAI0B;AACxB,QAAM,UAAU;AAAA,IACd;AAAA,IACA,MAAM,mBAAmB,QAAQ;AAAA,IACjC,MAAM;AAAA,EAAA;AAER,QAAM,aAAa,YAAY,QAAQ,QAAQ,mBAAmB;AAClE,YAAU,MAAM;AACd,QAAI,CAAC,YAAY,CAAC,cAAc,WAAW,CAAC,cAAe;AAC3D,yBAAqB,EAAE,UAAU,gBAAgB,cAAA,CAAe;AAAA,EAClE,GAAG,CAAC,UAAU,YAAY,SAAS,aAAa,CAAC;AACjD,UAAO,mCAAS,kBAAiB,UAAU;AAC7C;AAGO,MAAM,wBAAwB,cAAqC,IAAI;AAGvE,SAAS,uBAAuB,WAAqD;AAC1F,QAAM,UAAU,WAAW,qBAAqB;AAChD,SAAO,WAAW,aAAa,QAAQ,mBAAmB,YAAY,QAAQ,QAAQ;AACxF;"}
+{"version":3,"file":"handoff-arrival.js","sources":["../../../../agent-runtime/src/handoff-arrival.ts"],"sourcesContent":["/**\n * Where a handed-off conversation arrived on this surface: a transcript divider\n * (\"Continued from your phone\") after the last message that was already there\n * when the person picked it up.\n *\n * Ephemeral and client-side. A host records an arrival when its pick-up lands\n * (`recordHandoffArrival`); its transcript anchors it to the thread's last\n * message once that history has loaded (`useHandoffArrival`) and renders the\n * divider after that message (`useHandoffArrivalAfter`). Nothing is sent to\n * Athena or persisted; a reload forgets it.\n *\n * The arrival also carries where the source was reading (`cursor`, a message\n * id): the transcript opens at that message instead of the bottom, then\n * settles it (`settleHandoffArrivalCursor`) so a remount never scrolls again.\n */\nimport { createContext, useContext, useEffect, useSyncExternalStore } from 'react';\nimport { continuedFromLabel, parseHandoffCursor } from './thread-handoff-protocol';\n\nexport interface HandoffArrival {\n  threadId: string;\n  /** \"Continued from your phone\". */\n  label: string;\n  /**\n   * The last message present when the conversation arrived; the divider goes\n   * right after it. `null` until the transcript has anchored it.\n   */\n  afterMessageId: string | null;\n  /**\n   * The message the source was reading, which the transcript opens at. `null`\n   * when the source was at the bottom, or once the transcript settled it.\n   */\n  cursor: string | null;\n}\n\n/** Enough for every conversation one person picks up in a session. */\nexport const MAX_HANDOFF_ARRIVALS = 20;\n\n/**\n * The arrivals live on `globalThis`, not in module scope, because two copies of\n * this module can run in one page: the SDK bundles agent-runtime into its dist\n * while a host (Spaces, the Chrome extension, Midas) imports it directly. The\n * host records through its copy and the SDK transcript reads through its own.\n */\nconst HANDOFF_ARRIVALS = Symbol.for('@athenaintel/agent-runtime/handoff-arrivals');\n\ninterface ArrivalRegistry {\n  arrivals: Map<string, HandoffArrival>;\n  listeners: Set<() => void>;\n}\n\ntype ArrivalRegistryHost = typeof globalThis & { [HANDOFF_ARRIVALS]?: ArrivalRegistry };\n\n// process-local: this client only — what this surface picked up; nothing is persisted\nfunction registry(): ArrivalRegistry {\n  const host = globalThis as ArrivalRegistryHost;\n  return (host[HANDOFF_ARRIVALS] ??= { arrivals: new Map(), listeners: new Set() });\n}\n\nfunction publish(): void {\n  for (const listener of registry().listeners) listener();\n}\n\n/**\n * A pick-up landed `threadId` here from `source` (`mobile`, `chrome`, …),\n * where the source was reading `cursor` (a message id; absent or `null` at the\n * bottom). A second pick-up of the same thread moves the divider to the new\n * arrival and replaces the cursor.\n */\nexport function recordHandoffArrival({\n  threadId,\n  source,\n  cursor,\n}: {\n  threadId: string;\n  source: string;\n  cursor?: string | null;\n}): void {\n  if (!threadId) return;\n  const { arrivals } = registry();\n  arrivals.delete(threadId);\n  arrivals.set(threadId, {\n    threadId,\n    label: continuedFromLabel(source),\n    afterMessageId: null,\n    cursor: parseHandoffCursor(cursor),\n  });\n  while (arrivals.size > MAX_HANDOFF_ARRIVALS) {\n    const oldest = arrivals.keys().next().value;\n    if (oldest === undefined) break;\n    arrivals.delete(oldest);\n  }\n  publish();\n}\n\n/** The arrival recorded for `threadId`, anchored or not. */\nexport function readHandoffArrival(threadId: string | null | undefined): HandoffArrival | null {\n  return (threadId && registry().arrivals.get(threadId)) || null;\n}\n\nexport function subscribeHandoffArrivals(listener: () => void): () => void {\n  const { listeners } = registry();\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** Forgets the arrival of `threadId`: the pick-up never opened the conversation here. */\nexport function clearHandoffArrival(threadId: string): void {\n  if (!registry().arrivals.delete(threadId)) return;\n  publish();\n}\n\n/**\n * The transcript of `threadId` opened at its cursor (or gave up and stayed at\n * the bottom): forget the cursor so a remount never scrolls there again.\n */\nexport function settleHandoffArrivalCursor(threadId: string): void {\n  const { arrivals } = registry();\n  const arrival = arrivals.get(threadId);\n  if (!arrival || arrival.cursor === null) return;\n  arrivals.set(threadId, { ...arrival, cursor: null });\n  publish();\n}\n\n/** Where the transcript of `threadId` should open: the cursor not yet settled, or `null`. */\nexport function useHandoffArrivalCursor(threadId: string | null | undefined): string | null {\n  return useSyncExternalStore(\n    subscribeHandoffArrivals,\n    () => readHandoffArrival(threadId)?.cursor ?? null,\n    () => null\n  );\n}\n\n/** The first anchor wins: later messages are what came after the arrival. */\nexport function anchorHandoffArrival({\n  threadId,\n  afterMessageId,\n}: {\n  threadId: string;\n  afterMessageId: string;\n}): void {\n  const { arrivals } = registry();\n  const arrival = arrivals.get(threadId);\n  if (!arrival || arrival.afterMessageId !== null) return;\n  arrivals.set(threadId, { ...arrival, afterMessageId });\n  publish();\n}\n\n/**\n * The divider for the transcript of `threadId`, once anchored. The transcript\n * passes its last message id and whether its history is still loading; the\n * first time history has loaded with a message in it, the arrival anchors\n * after that message. A thread already on screen anchors at once.\n */\nexport function useHandoffArrival({\n  threadId,\n  lastMessageId,\n  loading,\n}: {\n  threadId: string | null | undefined;\n  lastMessageId: string | null | undefined;\n  loading: boolean;\n}): HandoffArrival | null {\n  const arrival = useSyncExternalStore(\n    subscribeHandoffArrivals,\n    () => readHandoffArrival(threadId),\n    () => null\n  );\n  const unanchored = arrival !== null && arrival.afterMessageId === null;\n  useEffect(() => {\n    if (!threadId || !unanchored || loading || !lastMessageId) return;\n    anchorHandoffArrival({ threadId, afterMessageId: lastMessageId });\n  }, [threadId, unanchored, loading, lastMessageId]);\n  return arrival?.afterMessageId ? arrival : null;\n}\n\n/** The anchored arrival of the transcript being rendered, for its messages. */\nexport const HandoffArrivalContext = createContext<HandoffArrival | null>(null);\n\n/** The divider label when it goes right after `messageId`; `null` otherwise. */\nexport function useHandoffArrivalAfter(messageId: string | null | undefined): string | null {\n  const arrival = useContext(HandoffArrivalContext);\n  return arrival && messageId && arrival.afterMessageId === messageId ? arrival.label : null;\n}\n\nexport function resetHandoffArrivalsForTests(): void {\n  registry().arrivals.clear();\n  publish();\n}\n"],"names":[],"mappings":";AA2CA,MAAM,mBAAmB,OAAO,IAAI,6CAA6C;AAUjF,SAAS,WAA4B;AACnC,QAAM,OAAO;AACb,SAAQ,oDAA2B,EAAE,UAAU,oBAAI,OAAO,WAAW,oBAAI,MAAI;AAC/E;AAEA,SAAS,UAAgB;AACvB,aAAW,YAAY,WAAW,UAAW,UAAA;AAC/C;AAmCO,SAAS,mBAAmB,UAA4D;AAC7F,SAAQ,YAAY,SAAA,EAAW,SAAS,IAAI,QAAQ,KAAM;AAC5D;AAEO,SAAS,yBAAyB,UAAkC;AACzE,QAAM,EAAE,UAAA,IAAc,SAAA;AACtB,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAYO,SAAS,2BAA2B,UAAwB;AACjE,QAAM,EAAE,SAAA,IAAa,SAAA;AACrB,QAAM,UAAU,SAAS,IAAI,QAAQ;AACrC,MAAI,CAAC,WAAW,QAAQ,WAAW,KAAM;AACzC,WAAS,IAAI,UAAU,EAAE,GAAG,SAAS,QAAQ,MAAM;AACnD,UAAA;AACF;AAGO,SAAS,wBAAwB,UAAoD;AAC1F,SAAO;AAAA,IACL;AAAA,IACA,MAAA;;AAAM,uCAAmB,QAAQ,MAA3B,mBAA8B,WAAU;AAAA;AAAA,IAC9C,MAAM;AAAA,EAAA;AAEV;AAGO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAGS;AACP,QAAM,EAAE,SAAA,IAAa,SAAA;AACrB,QAAM,UAAU,SAAS,IAAI,QAAQ;AACrC,MAAI,CAAC,WAAW,QAAQ,mBAAmB,KAAM;AACjD,WAAS,IAAI,UAAU,EAAE,GAAG,SAAS,gBAAgB;AACrD,UAAA;AACF;AAQO,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AACF,GAI0B;AACxB,QAAM,UAAU;AAAA,IACd;AAAA,IACA,MAAM,mBAAmB,QAAQ;AAAA,IACjC,MAAM;AAAA,EAAA;AAER,QAAM,aAAa,YAAY,QAAQ,QAAQ,mBAAmB;AAClE,YAAU,MAAM;AACd,QAAI,CAAC,YAAY,CAAC,cAAc,WAAW,CAAC,cAAe;AAC3D,yBAAqB,EAAE,UAAU,gBAAgB,cAAA,CAAe;AAAA,EAClE,GAAG,CAAC,UAAU,YAAY,SAAS,aAAa,CAAC;AACjD,UAAO,mCAAS,kBAAiB,UAAU;AAC7C;AAGO,MAAM,wBAAwB,cAAqC,IAAI;AAGvE,SAAS,uBAAuB,WAAqD;AAC1F,QAAM,UAAU,WAAW,qBAAqB;AAChD,SAAO,WAAW,aAAa,QAAQ,mBAAmB,YAAY,QAAQ,QAAQ;AACxF;"}

package/dist/agent-runtime/src/handoff-cursor-id.cjs

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const HANDOFF_CURSOR_PATTERN = /^[A-Za-z0-9._:-]{1,256}$/;
+const parseHandoffCursor = (value) => value && HANDOFF_CURSOR_PATTERN.test(value) ? value : null;
+exports.parseHandoffCursor = parseHandoffCursor;
+//# sourceMappingURL=handoff-cursor-id.cjs.map

package/dist/agent-runtime/src/handoff-cursor-id.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-cursor-id.cjs","sources":["../../../../agent-runtime/src/handoff-cursor-id.ts"],"sourcesContent":["/**\n * A handover's reading position: the id of the last message the source's\n * transcript showed (see `handoff-cursor`). An opaque id from the person's own\n * thread, never content; agora accepts this shape only.\n *\n * Kept free of zod (unlike `thread-handoff-protocol`, which re-exports it): the\n * React SDK bundles `handoff-cursor`, and a bundled zod would land under the\n * SDK's `dist/node_modules`, which npm never packs.\n */\nexport const MAX_HANDOFF_CURSOR_LENGTH = 256;\nconst HANDOFF_CURSOR_PATTERN = /^[A-Za-z0-9._:-]{1,256}$/;\n\n/** A message id a handover can carry as its reading position, or `null`. */\nexport const parseHandoffCursor = (value: string | null | undefined): string | null =>\n  value && HANDOFF_CURSOR_PATTERN.test(value) ? value : null;\n"],"names":[],"mappings":";;AAUA,MAAM,yBAAyB;AAGxB,MAAM,qBAAqB,CAAC,UACjC,SAAS,uBAAuB,KAAK,KAAK,IAAI,QAAQ;;"}

package/dist/agent-runtime/src/handoff-cursor-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A handover's reading position: the id of the last message the source's
+ * transcript showed (see `handoff-cursor`). An opaque id from the person's own
+ * thread, never content; agora accepts this shape only.
+ *
+ * Kept free of zod (unlike `thread-handoff-protocol`, which re-exports it): the
+ * React SDK bundles `handoff-cursor`, and a bundled zod would land under the
+ * SDK's `dist/node_modules`, which npm never packs.
+ */
+export declare const MAX_HANDOFF_CURSOR_LENGTH = 256;
+/** A message id a handover can carry as its reading position, or `null`. */
+export declare const parseHandoffCursor: (value: string | null | undefined) => string | null;

package/dist/agent-runtime/src/handoff-cursor-id.js

@@ -0,0 +1,6 @@
+const HANDOFF_CURSOR_PATTERN = /^[A-Za-z0-9._:-]{1,256}$/;
+const parseHandoffCursor = (value) => value && HANDOFF_CURSOR_PATTERN.test(value) ? value : null;
+export {
+  parseHandoffCursor
+};
+//# sourceMappingURL=handoff-cursor-id.js.map

package/dist/agent-runtime/src/handoff-cursor-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-cursor-id.js","sources":["../../../../agent-runtime/src/handoff-cursor-id.ts"],"sourcesContent":["/**\n * A handover's reading position: the id of the last message the source's\n * transcript showed (see `handoff-cursor`). An opaque id from the person's own\n * thread, never content; agora accepts this shape only.\n *\n * Kept free of zod (unlike `thread-handoff-protocol`, which re-exports it): the\n * React SDK bundles `handoff-cursor`, and a bundled zod would land under the\n * SDK's `dist/node_modules`, which npm never packs.\n */\nexport const MAX_HANDOFF_CURSOR_LENGTH = 256;\nconst HANDOFF_CURSOR_PATTERN = /^[A-Za-z0-9._:-]{1,256}$/;\n\n/** A message id a handover can carry as its reading position, or `null`. */\nexport const parseHandoffCursor = (value: string | null | undefined): string | null =>\n  value && HANDOFF_CURSOR_PATTERN.test(value) ? value : null;\n"],"names":[],"mappings":"AAUA,MAAM,yBAAyB;AAGxB,MAAM,qBAAqB,CAAC,UACjC,SAAS,uBAAuB,KAAK,KAAK,IAAI,QAAQ;"}

package/dist/agent-runtime/src/handoff-cursor.cjs

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const core = require("@assistant-ui/core");
+const handoffCursorId = require("./handoff-cursor-id.cjs");
+const READING_CURSOR_BOTTOM_TOLERANCE_PX = 48;
+const READING_LINE_FRACTION = 1 / 3;
+function readingCursorFromRows({
+  top,
+  bottom,
+  rows
+}) {
+  var _a;
+  const line = top + (bottom - top) * READING_LINE_FRACTION;
+  let lastFull = null;
+  let atLine = null;
+  for (const row of rows) {
+    if (row.bottom <= row.top) continue;
+    if (row.top >= top - 1 && row.bottom <= bottom + 1) lastFull = row;
+    if (row.top <= line && row.bottom > line) atLine = row;
+  }
+  return handoffCursorId.parseHandoffCursor((_a = lastFull ?? atLine) == null ? void 0 : _a.id);
+}
+const MESSAGE_ROW_ID_ATTRIBUTE = "data-message-id";
+function readingCursorOf({
+  viewport,
+  coveredBottomPx = 0,
+  idAttribute = MESSAGE_ROW_ID_ATTRIBUTE
+}) {
+  const fromBottom = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;
+  if (fromBottom <= READING_CURSOR_BOTTOM_TOLERANCE_PX) return null;
+  const box = viewport.getBoundingClientRect();
+  const rows = Array.from(viewport.querySelectorAll(`[${idAttribute}]`), (row) => {
+    const rect = row.getBoundingClientRect();
+    return { id: row.getAttribute(idAttribute) ?? "", top: rect.top, bottom: rect.bottom };
+  });
+  return readingCursorFromRows({
+    top: box.top,
+    bottom: Math.max(box.top, box.bottom - coveredBottomPx),
+    rows
+  });
+}
+function handoffCursorMessageId({
+  messages,
+  cursor
+}) {
+  for (const message of messages) {
+    if (message.id === cursor) return message.id;
+  }
+  for (const message of messages) {
+    const sources = core.getExternalStoreMessages(message);
+    if (!Array.isArray(sources)) continue;
+    for (const source of sources) {
+      if (source && typeof source === "object" && source.id === cursor) {
+        return message.id;
+      }
+    }
+  }
+  return null;
+}
+const HANDOFF_CURSOR_MAX_HISTORY_PAGES = 20;
+const HANDOFF_CURSOR_WAIT_MS = 3e4;
+const HANDOFF_CURSOR_HIGHLIGHT_MS = 2400;
+const HANDOFF_CURSOR_SETTLE_MS = 1500;
+function handoffCursorRevealStep({
+  found,
+  loading,
+  hasOlder,
+  pagesLoaded,
+  elapsedMs
+}) {
+  if (found) return "reveal";
+  if (elapsedMs >= HANDOFF_CURSOR_WAIT_MS) return "bottom";
+  if (loading || hasOlder === null) return "wait";
+  if (hasOlder && pagesLoaded < HANDOFF_CURSOR_MAX_HISTORY_PAGES) return "page";
+  return "bottom";
+}
+exports.HANDOFF_CURSOR_HIGHLIGHT_MS = HANDOFF_CURSOR_HIGHLIGHT_MS;
+exports.HANDOFF_CURSOR_MAX_HISTORY_PAGES = HANDOFF_CURSOR_MAX_HISTORY_PAGES;
+exports.HANDOFF_CURSOR_SETTLE_MS = HANDOFF_CURSOR_SETTLE_MS;
+exports.HANDOFF_CURSOR_WAIT_MS = HANDOFF_CURSOR_WAIT_MS;
+exports.MESSAGE_ROW_ID_ATTRIBUTE = MESSAGE_ROW_ID_ATTRIBUTE;
+exports.READING_CURSOR_BOTTOM_TOLERANCE_PX = READING_CURSOR_BOTTOM_TOLERANCE_PX;
+exports.READING_LINE_FRACTION = READING_LINE_FRACTION;
+exports.handoffCursorMessageId = handoffCursorMessageId;
+exports.handoffCursorRevealStep = handoffCursorRevealStep;
+exports.readingCursorFromRows = readingCursorFromRows;
+exports.readingCursorOf = readingCursorOf;
+//# sourceMappingURL=handoff-cursor.cjs.map

package/dist/agent-runtime/src/handoff-cursor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-cursor.cjs","sources":["../../../../agent-runtime/src/handoff-cursor.ts"],"sourcesContent":["/**\n * Where a handed-off conversation opens: at the message the source was\n * reading (\"the view at the last message the source showed\"), not just at the\n * bottom.\n *\n * The source reads its own transcript when the person issues the handover\n * (`readingCursorOf` on the web, the visible rows on the phone): `null` when\n * it was at the bottom, else the id of the last message fully in view or,\n * when one long message fills the view, the message at the reading line. The\n * id travels as the handover's `cursor` (an opaque id from the person's own\n * thread, never content). The destination records it with the arrival\n * (`recordHandoffArrival({ cursor })`) and its transcript reveals that message\n * once it has it, paging older history in when needed\n * (`handoffCursorRevealStep`), and highlights it briefly. A cursor it can't\n * find leaves the view at the bottom, as before: it is a hint, never a wait.\n */\nimport { getExternalStoreMessages, type ThreadMessage } from '@assistant-ui/core';\nimport { parseHandoffCursor } from './handoff-cursor-id';\n\n/** Whether older history is left to page in (`null` until the window is known). */\nexport { deepAgentHistoryHasOlder } from './edit-command';\n\n/** How far from the bottom still counts as \"at the bottom\": no cursor is sent. */\nexport const READING_CURSOR_BOTTOM_TOLERANCE_PX = 48;\n/** The reading line, as a fraction of the visible height from its top. */\nexport const READING_LINE_FRACTION = 1 / 3;\n\n/** One rendered message row, in the viewport's coordinates. */\nexport interface ReadingRow {\n  id: string;\n  top: number;\n  bottom: number;\n}\n\n/**\n * The reading position among `rows` (in document order) visible between `top`\n * and `bottom`: the last row fully inside, else the row across the reading\n * line (a message taller than the view). `null` when neither is a message id.\n */\nexport function readingCursorFromRows({\n  top,\n  bottom,\n  rows,\n}: {\n  top: number;\n  bottom: number;\n  rows: readonly ReadingRow[];\n}): string | null {\n  const line = top + (bottom - top) * READING_LINE_FRACTION;\n  let lastFull: ReadingRow | null = null;\n  let atLine: ReadingRow | null = null;\n  for (const row of rows) {\n    if (row.bottom <= row.top) continue;\n    if (row.top >= top - 1 && row.bottom <= bottom + 1) lastFull = row;\n    if (row.top <= line && row.bottom > line) atLine = row;\n  }\n  return parseHandoffCursor((lastFull ?? atLine)?.id);\n}\n\n/**\n * The reading position of a list that reports which rows are visible, in\n * order and partly visible ones included, but not where they sit (a native\n * list's viewability). Only the first and last visible rows can be cut off,\n * so with three or more the last fully visible one is the one before the\n * last; with fewer, the first (the one across the reading line, as far as the\n * list can tell). Callers check \"at the bottom\" themselves.\n */\nexport function readingCursorFromVisibleIds(ids: readonly string[]): string | null {\n  return parseHandoffCursor(ids.length >= 3 ? ids[ids.length - 2] : ids[0]);\n}\n\ninterface BoxLike {\n  getBoundingClientRect(): { top: number; bottom: number };\n}\n\ninterface RowLike extends BoxLike {\n  getAttribute(name: string): string | null;\n}\n\n/** The scroll container of a web transcript (structural, so Core needs no DOM types). */\nexport interface ReadingViewportLike extends BoxLike {\n  scrollTop: number;\n  scrollHeight: number;\n  clientHeight: number;\n  querySelectorAll(selectors: string): ArrayLike<RowLike>;\n}\n\n/** assistant-ui stamps every message row with its id. */\nexport const MESSAGE_ROW_ID_ATTRIBUTE = 'data-message-id';\n\n/**\n * Where a web transcript is being read: `null` at the bottom, else the message\n * id `readingCursorFromRows` picks. `coveredBottomPx` is what a sticky footer\n * (the composer) hides at the bottom of the viewport.\n */\nexport function readingCursorOf({\n  viewport,\n  coveredBottomPx = 0,\n  idAttribute = MESSAGE_ROW_ID_ATTRIBUTE,\n}: {\n  viewport: ReadingViewportLike;\n  coveredBottomPx?: number;\n  idAttribute?: string;\n}): string | null {\n  const fromBottom = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;\n  if (fromBottom <= READING_CURSOR_BOTTOM_TOLERANCE_PX) return null;\n  const box = viewport.getBoundingClientRect();\n  const rows: ReadingRow[] = Array.from(viewport.querySelectorAll(`[${idAttribute}]`), (row) => {\n    const rect = row.getBoundingClientRect();\n    return { id: row.getAttribute(idAttribute) ?? '', top: rect.top, bottom: rect.bottom };\n  });\n  return readingCursorFromRows({\n    top: box.top,\n    bottom: Math.max(box.top, box.bottom - coveredBottomPx),\n    rows,\n  });\n}\n\n/**\n * The id of the displayed message that holds `cursor`. A displayed message is\n * one agent turn whose id is its first wire message's, and that id changes\n * when an older page folds into it, so the cursor is matched against every\n * wire message behind each row as well.\n */\nexport function handoffCursorMessageId({\n  messages,\n  cursor,\n}: {\n  messages: readonly ThreadMessage[];\n  cursor: string;\n}): string | null {\n  for (const message of messages) {\n    if (message.id === cursor) return message.id;\n  }\n  for (const message of messages) {\n    const sources: unknown = getExternalStoreMessages(message);\n    if (!Array.isArray(sources)) continue;\n    for (const source of sources) {\n      if (source && typeof source === 'object' && (source as { id?: unknown }).id === cursor) {\n        return message.id;\n      }\n    }\n  }\n  return null;\n}\n\n/** Pages of older history one landing may load looking for its message. */\nexport const HANDOFF_CURSOR_MAX_HISTORY_PAGES = 20;\n/**\n * How long a landing waits without progress before staying at the bottom: a\n * transcript still attaching, or a page of older history that never lands.\n * Each page that lands starts the wait again, so a long conversation on a slow\n * connection still reaches its message within the page budget.\n */\nexport const HANDOFF_CURSOR_WAIT_MS = 30_000;\n/** How long the revealed message stays highlighted. */\nexport const HANDOFF_CURSOR_HIGHLIGHT_MS = 2_400;\n/**\n * How long the revealed message is held in view while the transcript settles\n * (an attaching thread can still scroll itself to the bottom). Any scroll the\n * person makes ends it at once.\n */\nexport const HANDOFF_CURSOR_SETTLE_MS = 1_500;\n\nexport type HandoffCursorRevealStep = 'reveal' | 'wait' | 'page' | 'bottom';\n\n/**\n * What a destination does next while opening at a cursor: `reveal` the message\n * it found; `wait` while the transcript (or a page it asked for) is loading or\n * whether older history exists is not known yet (`hasOlder: null`: a cached\n * transcript shows before its history window resolves); `page` older history\n * in while some is left and the budget allows; else stay at the `bottom`, the\n * fallback for a cursor that can't be found.\n */\nexport function handoffCursorRevealStep({\n  found,\n  loading,\n  hasOlder,\n  pagesLoaded,\n  elapsedMs,\n}: {\n  found: boolean;\n  loading: boolean;\n  hasOlder: boolean | null;\n  pagesLoaded: number;\n  /** Since the landing last made progress: it started, or a page of older history landed. */\n  elapsedMs: number;\n}): HandoffCursorRevealStep {\n  if (found) return 'reveal';\n  if (elapsedMs >= HANDOFF_CURSOR_WAIT_MS) return 'bottom';\n  if (loading || hasOlder === null) return 'wait';\n  if (hasOlder && pagesLoaded < HANDOFF_CURSOR_MAX_HISTORY_PAGES) return 'page';\n  return 'bottom';\n}\n"],"names":["parseHandoffCursor","getExternalStoreMessages"],"mappings":";;;;AAuBO,MAAM,qCAAqC;AAE3C,MAAM,wBAAwB,IAAI;AAclC,SAAS,sBAAsB;AAAA,EACpC;AAAA,EACA;AAAA,EACA;AACF,GAIkB;;AAChB,QAAM,OAAO,OAAO,SAAS,OAAO;AACpC,MAAI,WAA8B;AAClC,MAAI,SAA4B;AAChC,aAAW,OAAO,MAAM;AACtB,QAAI,IAAI,UAAU,IAAI,IAAK;AAC3B,QAAI,IAAI,OAAO,MAAM,KAAK,IAAI,UAAU,SAAS,EAAG,YAAW;AAC/D,QAAI,IAAI,OAAO,QAAQ,IAAI,SAAS,KAAM,UAAS;AAAA,EACrD;AACA,SAAOA,oCAAoB,iBAAY,WAAZ,mBAAqB,EAAE;AACpD;AA+BO,MAAM,2BAA2B;AAOjC,SAAS,gBAAgB;AAAA,EAC9B;AAAA,EACA,kBAAkB;AAAA,EAClB,cAAc;AAChB,GAIkB;AAChB,QAAM,aAAa,SAAS,eAAe,SAAS,YAAY,SAAS;AACzE,MAAI,cAAc,mCAAoC,QAAO;AAC7D,QAAM,MAAM,SAAS,sBAAA;AACrB,QAAM,OAAqB,MAAM,KAAK,SAAS,iBAAiB,IAAI,WAAW,GAAG,GAAG,CAAC,QAAQ;AAC5F,UAAM,OAAO,IAAI,sBAAA;AACjB,WAAO,EAAE,IAAI,IAAI,aAAa,WAAW,KAAK,IAAI,KAAK,KAAK,KAAK,QAAQ,KAAK,OAAA;AAAA,EAChF,CAAC;AACD,SAAO,sBAAsB;AAAA,IAC3B,KAAK,IAAI;AAAA,IACT,QAAQ,KAAK,IAAI,IAAI,KAAK,IAAI,SAAS,eAAe;AAAA,IACtD;AAAA,EAAA,CACD;AACH;AAQO,SAAS,uBAAuB;AAAA,EACrC;AAAA,EACA;AACF,GAGkB;AAChB,aAAW,WAAW,UAAU;AAC9B,QAAI,QAAQ,OAAO,OAAQ,QAAO,QAAQ;AAAA,EAC5C;AACA,aAAW,WAAW,UAAU;AAC9B,UAAM,UAAmBC,KAAAA,yBAAyB,OAAO;AACzD,QAAI,CAAC,MAAM,QAAQ,OAAO,EAAG;AAC7B,eAAW,UAAU,SAAS;AAC5B,UAAI,UAAU,OAAO,WAAW,YAAa,OAA4B,OAAO,QAAQ;AACtF,eAAO,QAAQ;AAAA,MACjB;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAGO,MAAM,mCAAmC;AAOzC,MAAM,yBAAyB;AAE/B,MAAM,8BAA8B;AAMpC,MAAM,2BAA2B;AAYjC,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAO4B;AAC1B,MAAI,MAAO,QAAO;AAClB,MAAI,aAAa,uBAAwB,QAAO;AAChD,MAAI,WAAW,aAAa,KAAM,QAAO;AACzC,MAAI,YAAY,cAAc,iCAAkC,QAAO;AACvE,SAAO;AACT;;;;;;;;;;;;"}

package/dist/agent-runtime/src/handoff-cursor.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Where a handed-off conversation opens: at the message the source was
+ * reading ("the view at the last message the source showed"), not just at the
+ * bottom.
+ *
+ * The source reads its own transcript when the person issues the handover
+ * (`readingCursorOf` on the web, the visible rows on the phone): `null` when
+ * it was at the bottom, else the id of the last message fully in view or,
+ * when one long message fills the view, the message at the reading line. The
+ * id travels as the handover's `cursor` (an opaque id from the person's own
+ * thread, never content). The destination records it with the arrival
+ * (`recordHandoffArrival({ cursor })`) and its transcript reveals that message
+ * once it has it, paging older history in when needed
+ * (`handoffCursorRevealStep`), and highlights it briefly. A cursor it can't
+ * find leaves the view at the bottom, as before: it is a hint, never a wait.
+ */
+import { type ThreadMessage } from '@assistant-ui/core';
+/** Whether older history is left to page in (`null` until the window is known). */
+export { deepAgentHistoryHasOlder } from './edit-command';
+/** How far from the bottom still counts as "at the bottom": no cursor is sent. */
+export declare const READING_CURSOR_BOTTOM_TOLERANCE_PX = 48;
+/** The reading line, as a fraction of the visible height from its top. */
+export declare const READING_LINE_FRACTION: number;
+/** One rendered message row, in the viewport's coordinates. */
+export interface ReadingRow {
+    id: string;
+    top: number;
+    bottom: number;
+}
+/**
+ * The reading position among `rows` (in document order) visible between `top`
+ * and `bottom`: the last row fully inside, else the row across the reading
+ * line (a message taller than the view). `null` when neither is a message id.
+ */
+export declare function readingCursorFromRows({ top, bottom, rows, }: {
+    top: number;
+    bottom: number;
+    rows: readonly ReadingRow[];
+}): string | null;
+/**
+ * The reading position of a list that reports which rows are visible, in
+ * order and partly visible ones included, but not where they sit (a native
+ * list's viewability). Only the first and last visible rows can be cut off,
+ * so with three or more the last fully visible one is the one before the
+ * last; with fewer, the first (the one across the reading line, as far as the
+ * list can tell). Callers check "at the bottom" themselves.
+ */
+export declare function readingCursorFromVisibleIds(ids: readonly string[]): string | null;
+interface BoxLike {
+    getBoundingClientRect(): {
+        top: number;
+        bottom: number;
+    };
+}
+interface RowLike extends BoxLike {
+    getAttribute(name: string): string | null;
+}
+/** The scroll container of a web transcript (structural, so Core needs no DOM types). */
+export interface ReadingViewportLike extends BoxLike {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+    querySelectorAll(selectors: string): ArrayLike<RowLike>;
+}
+/** assistant-ui stamps every message row with its id. */
+export declare const MESSAGE_ROW_ID_ATTRIBUTE = "data-message-id";
+/**
+ * Where a web transcript is being read: `null` at the bottom, else the message
+ * id `readingCursorFromRows` picks. `coveredBottomPx` is what a sticky footer
+ * (the composer) hides at the bottom of the viewport.
+ */
+export declare function readingCursorOf({ viewport, coveredBottomPx, idAttribute, }: {
+    viewport: ReadingViewportLike;
+    coveredBottomPx?: number;
+    idAttribute?: string;
+}): string | null;
+/**
+ * The id of the displayed message that holds `cursor`. A displayed message is
+ * one agent turn whose id is its first wire message's, and that id changes
+ * when an older page folds into it, so the cursor is matched against every
+ * wire message behind each row as well.
+ */
+export declare function handoffCursorMessageId({ messages, cursor, }: {
+    messages: readonly ThreadMessage[];
+    cursor: string;
+}): string | null;
+/** Pages of older history one landing may load looking for its message. */
+export declare const HANDOFF_CURSOR_MAX_HISTORY_PAGES = 20;
+/**
+ * How long a landing waits without progress before staying at the bottom: a
+ * transcript still attaching, or a page of older history that never lands.
+ * Each page that lands starts the wait again, so a long conversation on a slow
+ * connection still reaches its message within the page budget.
+ */
+export declare const HANDOFF_CURSOR_WAIT_MS = 30000;
+/** How long the revealed message stays highlighted. */
+export declare const HANDOFF_CURSOR_HIGHLIGHT_MS = 2400;
+/**
+ * How long the revealed message is held in view while the transcript settles
+ * (an attaching thread can still scroll itself to the bottom). Any scroll the
+ * person makes ends it at once.
+ */
+export declare const HANDOFF_CURSOR_SETTLE_MS = 1500;
+export type HandoffCursorRevealStep = 'reveal' | 'wait' | 'page' | 'bottom';
+/**
+ * What a destination does next while opening at a cursor: `reveal` the message
+ * it found; `wait` while the transcript (or a page it asked for) is loading or
+ * whether older history exists is not known yet (`hasOlder: null`: a cached
+ * transcript shows before its history window resolves); `page` older history
+ * in while some is left and the budget allows; else stay at the `bottom`, the
+ * fallback for a cursor that can't be found.
+ */
+export declare function handoffCursorRevealStep({ found, loading, hasOlder, pagesLoaded, elapsedMs, }: {
+    found: boolean;
+    loading: boolean;
+    hasOlder: boolean | null;
+    pagesLoaded: number;
+    /** Since the landing last made progress: it started, or a page of older history landed. */
+    elapsedMs: number;
+}): HandoffCursorRevealStep;

package/dist/agent-runtime/src/handoff-cursor.js

@@ -0,0 +1,88 @@
+import { getExternalStoreMessages } from "@assistant-ui/core";
+import { parseHandoffCursor } from "./handoff-cursor-id.js";
+const READING_CURSOR_BOTTOM_TOLERANCE_PX = 48;
+const READING_LINE_FRACTION = 1 / 3;
+function readingCursorFromRows({
+  top,
+  bottom,
+  rows
+}) {
+  var _a;
+  const line = top + (bottom - top) * READING_LINE_FRACTION;
+  let lastFull = null;
+  let atLine = null;
+  for (const row of rows) {
+    if (row.bottom <= row.top) continue;
+    if (row.top >= top - 1 && row.bottom <= bottom + 1) lastFull = row;
+    if (row.top <= line && row.bottom > line) atLine = row;
+  }
+  return parseHandoffCursor((_a = lastFull ?? atLine) == null ? void 0 : _a.id);
+}
+const MESSAGE_ROW_ID_ATTRIBUTE = "data-message-id";
+function readingCursorOf({
+  viewport,
+  coveredBottomPx = 0,
+  idAttribute = MESSAGE_ROW_ID_ATTRIBUTE
+}) {
+  const fromBottom = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;
+  if (fromBottom <= READING_CURSOR_BOTTOM_TOLERANCE_PX) return null;
+  const box = viewport.getBoundingClientRect();
+  const rows = Array.from(viewport.querySelectorAll(`[${idAttribute}]`), (row) => {
+    const rect = row.getBoundingClientRect();
+    return { id: row.getAttribute(idAttribute) ?? "", top: rect.top, bottom: rect.bottom };
+  });
+  return readingCursorFromRows({
+    top: box.top,
+    bottom: Math.max(box.top, box.bottom - coveredBottomPx),
+    rows
+  });
+}
+function handoffCursorMessageId({
+  messages,
+  cursor
+}) {
+  for (const message of messages) {
+    if (message.id === cursor) return message.id;
+  }
+  for (const message of messages) {
+    const sources = getExternalStoreMessages(message);
+    if (!Array.isArray(sources)) continue;
+    for (const source of sources) {
+      if (source && typeof source === "object" && source.id === cursor) {
+        return message.id;
+      }
+    }
+  }
+  return null;
+}
+const HANDOFF_CURSOR_MAX_HISTORY_PAGES = 20;
+const HANDOFF_CURSOR_WAIT_MS = 3e4;
+const HANDOFF_CURSOR_HIGHLIGHT_MS = 2400;
+const HANDOFF_CURSOR_SETTLE_MS = 1500;
+function handoffCursorRevealStep({
+  found,
+  loading,
+  hasOlder,
+  pagesLoaded,
+  elapsedMs
+}) {
+  if (found) return "reveal";
+  if (elapsedMs >= HANDOFF_CURSOR_WAIT_MS) return "bottom";
+  if (loading || hasOlder === null) return "wait";
+  if (hasOlder && pagesLoaded < HANDOFF_CURSOR_MAX_HISTORY_PAGES) return "page";
+  return "bottom";
+}
+export {
+  HANDOFF_CURSOR_HIGHLIGHT_MS,
+  HANDOFF_CURSOR_MAX_HISTORY_PAGES,
+  HANDOFF_CURSOR_SETTLE_MS,
+  HANDOFF_CURSOR_WAIT_MS,
+  MESSAGE_ROW_ID_ATTRIBUTE,
+  READING_CURSOR_BOTTOM_TOLERANCE_PX,
+  READING_LINE_FRACTION,
+  handoffCursorMessageId,
+  handoffCursorRevealStep,
+  readingCursorFromRows,
+  readingCursorOf
+};
+//# sourceMappingURL=handoff-cursor.js.map