@athenaintel/react 0.54.0 → 0.56.0

package/README.md

@@ -951,6 +951,38 @@ Both use the same bearer / API key as session creation. The full recipe
 template skill `voice-session-guide.md`. `createAthenaVoiceSession` is also
 exported if you hold the bridge state yourself.
 
+## What's new in 0.56.0
+
+**One history store per conversation, shared by every reader.** Older history read with `history/page` now lives in a per-conversation store that the thread, the history edge, edits and reveals all join. It no longer sits in a store `AthenaProvider` hands around. The store keeps each message by its parent, not its position:
+- **Kept on moves:** history you loaded survives a reconnect, a move to another server, and new messages pushing older ones out of the live view.
+- **Smaller live view:** the client says so on the attach (`x-athena-deep-agent-history: paged`). An agora that knows the header then keeps the live view to the newest 200 messages during a long run, since older ones stay in the store.
+- **Edits:** an edit of an older message pages back by command until it finds where to anchor.
+
+**Hosts need to pass nothing.** `StatewireHistoryPagesContext`, `useStatewireHistoryPages`, `StatewireHistoryEdge`'s `historyPages` prop and `AthenaStatewireRuntimeConfig.historyPages` are deprecated and ignored. A summarized turn's counts come with every thread. Hosts that compose their own thread still provide the steps control through `TurnStepsControlContext` (`EarlierStepsButton` is the stock one). Hosts built directly on `@athenaintel/agent-runtime` need no store: `loadDeepAgentTurnSteps({ send, marker })` loads a summarized turn's steps.
+
+**Refusals.** Only a host without the command (`unknown-command`) moves a connection back to interest pages. Any other refusal is that page's error, and loaded history stays shown.
+
+**Identity.** `AthenaProvider` drops the stores when the signed-in identity or API key changes. Against an agora older than protocol 3, paging works as in 0.54.0.
+
+## What's new in 0.55.0
+
+**Older history reaches the start of any conversation.** Against an agora that answers `history/page` (deep-agent protocol 3), `AthenaChat` loads older history as whole turns into a store of its own, kept outside the connection's view. The view is no longer the depth limit, so a long session reads back to its first message.
+- **Long runs read exactly.** A long run comes back as its prompt and answer and reads its exact counts ("Delegated to 4 agents · used 296 tools", not "300+").
+- **Steps on demand.** "Show N earlier steps" loads the run's steps when you ask.
+- **Older hosts.** Against an agora that does not advertise protocol 3, paging works exactly as in 0.54.0.
+
+`AthenaProvider` owns the store, clears it when the signed-in identity changes, and hands it to the runtime and the history edge.
+
+**`AthenaChat` needs nothing:** `AthenaProvider` wires it all up.
+
+**Hosts that compose their own thread** from the SDK's pieces (`ChatThreadShell`, `SuperGroupingCard`, `StatewireHistoryEdge`) provide two contexts from `@athenaintel/react/chat-ui/statewire`:
+- the store, through `StatewireHistoryPagesContext`;
+- the step control, through `TurnStepsControlContext` (`EarlierStepsButton` is the stock one).
+
+**Hosts built directly on `@athenaintel/agent-runtime`** create the store with `createDeepAgentHistoryStore()` and pass it to `useDeepAgentThread({ historyStore })` and `useDeepAgentWindowSync({ historyPages })`.
+
+Without a store, nothing changes, and none of the history-page code is bundled.
+
 ## What's new in 0.54.0
 
 **Older history says when it can't go deeper.** Agora holds one connection's loaded history in a document with a size limit (about a thousand messages, ~30% more since agora #50871). The "Load earlier messages" row used to keep a button that the host refused on every press, three times per approach to the top. The first refusal now ends paging for that conversation, and the row reads "Earlier messages can't be loaded here". An edit that shrinks the loaded view opens paging again. `useDeepAgentWindowSync` reports it as `canLoadOlder: false` for hosts that draw their own edge.

package/dist/agent-runtime/src/answer-label.cjs

@@ -85,11 +85,17 @@ function threadShowsAnswerLabels(messages) {
 function showsAnswerLabel({
   answers,
   threadShowsLabels,
-  viewerId
+  viewerId,
+  labelsOtherAgents = false
 }) {
   if (answers.length === 0) return false;
   if (threadShowsLabels) return true;
-  return viewerId !== null && answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId);
+  if (viewerId === null) return false;
+  if (labelsOtherAgents) {
+    const ownAssistant = `${ASSISTANT_AGENT_PREFIX}${viewerId}`;
+    if (answers.some((answer) => answer.agent !== ownAssistant)) return true;
+  }
+  return answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId);
 }
 function answererName(answer) {
   if (answer.agent_name !== null) return answer.agent_name;

package/dist/agent-runtime/src/answer-label.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"answer-label.cjs","sources":["../../../../agent-runtime/src/answer-label.ts"],"sourcesContent":["import { getExternalStoreMessages, type ThreadMessage } from '@assistant-ui/core';\nimport type { LangChainMessage } from '@assistant-ui/react-langgraph';\n\n/**\n * `metadata.custom` key naming the agent that answered an AI message and whom\n * its run worked for (identity v7 D13: \"each answer is labelled with its\n * agent, 'for <author>'\").\n *\n * The backend stamps it on every answer a deep-agent run's model produces\n * (`agora/.../conversation_agents/answer_label.py`), under the\n * `additional_kwargs.metadata` bag the converter exposes as\n * `message.metadata.custom`, and mirrors it onto the live wire once the\n * model's turn lands. Only the server writes it. Answers written before the\n * stamp existed carry none, and get no label.\n */\nexport const ATHENA_ANSWERED_BY_KEY = 'answered_by';\n\n/** The agent that answered and whom its run worked for, as the backend stamps them. */\nexport interface DeepAgentAnsweredBy {\n  /** `collab_agent:<asset id>` for a team agent, `assistant:<principal id>` for someone's own assistant. */\n  agent: string;\n  /** The collab agent's name when it answered; `null` for an assistant, which clients name. */\n  agent_name: string | null;\n  /** Whom the run worked for: a person (`user_…`), an agent's or automation's own run, or nobody (`null`). */\n  for_id: string | null;\n  /** That person's display name when it answered, else `null`. */\n  for_name: string | null;\n}\n\n/** What a label calls someone's own assistant: the managed default agent's product name. */\nexport const ATHENA_ASSISTANT_NAME = 'Athena';\n\nconst ASSISTANT_AGENT_PREFIX = 'assistant:';\nconst PERSON_PRINCIPAL_PREFIX = 'user_';\nconst UNNAMED_AGENT_NAME = 'Agent';\nconst LABEL_SEPARATOR = ' · ';\nconst NO_ANSWERS: readonly DeepAgentAnsweredBy[] = Object.freeze([]);\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\nconst optionalId = (value: unknown): string | null =>\n  typeof value === 'string' && value.length > 0 ? value : null;\n\nconst optionalName = (value: unknown): string | null => {\n  if (typeof value !== 'string') return null;\n  const trimmed = value.trim();\n  return trimmed.length > 0 ? trimmed : null;\n};\n\n/**\n * Parse an `answered_by` stamp off a wire value.\n *\n * A stamp without a string `agent` is no stamp at all; absent or malformed\n * optional fields read as `null`, so a partly malformed stamp still names its\n * agent and never names a person it can't.\n */\nexport function readAnsweredBy(value: unknown): DeepAgentAnsweredBy | null {\n  if (!isRecord(value)) return null;\n  const agent = optionalId(value.agent);\n  if (agent === null) return null;\n  return {\n    agent,\n    agent_name: optionalName(value.agent_name),\n    for_id: optionalId(value.for_id),\n    for_name: optionalName(value.for_name),\n  };\n}\n\n/**\n * The run id an answer's row carries when the deep-agent conversion split a\n * turn several answerers wrote into one row per answerer (`answer-rows.ts`):\n * one per agent and principal.\n */\nconst ANSWER_ROW_RUN_ID_PREFIX = 'answered_by:';\n\n/** The row run id of an answer by `agent` for `forId` (see `withAnswerRows`). */\nexport function answerRowRunId(agent: string, forId: string | null): string {\n  return `${ANSWER_ROW_RUN_ID_PREFIX}${agent}|${forId ?? ''}`;\n}\n\n/**\n * Whether a converted row is one of a turn the conversion split by answerer.\n * Reads `metadata` optionally, as `collectMessageAnswers` does: a message\n * another runtime (or a test) builds may carry none.\n */\nfunction isSplitAnswerRow(message: ThreadMessage): boolean {\n  const runId = message.role === 'assistant' ? message.metadata?.runId : undefined;\n  return typeof runId === 'string' && runId.startsWith(ANSWER_ROW_RUN_ID_PREFIX);\n}\n\nconst isSameAnswerer = (a: DeepAgentAnsweredBy, b: DeepAgentAnsweredBy): boolean =>\n  a.agent === b.agent && a.for_id === b.for_id;\n\nconst isPersonPrincipal = (id: string | null): id is string =>\n  id !== null && id.startsWith(PERSON_PRINCIPAL_PREFIX);\n\n/** The `answered_by` stamp an AI message as the wire carries it holds; `null` for any other message. */\nexport function readLangChainAnswer(\n  source: LangChainMessage | undefined\n): DeepAgentAnsweredBy | null {\n  if (source?.type !== 'ai') return null;\n  const bag = source.additional_kwargs?.metadata;\n  return isRecord(bag) ? readAnsweredBy(bag[ATHENA_ANSWERED_BY_KEY]) : null;\n}\n\nfunction collectMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  if (message.role !== 'assistant') return NO_ANSWERS;\n  const sources = getExternalStoreMessages<LangChainMessage>(message);\n  if (sources.length === 0) {\n    const joined = readAnsweredBy(message.metadata?.custom?.[ATHENA_ANSWERED_BY_KEY]);\n    return joined === null ? NO_ANSWERS : [joined];\n  }\n  let answers: DeepAgentAnsweredBy[] | null = null;\n  for (const source of sources) {\n    const answer = readLangChainAnswer(source);\n    if (answer === null || answers?.some((seen) => isSameAnswerer(seen, answer))) continue;\n    answers ??= [];\n    answers.push(answer);\n  }\n  return answers ?? NO_ANSWERS;\n}\n\nconst answersByMessage = new WeakMap<ThreadMessage, readonly DeepAgentAnsweredBy[]>();\n\n/**\n * The answers one thread message holds: each agent that answered in it and\n * whom it worked for, in the order they answered, one entry per agent and\n * principal.\n *\n * Read off the message's bound source messages, not its joined\n * `metadata.custom`: assistant-ui joins consecutive AI messages into one\n * turn, and its joined metadata keeps only the last stamp. The deep-agent\n * conversion gives each agent that answers one message in turn (D13 several\n * agents, one message) a row of its own (`answer-rows.ts`), so a row\n * normally holds one answer; a conversion without that split (another\n * pipeline, a stamp that never landed) still names every agent of the row.\n * A message with no bound sources (another runtime) falls back to the joined\n * value. Cached per message object: a settled message keeps its object\n * across a streamed token, so a thread-wide scan per token reads only the\n * message that changed.\n */\nexport function readMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  const cached = answersByMessage.get(message);\n  if (cached !== undefined) return cached;\n  const answers = collectMessageAnswers(message);\n  answersByMessage.set(message, answers);\n  return answers;\n}\n\n/**\n * The thread-wide half of the label decision: whether the transcript's\n * answers name two or more agents, or two or more principals they worked\n * for. Then every answer is labelled; a 1:1 chat with one agent working for\n * one person looks as it did before labels. Unstamped answers count for\n * nothing.\n *\n * It decides over the messages the client holds (on a windowed wire, the\n * pages loaded so far), as the human-author avatars do: a page of older\n * history that brings another agent or person turns the labels on. Each\n * label still names its own answer's stamp, so loading history never changes\n * what an answer is attributed to, only whether the line shows.\n *\n * A turn the conversion split into one row per answerer turns the labels on\n * too, before the next agent's stamp lands: while several agents answer one\n * message, the host's record already says a second agent is answering, so\n * the first agent's answer is labelled from the moment the second one's row\n * appears.\n */\nexport function threadShowsAnswerLabels(messages: readonly ThreadMessage[]): boolean {\n  let first: DeepAgentAnsweredBy | null = null;\n  for (const message of messages) {\n    if (isSplitAnswerRow(message)) return true;\n    for (const answer of readMessageAnswers(message)) {\n      if (first === null) {\n        first = answer;\n      } else if (!isSameAnswerer(first, answer)) {\n        return true;\n      }\n    }\n  }\n  return false;\n}\n\n/**\n * Whether a message's answers are labelled: always once the thread's answers\n * name several agents or principals (`threadShowsLabels`), and otherwise when\n * one of them worked for a person other than the viewer. Without a known\n * viewer that last rule is off, so a 1:1 chat never flashes labels while the\n * viewer loads.\n */\nexport function showsAnswerLabel({\n  answers,\n  threadShowsLabels,\n  viewerId,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  threadShowsLabels: boolean;\n  viewerId: string | null;\n}): boolean {\n  if (answers.length === 0) return false;\n  if (threadShowsLabels) return true;\n  return (\n    viewerId !== null &&\n    answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId)\n  );\n}\n\nfunction answererName(answer: DeepAgentAnsweredBy): string {\n  if (answer.agent_name !== null) return answer.agent_name;\n  return answer.agent.startsWith(ASSISTANT_AGENT_PREFIX)\n    ? ATHENA_ASSISTANT_NAME\n    : UNNAMED_AGENT_NAME;\n}\n\nfunction forWhomName(answer: DeepAgentAnsweredBy, viewerId: string | null): string | null {\n  if (answer.for_id !== null && answer.for_id === viewerId) return 'you';\n  if (answer.for_name !== null && isPersonPrincipal(answer.for_id)) return answer.for_name;\n  return null;\n}\n\nfunction joinNames(names: readonly string[]): string {\n  if (names.length <= 1) return names[0] ?? '';\n  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;\n}\n\n/**\n * The label's words: who answered, then whom for. \"Finance · for you\",\n * \"Athena · for Priya Shah\", \"Finance\" (a run that worked for nobody, or for\n * an agent's own run). The agent is the collab agent's name, else\n * {@link ATHENA_ASSISTANT_NAME} for someone's own assistant, else \"Agent\".\n * Several agents answering for the same principal read \"Finance and Legal ·\n * for you\"; answers for different principals are listed apart, even when the\n * people share a name (\"Finance · for Alex, Legal · for Alex\"). `null` when\n * the message holds no answers.\n */\nexport function answerLabelText({\n  answers,\n  viewerId,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  viewerId: string | null;\n}): string | null {\n  if (answers.length === 0) return null;\n  // One group per principal (nobody is one too), never per displayed name: two\n  // people who share a name stay two recipients.\n  const groups: { forId: string | null; names: string[]; forWhom: string | null }[] = [];\n  for (const answer of answers) {\n    const name = answererName(answer);\n    const forWhom = forWhomName(answer, viewerId);\n    const group = groups.find((candidate) => candidate.forId === answer.for_id);\n    if (group === undefined) {\n      groups.push({ forId: answer.for_id, names: [name], forWhom });\n      continue;\n    }\n    if (!group.names.includes(name)) group.names.push(name);\n    // A recipient one answer left unnamed takes the name a later answer for\n    // the same principal carries. The first name found wins: answers stamped\n    // under two names for one id (a rename between runs) read as the first.\n    group.forWhom ??= forWhom;\n  }\n  return groups\n    .map(({ names, forWhom }) =>\n      forWhom === null ? joinNames(names) : `${joinNames(names)}${LABEL_SEPARATOR}for ${forWhom}`\n    )\n    .join(', ');\n}\n"],"names":["getExternalStoreMessages"],"mappings":";;;AAeO,MAAM,yBAAyB;AAe/B,MAAM,wBAAwB;AAErC,MAAM,yBAAyB;AAC/B,MAAM,0BAA0B;AAChC,MAAM,qBAAqB;AAC3B,MAAM,kBAAkB;AACxB,MAAM,aAA6C,OAAO,OAAO,EAAE;AAEnE,MAAM,WAAW,CAAC,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAErE,MAAM,aAAa,CAAC,UAClB,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ;AAE1D,MAAM,eAAe,CAAC,UAAkC;AACtD,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,QAAM,UAAU,MAAM,KAAA;AACtB,SAAO,QAAQ,SAAS,IAAI,UAAU;AACxC;AASO,SAAS,eAAe,OAA4C;AACzE,MAAI,CAAC,SAAS,KAAK,EAAG,QAAO;AAC7B,QAAM,QAAQ,WAAW,MAAM,KAAK;AACpC,MAAI,UAAU,KAAM,QAAO;AAC3B,SAAO;AAAA,IACL;AAAA,IACA,YAAY,aAAa,MAAM,UAAU;AAAA,IACzC,QAAQ,WAAW,MAAM,MAAM;AAAA,IAC/B,UAAU,aAAa,MAAM,QAAQ;AAAA,EAAA;AAEzC;AAOA,MAAM,2BAA2B;AAG1B,SAAS,eAAe,OAAe,OAA8B;AAC1E,SAAO,GAAG,wBAAwB,GAAG,KAAK,IAAI,SAAS,EAAE;AAC3D;AAOA,SAAS,iBAAiB,SAAiC;;AACzD,QAAM,QAAQ,QAAQ,SAAS,eAAc,aAAQ,aAAR,mBAAkB,QAAQ;AACvE,SAAO,OAAO,UAAU,YAAY,MAAM,WAAW,wBAAwB;AAC/E;AAEA,MAAM,iBAAiB,CAAC,GAAwB,MAC9C,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE;AAExC,MAAM,oBAAoB,CAAC,OACzB,OAAO,QAAQ,GAAG,WAAW,uBAAuB;AAG/C,SAAS,oBACd,QAC4B;;AAC5B,OAAI,iCAAQ,UAAS,KAAM,QAAO;AAClC,QAAM,OAAM,YAAO,sBAAP,mBAA0B;AACtC,SAAO,SAAS,GAAG,IAAI,eAAe,IAAI,sBAAsB,CAAC,IAAI;AACvE;AAEA,SAAS,sBAAsB,SAAwD;;AACrF,MAAI,QAAQ,SAAS,YAAa,QAAO;AACzC,QAAM,UAAUA,KAAAA,yBAA2C,OAAO;AAClE,MAAI,QAAQ,WAAW,GAAG;AACxB,UAAM,SAAS,gBAAe,mBAAQ,aAAR,mBAAkB,WAAlB,mBAA2B,uBAAuB;AAChF,WAAO,WAAW,OAAO,aAAa,CAAC,MAAM;AAAA,EAC/C;AACA,MAAI,UAAwC;AAC5C,aAAW,UAAU,SAAS;AAC5B,UAAM,SAAS,oBAAoB,MAAM;AACzC,QAAI,WAAW,SAAQ,mCAAS,KAAK,CAAC,SAAS,eAAe,MAAM,MAAM,IAAI;AAC9E,0BAAY,CAAA;AACZ,YAAQ,KAAK,MAAM;AAAA,EACrB;AACA,SAAO,WAAW;AACpB;AAEA,MAAM,uCAAuB,QAAA;AAmBtB,SAAS,mBAAmB,SAAwD;AACzF,QAAM,SAAS,iBAAiB,IAAI,OAAO;AAC3C,MAAI,WAAW,OAAW,QAAO;AACjC,QAAM,UAAU,sBAAsB,OAAO;AAC7C,mBAAiB,IAAI,SAAS,OAAO;AACrC,SAAO;AACT;AAqBO,SAAS,wBAAwB,UAA6C;AACnF,MAAI,QAAoC;AACxC,aAAW,WAAW,UAAU;AAC9B,QAAI,iBAAiB,OAAO,EAAG,QAAO;AACtC,eAAW,UAAU,mBAAmB,OAAO,GAAG;AAChD,UAAI,UAAU,MAAM;AAClB,gBAAQ;AAAA,MACV,WAAW,CAAC,eAAe,OAAO,MAAM,GAAG;AACzC,eAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AASO,SAAS,iBAAiB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AACF,GAIY;AACV,MAAI,QAAQ,WAAW,EAAG,QAAO;AACjC,MAAI,kBAAmB,QAAO;AAC9B,SACE,aAAa,QACb,QAAQ,KAAK,CAAC,WAAW,kBAAkB,OAAO,MAAM,KAAK,OAAO,WAAW,QAAQ;AAE3F;AAEA,SAAS,aAAa,QAAqC;AACzD,MAAI,OAAO,eAAe,KAAM,QAAO,OAAO;AAC9C,SAAO,OAAO,MAAM,WAAW,sBAAsB,IACjD,wBACA;AACN;AAEA,SAAS,YAAY,QAA6B,UAAwC;AACxF,MAAI,OAAO,WAAW,QAAQ,OAAO,WAAW,SAAU,QAAO;AACjE,MAAI,OAAO,aAAa,QAAQ,kBAAkB,OAAO,MAAM,UAAU,OAAO;AAChF,SAAO;AACT;AAEA,SAAS,UAAU,OAAkC;AACnD,MAAI,MAAM,UAAU,EAAG,QAAO,MAAM,CAAC,KAAK;AAC1C,SAAO,GAAG,MAAM,MAAM,GAAG,EAAE,EAAE,KAAK,IAAI,CAAC,QAAQ,MAAM,MAAM,SAAS,CAAC,CAAC;AACxE;AAYO,SAAS,gBAAgB;AAAA,EAC9B;AAAA,EACA;AACF,GAGkB;AAChB,MAAI,QAAQ,WAAW,EAAG,QAAO;AAGjC,QAAM,SAA8E,CAAA;AACpF,aAAW,UAAU,SAAS;AAC5B,UAAM,OAAO,aAAa,MAAM;AAChC,UAAM,UAAU,YAAY,QAAQ,QAAQ;AAC5C,UAAM,QAAQ,OAAO,KAAK,CAAC,cAAc,UAAU,UAAU,OAAO,MAAM;AAC1E,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,EAAE,OAAO,OAAO,QAAQ,OAAO,CAAC,IAAI,GAAG,SAAS;AAC5D;AAAA,IACF;AACA,QAAI,CAAC,MAAM,MAAM,SAAS,IAAI,EAAG,OAAM,MAAM,KAAK,IAAI;AAItD,UAAM,YAAN,MAAM,UAAY;AAAA,EACpB;AACA,SAAO,OACJ;AAAA,IAAI,CAAC,EAAE,OAAO,QAAA,MACb,YAAY,OAAO,UAAU,KAAK,IAAI,GAAG,UAAU,KAAK,CAAC,GAAG,eAAe,OAAO,OAAO;AAAA,EAAA,EAE1F,KAAK,IAAI;AACd;;;;;;;;;;"}
+{"version":3,"file":"answer-label.cjs","sources":["../../../../agent-runtime/src/answer-label.ts"],"sourcesContent":["import { getExternalStoreMessages, type ThreadMessage } from '@assistant-ui/core';\nimport type { LangChainMessage } from '@assistant-ui/react-langgraph';\n\n/**\n * `metadata.custom` key naming the agent that answered an AI message and whom\n * its run worked for (identity v7 D13: \"each answer is labelled with its\n * agent, 'for <author>'\").\n *\n * The backend stamps it on every answer a deep-agent run's model produces\n * (`agora/.../conversation_agents/answer_label.py`), under the\n * `additional_kwargs.metadata` bag the converter exposes as\n * `message.metadata.custom`, and mirrors it onto the live wire once the\n * model's turn lands. Only the server writes it. Answers written before the\n * stamp existed carry none, and get no label.\n */\nexport const ATHENA_ANSWERED_BY_KEY = 'answered_by';\n\n/** The agent that answered and whom its run worked for, as the backend stamps them. */\nexport interface DeepAgentAnsweredBy {\n  /** `collab_agent:<asset id>` for a team agent, `assistant:<principal id>` for someone's own assistant. */\n  agent: string;\n  /** The collab agent's name when it answered; `null` for an assistant, which clients name. */\n  agent_name: string | null;\n  /** Whom the run worked for: a person (`user_…`), an agent's or automation's own run, or nobody (`null`). */\n  for_id: string | null;\n  /** That person's display name when it answered, else `null`. */\n  for_name: string | null;\n}\n\n/** What a label calls someone's own assistant: the managed default agent's product name. */\nexport const ATHENA_ASSISTANT_NAME = 'Athena';\n\nconst ASSISTANT_AGENT_PREFIX = 'assistant:';\nconst PERSON_PRINCIPAL_PREFIX = 'user_';\nconst UNNAMED_AGENT_NAME = 'Agent';\nconst LABEL_SEPARATOR = ' · ';\nconst NO_ANSWERS: readonly DeepAgentAnsweredBy[] = Object.freeze([]);\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\nconst optionalId = (value: unknown): string | null =>\n  typeof value === 'string' && value.length > 0 ? value : null;\n\nconst optionalName = (value: unknown): string | null => {\n  if (typeof value !== 'string') return null;\n  const trimmed = value.trim();\n  return trimmed.length > 0 ? trimmed : null;\n};\n\n/**\n * Parse an `answered_by` stamp off a wire value.\n *\n * A stamp without a string `agent` is no stamp at all; absent or malformed\n * optional fields read as `null`, so a partly malformed stamp still names its\n * agent and never names a person it can't.\n */\nexport function readAnsweredBy(value: unknown): DeepAgentAnsweredBy | null {\n  if (!isRecord(value)) return null;\n  const agent = optionalId(value.agent);\n  if (agent === null) return null;\n  return {\n    agent,\n    agent_name: optionalName(value.agent_name),\n    for_id: optionalId(value.for_id),\n    for_name: optionalName(value.for_name),\n  };\n}\n\n/**\n * The run id an answer's row carries when the deep-agent conversion split a\n * turn several answerers wrote into one row per answerer (`answer-rows.ts`):\n * one per agent and principal.\n */\nconst ANSWER_ROW_RUN_ID_PREFIX = 'answered_by:';\n\n/** The row run id of an answer by `agent` for `forId` (see `withAnswerRows`). */\nexport function answerRowRunId(agent: string, forId: string | null): string {\n  return `${ANSWER_ROW_RUN_ID_PREFIX}${agent}|${forId ?? ''}`;\n}\n\n/**\n * Whether a converted row is one of a turn the conversion split by answerer.\n * Reads `metadata` optionally, as `collectMessageAnswers` does: a message\n * another runtime (or a test) builds may carry none.\n */\nfunction isSplitAnswerRow(message: ThreadMessage): boolean {\n  const runId = message.role === 'assistant' ? message.metadata?.runId : undefined;\n  return typeof runId === 'string' && runId.startsWith(ANSWER_ROW_RUN_ID_PREFIX);\n}\n\nconst isSameAnswerer = (a: DeepAgentAnsweredBy, b: DeepAgentAnsweredBy): boolean =>\n  a.agent === b.agent && a.for_id === b.for_id;\n\nconst isPersonPrincipal = (id: string | null): id is string =>\n  id !== null && id.startsWith(PERSON_PRINCIPAL_PREFIX);\n\n/** The `answered_by` stamp an AI message as the wire carries it holds; `null` for any other message. */\nexport function readLangChainAnswer(\n  source: LangChainMessage | undefined\n): DeepAgentAnsweredBy | null {\n  if (source?.type !== 'ai') return null;\n  const bag = source.additional_kwargs?.metadata;\n  return isRecord(bag) ? readAnsweredBy(bag[ATHENA_ANSWERED_BY_KEY]) : null;\n}\n\nfunction collectMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  if (message.role !== 'assistant') return NO_ANSWERS;\n  const sources = getExternalStoreMessages<LangChainMessage>(message);\n  if (sources.length === 0) {\n    const joined = readAnsweredBy(message.metadata?.custom?.[ATHENA_ANSWERED_BY_KEY]);\n    return joined === null ? NO_ANSWERS : [joined];\n  }\n  let answers: DeepAgentAnsweredBy[] | null = null;\n  for (const source of sources) {\n    const answer = readLangChainAnswer(source);\n    if (answer === null || answers?.some((seen) => isSameAnswerer(seen, answer))) continue;\n    answers ??= [];\n    answers.push(answer);\n  }\n  return answers ?? NO_ANSWERS;\n}\n\nconst answersByMessage = new WeakMap<ThreadMessage, readonly DeepAgentAnsweredBy[]>();\n\n/**\n * The answers one thread message holds: each agent that answered in it and\n * whom it worked for, in the order they answered, one entry per agent and\n * principal.\n *\n * Read off the message's bound source messages, not its joined\n * `metadata.custom`: assistant-ui joins consecutive AI messages into one\n * turn, and its joined metadata keeps only the last stamp. The deep-agent\n * conversion gives each agent that answers one message in turn (D13 several\n * agents, one message) a row of its own (`answer-rows.ts`), so a row\n * normally holds one answer; a conversion without that split (another\n * pipeline, a stamp that never landed) still names every agent of the row.\n * A message with no bound sources (another runtime) falls back to the joined\n * value. Cached per message object: a settled message keeps its object\n * across a streamed token, so a thread-wide scan per token reads only the\n * message that changed.\n */\nexport function readMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  const cached = answersByMessage.get(message);\n  if (cached !== undefined) return cached;\n  const answers = collectMessageAnswers(message);\n  answersByMessage.set(message, answers);\n  return answers;\n}\n\n/**\n * The thread-wide half of the label decision: whether the transcript's\n * answers name two or more agents, or two or more principals they worked\n * for. Then every answer is labelled; a 1:1 chat with one agent working for\n * one person looks as it did before labels. Unstamped answers count for\n * nothing.\n *\n * It decides over the messages the client holds (on a windowed wire, the\n * pages loaded so far), as the human-author avatars do: a page of older\n * history that brings another agent or person turns the labels on. Each\n * label still names its own answer's stamp, so loading history never changes\n * what an answer is attributed to, only whether the line shows.\n *\n * A turn the conversion split into one row per answerer turns the labels on\n * too, before the next agent's stamp lands: while several agents answer one\n * message, the host's record already says a second agent is answering, so\n * the first agent's answer is labelled from the moment the second one's row\n * appears.\n */\nexport function threadShowsAnswerLabels(messages: readonly ThreadMessage[]): boolean {\n  let first: DeepAgentAnsweredBy | null = null;\n  for (const message of messages) {\n    if (isSplitAnswerRow(message)) return true;\n    for (const answer of readMessageAnswers(message)) {\n      if (first === null) {\n        first = answer;\n      } else if (!isSameAnswerer(first, answer)) {\n        return true;\n      }\n    }\n  }\n  return false;\n}\n\n/**\n * Whether a message's answers are labelled: always once the thread's answers\n * name several agents or principals (`threadShowsLabels`), and otherwise when\n * one of them worked for a person other than the viewer. With\n * `labelsOtherAgents`, also when one of them was written by any agent other\n * than the viewer's own assistant: a surface where the person names a team\n * agent for one message (Olympus's composer chips) shows who answered it even\n * in a 1:1 chat, where the answer would otherwise read as Athena's. Without a\n * known viewer both viewer rules are off, so a 1:1 chat never flashes labels\n * while the viewer loads.\n */\nexport function showsAnswerLabel({\n  answers,\n  threadShowsLabels,\n  viewerId,\n  labelsOtherAgents = false,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  threadShowsLabels: boolean;\n  viewerId: string | null;\n  /** Label an answer written by any agent other than the viewer's own assistant. */\n  labelsOtherAgents?: boolean;\n}): boolean {\n  if (answers.length === 0) return false;\n  if (threadShowsLabels) return true;\n  if (viewerId === null) return false;\n  if (labelsOtherAgents) {\n    const ownAssistant = `${ASSISTANT_AGENT_PREFIX}${viewerId}`;\n    if (answers.some((answer) => answer.agent !== ownAssistant)) return true;\n  }\n  return answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId);\n}\n\nfunction answererName(answer: DeepAgentAnsweredBy): string {\n  if (answer.agent_name !== null) return answer.agent_name;\n  return answer.agent.startsWith(ASSISTANT_AGENT_PREFIX)\n    ? ATHENA_ASSISTANT_NAME\n    : UNNAMED_AGENT_NAME;\n}\n\nfunction forWhomName(answer: DeepAgentAnsweredBy, viewerId: string | null): string | null {\n  if (answer.for_id !== null && answer.for_id === viewerId) return 'you';\n  if (answer.for_name !== null && isPersonPrincipal(answer.for_id)) return answer.for_name;\n  return null;\n}\n\nfunction joinNames(names: readonly string[]): string {\n  if (names.length <= 1) return names[0] ?? '';\n  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;\n}\n\n/**\n * The label's words: who answered, then whom for. \"Finance · for you\",\n * \"Athena · for Priya Shah\", \"Finance\" (a run that worked for nobody, or for\n * an agent's own run). The agent is the collab agent's name, else\n * {@link ATHENA_ASSISTANT_NAME} for someone's own assistant, else \"Agent\".\n * Several agents answering for the same principal read \"Finance and Legal ·\n * for you\"; answers for different principals are listed apart, even when the\n * people share a name (\"Finance · for Alex, Legal · for Alex\"). `null` when\n * the message holds no answers.\n */\nexport function answerLabelText({\n  answers,\n  viewerId,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  viewerId: string | null;\n}): string | null {\n  if (answers.length === 0) return null;\n  // One group per principal (nobody is one too), never per displayed name: two\n  // people who share a name stay two recipients.\n  const groups: { forId: string | null; names: string[]; forWhom: string | null }[] = [];\n  for (const answer of answers) {\n    const name = answererName(answer);\n    const forWhom = forWhomName(answer, viewerId);\n    const group = groups.find((candidate) => candidate.forId === answer.for_id);\n    if (group === undefined) {\n      groups.push({ forId: answer.for_id, names: [name], forWhom });\n      continue;\n    }\n    if (!group.names.includes(name)) group.names.push(name);\n    // A recipient one answer left unnamed takes the name a later answer for\n    // the same principal carries. The first name found wins: answers stamped\n    // under two names for one id (a rename between runs) read as the first.\n    group.forWhom ??= forWhom;\n  }\n  return groups\n    .map(({ names, forWhom }) =>\n      forWhom === null ? joinNames(names) : `${joinNames(names)}${LABEL_SEPARATOR}for ${forWhom}`\n    )\n    .join(', ');\n}\n"],"names":["getExternalStoreMessages"],"mappings":"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"}

