@athenaintel/react 0.41.2 → 0.42.1

package/dist/agent-runtime/src/composer-markdown.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The composer markdown a chat message was sent from.
+ *
+ * The chat composer sends a message's plain text exactly as typed, because the
+ * model reads the text literally, and writes real formatting (bold, lists,
+ * code, mention chips) as markdown. The sent text alone no longer says which
+ * characters are formatting and which were typed: literal `**strong**` and
+ * bold `strong` both send `**strong**`, and `List<T>`, `a\\b` or `2*3*4` read
+ * as markup when the text is rendered as markdown. So the composer also
+ * attaches the draft the text was serialized from (the same document with its
+ * plain text escaped for markdown) under {@link DEEP_AGENT_COMPOSER_MARKDOWN_KEY}
+ * in the message's metadata, and only when the two differ.
+ *
+ * It rides the statewire message, the queue and steer lanes and the persisted
+ * HumanMessage (`additional_kwargs.metadata`, which the converter surfaces as
+ * `metadata.custom`). It is display-only: the bubble renders it, and Edit,
+ * branch-and-edit and a withdrawn turn load it back into the composer. The
+ * model reads the message text, never this. A message without it (older
+ * messages, other clients) renders its text as before.
+ *
+ * agora validates it with the same rule
+ * (`agora/graphs/athena_deep_agent/composer_markdown.py`).
+ */
+export declare const DEEP_AGENT_COMPOSER_MARKDOWN_KEY = "composer_markdown";
+/**
+ * Whether `markdown` is the draft of `text`: no longer than escaping could make
+ * it, and equal to it once backslashes are dropped and the draft's character
+ * references decoded. A draft that would show other
+ * words than the text the model read (another message's, a client's mistake) is
+ * not taken; such a message renders its text as before.
+ */
+export declare function isComposerMarkdownOfText({ markdown, text, }: {
+    markdown: string;
+    text: string;
+}): boolean;
+/**
+ * `markdown`, a draft, trimmed as its text is trimmed (`text.trim()`): a
+ * send that trims its text stays a draft of it. `markdown.trim()` would keep
+ * the `&#32;` a draft writes for the space its first line starts with, and the
+ * `\` of a line break whose newline it trims.
+ */
+export declare function trimComposerDraft(markdown: string): string;
+/**
+ * The composer markdown to render or load for a message whose metadata is
+ * `metadata` (a message's `metadata.custom`, or a lane entry's `metadata`) and
+ * whose text is `text`; `null` when it carries none, or one that is not a
+ * draft of `text`.
+ */
+export declare function readDeepAgentComposerMarkdown({ metadata, text, }: {
+    metadata: unknown;
+    text: string;
+}): string | null;
+/**
+ * How long a staged composer markdown waits for its submission
+ * ({@link stageComposerMarkdown}).
+ */
+export declare const STAGED_COMPOSER_MARKDOWN_TTL_MS = 10000;
+/**
+ * Stage the draft `markdown` of `text` for `threadId`'s next submission.
+ *
+ * statewire captures message metadata once per new user message
+ * (`getMessageMetadata`, patched into `@assistant-ui/react-statewire@0.31.0`)
+ * without saying which message it is for, so a composer stages its draft right
+ * before it sends and the runtime's getter takes it for the submission that
+ * follows ({@link withStagedComposerMarkdown}). A draft equal to its text adds
+ * nothing and clears the slot. A slot nobody takes within
+ * {@link STAGED_COMPOSER_MARKDOWN_TTL_MS} expires; one a submission the
+ * composer did not make takes is harmless, since a composer markdown that is
+ * not a draft of the message's own text is neither kept by agora nor rendered.
+ */
+export declare function stageComposerMarkdown({ threadId, text, markdown, now, }: {
+    threadId: string;
+    text: string;
+    markdown: string;
+    /** Test seam: the time of the send. */
+    now?: number;
+}): void;
+/**
+ * The message metadata for `threadId`'s submission now being journaled: the
+ * staged composer markdown, if one is waiting and fresh. Takes the slot.
+ */
+export declare function takeStagedComposerMarkdownMetadata(threadId: string, now?: number): Record<string, unknown> | undefined;
+type MessageMetadataGetter = () => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+/**
+ * A runtime's `getMessageMetadata` that also carries the composer markdown a
+ * composer staged for `threadId` ({@link stageComposerMarkdown}), on top of the
+ * host's own metadata (`getMessageMetadata`, when it has one). The slot is
+ * taken synchronously at submission, before the host's capture resolves, so a
+ * draft never rides a later message. With nothing staged the host's own value
+ * is returned as is.
+ */
+export declare function withStagedComposerMarkdown({ threadId, getMessageMetadata, }: {
+    threadId: string;
+    getMessageMetadata?: MessageMetadataGetter | undefined;
+}): MessageMetadataGetter;
+/** Test seam: drop every staged composer markdown. */
+export declare function resetStagedComposerMarkdown(): void;
+/**
+ * `metadata` with the composer markdown set to the draft `markdown` of `text`,
+ * or without it when the draft equals the text (it adds nothing then).
+ * Returns `undefined` when nothing is left.
+ */
+export declare function withDeepAgentComposerMarkdown({ metadata, text, markdown, }: {
+    metadata: Readonly<Record<string, unknown>> | undefined;
+    text: string;
+    markdown: string;
+}): Record<string, unknown> | undefined;
+export {};

