@athenaintel/react 0.50.0 → 0.53.0

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-cursor.js","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":[],"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,SAAO,oBAAoB,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,UAAmB,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/index.d.ts

@@ -21,7 +21,7 @@ export { ATHENA_TRUNCATED_TOOL_OUTPUT_ARTIFACT_KEY, buildHistoryMessageCommand,
 export { buildHistoryLaneCommand, type DeepAgentLaneHistoryState, type DeepAgentLaneTarget, deepAgentLaneHistoryQueryKey, type HistoryLaneCommand, type HistoryLanePage, isWholeCardRefusal, mergeLaneHistory, readHistoryLanePage, useDeepAgentLaneHistory, } from "./lane-history";
 export { buildHistoryLaneImageCommand, type DeepAgentLaneImagesState, deepAgentLaneImageQueryKey, type HistoryLaneImageChunk, type HistoryLaneImageCommand, type InlineImage, type InlineImageChunk, type LaneImageRef, laneImageKey, omittedLaneImages, readChunkedInlineImage, readHistoryLaneImageChunk, readInlineImageChunk, readLaneImage, readLaneImageTile, showLaneImages, useDeepAgentLaneImages, } from "./lane-images";
 export { createDeepAgentLaneFollowRegistry, type DeepAgentLaneFollowRegistry, type DeepAgentLaneFollowRequest, type DeepAgentLaneFollows, isLaneFollowRequest, laneFollowRequest, mergeFollowedLane, readDeepAgentFollowedWindow, readDeepAgentLaneFollows, useDeepAgentLaneFollow, useDeepAgentLaneFollowSync, type UseDeepAgentLaneFollowSyncOptions, } from "./lane-follow";
-export { buildDeepAgentEditCommand, type DeepAgentPreparedMessageMetadata, type DeepAgentStatewireExtras, isSourceBelowLoadedWindow, loadOlderDeepAgentHistoryPage, MAX_EDIT_ANCHOR_HISTORY_LOADS, readDeepAgentStatewireExtras, resolveDeepAgentEditCommand, resolveWireAnchorMessageId, } from "./edit-command";
+export { buildDeepAgentEditCommand, deepAgentHistoryHasOlder, type DeepAgentPreparedMessageMetadata, type DeepAgentStatewireExtras, isSourceBelowLoadedWindow, loadOlderDeepAgentHistoryPage, MAX_EDIT_ANCHOR_HISTORY_LOADS, readDeepAgentStatewireExtras, resolveDeepAgentEditCommand, resolveWireAnchorMessageId, } from "./edit-command";
 export { DEEP_AGENT_MAX_CHAINED_HISTORY_LOADS, type DeepAgentHistoryLoadEvent, type DeepAgentWindowSyncMessage, type DeepAgentWindowSyncState, useDeepAgentMessageWindow, useDeepAgentWindowSync, type UseDeepAgentWindowSyncOptions, } from "./use-deep-agent-window-sync";
 export { useDeepAgentMessageEditSubmit } from "./use-deep-agent-edit-submit";
 export { createDeepAgentToolOutputStore, type DeepAgentToolOutputEntry, type DeepAgentToolOutputStore, type DeepAgentToolOutputStoreOptions, } from "./tool-outputs";
@@ -75,8 +75,9 @@ export { type DeepAgentAttachSource, type DeepAgentHeadersResolver, readSessionP
 export { GITHUB_EVENT_SOURCE_KEY, type GithubWakeEvent, githubWakeEventLabel, githubWakeEventUrl, githubWakeMarkerText, githubWakeReference, isGithubWakeMessage, readGithubWakeEvent, } from "./github-wake-event";
 export { githubSubscriptionHeadline, isSubscriptionWakeMessage, readSubscriptionWakeEvent, SUBSCRIPTION_EVENT_KEY, type SubscriptionWakeChange, type SubscriptionWakeEvent, type SubscriptionWakeGithub, subscriptionPlaceWords, subscriptionWakeDetail, subscriptionWakeGithub, subscriptionWakeHeadline, } from "./subscription-wake-event";
 export { describeTerminationReason, readRuntimeMessageFromSourceMessages, readSoleRuntimeMessageKind, readTerminationReason, runtimeMessageMarkerText, TERMINATION_REASONS, type AthenaRuntimeMessage, type AthenaRuntimeMessageKind, type AthenaRuntimeMessageSeverity, type AthenaTerminationReason, type TerminationDescription, } from "./runtime-messages";
-export { buildHandoffQrSvg, buildMobileHandoffSchemeUrl, classifyHandoffTransportError, type CreateThreadHandoffInput, type CreateThreadHandoffResponse, createThreadHandoffResponseSchema, describeHandoffTransportError, type DestinationReadiness, HANDOFF_DESTINATION_LABELS, HANDOFF_DESTINATIONS, HANDOFF_URL_PARAM, type HandoffDestination, type HandoffDestinationPresentation, type HandoffEnvironment, HandoffGoneError, type HandoffLaunch, type HandoffOutcome, HandoffPermanentError, type HandoffReadinessResponse, type HandoffReadinessState, type HandoffSource, type HandoffState, type HandoffTransportErrorKind, handoffHttpError, handoffReadinessResponseSchema, handoffStateSchema, isHandoffGoneError, isHandoffPermanentError, isRetryableHandoffHttpStatus, isOfficeHandoffDestination, isServerHandoffDestination, isTerminalHandoffState, type MobileHandoffLaunch, type MobileLaunchMode, mobileHandoffLaunchSchema, OFFICE_HANDOFF_DESTINATIONS, type OfficeHandoffDestination, type OfficeHandoffLaunch, officeHandoffLaunchSchema, type OfficeInvitationLaunch, officeInvitationLaunchSchema, type OfficeLaunchMode, officeLaunchModeSchema, threadHandoffCreateBody, parseHandoffIdParam, presentHandoffDestination, readinessByDestination, SERVER_HANDOFF_DESTINATIONS, type ServerHandoffDestination, selectMobileLaunchMode, supportsDesktopHandoffSource, type ThreadHandoffTransport, type ThreadHandoffView, threadHandoffViewSchema, waitForHandoffOutcome, type WaitForHandoffOutcomeOptions, type ClaimThreadHandoffResponse, claimThreadHandoffResponseSchema, clampHandoffDraft, handoffDraftToCarry, continuedFromLabel, pickUpFromLabel, pickUpOfferLabel, type DesktopThreadHandoffLaunch, desktopThreadHandoffLaunchSchema, driverSurfaceForChannel, drivingOnLabel, type HandoffLanding, handoffLandingFromView, isPickupSurface, MAX_HANDOFF_DRAFT_LENGTH, nextHandoffLaunchSchema, parseThreadHandoffCreateResponse, pendingThreadHandoffResponseSchema, pickedUpOnLabel, PICKUP_SURFACES, type PickupSurface, shouldOfferPendingHandoff, SPACES_HANDOFF_URL_PARAM, type SpacesHandoffLaunch, spacesHandoffLaunchSchema, SURFACE_HANDOFF_DESTINATIONS, type SurfaceHandoffDestination, supportsSurfaceHandoffDestinations, THREAD_HANDOFF_DESTINATION_LABELS, THREAD_HANDOFF_DESTINATIONS, threadHandoffClaimBody, threadHandoffCreateRequest, type ThreadHandoffDestination, type ThreadHandoffReceiverTransport, MAX_PENDING_EXCLUDE, pendingExcludeIds, pickupExcludeIds, pendingHandoffPath, type HandoffMode, handoffModeSchema, isVoiceHandoffDestination, livenessAgo, presentSurfaceLiveness, type SurfaceLiveness, type SurfaceLivenessBasis, surfaceLivenessBasisSchema, surfaceLivenessBySurface, type SurfaceLivenessPresentation, surfaceLivenessSchema, type SurfaceLivenessState, surfaceLivenessStateSchema, type SurfaceLivenessTone, supportsSurfaceLiveness, } from "./thread-handoff";
+export { buildHandoffQrSvg, buildMobileHandoffSchemeUrl, classifyHandoffTransportError, type CreateThreadHandoffInput, type CreateThreadHandoffResponse, createThreadHandoffResponseSchema, describeHandoffTransportError, type DestinationReadiness, HANDOFF_DESTINATION_LABELS, HANDOFF_DESTINATIONS, HANDOFF_URL_PARAM, type HandoffDestination, type HandoffDestinationPresentation, type HandoffEnvironment, HandoffGoneError, type HandoffLaunch, type HandoffOutcome, HandoffPermanentError, type HandoffReadinessResponse, type HandoffReadinessState, type HandoffSource, type HandoffState, type HandoffTransportErrorKind, handoffHttpError, handoffReadinessResponseSchema, handoffStateSchema, isHandoffGoneError, isHandoffPermanentError, isRetryableHandoffHttpStatus, isOfficeHandoffDestination, isServerHandoffDestination, isTerminalHandoffState, type MobileHandoffLaunch, type MobileLaunchMode, mobileHandoffLaunchSchema, OFFICE_HANDOFF_DESTINATIONS, type OfficeHandoffDestination, type OfficeHandoffLaunch, officeHandoffLaunchSchema, type OfficeInvitationLaunch, officeInvitationLaunchSchema, type OfficeLaunchMode, officeLaunchModeSchema, threadHandoffCreateBody, parseHandoffIdParam, presentHandoffDestination, readinessByDestination, SERVER_HANDOFF_DESTINATIONS, type ServerHandoffDestination, selectMobileLaunchMode, supportsDesktopHandoffSource, type ThreadHandoffTransport, type ThreadHandoffView, threadHandoffViewSchema, waitForHandoffOutcome, type WaitForHandoffOutcomeOptions, type ClaimThreadHandoffResponse, claimThreadHandoffResponseSchema, clampHandoffDraft, handoffDraftToCarry, continuedFromLabel, pickUpFromLabel, pickUpOfferLabel, type DesktopThreadHandoffLaunch, desktopThreadHandoffLaunchSchema, driverSurfaceForChannel, drivingOnLabel, type HandoffLanding, handoffLandingFromView, isPickupSurface, MAX_HANDOFF_DRAFT_LENGTH, nextHandoffLaunchSchema, parseThreadHandoffCreateResponse, pendingThreadHandoffResponseSchema, pickedUpOnLabel, PICKUP_SURFACES, type PickupSurface, shouldOfferPendingHandoff, IMPLICIT_PICKUP_ACTIVATION_WINDOW_MS, IMPLICIT_PICKUP_DECLINE_HOLD_MS, type ImplicitPickupAnswer, type ImplicitPickupContext, implicitPickupAllowed, isImplicitHandoff, nextImplicitPickupAnswer, SPACES_HANDOFF_URL_PARAM, type SpacesHandoffLaunch, spacesHandoffLaunchSchema, SURFACE_HANDOFF_DESTINATIONS, type SurfaceHandoffDestination, supportsSurfaceHandoffDestinations, THREAD_HANDOFF_DESTINATION_LABELS, THREAD_HANDOFF_DESTINATIONS, threadHandoffClaimBody, threadHandoffCreateRequest, type ThreadHandoffDestination, type ThreadHandoffReceiverTransport, MAX_PENDING_EXCLUDE, handoffDeclineKey, pendingExcludeIds, pickupExcludeIds, pendingHandoffPath, type HandoffMode, handoffModeSchema, isVoiceHandoffDestination, MAX_HANDOFF_CURSOR_LENGTH, parseHandoffCursor, supportsHandoffCursor, livenessAgo, presentSurfaceLiveness, type SurfaceLiveness, type SurfaceLivenessBasis, surfaceLivenessBasisSchema, surfaceLivenessBySurface, type SurfaceLivenessPresentation, surfaceLivenessSchema, type SurfaceLivenessState, surfaceLivenessStateSchema, type SurfaceLivenessTone, supportsSurfaceLiveness, } from "./thread-handoff";
 export { DEFAULT_MOBILE_HANDOFF_TIMEOUT_MS, DEFAULT_OFFICE_HANDOFF_TIMEOUT_MS, DEFAULT_PICKUP_HANDOFF_TIMEOUT_MS, type StartThreadHandoffInput, type ThreadHandoffFlowCallbacks, type ThreadHandoffFlowController, type ThreadHandoffFlowPhase, useThreadHandoffFlow, type UseThreadHandoffFlowOptions, } from "./use-thread-handoff-flow";
-export { anchorHandoffArrival, clearHandoffArrival, type HandoffArrival, HandoffArrivalContext, MAX_HANDOFF_ARRIVALS, readHandoffArrival, recordHandoffArrival, resetHandoffArrivalsForTests, subscribeHandoffArrivals, useHandoffArrival, useHandoffArrivalAfter, } from "./handoff-arrival";
+export { anchorHandoffArrival, clearHandoffArrival, type HandoffArrival, HandoffArrivalContext, MAX_HANDOFF_ARRIVALS, readHandoffArrival, recordHandoffArrival, resetHandoffArrivalsForTests, settleHandoffArrivalCursor, subscribeHandoffArrivals, useHandoffArrival, useHandoffArrivalAfter, useHandoffArrivalCursor, } from "./handoff-arrival";
+export { HANDOFF_CURSOR_HIGHLIGHT_MS, HANDOFF_CURSOR_MAX_HISTORY_PAGES, HANDOFF_CURSOR_SETTLE_MS, HANDOFF_CURSOR_WAIT_MS, handoffCursorMessageId, handoffCursorRevealStep, type HandoffCursorRevealStep, MESSAGE_ROW_ID_ATTRIBUTE, READING_CURSOR_BOTTOM_TOLERANCE_PX, READING_LINE_FRACTION, type ReadingRow, type ReadingViewportLike, readingCursorFromRows, readingCursorFromVisibleIds, readingCursorOf, } from "./handoff-cursor";
 export { connectVoiceMedia, VOICE_MICROPHONE_CAPTURE } from './voice-media';
 export type { VoiceMediaDriver, VoiceMediaEvent, VoiceMediaEventType, VoiceMediaHandlers, VoiceMediaSession, } from './voice-media';

package/dist/agent-runtime/src/thread-handoff-flow-machine.d.ts

@@ -54,6 +54,9 @@ export declare const threadHandoffFlowMachine: import("xstate").StateMachine<Han
             claimed_surface?: "chrome" | "desktop" | "mobile" | "spaces" | null | undefined;
             mode?: "text" | "voice" | undefined;
             draft?: string | null | undefined;
+            cursor?: string | null | undefined;
+            revision?: number | undefined;
+            implicit?: boolean | undefined;
         };
         launch: {
             kind: "mobile";
@@ -114,6 +117,9 @@ export declare const threadHandoffFlowMachine: import("xstate").StateMachine<Han
             claimed_surface?: "chrome" | "desktop" | "mobile" | "spaces" | null | undefined;
             mode?: "text" | "voice" | undefined;
             draft?: string | null | undefined;
+            cursor?: string | null | undefined;
+            revision?: number | undefined;
+            implicit?: boolean | undefined;
         };
         launch: {
             kind: "mobile";

package/dist/agent-runtime/src/thread-handoff-protocol.d.ts

@@ -29,6 +29,7 @@ export declare const SURFACE_HANDOFF_DESTINATIONS: readonly ['spaces', 'mobile',
 export type SurfaceHandoffDestination = (typeof SURFACE_HANDOFF_DESTINATIONS)[number];
 /** The source composer's unsent text that travels prefilled, never sent. */
 export declare const MAX_HANDOFF_DRAFT_LENGTH = 4000;
+export { MAX_HANDOFF_CURSOR_LENGTH, parseHandoffCursor } from './handoff-cursor-id';
 /**
  * How the person chose to continue. `voice` is an offer the destination shows
  * ("Continue by voice"); it never starts a microphone by itself. Older servers
@@ -170,6 +171,7 @@ export declare const handoffReadinessResponseSchema: z.ZodObject<{
     supports_office_invitations: z.ZodOptional<z.ZodBoolean>;
     supports_desktop_source: z.ZodOptional<z.ZodBoolean>;
     supports_surface_destinations: z.ZodOptional<z.ZodBoolean>;
+    supports_handoff_cursor: z.ZodOptional<z.ZodBoolean>;
     supports_surface_liveness: z.ZodOptional<z.ZodBoolean>;
     surfaces: z.ZodCatch<z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodUnknown>, z.ZodTransform<{
         surface: "chrome" | "desktop" | "mobile" | "spaces";
@@ -183,6 +185,8 @@ export type HandoffReadinessResponse = z.infer<typeof handoffReadinessResponseSc
 export declare const supportsDesktopHandoffSource: (readiness: HandoffReadinessResponse | null | undefined) => boolean;
 /** Whether the server can broker the four-surface destinations; absent means an older agora. */
 export declare const supportsSurfaceHandoffDestinations: (readiness: HandoffReadinessResponse | null | undefined) => boolean;
+/** Whether the server takes a reading position (`cursor`); absent means an older agora. */
+export declare const supportsHandoffCursor: (readiness: HandoffReadinessResponse | null | undefined) => boolean;
 /** Whether the server reports where the person's apps were last seen; absent means an older agora. */
 export declare const supportsSurfaceLiveness: (readiness: HandoffReadinessResponse | null | undefined) => boolean;
 /** Index liveness rows by surface; `null` where the server sent none (or can't report liveness). */
@@ -256,8 +260,17 @@ export declare const threadHandoffViewSchema: z.ZodObject<{
         voice: "voice";
     }>>;
     draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    revision: z.ZodOptional<z.ZodNumber>;
+    implicit: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ThreadHandoffView = z.infer<typeof threadHandoffViewSchema>;
+/**
+ * What a "Not now" remembers: the ticket at the revision it was offered at (`<id>@<revision>`).
+ * Sent back as `exclude`, it skips that ticket only until the same conversation is sent here
+ * again, which offers it again.
+ */
+export declare function handoffDeclineKey(view: Pick<ThreadHandoffView, 'handoff_id' | 'revision'>): string;
 export declare const mobileHandoffLaunchSchema: z.ZodObject<{
     kind: z.ZodLiteral<"mobile">;
     push_attempted: z.ZodBoolean;
@@ -400,6 +413,9 @@ export declare const createThreadHandoffResponseSchema: z.ZodObject<{
             voice: "voice";
         }>>;
         draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        cursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        revision: z.ZodOptional<z.ZodNumber>;
+        implicit: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     launch: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"mobile">;
@@ -457,6 +473,13 @@ export interface CreateThreadHandoffInput {
     draft?: string;
     /** `voice` offers "Continue by voice" on the destination. Omitted means text. */
     mode?: HandoffMode;
+    /**
+     * Where the source was reading: the id of the last message it showed, or `''`
+     * when it was at the bottom (which also clears a reused ticket's). Send it only
+     * to a host whose readiness says `supports_handoff_cursor`. A value that is
+     * not a message id goes as `''`.
+     */
+    cursor?: string;
 }
 /**
  * The draft a create carries, the one rule every source follows. An Office
@@ -475,7 +498,7 @@ export declare function handoffDraftToCarry({ destination, draft, }: {
 /** A phone invites the computer's pane; other sources keep their existing launch. */
 export declare function resolveOfficeHandoffLaunchMode({ source, destination, officeLaunchMode, }: CreateThreadHandoffInput): OfficeLaunchMode | undefined;
 /** The same request body for every host's authenticated HTTP adapter. */
-export declare function threadHandoffCreateBody({ threadId, destination, source, officeLaunchMode, expectedWorkspaceId, draft, mode: handoffMode, }: CreateThreadHandoffInput): {
+export declare function threadHandoffCreateBody({ threadId, destination, source, officeLaunchMode, expectedWorkspaceId, draft, mode: handoffMode, cursor, }: CreateThreadHandoffInput): {
     thread_id: string;
     destination: "chrome" | "desktop" | "excel" | "mobile" | "next" | "powerpoint" | "spaces" | "word";
     source: HandoffSource;
@@ -483,6 +506,7 @@ export declare function threadHandoffCreateBody({ threadId, destination, source,
     office_launch_mode?: "invitation" | "new_document" | undefined;
     draft?: string | undefined;
     mode?: "voice" | undefined;
+    cursor?: string | undefined;
 };
 /** Keep a draft within the server's limit at a character boundary; never send more. */
 export declare const clampHandoffDraft: (draft: string) => string;
@@ -528,10 +552,15 @@ export declare function pickupExcludeIds({ issuedHere, declined, }: {
     issuedHere: Iterable<string>;
     declined: Iterable<string>;
 }): string[];
-/** `/pending?destination=…&exclude=…` relative to `/api/handoffs`. */
-export declare function pendingHandoffPath({ destination, exclude, }: {
+/**
+ * `/pending?destination=…&exclude=…` relative to `/api/handoffs`. `includeImplicit` asks for an
+ * implicit ticket too ("pick up without sending"): only on a `next` peek, the one destination an
+ * implicit ticket names. A server that predates it ignores the flag.
+ */
+export declare function pendingHandoffPath({ destination, exclude, includeImplicit, }: {
     destination: Exclude<ThreadHandoffDestination, 'desktop'> | 'desktop';
     exclude?: Iterable<string>;
+    includeImplicit?: boolean;
 }): string;
 export declare const claimThreadHandoffResponseSchema: z.ZodObject<{
     handoff: z.ZodObject<{
@@ -582,6 +611,9 @@ export declare const claimThreadHandoffResponseSchema: z.ZodObject<{
             voice: "voice";
         }>>;
         draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        cursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        revision: z.ZodOptional<z.ZodNumber>;
+        implicit: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type ClaimThreadHandoffResponse = z.infer<typeof claimThreadHandoffResponseSchema>;
@@ -635,6 +667,9 @@ export declare const pendingThreadHandoffResponseSchema: z.ZodNullable<z.ZodObje
             voice: "voice";
         }>>;
         draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        cursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        revision: z.ZodOptional<z.ZodNumber>;
+        implicit: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
 }, z.core.$strip>>;
 /**
@@ -650,6 +685,8 @@ export interface ThreadHandoffReceiverTransport {
         destination: Exclude<ThreadHandoffDestination, 'desktop'>;
         /** Tickets this receiver declined or issued itself; the newest other one is returned. */
         exclude?: readonly string[];
+        /** Also an implicit ticket, on a `next` peek ({@link pendingHandoffPath}). */
+        includeImplicit?: boolean;
         signal?: AbortSignal;
     }) => Promise<ClaimThreadHandoffResponse | null>;
     claim: (options: {
@@ -667,16 +704,84 @@ export interface ThreadHandoffReceiverTransport {
         signal?: AbortSignal;
     }) => Promise<ThreadHandoffView>;
 }
+/**
+ * "Pick up without sending": an app offers a conversation the person is driving on another of
+ * their apps only when it just became active (the Spaces tab became visible, the phone came to the
+ * foreground, Chrome's side panel opened, the desktop window gained focus), within this long.
+ */
+export declare const IMPLICIT_PICKUP_ACTIVATION_WINDOW_MS = 10000;
+/**
+ * How long a "Not now" to an implicit offer is kept where declines expire (Chrome, the desktop
+ * app). The ticket keeps its id for as long as the same app drives, past its 10 minutes, so a
+ * decline kept only as long as the ticket's first expiry would let the same offer come back.
+ */
+export declare const IMPLICIT_PICKUP_DECLINE_HOLD_MS: number;
+/** Whether a view is an implicit ticket: left by the app the person drives from, never sent. */
+export declare const isImplicitHandoff: (view: Pick<ThreadHandoffView, 'implicit'> | null | undefined) => boolean;
+/**
+ * What a receiving app knows about itself to judge an implicit ticket. `seenAt` comes from
+ * {@link nextImplicitPickupAnswer}: when this app first saw the ticket after `becameActiveAt`.
+ */
+export interface ImplicitPickupContext {
+    /** This app. */
+    here: PickupSurface;
+    /** The conversation this app shows now; `null` when none. */
+    showingThreadId: string | null;
+    /** When this app last became active; `null` until it has. */
+    becameActiveAt: number | null;
+    /** When this app first saw the ticket after becoming active; `null` when it has not. */
+    seenAt: number | null;
+}
+/**
+ * Whether an implicit ticket may be offered here: it is another app's, this app isn't already
+ * showing that conversation, and this app saw it within {@link IMPLICIT_PICKUP_ACTIVATION_WINDOW_MS}
+ * of becoming active. An idle poll's answer never qualifies on its own, and nothing here ever
+ * raises a notification: only the app's own banner offers one.
+ */
+export declare function implicitPickupAllowed({ pending, context, }: {
+    pending: Pick<ThreadHandoffView, 'source' | 'thread_id'>;
+    context: ImplicitPickupContext;
+}): boolean;
+/** An implicit-pickup peek's answer, with what judging it needs. */
+export interface ImplicitPickupAnswer<View extends {
+    handoff_id: string;
+} = ThreadHandoffView> {
+    view: View | null;
+    /** The activation this answer belongs to. */
+    becameActiveAt: number;
+    /** When this app first saw `view`'s ticket since that activation. */
+    seenAt: number;
+}
+/**
+ * Fold a new peek into the earlier ones: a ticket seen again since the same activation keeps the
+ * time it was first seen, so an offer made on becoming active stays up until it is answered or
+ * goes away, while a ticket that first shows up on a later poll is never offered. `previous` may
+ * be every answer of this activation (one per set of exclusions a host asked with), so declining
+ * another ticket never makes this one look new.
+ */
+export declare function nextImplicitPickupAnswer<View extends {
+    handoff_id: string;
+} = ThreadHandoffView>({ previous, view, becameActiveAt, now, }: {
+    previous: ImplicitPickupAnswer<View> | readonly (ImplicitPickupAnswer<View> | null | undefined)[] | null | undefined;
+    view: View | null;
+    becameActiveAt: number;
+    now?: number;
+}): ImplicitPickupAnswer<View>;
 /**
  * Whether a pending handoff should be offered on this surface: still open,
  * not one this device issued itself, and not one it already declined.
  * Offering never claims; the person's tap does.
+ *
+ * A ticket the person sent is judged exactly as it always was. An implicit
+ * one ("pick up without sending") also needs `implicit`, the receiver's own
+ * context ({@link implicitPickupAllowed}); without it, it is never offered.
  */
-export declare function shouldOfferPendingHandoff({ pending, issuedHere, declined, now, }: {
+export declare function shouldOfferPendingHandoff({ pending, issuedHere, declined, now, implicit, }: {
     pending: ThreadHandoffView | null | undefined;
     issuedHere: ReadonlySet<string>;
     declined: ReadonlySet<string>;
     now?: number;
+    implicit?: ImplicitPickupContext;
 }): boolean;
 /**
  * Surface-specific HTTP adapter. Olympus binds it to `apiClient`; the
@@ -741,6 +846,11 @@ export interface HandoffLanding {
      * "Continue by voice"; nothing starts the microphone on its own.
      */
     continueByVoice: boolean;
+    /**
+     * The message the source was reading; the transcript opens there instead of
+     * at the bottom. `null` when the source was at the bottom (or sent none).
+     */
+    cursor: string | null;
 }
 export declare const handoffLandingFromView: (view: ThreadHandoffView) => HandoffLanding;
 export declare const isOfficeHandoffDestination: (destination: ThreadHandoffDestination) => destination is OfficeHandoffDestination;

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

@@ -1,3 +1,3 @@
 /** Backward-compatible entrypoint. Use the protocol entrypoint without QR rendering. */
-export { type CreateThreadHandoffInput, type CreateThreadHandoffResponse, type DestinationReadiness, HANDOFF_DESTINATIONS, HANDOFF_DESTINATION_LABELS, HANDOFF_URL_PARAM, type HandoffDestination, type HandoffDestinationPresentation, type HandoffEnvironment, HandoffGoneError, type HandoffLaunch, type HandoffOutcome, HandoffPermanentError, type HandoffReadinessResponse, type HandoffReadinessState, type HandoffSource, type HandoffState, type HandoffTransportErrorKind, MOBILE_APP_SCHEME, type MobileHandoffLaunch, type MobileLaunchMode, OFFICE_HANDOFF_DESTINATIONS, type OfficeHandoffDestination, type OfficeHandoffLaunch, type OfficeInvitationLaunch, type OfficeLaunchMode, SERVER_HANDOFF_DESTINATIONS, type ServerHandoffDestination, type ThreadHandoffTransport, type ThreadHandoffView, type WaitForHandoffOutcomeOptions, buildMobileHandoffSchemeUrl, chromeHandoffLaunchSchema, classifyHandoffTransportError, createThreadHandoffResponseSchema, describeHandoffTransportError, destinationReadinessSchema, handoffEnvironmentSchema, handoffHttpError, handoffLaunchSchema, handoffReadinessResponseSchema, handoffReadinessStateSchema, handoffStateSchema, isHandoffGoneError, isHandoffPermanentError, isOfficeHandoffDestination, isRetryableHandoffHttpStatus, isServerHandoffDestination, isTerminalHandoffState, mobileHandoffLaunchSchema, officeHandoffLaunchSchema, officeInvitationLaunchSchema, officeLaunchModeSchema, parseHandoffIdParam, presentHandoffDestination, readinessByDestination, resolveOfficeHandoffLaunchMode, selectMobileLaunchMode, supportsDesktopHandoffSource, threadHandoffCreateBody, threadHandoffViewSchema, waitForHandoffOutcome, type ClaimThreadHandoffResponse, claimThreadHandoffResponseSchema, clampHandoffDraft, handoffDraftToCarry, continuedFromLabel, pickUpFromLabel, pickUpOfferLabel, type DesktopThreadHandoffLaunch, desktopThreadHandoffLaunchSchema, driverSurfaceForChannel, drivingOnLabel, type HandoffLanding, handoffLandingFromView, isPickupSurface, MAX_HANDOFF_DRAFT_LENGTH, nextHandoffLaunchSchema, parseThreadHandoffCreateResponse, pendingThreadHandoffResponseSchema, pickedUpOnLabel, PICKUP_SURFACES, type PickupSurface, shouldOfferPendingHandoff, SPACES_HANDOFF_URL_PARAM, type SpacesHandoffLaunch, spacesHandoffLaunchSchema, SURFACE_HANDOFF_DESTINATIONS, type SurfaceHandoffDestination, supportsSurfaceHandoffDestinations, THREAD_HANDOFF_DESTINATION_LABELS, THREAD_HANDOFF_DESTINATIONS, threadHandoffClaimBody, threadHandoffCreateRequest, type ThreadHandoffDestination, type ThreadHandoffReceiverTransport, MAX_PENDING_EXCLUDE, pendingExcludeIds, pickupExcludeIds, pendingHandoffPath, type HandoffMode, handoffModeSchema, isVoiceHandoffDestination, livenessAgo, presentSurfaceLiveness, type SurfaceLiveness, type SurfaceLivenessBasis, surfaceLivenessBasisSchema, surfaceLivenessBySurface, type SurfaceLivenessPresentation, surfaceLivenessSchema, type SurfaceLivenessState, surfaceLivenessStateSchema, type SurfaceLivenessTone, supportsSurfaceLiveness, } from './thread-handoff-protocol';
+export { type CreateThreadHandoffInput, type CreateThreadHandoffResponse, type DestinationReadiness, HANDOFF_DESTINATIONS, HANDOFF_DESTINATION_LABELS, HANDOFF_URL_PARAM, type HandoffDestination, type HandoffDestinationPresentation, type HandoffEnvironment, HandoffGoneError, type HandoffLaunch, type HandoffOutcome, HandoffPermanentError, type HandoffReadinessResponse, type HandoffReadinessState, type HandoffSource, type HandoffState, type HandoffTransportErrorKind, MOBILE_APP_SCHEME, type MobileHandoffLaunch, type MobileLaunchMode, OFFICE_HANDOFF_DESTINATIONS, type OfficeHandoffDestination, type OfficeHandoffLaunch, type OfficeInvitationLaunch, type OfficeLaunchMode, SERVER_HANDOFF_DESTINATIONS, type ServerHandoffDestination, type ThreadHandoffTransport, type ThreadHandoffView, type WaitForHandoffOutcomeOptions, buildMobileHandoffSchemeUrl, chromeHandoffLaunchSchema, classifyHandoffTransportError, createThreadHandoffResponseSchema, describeHandoffTransportError, destinationReadinessSchema, handoffEnvironmentSchema, handoffHttpError, handoffLaunchSchema, handoffReadinessResponseSchema, handoffReadinessStateSchema, handoffStateSchema, isHandoffGoneError, isHandoffPermanentError, isOfficeHandoffDestination, isRetryableHandoffHttpStatus, isServerHandoffDestination, isTerminalHandoffState, mobileHandoffLaunchSchema, officeHandoffLaunchSchema, officeInvitationLaunchSchema, officeLaunchModeSchema, parseHandoffIdParam, presentHandoffDestination, readinessByDestination, resolveOfficeHandoffLaunchMode, selectMobileLaunchMode, supportsDesktopHandoffSource, threadHandoffCreateBody, threadHandoffViewSchema, waitForHandoffOutcome, type ClaimThreadHandoffResponse, claimThreadHandoffResponseSchema, clampHandoffDraft, handoffDraftToCarry, continuedFromLabel, pickUpFromLabel, pickUpOfferLabel, type DesktopThreadHandoffLaunch, desktopThreadHandoffLaunchSchema, driverSurfaceForChannel, drivingOnLabel, type HandoffLanding, handoffLandingFromView, isPickupSurface, MAX_HANDOFF_DRAFT_LENGTH, nextHandoffLaunchSchema, parseThreadHandoffCreateResponse, pendingThreadHandoffResponseSchema, pickedUpOnLabel, PICKUP_SURFACES, type PickupSurface, shouldOfferPendingHandoff, IMPLICIT_PICKUP_ACTIVATION_WINDOW_MS, IMPLICIT_PICKUP_DECLINE_HOLD_MS, type ImplicitPickupAnswer, type ImplicitPickupContext, implicitPickupAllowed, isImplicitHandoff, nextImplicitPickupAnswer, SPACES_HANDOFF_URL_PARAM, type SpacesHandoffLaunch, spacesHandoffLaunchSchema, SURFACE_HANDOFF_DESTINATIONS, type SurfaceHandoffDestination, supportsSurfaceHandoffDestinations, THREAD_HANDOFF_DESTINATION_LABELS, THREAD_HANDOFF_DESTINATIONS, threadHandoffClaimBody, threadHandoffCreateRequest, type ThreadHandoffDestination, type ThreadHandoffReceiverTransport, MAX_PENDING_EXCLUDE, handoffDeclineKey, pendingExcludeIds, pickupExcludeIds, pendingHandoffPath, type HandoffMode, handoffModeSchema, isVoiceHandoffDestination, MAX_HANDOFF_CURSOR_LENGTH, parseHandoffCursor, supportsHandoffCursor, livenessAgo, presentSurfaceLiveness, type SurfaceLiveness, type SurfaceLivenessBasis, surfaceLivenessBasisSchema, surfaceLivenessBySurface, type SurfaceLivenessPresentation, surfaceLivenessSchema, type SurfaceLivenessState, surfaceLivenessStateSchema, type SurfaceLivenessTone, supportsSurfaceLiveness, } from './thread-handoff-protocol';
 export { buildHandoffQrSvg } from './thread-handoff-qr';

package/dist/agent-runtime/src/use-deep-agent-window-sync.cjs

@@ -33,6 +33,9 @@ function pageShowedEarlierMessage(from, messages) {
   }
   return messages.length > from.count;
 }
+function isReply(message) {
+  return (message == null ? void 0 : message.role) !== void 0 && message.role !== "user";
+}
 function opensMidTurn(messages) {
   const first = messages[0];
   if (first === void 0) return false;
@@ -130,15 +133,17 @@ function useDeepAgentWindowSync({
       if (chainRef.current.loads >= maxChainedLoads) return;
       chainRef.current.loads += 1;
     }
+    const insideTurn = lastPageUnseen || isReply(messages[0]);
+    const stated = insideTurn && messageWindow.pageInterestRequests(window, runconfigContract.DEEP_AGENT_MAX_MESSAGE_WINDOW) || pageRequests;
     pageFromRef.current = { count: messages.length, secondId: (_a = messages[1]) == null ? void 0 : _a.id };
     const page = window.pages + 1;
-    const request = pageRequests[pageRequests.length - 1];
+    const request = stated[stated.length - 1];
     inflightRef.current = true;
     setLoading(true);
     const startedAt = nowRef.current();
-    invoke(runconfigContract.DEEP_AGENT_INTEREST_PROTOCOL, "set", [pageRequests]).then(() => {
+    invoke(runconfigContract.DEEP_AGENT_INTEREST_PROTOCOL, "set", [stated]).then(() => {
       var _a2;
-      statedRef.current = pageRequests;
+      statedRef.current = stated;
       (_a2 = onHistoryLoadRef.current) == null ? void 0 : _a2.call(onHistoryLoadRef, {
         page,
         request,