package/dist/agent-runtime/src/answer-label.d.ts

@@ -79,14 +79,20 @@ export declare function threadShowsAnswerLabels(messages: readonly ThreadMessage
 /**
  * Whether a message's answers are labelled: always once the thread's answers
  * name several agents or principals (`threadShowsLabels`), and otherwise when
- * one of them worked for a person other than the viewer. Without a known
- * viewer that last rule is off, so a 1:1 chat never flashes labels while the
- * viewer loads.
+ * one of them worked for a person other than the viewer. With
+ * `labelsOtherAgents`, also when one of them was written by any agent other
+ * than the viewer's own assistant: a surface where the person names a team
+ * agent for one message (Olympus's composer chips) shows who answered it even
+ * in a 1:1 chat, where the answer would otherwise read as Athena's. Without a
+ * known viewer both viewer rules are off, so a 1:1 chat never flashes labels
+ * while the viewer loads.
  */
-export declare function showsAnswerLabel({ answers, threadShowsLabels, viewerId, }: {
+export declare function showsAnswerLabel({ answers, threadShowsLabels, viewerId, labelsOtherAgents, }: {
     answers: readonly DeepAgentAnsweredBy[];
     threadShowsLabels: boolean;
     viewerId: string | null;
+    /** Label an answer written by any agent other than the viewer's own assistant. */
+    labelsOtherAgents?: boolean;
 }): boolean;
 /**
  * The label's words: who answered, then whom for. "Finance · for you",

package/dist/agent-runtime/src/answer-label.js

@@ -83,11 +83,17 @@ function threadShowsAnswerLabels(messages) {
 function showsAnswerLabel({
   answers,
   threadShowsLabels,
-  viewerId
+  viewerId,
+  labelsOtherAgents = false
 }) {
   if (answers.length === 0) return false;
   if (threadShowsLabels) return true;
-  return viewerId !== null && answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId);
+  if (viewerId === null) return false;
+  if (labelsOtherAgents) {
+    const ownAssistant = `${ASSISTANT_AGENT_PREFIX}${viewerId}`;
+    if (answers.some((answer) => answer.agent !== ownAssistant)) return true;
+  }
+  return answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId);
 }
 function answererName(answer) {
   if (answer.agent_name !== null) return answer.agent_name;

package/dist/agent-runtime/src/answer-label.js.map

@@ -1 +1 @@
-{"version":3,"file":"answer-label.js","sources":["../../../../agent-runtime/src/answer-label.ts"],"sourcesContent":["import { getExternalStoreMessages, type ThreadMessage } from '@assistant-ui/core';\nimport type { LangChainMessage } from '@assistant-ui/react-langgraph';\n\n/**\n * `metadata.custom` key naming the agent that answered an AI message and whom\n * its run worked for (identity v7 D13: \"each answer is labelled with its\n * agent, 'for <author>'\").\n *\n * The backend stamps it on every answer a deep-agent run's model produces\n * (`agora/.../conversation_agents/answer_label.py`), under the\n * `additional_kwargs.metadata` bag the converter exposes as\n * `message.metadata.custom`, and mirrors it onto the live wire once the\n * model's turn lands. Only the server writes it. Answers written before the\n * stamp existed carry none, and get no label.\n */\nexport const ATHENA_ANSWERED_BY_KEY = 'answered_by';\n\n/** The agent that answered and whom its run worked for, as the backend stamps them. */\nexport interface DeepAgentAnsweredBy {\n  /** `collab_agent:<asset id>` for a team agent, `assistant:<principal id>` for someone's own assistant. */\n  agent: string;\n  /** The collab agent's name when it answered; `null` for an assistant, which clients name. */\n  agent_name: string | null;\n  /** Whom the run worked for: a person (`user_…`), an agent's or automation's own run, or nobody (`null`). */\n  for_id: string | null;\n  /** That person's display name when it answered, else `null`. */\n  for_name: string | null;\n}\n\n/** What a label calls someone's own assistant: the managed default agent's product name. */\nexport const ATHENA_ASSISTANT_NAME = 'Athena';\n\nconst ASSISTANT_AGENT_PREFIX = 'assistant:';\nconst PERSON_PRINCIPAL_PREFIX = 'user_';\nconst UNNAMED_AGENT_NAME = 'Agent';\nconst LABEL_SEPARATOR = ' · ';\nconst NO_ANSWERS: readonly DeepAgentAnsweredBy[] = Object.freeze([]);\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\nconst optionalId = (value: unknown): string | null =>\n  typeof value === 'string' && value.length > 0 ? value : null;\n\nconst optionalName = (value: unknown): string | null => {\n  if (typeof value !== 'string') return null;\n  const trimmed = value.trim();\n  return trimmed.length > 0 ? trimmed : null;\n};\n\n/**\n * Parse an `answered_by` stamp off a wire value.\n *\n * A stamp without a string `agent` is no stamp at all; absent or malformed\n * optional fields read as `null`, so a partly malformed stamp still names its\n * agent and never names a person it can't.\n */\nexport function readAnsweredBy(value: unknown): DeepAgentAnsweredBy | null {\n  if (!isRecord(value)) return null;\n  const agent = optionalId(value.agent);\n  if (agent === null) return null;\n  return {\n    agent,\n    agent_name: optionalName(value.agent_name),\n    for_id: optionalId(value.for_id),\n    for_name: optionalName(value.for_name),\n  };\n}\n\n/**\n * The run id an answer's row carries when the deep-agent conversion split a\n * turn several answerers wrote into one row per answerer (`answer-rows.ts`):\n * one per agent and principal.\n */\nconst ANSWER_ROW_RUN_ID_PREFIX = 'answered_by:';\n\n/** The row run id of an answer by `agent` for `forId` (see `withAnswerRows`). */\nexport function answerRowRunId(agent: string, forId: string | null): string {\n  return `${ANSWER_ROW_RUN_ID_PREFIX}${agent}|${forId ?? ''}`;\n}\n\n/**\n * Whether a converted row is one of a turn the conversion split by answerer.\n * Reads `metadata` optionally, as `collectMessageAnswers` does: a message\n * another runtime (or a test) builds may carry none.\n */\nfunction isSplitAnswerRow(message: ThreadMessage): boolean {\n  const runId = message.role === 'assistant' ? message.metadata?.runId : undefined;\n  return typeof runId === 'string' && runId.startsWith(ANSWER_ROW_RUN_ID_PREFIX);\n}\n\nconst isSameAnswerer = (a: DeepAgentAnsweredBy, b: DeepAgentAnsweredBy): boolean =>\n  a.agent === b.agent && a.for_id === b.for_id;\n\nconst isPersonPrincipal = (id: string | null): id is string =>\n  id !== null && id.startsWith(PERSON_PRINCIPAL_PREFIX);\n\n/** The `answered_by` stamp an AI message as the wire carries it holds; `null` for any other message. */\nexport function readLangChainAnswer(\n  source: LangChainMessage | undefined\n): DeepAgentAnsweredBy | null {\n  if (source?.type !== 'ai') return null;\n  const bag = source.additional_kwargs?.metadata;\n  return isRecord(bag) ? readAnsweredBy(bag[ATHENA_ANSWERED_BY_KEY]) : null;\n}\n\nfunction collectMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  if (message.role !== 'assistant') return NO_ANSWERS;\n  const sources = getExternalStoreMessages<LangChainMessage>(message);\n  if (sources.length === 0) {\n    const joined = readAnsweredBy(message.metadata?.custom?.[ATHENA_ANSWERED_BY_KEY]);\n    return joined === null ? NO_ANSWERS : [joined];\n  }\n  let answers: DeepAgentAnsweredBy[] | null = null;\n  for (const source of sources) {\n    const answer = readLangChainAnswer(source);\n    if (answer === null || answers?.some((seen) => isSameAnswerer(seen, answer))) continue;\n    answers ??= [];\n    answers.push(answer);\n  }\n  return answers ?? NO_ANSWERS;\n}\n\nconst answersByMessage = new WeakMap<ThreadMessage, readonly DeepAgentAnsweredBy[]>();\n\n/**\n * The answers one thread message holds: each agent that answered in it and\n * whom it worked for, in the order they answered, one entry per agent and\n * principal.\n *\n * Read off the message's bound source messages, not its joined\n * `metadata.custom`: assistant-ui joins consecutive AI messages into one\n * turn, and its joined metadata keeps only the last stamp. The deep-agent\n * conversion gives each agent that answers one message in turn (D13 several\n * agents, one message) a row of its own (`answer-rows.ts`), so a row\n * normally holds one answer; a conversion without that split (another\n * pipeline, a stamp that never landed) still names every agent of the row.\n * A message with no bound sources (another runtime) falls back to the joined\n * value. Cached per message object: a settled message keeps its object\n * across a streamed token, so a thread-wide scan per token reads only the\n * message that changed.\n */\nexport function readMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  const cached = answersByMessage.get(message);\n  if (cached !== undefined) return cached;\n  const answers = collectMessageAnswers(message);\n  answersByMessage.set(message, answers);\n  return answers;\n}\n\n/**\n * The thread-wide half of the label decision: whether the transcript's\n * answers name two or more agents, or two or more principals they worked\n * for. Then every answer is labelled; a 1:1 chat with one agent working for\n * one person looks as it did before labels. Unstamped answers count for\n * nothing.\n *\n * It decides over the messages the client holds (on a windowed wire, the\n * pages loaded so far), as the human-author avatars do: a page of older\n * history that brings another agent or person turns the labels on. Each\n * label still names its own answer's stamp, so loading history never changes\n * what an answer is attributed to, only whether the line shows.\n *\n * A turn the conversion split into one row per answerer turns the labels on\n * too, before the next agent's stamp lands: while several agents answer one\n * message, the host's record already says a second agent is answering, so\n * the first agent's answer is labelled from the moment the second one's row\n * appears.\n */\nexport function threadShowsAnswerLabels(messages: readonly ThreadMessage[]): boolean {\n  let first: DeepAgentAnsweredBy | null = null;\n  for (const message of messages) {\n    if (isSplitAnswerRow(message)) return true;\n    for (const answer of readMessageAnswers(message)) {\n      if (first === null) {\n        first = answer;\n      } else if (!isSameAnswerer(first, answer)) {\n        return true;\n      }\n    }\n  }\n  return false;\n}\n\n/**\n * Whether a message's answers are labelled: always once the thread's answers\n * name several agents or principals (`threadShowsLabels`), and otherwise when\n * one of them worked for a person other than the viewer. Without a known\n * viewer that last rule is off, so a 1:1 chat never flashes labels while the\n * viewer loads.\n */\nexport function showsAnswerLabel({\n  answers,\n  threadShowsLabels,\n  viewerId,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  threadShowsLabels: boolean;\n  viewerId: string | null;\n}): boolean {\n  if (answers.length === 0) return false;\n  if (threadShowsLabels) return true;\n  return (\n    viewerId !== null &&\n    answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId)\n  );\n}\n\nfunction answererName(answer: DeepAgentAnsweredBy): string {\n  if (answer.agent_name !== null) return answer.agent_name;\n  return answer.agent.startsWith(ASSISTANT_AGENT_PREFIX)\n    ? ATHENA_ASSISTANT_NAME\n    : UNNAMED_AGENT_NAME;\n}\n\nfunction forWhomName(answer: DeepAgentAnsweredBy, viewerId: string | null): string | null {\n  if (answer.for_id !== null && answer.for_id === viewerId) return 'you';\n  if (answer.for_name !== null && isPersonPrincipal(answer.for_id)) return answer.for_name;\n  return null;\n}\n\nfunction joinNames(names: readonly string[]): string {\n  if (names.length <= 1) return names[0] ?? '';\n  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;\n}\n\n/**\n * The label's words: who answered, then whom for. \"Finance · for you\",\n * \"Athena · for Priya Shah\", \"Finance\" (a run that worked for nobody, or for\n * an agent's own run). The agent is the collab agent's name, else\n * {@link ATHENA_ASSISTANT_NAME} for someone's own assistant, else \"Agent\".\n * Several agents answering for the same principal read \"Finance and Legal ·\n * for you\"; answers for different principals are listed apart, even when the\n * people share a name (\"Finance · for Alex, Legal · for Alex\"). `null` when\n * the message holds no answers.\n */\nexport function answerLabelText({\n  answers,\n  viewerId,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  viewerId: string | null;\n}): string | null {\n  if (answers.length === 0) return null;\n  // One group per principal (nobody is one too), never per displayed name: two\n  // people who share a name stay two recipients.\n  const groups: { forId: string | null; names: string[]; forWhom: string | null }[] = [];\n  for (const answer of answers) {\n    const name = answererName(answer);\n    const forWhom = forWhomName(answer, viewerId);\n    const group = groups.find((candidate) => candidate.forId === answer.for_id);\n    if (group === undefined) {\n      groups.push({ forId: answer.for_id, names: [name], forWhom });\n      continue;\n    }\n    if (!group.names.includes(name)) group.names.push(name);\n    // A recipient one answer left unnamed takes the name a later answer for\n    // the same principal carries. The first name found wins: answers stamped\n    // under two names for one id (a rename between runs) read as the first.\n    group.forWhom ??= forWhom;\n  }\n  return groups\n    .map(({ names, forWhom }) =>\n      forWhom === null ? joinNames(names) : `${joinNames(names)}${LABEL_SEPARATOR}for ${forWhom}`\n    )\n    .join(', ');\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"answer-label.js","sources":["../../../../agent-runtime/src/answer-label.ts"],"sourcesContent":["import { getExternalStoreMessages, type ThreadMessage } from '@assistant-ui/core';\nimport type { LangChainMessage } from '@assistant-ui/react-langgraph';\n\n/**\n * `metadata.custom` key naming the agent that answered an AI message and whom\n * its run worked for (identity v7 D13: \"each answer is labelled with its\n * agent, 'for <author>'\").\n *\n * The backend stamps it on every answer a deep-agent run's model produces\n * (`agora/.../conversation_agents/answer_label.py`), under the\n * `additional_kwargs.metadata` bag the converter exposes as\n * `message.metadata.custom`, and mirrors it onto the live wire once the\n * model's turn lands. Only the server writes it. Answers written before the\n * stamp existed carry none, and get no label.\n */\nexport const ATHENA_ANSWERED_BY_KEY = 'answered_by';\n\n/** The agent that answered and whom its run worked for, as the backend stamps them. */\nexport interface DeepAgentAnsweredBy {\n  /** `collab_agent:<asset id>` for a team agent, `assistant:<principal id>` for someone's own assistant. */\n  agent: string;\n  /** The collab agent's name when it answered; `null` for an assistant, which clients name. */\n  agent_name: string | null;\n  /** Whom the run worked for: a person (`user_…`), an agent's or automation's own run, or nobody (`null`). */\n  for_id: string | null;\n  /** That person's display name when it answered, else `null`. */\n  for_name: string | null;\n}\n\n/** What a label calls someone's own assistant: the managed default agent's product name. */\nexport const ATHENA_ASSISTANT_NAME = 'Athena';\n\nconst ASSISTANT_AGENT_PREFIX = 'assistant:';\nconst PERSON_PRINCIPAL_PREFIX = 'user_';\nconst UNNAMED_AGENT_NAME = 'Agent';\nconst LABEL_SEPARATOR = ' · ';\nconst NO_ANSWERS: readonly DeepAgentAnsweredBy[] = Object.freeze([]);\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\nconst optionalId = (value: unknown): string | null =>\n  typeof value === 'string' && value.length > 0 ? value : null;\n\nconst optionalName = (value: unknown): string | null => {\n  if (typeof value !== 'string') return null;\n  const trimmed = value.trim();\n  return trimmed.length > 0 ? trimmed : null;\n};\n\n/**\n * Parse an `answered_by` stamp off a wire value.\n *\n * A stamp without a string `agent` is no stamp at all; absent or malformed\n * optional fields read as `null`, so a partly malformed stamp still names its\n * agent and never names a person it can't.\n */\nexport function readAnsweredBy(value: unknown): DeepAgentAnsweredBy | null {\n  if (!isRecord(value)) return null;\n  const agent = optionalId(value.agent);\n  if (agent === null) return null;\n  return {\n    agent,\n    agent_name: optionalName(value.agent_name),\n    for_id: optionalId(value.for_id),\n    for_name: optionalName(value.for_name),\n  };\n}\n\n/**\n * The run id an answer's row carries when the deep-agent conversion split a\n * turn several answerers wrote into one row per answerer (`answer-rows.ts`):\n * one per agent and principal.\n */\nconst ANSWER_ROW_RUN_ID_PREFIX = 'answered_by:';\n\n/** The row run id of an answer by `agent` for `forId` (see `withAnswerRows`). */\nexport function answerRowRunId(agent: string, forId: string | null): string {\n  return `${ANSWER_ROW_RUN_ID_PREFIX}${agent}|${forId ?? ''}`;\n}\n\n/**\n * Whether a converted row is one of a turn the conversion split by answerer.\n * Reads `metadata` optionally, as `collectMessageAnswers` does: a message\n * another runtime (or a test) builds may carry none.\n */\nfunction isSplitAnswerRow(message: ThreadMessage): boolean {\n  const runId = message.role === 'assistant' ? message.metadata?.runId : undefined;\n  return typeof runId === 'string' && runId.startsWith(ANSWER_ROW_RUN_ID_PREFIX);\n}\n\nconst isSameAnswerer = (a: DeepAgentAnsweredBy, b: DeepAgentAnsweredBy): boolean =>\n  a.agent === b.agent && a.for_id === b.for_id;\n\nconst isPersonPrincipal = (id: string | null): id is string =>\n  id !== null && id.startsWith(PERSON_PRINCIPAL_PREFIX);\n\n/** The `answered_by` stamp an AI message as the wire carries it holds; `null` for any other message. */\nexport function readLangChainAnswer(\n  source: LangChainMessage | undefined\n): DeepAgentAnsweredBy | null {\n  if (source?.type !== 'ai') return null;\n  const bag = source.additional_kwargs?.metadata;\n  return isRecord(bag) ? readAnsweredBy(bag[ATHENA_ANSWERED_BY_KEY]) : null;\n}\n\nfunction collectMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  if (message.role !== 'assistant') return NO_ANSWERS;\n  const sources = getExternalStoreMessages<LangChainMessage>(message);\n  if (sources.length === 0) {\n    const joined = readAnsweredBy(message.metadata?.custom?.[ATHENA_ANSWERED_BY_KEY]);\n    return joined === null ? NO_ANSWERS : [joined];\n  }\n  let answers: DeepAgentAnsweredBy[] | null = null;\n  for (const source of sources) {\n    const answer = readLangChainAnswer(source);\n    if (answer === null || answers?.some((seen) => isSameAnswerer(seen, answer))) continue;\n    answers ??= [];\n    answers.push(answer);\n  }\n  return answers ?? NO_ANSWERS;\n}\n\nconst answersByMessage = new WeakMap<ThreadMessage, readonly DeepAgentAnsweredBy[]>();\n\n/**\n * The answers one thread message holds: each agent that answered in it and\n * whom it worked for, in the order they answered, one entry per agent and\n * principal.\n *\n * Read off the message's bound source messages, not its joined\n * `metadata.custom`: assistant-ui joins consecutive AI messages into one\n * turn, and its joined metadata keeps only the last stamp. The deep-agent\n * conversion gives each agent that answers one message in turn (D13 several\n * agents, one message) a row of its own (`answer-rows.ts`), so a row\n * normally holds one answer; a conversion without that split (another\n * pipeline, a stamp that never landed) still names every agent of the row.\n * A message with no bound sources (another runtime) falls back to the joined\n * value. Cached per message object: a settled message keeps its object\n * across a streamed token, so a thread-wide scan per token reads only the\n * message that changed.\n */\nexport function readMessageAnswers(message: ThreadMessage): readonly DeepAgentAnsweredBy[] {\n  const cached = answersByMessage.get(message);\n  if (cached !== undefined) return cached;\n  const answers = collectMessageAnswers(message);\n  answersByMessage.set(message, answers);\n  return answers;\n}\n\n/**\n * The thread-wide half of the label decision: whether the transcript's\n * answers name two or more agents, or two or more principals they worked\n * for. Then every answer is labelled; a 1:1 chat with one agent working for\n * one person looks as it did before labels. Unstamped answers count for\n * nothing.\n *\n * It decides over the messages the client holds (on a windowed wire, the\n * pages loaded so far), as the human-author avatars do: a page of older\n * history that brings another agent or person turns the labels on. Each\n * label still names its own answer's stamp, so loading history never changes\n * what an answer is attributed to, only whether the line shows.\n *\n * A turn the conversion split into one row per answerer turns the labels on\n * too, before the next agent's stamp lands: while several agents answer one\n * message, the host's record already says a second agent is answering, so\n * the first agent's answer is labelled from the moment the second one's row\n * appears.\n */\nexport function threadShowsAnswerLabels(messages: readonly ThreadMessage[]): boolean {\n  let first: DeepAgentAnsweredBy | null = null;\n  for (const message of messages) {\n    if (isSplitAnswerRow(message)) return true;\n    for (const answer of readMessageAnswers(message)) {\n      if (first === null) {\n        first = answer;\n      } else if (!isSameAnswerer(first, answer)) {\n        return true;\n      }\n    }\n  }\n  return false;\n}\n\n/**\n * Whether a message's answers are labelled: always once the thread's answers\n * name several agents or principals (`threadShowsLabels`), and otherwise when\n * one of them worked for a person other than the viewer. With\n * `labelsOtherAgents`, also when one of them was written by any agent other\n * than the viewer's own assistant: a surface where the person names a team\n * agent for one message (Olympus's composer chips) shows who answered it even\n * in a 1:1 chat, where the answer would otherwise read as Athena's. Without a\n * known viewer both viewer rules are off, so a 1:1 chat never flashes labels\n * while the viewer loads.\n */\nexport function showsAnswerLabel({\n  answers,\n  threadShowsLabels,\n  viewerId,\n  labelsOtherAgents = false,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  threadShowsLabels: boolean;\n  viewerId: string | null;\n  /** Label an answer written by any agent other than the viewer's own assistant. */\n  labelsOtherAgents?: boolean;\n}): boolean {\n  if (answers.length === 0) return false;\n  if (threadShowsLabels) return true;\n  if (viewerId === null) return false;\n  if (labelsOtherAgents) {\n    const ownAssistant = `${ASSISTANT_AGENT_PREFIX}${viewerId}`;\n    if (answers.some((answer) => answer.agent !== ownAssistant)) return true;\n  }\n  return answers.some((answer) => isPersonPrincipal(answer.for_id) && answer.for_id !== viewerId);\n}\n\nfunction answererName(answer: DeepAgentAnsweredBy): string {\n  if (answer.agent_name !== null) return answer.agent_name;\n  return answer.agent.startsWith(ASSISTANT_AGENT_PREFIX)\n    ? ATHENA_ASSISTANT_NAME\n    : UNNAMED_AGENT_NAME;\n}\n\nfunction forWhomName(answer: DeepAgentAnsweredBy, viewerId: string | null): string | null {\n  if (answer.for_id !== null && answer.for_id === viewerId) return 'you';\n  if (answer.for_name !== null && isPersonPrincipal(answer.for_id)) return answer.for_name;\n  return null;\n}\n\nfunction joinNames(names: readonly string[]): string {\n  if (names.length <= 1) return names[0] ?? '';\n  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;\n}\n\n/**\n * The label's words: who answered, then whom for. \"Finance · for you\",\n * \"Athena · for Priya Shah\", \"Finance\" (a run that worked for nobody, or for\n * an agent's own run). The agent is the collab agent's name, else\n * {@link ATHENA_ASSISTANT_NAME} for someone's own assistant, else \"Agent\".\n * Several agents answering for the same principal read \"Finance and Legal ·\n * for you\"; answers for different principals are listed apart, even when the\n * people share a name (\"Finance · for Alex, Legal · for Alex\"). `null` when\n * the message holds no answers.\n */\nexport function answerLabelText({\n  answers,\n  viewerId,\n}: {\n  answers: readonly DeepAgentAnsweredBy[];\n  viewerId: string | null;\n}): string | null {\n  if (answers.length === 0) return null;\n  // One group per principal (nobody is one too), never per displayed name: two\n  // people who share a name stay two recipients.\n  const groups: { forId: string | null; names: string[]; forWhom: string | null }[] = [];\n  for (const answer of answers) {\n    const name = answererName(answer);\n    const forWhom = forWhomName(answer, viewerId);\n    const group = groups.find((candidate) => candidate.forId === answer.for_id);\n    if (group === undefined) {\n      groups.push({ forId: answer.for_id, names: [name], forWhom });\n      continue;\n    }\n    if (!group.names.includes(name)) group.names.push(name);\n    // A recipient one answer left unnamed takes the name a later answer for\n    // the same principal carries. The first name found wins: answers stamped\n    // under two names for one id (a rename between runs) read as the first.\n    group.forWhom ??= forWhom;\n  }\n  return groups\n    .map(({ names, forWhom }) =>\n      forWhom === null ? joinNames(names) : `${joinNames(names)}${LABEL_SEPARATOR}for ${forWhom}`\n    )\n    .join(', ');\n}\n"],"names":[],"mappings":"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"}

package/dist/agent-runtime/src/deep-agent-transport-recipe.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const messageWindow = require("./message-window.cjs");
+const historyStore = require("./history-store.cjs");
 const protocol = require("./protocol.cjs");
 const statewireAttachObserver = require("./statewire-attach-observer.cjs");
 const statewireTransport = require("./statewire-transport.cjs");
@@ -39,9 +40,11 @@ function createDeepAgentAttachTransport({
       await retryGate.waitForDial(url);
       onAuthResolve == null ? void 0 : onAuthResolve(ctx);
       return messageWindow.withDeclaredInterests(
-        messageWindow.withDeclaredMessageWindow(
-          protocol.withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),
-          messageWindow$1
+        historyStore.withDeclaredPagedHistory(
+          messageWindow.withDeclaredMessageWindow(
+            protocol.withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),
+            messageWindow$1
+          )
         ),
         (declaredInterests == null ? void 0 : declaredInterests()) ?? null
       );

package/dist/agent-runtime/src/deep-agent-transport-recipe.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"deep-agent-transport-recipe.cjs","sources":["../../../../agent-runtime/src/deep-agent-transport-recipe.ts"],"sourcesContent":["import type { ResourceElement } from \"@assistant-ui/tap\";\nimport type { Statewire, StatewireClient } from \"statewire\";\nimport {\n  type DeepAgentInterestDeclaration,\n  type DeepAgentMessageWindowDeclaration,\n  withDeclaredInterests,\n  withDeclaredMessageWindow,\n} from \"./message-window\";\nimport { withDeclaredProtocolVersion } from \"./protocol\";\nimport {\n  attachRetryGate,\n  type AttachRetryGate,\n  createAttachInstrumentation,\n  type DeepAgentAttachTimingEvent,\n  type DeepAgentWakeRefusal,\n  parseRetryAfterHeaderMs,\n} from \"./statewire-attach-observer\";\nimport {\n  resolveStatewireTransportKind,\n  statewireTransport,\n  type StatewireTransportOptions,\n} from \"./statewire-transport\";\n\n/** Auth-header resolver for the transport; `staleAuth` is true right after an\n * auth rejection, so resolvers that can force-renew should honor it. */\nexport type DeepAgentHeadersResolver = (ctx: {\n  staleAuth: boolean;\n}) => Record<string, string> | Promise<Record<string, string>>;\n\n/** The statewire attach URL for a thread: the host's `…/v2/threads` mount plus the id. */\nexport function deepAgentThreadUrl({\n  baseUrl,\n  threadId,\n}: {\n  baseUrl: string;\n  threadId: string;\n}): string {\n  return `${baseUrl.replace(/\\/+$/, \"\")}/${encodeURIComponent(threadId)}`;\n}\n\nexport interface DeepAgentAttachTransportOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  /** SSE when true, WebSocket otherwise (`resolveStatewireTransportKind`). */\n  sse?: boolean;\n  /** A never-started chat: the transport makes no network calls until the first command send. */\n  isNew?: boolean;\n  /** Host session store (mobile); browser hosts mount `storage.session` on the thread instead. */\n  sessionStore?: StatewireClient.SessionStorage | undefined;\n  /** Observes every headers resolve (the diagnostics recorder's stale-auth seam). */\n  onAuthResolve?: ((ctx: { staleAuth: boolean }) => void) | undefined;\n  /** Attach timing + retry hints (see `statewire-attach-observer`). */\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  /**\n   * The head window declared on the attach (`x-athena-deep-agent-window`,\n   * see `message-window.ts`): the hello of a client the host does not\n   * remember carries the newest `size` messages. Part of the recipe so a\n   * pooled dial asks for the same shape as the thread's own attach — a pooled\n   * hello then seeds the very state the attach will reconcile. Omitted, the\n   * shared default is declared.\n   */\n  messageWindow?: DeepAgentMessageWindowDeclaration | undefined;\n  /**\n   * The view this thread's attach holds, read at every attach's header\n   * resolve (`x-athena-deep-agent-interests`, see `message-window.ts`): a\n   * re-attach's hello then carries the pages it had loaded on whichever host\n   * instance it lands on. `null` (a first attach) declares nothing. Not part\n   * of a pooled dial, which never held a view.\n   */\n  declaredInterests?: (() => DeepAgentInterestDeclaration | null) | undefined;\n  /**\n   * The surface pages cut lanes (see `DeepAgentProtocolDeclaration`), so its\n   * attach declares the lane-cut contract version. Part of the recipe so a\n   * pooled dial declares what the thread's own attach would; omitted, the\n   * default version is declared.\n   */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * The ONE recipe for a deep-agent thread transport — shared by the mounted\n * thread (`useDeepAgentThread`) and the prewarm pool, so a pre-dialed\n * connection is byte-for-byte the connection the thread would have opened\n * itself: same URL, same auth + wire-contract headers, same session lane, same\n * instrumentation.\n *\n * Every attach declares the surface's wire-contract version alongside the\n * host's auth headers (first WS frame / SSE request headers) — the server\n * half of version negotiation reads it in `authorize`. The headers resolve\n * also waits out any server `Retry-After` floor for the thread: both statewire\n * attach paths resolve headers before they dial, so this is the seam where a\n * hint can hold the next dial without touching the library's backoff.\n */\nexport function createDeepAgentAttachTransport<TState = unknown>({\n  baseUrl,\n  threadId,\n  headers,\n  sse = false,\n  isNew = false,\n  sessionStore,\n  onAuthResolve,\n  onAttachTiming,\n  retryGate = attachRetryGate,\n  messageWindow,\n  declaredInterests,\n  laneHistory = false,\n}: DeepAgentAttachTransportOptions): ResourceElement<\n  Statewire<TState | undefined>\n> {\n  const url = deepAgentThreadUrl({ baseUrl, threadId });\n  // The instrumentation wraps the transport actually built: SSE needs the\n  // fetch wrapper that reads a refused attach's `Retry-After`.\n  const useSse = resolveStatewireTransportKind({ sse }) === \"sse\";\n  const instrumentation = createAttachInstrumentation({\n    url,\n    sse: useSse,\n    onEvent: onAttachTiming,\n    retryGate,\n  });\n  const options: StatewireTransportOptions = {\n    url,\n    ...(isNew && { isNew: true }),\n    headers: async (ctx: { staleAuth: boolean }) => {\n      await retryGate.waitForDial(url);\n      onAuthResolve?.(ctx);\n      return withDeclaredInterests(\n        withDeclaredMessageWindow(\n          withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),\n          messageWindow,\n        ),\n        declaredInterests?.() ?? null,\n      );\n    },\n    ...(sessionStore && { sessionStore }),\n    // Structural types: this package compiles without the DOM lib, while\n    // statewire's option types name the browser `WebSocket`/`fetch`.\n    ...(instrumentation.webSocket && {\n      webSocket:\n        instrumentation.webSocket as unknown as StatewireTransportOptions[\"webSocket\"],\n    }),\n    ...(instrumentation.fetch && {\n      fetch:\n        instrumentation.fetch as unknown as StatewireTransportOptions[\"fetch\"],\n    }),\n  };\n  return statewireTransport<TState>(options, { sse: useSse });\n}\n\n/** What `POST …/prewarm` answered. */\nexport interface DeepAgentWakeResult {\n  status: number;\n  /** The host activated the thread and its history is resident. */\n  warm: boolean;\n  /**\n   * `'warm'` when the history was already memoized, `'fresh_load'` when this\n   * call loaded it; `null` when the host did not say (a refusal, or a host\n   * without the route).\n   */\n  history: \"fresh_load\" | \"warm\" | null;\n  /**\n   * The dial floor recorded for the thread off a 503/429 `Retry-After` — the\n   * header's value, except a 503 `\"worker\"` refusal, capped at\n   * {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n   */\n  retryAfterMs: number | null;\n  /** Who refused a 503/429 (see {@link DeepAgentWakeRefusal}); `null` for any other answer. */\n  refusal: DeepAgentWakeRefusal;\n  durationMs: number;\n}\n\n/**\n * Dial floor for a 503 the pinned worker produced about one instance's\n * lifecycle. Pinned answers every retriable 503 with a blanket\n * `Retry-After: 1`, but what those name — an instance record mid-teardown\n * (\"instance closing; retry\": fence release + placement release, ≈100 ms), a\n * full activation queue — clears far sooner than that, and the thread's own\n * attach is the request that carries the next activation. Holding it a full\n * second traded a ≈100 ms gap for a ≈1 s stall on every refused wake. A 429\n * is rate limiting and keeps its hint whatever the body says.\n */\nexport const WAKE_WORKER_REFUSAL_FLOOR_MS = 250;\n\n/**\n * The pinboard's own placement-refusal vocabulary — the `error` strings of\n * `@assistant-ui/pinboard` (`src/refusals.ts` plus the two inline refusals in\n * `src/server.ts`). Mirrors `PINBOARD_PLACEMENT_REFUSAL_ERRORS` in\n * `iris/scaler/src/v2AccessLog.ts`, whose test pins it to the installed\n * library; keep the two lists identical. A body with any other `error`\n * string is `\"unknown\"`, never `\"placement\"`.\n */\nexport const PINBOARD_PLACEMENT_REFUSAL_ERRORS: ReadonlySet<string> = new Set([\n  \"no live backends for namespace\",\n  \"registry cold start, retry\",\n  \"not the serving fleet\",\n  \"no live workers for hostname\",\n  \"hostname binding displaced, retry\",\n  \"hostname bindings inconsistent, retry\",\n  \"takeover in progress, retry\",\n  \"placement held by another hostname\",\n  \"worker inflight cap exceeded, retry\",\n  \"worker refused activation, retry\",\n]);\n\n/**\n * Pinned's instance-lifecycle refusals (`pinned/hosting/directory.py`,\n * `pinned/hosting/_records.py`): each names one instance on the worker the\n * thread is already placed on and clears in the time a teardown or an\n * activation slot takes. Anything else the worker answers 503 with — \"Thread\n * history load failed\", \"The regional conversation store is temporarily\n * unavailable\", a lease that expired — is not about one instance and keeps\n * the full hint.\n */\nexport const PINNED_TRANSIENT_WORKER_REFUSALS: ReadonlySet<string> = new Set([\n  \"instance closing; retry\",\n  \"instance aborted\",\n  \"activation queue full; retry\",\n  \"host draining; retry\",\n  \"instance capacity reached; retry\",\n  \"instance past its wind-down deadline; retry\",\n]);\n\n/**\n * Classify a 503/429 body (see {@link DeepAgentWakeRefusal}): a known pinboard\n * `error` is `\"placement\"`, a known pinned `detail` is `\"worker\"`, everything\n * else — including unfamiliar strings in either field — is `\"unknown\"`.\n */\nexport function classifyWakeRefusal(\n  body: unknown,\n): Exclude<DeepAgentWakeRefusal, null> {\n  if (typeof body === \"object\" && body !== null) {\n    const record = body as Record<string, unknown>;\n    if (\n      typeof record.error === \"string\" &&\n      PINBOARD_PLACEMENT_REFUSAL_ERRORS.has(record.error)\n    ) {\n      return \"placement\";\n    }\n    if (\n      typeof record.detail === \"string\" &&\n      PINNED_TRANSIENT_WORKER_REFUSALS.has(record.detail)\n    ) {\n      return \"worker\";\n    }\n  }\n  return \"unknown\";\n}\n\n/** Structural `fetch` for the wake call — this package compiles without the DOM lib. */\nexport type DeepAgentWakeFetch = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    keepalive?: boolean;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n}>;\n\nexport interface DeepAgentWakeOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  fetch?: DeepAgentWakeFetch | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  now?: () => number;\n  /** The surface pages cut lanes: declare what its attach declares (see `DeepAgentAttachTransportOptions`). */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * Wake a thread's server instance ahead of its attach. `POST …/prewarm` runs\n * the host's `authorize` and history load — the fence adopt, graph compile and\n * checkpoint read that make a cold attach's hello take ≈1 s — and answers with\n * no thread content, only whether the history was already resident. Fire it\n * on hover intent, before a pooled attach or the click's own dial, so the\n * activation overlaps the handshake and the attach that follows finds the\n * instance warm.\n *\n * Fire-and-forget by contract: every failure resolves `null`, and a host\n * without the route (404) is reported like any other non-OK answer. A 503/429\n * `Retry-After` is recorded as a dial floor for the thread, so the attach that\n * follows waits it out instead of bouncing — in full, except a 503 that names\n * one of pinned's instance-lifecycle refusals (one instance mid-teardown on\n * the worker the thread already has; see {@link DeepAgentWakeRefusal}), whose\n * floor is capped at {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n */\nexport async function wakeDeepAgentThread({\n  baseUrl,\n  threadId,\n  headers,\n  fetch: fetchOverride,\n  retryGate = attachRetryGate,\n  onAttachTiming,\n  now = () => Date.now(),\n  laneHistory = false,\n}: DeepAgentWakeOptions): Promise<DeepAgentWakeResult | null> {\n  const fetchImpl =\n    fetchOverride ?? (globalThis as { fetch?: DeepAgentWakeFetch }).fetch;\n  if (typeof fetchImpl !== \"function\") return null;\n  const threadUrl = deepAgentThreadUrl({ baseUrl, threadId });\n  const emit = (event: DeepAgentAttachTimingEvent): void => {\n    try {\n      onAttachTiming?.(event);\n    } catch {\n      // Observers are best-effort.\n    }\n  };\n  const startedAt = now();\n  try {\n    const resolved = withDeclaredProtocolVersion(\n      await headers({ staleAuth: false }),\n      { laneHistory },\n    );\n    const response = await fetchImpl(`${threadUrl}/prewarm`, {\n      method: \"POST\",\n      headers: resolved,\n      keepalive: true,\n    });\n    const durationMs = now() - startedAt;\n    let retryAfterMs: number | null = null;\n    let refusal: DeepAgentWakeRefusal = null;\n    if (response.status === 503 || response.status === 429) {\n      let body: unknown = null;\n      try {\n        body = await response.json();\n      } catch {\n        // A refusal without a readable body is classified by nothing.\n      }\n      refusal = classifyWakeRefusal(body);\n      const hinted = parseRetryAfterHeaderMs(\n        response.headers.get(\"retry-after\"),\n        now,\n      );\n      if (hinted !== null) {\n        retryAfterMs =\n          response.status === 503 && refusal === \"worker\"\n            ? Math.min(hinted, WAKE_WORKER_REFUSAL_FLOOR_MS)\n            : hinted;\n        if (retryAfterMs > 0) {\n          retryGate.noteRetryAfter(threadUrl, retryAfterMs);\n          emit({\n            type: \"retry-after\",\n            url: threadUrl,\n            delayMs: retryAfterMs,\n            source: \"http-header\",\n          });\n        }\n      }\n    }\n    let warm = false;\n    let history: DeepAgentWakeResult[\"history\"] = null;\n    if (response.ok) {\n      try {\n        const body = (await response.json()) as {\n          warm?: unknown;\n          history?: unknown;\n        } | null;\n        warm = body?.warm === true;\n        history =\n          body?.history === \"warm\" || body?.history === \"fresh_load\"\n            ? body.history\n            : null;\n      } catch {\n        // A 200 without a JSON body still means the instance is up.\n        warm = true;\n      }\n    }\n    emit({\n      type: \"wake\",\n      url: threadUrl,\n      status: response.status,\n      durationMs,\n      history,\n      refusal,\n    });\n    return {\n      status: response.status,\n      warm,\n      history,\n      retryAfterMs,\n      refusal,\n      durationMs,\n    };\n  } catch {\n    return null;\n  }\n}\n"],"names":["attachRetryGate","messageWindow","resolveStatewireTransportKind","createAttachInstrumentation","withDeclaredInterests","withDeclaredMessageWindow","withDeclaredProtocolVersion","statewireTransport"],"mappings":";;;;;;AA8BO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGW;AACT,SAAO,GAAG,QAAQ,QAAQ,QAAQ,EAAE,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AACvE;AA2DO,SAAS,+BAAiD;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN,QAAQ;AAAA,EACR;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAYA,wBAAAA;AAAAA,EAAA,eACZC;AAAAA,EACA;AAAA,EACA,cAAc;AAChB,GAEE;AACA,QAAM,MAAM,mBAAmB,EAAE,SAAS,UAAU;AAGpD,QAAM,SAASC,mBAAAA,8BAA8B,EAAE,IAAA,CAAK,MAAM;AAC1D,QAAM,kBAAkBC,wBAAAA,4BAA4B;AAAA,IAClD;AAAA,IACA,KAAK;AAAA,IACL,SAAS;AAAA,IACT;AAAA,EAAA,CACD;AACD,QAAM,UAAqC;AAAA,IACzC;AAAA,IACA,GAAI,SAAS,EAAE,OAAO,KAAA;AAAA,IACtB,SAAS,OAAO,QAAgC;AAC9C,YAAM,UAAU,YAAY,GAAG;AAC/B,qDAAgB;AAChB,aAAOC,cAAAA;AAAAA,QACLC,cAAAA;AAAAA,UACEC,SAAAA,4BAA4B,MAAM,QAAQ,GAAG,GAAG,EAAE,aAAa;AAAA,UAC/DL;AAAAA,QAAA;AAAA,SAEF,6DAAyB;AAAA,MAAA;AAAA,IAE7B;AAAA,IACA,GAAI,gBAAgB,EAAE,aAAA;AAAA;AAAA;AAAA,IAGtB,GAAI,gBAAgB,aAAa;AAAA,MAC/B,WACE,gBAAgB;AAAA,IAAA;AAAA,IAEpB,GAAI,gBAAgB,SAAS;AAAA,MAC3B,OACE,gBAAgB;AAAA,IAAA;AAAA,EACpB;AAEF,SAAOM,mBAAAA,mBAA2B,SAAS,EAAE,KAAK,QAAQ;AAC5D;;;"}
+{"version":3,"file":"deep-agent-transport-recipe.cjs","sources":["../../../../agent-runtime/src/deep-agent-transport-recipe.ts"],"sourcesContent":["import type { ResourceElement } from \"@assistant-ui/tap\";\nimport type { Statewire, StatewireClient } from \"statewire\";\nimport {\n  type DeepAgentInterestDeclaration,\n  type DeepAgentMessageWindowDeclaration,\n  withDeclaredInterests,\n  withDeclaredMessageWindow,\n} from \"./message-window\";\nimport { withDeclaredPagedHistory } from \"./history-store\";\nimport { withDeclaredProtocolVersion } from \"./protocol\";\nimport {\n  attachRetryGate,\n  type AttachRetryGate,\n  createAttachInstrumentation,\n  type DeepAgentAttachTimingEvent,\n  type DeepAgentWakeRefusal,\n  parseRetryAfterHeaderMs,\n} from \"./statewire-attach-observer\";\nimport {\n  resolveStatewireTransportKind,\n  statewireTransport,\n  type StatewireTransportOptions,\n} from \"./statewire-transport\";\n\n/** Auth-header resolver for the transport; `staleAuth` is true right after an\n * auth rejection, so resolvers that can force-renew should honor it. */\nexport type DeepAgentHeadersResolver = (ctx: {\n  staleAuth: boolean;\n}) => Record<string, string> | Promise<Record<string, string>>;\n\n/** The statewire attach URL for a thread: the host's `…/v2/threads` mount plus the id. */\nexport function deepAgentThreadUrl({\n  baseUrl,\n  threadId,\n}: {\n  baseUrl: string;\n  threadId: string;\n}): string {\n  return `${baseUrl.replace(/\\/+$/, \"\")}/${encodeURIComponent(threadId)}`;\n}\n\nexport interface DeepAgentAttachTransportOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  /** SSE when true, WebSocket otherwise (`resolveStatewireTransportKind`). */\n  sse?: boolean;\n  /** A never-started chat: the transport makes no network calls until the first command send. */\n  isNew?: boolean;\n  /** Host session store (mobile); browser hosts mount `storage.session` on the thread instead. */\n  sessionStore?: StatewireClient.SessionStorage | undefined;\n  /** Observes every headers resolve (the diagnostics recorder's stale-auth seam). */\n  onAuthResolve?: ((ctx: { staleAuth: boolean }) => void) | undefined;\n  /** Attach timing + retry hints (see `statewire-attach-observer`). */\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  /**\n   * The head window declared on the attach (`x-athena-deep-agent-window`,\n   * see `message-window.ts`): the hello of a client the host does not\n   * remember carries the newest `size` messages. Part of the recipe so a\n   * pooled dial asks for the same shape as the thread's own attach — a pooled\n   * hello then seeds the very state the attach will reconcile. Omitted, the\n   * shared default is declared.\n   */\n  messageWindow?: DeepAgentMessageWindowDeclaration | undefined;\n  /**\n   * The view this thread's attach holds, read at every attach's header\n   * resolve (`x-athena-deep-agent-interests`, see `message-window.ts`): a\n   * re-attach's hello then carries the pages it had loaded on whichever host\n   * instance it lands on. `null` (a first attach) declares nothing. Not part\n   * of a pooled dial, which never held a view.\n   */\n  declaredInterests?: (() => DeepAgentInterestDeclaration | null) | undefined;\n  /**\n   * The surface pages cut lanes (see `DeepAgentProtocolDeclaration`), so its\n   * attach declares the lane-cut contract version. Part of the recipe so a\n   * pooled dial declares what the thread's own attach would; omitted, the\n   * default version is declared.\n   */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * The ONE recipe for a deep-agent thread transport — shared by the mounted\n * thread (`useDeepAgentThread`) and the prewarm pool, so a pre-dialed\n * connection is byte-for-byte the connection the thread would have opened\n * itself: same URL, same auth + wire-contract headers, same session lane, same\n * instrumentation.\n *\n * Every attach declares the surface's wire-contract version alongside the\n * host's auth headers (first WS frame / SSE request headers) — the server\n * half of version negotiation reads it in `authorize`. The headers resolve\n * also waits out any server `Retry-After` floor for the thread: both statewire\n * attach paths resolve headers before they dial, so this is the seam where a\n * hint can hold the next dial without touching the library's backoff.\n */\nexport function createDeepAgentAttachTransport<TState = unknown>({\n  baseUrl,\n  threadId,\n  headers,\n  sse = false,\n  isNew = false,\n  sessionStore,\n  onAuthResolve,\n  onAttachTiming,\n  retryGate = attachRetryGate,\n  messageWindow,\n  declaredInterests,\n  laneHistory = false,\n}: DeepAgentAttachTransportOptions): ResourceElement<\n  Statewire<TState | undefined>\n> {\n  const url = deepAgentThreadUrl({ baseUrl, threadId });\n  // The instrumentation wraps the transport actually built: SSE needs the\n  // fetch wrapper that reads a refused attach's `Retry-After`.\n  const useSse = resolveStatewireTransportKind({ sse }) === \"sse\";\n  const instrumentation = createAttachInstrumentation({\n    url,\n    sse: useSse,\n    onEvent: onAttachTiming,\n    retryGate,\n  });\n  const options: StatewireTransportOptions = {\n    url,\n    ...(isNew && { isNew: true }),\n    headers: async (ctx: { staleAuth: boolean }) => {\n      await retryGate.waitForDial(url);\n      onAuthResolve?.(ctx);\n      return withDeclaredInterests(\n        withDeclaredPagedHistory(\n          withDeclaredMessageWindow(\n            withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),\n            messageWindow,\n          ),\n        ),\n        declaredInterests?.() ?? null,\n      );\n    },\n    ...(sessionStore && { sessionStore }),\n    // Structural types: this package compiles without the DOM lib, while\n    // statewire's option types name the browser `WebSocket`/`fetch`.\n    ...(instrumentation.webSocket && {\n      webSocket:\n        instrumentation.webSocket as unknown as StatewireTransportOptions[\"webSocket\"],\n    }),\n    ...(instrumentation.fetch && {\n      fetch:\n        instrumentation.fetch as unknown as StatewireTransportOptions[\"fetch\"],\n    }),\n  };\n  return statewireTransport<TState>(options, { sse: useSse });\n}\n\n/** What `POST …/prewarm` answered. */\nexport interface DeepAgentWakeResult {\n  status: number;\n  /** The host activated the thread and its history is resident. */\n  warm: boolean;\n  /**\n   * `'warm'` when the history was already memoized, `'fresh_load'` when this\n   * call loaded it; `null` when the host did not say (a refusal, or a host\n   * without the route).\n   */\n  history: \"fresh_load\" | \"warm\" | null;\n  /**\n   * The dial floor recorded for the thread off a 503/429 `Retry-After` — the\n   * header's value, except a 503 `\"worker\"` refusal, capped at\n   * {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n   */\n  retryAfterMs: number | null;\n  /** Who refused a 503/429 (see {@link DeepAgentWakeRefusal}); `null` for any other answer. */\n  refusal: DeepAgentWakeRefusal;\n  durationMs: number;\n}\n\n/**\n * Dial floor for a 503 the pinned worker produced about one instance's\n * lifecycle. Pinned answers every retriable 503 with a blanket\n * `Retry-After: 1`, but what those name — an instance record mid-teardown\n * (\"instance closing; retry\": fence release + placement release, ≈100 ms), a\n * full activation queue — clears far sooner than that, and the thread's own\n * attach is the request that carries the next activation. Holding it a full\n * second traded a ≈100 ms gap for a ≈1 s stall on every refused wake. A 429\n * is rate limiting and keeps its hint whatever the body says.\n */\nexport const WAKE_WORKER_REFUSAL_FLOOR_MS = 250;\n\n/**\n * The pinboard's own placement-refusal vocabulary — the `error` strings of\n * `@assistant-ui/pinboard` (`src/refusals.ts` plus the two inline refusals in\n * `src/server.ts`). Mirrors `PINBOARD_PLACEMENT_REFUSAL_ERRORS` in\n * `iris/scaler/src/v2AccessLog.ts`, whose test pins it to the installed\n * library; keep the two lists identical. A body with any other `error`\n * string is `\"unknown\"`, never `\"placement\"`.\n */\nexport const PINBOARD_PLACEMENT_REFUSAL_ERRORS: ReadonlySet<string> = new Set([\n  \"no live backends for namespace\",\n  \"registry cold start, retry\",\n  \"not the serving fleet\",\n  \"no live workers for hostname\",\n  \"hostname binding displaced, retry\",\n  \"hostname bindings inconsistent, retry\",\n  \"takeover in progress, retry\",\n  \"placement held by another hostname\",\n  \"worker inflight cap exceeded, retry\",\n  \"worker refused activation, retry\",\n]);\n\n/**\n * Pinned's instance-lifecycle refusals (`pinned/hosting/directory.py`,\n * `pinned/hosting/_records.py`): each names one instance on the worker the\n * thread is already placed on and clears in the time a teardown or an\n * activation slot takes. Anything else the worker answers 503 with — \"Thread\n * history load failed\", \"The regional conversation store is temporarily\n * unavailable\", a lease that expired — is not about one instance and keeps\n * the full hint.\n */\nexport const PINNED_TRANSIENT_WORKER_REFUSALS: ReadonlySet<string> = new Set([\n  \"instance closing; retry\",\n  \"instance aborted\",\n  \"activation queue full; retry\",\n  \"host draining; retry\",\n  \"instance capacity reached; retry\",\n  \"instance past its wind-down deadline; retry\",\n]);\n\n/**\n * Classify a 503/429 body (see {@link DeepAgentWakeRefusal}): a known pinboard\n * `error` is `\"placement\"`, a known pinned `detail` is `\"worker\"`, everything\n * else — including unfamiliar strings in either field — is `\"unknown\"`.\n */\nexport function classifyWakeRefusal(\n  body: unknown,\n): Exclude<DeepAgentWakeRefusal, null> {\n  if (typeof body === \"object\" && body !== null) {\n    const record = body as Record<string, unknown>;\n    if (\n      typeof record.error === \"string\" &&\n      PINBOARD_PLACEMENT_REFUSAL_ERRORS.has(record.error)\n    ) {\n      return \"placement\";\n    }\n    if (\n      typeof record.detail === \"string\" &&\n      PINNED_TRANSIENT_WORKER_REFUSALS.has(record.detail)\n    ) {\n      return \"worker\";\n    }\n  }\n  return \"unknown\";\n}\n\n/** Structural `fetch` for the wake call — this package compiles without the DOM lib. */\nexport type DeepAgentWakeFetch = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    keepalive?: boolean;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n}>;\n\nexport interface DeepAgentWakeOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  fetch?: DeepAgentWakeFetch | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  now?: () => number;\n  /** The surface pages cut lanes: declare what its attach declares (see `DeepAgentAttachTransportOptions`). */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * Wake a thread's server instance ahead of its attach. `POST …/prewarm` runs\n * the host's `authorize` and history load — the fence adopt, graph compile and\n * checkpoint read that make a cold attach's hello take ≈1 s — and answers with\n * no thread content, only whether the history was already resident. Fire it\n * on hover intent, before a pooled attach or the click's own dial, so the\n * activation overlaps the handshake and the attach that follows finds the\n * instance warm.\n *\n * Fire-and-forget by contract: every failure resolves `null`, and a host\n * without the route (404) is reported like any other non-OK answer. A 503/429\n * `Retry-After` is recorded as a dial floor for the thread, so the attach that\n * follows waits it out instead of bouncing — in full, except a 503 that names\n * one of pinned's instance-lifecycle refusals (one instance mid-teardown on\n * the worker the thread already has; see {@link DeepAgentWakeRefusal}), whose\n * floor is capped at {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n */\nexport async function wakeDeepAgentThread({\n  baseUrl,\n  threadId,\n  headers,\n  fetch: fetchOverride,\n  retryGate = attachRetryGate,\n  onAttachTiming,\n  now = () => Date.now(),\n  laneHistory = false,\n}: DeepAgentWakeOptions): Promise<DeepAgentWakeResult | null> {\n  const fetchImpl =\n    fetchOverride ?? (globalThis as { fetch?: DeepAgentWakeFetch }).fetch;\n  if (typeof fetchImpl !== \"function\") return null;\n  const threadUrl = deepAgentThreadUrl({ baseUrl, threadId });\n  const emit = (event: DeepAgentAttachTimingEvent): void => {\n    try {\n      onAttachTiming?.(event);\n    } catch {\n      // Observers are best-effort.\n    }\n  };\n  const startedAt = now();\n  try {\n    const resolved = withDeclaredProtocolVersion(\n      await headers({ staleAuth: false }),\n      { laneHistory },\n    );\n    const response = await fetchImpl(`${threadUrl}/prewarm`, {\n      method: \"POST\",\n      headers: resolved,\n      keepalive: true,\n    });\n    const durationMs = now() - startedAt;\n    let retryAfterMs: number | null = null;\n    let refusal: DeepAgentWakeRefusal = null;\n    if (response.status === 503 || response.status === 429) {\n      let body: unknown = null;\n      try {\n        body = await response.json();\n      } catch {\n        // A refusal without a readable body is classified by nothing.\n      }\n      refusal = classifyWakeRefusal(body);\n      const hinted = parseRetryAfterHeaderMs(\n        response.headers.get(\"retry-after\"),\n        now,\n      );\n      if (hinted !== null) {\n        retryAfterMs =\n          response.status === 503 && refusal === \"worker\"\n            ? Math.min(hinted, WAKE_WORKER_REFUSAL_FLOOR_MS)\n            : hinted;\n        if (retryAfterMs > 0) {\n          retryGate.noteRetryAfter(threadUrl, retryAfterMs);\n          emit({\n            type: \"retry-after\",\n            url: threadUrl,\n            delayMs: retryAfterMs,\n            source: \"http-header\",\n          });\n        }\n      }\n    }\n    let warm = false;\n    let history: DeepAgentWakeResult[\"history\"] = null;\n    if (response.ok) {\n      try {\n        const body = (await response.json()) as {\n          warm?: unknown;\n          history?: unknown;\n        } | null;\n        warm = body?.warm === true;\n        history =\n          body?.history === \"warm\" || body?.history === \"fresh_load\"\n            ? body.history\n            : null;\n      } catch {\n        // A 200 without a JSON body still means the instance is up.\n        warm = true;\n      }\n    }\n    emit({\n      type: \"wake\",\n      url: threadUrl,\n      status: response.status,\n      durationMs,\n      history,\n      refusal,\n    });\n    return {\n      status: response.status,\n      warm,\n      history,\n      retryAfterMs,\n      refusal,\n      durationMs,\n    };\n  } catch {\n    return null;\n  }\n}\n"],"names":["attachRetryGate","messageWindow","resolveStatewireTransportKind","createAttachInstrumentation","withDeclaredInterests","withDeclaredPagedHistory","withDeclaredMessageWindow","withDeclaredProtocolVersion","statewireTransport"],"mappings":";;;;;;;AA+BO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGW;AACT,SAAO,GAAG,QAAQ,QAAQ,QAAQ,EAAE,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AACvE;AA2DO,SAAS,+BAAiD;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN,QAAQ;AAAA,EACR;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAYA,wBAAAA;AAAAA,EAAA,eACZC;AAAAA,EACA;AAAA,EACA,cAAc;AAChB,GAEE;AACA,QAAM,MAAM,mBAAmB,EAAE,SAAS,UAAU;AAGpD,QAAM,SAASC,mBAAAA,8BAA8B,EAAE,IAAA,CAAK,MAAM;AAC1D,QAAM,kBAAkBC,wBAAAA,4BAA4B;AAAA,IAClD;AAAA,IACA,KAAK;AAAA,IACL,SAAS;AAAA,IACT;AAAA,EAAA,CACD;AACD,QAAM,UAAqC;AAAA,IACzC;AAAA,IACA,GAAI,SAAS,EAAE,OAAO,KAAA;AAAA,IACtB,SAAS,OAAO,QAAgC;AAC9C,YAAM,UAAU,YAAY,GAAG;AAC/B,qDAAgB;AAChB,aAAOC,cAAAA;AAAAA,QACLC,aAAAA;AAAAA,UACEC,cAAAA;AAAAA,YACEC,SAAAA,4BAA4B,MAAM,QAAQ,GAAG,GAAG,EAAE,aAAa;AAAA,YAC/DN;AAAAA,UAAA;AAAA,QACF;AAAA,SAEF,6DAAyB;AAAA,MAAA;AAAA,IAE7B;AAAA,IACA,GAAI,gBAAgB,EAAE,aAAA;AAAA;AAAA;AAAA,IAGtB,GAAI,gBAAgB,aAAa;AAAA,MAC/B,WACE,gBAAgB;AAAA,IAAA;AAAA,IAEpB,GAAI,gBAAgB,SAAS;AAAA,MAC3B,OACE,gBAAgB;AAAA,IAAA;AAAA,EACpB;AAEF,SAAOO,mBAAAA,mBAA2B,SAAS,EAAE,KAAK,QAAQ;AAC5D;;;"}

package/dist/agent-runtime/src/deep-agent-transport-recipe.js

@@ -1,4 +1,5 @@
 import { withDeclaredInterests, withDeclaredMessageWindow } from "./message-window.js";
+import { withDeclaredPagedHistory } from "./history-store.js";
 import { withDeclaredProtocolVersion } from "./protocol.js";
 import { createAttachInstrumentation, attachRetryGate } from "./statewire-attach-observer.js";
 import { statewireTransport, resolveStatewireTransportKind } from "./statewire-transport.js";
@@ -37,9 +38,11 @@ function createDeepAgentAttachTransport({
       await retryGate.waitForDial(url);
       onAuthResolve == null ? void 0 : onAuthResolve(ctx);
       return withDeclaredInterests(
-        withDeclaredMessageWindow(
-          withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),
-          messageWindow
+        withDeclaredPagedHistory(
+          withDeclaredMessageWindow(
+            withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),
+            messageWindow
+          )
         ),
         (declaredInterests == null ? void 0 : declaredInterests()) ?? null
       );

package/dist/agent-runtime/src/deep-agent-transport-recipe.js.map

@@ -1 +1 @@
-{"version":3,"file":"deep-agent-transport-recipe.js","sources":["../../../../agent-runtime/src/deep-agent-transport-recipe.ts"],"sourcesContent":["import type { ResourceElement } from \"@assistant-ui/tap\";\nimport type { Statewire, StatewireClient } from \"statewire\";\nimport {\n  type DeepAgentInterestDeclaration,\n  type DeepAgentMessageWindowDeclaration,\n  withDeclaredInterests,\n  withDeclaredMessageWindow,\n} from \"./message-window\";\nimport { withDeclaredProtocolVersion } from \"./protocol\";\nimport {\n  attachRetryGate,\n  type AttachRetryGate,\n  createAttachInstrumentation,\n  type DeepAgentAttachTimingEvent,\n  type DeepAgentWakeRefusal,\n  parseRetryAfterHeaderMs,\n} from \"./statewire-attach-observer\";\nimport {\n  resolveStatewireTransportKind,\n  statewireTransport,\n  type StatewireTransportOptions,\n} from \"./statewire-transport\";\n\n/** Auth-header resolver for the transport; `staleAuth` is true right after an\n * auth rejection, so resolvers that can force-renew should honor it. */\nexport type DeepAgentHeadersResolver = (ctx: {\n  staleAuth: boolean;\n}) => Record<string, string> | Promise<Record<string, string>>;\n\n/** The statewire attach URL for a thread: the host's `…/v2/threads` mount plus the id. */\nexport function deepAgentThreadUrl({\n  baseUrl,\n  threadId,\n}: {\n  baseUrl: string;\n  threadId: string;\n}): string {\n  return `${baseUrl.replace(/\\/+$/, \"\")}/${encodeURIComponent(threadId)}`;\n}\n\nexport interface DeepAgentAttachTransportOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  /** SSE when true, WebSocket otherwise (`resolveStatewireTransportKind`). */\n  sse?: boolean;\n  /** A never-started chat: the transport makes no network calls until the first command send. */\n  isNew?: boolean;\n  /** Host session store (mobile); browser hosts mount `storage.session` on the thread instead. */\n  sessionStore?: StatewireClient.SessionStorage | undefined;\n  /** Observes every headers resolve (the diagnostics recorder's stale-auth seam). */\n  onAuthResolve?: ((ctx: { staleAuth: boolean }) => void) | undefined;\n  /** Attach timing + retry hints (see `statewire-attach-observer`). */\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  /**\n   * The head window declared on the attach (`x-athena-deep-agent-window`,\n   * see `message-window.ts`): the hello of a client the host does not\n   * remember carries the newest `size` messages. Part of the recipe so a\n   * pooled dial asks for the same shape as the thread's own attach — a pooled\n   * hello then seeds the very state the attach will reconcile. Omitted, the\n   * shared default is declared.\n   */\n  messageWindow?: DeepAgentMessageWindowDeclaration | undefined;\n  /**\n   * The view this thread's attach holds, read at every attach's header\n   * resolve (`x-athena-deep-agent-interests`, see `message-window.ts`): a\n   * re-attach's hello then carries the pages it had loaded on whichever host\n   * instance it lands on. `null` (a first attach) declares nothing. Not part\n   * of a pooled dial, which never held a view.\n   */\n  declaredInterests?: (() => DeepAgentInterestDeclaration | null) | undefined;\n  /**\n   * The surface pages cut lanes (see `DeepAgentProtocolDeclaration`), so its\n   * attach declares the lane-cut contract version. Part of the recipe so a\n   * pooled dial declares what the thread's own attach would; omitted, the\n   * default version is declared.\n   */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * The ONE recipe for a deep-agent thread transport — shared by the mounted\n * thread (`useDeepAgentThread`) and the prewarm pool, so a pre-dialed\n * connection is byte-for-byte the connection the thread would have opened\n * itself: same URL, same auth + wire-contract headers, same session lane, same\n * instrumentation.\n *\n * Every attach declares the surface's wire-contract version alongside the\n * host's auth headers (first WS frame / SSE request headers) — the server\n * half of version negotiation reads it in `authorize`. The headers resolve\n * also waits out any server `Retry-After` floor for the thread: both statewire\n * attach paths resolve headers before they dial, so this is the seam where a\n * hint can hold the next dial without touching the library's backoff.\n */\nexport function createDeepAgentAttachTransport<TState = unknown>({\n  baseUrl,\n  threadId,\n  headers,\n  sse = false,\n  isNew = false,\n  sessionStore,\n  onAuthResolve,\n  onAttachTiming,\n  retryGate = attachRetryGate,\n  messageWindow,\n  declaredInterests,\n  laneHistory = false,\n}: DeepAgentAttachTransportOptions): ResourceElement<\n  Statewire<TState | undefined>\n> {\n  const url = deepAgentThreadUrl({ baseUrl, threadId });\n  // The instrumentation wraps the transport actually built: SSE needs the\n  // fetch wrapper that reads a refused attach's `Retry-After`.\n  const useSse = resolveStatewireTransportKind({ sse }) === \"sse\";\n  const instrumentation = createAttachInstrumentation({\n    url,\n    sse: useSse,\n    onEvent: onAttachTiming,\n    retryGate,\n  });\n  const options: StatewireTransportOptions = {\n    url,\n    ...(isNew && { isNew: true }),\n    headers: async (ctx: { staleAuth: boolean }) => {\n      await retryGate.waitForDial(url);\n      onAuthResolve?.(ctx);\n      return withDeclaredInterests(\n        withDeclaredMessageWindow(\n          withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),\n          messageWindow,\n        ),\n        declaredInterests?.() ?? null,\n      );\n    },\n    ...(sessionStore && { sessionStore }),\n    // Structural types: this package compiles without the DOM lib, while\n    // statewire's option types name the browser `WebSocket`/`fetch`.\n    ...(instrumentation.webSocket && {\n      webSocket:\n        instrumentation.webSocket as unknown as StatewireTransportOptions[\"webSocket\"],\n    }),\n    ...(instrumentation.fetch && {\n      fetch:\n        instrumentation.fetch as unknown as StatewireTransportOptions[\"fetch\"],\n    }),\n  };\n  return statewireTransport<TState>(options, { sse: useSse });\n}\n\n/** What `POST …/prewarm` answered. */\nexport interface DeepAgentWakeResult {\n  status: number;\n  /** The host activated the thread and its history is resident. */\n  warm: boolean;\n  /**\n   * `'warm'` when the history was already memoized, `'fresh_load'` when this\n   * call loaded it; `null` when the host did not say (a refusal, or a host\n   * without the route).\n   */\n  history: \"fresh_load\" | \"warm\" | null;\n  /**\n   * The dial floor recorded for the thread off a 503/429 `Retry-After` — the\n   * header's value, except a 503 `\"worker\"` refusal, capped at\n   * {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n   */\n  retryAfterMs: number | null;\n  /** Who refused a 503/429 (see {@link DeepAgentWakeRefusal}); `null` for any other answer. */\n  refusal: DeepAgentWakeRefusal;\n  durationMs: number;\n}\n\n/**\n * Dial floor for a 503 the pinned worker produced about one instance's\n * lifecycle. Pinned answers every retriable 503 with a blanket\n * `Retry-After: 1`, but what those name — an instance record mid-teardown\n * (\"instance closing; retry\": fence release + placement release, ≈100 ms), a\n * full activation queue — clears far sooner than that, and the thread's own\n * attach is the request that carries the next activation. Holding it a full\n * second traded a ≈100 ms gap for a ≈1 s stall on every refused wake. A 429\n * is rate limiting and keeps its hint whatever the body says.\n */\nexport const WAKE_WORKER_REFUSAL_FLOOR_MS = 250;\n\n/**\n * The pinboard's own placement-refusal vocabulary — the `error` strings of\n * `@assistant-ui/pinboard` (`src/refusals.ts` plus the two inline refusals in\n * `src/server.ts`). Mirrors `PINBOARD_PLACEMENT_REFUSAL_ERRORS` in\n * `iris/scaler/src/v2AccessLog.ts`, whose test pins it to the installed\n * library; keep the two lists identical. A body with any other `error`\n * string is `\"unknown\"`, never `\"placement\"`.\n */\nexport const PINBOARD_PLACEMENT_REFUSAL_ERRORS: ReadonlySet<string> = new Set([\n  \"no live backends for namespace\",\n  \"registry cold start, retry\",\n  \"not the serving fleet\",\n  \"no live workers for hostname\",\n  \"hostname binding displaced, retry\",\n  \"hostname bindings inconsistent, retry\",\n  \"takeover in progress, retry\",\n  \"placement held by another hostname\",\n  \"worker inflight cap exceeded, retry\",\n  \"worker refused activation, retry\",\n]);\n\n/**\n * Pinned's instance-lifecycle refusals (`pinned/hosting/directory.py`,\n * `pinned/hosting/_records.py`): each names one instance on the worker the\n * thread is already placed on and clears in the time a teardown or an\n * activation slot takes. Anything else the worker answers 503 with — \"Thread\n * history load failed\", \"The regional conversation store is temporarily\n * unavailable\", a lease that expired — is not about one instance and keeps\n * the full hint.\n */\nexport const PINNED_TRANSIENT_WORKER_REFUSALS: ReadonlySet<string> = new Set([\n  \"instance closing; retry\",\n  \"instance aborted\",\n  \"activation queue full; retry\",\n  \"host draining; retry\",\n  \"instance capacity reached; retry\",\n  \"instance past its wind-down deadline; retry\",\n]);\n\n/**\n * Classify a 503/429 body (see {@link DeepAgentWakeRefusal}): a known pinboard\n * `error` is `\"placement\"`, a known pinned `detail` is `\"worker\"`, everything\n * else — including unfamiliar strings in either field — is `\"unknown\"`.\n */\nexport function classifyWakeRefusal(\n  body: unknown,\n): Exclude<DeepAgentWakeRefusal, null> {\n  if (typeof body === \"object\" && body !== null) {\n    const record = body as Record<string, unknown>;\n    if (\n      typeof record.error === \"string\" &&\n      PINBOARD_PLACEMENT_REFUSAL_ERRORS.has(record.error)\n    ) {\n      return \"placement\";\n    }\n    if (\n      typeof record.detail === \"string\" &&\n      PINNED_TRANSIENT_WORKER_REFUSALS.has(record.detail)\n    ) {\n      return \"worker\";\n    }\n  }\n  return \"unknown\";\n}\n\n/** Structural `fetch` for the wake call — this package compiles without the DOM lib. */\nexport type DeepAgentWakeFetch = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    keepalive?: boolean;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n}>;\n\nexport interface DeepAgentWakeOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  fetch?: DeepAgentWakeFetch | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  now?: () => number;\n  /** The surface pages cut lanes: declare what its attach declares (see `DeepAgentAttachTransportOptions`). */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * Wake a thread's server instance ahead of its attach. `POST …/prewarm` runs\n * the host's `authorize` and history load — the fence adopt, graph compile and\n * checkpoint read that make a cold attach's hello take ≈1 s — and answers with\n * no thread content, only whether the history was already resident. Fire it\n * on hover intent, before a pooled attach or the click's own dial, so the\n * activation overlaps the handshake and the attach that follows finds the\n * instance warm.\n *\n * Fire-and-forget by contract: every failure resolves `null`, and a host\n * without the route (404) is reported like any other non-OK answer. A 503/429\n * `Retry-After` is recorded as a dial floor for the thread, so the attach that\n * follows waits it out instead of bouncing — in full, except a 503 that names\n * one of pinned's instance-lifecycle refusals (one instance mid-teardown on\n * the worker the thread already has; see {@link DeepAgentWakeRefusal}), whose\n * floor is capped at {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n */\nexport async function wakeDeepAgentThread({\n  baseUrl,\n  threadId,\n  headers,\n  fetch: fetchOverride,\n  retryGate = attachRetryGate,\n  onAttachTiming,\n  now = () => Date.now(),\n  laneHistory = false,\n}: DeepAgentWakeOptions): Promise<DeepAgentWakeResult | null> {\n  const fetchImpl =\n    fetchOverride ?? (globalThis as { fetch?: DeepAgentWakeFetch }).fetch;\n  if (typeof fetchImpl !== \"function\") return null;\n  const threadUrl = deepAgentThreadUrl({ baseUrl, threadId });\n  const emit = (event: DeepAgentAttachTimingEvent): void => {\n    try {\n      onAttachTiming?.(event);\n    } catch {\n      // Observers are best-effort.\n    }\n  };\n  const startedAt = now();\n  try {\n    const resolved = withDeclaredProtocolVersion(\n      await headers({ staleAuth: false }),\n      { laneHistory },\n    );\n    const response = await fetchImpl(`${threadUrl}/prewarm`, {\n      method: \"POST\",\n      headers: resolved,\n      keepalive: true,\n    });\n    const durationMs = now() - startedAt;\n    let retryAfterMs: number | null = null;\n    let refusal: DeepAgentWakeRefusal = null;\n    if (response.status === 503 || response.status === 429) {\n      let body: unknown = null;\n      try {\n        body = await response.json();\n      } catch {\n        // A refusal without a readable body is classified by nothing.\n      }\n      refusal = classifyWakeRefusal(body);\n      const hinted = parseRetryAfterHeaderMs(\n        response.headers.get(\"retry-after\"),\n        now,\n      );\n      if (hinted !== null) {\n        retryAfterMs =\n          response.status === 503 && refusal === \"worker\"\n            ? Math.min(hinted, WAKE_WORKER_REFUSAL_FLOOR_MS)\n            : hinted;\n        if (retryAfterMs > 0) {\n          retryGate.noteRetryAfter(threadUrl, retryAfterMs);\n          emit({\n            type: \"retry-after\",\n            url: threadUrl,\n            delayMs: retryAfterMs,\n            source: \"http-header\",\n          });\n        }\n      }\n    }\n    let warm = false;\n    let history: DeepAgentWakeResult[\"history\"] = null;\n    if (response.ok) {\n      try {\n        const body = (await response.json()) as {\n          warm?: unknown;\n          history?: unknown;\n        } | null;\n        warm = body?.warm === true;\n        history =\n          body?.history === \"warm\" || body?.history === \"fresh_load\"\n            ? body.history\n            : null;\n      } catch {\n        // A 200 without a JSON body still means the instance is up.\n        warm = true;\n      }\n    }\n    emit({\n      type: \"wake\",\n      url: threadUrl,\n      status: response.status,\n      durationMs,\n      history,\n      refusal,\n    });\n    return {\n      status: response.status,\n      warm,\n      history,\n      retryAfterMs,\n      refusal,\n      durationMs,\n    };\n  } catch {\n    return null;\n  }\n}\n"],"names":[],"mappings":";;;;AA8BO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGW;AACT,SAAO,GAAG,QAAQ,QAAQ,QAAQ,EAAE,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AACvE;AA2DO,SAAS,+BAAiD;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN,QAAQ;AAAA,EACR;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA;AAAA,EACA,cAAc;AAChB,GAEE;AACA,QAAM,MAAM,mBAAmB,EAAE,SAAS,UAAU;AAGpD,QAAM,SAAS,8BAA8B,EAAE,IAAA,CAAK,MAAM;AAC1D,QAAM,kBAAkB,4BAA4B;AAAA,IAClD;AAAA,IACA,KAAK;AAAA,IACL,SAAS;AAAA,IACT;AAAA,EAAA,CACD;AACD,QAAM,UAAqC;AAAA,IACzC;AAAA,IACA,GAAI,SAAS,EAAE,OAAO,KAAA;AAAA,IACtB,SAAS,OAAO,QAAgC;AAC9C,YAAM,UAAU,YAAY,GAAG;AAC/B,qDAAgB;AAChB,aAAO;AAAA,QACL;AAAA,UACE,4BAA4B,MAAM,QAAQ,GAAG,GAAG,EAAE,aAAa;AAAA,UAC/D;AAAA,QAAA;AAAA,SAEF,6DAAyB;AAAA,MAAA;AAAA,IAE7B;AAAA,IACA,GAAI,gBAAgB,EAAE,aAAA;AAAA;AAAA;AAAA,IAGtB,GAAI,gBAAgB,aAAa;AAAA,MAC/B,WACE,gBAAgB;AAAA,IAAA;AAAA,IAEpB,GAAI,gBAAgB,SAAS;AAAA,MAC3B,OACE,gBAAgB;AAAA,IAAA;AAAA,EACpB;AAEF,SAAO,mBAA2B,SAAS,EAAE,KAAK,QAAQ;AAC5D;"}
+{"version":3,"file":"deep-agent-transport-recipe.js","sources":["../../../../agent-runtime/src/deep-agent-transport-recipe.ts"],"sourcesContent":["import type { ResourceElement } from \"@assistant-ui/tap\";\nimport type { Statewire, StatewireClient } from \"statewire\";\nimport {\n  type DeepAgentInterestDeclaration,\n  type DeepAgentMessageWindowDeclaration,\n  withDeclaredInterests,\n  withDeclaredMessageWindow,\n} from \"./message-window\";\nimport { withDeclaredPagedHistory } from \"./history-store\";\nimport { withDeclaredProtocolVersion } from \"./protocol\";\nimport {\n  attachRetryGate,\n  type AttachRetryGate,\n  createAttachInstrumentation,\n  type DeepAgentAttachTimingEvent,\n  type DeepAgentWakeRefusal,\n  parseRetryAfterHeaderMs,\n} from \"./statewire-attach-observer\";\nimport {\n  resolveStatewireTransportKind,\n  statewireTransport,\n  type StatewireTransportOptions,\n} from \"./statewire-transport\";\n\n/** Auth-header resolver for the transport; `staleAuth` is true right after an\n * auth rejection, so resolvers that can force-renew should honor it. */\nexport type DeepAgentHeadersResolver = (ctx: {\n  staleAuth: boolean;\n}) => Record<string, string> | Promise<Record<string, string>>;\n\n/** The statewire attach URL for a thread: the host's `…/v2/threads` mount plus the id. */\nexport function deepAgentThreadUrl({\n  baseUrl,\n  threadId,\n}: {\n  baseUrl: string;\n  threadId: string;\n}): string {\n  return `${baseUrl.replace(/\\/+$/, \"\")}/${encodeURIComponent(threadId)}`;\n}\n\nexport interface DeepAgentAttachTransportOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  /** SSE when true, WebSocket otherwise (`resolveStatewireTransportKind`). */\n  sse?: boolean;\n  /** A never-started chat: the transport makes no network calls until the first command send. */\n  isNew?: boolean;\n  /** Host session store (mobile); browser hosts mount `storage.session` on the thread instead. */\n  sessionStore?: StatewireClient.SessionStorage | undefined;\n  /** Observes every headers resolve (the diagnostics recorder's stale-auth seam). */\n  onAuthResolve?: ((ctx: { staleAuth: boolean }) => void) | undefined;\n  /** Attach timing + retry hints (see `statewire-attach-observer`). */\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  /**\n   * The head window declared on the attach (`x-athena-deep-agent-window`,\n   * see `message-window.ts`): the hello of a client the host does not\n   * remember carries the newest `size` messages. Part of the recipe so a\n   * pooled dial asks for the same shape as the thread's own attach — a pooled\n   * hello then seeds the very state the attach will reconcile. Omitted, the\n   * shared default is declared.\n   */\n  messageWindow?: DeepAgentMessageWindowDeclaration | undefined;\n  /**\n   * The view this thread's attach holds, read at every attach's header\n   * resolve (`x-athena-deep-agent-interests`, see `message-window.ts`): a\n   * re-attach's hello then carries the pages it had loaded on whichever host\n   * instance it lands on. `null` (a first attach) declares nothing. Not part\n   * of a pooled dial, which never held a view.\n   */\n  declaredInterests?: (() => DeepAgentInterestDeclaration | null) | undefined;\n  /**\n   * The surface pages cut lanes (see `DeepAgentProtocolDeclaration`), so its\n   * attach declares the lane-cut contract version. Part of the recipe so a\n   * pooled dial declares what the thread's own attach would; omitted, the\n   * default version is declared.\n   */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * The ONE recipe for a deep-agent thread transport — shared by the mounted\n * thread (`useDeepAgentThread`) and the prewarm pool, so a pre-dialed\n * connection is byte-for-byte the connection the thread would have opened\n * itself: same URL, same auth + wire-contract headers, same session lane, same\n * instrumentation.\n *\n * Every attach declares the surface's wire-contract version alongside the\n * host's auth headers (first WS frame / SSE request headers) — the server\n * half of version negotiation reads it in `authorize`. The headers resolve\n * also waits out any server `Retry-After` floor for the thread: both statewire\n * attach paths resolve headers before they dial, so this is the seam where a\n * hint can hold the next dial without touching the library's backoff.\n */\nexport function createDeepAgentAttachTransport<TState = unknown>({\n  baseUrl,\n  threadId,\n  headers,\n  sse = false,\n  isNew = false,\n  sessionStore,\n  onAuthResolve,\n  onAttachTiming,\n  retryGate = attachRetryGate,\n  messageWindow,\n  declaredInterests,\n  laneHistory = false,\n}: DeepAgentAttachTransportOptions): ResourceElement<\n  Statewire<TState | undefined>\n> {\n  const url = deepAgentThreadUrl({ baseUrl, threadId });\n  // The instrumentation wraps the transport actually built: SSE needs the\n  // fetch wrapper that reads a refused attach's `Retry-After`.\n  const useSse = resolveStatewireTransportKind({ sse }) === \"sse\";\n  const instrumentation = createAttachInstrumentation({\n    url,\n    sse: useSse,\n    onEvent: onAttachTiming,\n    retryGate,\n  });\n  const options: StatewireTransportOptions = {\n    url,\n    ...(isNew && { isNew: true }),\n    headers: async (ctx: { staleAuth: boolean }) => {\n      await retryGate.waitForDial(url);\n      onAuthResolve?.(ctx);\n      return withDeclaredInterests(\n        withDeclaredPagedHistory(\n          withDeclaredMessageWindow(\n            withDeclaredProtocolVersion(await headers(ctx), { laneHistory }),\n            messageWindow,\n          ),\n        ),\n        declaredInterests?.() ?? null,\n      );\n    },\n    ...(sessionStore && { sessionStore }),\n    // Structural types: this package compiles without the DOM lib, while\n    // statewire's option types name the browser `WebSocket`/`fetch`.\n    ...(instrumentation.webSocket && {\n      webSocket:\n        instrumentation.webSocket as unknown as StatewireTransportOptions[\"webSocket\"],\n    }),\n    ...(instrumentation.fetch && {\n      fetch:\n        instrumentation.fetch as unknown as StatewireTransportOptions[\"fetch\"],\n    }),\n  };\n  return statewireTransport<TState>(options, { sse: useSse });\n}\n\n/** What `POST …/prewarm` answered. */\nexport interface DeepAgentWakeResult {\n  status: number;\n  /** The host activated the thread and its history is resident. */\n  warm: boolean;\n  /**\n   * `'warm'` when the history was already memoized, `'fresh_load'` when this\n   * call loaded it; `null` when the host did not say (a refusal, or a host\n   * without the route).\n   */\n  history: \"fresh_load\" | \"warm\" | null;\n  /**\n   * The dial floor recorded for the thread off a 503/429 `Retry-After` — the\n   * header's value, except a 503 `\"worker\"` refusal, capped at\n   * {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n   */\n  retryAfterMs: number | null;\n  /** Who refused a 503/429 (see {@link DeepAgentWakeRefusal}); `null` for any other answer. */\n  refusal: DeepAgentWakeRefusal;\n  durationMs: number;\n}\n\n/**\n * Dial floor for a 503 the pinned worker produced about one instance's\n * lifecycle. Pinned answers every retriable 503 with a blanket\n * `Retry-After: 1`, but what those name — an instance record mid-teardown\n * (\"instance closing; retry\": fence release + placement release, ≈100 ms), a\n * full activation queue — clears far sooner than that, and the thread's own\n * attach is the request that carries the next activation. Holding it a full\n * second traded a ≈100 ms gap for a ≈1 s stall on every refused wake. A 429\n * is rate limiting and keeps its hint whatever the body says.\n */\nexport const WAKE_WORKER_REFUSAL_FLOOR_MS = 250;\n\n/**\n * The pinboard's own placement-refusal vocabulary — the `error` strings of\n * `@assistant-ui/pinboard` (`src/refusals.ts` plus the two inline refusals in\n * `src/server.ts`). Mirrors `PINBOARD_PLACEMENT_REFUSAL_ERRORS` in\n * `iris/scaler/src/v2AccessLog.ts`, whose test pins it to the installed\n * library; keep the two lists identical. A body with any other `error`\n * string is `\"unknown\"`, never `\"placement\"`.\n */\nexport const PINBOARD_PLACEMENT_REFUSAL_ERRORS: ReadonlySet<string> = new Set([\n  \"no live backends for namespace\",\n  \"registry cold start, retry\",\n  \"not the serving fleet\",\n  \"no live workers for hostname\",\n  \"hostname binding displaced, retry\",\n  \"hostname bindings inconsistent, retry\",\n  \"takeover in progress, retry\",\n  \"placement held by another hostname\",\n  \"worker inflight cap exceeded, retry\",\n  \"worker refused activation, retry\",\n]);\n\n/**\n * Pinned's instance-lifecycle refusals (`pinned/hosting/directory.py`,\n * `pinned/hosting/_records.py`): each names one instance on the worker the\n * thread is already placed on and clears in the time a teardown or an\n * activation slot takes. Anything else the worker answers 503 with — \"Thread\n * history load failed\", \"The regional conversation store is temporarily\n * unavailable\", a lease that expired — is not about one instance and keeps\n * the full hint.\n */\nexport const PINNED_TRANSIENT_WORKER_REFUSALS: ReadonlySet<string> = new Set([\n  \"instance closing; retry\",\n  \"instance aborted\",\n  \"activation queue full; retry\",\n  \"host draining; retry\",\n  \"instance capacity reached; retry\",\n  \"instance past its wind-down deadline; retry\",\n]);\n\n/**\n * Classify a 503/429 body (see {@link DeepAgentWakeRefusal}): a known pinboard\n * `error` is `\"placement\"`, a known pinned `detail` is `\"worker\"`, everything\n * else — including unfamiliar strings in either field — is `\"unknown\"`.\n */\nexport function classifyWakeRefusal(\n  body: unknown,\n): Exclude<DeepAgentWakeRefusal, null> {\n  if (typeof body === \"object\" && body !== null) {\n    const record = body as Record<string, unknown>;\n    if (\n      typeof record.error === \"string\" &&\n      PINBOARD_PLACEMENT_REFUSAL_ERRORS.has(record.error)\n    ) {\n      return \"placement\";\n    }\n    if (\n      typeof record.detail === \"string\" &&\n      PINNED_TRANSIENT_WORKER_REFUSALS.has(record.detail)\n    ) {\n      return \"worker\";\n    }\n  }\n  return \"unknown\";\n}\n\n/** Structural `fetch` for the wake call — this package compiles without the DOM lib. */\nexport type DeepAgentWakeFetch = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    keepalive?: boolean;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n}>;\n\nexport interface DeepAgentWakeOptions {\n  /** Base URL of the deep-agent statewire host (the `…/v2/threads` mount). */\n  baseUrl: string;\n  threadId: string;\n  headers: DeepAgentHeadersResolver;\n  fetch?: DeepAgentWakeFetch | undefined;\n  /** Dial floors from server retry hints; the process-wide gate by default. */\n  retryGate?: AttachRetryGate;\n  onAttachTiming?: ((event: DeepAgentAttachTimingEvent) => void) | undefined;\n  now?: () => number;\n  /** The surface pages cut lanes: declare what its attach declares (see `DeepAgentAttachTransportOptions`). */\n  laneHistory?: boolean | undefined;\n}\n\n/**\n * Wake a thread's server instance ahead of its attach. `POST …/prewarm` runs\n * the host's `authorize` and history load — the fence adopt, graph compile and\n * checkpoint read that make a cold attach's hello take ≈1 s — and answers with\n * no thread content, only whether the history was already resident. Fire it\n * on hover intent, before a pooled attach or the click's own dial, so the\n * activation overlaps the handshake and the attach that follows finds the\n * instance warm.\n *\n * Fire-and-forget by contract: every failure resolves `null`, and a host\n * without the route (404) is reported like any other non-OK answer. A 503/429\n * `Retry-After` is recorded as a dial floor for the thread, so the attach that\n * follows waits it out instead of bouncing — in full, except a 503 that names\n * one of pinned's instance-lifecycle refusals (one instance mid-teardown on\n * the worker the thread already has; see {@link DeepAgentWakeRefusal}), whose\n * floor is capped at {@link WAKE_WORKER_REFUSAL_FLOOR_MS}.\n */\nexport async function wakeDeepAgentThread({\n  baseUrl,\n  threadId,\n  headers,\n  fetch: fetchOverride,\n  retryGate = attachRetryGate,\n  onAttachTiming,\n  now = () => Date.now(),\n  laneHistory = false,\n}: DeepAgentWakeOptions): Promise<DeepAgentWakeResult | null> {\n  const fetchImpl =\n    fetchOverride ?? (globalThis as { fetch?: DeepAgentWakeFetch }).fetch;\n  if (typeof fetchImpl !== \"function\") return null;\n  const threadUrl = deepAgentThreadUrl({ baseUrl, threadId });\n  const emit = (event: DeepAgentAttachTimingEvent): void => {\n    try {\n      onAttachTiming?.(event);\n    } catch {\n      // Observers are best-effort.\n    }\n  };\n  const startedAt = now();\n  try {\n    const resolved = withDeclaredProtocolVersion(\n      await headers({ staleAuth: false }),\n      { laneHistory },\n    );\n    const response = await fetchImpl(`${threadUrl}/prewarm`, {\n      method: \"POST\",\n      headers: resolved,\n      keepalive: true,\n    });\n    const durationMs = now() - startedAt;\n    let retryAfterMs: number | null = null;\n    let refusal: DeepAgentWakeRefusal = null;\n    if (response.status === 503 || response.status === 429) {\n      let body: unknown = null;\n      try {\n        body = await response.json();\n      } catch {\n        // A refusal without a readable body is classified by nothing.\n      }\n      refusal = classifyWakeRefusal(body);\n      const hinted = parseRetryAfterHeaderMs(\n        response.headers.get(\"retry-after\"),\n        now,\n      );\n      if (hinted !== null) {\n        retryAfterMs =\n          response.status === 503 && refusal === \"worker\"\n            ? Math.min(hinted, WAKE_WORKER_REFUSAL_FLOOR_MS)\n            : hinted;\n        if (retryAfterMs > 0) {\n          retryGate.noteRetryAfter(threadUrl, retryAfterMs);\n          emit({\n            type: \"retry-after\",\n            url: threadUrl,\n            delayMs: retryAfterMs,\n            source: \"http-header\",\n          });\n        }\n      }\n    }\n    let warm = false;\n    let history: DeepAgentWakeResult[\"history\"] = null;\n    if (response.ok) {\n      try {\n        const body = (await response.json()) as {\n          warm?: unknown;\n          history?: unknown;\n        } | null;\n        warm = body?.warm === true;\n        history =\n          body?.history === \"warm\" || body?.history === \"fresh_load\"\n            ? body.history\n            : null;\n      } catch {\n        // A 200 without a JSON body still means the instance is up.\n        warm = true;\n      }\n    }\n    emit({\n      type: \"wake\",\n      url: threadUrl,\n      status: response.status,\n      durationMs,\n      history,\n      refusal,\n    });\n    return {\n      status: response.status,\n      warm,\n      history,\n      retryAfterMs,\n      refusal,\n      durationMs,\n    };\n  } catch {\n    return null;\n  }\n}\n"],"names":[],"mappings":";;;;;AA+BO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AACF,GAGW;AACT,SAAO,GAAG,QAAQ,QAAQ,QAAQ,EAAE,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AACvE;AA2DO,SAAS,+BAAiD;AAAA,EAC/D;AAAA,EACA;AAAA,EACA;AAAA,EACA,MAAM;AAAA,EACN,QAAQ;AAAA,EACR;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA;AAAA,EACA,cAAc;AAChB,GAEE;AACA,QAAM,MAAM,mBAAmB,EAAE,SAAS,UAAU;AAGpD,QAAM,SAAS,8BAA8B,EAAE,IAAA,CAAK,MAAM;AAC1D,QAAM,kBAAkB,4BAA4B;AAAA,IAClD;AAAA,IACA,KAAK;AAAA,IACL,SAAS;AAAA,IACT;AAAA,EAAA,CACD;AACD,QAAM,UAAqC;AAAA,IACzC;AAAA,IACA,GAAI,SAAS,EAAE,OAAO,KAAA;AAAA,IACtB,SAAS,OAAO,QAAgC;AAC9C,YAAM,UAAU,YAAY,GAAG;AAC/B,qDAAgB;AAChB,aAAO;AAAA,QACL;AAAA,UACE;AAAA,YACE,4BAA4B,MAAM,QAAQ,GAAG,GAAG,EAAE,aAAa;AAAA,YAC/D;AAAA,UAAA;AAAA,QACF;AAAA,SAEF,6DAAyB;AAAA,MAAA;AAAA,IAE7B;AAAA,IACA,GAAI,gBAAgB,EAAE,aAAA;AAAA;AAAA;AAAA,IAGtB,GAAI,gBAAgB,aAAa;AAAA,MAC/B,WACE,gBAAgB;AAAA,IAAA;AAAA,IAEpB,GAAI,gBAAgB,SAAS;AAAA,MAC3B,OACE,gBAAgB;AAAA,IAAA;AAAA,EACpB;AAEF,SAAO,mBAA2B,SAAS,EAAE,KAAK,QAAQ;AAC5D;"}

package/dist/agent-runtime/src/edit-command.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const runconfigContract = require("./generated/runconfig-contract.cjs");
+const historyStore = require("./history-store.cjs");
 const messageWindow = require("./message-window.cjs");
 const threadExtras = require("./thread-extras.cjs");
 function readDeepAgentStatewireExtras(extras) {
@@ -33,6 +34,38 @@ const readWindow = (extras) => {
   var _a;
   return messageWindow.readDeepAgentMessageWindow((_a = extras.documents) == null ? void 0 : _a.list());
 };
+const anchorMessages = (extras, window) => {
+  var _a;
+  return window !== null && (window.stored ?? 0) > 0 ? window.messages : (_a = extras.state) == null ? void 0 : _a.messages;
+};
+async function loadOlderPage(extras, window, pageSize) {
+  var _a;
+  if (!window.hasOlder) return false;
+  if (window.historyPaged && window.threadId !== void 0) {
+    const before = (_a = window.chain[0]) == null ? void 0 : _a.id;
+    if (before === void 0) return false;
+    const store = historyStore.deepAgentHistoryStore(window.threadId);
+    let payload;
+    try {
+      payload = await extras.sendCommand(historyStore.buildHistoryPageCommand({ before }));
+    } catch (error) {
+      if (!historyStore.isHistoryPageUnserved(error)) throw error;
+      store.markUnserved(extras.connection);
+      const live = readWindow(extras);
+      if (live === null || live.historyPaged) return false;
+      return loadOlderPage(extras, live, pageSize);
+    }
+    const page = historyStore.readHistoryPageResult(payload, before);
+    if (page === null) return false;
+    store.addPage(page);
+    return true;
+  }
+  if (!extras.invoke) return false;
+  const requests = messageWindow.pageInterestRequests(window, pageSize);
+  if (requests === null) return false;
+  await extras.invoke(runconfigContract.DEEP_AGENT_INTEREST_PROTOCOL, "set", [requests]);
+  return true;
+}
 function mintCommandId() {
   const webcrypto = globalThis.crypto;
   if (typeof (webcrypto == null ? void 0 : webcrypto.randomUUID) === "function") return webcrypto.randomUUID();
@@ -44,11 +77,11 @@ function buildDeepAgentEditCommand({
   sourceId,
   text
 }) {
-  var _a, _b;
+  const window = readWindow(extras);
   const runAnchorMessageId = resolveWireAnchorMessageId({
-    wireMessages: (_a = extras.state) == null ? void 0 : _a.messages,
+    wireMessages: anchorMessages(extras, window),
     sourceId,
-    hasOlder: ((_b = readWindow(extras)) == null ? void 0 : _b.hasOlder) ?? false
+    hasOlder: (window == null ? void 0 : window.hasOlder) ?? false
   });
   if (runAnchorMessageId === void 0) return null;
   return {
@@ -70,13 +103,10 @@ async function loadOlderDeepAgentHistoryPage({
   pageSize
 }) {
   const extras = readExtras();
-  if (!(extras == null ? void 0 : extras.invoke)) return false;
+  if (!extras) return false;
   const window = readWindow(extras);
-  if (window === null || !window.hasOlder) return false;
-  const requests = messageWindow.pageInterestRequests(window, pageSize);
-  if (requests === null) return false;
-  await extras.invoke(runconfigContract.DEEP_AGENT_INTEREST_PROTOCOL, "set", [requests]);
-  return true;
+  if (window === null) return false;
+  return loadOlderPage(extras, window, pageSize);
 }
 function isHistoryPageLostToReconnect(error) {
   if (typeof error !== "object" || error === null || !("failure" in error)) return false;
@@ -91,20 +121,17 @@ async function resolveDeepAgentEditCommand({
   pageSize,
   maxHistoryLoads = MAX_EDIT_ANCHOR_HISTORY_LOADS
 }) {
-  var _a;
   for (let page = 0; page <= maxHistoryLoads; page += 1) {
     const extras = readExtras();
     if (!extras) return null;
     const command = buildDeepAgentEditCommand({ extras, sourceId, text });
     if (command) return command;
-    if (page === maxHistoryLoads || !extras.invoke) return null;
+    if (page === maxHistoryLoads) return null;
     const window = readWindow(extras);
-    if (!isSourceBelowLoadedWindow({ wireMessages: (_a = extras.state) == null ? void 0 : _a.messages, sourceId, window })) {
+    if (window === null || !isSourceBelowLoadedWindow({ wireMessages: anchorMessages(extras, window), sourceId, window })) {
       return null;
     }
-    const requests = window === null ? null : messageWindow.pageInterestRequests(window, pageSize);
-    if (requests === null) return null;
-    await extras.invoke(runconfigContract.DEEP_AGENT_INTEREST_PROTOCOL, "set", [requests]);
+    if (!await loadOlderPage(extras, window, pageSize)) return null;
   }
   return null;
 }