@runtypelabs/persona 4.7.0 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -62,6 +62,16 @@
       "import": "./dist/animations/wipe.js",
       "require": "./dist/animations/wipe.cjs"
     },
+    "./context-mentions": {
+      "types": "./dist/context-mentions.d.ts",
+      "import": "./dist/context-mentions.js",
+      "require": "./dist/context-mentions.cjs"
+    },
+    "./context-mentions-inline": {
+      "types": "./dist/context-mentions-inline.d.ts",
+      "import": "./dist/context-mentions-inline.js",
+      "require": "./dist/context-mentions-inline.cjs"
+    },
     "./widget.css": "./dist/widget.css"
   },
   "files": [
@@ -74,8 +84,7 @@
     "idiomorph": "^0.7.4",
     "lucide": "^1.18.0",
     "marked": "^12.0.2",
-    "partial-json": "^0.1.7",
-    "zod": "^3.22.4"
+    "partial-json": "^0.1.7"
   },
   "devDependencies": {
     "@size-limit/file": "^12.1.0",
@@ -121,7 +130,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf dist && pnpm run build:styles && pnpm run build:markdown-parsers && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:webmcp-polyfill && pnpm run build:runtype-tts && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:theme-editor-preview && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:voice-worklet-player && pnpm run build:plugin-kit && pnpm run build:animations && pnpm run check:dist-vite8",
+    "build": "rimraf dist && pnpm run build:styles && pnpm run build:markdown-parsers && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:webmcp-polyfill && pnpm run build:context-mentions && pnpm run build:context-mentions-inline && pnpm run build:runtype-tts && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:theme-editor-preview && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:voice-worklet-player && pnpm run build:plugin-kit && pnpm run build:animations && pnpm run check:dist-vite8",
     "check:dist-vite8": "node scripts/check-dist-no-in-for-init.mjs",
     "build:markdown-parsers": "tsup --config tsup.markdown-parsers.config.ts",
     "build:plugin-kit": "tsup src/plugin-kit.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
@@ -134,8 +143,10 @@
     "build:theme-ref": "tsup src/theme-reference.ts --format esm,cjs --minify --dts",
     "build:codegen": "tsup src/codegen.ts --format esm,cjs --minify --dts",
     "build:styles": "node scripts/build-styles.mjs",
-    "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" && tsup --config tsup.global.config.ts && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
+    "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" --external @runtypelabs/persona/context-mentions --external @runtypelabs/persona/context-mentions-inline && tsup --config tsup.global.config.ts && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
     "build:webmcp-polyfill": "tsup --config tsup.webmcp-polyfill.config.ts",
+    "build:context-mentions": "tsup --config tsup.context-mentions.config.ts",
+    "build:context-mentions-inline": "tsup --config tsup.context-mentions-inline.config.ts",
     "build:runtype-tts": "tsup --config tsup.runtype-tts.config.ts",
     "build:installer": "tsup src/install.ts --format iife --global-name SiteAgentInstaller --out-dir dist --minify --sourcemap --no-splitting",
     "build:launcher": "tsup src/launcher-global.ts --format iife --global-name AgentWidgetLauncher --minify --sourcemap --splitting false --out-dir dist && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/launcher-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/launcher'+ext);}\"",

package/src/artifacts-session.test.ts

@@ -77,4 +77,182 @@ describe("AgentWidgetSession artifacts", () => {
     expect(session.getArtifacts()).toHaveLength(1);
     expect(session.getArtifacts()[0].markdown).toBe("C");
   });
+
+  it("stores file metadata via applyArtifactStreamEvent and keeps accumulating deltas", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    const file = { path: "outputs/cat.html", mimeType: "text/html", language: "html" };
+    session.injectTestEvent({
+      type: "artifact_start",
+      id: "f1",
+      artifactType: "markdown",
+      title: "outputs/cat.html",
+      file
+    });
+    session.injectTestEvent({ type: "artifact_delta", id: "f1", artDelta: "```html\n" });
+    session.injectTestEvent({ type: "artifact_delta", id: "f1", artDelta: "<h1>hi</h1>\n```" });
+    const rec = session.getArtifactById("f1");
+    expect(rec?.file).toEqual(file);
+    expect(rec?.markdown).toBe("```html\n<h1>hi</h1>\n```");
+  });
+
+  it("upsertArtifact injects a card transcript block by default", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    const rec = session.upsertArtifact({
+      artifactType: "markdown",
+      title: "Doc",
+      content: "# Hi"
+    });
+    const block = session
+      .getMessages()
+      .find((m) => m.id === `artifact-ref-${rec.id}`);
+    expect(block).toBeDefined();
+    expect(block?.role).toBe("assistant");
+    const parsed = JSON.parse(block!.rawContent!);
+    expect(parsed.component).toBe("PersonaArtifactCard");
+    expect(parsed.props).toMatchObject({
+      artifactId: rec.id,
+      title: "Doc",
+      artifactType: "markdown",
+      status: "complete",
+      markdown: "# Hi"
+    });
+  });
+
+  it("upsertArtifact injects an inline block when display resolves to inline", () => {
+    const session = new AgentWidgetSession(
+      { features: { artifacts: { enabled: true, display: "inline" } } },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    const rec = session.upsertArtifact({
+      artifactType: "component",
+      title: "Chart",
+      component: "MyChart",
+      props: { series: [1, 2] }
+    });
+    const block = session
+      .getMessages()
+      .find((m) => m.id === `artifact-ref-${rec.id}`);
+    expect(block).toBeDefined();
+    const parsed = JSON.parse(block!.rawContent!);
+    expect(parsed.component).toBe("PersonaArtifactInline");
+    // Inline blocks render component artifacts through the registry, so the
+    // component name AND its props are embedded in the block props (the
+    // registry is not persisted, so hydration re-invokes the renderer from
+    // these).
+    expect(parsed.props.component).toBe("MyChart");
+    expect(parsed.props.componentProps).toEqual({ series: [1, 2] });
+    expect(parsed.props.status).toBe("complete");
+  });
+
+  it("upsertArtifact with transcript: false injects no transcript block", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    session.upsertArtifact({
+      id: "pane-only",
+      artifactType: "markdown",
+      content: "C",
+      transcript: false
+    });
+    expect(session.getArtifacts()).toHaveLength(1);
+    expect(session.getMessages()).toHaveLength(0);
+  });
+
+  it("upsertArtifact update to an existing artifact does not duplicate the block", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    session.upsertArtifact({ id: "a1", artifactType: "markdown", content: "v1" });
+    session.upsertArtifact({ id: "a1", artifactType: "markdown", content: "v2" });
+    const blocks = session
+      .getMessages()
+      .filter((m) => m.id === "artifact-ref-a1");
+    expect(blocks).toHaveLength(1);
+    expect(session.getArtifacts()).toHaveLength(1);
+    expect(session.getArtifactById("a1")?.markdown).toBe("v2");
+  });
+
+  it("upsertArtifact re-upsert rebuilds the existing block's persisted props", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    session.upsertArtifact({
+      id: "a1",
+      artifactType: "markdown",
+      title: "T1",
+      content: "v1"
+    });
+    session.upsertArtifact({
+      id: "a1",
+      artifactType: "markdown",
+      title: "T2",
+      content: "v2"
+    });
+    const blocks = session
+      .getMessages()
+      .filter((m) => m.id === "artifact-ref-a1");
+    expect(blocks).toHaveLength(1);
+    const parsed = JSON.parse(blocks[0].rawContent!);
+    expect(parsed.props.markdown).toBe("v2");
+    expect(parsed.props.title).toBe("T2");
+  });
+
+  it("stores file metadata via upsertArtifact", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    const file = { path: "notes.md", mimeType: "text/markdown" };
+    session.upsertArtifact({
+      artifactType: "markdown",
+      title: "notes.md",
+      content: "```md\n# Hi\n\n```",
+      file
+    });
+    expect(session.getArtifactById(session.getArtifacts()[0].id)?.file).toEqual(file);
+  });
 });

