@athenaintel/react 0.57.1 → 0.59.0

package/dist/references/src/anchors/types.js

@@ -42,9 +42,14 @@ const LEGACY_ANCHOR_TYPES = {
 function isAnchorType(value) {
   return typeof value === "string" && Object.values(AnchorType).includes(value);
 }
+function isAnchor(value) {
+  if (typeof value !== "object" || value === null) return false;
+  return isAnchorType(value.type);
+}
 export {
   AnchorType,
   LEGACY_ANCHOR_TYPES,
+  isAnchor,
   isAnchorType
 };
 //# sourceMappingURL=types.js.map

package/dist/references/src/anchors/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../../../../references/src/anchors/types.ts"],"sourcesContent":["/**\n * Anchor types — Level 2 of the reference system.\n *\n * Each anchor describes a specific location within an asset.\n * Discriminated union on `type`. Ordered alphabetically.\n *\n * Property names use camelCase; the `type` discriminator string stays snake_case\n * (it's a version identifier, not a property name).\n */\n\n// ---------------------------------------------------------------------------\n// Individual anchor types (alphabetical by `type` discriminator)\n// ---------------------------------------------------------------------------\n\nexport type CellAnchor = { type: 'cell'; cellId: string };\nexport type CellRangeAnchor = {\n  type: 'cell_range';\n  startCellId: string;\n  endCellId: string;\n};\nexport type CommentAnchor = {\n  type: 'comment';\n  threadId: string;\n  commentId: string;\n};\nexport type CommentThreadAnchor = { type: 'comment_thread'; threadId: string };\n/**\n * An inclusive, 1-based line range of one file of a repository source — a\n * GitHub `catalog` asset whose files Clio indexes\n * (`docs/clio/21-repository-source.md`). `path` is the repo-relative,\n * `/`-separated file path: structure, not content. Distinct from the\n * path-less `line_range` so a reader that does not know the kind fails closed\n * instead of dropping the file. Bounds, path grammar and the byte cap are\n * shared with Clio's `LineRangeLocator` (`./file-line-range.ts`).\n *\n * Wire form (canonical — parameters sorted, as Clio writes it):\n * `anchor=file_line_range&end_line=<m>&path=<path>&start_line=<n>`.\n */\nexport type FileLineRangeAnchor = {\n  type: 'file_line_range';\n  path: string;\n  startLine: number;\n  endLine: number;\n};\nexport type LineAnchor = { type: 'line'; line: number };\nexport type LineRangeAnchor = {\n  type: 'line_range';\n  startLine: number;\n  endLine: number;\n};\n/**\n * A single chat message in a session transcript.\n *\n * `messageId` is the **Athena message tracking id** — the same uuid4 that\n * appears as `user_message_tracking_id` / `ai_message_tracking_id` in Keryx\n * activity attributions (built by `build_agent_attributions`,\n * agora/services/keryx/client.py), as `trackingId` on session Y.Doc\n * liveMessages, as the `data-message-tracking-id` DOM attribute, and as the\n * existing `scroll_to_message` URL param in Olympus. It is NOT the LangChain\n * checkpoint `message.id`.\n *\n * Wire form: `anchor=msg&msg_id=…` (the pre-rename spellings\n * `anchor=message&message_id=…` are still parsed).\n */\nexport type MessageAnchor = { type: 'msg'; messageId: string };\n/**\n * Inclusive span of session messages in transcript order. Both ids are\n * Athena message tracking ids (see `MessageAnchor`).\n */\nexport type MessageRangeAnchor = {\n  type: 'msg_range';\n  startMessageId: string;\n  endMessageId: string;\n};\n/**\n * One top-level block (paragraph, heading, list, table, code fence, …) of a\n * session message's markdown body. `messageId` is the Athena message tracking\n * id (see `MessageAnchor`); `block` is the 1-based position among the\n * message's top-level blocks. `hash` is an optional short fingerprint of the\n * block's normalized text (see `messageBlockHash`) so consumers can detect\n * that the block at that position no longer holds the linked content.\n *\n * URL params: `msg_id`, `block`, `hash`.\n */\nexport type MessageBlockAnchor = {\n  type: 'msg_block';\n  messageId: string;\n  block: number;\n  hash?: string;\n};\n/**\n * A heading-delimited section of a session message: the heading whose slug\n * (see `messageHeadingSlug`) equals `heading`, through the block before the\n * next heading of the same or a higher level. `nth` (1-based) disambiguates\n * repeated headings; absent ⇒ first.\n *\n * URL params: `msg_id`, `heading`, `nth`.\n */\nexport type MessageSectionAnchor = {\n  type: 'msg_section';\n  messageId: string;\n  heading: string;\n  nth?: number;\n};\n/**\n * An exact text span inside a session message. `text` is the quoted excerpt,\n * matched against the message's whitespace-normalized plain text (see\n * `normalizeMessageText`). Optional `block` narrows the search to one\n * top-level block (1-based); optional `prefix` / `suffix` are the normalized\n * text immediately before / after the span, used to pick between repeated\n * occurrences. Consumers fall back to the block, then the whole message, when\n * the span can't be found.\n *\n * URL params: `msg_id`, `text`, `block`, `prefix`, `suffix`.\n */\nexport type MessageTextAnchor = {\n  type: 'msg_text';\n  messageId: string;\n  text: string;\n  block?: number;\n  prefix?: string;\n  suffix?: string;\n};\nexport type PageAnchor = { type: 'page'; page: number };\n/**\n * A file path inside an asset, optionally narrowed to a 1-based source\n * location. `column` is only meaningful when `line` is present.\n */\nexport type PathAnchor = {\n  type: 'path';\n  path: string;\n  line?: number;\n  column?: number;\n};\nexport type PageRangeAnchor = {\n  type: 'page_range';\n  startPage: number;\n  endPage: number;\n};\n/** Coordinate unit for a `page_rect` anchor. Absent ⇒ `percent`. */\nexport const PageRectUnit = {\n  /** Percentages of the page dimensions (0-100). Resolution-independent. */\n  Percent: 'percent',\n  /**\n   * PDF points (1/72\"), the unit of the legacy `bbox_left/bbox_top/...`\n   * citation-URL params and of PDF viewer page coordinates.\n   */\n  Point: 'point',\n} as const;\n\nexport type PageRectUnit = (typeof PageRectUnit)[keyof typeof PageRectUnit];\n\n/**\n * Rectangular region on a specific page. `x`/`y`/`width`/`height` are in\n * `unit` coordinates — percentages of the page dimensions (0-100) when\n * `unit` is absent or `percent`, PDF points when `unit` is `point`.\n */\nexport type PageRectAnchor = {\n  type: 'page_rect';\n  page: number;\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n  unit?: PageRectUnit;\n};\n/**\n * A quoted text span on a specific page. `text` is the selected excerpt,\n * re-located by text search when the anchor is resolved. Optional `prefix` /\n * `suffix` are the normalized text immediately before / after the span, used\n * to pick between repeated occurrences of `text` on the page (the same\n * contract as `MessageTextAnchor`). Optional `hash` is a short fingerprint of\n * the cited unit's normalized text (the `MessageBlockAnchor` pattern:\n * `messageBlockHash`, 32-bit FNV-1a as 8 hex chars) so a consumer can tell a\n * stale citation from a live one and fall back to text search. The anchor\n * never stores geometry; rectangles are derived when it is resolved.\n *\n * URL params: `page`, `text`, `prefix`, `suffix`, `hash`.\n */\nexport type PageTextAnchor = {\n  type: 'page_text';\n  page: number;\n  text: string;\n  prefix?: string;\n  suffix?: string;\n  hash?: string;\n};\nexport type PmNodeAnchor = { type: 'pm_node'; nodeId: string };\nexport type PmNodeRangeAnchor = {\n  type: 'pm_node_range';\n  startNodeId: string;\n  endNodeId: string;\n};\n/** Pixel-based region anchor for images. Coordinates relative to natural image dimensions. */\nexport type PixelRangeAnchor = {\n  type: 'pixel_range';\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n};\n/** ProseMirror mark pointer; composite `markType:instanceId` (e.g. CommentsKit `thread` + thread id). */\nexport type PmMarkAnchor = { type: 'pm_mark'; markId: string };\n/** Percentage-based region (0-100). Resolution-independent. */\nexport type RectAnchor = {\n  type: 'rect';\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n};\n/**\n * Named slice of an asset's persisted metadata (e.g. a computer asset's `status` / `ports`\n * section), or a section of a recording's generated notes (`decisions`, `action_items`,\n * `open_questions`, `notes`). `topic` is the 1-based `### topic` under a recording's Notes\n * (`section=notes&topic=2`), as Clio's notes hits name it; absent for every other section.\n */\nexport type SectionAnchor = { type: 'section'; section: string; topic?: number };\n/**\n * How a cited value relates to a generative (query) anchor's result.\n *\n * Absent ⇒ consumers MUST treat it as `supporting`. The (de)serializer never\n * defaults it, so round-trips stay exact.\n */\nexport const QueryResultRelationship = {\n  /** The cell value IS (a cell of) the query result — a 1:1 extraction. */\n  Exact: 'exact',\n  /**\n   * The cell value is authored (e.g. a narrative claim); the query result is\n   * supporting evidence / justification, not the value itself. Re-running the\n   * query is read-only verification and never replaces the cell value.\n   */\n  Supporting: 'supporting',\n} as const;\n\nexport type QueryResultRelationship =\n  (typeof QueryResultRelationship)[keyof typeof QueryResultRelationship];\n\n/**\n * Generative anchor — a value derived from a semantic-model (Cube.js) query.\n *\n * Unlike positional anchors (page/cell/line), the \"location\" is the\n * transformation itself: the full Cube.js query spec that was run. Re-running\n * it is read-only verification; it never overwrites the cited value.\n */\nexport type SemanticQueryAnchor = {\n  type: 'semantic_query';\n  /** The full Cube.js query spec that produced the result (the codified transformation). */\n  query: Record<string, unknown>;\n  /** Cited measure/dimension id, e.g. `orders.total_revenue`. Omit ⇒ the whole result is the evidence. */\n  field?: string;\n  /** Dimension/key values identifying the cited row. Robust to re-ordering, unlike `rowIndex`. */\n  rowKey?: Record<string, string>;\n  /** Positional fallback row selector. */\n  rowIndex?: number;\n  /** Whether the cell value equals the result (`exact`) or is authored evidence (`supporting`). */\n  relationship?: QueryResultRelationship;\n  /** Provenance: semantic-model schema version at run time. */\n  schemaVersion?: number;\n  /** Provenance: sha256 of the deployed YAML at run time, for drift detection. */\n  schemaHash?: string;\n  /**\n   * Provenance for lakehouse-backed models: each source table's Iceberg identity\n   * and snapshot when the value was computed (`\"<namespace>.<table>\"` →\n   * `\"<table_uuid>:<snapshot_id>\"`, the snapshot empty for a table never written).\n   * Compared with the live tables by the freshness check.\n   */\n  sourceSnapshots?: Record<string, string>;\n  /** Provenance: the result's \"data as of\" instant (ISO-8601 UTC) at capture. */\n  dataAsOf?: string;\n};\n/**\n * One or more shapes on a presentation slide. `shapeIds` are stable Yjs\n * ElementIds (the SDK's `shape.shape_id`) and resolve the anchor on their\n * own; `slideId` / `slideIndex` (1-based) are optional refinements.\n */\nexport type ShapeAnchor = {\n  type: 'shape';\n  slideId?: string;\n  slideIndex?: number;\n  shapeIds: string[];\n};\n/**\n * A single cell. `chartId` (`chart=`) names the chart anchored at the cell\n * when the place is that chart, not the cell's value: a chart sits right of\n * and below its anchor cell, so a reader reveals it from that corner.\n */\nexport type SheetCellAnchor = {\n  type: 'sheet_cell';\n  sheetId: number;\n  cell: string;\n  chartId?: string;\n};\nexport type SheetRangeAnchor = {\n  type: 'sheet_range';\n  sheetId: number;\n  range: string;\n  /**\n   * The spreadsheet engine's shift-log frontier (writer id → seq, `RncEngine.shiftLogFrontier`) the\n   * moment `range` was taken, so a reader with the live engine can resolve the range to its current\n   * coordinates after rows/columns were inserted or deleted since (`RncEngine.transformRange`).\n   * Absent on an anchor taken without an engine, which resolves to `range` as stored.\n   */\n  frontier?: Record<string, number>;\n};\n/** A whole worksheet / sheet tab in a spreadsheet. */\nexport type SheetTabAnchor = {\n  type: 'sheet_tab';\n  sheetId: number;\n};\n/**\n * A named Excel table (ListObject) within a worksheet. Stable identity:\n * the table's name survives sorts, inserts, and row additions that would\n * break a raw `sheet_range`. Use this anchor in preference to\n * `sheet_range` whenever the user is binding to a structured table.\n *\n * `fallbackRange` is an optional A1-style range used by resolvers when\n * the table has been deleted or renamed — best-effort recovery.\n */\nexport type SheetTableAnchor = {\n  type: 'sheet_table';\n  sheetId: number;\n  tableName: string;\n  fallbackRange?: string;\n};\n/**\n * One table of an Orion lakehouse namespace, addressed on the namespace asset\n * (tables have no asset rows). `table` is the name within the namespace;\n * `tableUuid` is the Iceberg table UUID, the stable identity that detects a\n * drop-and-recreate or rename; `snapshotId` pins a read to one Iceberg\n * snapshot (an unsupported pinned read is rejected, never served from current\n * data).\n */\nexport type LakehouseTableAnchor = {\n  type: 'lakehouse_table';\n  table: string;\n  tableUuid?: string;\n  snapshotId?: string;\n};\n/**\n * A whole slide of a PPTX deck. `slideId` is the stable Yjs SlideId (the\n * SDK's `slide.slide_id`); `slideIndex` is the 1-based display position.\n * At least one must be present; producers should emit both when known.\n */\nexport type SlideAnchor = {\n  type: 'slide';\n  slideId?: string;\n  slideIndex?: number;\n};\n/**\n * Generative anchor — a value derived from a SQL query.\n *\n * The transformation is the SQL text, carried inline or (preferred) as a\n * governed, re-runnable `query_snippet` asset. Re-running it is read-only\n * verification; it never overwrites the cited value.\n */\nexport type SqlQueryAnchor = {\n  type: 'sql_query';\n  /** The SQL that produced the result. Optional when `querySnippetAssetId` is set. */\n  sql?: string;\n  /** A re-runnable `query_snippet` asset that holds the SQL (preferred over inline `sql`). */\n  querySnippetAssetId?: string;\n  /** SQL dialect, e.g. `postgres`, `snowflake`. */\n  dialect?: string;\n  /** Cited result column name. Omit ⇒ the whole result is the evidence. */\n  field?: string;\n  /** Identifying column values for the cited row. Robust to re-ordering, unlike `rowIndex`. */\n  rowKey?: Record<string, string>;\n  /** Positional fallback row selector. */\n  rowIndex?: number;\n  /** Whether the cell value equals the result (`exact`) or is authored evidence (`supporting`). */\n  relationship?: QueryResultRelationship;\n};\n/** Time string in \"H:MM:SS\" / \"MM:SS\" / \"M:SS\" format. No plain seconds. */\nexport type TimeAnchor = { type: 'time'; time: string };\nexport type TimeRangeAnchor = {\n  type: 'time_range';\n  startTime: string;\n  endTime: string;\n};\n/**\n * A tool invocation in a session transcript. `toolCallId` is the\n * LangChain-native tool call id (the key used by session Y.Doc\n * liveToolCalls), NOT an Athena message tracking id. `messageId` is the\n * tracking id of the assistant message that issued the call, when the\n * producer knows it (Keryx activity carries both as `tool_call_id` and\n * `ai_message_tracking_id`); it lets a consumer still land on the owning\n * message when the call itself is not in view (e.g. an abandoned branch).\n */\nexport type ToolCallAnchor = { type: 'tool_call'; toolCallId: string; messageId?: string };\n\n// ---------------------------------------------------------------------------\n// Union\n// ---------------------------------------------------------------------------\n\nexport type Anchor =\n  | CellAnchor\n  | CellRangeAnchor\n  | CommentAnchor\n  | CommentThreadAnchor\n  | FileLineRangeAnchor\n  | LineAnchor\n  | LineRangeAnchor\n  | MessageAnchor\n  | MessageRangeAnchor\n  | MessageBlockAnchor\n  | MessageSectionAnchor\n  | MessageTextAnchor\n  | PageAnchor\n  | PageRangeAnchor\n  | PathAnchor\n  | PageRectAnchor\n  | PageTextAnchor\n  | PixelRangeAnchor\n  | PmNodeAnchor\n  | PmNodeRangeAnchor\n  | PmMarkAnchor\n  | RectAnchor\n  | SectionAnchor\n  | SemanticQueryAnchor\n  | ShapeAnchor\n  | SheetCellAnchor\n  | SheetRangeAnchor\n  | SheetTabAnchor\n  | SheetTableAnchor\n  | LakehouseTableAnchor\n  | SlideAnchor\n  | SqlQueryAnchor\n  | TimeAnchor\n  | TimeRangeAnchor\n  | ToolCallAnchor;\n\n// ---------------------------------------------------------------------------\n// AnchorType — string literal union of all `type` discriminators\n// ---------------------------------------------------------------------------\n\nexport type AnchorType = Anchor['type'];\n\nexport const AnchorType = {\n  Cell: 'cell',\n  CellRange: 'cell_range',\n  Comment: 'comment',\n  CommentThread: 'comment_thread',\n  FileLineRange: 'file_line_range',\n  Line: 'line',\n  LineRange: 'line_range',\n  Message: 'msg',\n  MessageRange: 'msg_range',\n  MessageBlock: 'msg_block',\n  MessageSection: 'msg_section',\n  MessageText: 'msg_text',\n  Page: 'page',\n  PageRange: 'page_range',\n  Path: 'path',\n  PageRect: 'page_rect',\n  PageText: 'page_text',\n  PixelRange: 'pixel_range',\n  PmMark: 'pm_mark',\n  PmNode: 'pm_node',\n  PmNodeRange: 'pm_node_range',\n  Rect: 'rect',\n  Section: 'section',\n  SemanticQuery: 'semantic_query',\n  Shape: 'shape',\n  SheetCell: 'sheet_cell',\n  SheetRange: 'sheet_range',\n  SheetTab: 'sheet_tab',\n  SheetTable: 'sheet_table',\n  LakehouseTable: 'lakehouse_table',\n  Slide: 'slide',\n  SqlQuery: 'sql_query',\n  Time: 'time',\n  TimeRange: 'time_range',\n  ToolCall: 'tool_call',\n} as const satisfies Record<string, AnchorType>;\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\n/**\n * Pre-rename session anchor spellings that are still accepted on input so\n * links shared before the `msg*` rename keep resolving. Output always uses\n * the current names (see `serialize.ts`).\n */\nexport const LEGACY_ANCHOR_TYPES: Readonly<Record<string, AnchorType>> = {\n  message: 'msg',\n  message_range: 'msg_range',\n};\n\nexport function isAnchorType(value: unknown): value is AnchorType {\n  return typeof value === 'string' && Object.values(AnchorType).includes(value as AnchorType);\n}\n\n/**\n * Quick check: validates only the `type` discriminator string.\n * For full structural validation, use `parseAnchor` from `./schemas`.\n */\nexport function isAnchor(value: unknown): value is Anchor {\n  if (typeof value !== 'object' || value === null) return false;\n  return isAnchorType((value as Record<string, unknown>).type);\n}\n\n// ---------------------------------------------------------------------------\n// Runtime-only types (not stored, produced by accessors)\n// ---------------------------------------------------------------------------\n\n/** Runtime form of TimeAnchor with pre-computed seconds. */\nexport type TimeAnchorSeconds = { type: 'time_seconds'; timeSeconds: number };\n/** Runtime form of TimeRangeAnchor with pre-computed seconds. */\nexport type TimeRangeAnchorSeconds = {\n  type: 'time_range_seconds';\n  startTimeSeconds: number;\n  endTimeSeconds: number;\n};\n"],"names":[],"mappings":"AAsbO,MAAM,aAAa;AAAA,EACxB,MAAM;AAAA,EACN,WAAW;AAAA,EACX,SAAS;AAAA,EACT,eAAe;AAAA,EACf,eAAe;AAAA,EACf,MAAM;AAAA,EACN,WAAW;AAAA,EACX,SAAS;AAAA,EACT,cAAc;AAAA,EACd,cAAc;AAAA,EACd,gBAAgB;AAAA,EAChB,aAAa;AAAA,EACb,MAAM;AAAA,EACN,WAAW;AAAA,EACX,MAAM;AAAA,EACN,UAAU;AAAA,EACV,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,aAAa;AAAA,EACb,MAAM;AAAA,EACN,SAAS;AAAA,EACT,eAAe;AAAA,EACf,OAAO;AAAA,EACP,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,gBAAgB;AAAA,EAChB,OAAO;AAAA,EACP,UAAU;AAAA,EACV,MAAM;AAAA,EACN,WAAW;AAAA,EACX,UAAU;AACZ;AAWO,MAAM,sBAA4D;AAAA,EACvE,SAAS;AAAA,EACT,eAAe;AACjB;AAEO,SAAS,aAAa,OAAqC;AAChE,SAAO,OAAO,UAAU,YAAY,OAAO,OAAO,UAAU,EAAE,SAAS,KAAmB;AAC5F;"}
+{"version":3,"file":"types.js","sources":["../../../../../references/src/anchors/types.ts"],"sourcesContent":["/**\n * Anchor types — Level 2 of the reference system.\n *\n * Each anchor describes a specific location within an asset.\n * Discriminated union on `type`. Ordered alphabetically.\n *\n * Property names use camelCase; the `type` discriminator string stays snake_case\n * (it's a version identifier, not a property name).\n */\n\n// ---------------------------------------------------------------------------\n// Individual anchor types (alphabetical by `type` discriminator)\n// ---------------------------------------------------------------------------\n\nexport type CellAnchor = { type: 'cell'; cellId: string };\nexport type CellRangeAnchor = {\n  type: 'cell_range';\n  startCellId: string;\n  endCellId: string;\n};\nexport type CommentAnchor = {\n  type: 'comment';\n  threadId: string;\n  commentId: string;\n};\nexport type CommentThreadAnchor = { type: 'comment_thread'; threadId: string };\n/**\n * An inclusive, 1-based line range of one file of a repository source — a\n * GitHub `catalog` asset whose files Clio indexes\n * (`docs/clio/21-repository-source.md`). `path` is the repo-relative,\n * `/`-separated file path: structure, not content. Distinct from the\n * path-less `line_range` so a reader that does not know the kind fails closed\n * instead of dropping the file. Bounds, path grammar and the byte cap are\n * shared with Clio's `LineRangeLocator` (`./file-line-range.ts`).\n *\n * Wire form (canonical — parameters sorted, as Clio writes it):\n * `anchor=file_line_range&end_line=<m>&path=<path>&start_line=<n>`.\n */\nexport type FileLineRangeAnchor = {\n  type: 'file_line_range';\n  path: string;\n  startLine: number;\n  endLine: number;\n};\nexport type LineAnchor = { type: 'line'; line: number };\nexport type LineRangeAnchor = {\n  type: 'line_range';\n  startLine: number;\n  endLine: number;\n};\n/**\n * A single chat message in a session transcript.\n *\n * `messageId` is the **Athena message tracking id** — the same uuid4 that\n * appears as `user_message_tracking_id` / `ai_message_tracking_id` in Keryx\n * activity attributions (built by `build_agent_attributions`,\n * agora/services/keryx/client.py), as `trackingId` on session Y.Doc\n * liveMessages, as the `data-message-tracking-id` DOM attribute, and as the\n * existing `scroll_to_message` URL param in Olympus. It is NOT the LangChain\n * checkpoint `message.id`.\n *\n * Wire form: `anchor=msg&msg_id=…` (the pre-rename spellings\n * `anchor=message&message_id=…` are still parsed).\n */\nexport type MessageAnchor = { type: 'msg'; messageId: string };\n/**\n * Inclusive span of session messages in transcript order. Both ids are\n * Athena message tracking ids (see `MessageAnchor`).\n */\nexport type MessageRangeAnchor = {\n  type: 'msg_range';\n  startMessageId: string;\n  endMessageId: string;\n};\n/**\n * One top-level block (paragraph, heading, list, table, code fence, …) of a\n * session message's markdown body. `messageId` is the Athena message tracking\n * id (see `MessageAnchor`); `block` is the 1-based position among the\n * message's top-level blocks. `hash` is an optional short fingerprint of the\n * block's normalized text (see `messageBlockHash`) so consumers can detect\n * that the block at that position no longer holds the linked content.\n *\n * URL params: `msg_id`, `block`, `hash`.\n */\nexport type MessageBlockAnchor = {\n  type: 'msg_block';\n  messageId: string;\n  block: number;\n  hash?: string;\n};\n/**\n * A heading-delimited section of a session message: the heading whose slug\n * (see `messageHeadingSlug`) equals `heading`, through the block before the\n * next heading of the same or a higher level. `nth` (1-based) disambiguates\n * repeated headings; absent ⇒ first.\n *\n * URL params: `msg_id`, `heading`, `nth`.\n */\nexport type MessageSectionAnchor = {\n  type: 'msg_section';\n  messageId: string;\n  heading: string;\n  nth?: number;\n};\n/**\n * An exact text span inside a session message. `text` is the quoted excerpt,\n * matched against the message's whitespace-normalized plain text (see\n * `normalizeMessageText`). Optional `block` narrows the search to one\n * top-level block (1-based); optional `prefix` / `suffix` are the normalized\n * text immediately before / after the span, used to pick between repeated\n * occurrences. Consumers fall back to the block, then the whole message, when\n * the span can't be found.\n *\n * URL params: `msg_id`, `text`, `block`, `prefix`, `suffix`.\n */\nexport type MessageTextAnchor = {\n  type: 'msg_text';\n  messageId: string;\n  text: string;\n  block?: number;\n  prefix?: string;\n  suffix?: string;\n};\nexport type PageAnchor = { type: 'page'; page: number };\n/**\n * A file path inside an asset, optionally narrowed to a 1-based source\n * location. `column` is only meaningful when `line` is present.\n */\nexport type PathAnchor = {\n  type: 'path';\n  path: string;\n  line?: number;\n  column?: number;\n};\nexport type PageRangeAnchor = {\n  type: 'page_range';\n  startPage: number;\n  endPage: number;\n};\n/** Coordinate unit for a `page_rect` anchor. Absent ⇒ `percent`. */\nexport const PageRectUnit = {\n  /** Percentages of the page dimensions (0-100). Resolution-independent. */\n  Percent: 'percent',\n  /**\n   * PDF points (1/72\"), the unit of the legacy `bbox_left/bbox_top/...`\n   * citation-URL params and of PDF viewer page coordinates.\n   */\n  Point: 'point',\n} as const;\n\nexport type PageRectUnit = (typeof PageRectUnit)[keyof typeof PageRectUnit];\n\n/**\n * Rectangular region on a specific page. `x`/`y`/`width`/`height` are in\n * `unit` coordinates — percentages of the page dimensions (0-100) when\n * `unit` is absent or `percent`, PDF points when `unit` is `point`.\n */\nexport type PageRectAnchor = {\n  type: 'page_rect';\n  page: number;\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n  unit?: PageRectUnit;\n};\n/**\n * A quoted text span on a specific page. `text` is the selected excerpt,\n * re-located by text search when the anchor is resolved. Optional `prefix` /\n * `suffix` are the normalized text immediately before / after the span, used\n * to pick between repeated occurrences of `text` on the page (the same\n * contract as `MessageTextAnchor`). Optional `hash` is a short fingerprint of\n * the cited unit's normalized text (the `MessageBlockAnchor` pattern:\n * `messageBlockHash`, 32-bit FNV-1a as 8 hex chars) so a consumer can tell a\n * stale citation from a live one and fall back to text search. The anchor\n * never stores geometry; rectangles are derived when it is resolved.\n *\n * URL params: `page`, `text`, `prefix`, `suffix`, `hash`.\n */\nexport type PageTextAnchor = {\n  type: 'page_text';\n  page: number;\n  text: string;\n  prefix?: string;\n  suffix?: string;\n  hash?: string;\n};\nexport type PmNodeAnchor = { type: 'pm_node'; nodeId: string };\nexport type PmNodeRangeAnchor = {\n  type: 'pm_node_range';\n  startNodeId: string;\n  endNodeId: string;\n};\n/** Pixel-based region anchor for images. Coordinates relative to natural image dimensions. */\nexport type PixelRangeAnchor = {\n  type: 'pixel_range';\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n};\n/** ProseMirror mark pointer; composite `markType:instanceId` (e.g. CommentsKit `thread` + thread id). */\nexport type PmMarkAnchor = { type: 'pm_mark'; markId: string };\n/** Percentage-based region (0-100). Resolution-independent. */\nexport type RectAnchor = {\n  type: 'rect';\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n};\n/**\n * Named slice of an asset's persisted metadata (e.g. a computer asset's `status` / `ports`\n * section), or a section of a recording's generated notes (`decisions`, `action_items`,\n * `open_questions`, `notes`). `topic` is the 1-based `### topic` under a recording's Notes\n * (`section=notes&topic=2`), as Clio's notes hits name it; absent for every other section.\n */\nexport type SectionAnchor = { type: 'section'; section: string; topic?: number };\n/**\n * How a cited value relates to a generative (query) anchor's result.\n *\n * Absent ⇒ consumers MUST treat it as `supporting`. The (de)serializer never\n * defaults it, so round-trips stay exact.\n */\nexport const QueryResultRelationship = {\n  /** The cell value IS (a cell of) the query result — a 1:1 extraction. */\n  Exact: 'exact',\n  /**\n   * The cell value is authored (e.g. a narrative claim); the query result is\n   * supporting evidence / justification, not the value itself. Re-running the\n   * query is read-only verification and never replaces the cell value.\n   */\n  Supporting: 'supporting',\n} as const;\n\nexport type QueryResultRelationship =\n  (typeof QueryResultRelationship)[keyof typeof QueryResultRelationship];\n\n/**\n * Generative anchor — a value derived from a semantic-model (Cube.js) query.\n *\n * Unlike positional anchors (page/cell/line), the \"location\" is the\n * transformation itself: the full Cube.js query spec that was run. Re-running\n * it is read-only verification; it never overwrites the cited value.\n */\nexport type SemanticQueryAnchor = {\n  type: 'semantic_query';\n  /** The full Cube.js query spec that produced the result (the codified transformation). */\n  query: Record<string, unknown>;\n  /** Cited measure/dimension id, e.g. `orders.total_revenue`. Omit ⇒ the whole result is the evidence. */\n  field?: string;\n  /** Dimension/key values identifying the cited row. Robust to re-ordering, unlike `rowIndex`. */\n  rowKey?: Record<string, string>;\n  /** Positional fallback row selector. */\n  rowIndex?: number;\n  /** Whether the cell value equals the result (`exact`) or is authored evidence (`supporting`). */\n  relationship?: QueryResultRelationship;\n  /** Provenance: semantic-model schema version at run time. */\n  schemaVersion?: number;\n  /** Provenance: sha256 of the deployed YAML at run time, for drift detection. */\n  schemaHash?: string;\n  /**\n   * Provenance for lakehouse-backed models: each source table's Iceberg identity\n   * and snapshot when the value was computed (`\"<namespace>.<table>\"` →\n   * `\"<table_uuid>:<snapshot_id>\"`, the snapshot empty for a table never written).\n   * Compared with the live tables by the freshness check.\n   */\n  sourceSnapshots?: Record<string, string>;\n  /** Provenance: the result's \"data as of\" instant (ISO-8601 UTC) at capture. */\n  dataAsOf?: string;\n};\n/**\n * One or more shapes on a presentation slide. `shapeIds` are stable Yjs\n * ElementIds (the SDK's `shape.shape_id`) and resolve the anchor on their\n * own; `slideId` / `slideIndex` (1-based) are optional refinements.\n */\nexport type ShapeAnchor = {\n  type: 'shape';\n  slideId?: string;\n  slideIndex?: number;\n  shapeIds: string[];\n};\n/**\n * A single cell. `chartId` (`chart=`) names the chart anchored at the cell\n * when the place is that chart, not the cell's value: a chart sits right of\n * and below its anchor cell, so a reader reveals it from that corner.\n */\nexport type SheetCellAnchor = {\n  type: 'sheet_cell';\n  sheetId: number;\n  cell: string;\n  chartId?: string;\n};\nexport type SheetRangeAnchor = {\n  type: 'sheet_range';\n  sheetId: number;\n  range: string;\n  /**\n   * The spreadsheet engine's shift-log frontier (writer id → seq, `RncEngine.shiftLogFrontier`) the\n   * moment `range` was taken, so a reader with the live engine can resolve the range to its current\n   * coordinates after rows/columns were inserted or deleted since (`RncEngine.transformRange`).\n   * Absent on an anchor taken without an engine, which resolves to `range` as stored.\n   */\n  frontier?: Record<string, number>;\n};\n/** A whole worksheet / sheet tab in a spreadsheet. */\nexport type SheetTabAnchor = {\n  type: 'sheet_tab';\n  sheetId: number;\n};\n/**\n * A named Excel table (ListObject) within a worksheet. Stable identity:\n * the table's name survives sorts, inserts, and row additions that would\n * break a raw `sheet_range`. Use this anchor in preference to\n * `sheet_range` whenever the user is binding to a structured table.\n *\n * `fallbackRange` is an optional A1-style range used by resolvers when\n * the table has been deleted or renamed — best-effort recovery.\n */\nexport type SheetTableAnchor = {\n  type: 'sheet_table';\n  sheetId: number;\n  tableName: string;\n  fallbackRange?: string;\n};\n/**\n * One table of an Orion lakehouse namespace, addressed on the namespace asset\n * (tables have no asset rows). `table` is the name within the namespace;\n * `tableUuid` is the Iceberg table UUID, the stable identity that detects a\n * drop-and-recreate or rename; `snapshotId` pins a read to one Iceberg\n * snapshot (an unsupported pinned read is rejected, never served from current\n * data).\n */\nexport type LakehouseTableAnchor = {\n  type: 'lakehouse_table';\n  table: string;\n  tableUuid?: string;\n  snapshotId?: string;\n};\n/**\n * A whole slide of a PPTX deck. `slideId` is the stable Yjs SlideId (the\n * SDK's `slide.slide_id`); `slideIndex` is the 1-based display position.\n * At least one must be present; producers should emit both when known.\n */\nexport type SlideAnchor = {\n  type: 'slide';\n  slideId?: string;\n  slideIndex?: number;\n};\n/**\n * Generative anchor — a value derived from a SQL query.\n *\n * The transformation is the SQL text, carried inline or (preferred) as a\n * governed, re-runnable `query_snippet` asset. Re-running it is read-only\n * verification; it never overwrites the cited value.\n */\nexport type SqlQueryAnchor = {\n  type: 'sql_query';\n  /** The SQL that produced the result. Optional when `querySnippetAssetId` is set. */\n  sql?: string;\n  /** A re-runnable `query_snippet` asset that holds the SQL (preferred over inline `sql`). */\n  querySnippetAssetId?: string;\n  /** SQL dialect, e.g. `postgres`, `snowflake`. */\n  dialect?: string;\n  /** Cited result column name. Omit ⇒ the whole result is the evidence. */\n  field?: string;\n  /** Identifying column values for the cited row. Robust to re-ordering, unlike `rowIndex`. */\n  rowKey?: Record<string, string>;\n  /** Positional fallback row selector. */\n  rowIndex?: number;\n  /** Whether the cell value equals the result (`exact`) or is authored evidence (`supporting`). */\n  relationship?: QueryResultRelationship;\n};\n/** Time string in \"H:MM:SS\" / \"MM:SS\" / \"M:SS\" format. No plain seconds. */\nexport type TimeAnchor = { type: 'time'; time: string };\nexport type TimeRangeAnchor = {\n  type: 'time_range';\n  startTime: string;\n  endTime: string;\n};\n/**\n * A tool invocation in a session transcript. `toolCallId` is the\n * LangChain-native tool call id (the key used by session Y.Doc\n * liveToolCalls), NOT an Athena message tracking id. `messageId` is the\n * tracking id of the assistant message that issued the call, when the\n * producer knows it (Keryx activity carries both as `tool_call_id` and\n * `ai_message_tracking_id`); it lets a consumer still land on the owning\n * message when the call itself is not in view (e.g. an abandoned branch).\n */\nexport type ToolCallAnchor = { type: 'tool_call'; toolCallId: string; messageId?: string };\n\n// ---------------------------------------------------------------------------\n// Union\n// ---------------------------------------------------------------------------\n\nexport type Anchor =\n  | CellAnchor\n  | CellRangeAnchor\n  | CommentAnchor\n  | CommentThreadAnchor\n  | FileLineRangeAnchor\n  | LineAnchor\n  | LineRangeAnchor\n  | MessageAnchor\n  | MessageRangeAnchor\n  | MessageBlockAnchor\n  | MessageSectionAnchor\n  | MessageTextAnchor\n  | PageAnchor\n  | PageRangeAnchor\n  | PathAnchor\n  | PageRectAnchor\n  | PageTextAnchor\n  | PixelRangeAnchor\n  | PmNodeAnchor\n  | PmNodeRangeAnchor\n  | PmMarkAnchor\n  | RectAnchor\n  | SectionAnchor\n  | SemanticQueryAnchor\n  | ShapeAnchor\n  | SheetCellAnchor\n  | SheetRangeAnchor\n  | SheetTabAnchor\n  | SheetTableAnchor\n  | LakehouseTableAnchor\n  | SlideAnchor\n  | SqlQueryAnchor\n  | TimeAnchor\n  | TimeRangeAnchor\n  | ToolCallAnchor;\n\n// ---------------------------------------------------------------------------\n// AnchorType — string literal union of all `type` discriminators\n// ---------------------------------------------------------------------------\n\nexport type AnchorType = Anchor['type'];\n\nexport const AnchorType = {\n  Cell: 'cell',\n  CellRange: 'cell_range',\n  Comment: 'comment',\n  CommentThread: 'comment_thread',\n  FileLineRange: 'file_line_range',\n  Line: 'line',\n  LineRange: 'line_range',\n  Message: 'msg',\n  MessageRange: 'msg_range',\n  MessageBlock: 'msg_block',\n  MessageSection: 'msg_section',\n  MessageText: 'msg_text',\n  Page: 'page',\n  PageRange: 'page_range',\n  Path: 'path',\n  PageRect: 'page_rect',\n  PageText: 'page_text',\n  PixelRange: 'pixel_range',\n  PmMark: 'pm_mark',\n  PmNode: 'pm_node',\n  PmNodeRange: 'pm_node_range',\n  Rect: 'rect',\n  Section: 'section',\n  SemanticQuery: 'semantic_query',\n  Shape: 'shape',\n  SheetCell: 'sheet_cell',\n  SheetRange: 'sheet_range',\n  SheetTab: 'sheet_tab',\n  SheetTable: 'sheet_table',\n  LakehouseTable: 'lakehouse_table',\n  Slide: 'slide',\n  SqlQuery: 'sql_query',\n  Time: 'time',\n  TimeRange: 'time_range',\n  ToolCall: 'tool_call',\n} as const satisfies Record<string, AnchorType>;\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\n/**\n * Pre-rename session anchor spellings that are still accepted on input so\n * links shared before the `msg*` rename keep resolving. Output always uses\n * the current names (see `serialize.ts`).\n */\nexport const LEGACY_ANCHOR_TYPES: Readonly<Record<string, AnchorType>> = {\n  message: 'msg',\n  message_range: 'msg_range',\n};\n\nexport function isAnchorType(value: unknown): value is AnchorType {\n  return typeof value === 'string' && Object.values(AnchorType).includes(value as AnchorType);\n}\n\n/**\n * Quick check: validates only the `type` discriminator string.\n * For full structural validation, use `parseAnchor` from `./schemas`.\n */\nexport function isAnchor(value: unknown): value is Anchor {\n  if (typeof value !== 'object' || value === null) return false;\n  return isAnchorType((value as Record<string, unknown>).type);\n}\n\n// ---------------------------------------------------------------------------\n// Runtime-only types (not stored, produced by accessors)\n// ---------------------------------------------------------------------------\n\n/** Runtime form of TimeAnchor with pre-computed seconds. */\nexport type TimeAnchorSeconds = { type: 'time_seconds'; timeSeconds: number };\n/** Runtime form of TimeRangeAnchor with pre-computed seconds. */\nexport type TimeRangeAnchorSeconds = {\n  type: 'time_range_seconds';\n  startTimeSeconds: number;\n  endTimeSeconds: number;\n};\n"],"names":[],"mappings":"AAsbO,MAAM,aAAa;AAAA,EACxB,MAAM;AAAA,EACN,WAAW;AAAA,EACX,SAAS;AAAA,EACT,eAAe;AAAA,EACf,eAAe;AAAA,EACf,MAAM;AAAA,EACN,WAAW;AAAA,EACX,SAAS;AAAA,EACT,cAAc;AAAA,EACd,cAAc;AAAA,EACd,gBAAgB;AAAA,EAChB,aAAa;AAAA,EACb,MAAM;AAAA,EACN,WAAW;AAAA,EACX,MAAM;AAAA,EACN,UAAU;AAAA,EACV,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,aAAa;AAAA,EACb,MAAM;AAAA,EACN,SAAS;AAAA,EACT,eAAe;AAAA,EACf,OAAO;AAAA,EACP,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,gBAAgB;AAAA,EAChB,OAAO;AAAA,EACP,UAAU;AAAA,EACV,MAAM;AAAA,EACN,WAAW;AAAA,EACX,UAAU;AACZ;AAWO,MAAM,sBAA4D;AAAA,EACvE,SAAS;AAAA,EACT,eAAe;AACjB;AAEO,SAAS,aAAa,OAAqC;AAChE,SAAO,OAAO,UAAU,YAAY,OAAO,OAAO,UAAU,EAAE,SAAS,KAAmB;AAC5F;AAMO,SAAS,SAAS,OAAiC;AACxD,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,SAAO,aAAc,MAAkC,IAAI;AAC7D;"}

package/dist/references/src/attachable.cjs

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const parse = require("./anchors/parse.cjs");
+const serialize = require("./anchors/serialize.cjs");
+const types = require("./anchors/types.cjs");
+const ATTACHED_REFERENCES_METADATA_KEY = "attachedReferences";
+const MAX_ATTACHED_REFERENCES = 10;
+const MAX_ATTACHED_REFERENCE_LABEL_CHARS = 200;
+const MAX_ATTACHED_URL_CHARS = 2048;
+const ASSET_ID = /^asset_[A-Za-z0-9_-]{1,200}$/;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function displayText(value, limit) {
+  if (typeof value !== "string") return void 0;
+  const oneLine = value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  if (!oneLine) return void 0;
+  return oneLine.length > limit ? `${oneLine.slice(0, limit - 1).trimEnd()}…` : oneLine;
+}
+function assetId(value) {
+  return typeof value === "string" && ASSET_ID.test(value) ? value : null;
+}
+function canonicalAnchor(value) {
+  if (!types.isAnchor(value)) return null;
+  try {
+    const params = serialize.serializeAnchorToParams(value);
+    for (const param of params.values()) {
+      if (param === "undefined" || param === "NaN" || param === "null") return null;
+    }
+    return parse.parseAnchorFromParams(params) ?? null;
+  } catch {
+    return null;
+  }
+}
+const NON_URL_CHARACTERS = /[^A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=%]/g;
+function webUrl(value) {
+  if (typeof value !== "string" || value.length > MAX_ATTACHED_URL_CHARS) return null;
+  let parsed;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  if (!parsed.hostname || parsed.username || parsed.password) return null;
+  const href = parsed.href.replace(NON_URL_CHARACTERS, (character) => encodeURIComponent(character));
+  return href.length > MAX_ATTACHED_URL_CHARS ? null : href;
+}
+function normalizeAttachableReference(value) {
+  if (!isRecord(value)) return null;
+  const meta = isRecord(value.meta) ? value.meta : {};
+  const title = displayText(meta.title, MAX_ATTACHED_REFERENCE_LABEL_CHARS);
+  switch (value.referenced) {
+    case "asset": {
+      const id = assetId(value.id);
+      if (id === null) return null;
+      const reference = { referenced: "asset", id };
+      if (value.anchor !== void 0 && value.anchor !== null) {
+        const anchor = canonicalAnchor(value.anchor);
+        if (anchor === null) return null;
+        reference.anchor = anchor;
+      }
+      const assetType = displayText(meta.assetType, 100);
+      if (title !== void 0 || assetType !== void 0) {
+        reference.meta = {
+          ...title !== void 0 && { title },
+          ...assetType !== void 0 && { assetType }
+        };
+      }
+      return reference;
+    }
+    case "ontology_object": {
+      const id = assetId(value.id);
+      if (id === null) return null;
+      const reference = { referenced: "ontology_object", id };
+      const objectType = displayText(meta.objectType, 100);
+      if (title !== void 0 || objectType !== void 0) {
+        reference.meta = {
+          ...title !== void 0 && { title },
+          ...objectType !== void 0 && { objectType }
+        };
+      }
+      return reference;
+    }
+    case "external_url": {
+      const url = webUrl(value.url);
+      if (url === null) return null;
+      const reference = { referenced: "external_url", url };
+      if (title !== void 0) reference.meta = { title };
+      return reference;
+    }
+    default:
+      return null;
+  }
+}
+function attachableReferenceKey(reference) {
+  switch (reference.referenced) {
+    case "asset":
+      return reference.anchor ? `asset:${reference.id}?${serialize.serializeAnchorToParams(reference.anchor).toString()}` : `asset:${reference.id}`;
+    case "ontology_object":
+      return `ontology_object:${reference.id}`;
+    case "external_url":
+      return `external_url:${reference.url}`;
+  }
+}
+function attachableReferenceLabel(reference) {
+  var _a;
+  const title = (_a = reference.meta) == null ? void 0 : _a.title;
+  if (title) return title;
+  if (reference.referenced !== "external_url") return reference.id;
+  try {
+    const url = new URL(reference.url);
+    const path = url.pathname === "/" ? "" : url.pathname;
+    return `${url.hostname}${path}`;
+  } catch {
+    return reference.url;
+  }
+}
+function readAttachedReferences(metadata) {
+  if (!isRecord(metadata)) return [];
+  const raw = metadata[ATTACHED_REFERENCES_METADATA_KEY];
+  if (!Array.isArray(raw)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const references = [];
+  for (const entry of raw) {
+    if (references.length >= MAX_ATTACHED_REFERENCES) break;
+    const reference = normalizeAttachableReference(entry);
+    if (reference === null) continue;
+    const key = attachableReferenceKey(reference);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    references.push(reference);
+  }
+  return references;
+}
+function withAttachedReferences(metadata, references) {
+  if (references.length === 0) return metadata === void 0 ? void 0 : { ...metadata };
+  return { ...metadata, [ATTACHED_REFERENCES_METADATA_KEY]: references.map((reference) => ({ ...reference })) };
+}
+exports.ATTACHED_REFERENCES_METADATA_KEY = ATTACHED_REFERENCES_METADATA_KEY;
+exports.MAX_ATTACHED_REFERENCES = MAX_ATTACHED_REFERENCES;
+exports.MAX_ATTACHED_REFERENCE_LABEL_CHARS = MAX_ATTACHED_REFERENCE_LABEL_CHARS;
+exports.MAX_ATTACHED_URL_CHARS = MAX_ATTACHED_URL_CHARS;
+exports.attachableReferenceKey = attachableReferenceKey;
+exports.attachableReferenceLabel = attachableReferenceLabel;
+exports.normalizeAttachableReference = normalizeAttachableReference;
+exports.readAttachedReferences = readAttachedReferences;
+exports.withAttachedReferences = withAttachedReferences;
+//# sourceMappingURL=attachable.cjs.map

package/dist/references/src/attachable.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachable.cjs","sources":["../../../../references/src/attachable.ts"],"sourcesContent":["/**\n * `@athenaintel/references/attachable` — what an app can attach to a chat message.\n *\n * An app hands the agent the object on screen (\"Discuss this with the agent\"): the person's next\n * message carries a list of references as structured data, in its own metadata\n * (`message.metadata.attachedReferences`), never as text. agora tells the agent what was attached\n * (kind, id, label) and the agent resolves each one on the server, through the canonical gates and\n * with the viewer's own permission; something the viewer can't open reaches the agent as a refusal,\n * never as content (`agora/agora/graphs/athena_deep_agent/attached_references.py`).\n *\n * Every kind is a member of the reference standard's family, discriminated by `referenced`:\n *\n * - `asset`: the standard's {@link AssetReference}, optionally with an `anchor` (its L2: a page,\n *   a cell range, a node, …), without a pinned `version`;\n * - `ontology_object`: an ontology object, named by its `asset_<uuid>` id: a v1 object (an\n *   `ontology_object` asset) or a Platform 2.0 object row;\n * - `external_url`: the standard's {@link ExternalUrlReference}.\n *\n * TODO(#54759): `table_row` (a row of a lakehouse or Kronos table, by key) waits for a\n * permission-checked row reader on the server; until it exists an app cannot attach one.\n *\n * `meta` is display only (the standard's L3): the label a chip shows, which the server never\n * trusts as content. The same rules hold on both sides; agora's copy is\n * `attached_references.py`, and `agora/tests/unit/deep_agent/test_attached_references.py` holds\n * the two to the same key and cap.\n *\n * The `@athenaintel/react` SDK bundles this entry, so it stays free of `zod`: `attachable.test.ts`\n * walks its import graph.\n */\n\nimport { parseAnchorFromParams } from './anchors/parse';\nimport { serializeAnchorToParams } from './anchors/serialize';\nimport type { Anchor } from './anchors/types';\nimport { isAnchor } from './anchors/types';\nimport type { AssetMeta, AssetReference, ExternalUrlMeta, ExternalUrlReference } from './types';\n\n/** The message metadata key a message's attached references ride under. */\nexport const ATTACHED_REFERENCES_METADATA_KEY = 'attachedReferences';\n\n/** The most references one message may carry (agora's `MAX_ATTACHED_REFERENCES`). */\nexport const MAX_ATTACHED_REFERENCES = 10;\n\n/** The longest label (`meta.title`) a reference keeps; a longer one is cut. */\nexport const MAX_ATTACHED_REFERENCE_LABEL_CHARS = 200;\n\n/** The longest URL an `external_url` reference may name. */\nexport const MAX_ATTACHED_URL_CHARS = 2048;\n\n/** An asset (or a Platform 2.0 object) id: `asset_` and up to 200 id characters, nothing else. */\nconst ASSET_ID = /^asset_[A-Za-z0-9_-]{1,200}$/;\n\n/** Display metadata of an ontology object: its title and the name of its type. */\nexport type OntologyObjectMeta = {\n  title?: string;\n  objectType?: string;\n};\n\n/**\n * An ontology object: a v1 object (an `ontology_object` asset) or a Platform 2.0 object row, both\n * named by their `asset_<uuid>` id. agora decides which it is and gates it accordingly.\n */\nexport type OntologyObjectReference = {\n  referenced: 'ontology_object';\n  id: string;\n  meta?: OntologyObjectMeta;\n};\n\n/** An asset, optionally narrowed to a place inside it (`anchor`). */\nexport type AttachableAssetReference = Pick<AssetReference, 'referenced' | 'id' | 'anchor'> & {\n  meta?: Pick<AssetMeta, 'title' | 'assetType'>;\n};\n\n/** A web page. */\nexport type AttachableUrlReference = Pick<ExternalUrlReference, 'referenced' | 'url'> & {\n  meta?: Pick<ExternalUrlMeta, 'title'>;\n};\n\n/** Anything an app may attach to a message. */\nexport type AttachableReference =\n  | AttachableAssetReference\n  | OntologyObjectReference\n  | AttachableUrlReference;\n\n/** The kinds an app may attach (`referenced`). */\nexport type AttachableReferenceKind = AttachableReference['referenced'];\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** A display string: trimmed, one line, cut to `limit`; `undefined` when nothing is left. */\nfunction displayText(value: unknown, limit: number): string | undefined {\n  if (typeof value !== 'string') return undefined;\n  // Control characters (newlines included) never reach a chip or the agent's note.\n  const oneLine = value.replace(/[\\u0000-\\u001f\\u007f]+/g, ' ').replace(/\\s+/g, ' ').trim();\n  if (!oneLine) return undefined;\n  return oneLine.length > limit ? `${oneLine.slice(0, limit - 1).trimEnd()}…` : oneLine;\n}\n\nfunction assetId(value: unknown): string | null {\n  return typeof value === 'string' && ASSET_ID.test(value) ? value : null;\n}\n\n/**\n * The anchor as the reference standard writes it, or `null` when it is not one: round-tripped\n * through its canonical query form, so what goes out is exactly what agora's `read_asset` parses.\n */\nfunction canonicalAnchor(value: unknown): Anchor | null {\n  if (!isAnchor(value)) return null;\n  try {\n    const params = serializeAnchorToParams(value);\n    // A missing field serializes as the string \"undefined\" (or \"NaN\"): not an anchor.\n    for (const param of params.values()) {\n      if (param === 'undefined' || param === 'NaN' || param === 'null') return null;\n    }\n    return parseAnchorFromParams(params) ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Characters outside RFC 3986's set. `URL.href` percent-encodes most of them but leaves a few in a\n * query (`{`, `}`, `|`, `^`, …); agora accepts RFC 3986 characters only.\n */\nconst NON_URL_CHARACTERS = /[^A-Za-z0-9\\-._~:/?#[\\]@!$&'()*+,;=%]/g;\n\n/** The URL, normalized, when it is an `http(s)` URL with a host and no embedded credentials. */\nfunction webUrl(value: unknown): string | null {\n  if (typeof value !== 'string' || value.length > MAX_ATTACHED_URL_CHARS) return null;\n  let parsed: URL;\n  try {\n    parsed = new URL(value.trim());\n  } catch {\n    return null;\n  }\n  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;\n  if (!parsed.hostname || parsed.username || parsed.password) return null;\n  const href = parsed.href.replace(NON_URL_CHARACTERS, (character) => encodeURIComponent(character));\n  return href.length > MAX_ATTACHED_URL_CHARS ? null : href;\n}\n\n/**\n * `value` as an attachable reference in its canonical shape, or `null` when it is not one: an\n * unknown kind, a malformed id or URL, or an anchor the standard can't read. Unknown fields are\n * dropped and labels are cut to {@link MAX_ATTACHED_REFERENCE_LABEL_CHARS}.\n */\nexport function normalizeAttachableReference(value: unknown): AttachableReference | null {\n  if (!isRecord(value)) return null;\n  const meta = isRecord(value.meta) ? value.meta : {};\n  const title = displayText(meta.title, MAX_ATTACHED_REFERENCE_LABEL_CHARS);\n  switch (value.referenced) {\n    case 'asset': {\n      const id = assetId(value.id);\n      if (id === null) return null;\n      const reference: AttachableAssetReference = { referenced: 'asset', id };\n      if (value.anchor !== undefined && value.anchor !== null) {\n        const anchor = canonicalAnchor(value.anchor);\n        if (anchor === null) return null;\n        reference.anchor = anchor;\n      }\n      const assetType = displayText(meta.assetType, 100);\n      if (title !== undefined || assetType !== undefined) {\n        reference.meta = {\n          ...(title !== undefined && { title }),\n          ...(assetType !== undefined && { assetType }),\n        };\n      }\n      return reference;\n    }\n    case 'ontology_object': {\n      const id = assetId(value.id);\n      if (id === null) return null;\n      const reference: OntologyObjectReference = { referenced: 'ontology_object', id };\n      const objectType = displayText(meta.objectType, 100);\n      if (title !== undefined || objectType !== undefined) {\n        reference.meta = {\n          ...(title !== undefined && { title }),\n          ...(objectType !== undefined && { objectType }),\n        };\n      }\n      return reference;\n    }\n    case 'external_url': {\n      const url = webUrl(value.url);\n      if (url === null) return null;\n      const reference: AttachableUrlReference = { referenced: 'external_url', url };\n      if (title !== undefined) reference.meta = { title };\n      return reference;\n    }\n    default:\n      return null;\n  }\n}\n\n/**\n * What makes two attachments the same one: the kind and its pointer (an asset's anchor included),\n * never its label. A message carries each at most once.\n */\nexport function attachableReferenceKey(reference: AttachableReference): string {\n  switch (reference.referenced) {\n    case 'asset':\n      return reference.anchor\n        ? `asset:${reference.id}?${serializeAnchorToParams(reference.anchor).toString()}`\n        : `asset:${reference.id}`;\n    case 'ontology_object':\n      return `ontology_object:${reference.id}`;\n    case 'external_url':\n      return `external_url:${reference.url}`;\n  }\n}\n\n/** What a chip calls the reference: its label, else its id or the URL's host and path. */\nexport function attachableReferenceLabel(reference: AttachableReference): string {\n  const title = reference.meta?.title;\n  if (title) return title;\n  if (reference.referenced !== 'external_url') return reference.id;\n  try {\n    const url = new URL(reference.url);\n    const path = url.pathname === '/' ? '' : url.pathname;\n    return `${url.hostname}${path}`;\n  } catch {\n    return reference.url;\n  }\n}\n\n/**\n * The references a message's metadata carries, normalized: each valid one once, in order, at most\n * {@link MAX_ATTACHED_REFERENCES}; anything malformed is left out. `[]` when it carries none.\n */\nexport function readAttachedReferences(metadata: unknown): AttachableReference[] {\n  if (!isRecord(metadata)) return [];\n  const raw = metadata[ATTACHED_REFERENCES_METADATA_KEY];\n  if (!Array.isArray(raw)) return [];\n  const seen = new Set<string>();\n  const references: AttachableReference[] = [];\n  for (const entry of raw) {\n    if (references.length >= MAX_ATTACHED_REFERENCES) break;\n    const reference = normalizeAttachableReference(entry);\n    if (reference === null) continue;\n    const key = attachableReferenceKey(reference);\n    if (seen.has(key)) continue;\n    seen.add(key);\n    references.push(reference);\n  }\n  return references;\n}\n\n/**\n * `metadata` carrying `references` under {@link ATTACHED_REFERENCES_METADATA_KEY}; an empty list\n * leaves the key out (a message attaching nothing says nothing about attachments).\n */\nexport function withAttachedReferences(\n  metadata: Readonly<Record<string, unknown>> | undefined,\n  references: readonly AttachableReference[]\n): Record<string, unknown> | undefined {\n  if (references.length === 0) return metadata === undefined ? undefined : { ...metadata };\n  return { ...metadata, [ATTACHED_REFERENCES_METADATA_KEY]: references.map((reference) => ({ ...reference })) };\n}\n"],"names":["isAnchor","serializeAnchorToParams","parseAnchorFromParams"],"mappings":"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"}

package/dist/references/src/attachable.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `@athenaintel/references/attachable` — what an app can attach to a chat message.
+ *
+ * An app hands the agent the object on screen ("Discuss this with the agent"): the person's next
+ * message carries a list of references as structured data, in its own metadata
+ * (`message.metadata.attachedReferences`), never as text. agora tells the agent what was attached
+ * (kind, id, label) and the agent resolves each one on the server, through the canonical gates and
+ * with the viewer's own permission; something the viewer can't open reaches the agent as a refusal,
+ * never as content (`agora/agora/graphs/athena_deep_agent/attached_references.py`).
+ *
+ * Every kind is a member of the reference standard's family, discriminated by `referenced`:
+ *
+ * - `asset`: the standard's {@link AssetReference}, optionally with an `anchor` (its L2: a page,
+ *   a cell range, a node, …), without a pinned `version`;
+ * - `ontology_object`: an ontology object, named by its `asset_<uuid>` id: a v1 object (an
+ *   `ontology_object` asset) or a Platform 2.0 object row;
+ * - `external_url`: the standard's {@link ExternalUrlReference}.
+ *
+ * TODO(#54759): `table_row` (a row of a lakehouse or Kronos table, by key) waits for a
+ * permission-checked row reader on the server; until it exists an app cannot attach one.
+ *
+ * `meta` is display only (the standard's L3): the label a chip shows, which the server never
+ * trusts as content. The same rules hold on both sides; agora's copy is
+ * `attached_references.py`, and `agora/tests/unit/deep_agent/test_attached_references.py` holds
+ * the two to the same key and cap.
+ *
+ * The `@athenaintel/react` SDK bundles this entry, so it stays free of `zod`: `attachable.test.ts`
+ * walks its import graph.
+ */
+import type { AssetMeta, AssetReference, ExternalUrlMeta, ExternalUrlReference } from './types';
+/** The message metadata key a message's attached references ride under. */
+export declare const ATTACHED_REFERENCES_METADATA_KEY = "attachedReferences";
+/** The most references one message may carry (agora's `MAX_ATTACHED_REFERENCES`). */
+export declare const MAX_ATTACHED_REFERENCES = 10;
+/** The longest label (`meta.title`) a reference keeps; a longer one is cut. */
+export declare const MAX_ATTACHED_REFERENCE_LABEL_CHARS = 200;
+/** The longest URL an `external_url` reference may name. */
+export declare const MAX_ATTACHED_URL_CHARS = 2048;
+/** Display metadata of an ontology object: its title and the name of its type. */
+export type OntologyObjectMeta = {
+    title?: string;
+    objectType?: string;
+};
+/**
+ * An ontology object: a v1 object (an `ontology_object` asset) or a Platform 2.0 object row, both
+ * named by their `asset_<uuid>` id. agora decides which it is and gates it accordingly.
+ */
+export type OntologyObjectReference = {
+    referenced: 'ontology_object';
+    id: string;
+    meta?: OntologyObjectMeta;
+};
+/** An asset, optionally narrowed to a place inside it (`anchor`). */
+export type AttachableAssetReference = Pick<AssetReference, 'referenced' | 'id' | 'anchor'> & {
+    meta?: Pick<AssetMeta, 'title' | 'assetType'>;
+};
+/** A web page. */
+export type AttachableUrlReference = Pick<ExternalUrlReference, 'referenced' | 'url'> & {
+    meta?: Pick<ExternalUrlMeta, 'title'>;
+};
+/** Anything an app may attach to a message. */
+export type AttachableReference = AttachableAssetReference | OntologyObjectReference | AttachableUrlReference;
+/** The kinds an app may attach (`referenced`). */
+export type AttachableReferenceKind = AttachableReference['referenced'];
+/**
+ * `value` as an attachable reference in its canonical shape, or `null` when it is not one: an
+ * unknown kind, a malformed id or URL, or an anchor the standard can't read. Unknown fields are
+ * dropped and labels are cut to {@link MAX_ATTACHED_REFERENCE_LABEL_CHARS}.
+ */
+export declare function normalizeAttachableReference(value: unknown): AttachableReference | null;
+/**
+ * What makes two attachments the same one: the kind and its pointer (an asset's anchor included),
+ * never its label. A message carries each at most once.
+ */
+export declare function attachableReferenceKey(reference: AttachableReference): string;
+/** What a chip calls the reference: its label, else its id or the URL's host and path. */
+export declare function attachableReferenceLabel(reference: AttachableReference): string;
+/**
+ * The references a message's metadata carries, normalized: each valid one once, in order, at most
+ * {@link MAX_ATTACHED_REFERENCES}; anything malformed is left out. `[]` when it carries none.
+ */
+export declare function readAttachedReferences(metadata: unknown): AttachableReference[];
+/**
+ * `metadata` carrying `references` under {@link ATTACHED_REFERENCES_METADATA_KEY}; an empty list
+ * leaves the key out (a message attaching nothing says nothing about attachments).
+ */
+export declare function withAttachedReferences(metadata: Readonly<Record<string, unknown>> | undefined, references: readonly AttachableReference[]): Record<string, unknown> | undefined;

package/dist/references/src/attachable.js

@@ -0,0 +1,149 @@
+import { parseAnchorFromParams } from "./anchors/parse.js";
+import { serializeAnchorToParams } from "./anchors/serialize.js";
+import { isAnchor } from "./anchors/types.js";
+const ATTACHED_REFERENCES_METADATA_KEY = "attachedReferences";
+const MAX_ATTACHED_REFERENCES = 10;
+const MAX_ATTACHED_REFERENCE_LABEL_CHARS = 200;
+const MAX_ATTACHED_URL_CHARS = 2048;
+const ASSET_ID = /^asset_[A-Za-z0-9_-]{1,200}$/;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function displayText(value, limit) {
+  if (typeof value !== "string") return void 0;
+  const oneLine = value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  if (!oneLine) return void 0;
+  return oneLine.length > limit ? `${oneLine.slice(0, limit - 1).trimEnd()}…` : oneLine;
+}
+function assetId(value) {
+  return typeof value === "string" && ASSET_ID.test(value) ? value : null;
+}
+function canonicalAnchor(value) {
+  if (!isAnchor(value)) return null;
+  try {
+    const params = serializeAnchorToParams(value);
+    for (const param of params.values()) {
+      if (param === "undefined" || param === "NaN" || param === "null") return null;
+    }
+    return parseAnchorFromParams(params) ?? null;
+  } catch {
+    return null;
+  }
+}
+const NON_URL_CHARACTERS = /[^A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=%]/g;
+function webUrl(value) {
+  if (typeof value !== "string" || value.length > MAX_ATTACHED_URL_CHARS) return null;
+  let parsed;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  if (!parsed.hostname || parsed.username || parsed.password) return null;
+  const href = parsed.href.replace(NON_URL_CHARACTERS, (character) => encodeURIComponent(character));
+  return href.length > MAX_ATTACHED_URL_CHARS ? null : href;
+}
+function normalizeAttachableReference(value) {
+  if (!isRecord(value)) return null;
+  const meta = isRecord(value.meta) ? value.meta : {};
+  const title = displayText(meta.title, MAX_ATTACHED_REFERENCE_LABEL_CHARS);
+  switch (value.referenced) {
+    case "asset": {
+      const id = assetId(value.id);
+      if (id === null) return null;
+      const reference = { referenced: "asset", id };
+      if (value.anchor !== void 0 && value.anchor !== null) {
+        const anchor = canonicalAnchor(value.anchor);
+        if (anchor === null) return null;
+        reference.anchor = anchor;
+      }
+      const assetType = displayText(meta.assetType, 100);
+      if (title !== void 0 || assetType !== void 0) {
+        reference.meta = {
+          ...title !== void 0 && { title },
+          ...assetType !== void 0 && { assetType }
+        };
+      }
+      return reference;
+    }
+    case "ontology_object": {
+      const id = assetId(value.id);
+      if (id === null) return null;
+      const reference = { referenced: "ontology_object", id };
+      const objectType = displayText(meta.objectType, 100);
+      if (title !== void 0 || objectType !== void 0) {
+        reference.meta = {
+          ...title !== void 0 && { title },
+          ...objectType !== void 0 && { objectType }
+        };
+      }
+      return reference;
+    }
+    case "external_url": {
+      const url = webUrl(value.url);
+      if (url === null) return null;
+      const reference = { referenced: "external_url", url };
+      if (title !== void 0) reference.meta = { title };
+      return reference;
+    }
+    default:
+      return null;
+  }
+}
+function attachableReferenceKey(reference) {
+  switch (reference.referenced) {
+    case "asset":
+      return reference.anchor ? `asset:${reference.id}?${serializeAnchorToParams(reference.anchor).toString()}` : `asset:${reference.id}`;
+    case "ontology_object":
+      return `ontology_object:${reference.id}`;
+    case "external_url":
+      return `external_url:${reference.url}`;
+  }
+}
+function attachableReferenceLabel(reference) {
+  var _a;
+  const title = (_a = reference.meta) == null ? void 0 : _a.title;
+  if (title) return title;
+  if (reference.referenced !== "external_url") return reference.id;
+  try {
+    const url = new URL(reference.url);
+    const path = url.pathname === "/" ? "" : url.pathname;
+    return `${url.hostname}${path}`;
+  } catch {
+    return reference.url;
+  }
+}
+function readAttachedReferences(metadata) {
+  if (!isRecord(metadata)) return [];
+  const raw = metadata[ATTACHED_REFERENCES_METADATA_KEY];
+  if (!Array.isArray(raw)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const references = [];
+  for (const entry of raw) {
+    if (references.length >= MAX_ATTACHED_REFERENCES) break;
+    const reference = normalizeAttachableReference(entry);
+    if (reference === null) continue;
+    const key = attachableReferenceKey(reference);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    references.push(reference);
+  }
+  return references;
+}
+function withAttachedReferences(metadata, references) {
+  if (references.length === 0) return metadata === void 0 ? void 0 : { ...metadata };
+  return { ...metadata, [ATTACHED_REFERENCES_METADATA_KEY]: references.map((reference) => ({ ...reference })) };
+}
+export {
+  ATTACHED_REFERENCES_METADATA_KEY,
+  MAX_ATTACHED_REFERENCES,
+  MAX_ATTACHED_REFERENCE_LABEL_CHARS,
+  MAX_ATTACHED_URL_CHARS,
+  attachableReferenceKey,
+  attachableReferenceLabel,
+  normalizeAttachableReference,
+  readAttachedReferences,
+  withAttachedReferences
+};
+//# sourceMappingURL=attachable.js.map

package/dist/references/src/attachable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachable.js","sources":["../../../../references/src/attachable.ts"],"sourcesContent":["/**\n * `@athenaintel/references/attachable` — what an app can attach to a chat message.\n *\n * An app hands the agent the object on screen (\"Discuss this with the agent\"): the person's next\n * message carries a list of references as structured data, in its own metadata\n * (`message.metadata.attachedReferences`), never as text. agora tells the agent what was attached\n * (kind, id, label) and the agent resolves each one on the server, through the canonical gates and\n * with the viewer's own permission; something the viewer can't open reaches the agent as a refusal,\n * never as content (`agora/agora/graphs/athena_deep_agent/attached_references.py`).\n *\n * Every kind is a member of the reference standard's family, discriminated by `referenced`:\n *\n * - `asset`: the standard's {@link AssetReference}, optionally with an `anchor` (its L2: a page,\n *   a cell range, a node, …), without a pinned `version`;\n * - `ontology_object`: an ontology object, named by its `asset_<uuid>` id: a v1 object (an\n *   `ontology_object` asset) or a Platform 2.0 object row;\n * - `external_url`: the standard's {@link ExternalUrlReference}.\n *\n * TODO(#54759): `table_row` (a row of a lakehouse or Kronos table, by key) waits for a\n * permission-checked row reader on the server; until it exists an app cannot attach one.\n *\n * `meta` is display only (the standard's L3): the label a chip shows, which the server never\n * trusts as content. The same rules hold on both sides; agora's copy is\n * `attached_references.py`, and `agora/tests/unit/deep_agent/test_attached_references.py` holds\n * the two to the same key and cap.\n *\n * The `@athenaintel/react` SDK bundles this entry, so it stays free of `zod`: `attachable.test.ts`\n * walks its import graph.\n */\n\nimport { parseAnchorFromParams } from './anchors/parse';\nimport { serializeAnchorToParams } from './anchors/serialize';\nimport type { Anchor } from './anchors/types';\nimport { isAnchor } from './anchors/types';\nimport type { AssetMeta, AssetReference, ExternalUrlMeta, ExternalUrlReference } from './types';\n\n/** The message metadata key a message's attached references ride under. */\nexport const ATTACHED_REFERENCES_METADATA_KEY = 'attachedReferences';\n\n/** The most references one message may carry (agora's `MAX_ATTACHED_REFERENCES`). */\nexport const MAX_ATTACHED_REFERENCES = 10;\n\n/** The longest label (`meta.title`) a reference keeps; a longer one is cut. */\nexport const MAX_ATTACHED_REFERENCE_LABEL_CHARS = 200;\n\n/** The longest URL an `external_url` reference may name. */\nexport const MAX_ATTACHED_URL_CHARS = 2048;\n\n/** An asset (or a Platform 2.0 object) id: `asset_` and up to 200 id characters, nothing else. */\nconst ASSET_ID = /^asset_[A-Za-z0-9_-]{1,200}$/;\n\n/** Display metadata of an ontology object: its title and the name of its type. */\nexport type OntologyObjectMeta = {\n  title?: string;\n  objectType?: string;\n};\n\n/**\n * An ontology object: a v1 object (an `ontology_object` asset) or a Platform 2.0 object row, both\n * named by their `asset_<uuid>` id. agora decides which it is and gates it accordingly.\n */\nexport type OntologyObjectReference = {\n  referenced: 'ontology_object';\n  id: string;\n  meta?: OntologyObjectMeta;\n};\n\n/** An asset, optionally narrowed to a place inside it (`anchor`). */\nexport type AttachableAssetReference = Pick<AssetReference, 'referenced' | 'id' | 'anchor'> & {\n  meta?: Pick<AssetMeta, 'title' | 'assetType'>;\n};\n\n/** A web page. */\nexport type AttachableUrlReference = Pick<ExternalUrlReference, 'referenced' | 'url'> & {\n  meta?: Pick<ExternalUrlMeta, 'title'>;\n};\n\n/** Anything an app may attach to a message. */\nexport type AttachableReference =\n  | AttachableAssetReference\n  | OntologyObjectReference\n  | AttachableUrlReference;\n\n/** The kinds an app may attach (`referenced`). */\nexport type AttachableReferenceKind = AttachableReference['referenced'];\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** A display string: trimmed, one line, cut to `limit`; `undefined` when nothing is left. */\nfunction displayText(value: unknown, limit: number): string | undefined {\n  if (typeof value !== 'string') return undefined;\n  // Control characters (newlines included) never reach a chip or the agent's note.\n  const oneLine = value.replace(/[\\u0000-\\u001f\\u007f]+/g, ' ').replace(/\\s+/g, ' ').trim();\n  if (!oneLine) return undefined;\n  return oneLine.length > limit ? `${oneLine.slice(0, limit - 1).trimEnd()}…` : oneLine;\n}\n\nfunction assetId(value: unknown): string | null {\n  return typeof value === 'string' && ASSET_ID.test(value) ? value : null;\n}\n\n/**\n * The anchor as the reference standard writes it, or `null` when it is not one: round-tripped\n * through its canonical query form, so what goes out is exactly what agora's `read_asset` parses.\n */\nfunction canonicalAnchor(value: unknown): Anchor | null {\n  if (!isAnchor(value)) return null;\n  try {\n    const params = serializeAnchorToParams(value);\n    // A missing field serializes as the string \"undefined\" (or \"NaN\"): not an anchor.\n    for (const param of params.values()) {\n      if (param === 'undefined' || param === 'NaN' || param === 'null') return null;\n    }\n    return parseAnchorFromParams(params) ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Characters outside RFC 3986's set. `URL.href` percent-encodes most of them but leaves a few in a\n * query (`{`, `}`, `|`, `^`, …); agora accepts RFC 3986 characters only.\n */\nconst NON_URL_CHARACTERS = /[^A-Za-z0-9\\-._~:/?#[\\]@!$&'()*+,;=%]/g;\n\n/** The URL, normalized, when it is an `http(s)` URL with a host and no embedded credentials. */\nfunction webUrl(value: unknown): string | null {\n  if (typeof value !== 'string' || value.length > MAX_ATTACHED_URL_CHARS) return null;\n  let parsed: URL;\n  try {\n    parsed = new URL(value.trim());\n  } catch {\n    return null;\n  }\n  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;\n  if (!parsed.hostname || parsed.username || parsed.password) return null;\n  const href = parsed.href.replace(NON_URL_CHARACTERS, (character) => encodeURIComponent(character));\n  return href.length > MAX_ATTACHED_URL_CHARS ? null : href;\n}\n\n/**\n * `value` as an attachable reference in its canonical shape, or `null` when it is not one: an\n * unknown kind, a malformed id or URL, or an anchor the standard can't read. Unknown fields are\n * dropped and labels are cut to {@link MAX_ATTACHED_REFERENCE_LABEL_CHARS}.\n */\nexport function normalizeAttachableReference(value: unknown): AttachableReference | null {\n  if (!isRecord(value)) return null;\n  const meta = isRecord(value.meta) ? value.meta : {};\n  const title = displayText(meta.title, MAX_ATTACHED_REFERENCE_LABEL_CHARS);\n  switch (value.referenced) {\n    case 'asset': {\n      const id = assetId(value.id);\n      if (id === null) return null;\n      const reference: AttachableAssetReference = { referenced: 'asset', id };\n      if (value.anchor !== undefined && value.anchor !== null) {\n        const anchor = canonicalAnchor(value.anchor);\n        if (anchor === null) return null;\n        reference.anchor = anchor;\n      }\n      const assetType = displayText(meta.assetType, 100);\n      if (title !== undefined || assetType !== undefined) {\n        reference.meta = {\n          ...(title !== undefined && { title }),\n          ...(assetType !== undefined && { assetType }),\n        };\n      }\n      return reference;\n    }\n    case 'ontology_object': {\n      const id = assetId(value.id);\n      if (id === null) return null;\n      const reference: OntologyObjectReference = { referenced: 'ontology_object', id };\n      const objectType = displayText(meta.objectType, 100);\n      if (title !== undefined || objectType !== undefined) {\n        reference.meta = {\n          ...(title !== undefined && { title }),\n          ...(objectType !== undefined && { objectType }),\n        };\n      }\n      return reference;\n    }\n    case 'external_url': {\n      const url = webUrl(value.url);\n      if (url === null) return null;\n      const reference: AttachableUrlReference = { referenced: 'external_url', url };\n      if (title !== undefined) reference.meta = { title };\n      return reference;\n    }\n    default:\n      return null;\n  }\n}\n\n/**\n * What makes two attachments the same one: the kind and its pointer (an asset's anchor included),\n * never its label. A message carries each at most once.\n */\nexport function attachableReferenceKey(reference: AttachableReference): string {\n  switch (reference.referenced) {\n    case 'asset':\n      return reference.anchor\n        ? `asset:${reference.id}?${serializeAnchorToParams(reference.anchor).toString()}`\n        : `asset:${reference.id}`;\n    case 'ontology_object':\n      return `ontology_object:${reference.id}`;\n    case 'external_url':\n      return `external_url:${reference.url}`;\n  }\n}\n\n/** What a chip calls the reference: its label, else its id or the URL's host and path. */\nexport function attachableReferenceLabel(reference: AttachableReference): string {\n  const title = reference.meta?.title;\n  if (title) return title;\n  if (reference.referenced !== 'external_url') return reference.id;\n  try {\n    const url = new URL(reference.url);\n    const path = url.pathname === '/' ? '' : url.pathname;\n    return `${url.hostname}${path}`;\n  } catch {\n    return reference.url;\n  }\n}\n\n/**\n * The references a message's metadata carries, normalized: each valid one once, in order, at most\n * {@link MAX_ATTACHED_REFERENCES}; anything malformed is left out. `[]` when it carries none.\n */\nexport function readAttachedReferences(metadata: unknown): AttachableReference[] {\n  if (!isRecord(metadata)) return [];\n  const raw = metadata[ATTACHED_REFERENCES_METADATA_KEY];\n  if (!Array.isArray(raw)) return [];\n  const seen = new Set<string>();\n  const references: AttachableReference[] = [];\n  for (const entry of raw) {\n    if (references.length >= MAX_ATTACHED_REFERENCES) break;\n    const reference = normalizeAttachableReference(entry);\n    if (reference === null) continue;\n    const key = attachableReferenceKey(reference);\n    if (seen.has(key)) continue;\n    seen.add(key);\n    references.push(reference);\n  }\n  return references;\n}\n\n/**\n * `metadata` carrying `references` under {@link ATTACHED_REFERENCES_METADATA_KEY}; an empty list\n * leaves the key out (a message attaching nothing says nothing about attachments).\n */\nexport function withAttachedReferences(\n  metadata: Readonly<Record<string, unknown>> | undefined,\n  references: readonly AttachableReference[]\n): Record<string, unknown> | undefined {\n  if (references.length === 0) return metadata === undefined ? undefined : { ...metadata };\n  return { ...metadata, [ATTACHED_REFERENCES_METADATA_KEY]: references.map((reference) => ({ ...reference })) };\n}\n"],"names":[],"mappings":"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"}