akanjs 3.0.0-beta.7 → 3.0.0-beta.8

package/vendor/use-agentic/AgentSession.ts

@@ -1,5 +1,6 @@
 import type { AgentProgressReport } from "./AgentProgress";
 import { Compaction, type CompactOptions } from "./Compaction";
+import { Reference } from "./Reference";
 import { ToolOutput } from "./ToolOutput";
 import { type ToolApprovalRequest, ToolRunner } from "./ToolRunner";
 import { Transcript } from "./Transcript";
@@ -7,6 +8,7 @@ import type {
   AgentRunner,
   ChatMessage,
   ContextBlock,
+  MessageReference,
   PublishedTool,
   RunnerRequest,
   SurfaceView,
@@ -132,6 +134,9 @@ export class AgentSession {
   #running = false;
   #pending: PendingApproval | null = null;
   #question: PendingQuestion | null = null;
+  #staged: MessageReference[] = [];
+  #inserts: MessageReference[] = [];
+  #chats = 0;
   #progress: (AgentProgressReport & { callId: string }) | null = null;
   #controller: AbortController | null = null;
   #active: Promise<void> | null = null;
@@ -212,6 +217,117 @@ export class AgentSession {
     return this.#question;
   }
 
+  /**
+   * 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[] {
+    return this.#staged;
+  }
+
+  /**
+   * 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) => {
+    this.#stage(Reference.clipped(reference));
+    this.#announce();
+  };
+
+  /**
+   * 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) => {
+    const clipped = Reference.clipped(reference);
+    this.#stage(clipped);
+    if (this.#chats) this.#inserts = [...this.#inserts.filter((one) => !Reference.same(one, clipped)), clipped];
+    else
+      console.warn(
+        `No chat is rendering this agent session, so "${clipped.label}" was staged with no token written for it. ` +
+          "The component calling this and an <Agent.Chat /> have to share one session — check which <Agent.Zone> " +
+          "each of them is inside.",
+      );
+    this.#announce();
+  };
+
+  /**
+   * 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[] {
+    return this.#inserts;
+  }
+
+  /** Idempotent by key: the second chat to apply the same insert is acknowledging one that is already gone. */
+  insertApplied = (key: string) => {
+    const next = this.#inserts.filter((one) => Reference.keyOf(one) !== key);
+    if (next.length === this.#inserts.length) return;
+    this.#inserts = next;
+    this.#announce();
+  };
+
+  /**
+   * 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[]) => {
+    const fresh = references.filter((one) => !this.#staged.some((held) => Reference.same(held, one)));
+    if (!fresh.length) return;
+    this.#staged = [...fresh.map((one) => Reference.clipped(one)), ...this.#staged];
+    this.#announce();
+  };
+
+  /**
+   * 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 = () => {
+    this.#chats += 1;
+    return () => {
+      this.#chats = Math.max(0, this.#chats - 1);
+    };
+  };
+
+  #stage(clipped: MessageReference) {
+    const at = this.#staged.findIndex((one) => Reference.same(one, clipped));
+    this.#staged =
+      at === -1 ? [...this.#staged, clipped] : this.#staged.map((one, idx) => (idx === at ? clipped : one));
+  }
+
+  /** By key, never by index: what orders the references of a message is its text, and that is not this list. */
+  unstage = (key: string) => {
+    const next = this.#staged.filter((one) => Reference.keyOf(one) !== key);
+    if (next.length === this.#staged.length) return;
+    this.#staged = next;
+    this.#announce();
+  };
+
+  clearStaged = () => {
+    if (!this.#staged.length && !this.#inserts.length) return;
+    this.#staged = [];
+    this.#inserts = [];
+    this.#announce();
+  };
+
   /** What the tool running now last said about its own progress, for the row that is still spinning. */
   get progress(): (AgentProgressReport & { callId: string }) | null {
     return this.#progress;
@@ -315,6 +431,8 @@ export class AgentSession {
       await this.#active;
     }
     this.#messages = [];
+    this.#staged = [];
+    this.#inserts = [];
     this.#compactFloor = 0;
     
     if (this.#saveTimer) {
@@ -631,9 +749,17 @@ export class AgentSession {
   }
 
   #notify() {
+    this.#announce();
+    this.#schedulePersist();
+  }
+
+  /**
+   * A change that is not the transcript's. Staged references live beside the messages rather than in them, so
+   * announcing one has to redraw the composer without scheduling a save of messages nothing touched.
+   */
+  #announce() {
     this.#version += 1;
     for (const listener of this.#listeners) listener();
-    this.#schedulePersist();
   }
 
   /** Debounced: streaming patches the last message on every delta, and a save per delta would thrash storage. */

package/vendor/use-agentic/Compaction.ts

@@ -103,6 +103,12 @@ export class Compaction {
 
     for (const attachment of message.attachments ?? [])
       parts.push(`[attached ${attachment.name}, content not carried into this summary]`);
+
+    for (const reference of message.references ?? [])
+      parts.push(
+        `[referenced ${reference.refName}/${reference.refId}${reference.path ? `#${reference.path}` : ""}` +
+          ` (${reference.label}), value not carried into this summary]`,
+      );
     for (const call of message.toolCalls ?? [])
       parts.push(`[called ${call.name} ${Compaction.#clip(JSON.stringify(call.args), 200)}]`);
     for (const result of message.toolResults ?? [])

package/vendor/use-agentic/Reference.ts

@@ -0,0 +1,99 @@
+import type { MessageReference } from "./types";
+
+/**
+ * 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 class Reference {
+  /**
+   * 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 = 20_000;
+
+  /**
+   * 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 {
+    return `${refName}/${refId}${path ? `#${path}` : ""}`;
+  }
+
+  static same(one: MessageReference, other: MessageReference): boolean {
+    return Reference.keyOf(one) === Reference.keyOf(other);
+  }
+
+  /**
+   * 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 {
+    return `@[${reference.label}](mention:${Reference.keyOf(reference)})`;
+  }
+
+  /** Greedy on the label alone: a label may hold anything but `]`, and every other part is a name or an id. */
+  static readonly pattern = /@\[([^\]]*)\]\(mention:([^/)]+)\/([^#)]+)(?:#([^)]*))?\)/g;
+
+  /**
+   * 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[] {
+    return [...text.matchAll(Reference.pattern)].map(([, label, refName, refId, path]) => ({
+      refName,
+      refId,
+      label,
+      ...(path ? { path } : {}),
+    }));
+  }
+
+  /**
+   * 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 {
+    if (reference.value === undefined) return reference;
+    const json = JSON.stringify(reference.value) ?? "";
+    if (json.length <= Reference.limit) return reference;
+    return { ...reference, value: `${json.slice(0, Reference.limit)}…`, note: Reference.#note(json.length) };
+  }
+
+  /**
+   * 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 {
+    return text
+      .replace(new RegExp(Reference.pattern.source, "g"), (match, label, refName, refId, path) =>
+        Reference.keyOf({ refName, refId, label, path }) === key ? "" : match,
+      )
+      .replace(/[^\S\n]{2,}/g, " ")
+      .replace(/[^\S\n]+$/gm, "");
+  }
+
+  /** 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";
+
+  static #note(chars: number): string {
+    return (
+      `The value is ${chars} characters (~${Math.ceil(chars / 4)} tokens), past the ${Reference.limit}-character ` +
+      `ceiling one reference may add to this conversation, so only the first ${Reference.limit} are shown and the ` +
+      `JSON is cut mid-structure. Read a narrower part of it with a tool — one row, one field — rather than asking ` +
+      `for the whole value, and tell the user if you cannot answer from what you can see.`
+    );
+  }
+}

package/vendor/use-agentic/Transcript.ts

@@ -45,6 +45,12 @@ export class Transcript {
 
   /** An empty assistant message is a draft a reload or an abort caught before it said anything. */
   static carries(message: ChatMessage) {
-    return !!message.text || !!message.error || !!message.toolCalls?.length || !!message.attachments?.length;
+    return (
+      !!message.text ||
+      !!message.error ||
+      !!message.toolCalls?.length ||
+      !!message.attachments?.length ||
+      !!message.references?.length
+    );
   }
 }

package/vendor/use-agentic/index.ts

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

package/vendor/use-agentic/types.ts

@@ -118,6 +118,13 @@ export interface ToolCallResult {
   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.
@@ -131,13 +138,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;
@@ -154,11 +154,42 @@ 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. */