package/src/client.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { AgentWidgetClient, preferFinalStructuredContent } from './client';
-import { AgentWidgetEvent, AgentWidgetMessage } from './types';
+import { AgentWidgetEvent, AgentWidgetMessage, AgentWidgetArtifactsFeature } from './types';
 import { createJsonStreamParser } from './utils/formatting';
 import { VERSION } from './version';
 import { createUnifiedEventWrite } from './utils/__fixtures__/unified-translator.oracle';
@@ -4357,3 +4357,257 @@ describe('AgentWidgetClient - Wire event vocabulary (default in 4.0)', () => {
     }
   });
 });
+
+describe('AgentWidgetClient - Artifact file metadata', () => {
+  const artifactFrames = (fileField: string | null): string[] => [
+    `data: {"type":"artifact_start","id":"a1","artifactType":"markdown","title":"outputs/cat.html"${
+      fileField === null ? '' : ',"file":' + fileField
+    }}\n\n`,
+    `data: {"type":"artifact_delta","id":"a1","delta":${JSON.stringify('```html\n<h1>hi</h1>\n```')}}\n\n`,
+    `data: {"type":"artifact_complete","id":"a1"}\n\n`,
+  ];
+
+  it('propagates valid file metadata to the artifact_start event and card props', async () => {
+    global.fetch = createRawStreamFetch(
+      artifactFrames('{"path":"outputs/cat.html","mimeType":"text/html","language":"html"}')
+    );
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const startEv = events.find((e) => e.type === 'artifact_start');
+    expect(startEv).toBeDefined();
+    if (startEv?.type === 'artifact_start') {
+      expect(startEv.file).toEqual({
+        path: 'outputs/cat.html',
+        mimeType: 'text/html',
+        language: 'html',
+      });
+    }
+
+    // The completed card message carries the file metadata in its rawContent props.
+    const cardMsgs = events.filter(
+      (e): e is Extract<AgentWidgetEvent, { type: 'message' }> =>
+        e.type === 'message' && e.message.id === 'artifact-ref-a1'
+    );
+    const lastCard = cardMsgs[cardMsgs.length - 1];
+    expect(lastCard).toBeDefined();
+    const props = JSON.parse(lastCard.message.rawContent ?? '{}').props;
+    expect(props.status).toBe('complete');
+    expect(props.file).toEqual({
+      path: 'outputs/cat.html',
+      mimeType: 'text/html',
+      language: 'html',
+    });
+    expect(props.markdown).toBe('```html\n<h1>hi</h1>\n```');
+  });
+
+  it('drops malformed file metadata without error', async () => {
+    global.fetch = createRawStreamFetch(artifactFrames('{"path":123}'));
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+    const startEv = events.find((e) => e.type === 'artifact_start');
+    expect(startEv).toBeDefined();
+    if (startEv?.type === 'artifact_start') {
+      expect(startEv.file).toBeUndefined();
+    }
+    const cardMsgs = events.filter(
+      (e): e is Extract<AgentWidgetEvent, { type: 'message' }> =>
+        e.type === 'message' && e.message.id === 'artifact-ref-a1'
+    );
+    const props = JSON.parse(cardMsgs[cardMsgs.length - 1].message.rawContent ?? '{}').props;
+    expect(props.file).toBeUndefined();
+  });
+});
+
+describe('AgentWidgetClient - Artifact display modes', () => {
+  const markdownArtifactFrames = (id = 'a1'): string[] => [
+    `data: {"type":"artifact_start","id":"${id}","artifactType":"markdown","title":"Notes"}\n\n`,
+    `data: {"type":"artifact_delta","id":"${id}","delta":"# Hello"}\n\n`,
+    `data: {"type":"artifact_complete","id":"${id}"}\n\n`,
+  ];
+  const componentArtifactFrames = (id = 'c1'): string[] => [
+    `data: {"type":"artifact_start","id":"${id}","artifactType":"component","title":"Chart","component":"MyChart"}\n\n`,
+    `data: {"type":"artifact_complete","id":"${id}"}\n\n`,
+  ];
+
+  const dispatchAndCollect = async (
+    frames: string[],
+    artifacts?: AgentWidgetArtifactsFeature
+  ): Promise<AgentWidgetEvent[]> => {
+    global.fetch = createRawStreamFetch(frames);
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      ...(artifacts ? { features: { artifacts } } : {}),
+    });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+    return events;
+  };
+
+  const blockMessagesFor = (events: AgentWidgetEvent[], artifactId: string) =>
+    events.filter(
+      (e): e is Extract<AgentWidgetEvent, { type: 'message' }> =>
+        e.type === 'message' && e.message.id === `artifact-ref-${artifactId}`
+    );
+
+  const componentNameOf = (msg: AgentWidgetMessage): string =>
+    JSON.parse(msg.rawContent ?? '{}').component;
+
+  it('injects PersonaArtifactCard when display is unset (default "panel")', async () => {
+    const events = await dispatchAndCollect(markdownArtifactFrames());
+    const msgs = blockMessagesFor(events, 'a1');
+    expect(msgs.length).toBeGreaterThan(0);
+    for (const m of msgs) {
+      expect(componentNameOf(m.message)).toBe('PersonaArtifactCard');
+    }
+  });
+
+  it('injects PersonaArtifactCard for display: "card" and display: "panel"', async () => {
+    for (const mode of ['card', 'panel'] as const) {
+      const events = await dispatchAndCollect(markdownArtifactFrames(), {
+        enabled: true,
+        display: mode,
+      });
+      const msgs = blockMessagesFor(events, 'a1');
+      expect(msgs.length).toBeGreaterThan(0);
+      expect(componentNameOf(msgs[0].message)).toBe('PersonaArtifactCard');
+    }
+  });
+
+  it('injects PersonaArtifactInline for display: "inline"', async () => {
+    const events = await dispatchAndCollect(markdownArtifactFrames(), {
+      enabled: true,
+      display: 'inline',
+    });
+    const msgs = blockMessagesFor(events, 'a1');
+    expect(msgs.length).toBeGreaterThan(0);
+    for (const m of msgs) {
+      expect(componentNameOf(m.message)).toBe('PersonaArtifactInline');
+    }
+    const startProps = JSON.parse(msgs[0].message.rawContent ?? '{}').props;
+    expect(startProps).toMatchObject({
+      artifactId: 'a1',
+      artifactType: 'markdown',
+      status: 'streaming',
+    });
+  });
+
+  it('resolves the mode per artifact type via display.byType', async () => {
+    const display: AgentWidgetArtifactsFeature['display'] = {
+      default: 'card',
+      byType: { component: 'inline' },
+    };
+
+    const mdEvents = await dispatchAndCollect(markdownArtifactFrames(), {
+      enabled: true,
+      display,
+    });
+    expect(componentNameOf(blockMessagesFor(mdEvents, 'a1')[0].message)).toBe(
+      'PersonaArtifactCard'
+    );
+
+    const compEvents = await dispatchAndCollect(componentArtifactFrames(), {
+      enabled: true,
+      display,
+    });
+    const compMsgs = blockMessagesFor(compEvents, 'c1');
+    expect(componentNameOf(compMsgs[0].message)).toBe('PersonaArtifactInline');
+    // Inline component artifacts carry the component name for the preview registry.
+    expect(JSON.parse(compMsgs[0].message.rawContent ?? '{}').props.component).toBe('MyChart');
+  });
+
+  it('embeds accumulated markdown and complete status in inline block props on artifact_complete', async () => {
+    const events = await dispatchAndCollect(markdownArtifactFrames(), {
+      enabled: true,
+      display: 'inline',
+    });
+    const msgs = blockMessagesFor(events, 'a1');
+    const last = msgs[msgs.length - 1];
+    expect(last.message.streaming).toBe(false);
+    const props = JSON.parse(last.message.rawContent ?? '{}').props;
+    expect(props.status).toBe('complete');
+    expect(props.markdown).toBe('# Hello');
+  });
+});
+
+describe('AgentWidgetClient - mention context', () => {
+  const agentDone = (controller: ReadableStreamDefaultController, encoder: TextEncoder) => {
+    controller.enqueue(encoder.encode(sseEvent('agent_complete', {
+      executionId: 'exec_1',
+      agentId: 'agent_123',
+      success: true,
+      iterations: 1,
+      completedAt: new Date().toISOString(),
+      seq: 1,
+    })));
+    controller.close();
+  };
+
+  const captureContext = () => {
+    let capturedPayload: any = null;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: any) => {
+      capturedPayload = JSON.parse(options.body);
+      const encoder = new TextEncoder();
+      return {
+        ok: true,
+        body: new ReadableStream({ start(c) { agentDone(c, encoder); } }),
+      };
+    });
+    return () => capturedPayload;
+  };
+
+  it('attaches the latest user turn mention context under context.mentions', async () => {
+    const get = captureContext();
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000', agentId: 'agent_123' });
+
+    await client.dispatch({
+      messages: [{
+        id: 'u1', role: 'user', content: 'Summarize this',
+        createdAt: '2025-01-01T00:00:00.000Z',
+        mentionContext: { files: { app: { path: 'App.tsx' } } },
+      } as AgentWidgetMessage],
+    }, () => {});
+
+    expect(get().context).toEqual({ mentions: { files: { app: { path: 'App.tsx' } } } });
+  });
+
+  it('does NOT re-attach an older turn mention context on a later send', async () => {
+    const get = captureContext();
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000', agentId: 'agent_123' });
+
+    await client.dispatch({
+      messages: [
+        {
+          id: 'u1', role: 'user', content: 'Summarize this',
+          createdAt: '2025-01-01T00:00:00.000Z',
+          mentionContext: { files: { app: { path: 'App.tsx' } } },
+        } as AgentWidgetMessage,
+        {
+          id: 'a1', role: 'assistant', content: 'Done',
+          createdAt: '2025-01-01T00:00:01.000Z',
+        } as AgentWidgetMessage,
+        {
+          id: 'u2', role: 'user', content: 'Now a plain follow-up',
+          createdAt: '2025-01-01T00:00:02.000Z',
+        } as AgentWidgetMessage,
+      ],
+    }, () => {});
+
+    // The most recent user turn (u2) carried no mentionContext, so the stale
+    // context from u1 must not leak into this request.
+    expect(get().context).toBeUndefined();
+  });
+});