@runtypelabs/persona 4.8.0 → 4.10.0

package/src/session.mentions.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from "vitest";
+import { AgentWidgetSession } from "./session";
+import type {
+  AgentWidgetMessage,
+  AgentWidgetRequestPayload,
+  ContentPart,
+} from "./types";
+import type { MentionSubmitBundle } from "./context-mentions-entry";
+
+/** A closed, empty SSE stream so `dispatch` completes with no events. */
+function closedStream(): ReadableStream<Uint8Array> {
+  return new ReadableStream({ start: (c) => c.close() });
+}
+
+/**
+ * Regression coverage for the mention/command submit path:
+ * - an empty-text, chip-only submit must NOT render the "[Image]" fallback
+ *   (that fallback is for image-only turns);
+ * - a `command: "server"` mention's `resolve().context` must ride to the
+ *   backend under request `context.mentions` (the c1 dispatch channel).
+ */
+describe("AgentWidgetSession — mention/command submit", () => {
+  function makeSession(captured: { payload?: AgentWidgetRequestPayload }) {
+    let messages: AgentWidgetMessage[] = [];
+    let status = "idle";
+    let streaming = false;
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: "http://localhost:8000",
+        customFetch: async (_url, _init, payload) => {
+          captured.payload = payload;
+          return { ok: true, body: closedStream() } as unknown as Response;
+        },
+      },
+      {
+        onMessagesChanged: (m) => {
+          messages = m;
+        },
+        onStatusChanged: (s) => {
+          status = s;
+        },
+        onStreamingChanged: (s) => {
+          streaming = s;
+        },
+        onError: () => {},
+      }
+    );
+    return {
+      session,
+      user: () => messages.find((m) => m.role === "user"),
+      status: () => status,
+      streaming: () => streaming,
+    };
+  }
+
+  it("renders no [Image] fallback for a command-only submit and forwards context.mentions", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, user } = makeSession(captured);
+
+    // A server skill: `/lookup 1042` resolved to structured context, namespaced
+    // `{ [sourceId]: { [itemId]: context } }` exactly as the manager builds it.
+    const context = { commands: { lookup: { intent: "lookup-order", orderId: "1042" } } };
+    const refs = [{ sourceId: "commands", itemId: "lookup", label: "lookup" }];
+    const bundle: MentionSubmitBundle = {
+      blocks: [],
+      contentParts: [],
+      context,
+    };
+
+    await session.sendMessage("", {
+      mentions: {
+        refs,
+        finalize: async () => bundle,
+      },
+    });
+
+    const msg = user();
+    expect(msg).toBeDefined();
+    // The bug: an empty-text, mention-only submit used to display "[Image]".
+    expect(msg!.content).toBe("");
+    expect(msg!.content).not.toBe("[Image]");
+    // The command chip echoes immediately as a ref.
+    expect(msg!.contextMentions).toEqual(refs);
+    // Structured server-command data is merged onto the message…
+    expect(msg!.mentionContext).toEqual(context);
+    // …and rides to the backend under request `context.mentions`.
+    expect(captured.payload?.context).toMatchObject({ mentions: context });
+  });
+
+  it("merges resolved @-mention llmContent into the dispatched snapshot", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session } = makeSession(captured);
+
+    await session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: async (): Promise<MentionSubmitBundle> => ({
+          blocks: ["```App.tsx\nFILE BODY\n```"],
+          contentParts: [],
+          context: {},
+        }),
+      },
+    });
+
+    const dispatched = (captured.payload?.messages ?? []).find(
+      (m) => m.role === "user"
+    );
+    // The client collapses `llmContent` into the payload `content` field via the
+    // content-priority chain, so the model must see the resolved file body
+    // appended to the typed prose — not just the raw "summarize this".
+    const sent = dispatched?.content;
+    expect(typeof sent).toBe("string");
+    expect(sent as string).toContain("FILE BODY");
+    expect(sent as string).toContain("summarize this");
+    // Mention blocks lead; the typed prose lands last (joined by a blank line).
+    expect(sent as string).toBe("```App.tsx\nFILE BODY\n```\n\nsummarize this");
+  });
+
+  it("still renders the [Image] fallback for an image-only submit", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, user } = makeSession(captured);
+
+    const contentParts: ContentPart[] = [
+      { type: "image", image: "data:image/png;base64,abc123", mimeType: "image/png" },
+    ];
+    await session.sendMessage("", { contentParts });
+
+    expect(user()!.content).toBe("[Image]");
+  });
+
+  it("cancel() during a pending mention finalize aborts the turn without dispatching", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, status, streaming } = makeSession(captured);
+
+    let releaseFinalize!: (bundle: MentionSubmitBundle) => void;
+    const pending = new Promise<MentionSubmitBundle>((resolve) => {
+      releaseFinalize = resolve;
+    });
+
+    const sent = session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: () => pending,
+      },
+    });
+
+    // Stop mid-resolution, then let finalize settle: dispatch must not fire.
+    session.cancel();
+    releaseFinalize({ blocks: ["```App.tsx\nBODY\n```"], contentParts: [], context: {} });
+    await sent;
+
+    expect(captured.payload).toBeUndefined();
+    expect(status()).toBe("idle");
+    expect(streaming()).toBe(false);
+  });
+
+  it("dispatches a normal mention submit once finalize resolves", async () => {
+    const captured: { payload?: AgentWidgetRequestPayload } = {};
+    const { session, streaming } = makeSession(captured);
+
+    await session.sendMessage("summarize this", {
+      mentions: {
+        refs: [{ sourceId: "files", itemId: "app", label: "App.tsx" }],
+        finalize: async (): Promise<MentionSubmitBundle> => ({
+          blocks: ["```App.tsx\nBODY\n```"],
+          contentParts: [],
+          context: {},
+        }),
+      },
+    });
+
+    expect(captured.payload).toBeDefined();
+    expect(streaming()).toBe(false);
+  });
+});

