akanjs 3.0.0-beta.7 → 3.0.0-beta.9

package/types/store/agentic/useAgentReference.d.ts

@@ -0,0 +1,32 @@
+import { type AgentFieldType, type AgentValueOf } from "./AgentValue.d.ts";
+/**
+ * What a component hands over when the user points at data it is already drawing.
+ *
+ * The pointer and the value are declared apart on purpose. `refName`/`refId`/`path` say *what was pointed at*, and
+ * travel so the agent can read it again later; `type` and `value` say *what is being shown to the model now*, and
+ * the component supplies the value it already holds, so there is no round trip. They come apart because the two
+ * are genuinely different in the case this exists for: a rich-text field stored as `field(Any)` is an editor
+ * document at its path and a paragraph of prose to a reader, and the model wants the paragraph.
+ *
+ * `type` is `st.expose`'s vocabulary, not a second one. It decides what leaves the browser — a model class masks
+ * by that model, a scalar passes, `Any` passes untouched — so naming a `Light` class that does not carry the field
+ * is how a reference arrives empty.
+ */
+export interface AgentReferenceInput<T extends AgentFieldType> {
+    refName: string;
+    refId: string;
+    /** What the chip draws and what the token in the draft spells. */
+    label: string;
+    /** A dotted path into the document, in `pathSet`'s vocabulary. Absent points at the whole of it. */
+    path?: string;
+    type: T;
+    value: AgentValueOf<T>;
+}
+/**
+ * Points the enclosing agent session at data, from anywhere that draws it.
+ *
+ * No-ops outside a session rather than throwing, the same call `AgentValue.publishable` makes: a card carrying a
+ * reference button is mounted on whatever routes render it, and a route that happens to host no agent must not
+ * lose its render over it.
+ */
+export declare const useAgentReference: () => <T extends AgentFieldType>({ type, value, ...pointer }: AgentReferenceInput<T>) => void;

package/types/store/hooks.d.ts

@@ -1 +1 @@
-export { useEffect, useRef, useSyncExternalStore } from "react";
+export { useContext, useEffect, useRef, useSyncExternalStore } from "react";

package/types/ui/Agent/Chat.d.ts