package/dist/agent-runtime/src/composer-markdown.js

@@ -111,6 +111,15 @@ function withStagedComposerMarkdown({
     return captured instanceof Promise ? captured.then(merge) : merge(captured);
   };
 }
+function withDeepAgentComposerMarkdown({
+  metadata,
+  text,
+  markdown
+}) {
+  const { [DEEP_AGENT_COMPOSER_MARKDOWN_KEY]: _previous, ...rest } = metadata ?? {};
+  const next = markdown === text ? rest : { ...rest, [DEEP_AGENT_COMPOSER_MARKDOWN_KEY]: markdown };
+  return Object.keys(next).length > 0 ? next : void 0;
+}
 export {
   DEEP_AGENT_COMPOSER_MARKDOWN_KEY,
   STAGED_COMPOSER_MARKDOWN_TTL_MS,
@@ -119,6 +128,7 @@ export {
   stageComposerMarkdown,
   takeStagedComposerMarkdownMetadata,
   trimComposerDraft,
+  withDeepAgentComposerMarkdown,
   withStagedComposerMarkdown
 };
 //# sourceMappingURL=composer-markdown.js.map

package/dist/agent-runtime/src/composer-markdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"composer-markdown.js","sources":["../../../../agent-runtime/src/composer-markdown.ts"],"sourcesContent":["/**\n * The composer markdown a chat message was sent from.\n *\n * The chat composer sends a message's plain text exactly as typed, because the\n * model reads the text literally, and writes real formatting (bold, lists,\n * code, mention chips) as markdown. The sent text alone no longer says which\n * characters are formatting and which were typed: literal `**strong**` and\n * bold `strong` both send `**strong**`, and `List<T>`, `a\\\\b` or `2*3*4` read\n * as markup when the text is rendered as markdown. So the composer also\n * attaches the draft the text was serialized from (the same document with its\n * plain text escaped for markdown) under {@link DEEP_AGENT_COMPOSER_MARKDOWN_KEY}\n * in the message's metadata, and only when the two differ.\n *\n * It rides the statewire message, the queue and steer lanes and the persisted\n * HumanMessage (`additional_kwargs.metadata`, which the converter surfaces as\n * `metadata.custom`). It is display-only: the bubble renders it, and Edit,\n * branch-and-edit and a withdrawn turn load it back into the composer. The\n * model reads the message text, never this. A message without it (older\n * messages, other clients) renders its text as before.\n *\n * agora validates it with the same rule\n * (`agora/graphs/athena_deep_agent/composer_markdown.py`).\n */\nexport const DEEP_AGENT_COMPOSER_MARKDOWN_KEY = 'composer_markdown';\n\nconst DRAFT_CHARACTER_REFERENCES: Readonly<Record<string, string>> = {\n  lt: '<',\n  gt: '>',\n  amp: '&',\n  '#32': ' ',\n  '#9': '\\t',\n};\n\n/**\n * A sent text in comparable form: every backslash dropped (the draft's\n * escapes, and the `\\` before a hard break's newline, are backslashes).\n */\nconst comparableText = (text: string): string => text.replace(/\\\\/g, '');\n\n/**\n * A draft in comparable form: every backslash dropped, then the character\n * references the draft serializer writes decoded in one pass (`&lt;` and\n * `&gt;` for typed `<` and `>`, `&amp;` for a typed `&` that starts a\n * reference, so typed `&lt;` is `&amp;lt;`, and `&#32;` / `&#9;` for the space\n * or tab a line starts with, which markdown would otherwise drop).\n */\nconst comparableDraft = (markdown: string): string =>\n  comparableText(markdown).replace(\n    /&(lt|gt|amp|#32|#9);/g,\n    (reference, name: string) => DRAFT_CHARACTER_REFERENCES[name] ?? reference\n  );\n\n/**\n * Escaping at most turns one character into four (`<` → `&lt;`). A line's\n * first space becomes five (`&#32;`), but only once a line, so a whole line\n * with its line break stays under four a character; the slack covers short\n * texts. agora caps a stored draft the same way.\n */\nconst MAX_EXPANSION = 4;\nconst EXPANSION_SLACK_CHARS = 1024;\n\n/**\n * Whether `markdown` is the draft of `text`: no longer than escaping could make\n * it, and equal to it once backslashes are dropped and the draft's character\n * references decoded. A draft that would show other\n * words than the text the model read (another message's, a client's mistake) is\n * not taken; such a message renders its text as before.\n */\nexport function isComposerMarkdownOfText({\n  markdown,\n  text,\n}: {\n  markdown: string;\n  text: string;\n}): boolean {\n  return (\n    markdown.length <= text.length * MAX_EXPANSION + EXPANSION_SLACK_CHARS &&\n    comparableDraft(markdown) === comparableText(text)\n  );\n}\n\n/** The references a draft writes a line's first space or tab as. */\nconst DRAFT_WHITESPACE_REFERENCES: readonly string[] = ['&#32;', '&#9;'];\n\nconst isWhitespace = (character: string): boolean => /\\s/.test(character);\n\n/** A hard break in a draft: `\\` before the newline (the text holds the newline alone). */\nconst DRAFT_HARD_BREAK = '\\\\\\n';\n\n/** Whether an odd run of backslashes ends at `end`: its last one escapes what follows, not a typed `\\` (`\\\\`). */\nfunction endsInEscapingBackslash({\n  markdown,\n  start,\n  end,\n}: {\n  markdown: string;\n  start: number;\n  end: number;\n}): boolean {\n  let backslashes = 0;\n  while (end - backslashes > start && markdown.charAt(end - backslashes - 1) === '\\\\') {\n    backslashes += 1;\n  }\n  return backslashes % 2 === 1;\n}\n\n/**\n * `markdown`, a draft, trimmed as its text is trimmed (`text.trim()`): a\n * send that trims its text stays a draft of it. `markdown.trim()` would keep\n * the `&#32;` a draft writes for the space its first line starts with, and the\n * `\\` of a line break whose newline it trims.\n */\nexport function trimComposerDraft(markdown: string): string {\n  let start = 0;\n  let end = markdown.length;\n  for (;;) {\n    while (start < end && isWhitespace(markdown.charAt(start))) start += 1;\n    const reference = [...DRAFT_WHITESPACE_REFERENCES, DRAFT_HARD_BREAK].find(\n      (candidate) => start + candidate.length <= end && markdown.startsWith(candidate, start)\n    );\n    if (reference === undefined) break;\n    start += reference.length;\n  }\n  for (;;) {\n    while (end > start && isWhitespace(markdown.charAt(end - 1))) end -= 1;\n    const reference = DRAFT_WHITESPACE_REFERENCES.find(\n      (candidate) => end - candidate.length >= start && markdown.endsWith(candidate, end)\n    );\n    if (reference !== undefined) {\n      end -= reference.length;\n    } else if (\n      markdown.charAt(end) === '\\n' &&\n      endsInEscapingBackslash({ markdown, start, end })\n    ) {\n      // The newline just trimmed was a line break's: its `\\` goes with it.\n      end -= 1;\n    } else {\n      break;\n    }\n  }\n  return markdown.slice(start, end);\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/**\n * The composer markdown to render or load for a message whose metadata is\n * `metadata` (a message's `metadata.custom`, or a lane entry's `metadata`) and\n * whose text is `text`; `null` when it carries none, or one that is not a\n * draft of `text`.\n */\nexport function readDeepAgentComposerMarkdown({\n  metadata,\n  text,\n}: {\n  metadata: unknown;\n  text: string;\n}): string | null {\n  if (!isRecord(metadata)) return null;\n  const markdown: unknown = metadata[DEEP_AGENT_COMPOSER_MARKDOWN_KEY];\n  return typeof markdown === 'string' && isComposerMarkdownOfText({ markdown, text })\n    ? markdown\n    : null;\n}\n\n/**\n * How long a staged composer markdown waits for its submission\n * ({@link stageComposerMarkdown}).\n */\nexport const STAGED_COMPOSER_MARKDOWN_TTL_MS = 10_000;\n\ninterface StagedComposerMarkdown {\n  readonly markdown: string;\n  readonly stagedAt: number;\n}\n\n/**\n * The staged drafts live on `globalThis`, not in module scope, because two\n * copies of this module run in one page: the SDK bundles agent-runtime into its\n * dist, so its composer stages through the SDK's copy, while the Chrome\n * extension and the Office add-in build their runtime on agent-runtime directly\n * and take the draft through their own (see `asset-attachment.ts`).\n */\nconst STAGED_COMPOSER_MARKDOWN = Symbol.for('@athenaintel/agent-runtime/staged-composer-markdown');\n\ntype StagedComposerMarkdownHost = typeof globalThis & {\n  [STAGED_COMPOSER_MARKDOWN]?: Map<string, StagedComposerMarkdown>;\n};\n\nfunction stagedComposerMarkdownByThread(): Map<string, StagedComposerMarkdown> {\n  const host = globalThis as StagedComposerMarkdownHost;\n  return (host[STAGED_COMPOSER_MARKDOWN] ??= new Map());\n}\n\n/**\n * Stage the draft `markdown` of `text` for `threadId`'s next submission.\n *\n * statewire captures message metadata once per new user message\n * (`getMessageMetadata`, patched into `@assistant-ui/react-statewire@0.31.0`)\n * without saying which message it is for, so a composer stages its draft right\n * before it sends and the runtime's getter takes it for the submission that\n * follows ({@link withStagedComposerMarkdown}). A draft equal to its text adds\n * nothing and clears the slot. A slot nobody takes within\n * {@link STAGED_COMPOSER_MARKDOWN_TTL_MS} expires; one a submission the\n * composer did not make takes is harmless, since a composer markdown that is\n * not a draft of the message's own text is neither kept by agora nor rendered.\n */\nexport function stageComposerMarkdown({\n  threadId,\n  text,\n  markdown,\n  now = Date.now(),\n}: {\n  threadId: string;\n  text: string;\n  markdown: string;\n  /** Test seam: the time of the send. */\n  now?: number;\n}): void {\n  const staged = stagedComposerMarkdownByThread();\n  if (markdown === text) {\n    staged.delete(threadId);\n    return;\n  }\n  staged.set(threadId, { markdown, stagedAt: now });\n}\n\n/**\n * The message metadata for `threadId`'s submission now being journaled: the\n * staged composer markdown, if one is waiting and fresh. Takes the slot.\n */\nexport function takeStagedComposerMarkdownMetadata(\n  threadId: string,\n  now: number = Date.now()\n): Record<string, unknown> | undefined {\n  const staged = stagedComposerMarkdownByThread();\n  const entry = staged.get(threadId);\n  staged.delete(threadId);\n  if (entry === undefined || now - entry.stagedAt > STAGED_COMPOSER_MARKDOWN_TTL_MS) {\n    return undefined;\n  }\n  return { [DEEP_AGENT_COMPOSER_MARKDOWN_KEY]: entry.markdown };\n}\n\ntype MessageMetadataGetter = () =>\n  | Record<string, unknown>\n  | undefined\n  | Promise<Record<string, unknown> | undefined>;\n\n/**\n * A runtime's `getMessageMetadata` that also carries the composer markdown a\n * composer staged for `threadId` ({@link stageComposerMarkdown}), on top of the\n * host's own metadata (`getMessageMetadata`, when it has one). The slot is\n * taken synchronously at submission, before the host's capture resolves, so a\n * draft never rides a later message. With nothing staged the host's own value\n * is returned as is.\n */\nexport function withStagedComposerMarkdown({\n  threadId,\n  getMessageMetadata,\n}: {\n  threadId: string;\n  getMessageMetadata?: MessageMetadataGetter | undefined;\n}): MessageMetadataGetter {\n  return () => {\n    const staged = takeStagedComposerMarkdownMetadata(threadId);\n    const captured = getMessageMetadata?.();\n    if (staged === undefined) return captured;\n    const merge = (host: Record<string, unknown> | undefined): Record<string, unknown> => ({\n      ...host,\n      ...staged,\n    });\n    return captured instanceof Promise ? captured.then(merge) : merge(captured);\n  };\n}\n\n/** Test seam: drop every staged composer markdown. */\nexport function resetStagedComposerMarkdown(): void {\n  stagedComposerMarkdownByThread().clear();\n}\n\n/**\n * `metadata` with the composer markdown set to the draft `markdown` of `text`,\n * or without it when the draft equals the text (it adds nothing then).\n * Returns `undefined` when nothing is left.\n */\nexport function withDeepAgentComposerMarkdown({\n  metadata,\n  text,\n  markdown,\n}: {\n  metadata: Readonly<Record<string, unknown>> | undefined;\n  text: string;\n  markdown: string;\n}): Record<string, unknown> | undefined {\n  const { [DEEP_AGENT_COMPOSER_MARKDOWN_KEY]: _previous, ...rest } = metadata ?? {};\n  const next: Record<string, unknown> =\n    markdown === text ? rest : { ...rest, [DEEP_AGENT_COMPOSER_MARKDOWN_KEY]: markdown };\n  return Object.keys(next).length > 0 ? next : undefined;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"composer-markdown.js","sources":["../../../../agent-runtime/src/composer-markdown.ts"],"sourcesContent":["/**\n * The composer markdown a chat message was sent from.\n *\n * The chat composer sends a message's plain text exactly as typed, because the\n * model reads the text literally, and writes real formatting (bold, lists,\n * code, mention chips) as markdown. The sent text alone no longer says which\n * characters are formatting and which were typed: literal `**strong**` and\n * bold `strong` both send `**strong**`, and `List<T>`, `a\\\\b` or `2*3*4` read\n * as markup when the text is rendered as markdown. So the composer also\n * attaches the draft the text was serialized from (the same document with its\n * plain text escaped for markdown) under {@link DEEP_AGENT_COMPOSER_MARKDOWN_KEY}\n * in the message's metadata, and only when the two differ.\n *\n * It rides the statewire message, the queue and steer lanes and the persisted\n * HumanMessage (`additional_kwargs.metadata`, which the converter surfaces as\n * `metadata.custom`). It is display-only: the bubble renders it, and Edit,\n * branch-and-edit and a withdrawn turn load it back into the composer. The\n * model reads the message text, never this. A message without it (older\n * messages, other clients) renders its text as before.\n *\n * agora validates it with the same rule\n * (`agora/graphs/athena_deep_agent/composer_markdown.py`).\n */\nexport const DEEP_AGENT_COMPOSER_MARKDOWN_KEY = 'composer_markdown';\n\nconst DRAFT_CHARACTER_REFERENCES: Readonly<Record<string, string>> = {\n  lt: '<',\n  gt: '>',\n  amp: '&',\n  '#32': ' ',\n  '#9': '\\t',\n};\n\n/**\n * A sent text in comparable form: every backslash dropped (the draft's\n * escapes, and the `\\` before a hard break's newline, are backslashes).\n */\nconst comparableText = (text: string): string => text.replace(/\\\\/g, '');\n\n/**\n * A draft in comparable form: every backslash dropped, then the character\n * references the draft serializer writes decoded in one pass (`&lt;` and\n * `&gt;` for typed `<` and `>`, `&amp;` for a typed `&` that starts a\n * reference, so typed `&lt;` is `&amp;lt;`, and `&#32;` / `&#9;` for the space\n * or tab a line starts with, which markdown would otherwise drop).\n */\nconst comparableDraft = (markdown: string): string =>\n  comparableText(markdown).replace(\n    /&(lt|gt|amp|#32|#9);/g,\n    (reference, name: string) => DRAFT_CHARACTER_REFERENCES[name] ?? reference\n  );\n\n/**\n * Escaping at most turns one character into four (`<` → `&lt;`). A line's\n * first space becomes five (`&#32;`), but only once a line, so a whole line\n * with its line break stays under four a character; the slack covers short\n * texts. agora caps a stored draft the same way.\n */\nconst MAX_EXPANSION = 4;\nconst EXPANSION_SLACK_CHARS = 1024;\n\n/**\n * Whether `markdown` is the draft of `text`: no longer than escaping could make\n * it, and equal to it once backslashes are dropped and the draft's character\n * references decoded. A draft that would show other\n * words than the text the model read (another message's, a client's mistake) is\n * not taken; such a message renders its text as before.\n */\nexport function isComposerMarkdownOfText({\n  markdown,\n  text,\n}: {\n  markdown: string;\n  text: string;\n}): boolean {\n  return (\n    markdown.length <= text.length * MAX_EXPANSION + EXPANSION_SLACK_CHARS &&\n    comparableDraft(markdown) === comparableText(text)\n  );\n}\n\n/** The references a draft writes a line's first space or tab as. */\nconst DRAFT_WHITESPACE_REFERENCES: readonly string[] = ['&#32;', '&#9;'];\n\nconst isWhitespace = (character: string): boolean => /\\s/.test(character);\n\n/** A hard break in a draft: `\\` before the newline (the text holds the newline alone). */\nconst DRAFT_HARD_BREAK = '\\\\\\n';\n\n/** Whether an odd run of backslashes ends at `end`: its last one escapes what follows, not a typed `\\` (`\\\\`). */\nfunction endsInEscapingBackslash({\n  markdown,\n  start,\n  end,\n}: {\n  markdown: string;\n  start: number;\n  end: number;\n}): boolean {\n  let backslashes = 0;\n  while (end - backslashes > start && markdown.charAt(end - backslashes - 1) === '\\\\') {\n    backslashes += 1;\n  }\n  return backslashes % 2 === 1;\n}\n\n/**\n * `markdown`, a draft, trimmed as its text is trimmed (`text.trim()`): a\n * send that trims its text stays a draft of it. `markdown.trim()` would keep\n * the `&#32;` a draft writes for the space its first line starts with, and the\n * `\\` of a line break whose newline it trims.\n */\nexport function trimComposerDraft(markdown: string): string {\n  let start = 0;\n  let end = markdown.length;\n  for (;;) {\n    while (start < end && isWhitespace(markdown.charAt(start))) start += 1;\n    const reference = [...DRAFT_WHITESPACE_REFERENCES, DRAFT_HARD_BREAK].find(\n      (candidate) => start + candidate.length <= end && markdown.startsWith(candidate, start)\n    );\n    if (reference === undefined) break;\n    start += reference.length;\n  }\n  for (;;) {\n    while (end > start && isWhitespace(markdown.charAt(end - 1))) end -= 1;\n    const reference = DRAFT_WHITESPACE_REFERENCES.find(\n      (candidate) => end - candidate.length >= start && markdown.endsWith(candidate, end)\n    );\n    if (reference !== undefined) {\n      end -= reference.length;\n    } else if (\n      markdown.charAt(end) === '\\n' &&\n      endsInEscapingBackslash({ markdown, start, end })\n    ) {\n      // The newline just trimmed was a line break's: its `\\` goes with it.\n      end -= 1;\n    } else {\n      break;\n    }\n  }\n  return markdown.slice(start, end);\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/**\n * The composer markdown to render or load for a message whose metadata is\n * `metadata` (a message's `metadata.custom`, or a lane entry's `metadata`) and\n * whose text is `text`; `null` when it carries none, or one that is not a\n * draft of `text`.\n */\nexport function readDeepAgentComposerMarkdown({\n  metadata,\n  text,\n}: {\n  metadata: unknown;\n  text: string;\n}): string | null {\n  if (!isRecord(metadata)) return null;\n  const markdown: unknown = metadata[DEEP_AGENT_COMPOSER_MARKDOWN_KEY];\n  return typeof markdown === 'string' && isComposerMarkdownOfText({ markdown, text })\n    ? markdown\n    : null;\n}\n\n/**\n * How long a staged composer markdown waits for its submission\n * ({@link stageComposerMarkdown}).\n */\nexport const STAGED_COMPOSER_MARKDOWN_TTL_MS = 10_000;\n\ninterface StagedComposerMarkdown {\n  readonly markdown: string;\n  readonly stagedAt: number;\n}\n\n/**\n * The staged drafts live on `globalThis`, not in module scope, because two\n * copies of this module run in one page: the SDK bundles agent-runtime into its\n * dist, so its composer stages through the SDK's copy, while the Chrome\n * extension and the Office add-in build their runtime on agent-runtime directly\n * and take the draft through their own (see `asset-attachment.ts`).\n */\nconst STAGED_COMPOSER_MARKDOWN = Symbol.for('@athenaintel/agent-runtime/staged-composer-markdown');\n\ntype StagedComposerMarkdownHost = typeof globalThis & {\n  [STAGED_COMPOSER_MARKDOWN]?: Map<string, StagedComposerMarkdown>;\n};\n\nfunction stagedComposerMarkdownByThread(): Map<string, StagedComposerMarkdown> {\n  const host = globalThis as StagedComposerMarkdownHost;\n  return (host[STAGED_COMPOSER_MARKDOWN] ??= new Map());\n}\n\n/**\n * Stage the draft `markdown` of `text` for `threadId`'s next submission.\n *\n * statewire captures message metadata once per new user message\n * (`getMessageMetadata`, patched into `@assistant-ui/react-statewire@0.31.0`)\n * without saying which message it is for, so a composer stages its draft right\n * before it sends and the runtime's getter takes it for the submission that\n * follows ({@link withStagedComposerMarkdown}). A draft equal to its text adds\n * nothing and clears the slot. A slot nobody takes within\n * {@link STAGED_COMPOSER_MARKDOWN_TTL_MS} expires; one a submission the\n * composer did not make takes is harmless, since a composer markdown that is\n * not a draft of the message's own text is neither kept by agora nor rendered.\n */\nexport function stageComposerMarkdown({\n  threadId,\n  text,\n  markdown,\n  now = Date.now(),\n}: {\n  threadId: string;\n  text: string;\n  markdown: string;\n  /** Test seam: the time of the send. */\n  now?: number;\n}): void {\n  const staged = stagedComposerMarkdownByThread();\n  if (markdown === text) {\n    staged.delete(threadId);\n    return;\n  }\n  staged.set(threadId, { markdown, stagedAt: now });\n}\n\n/**\n * The message metadata for `threadId`'s submission now being journaled: the\n * staged composer markdown, if one is waiting and fresh. Takes the slot.\n */\nexport function takeStagedComposerMarkdownMetadata(\n  threadId: string,\n  now: number = Date.now()\n): Record<string, unknown> | undefined {\n  const staged = stagedComposerMarkdownByThread();\n  const entry = staged.get(threadId);\n  staged.delete(threadId);\n  if (entry === undefined || now - entry.stagedAt > STAGED_COMPOSER_MARKDOWN_TTL_MS) {\n    return undefined;\n  }\n  return { [DEEP_AGENT_COMPOSER_MARKDOWN_KEY]: entry.markdown };\n}\n\ntype MessageMetadataGetter = () =>\n  | Record<string, unknown>\n  | undefined\n  | Promise<Record<string, unknown> | undefined>;\n\n/**\n * A runtime's `getMessageMetadata` that also carries the composer markdown a\n * composer staged for `threadId` ({@link stageComposerMarkdown}), on top of the\n * host's own metadata (`getMessageMetadata`, when it has one). The slot is\n * taken synchronously at submission, before the host's capture resolves, so a\n * draft never rides a later message. With nothing staged the host's own value\n * is returned as is.\n */\nexport function withStagedComposerMarkdown({\n  threadId,\n  getMessageMetadata,\n}: {\n  threadId: string;\n  getMessageMetadata?: MessageMetadataGetter | undefined;\n}): MessageMetadataGetter {\n  return () => {\n    const staged = takeStagedComposerMarkdownMetadata(threadId);\n    const captured = getMessageMetadata?.();\n    if (staged === undefined) return captured;\n    const merge = (host: Record<string, unknown> | undefined): Record<string, unknown> => ({\n      ...host,\n      ...staged,\n    });\n    return captured instanceof Promise ? captured.then(merge) : merge(captured);\n  };\n}\n\n/** Test seam: drop every staged composer markdown. */\nexport function resetStagedComposerMarkdown(): void {\n  stagedComposerMarkdownByThread().clear();\n}\n\n/**\n * `metadata` with the composer markdown set to the draft `markdown` of `text`,\n * or without it when the draft equals the text (it adds nothing then).\n * Returns `undefined` when nothing is left.\n */\nexport function withDeepAgentComposerMarkdown({\n  metadata,\n  text,\n  markdown,\n}: {\n  metadata: Readonly<Record<string, unknown>> | undefined;\n  text: string;\n  markdown: string;\n}): Record<string, unknown> | undefined {\n  const { [DEEP_AGENT_COMPOSER_MARKDOWN_KEY]: _previous, ...rest } = metadata ?? {};\n  const next: Record<string, unknown> =\n    markdown === text ? rest : { ...rest, [DEEP_AGENT_COMPOSER_MARKDOWN_KEY]: markdown };\n  return Object.keys(next).length > 0 ? next : undefined;\n}\n"],"names":[],"mappings":"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"}

package/dist/agent-runtime/src/config-mutations.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure transforms behind the `config/*` command family — the client-side
+ * mirror of `agora/agora/graphs/athena_deep_agent/thread_config.py`
+ * (`apply_config_patch` / `apply_tools_enable` / `apply_tools_disable`).
+ *
+ * The hook folds these over `state.config.custom` while a command is in
+ * flight so the UI reflects the write immediately; the server applies the same
+ * transform under the config row's lock, so the optimistic and the durable
+ * result agree whenever no other device wrote in between — and compose
+ * (rather than conflict) when one did.
+ */
+export type ThreadConfigCustom = Record<string, unknown>;
+/** A `config/patch` payload: `null` unsets the key. */
+export type ThreadConfigPatch = Record<string, unknown | null>;
+/** Set / unset top-level keys. `panel_config` is never part of the server config. */
+export declare function applyConfigPatch(custom: ThreadConfigCustom, patch: ThreadConfigPatch): ThreadConfigCustom;
+/**
+ * Append ids to `enabled_tools` (deduplicated, order preserved) and lift
+ * them out of `excluded_tools` / `declined_toolkit_ids`.
+ */
+export declare function applyToolsEnable(custom: ThreadConfigCustom, toolIds: readonly string[]): ThreadConfigCustom;
+/**
+ * Remove ids from an explicit `enabled_tools` list; an id that is not in the
+ * list (or a thread without one — running its collab agent's compiled
+ * toolkits) is recorded in `declined_toolkit_ids` so the opt-out sticks.
+ */
+export declare function applyToolsDisable(custom: ThreadConfigCustom, toolIds: readonly string[]): ThreadConfigCustom;
+/** A thread's currently enabled tool ids — `null` when the thread has no explicit list (defers to its agent). */
+export declare function readEnabledTools(custom: ThreadConfigCustom | null | undefined): string[] | null;
+/** The `declined_toolkit_ids` advisory list (empty when absent). */
+export declare function readDeclinedToolkitIds(custom: ThreadConfigCustom | null | undefined): string[];
+/**
+ * The subset of a `runConfig.custom` payload a client is allowed to carry per
+ * send on a server-configured thread (`RUN_CONFIG_PER_SEND_CUSTOM_KEYS`).
+ * Every other key is owned by the server config lane and would be dropped at
+ * dispatch, so sending it only invites drift between what a client thinks it
+ * asked for and what ran.
+ */
+export declare function pickPerSendCustom(custom: ThreadConfigCustom): ThreadConfigCustom;
+/**
+ * The subset of a `runConfig.custom` payload the thread's server config lane
+ * owns (`THREAD_CONFIG_CUSTOM_KEYS`) — what a client seeds a fresh thread with
+ * through `config/patch` before its first send.
+ */
+export declare function pickThreadConfigCustom(custom: ThreadConfigCustom): ThreadConfigCustom;
+/**
+ * The `config/patch` that turns `current` into `desired` over the thread-config
+ * keys: changed keys carry their new value, keys absent from `desired` carry
+ * `null` (unset). `null` when nothing differs.
+ */
+export declare function diffThreadConfig(current: ThreadConfigCustom, desired: ThreadConfigCustom): ThreadConfigPatch | null;

package/dist/agent-runtime/src/conversation-index.d.ts

@@ -0,0 +1,110 @@
+import { type StatewireClient } from 'statewire';
+import type { ConversationAttention, ConversationAttentionSource } from './conversation-list';
+import type { DeepAgentHeadersResolver } from './use-deep-agent-thread';
+/**
+ * Client side of the conversation-index statewire (issue #29088): agora
+ * replicates the newest page of one viewer's conversation list as one state
+ * object, so thread creation / lifecycle / title changes arrive as ops
+ * instead of newest-page polling. The replicated rows are renderable and the
+ * typed commands extend or refresh the inclusive window; reconnects are free
+ * because the protocol's snapshot-first attach IS the newest-page reconcile.
+ *
+ * A viewer is a `(workspaceId, userId)` pair and every pair is its own
+ * instance (`/conversation-index/<workspaceId>-<userId>`): workspaces are
+ * tenants, so a tab in one workspace never shares a window with a tab in
+ * another, and switching workspaces attaches to a different instance instead
+ * of retagging the one other tabs are still reading.
+ */
+export interface ConversationIndexEntry {
+    thread_id: string;
+    title: string;
+    updated_at: string;
+    state: string | null;
+    runtime: string | null;
+    start_channel: string | null;
+    asset_type: string;
+    asset_id: string | null;
+    app_id: string | null;
+    trigger_type: string | null;
+    last_message_preview: string | null;
+    message_count: number | null;
+    is_unread: boolean | null;
+    /**
+     * Canonical status_v2 planes, present once the publishing agora reports them
+     * (absent from snapshots replicated by an older pod during a rollout).
+     */
+    session_status?: string | null;
+    run_status?: string | null;
+    /**
+     * The viewer's attention state and its one-line next action, present once
+     * the publishing agora derives them (absent from snapshots replicated by
+     * an older pod). Pull-request state is never pushed — it rides the list
+     * fetch only (`include_pull_requests`).
+     */
+    attention?: ConversationAttention | null;
+    next_action?: string | null;
+    attention_source?: ConversationAttentionSource | null;
+    is_favorited?: boolean | null;
+}
+/**
+ * When one of this viewer's own asset subscriptions on a thread last queued or
+ * settled an event: thread id → ISO instant. A contentless "re-read now" for
+ * Olympus's Watching card, which reads what changed through its own gated
+ * query; it never says what changed, who changed it, or where. Absent from an
+ * older agora's snapshot.
+ */
+export type ConversationWatchActivity = Readonly<Record<string, string>>;
+export interface UseConversationIndexOptions {
+    /** Base URL of the conversation-index host (the `…/v2/conversation-index` mount). */
+    baseUrl: string;
+    /** The workspace being viewed — half of the instance id. Callers gate mounting on it. */
+    workspaceId: string;
+    /** The signed-in user's id — the other half. Callers gate mounting on it. */
+    userId: string;
+    /** Transport selection: SSE when true, WebSocket otherwise. */
+    sse?: boolean;
+    headers: DeepAgentHeadersResolver;
+    /** Park the transport until the caller has a resolved principal. */
+    enabled?: boolean;
+}
+export interface UseConversationIndexResult {
+    /** Newest-page entries, or `null` until the attach snapshot applies. */
+    entries: ConversationIndexEntry[] | null;
+    hasNextPage: boolean;
+    totalCount: number | null;
+    /**
+     * The viewer's watch-activity stamps (see {@link ConversationWatchActivity});
+     * `null` until the snapshot applies or when the host does not send them.
+     */
+    watchActivity: ConversationWatchActivity | null;
+    connection: StatewireClient.Connection;
+    refresh: () => Promise<void>;
+    loadMore: () => Promise<void>;
+}
+/** The conversation-index host is mounted beside the threads host. */
+export declare function conversationIndexUrlFromStatewireUrl(statewireUrl: string): string;
+/** Instance id of one viewer's index; mirrors agora's `conversation_index_id`. */
+export declare function conversationIndexId({ workspaceId, userId, }: {
+    workspaceId: string;
+    userId: string;
+}): string;
+/**
+ * Attach to the live conversation index of one `(workspace, user)` viewer.
+ */
+export declare function useConversationIndex({ baseUrl, workspaceId, userId, sse, headers, enabled, }: UseConversationIndexOptions): UseConversationIndexResult;
+/**
+ * Stable change fingerprint over a snapshot's watch-activity stamps: the
+ * well-formed `[threadId, instant]` pairs, sorted by thread. An empty string
+ * means "nothing sent yet" (no snapshot, or a host that predates the stamps),
+ * so an effect keyed on it skips; an applied-but-empty map is `'[]'`.
+ */
+export declare function watchActivityFingerprint(activity: unknown): string;
+/**
+ * Stable change fingerprint over the entries a list surface reacts to. An
+ * empty string means "no snapshot yet" — effects keyed on the fingerprint
+ * should treat it as a no-op rather than an empty list. An applied-but-empty
+ * snapshot serializes to `'[]'`, so deleting the last conversation still
+ * changes the fingerprint. JSON-encoding keeps arbitrary titles from
+ * colliding across field or entry boundaries.
+ */
+export declare function conversationIndexFingerprint(entries: ConversationIndexEntry[] | null): string;