package/src/session.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
 import { AgentWidgetSession, AgentWidgetSessionStatus } from './session';
-import { AgentWidgetMessage } from './types';
+import { AgentWidgetMessage, AgentWidgetContentSegment } from './types';
 
 describe('AgentWidgetSession - Message Injection', () => {
   let session: AgentWidgetSession;
@@ -369,6 +369,51 @@ describe('AgentWidgetSession - Message Injection', () => {
   });
 });
 
+describe('AgentWidgetSession - inline contentSegments', () => {
+  const originalFetch = global.fetch;
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  const makeHangingSession = () => {
+    // A never-settling fetch keeps the turn in-flight so the appended user
+    // message can be inspected without a dispatch-error bubble replacing it.
+    global.fetch = vi.fn().mockImplementation(() => new Promise(() => {}));
+    return new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+  };
+
+  it('stores ordered contentSegments on the sent user message', () => {
+    const session = makeHangingSession();
+    const segments: AgentWidgetContentSegment[] = [
+      { kind: 'text', text: 'Check ' },
+      { kind: 'mention', ref: { sourceId: 'files', itemId: 'app', label: 'App.tsx' } },
+      { kind: 'text', text: ' please' },
+    ];
+    void session.sendMessage('Check @App.tsx please', {
+      contentSegments: segments,
+    });
+    const userMsg = session.getMessages().find((m) => m.role === 'user');
+    // Segments must land on the stored (sequence-normalized) copy, not just the
+    // orphaned input literal — this is the fix for the dead inline-token branch.
+    expect(userMsg?.contentSegments).toEqual(segments);
+  });
+
+  it('omits contentSegments for a plain message', () => {
+    const session = makeHangingSession();
+    void session.sendMessage('plain message');
+    const userMsg = session.getMessages().find((m) => m.role === 'user');
+    expect(userMsg?.contentSegments).toBeUndefined();
+  });
+});
+
 describe('AgentWidgetSession - cancel()', () => {
   const originalFetch = global.fetch;
 
@@ -404,9 +449,12 @@ describe('AgentWidgetSession - cancel()', () => {
 
     // Kick off the dispatch but don't await: we want it in-flight when we cancel.
     const dispatchPromise = session.sendMessage('Hello');
-    // Let the session set up the AbortController and call fetch.
-    await Promise.resolve();
-    await Promise.resolve();
+    // Drain microtasks until the session has set up the AbortController and
+    // called fetch (payload building is async, so the exact tick count is not a
+    // contract — wait for the observable effect instead).
+    for (let i = 0; i < 20 && capturedSignal === null; i++) {
+      await Promise.resolve();
+    }
 
     expect(streaming).toBe(true);
     expect(session.isStreaming()).toBe(true);

package/src/session.ts

@@ -27,7 +27,7 @@ import {
   generateUserMessageId,
   generateAssistantMessageId
 } from "./utils/message-id";
-import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "./utils/content";
+import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT, createTextPart, hasImages } from "./utils/content";
 import {
   buildArtifactRefRawContent,
   resolveArtifactDisplayMode
@@ -37,8 +37,11 @@ import type {
   VoiceStatus,
   VoiceConfig,
   ReadAloudState,
-  SpeechEngine
+  SpeechEngine,
+  AgentWidgetContentSegment,
+  AgentWidgetContextMentionRef
 } from "./types";
+import type { MentionSubmitBundle } from "./utils/context-mention-manager";
 import {
   createVoiceProvider,
   isVoiceSupported,
@@ -1129,17 +1132,92 @@ export class AgentWidgetSession {
     });
   }
 
+  /**
+   * Resolve the gathered mentions and merge them into the user message's
+   * model-visible content. Default path is `llmAppend` → `llmContent` (or a text
+   * `contentPart` when parts are present, since `contentParts` wins the priority
+   * chain); the opt-in structured `context` lands on `mentionContext` for the
+   * client to namespace into the request `context`. Failures were already
+   * dropped by `finalize()`.
+   */
+  private async applyMentionBundle(
+    userMessage: AgentWidgetMessage,
+    typedText: string,
+    finalize: () => Promise<MentionSubmitBundle>
+  ): Promise<void> {
+    let bundle: MentionSubmitBundle;
+    try {
+      bundle = await finalize();
+    } catch {
+      return; // resolution failed entirely; send the typed text as-is
+    }
+
+    // Blocks arrive pre-formatted from the mention layer (fenced/document/custom
+    // per `contextMentions.llmFormat`); the session just joins them and appends
+    // the typed prose last.
+    const block = bundle.blocks.join("\n\n");
+    const llmText = [block, typedText].filter(Boolean).join("\n\n");
+
+    const hasAttachments =
+      Array.isArray(userMessage.contentParts) &&
+      userMessage.contentParts.length > 0;
+    const hasMentionParts = bundle.contentParts.length > 0;
+
+    if (hasAttachments) {
+      // The typed text already rides as a content part; add the block + mention
+      // parts ahead of the existing attachment parts (mentions first).
+      const parts: ContentPart[] = [];
+      if (block) parts.push(createTextPart(block));
+      parts.push(...bundle.contentParts);
+      parts.push(...userMessage.contentParts!);
+      userMessage.contentParts = parts;
+    } else if (hasMentionParts) {
+      const parts: ContentPart[] = [];
+      if (llmText) parts.push(createTextPart(llmText));
+      parts.push(...bundle.contentParts);
+      userMessage.contentParts = parts;
+    } else if (block) {
+      userMessage.llmContent = llmText;
+    }
+
+    if (Object.keys(bundle.context).length > 0) {
+      userMessage.mentionContext = bundle.context;
+    }
+  }
+
   public async sendMessage(
     rawInput: string,
     options?: {
       viaVoice?: boolean;
       /** Multi-modal content parts (e.g., images) to include with the message */
       contentParts?: ContentPart[];
+      /**
+       * Context mentions gathered from the composer. `refs` echo immediately as
+       * chips; `finalize()` resolves any pending/submit sources just before
+       * dispatch (after the instant echo) and the bundle is merged into this
+       * message's model-visible content.
+       */
+      mentions?: {
+        refs: AgentWidgetContextMentionRef[];
+        finalize: () => Promise<MentionSubmitBundle>;
+      };
+      /**
+       * Ordered prose + mention segments for inline-mode display (`display:
+       * "inline"`). Stored on the user message so its bubble re-renders `@tokens`
+       * in place (and suppresses the chip row). Display/transcript only — the
+       * model still sees resolved bodies via the `mentions` bundle above.
+       */
+      contentSegments?: AgentWidgetContentSegment[];
     }
   ) {
     const input = rawInput.trim();
-    // Allow sending if there's text OR attachments
-    if (!input && (!options?.contentParts || options.contentParts.length === 0)) return;
+    // Allow sending if there's text OR attachments OR mentions
+    if (
+      !input &&
+      (!options?.contentParts || options.contentParts.length === 0) &&
+      (!options?.mentions || options.mentions.refs.length === 0)
+    )
+      return;
 
     this.stopSpeaking();
     this.abortController?.abort();
@@ -1160,25 +1238,63 @@ export class AgentWidgetSession {
     // the proxy path auto-generates a different id than `assistantMessageId`.
     this.activeAssistantMessageId = null;
 
+    // Fallback display text ONLY when the sole content is image attachments.
+    // A mention/command-only submit (empty text + a chip) must NOT read as
+    // "[Image]"; it renders its chips with empty text instead.
+    const imageOnlyFallback =
+      options?.contentParts && hasImages(options.contentParts)
+        ? IMAGE_ONLY_MESSAGE_FALLBACK_TEXT
+        : "";
+
     const userMessage: AgentWidgetMessage = {
       id: userMessageId,
       role: "user",
-      content: input || IMAGE_ONLY_MESSAGE_FALLBACK_TEXT, // Display text (fallback if only images)
+      content: input || imageOnlyFallback, // Display text (fallback if only images)
       createdAt: new Date().toISOString(),
       sequence: this.nextSequence(),
       viaVoice: options?.viaVoice || false,
       // Include contentParts if provided (for multi-modal messages)
       ...(options?.contentParts && options.contentParts.length > 0 && {
         contentParts: options.contentParts
+      }),
+      // Echo mention chips immediately (refs only; payloads merged below).
+      ...(options?.mentions && options.mentions.refs.length > 0 && {
+        contextMentions: options.mentions.refs
+      }),
+      // Inline mode: ordered display segments for in-prose `@token` rendering.
+      ...(options?.contentSegments && options.contentSegments.length > 0 && {
+        contentSegments: options.contentSegments
       })
     };
 
     this.appendMessage(userMessage);
     this.setStreaming(true);
 
+    // Assign the fresh controller BEFORE the mention await so cancel() (or a
+    // superseding sendMessage) during finalize() aborts THIS turn, not a stale
+    // prior controller.
     const controller = new AbortController();
     this.abortController = controller;
 
+    // Resolve + merge mentions AFTER the instant echo but BEFORE dispatch, so
+    // the model sees the context while the user's bubble already rendered.
+    // `appendMessage` stores a sequence-normalized COPY (see `ensureSequence`),
+    // so mutate THAT live reference — not the orphaned `userMessage` literal —
+    // or the merged `llmContent`/`contentParts`/`mentionContext` never reach the
+    // dispatch snapshot below. Re-emit so any merged parts also reach the UI.
+    if (options?.mentions) {
+      const stored =
+        this.messages.find((m) => m.id === userMessageId) ?? userMessage;
+      await this.applyMentionBundle(stored, input, options.mentions.finalize);
+      // A cancel() or new sendMessage during finalize aborted this controller
+      // (and replaced/nulled the shared ref). Bail without dispatching and
+      // leave whatever idle/streaming state that caller already set.
+      if (controller.signal.aborted || this.abortController !== controller) {
+        return;
+      }
+      this.callbacks.onMessagesChanged([...this.messages]);
+    }
+
     const snapshot = [...this.messages];
 
     try {

package/src/smart-dom-reader.test.ts

@@ -4,10 +4,11 @@
 // vendored library under jsdom. The pure-mapper correctness guarantee lives in
 // utils/smart-dom-adapter.test.ts (no DOM, no library); this test confirms the
 // vendored runtime loads and the provider wires up against a real document.
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import {
   collectSmartDomContext,
-  createSmartDomReaderContextProvider
+  createSmartDomReaderContextProvider,
+  createSmartDomMentionSource
 } from "./smart-dom-reader";
 
 // jsdom implements no layout, so getBoundingClientRect()/offsetParent report the
@@ -116,6 +117,66 @@ describe("smart-dom-reader entry (jsdom)", () => {
     expect(texts).toContain("Scoped shadow action");
   });
 
+  it("mention source surfaces page elements as items and resolves text at submit", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+    const source = createSmartDomMentionSource({ label: "Page", ...JSDOM_OPTS });
+    expect(source.id).toBe("page");
+    expect(source.resolveOn).toBe("submit");
+
+    const items = await source.search("", { messages: [], config: {} as never, signal: new AbortController().signal });
+    const go = items.find((i) => i.label.includes("Continue"));
+    expect(go).toBeTruthy();
+    expect(go!.id).toMatch(/#go|go/); // selector is the item id
+
+    // Filtering narrows the snapshot client-side.
+    const filtered = await source.search("checkout", { messages: [], config: {} as never, signal: new AbortController().signal });
+    expect(filtered.some((i) => i.label.includes("Continue"))).toBe(true);
+
+    // resolve() reads the live element text at submit.
+    const payload = await source.resolve(go!, {
+      messages: [],
+      config: {} as never,
+      composerText: "",
+      args: "",
+      signal: new AbortController().signal,
+    });
+    expect(payload.llmAppend).toContain("Continue to checkout");
+    expect(payload.context).toMatchObject({ selector: go!.id });
+  });
+
+  it("applies mapItem to reshape surfaced items without breaking resolve", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+    const source = createSmartDomMentionSource({
+      label: "Page",
+      ...JSDOM_OPTS,
+      mapItem: (el, defaultItem) => ({
+        ...defaultItem,
+        iconName: "star",
+        description: `custom:${el.tagName}`,
+      }),
+    });
+
+    const items = await source.search("", {
+      messages: [],
+      config: {} as never,
+      signal: new AbortController().signal,
+    });
+    const go = items.find((i) => i.label.includes("Continue"));
+    expect(go).toBeTruthy();
+    expect(go!.iconName).toBe("star");
+    expect(go!.description).toMatch(/^custom:/i);
+
+    // id stays the selector, so submit-time resolve still reads the live element.
+    const payload = await source.resolve(go!, {
+      messages: [],
+      config: {} as never,
+      composerText: "",
+      args: "",
+      signal: new AbortController().signal,
+    });
+    expect(payload.llmAppend).toContain("Continue to checkout");
+  });
+
   it("provider returns formatted context under the configured key", async () => {
     document.body.innerHTML = `<main><button id="go">Continue</button></main>`;
     const provider = createSmartDomReaderContextProvider({
@@ -132,4 +193,70 @@ describe("smart-dom-reader entry (jsdom)", () => {
     document.body.innerHTML = "";
     expect(collectSmartDomContext(JSDOM_OPTS)).toEqual([]);
   });
+
+  const searchCtx = () => ({
+    messages: [],
+    config: {} as never,
+    signal: new AbortController().signal,
+  });
+
+  it("reuses the snapshot across empty-query searches within the TTL (scans once)", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+    const source = createSmartDomMentionSource({ label: "Page", ...JSDOM_OPTS });
+
+    // Count extractions by observing DOM reads: a spy on querySelectorAll fires
+    // per scan. Simpler and TTL-independent: mutate the DOM between the two empty
+    // searches and assert the second still returns the pre-mutation snapshot.
+    const first = await source.search("", searchCtx());
+    expect(first.some((i) => i.label.includes("Continue"))).toBe(true);
+
+    // Change the page; a rescan would surface the new element.
+    document.body.innerHTML = `<main><button id="new">Brand new action</button></main>`;
+    const second = await source.search("", searchCtx());
+    // Still the cached snapshot: no rescan happened within the TTL.
+    expect(second.some((i) => i.label.includes("Continue"))).toBe(true);
+    expect(second.some((i) => i.label.includes("Brand new"))).toBe(false);
+  });
+
+  it("rescans on an empty query once the TTL has elapsed", async () => {
+    vi.useFakeTimers();
+    try {
+      document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+      const source = createSmartDomMentionSource({ label: "Page", ...JSDOM_OPTS });
+
+      const first = await source.search("", searchCtx());
+      expect(first.some((i) => i.label.includes("Continue"))).toBe(true);
+
+      // Mutate the page, then advance past the 2s TTL so the next empty query rescans.
+      document.body.innerHTML = `<main><button id="new">Brand new action</button></main>`;
+      vi.advanceTimersByTime(2500);
+
+      const second = await source.search("", searchCtx());
+      expect(second.some((i) => i.label.includes("Brand new"))).toBe(true);
+      expect(second.some((i) => i.label.includes("Continue"))).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("resolves an item from a cached snapshot against the live element", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue to checkout</button></main>`;
+    const source = createSmartDomMentionSource({ label: "Page", ...JSDOM_OPTS });
+
+    // Prime the snapshot, then re-search (cached) to get the item without rescanning.
+    await source.search("", searchCtx());
+    const items = await source.search("checkout", searchCtx());
+    const go = items.find((i) => i.label.includes("Continue"));
+    expect(go).toBeTruthy();
+
+    const payload = await source.resolve(go!, {
+      messages: [],
+      config: {} as never,
+      composerText: "",
+      args: "",
+      signal: new AbortController().signal,
+    });
+    expect(payload.llmAppend).toContain("Continue to checkout");
+    expect(payload.context).toMatchObject({ selector: go!.id });
+  });
 });