@@ -3,6 +3,7 @@ import { type AgentRunner, type AgentSessionOptions, type CompactOptions, type S
 import type { AttachLimits, AttachReader } from "./attachment.d.ts";
 import type { PersistOption } from "./sessionHistory.d.ts";
 import type { BuiltinOption } from "./sessionView.d.ts";
+import { type ReferenceSource } from "./useReferenceMenu.d.ts";
 import type { VoiceEngine } from "./voice.d.ts";
 export interface ChatProps {
     /** Reaches whichever surface is showing — the launcher while closed, the panel while open. */
@@ -78,6 +79,15 @@ export interface ChatProps {
      * uploading reader gets a thumbnail without betting the answer on who can reach its storage.
      */
     attach?: AttachReader;
+    /**
+     * What the composer's `@` menu can point at — one entry per kind of document a user may name while asking.
+     *
+     * Which documents those are is the app's answer, so the source carries its own `search`; the framework carries
+     * the token, the masking and the snapshot. Whole documents only: a field inside one is pointed at from the
+     * component that draws it, with `useAgentReference`, because that component is the thing that knows a rich-text
+     * field reads as a paragraph rather than as the editor document it is stored as.
+     */
+    reference?: readonly ReferenceSource[];
     /**
      * Raises or lowers what the composer accepts — per file, per message, and how many. The defaults are what one
      * turn's JSON safely carries to a conservative provider; an app pointed at a larger request limit, or one whose
@@ -98,6 +108,6 @@ export interface ChatProps {
  * `persist` keeps it. An enclosing AgentProvider's session wins, which is how an app isolates a surface or swaps
  * the loop while keeping this UI.
  */
-export declare const DefaultChat: ({ className, title, instructions, runner, maxTurns, compact, builtins, onCompact, defaultOpen, open: openProp, onOpenChange, launcher, persist, inline, shortcut, launcherClassName, panelClassName, intro, header, chrome, defaultDraft, attach, attachLimits, voice, }: ChatProps) => ReactNode;
+export declare const DefaultChat: ({ className, title, instructions, runner, maxTurns, compact, builtins, onCompact, defaultOpen, open: openProp, onOpenChange, launcher, persist, inline, shortcut, launcherClassName, panelClassName, intro, header, chrome, defaultDraft, attach, attachLimits, reference, voice, }: ChatProps) => ReactNode;
 declare const _default: import("react").ComponentType<ChatProps>;
 export default _default;

package/types/ui/Agent/Composer.d.ts

@@ -1,10 +1,15 @@
 import { type KeyboardEvent, type RefObject } from "react";
-import type { AgentSession, MessageAttachment } from "../../vendor/use-agentic.d.ts";
+import type { AgentSession, MessageAttachment, MessageReference } from "../../vendor/use-agentic.d.ts";
 export interface ComposerProps {
     className?: string;
     session: AgentSession;
     draft: string;
     attached: readonly MessageAttachment[];
+    /**
+     * What the draft's `@[…](mention:…)` tokens point at. The text is what carries them, so a composer that draws no
+     * chip still sends them — the chip is how somebody sees and removes one, not how it travels.
+     */
+    references?: readonly MessageReference[];
     /** Files still being read. An `attach` that uploads takes seconds, and a panel that shows nothing looks broken. */
     pending?: number;
     /** Absent when the screen cannot listen — the same rule as publishing no tool for a control that is not drawn. */
@@ -16,10 +21,12 @@ export interface ComposerProps {
     onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
     onFiles: (files: File[]) => void;
     onRemoveFile: (idx: number) => void;
+    /** Keyed on `refName/refId#path`, not on a row index: the order is the draft's, and the draft is the truth. */
+    onRemoveReference?: (key: string) => void;
     onSend: () => void;
     onStop: () => void;
     inputRef?: RefObject<HTMLTextAreaElement | null>;
 }
 /** What the user writes with: the staged files above, and the controls that send or stop below them. */
-export declare const DefaultComposer: ({ className, session, draft, attached, pending, mic, onDraft, onKeyDown, onFiles, onRemoveFile, onSend, onStop, inputRef, }: ComposerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DefaultComposer: ({ className, session, draft, attached, references, pending, mic, onDraft, onKeyDown, onFiles, onRemoveFile, onRemoveReference, onSend, onStop, inputRef, }: ComposerProps) => import("react/jsx-runtime").JSX.Element;
 export declare const Composer: import("react").ComponentType<ComposerProps>;

package/types/ui/Agent/Menu.d.ts

@@ -10,9 +10,11 @@ export interface MenuProps {
     rows: MenuRow[];
     /** Index the arrows are on. Enter picks it and Tab completes its name, so it has to be visible. */
     selected: number;
+    /** What the rows are being typed after, so a name reads as the thing the user is completing. */
+    prefix?: string;
     onPick: (row: MenuRow) => void;
 }
-/** The `/` menu: this chat's own commands first, then the app's `prompt()` endpoints. */
-export declare const DefaultAgentMenu: ({ className, rows, selected, onPick }: MenuProps) => import("react/jsx-runtime").JSX.Element | null;
+/** The composer's completion list: `/` commands and `prompt()` endpoints, or the `@` menu's reference rows. */
+export declare const DefaultAgentMenu: ({ className, rows, selected, prefix, onPick }: MenuProps) => import("react/jsx-runtime").JSX.Element | null;
 declare const _default: import("react").ComponentType<MenuProps>;
 export default _default;

package/types/ui/Agent/Refer.d.ts

@@ -0,0 +1,13 @@
+import { type MessageReference } from "../../vendor/use-agentic.d.ts";
+export interface ReferenceChipsProps {
+    className?: string;
+    references: readonly MessageReference[];
+    /** Omitted for a sent message: what is already on the wire cannot be taken back. */
+    onRemove?: (key: string) => void;
+    removeLabel?: string;
+}
+/**
+ * What the user pointed at, beside what they are typing. Keyed on the pointer rather than on the row's position:
+ * the order a message's references appear in is its text's, and removing one is removing its token.
+ */
+export declare const ReferenceChips: ({ className, references, onRemove, removeLabel }: ReferenceChipsProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Agent/useChatQueue.d.ts

@@ -1,9 +1,11 @@
-import type { AgentSession, MessageAttachment } from "../../vendor/use-agentic.d.ts";
+import type { AgentSession, MessageAttachment, MessageReference } from "../../vendor/use-agentic.d.ts";
 import { type AttachLimits } from "./attachment.d.ts";
 /** What the composer held when it was sent: the shape a turn opens with, whether now or after the running one. */
 export interface QueuedMessage {
     text: string;
     attachments: MessageAttachment[];
+    /** What the parked text's tokens pointed at. Carried so a turn that opens later still knows what they held. */
+    references: MessageReference[];
     /** The ask came from the microphone, so the reply it gets is read aloud — carried until the send that opens it. */
     byVoice: boolean;
 }

package/types/ui/Agent/useChatReferences.d.ts

@@ -0,0 +1,26 @@
+import { type RefObject } from "react";
+import { type AgentSession, type MessageReference } from "../../vendor/use-agentic.d.ts";
+interface ChatReferencesSetup {
+    session: AgentSession;
+    draft: string;
+    /** The chat's own version snapshot — a `refer` from anywhere on the page is one of the changes it counts. */
+    version: number;
+    inputRef: RefObject<HTMLTextAreaElement | null>;
+    onDraft: (text: string) => void;
+}
+/**
+ * The composer's half of a reference: writing the token for one somebody pointed at elsewhere, and reading back
+ * which references the draft now carries.
+ *
+ * **The text is the source of truth, and the staged values are looked up beside it.** A reference is on the
+ * message because its token is in the message — so deleting the token by hand drops it, exactly as deleting the
+ * chip does, and neither can leave the other behind. The draft is never scanned to re-derive a value; a token
+ * whose value was never staged (pasted out of an earlier message) travels as a pointer with a note saying to read
+ * it again, which is the same shape a restored conversation produces.
+ */
+export declare const useChatReferences: ({ session, draft, version, inputRef, onDraft }: ChatReferencesSetup) => {
+    references: MessageReference[];
+    /** Removing the chip removes the token, because the token is what puts the reference on the message. */
+    remove: (key: string) => void;
+};
+export {};

package/types/ui/Agent/useReferenceMenu.d.ts

@@ -0,0 +1,43 @@
+import { type AgentFieldType } from "akanjs/store";
+import { type AgentSession } from "../../vendor/use-agentic.d.ts";
+import type { MenuRow } from "./Menu.d.ts";
+/** One row the `@` menu offers: a document of its source's model, named the way the screen names it. */
+export interface ReferenceCandidate {
+    refId: string;
+    label: string;
+    description?: string;
+}
+/**
+ * A kind of document the `@` menu can point at.
+ *
+ * `type` is the whole decision about what leaves the browser, in `st.expose`'s vocabulary — a model class masks by
+ * that model. **Name the class that actually carries the fields somebody is pointing at**: a `Light<Model>` is
+ * usually not it, and a reference masked by one arrives without the field that was the reason for pointing.
+ *
+ * `search` is the app's own query, because which documents a person may point at is the app's answer and not the
+ * framework's; the signal is aborted when the query moves on. `resolve` is called once, when a row is picked.
+ */
+export interface ReferenceSource<T extends AgentFieldType = AgentFieldType> {
+    refName: string;
+    /** What this group of rows is called in the menu. */
+    label: string;
+    type: T;
+    search: (query: string, signal: AbortSignal) => Promise<ReferenceCandidate[]>;
+    resolve: (refId: string) => Promise<unknown>;
+}
+interface ReferenceMenuSetup {
+    draft: string;
+    sources: readonly ReferenceSource[];
+    session: AgentSession;
+    l: (key: string, param?: Record<string, string | number>) => string;
+    onWrite: (text: string) => void;
+}
+export declare const useReferenceMenu: ({ draft, sources, session, l, onWrite }: ReferenceMenuSetup) => {
+    rows: MenuRow[];
+    selected: number;
+    reopen: () => void;
+    hide: () => void;
+    move: (delta: number) => void;
+    at: () => MenuRow | undefined;
+};
+export {};

package/types/ui/Field/lightRefCache.d.ts

@@ -0,0 +1,19 @@
+interface LightRow {
+    id: string;
+}
+/**
+ * Light rows read one id at a time, for a control holding an id its option list does not carry — a form opened
+ * through `edit<Model>` before the dropdown was ever opened, or a row outside the one `limit`-sized window a
+ * slice list holds.
+ *
+ * Deliberately not the model's store: that store is a singleton, so reading into it would overwrite whatever
+ * listing of the same model is already on the screen — the same reason `Data/RefPicker` keeps its rows local.
+ */
+export declare class LightRefCache {
+    #private;
+    static get<Light extends LightRow>(refName: string, id: string): Light | null;
+    static subscribe(listener: (refName: string, id: string) => void): () => void;
+    static load(refName: string, ids: string[]): void;
+    static reset(): void;
+}
+export {};

package/types/ui/Field/useRelationOptions.d.ts

@@ -0,0 +1,39 @@
+import { DataList } from "akanjs/base";
+import type { SliceMeta } from "akanjs/fetch";
+import { type ReactNode } from "react";
+export interface RelationOptionsSource<Light extends {
+    id: string;
+}> {
+    slice: SliceMeta;
+    /** Ids the control holds right now, whether or not the option list carries them. */
+    ids: string[];
+    /** Rows the control was handed outright, which a `Light`-valued field's own value already is. */
+    pinned?: (Light | null)[];
+    initArgs?: any[];
+    sortOption?: (a: Light, b: Light) => number;
+    renderOption?: (model: Light) => ReactNode;
+}
+/**
+ * The options a relation control offers, which are never only the slice list: that list arrives when the dropdown
+ * opens and holds one page when it does, so a control rendering a value the list does not carry would render an
+ * empty field over a form that holds the value. What is missing from it is filled from the value the control was
+ * handed, and — for an id-valued control, which holds no row at all — read by id through {@link LightRefCache}.
+ */
+export declare const useRelationOptions: <Light extends {
+    id: string;
+}>({ slice, ids, pinned, initArgs, sortOption, renderOption, }: RelationOptionsSource<Light>) => {
+    models: DataList<Light>;
+    options: {
+        label: string;
+        value: string;
+    }[];
+    optionLabel: (model: Light) => string;
+    listLoading: boolean;
+    /**
+     * `invalidate: false` so an open reuses a list the page already loaded rather than replacing it: the slice
+     * list is one store key, so refetching it here overwrites whatever listing of the same model is on screen.
+     */
+    load: () => Promise<void>;
+    /** Live rather than the rendered list, because the agent's list tool loads and reads within one call. */
+    read: () => DataList<Light>;
+};

package/types/ui/Select.d.ts

@@ -28,6 +28,8 @@ export interface SelectProps<T extends string | number | boolean | null | undefi
     nullable?: boolean;
     /** Disable open and selection behavior. */
     disabled?: boolean;
+    /** The options are still being loaded: shows a spinner in place of the empty placeholder. */
+    loading?: boolean;
     /** Called when the dropdown opens. */
     onOpen?: () => void;
     /** Controlled change callback. Receives next and previous value. */

package/types/ui/index.d.ts

@@ -1,4 +1,5 @@
-export { AgentProvider, type AgentProviderProps, type AgentRunner, AgentSession, type AgentSessionOptions, type ChatMessage, type CompactOptions, type ContextBlock, httpRunner, type MessageAttachment, type PublishedTool, type RunnerEvent, type RunnerRequest, SessionContext, type SessionHistory, type SurfaceView, useAgent, } from "../vendor/use-agentic.d.ts";
+export { type AgentReferenceInput, useAgentReference } from "akanjs/store";
+export { AgentProvider, type AgentProviderProps, type AgentRunner, AgentSession, type AgentSessionOptions, type ChatMessage, type CompactOptions, type ContextBlock, httpRunner, type MessageAttachment, type MessageReference, type PublishedTool, Reference, type RunnerEvent, type RunnerRequest, SessionContext, type SessionHistory, type SurfaceView, useAgent, } from "../vendor/use-agentic.d.ts";
 export { Agent } from "./Agent.d.ts";
 export { type ApprovalProps, DefaultApproval } from "./Agent/Approval.d.ts";
 export { Chips as AgentAttachments, type ChipsProps as AgentAttachmentsProps } from "./Agent/Attach.d.ts";
@@ -15,10 +16,12 @@ export { type CodeProps, DefaultCode, DefaultMarkdown, type MarkdownProps } from
 export { DefaultAgentMenu, type MenuProps as AgentMenuProps, type MenuRow } from "./Agent/Menu.d.ts";
 export { DefaultQuestion, type QuestionProps } from "./Agent/Question.d.ts";
 export { DefaultQueued, type QueuedProps } from "./Agent/Queued.d.ts";
+export { ReferenceChips as AgentReferences, type ReferenceChipsProps as AgentReferencesProps, } from "./Agent/Refer.d.ts";
 export type { PersistOption } from "./Agent/sessionHistory.d.ts";
 export type { AgentBuiltin, BuiltinOption } from "./Agent/sessionView.d.ts";
 export { tokenCount } from "./Agent/tokenCount.d.ts";
 export type { QueuedMessage } from "./Agent/useChatQueue.d.ts";
+export type { ReferenceCandidate, ReferenceSource } from "./Agent/useReferenceMenu.d.ts";
 export type { VoiceEngine, VoiceHandlers, VoiceListener, VoiceSpeech } from "./Agent/voice.d.ts";
 export { agentAttrs } from "./agentAttrs.d.ts";
 export { animated } from "./animated.d.ts";

package/types/vendor/use-agentic/AgentSession.d.ts

@@ -1,6 +1,6 @@
 import type { AgentProgressReport } from "./AgentProgress.d.ts";
 import { type CompactOptions } from "./Compaction.d.ts";
-import type { AgentRunner, ChatMessage, ContextBlock, PublishedTool, SurfaceView } from "./types.d.ts";
+import type { AgentRunner, ChatMessage, ContextBlock, MessageReference, PublishedTool, SurfaceView } from "./types.d.ts";
 export interface PendingApproval {
     callId: string;
     name: string;
@@ -111,6 +111,59 @@ export declare class AgentSession {
     get isCompacting(): boolean;
     get pendingApproval(): PendingApproval | null;
     get pendingQuestion(): PendingQuestion | null;
+    /**
+     * What the user has pointed at and not yet sent.
+     *
+     * Held by the session rather than by the composer, which is where staged *files* live — and the difference is
+     * not an inconsistency. A file only ever arrives from the composer's own picker or drop zone, so composer-local
+     * state can reach every producer of one. A reference arrives from whichever component drew the data: a card
+     * partway down the page, reaching the session it is already inside. Composer state is unreachable from there,
+     * and a chat that replaces its composer has no state to reach anyway.
+     *
+     * A staging slot, not a tray. `send` empties it, so what somebody pointed at belongs to the message they were
+     * writing and never leaks into the next one.
+     */
+    get staged(): readonly MessageReference[];
+    /**
+     * Pointing at the same field twice replaces it: the newer value is the one they meant, and one chip is honest.
+     *
+     * Stages the value only. The caller is the composer's own `@` menu, which is already writing the token as the
+     * user picks — `refer` is the entry point for everything that is not the composer.
+     */
+    stage: (reference: MessageReference) => void;
+    /**
+     * Points at something from a component that is not the composer — a card the user clicked beside the data.
+     *
+     * Two halves, because the composer owns one of them: the value is staged here, and the token the message needs
+     * is left for whichever chat is rendering this session's draft to write. That is why nothing is queued when no
+     * chat is: the value would sit staged with no token anywhere naming it, and the message text is what decides
+     * which references a turn carries — so the user would press a button and watch nothing happen, which is the
+     * failure this warns about instead.
+     */
+    refer: (reference: MessageReference) => void;
+    /**
+     * Tokens a chat has not written into its draft yet. State rather than a queue somebody drains, for the reason
+     * `pendingApproval` is state: two chats may be mounted on one session — a responsive app renders a desktop and
+     * a mobile composer and hides one in CSS — and each holds its own draft, so each has to write the token. A
+     * destructive read would hand it to whichever rendered first and leave the other silently without it.
+     */
+    get pendingInserts(): readonly MessageReference[];
+    /** Idempotent by key: the second chat to apply the same insert is acknowledging one that is already gone. */
+    insertApplied: (key: string) => void;
+    /**
+     * Stages references back from a message that was parked behind a running turn. What was pointed at since wins:
+     * the parked value is the older read of the same field, and letting it land would undo an edit made in between.
+     * No token is written — the parked text carries them already, and the composer is putting that text back.
+     */
+    restoreStaged: (references: readonly MessageReference[]) => void;
+    /**
+     * Registered by a chat for as long as it is rendering this session's draft, so `refer` can tell the difference
+     * between a token nobody has written yet and one nobody ever will.
+     */
+    attachChat: () => () => void;
+    /** By key, never by index: what orders the references of a message is its text, and that is not this list. */
+    unstage: (key: string) => void;
+    clearStaged: () => void;
     /** What the tool running now last said about its own progress, for the row that is still spinning. */
     get progress(): (AgentProgressReport & {
         callId: string;

package/types/vendor/use-agentic/Reference.d.ts

@@ -0,0 +1,56 @@
+import type { MessageReference } from "./types.d.ts";
+/**
+ * The ceiling on what one reference may add to the transcript, and the identity two of them are the same by.
+ *
+ * A reference is bulkier than it looks and lasts longer than a tool result. The host hands over whatever the
+ * screen was already holding — a document with an array of rows in it is tens of kilobytes — and unlike a tool
+ * result, which answers one turn's question, a reference is part of a *user* message: it rides the wire on this
+ * turn and on every turn after it, and it is the last thing compaction folds, because folding the thing the user
+ * pointed at is folding the question.
+ *
+ * So the value is bounded where it is staged, before it ever enters a message. Clipped rather than dropped, and
+ * the note says which: a model shown a value it cannot see the end of asks a narrower question, where one shown
+ * nothing answers from the field names.
+ */
+export declare class Reference {
+    #private;
+    /**
+     * Characters. The same number as `ToolOutput.limit` and for the same reason — far below any provider's window,
+     * comfortably above what one record needs — but its own constant, because the two bound different things and a
+     * host that finds one too generous has no reason to have found the other so.
+     */
+    static readonly limit = 20000;
+    /**
+     * What the token in the message text spells, so the text is the index into the values and neither can drift
+     * from the other. A path is part of the identity: two fields of one document are two references.
+     */
+    static keyOf({ refName, refId, path }: MessageReference): string;
+    static same(one: MessageReference, other: MessageReference): boolean;
+    /**
+     * The token a reference reads as in the message the user is writing: `@[label](mention:refName/id#path)`.
+     *
+     * The text is the source of truth for which references a message carries — deleting the token is how somebody
+     * takes one back — so the token has to say everything the pointer does. The value is looked up beside it by key.
+     */
+    static token(reference: MessageReference): string;
+    /** Greedy on the label alone: a label may hold anything but `]`, and every other part is a name or an id. */
+    static readonly pattern: RegExp;
+    /**
+     * The pointers a draft names, in the order it names them. Pointers only — the value lives in `staged` and is
+     * joined on by key, so reading the text can never resurrect a value somebody deleted the token for.
+     */
+    static parse(text: string): MessageReference[];
+    /**
+     * A value past the ceiling becomes the JSON text up to it. That leaves `value` a string holding a fragment of a
+     * structure, which is exactly what it is — and a reader renders a string value as itself, so the model sees the
+     * fragment rather than an escaped quotation of one.
+     */
+    static clipped(reference: MessageReference): MessageReference;
+    /**
+     * The text with every token naming `key` taken out, and the gap it leaves closed up. Deleting the chip and
+     * deleting the token have to be the same act, because the text is what decides which references a turn carries.
+     */
+    static without(text: string, key: string): string;
+    /** What a pasted token resolves to: the pointer is in the text, and no value was ever staged beside it. */
+    static readonly unstagedNote = "the value was not captured with this reference, so read it again with a tool before answering about it";
+}

package/types/vendor/use-agentic/index.d.ts

@@ -7,6 +7,7 @@ export * from "./AgentScope.d.ts";
 export * from "./AgentSession.d.ts";
 export * from "./Compaction.d.ts";
 export * from "./httpRunner.d.ts";
+export * from "./Reference.d.ts";
 export * from "./sharedContext.d.ts";
 export * from "./surfaceContext.d.ts";
 export * from "./ToolOutput.d.ts";

package/types/vendor/use-agentic/types.d.ts

@@ -101,6 +101,12 @@ export interface ToolCallResult {
     changes?: ResourceDiff[];
     error?: string;
 }
+/**
+ * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn
+ * is incomplete — a truncated answer and a turn cut off before its tool call finished both arrive this way, and
+ * neither is distinguishable from `end` without it.
+ */
+export type TurnStop = "end" | "toolUse" | "length";
 /**
  * A file the user handed the conversation rather than the screen — which is why it rides a message instead of a
  * tool, the same reason `askUser` belongs to the session and not to the surface.
@@ -114,12 +120,6 @@ export interface ToolCallResult {
  * model cannot read and says so in the transcript, because a silently dropped file is one the model then
  * hallucinates about.
  */
-/**
- * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn
- * is incomplete — a truncated answer and a turn cut off before its tool call finished both arrive this way, and
- * neither is distinguishable from `end` without it.
- */
-export type TurnStop = "end" | "toolUse" | "length";
 export interface MessageAttachment {
     name: string;
     mimeType: string;
@@ -135,11 +135,41 @@ export interface MessageAttachment {
      */
     ref?: string;
 }
+/**
+ * Data the user pointed at while they were talking, rather than a file they handed over — a record, or one field
+ * of one, named in the message the way they named it. It rides a message for the same reason an attachment does:
+ * what somebody referred to while asking is part of the asking, and the turn context is rebuilt from the screen
+ * every turn, so a screen-shaped carrier forgets what was pointed at three turns ago.
+ *
+ * **`value` is a snapshot, deliberately.** It is what the data was when the user sent the message, and it is never
+ * re-read on a later turn. Re-reading would be wrong twice over: it rewrites what the person was looking at when
+ * they spoke, and the common case is an agent that then *edits* the very field it was pointed at, which would
+ * leave the reference showing the result and no record of what was being changed from. `refName`, `refId` and
+ * `path` are the way back to the current value — a tool re-reads it when the answer needs it.
+ *
+ * **`value` arrives masked, and nothing downstream can mask it again.** Masking needs the model class
+ * (`mask(model, value)`), which no wire carries, so whichever model the host names when it stages the reference is
+ * the whole of the decision about what leaves the browser.
+ */
+export interface MessageReference {
+    /** The host's own `refName`, unchanged — the vocabulary its published tools already speak. */
+    refName: string;
+    refId: string;
+    /** What the chip draws and what the token in the text spells, so the two can never disagree. */
+    label: string;
+    /** A dotted path into the document, in `pathSet`'s vocabulary. Absent means the whole of it. */
+    path?: string;
+    value?: unknown;
+    /** Read by the model in place of a value there is none of — clipped, unreadable, or gone from a restored chat. */
+    note?: string;
+}
 export interface ChatMessage {
     role: ChatRole;
     text?: string;
     /** Files the message carries. Content, not instructions — a backend frames them the way it frames context. */
     attachments?: MessageAttachment[];
+    /** Data the message points at. Content, framed like attachments and for the same reason. */
+    references?: MessageReference[];
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolCallResult[];
     /** A failed or capped turn, recorded in the transcript rather than thrown past it. */

package/ui/Agent/Bubble.tsx

@@ -5,6 +5,7 @@ import { type AgentProgressReport, AgentSession, type ChatMessage, type ToolCall
 import { createOverridable } from "../UiOverride";
 import { Chips } from "./Attach";
 import Markdown from "./Markdown";
+import { ReferenceChips } from "./Refer";
 import { tokenCount } from "./tokenCount";
 
 export interface BubbleProps {
@@ -150,6 +151,7 @@ const Content = ({ className, message, progress, results }: BubbleProps) => {
     return (
       <div className={cn("flex max-w-[85%] flex-col items-end gap-1 self-end", className)}>
         {message.attachments?.length ? <Chips attachments={message.attachments} className="justify-end" /> : null}
+        {message.references?.length ? <ReferenceChips className="justify-end" references={message.references} /> : null}
         {message.text ? (
           <p className="whitespace-pre-wrap rounded-box bg-primary/10 px-3 py-2 text-sm">{message.text}</p>
         ) : null}