@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/composer/extensions/FileReference.tsx

@@ -0,0 +1,55 @@
+import { IconFile, IconFolder } from "@tabler/icons-react";
+import { mergeAttributes, Node } from "@tiptap/core";
+import { NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
+
+const FileReferenceComponent = ({ node }: { node: any }) => {
+  const isFolder = node.attrs.path?.endsWith("/");
+  const cleanPath = isFolder ? node.attrs.path.slice(0, -1) : node.attrs.path;
+  const displayName = cleanPath.split("/").pop() || cleanPath;
+
+  return (
+    <NodeViewWrapper as="span" className="inline">
+      <span
+        className="inline-flex items-center gap-1 rounded-md border border-input bg-muted/50 px-1.5 py-0.5 text-xs font-medium text-foreground align-middle mx-0.5 max-w-[200px] select-none"
+        title={node.attrs.path}
+      >
+        {isFolder ? (
+          <IconFolder size={14} className="shrink-0 text-muted-foreground" />
+        ) : (
+          <IconFile size={14} className="shrink-0 text-muted-foreground" />
+        )}
+        <span className="truncate">{displayName}</span>
+      </span>
+    </NodeViewWrapper>
+  );
+};
+
+export const FileReference = Node.create({
+  name: "fileReference",
+  group: "inline",
+  inline: true,
+  selectable: true,
+  atom: true,
+
+  addAttributes() {
+    return {
+      path: { default: null },
+      source: { default: "codebase" },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-type="file-reference"]' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "span",
+      mergeAttributes({ "data-type": "file-reference" }, HTMLAttributes),
+    ];
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer(FileReferenceComponent);
+  },
+});

package/src/composer/extensions/MentionReference.tsx

@@ -0,0 +1,93 @@
+import {
+  IconFile,
+  IconFolder,
+  IconFileText,
+  IconCheckbox,
+  IconMail,
+  IconUser,
+  IconPresentation,
+  IconStack2,
+  IconMessageChatbot,
+} from "@tabler/icons-react";
+import { mergeAttributes, Node } from "@tiptap/core";
+import { NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
+
+const iconProps = { size: 14, className: "shrink-0 text-muted-foreground" };
+
+function MentionIcon({ icon }: { icon?: string }) {
+  switch (icon) {
+    case "folder":
+      return <IconFolder {...iconProps} />;
+    case "document":
+      return <IconFileText {...iconProps} />;
+    case "form":
+      return <IconCheckbox {...iconProps} />;
+    case "email":
+      return <IconMail {...iconProps} />;
+    case "user":
+      return <IconUser {...iconProps} />;
+    case "deck":
+      return <IconPresentation {...iconProps} />;
+    case "agent":
+      return <IconMessageChatbot {...iconProps} />;
+    case "file":
+      return <IconFile {...iconProps} />;
+    default:
+      return <IconStack2 {...iconProps} />;
+  }
+}
+
+const MentionReferenceComponent = ({ node }: { node: any }) => {
+  return (
+    <NodeViewWrapper as="span" className="inline">
+      <span
+        className="inline-flex items-center gap-1 rounded-md border border-input bg-muted/50 px-1.5 py-0.5 text-xs font-medium text-foreground align-middle mx-0.5 max-w-[200px] select-none"
+        title={node.attrs.refPath || node.attrs.refId || node.attrs.label}
+      >
+        <MentionIcon icon={node.attrs.icon} />
+        <span className="truncate">{node.attrs.label}</span>
+      </span>
+    </NodeViewWrapper>
+  );
+};
+
+export const MentionReference = Node.create({
+  name: "mentionReference",
+  group: "inline",
+  inline: true,
+  selectable: true,
+  atom: true,
+
+  addAttributes() {
+    return {
+      label: { default: null },
+      icon: { default: "file" },
+      source: { default: "" },
+      refType: { default: "file" },
+      refId: { default: null },
+      refPath: { default: null },
+      slotKey: { default: null },
+      slotLabel: { default: null },
+      metadata: { default: null },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-type="mention-reference"]' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "span",
+      mergeAttributes({ "data-type": "mention-reference" }, HTMLAttributes),
+    ];
+  },
+
+  renderText({ node }) {
+    return `@${node.attrs.label}`;
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer(MentionReferenceComponent);
+  },
+});

package/src/composer/extensions/SkillReference.tsx

@@ -0,0 +1,56 @@
+import { IconStack2 } from "@tabler/icons-react";
+import { mergeAttributes, Node } from "@tiptap/core";
+import { NodeViewWrapper, ReactNodeViewRenderer } from "@tiptap/react";
+
+const SkillReferenceComponent = ({ node }: { node: any }) => {
+  const displayName =
+    (node.attrs.name || node.attrs.path || "")
+      .replace(/^(\.agents?\/)?skills\//, "")
+      .replace(/\/SKILL\.md$/i, "")
+      .replace(/\.md$/i, "")
+      .split("/")
+      .pop() || "skill";
+
+  return (
+    <NodeViewWrapper as="span" className="inline">
+      <span
+        className="inline-flex items-center gap-1 rounded-md border border-input bg-muted/50 px-1.5 py-0.5 text-xs font-medium text-foreground align-middle mx-0.5 max-w-[160px] select-none"
+        title={node.attrs.path}
+      >
+        <IconStack2 size={14} className="shrink-0 text-muted-foreground" />
+        <span className="truncate">{displayName}</span>
+      </span>
+    </NodeViewWrapper>
+  );
+};
+
+export const SkillReference = Node.create({
+  name: "skillReference",
+  group: "inline",
+  inline: true,
+  selectable: true,
+  atom: true,
+
+  addAttributes() {
+    return {
+      name: { default: null },
+      path: { default: null },
+      source: { default: "codebase" },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-type="skill-reference"]' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "span",
+      mergeAttributes({ "data-type": "skill-reference" }, HTMLAttributes),
+    ];
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer(SkillReferenceComponent);
+  },
+});

package/src/composer/index.ts

@@ -0,0 +1,86 @@
+export { FileReference } from "./extensions/FileReference.js";
+export { SkillReference } from "./extensions/SkillReference.js";
+export { MentionReference } from "./extensions/MentionReference.js";
+export {
+  AgentComposerFrame,
+  type AgentComposerFrameProps,
+} from "./AgentComposerFrame.js";
+export {
+  TiptapComposer,
+  canSubmitComposerContent,
+  displayableComposerModeMessage,
+  getComposerSubmitIntentForEnterKey,
+  handleComposerFileDrop,
+  insertComposerHardBreakAndScrollIntoView,
+  type ComposerSubmitIntent,
+  type TiptapComposerHandle,
+  type TiptapComposerProps,
+  type TiptapComposerSubmitOptions,
+} from "./TiptapComposer.js";
+export {
+  isClaudeCodeAgentId,
+  isLunaModel,
+  resolvePreferredAgentModel,
+  type ComposerModelGroupLike,
+} from "./model-selection.js";
+export {
+  PromptComposer,
+  type PromptComposerProps,
+  type PromptComposerFile,
+  type PromptComposerSubmitOptions,
+} from "./PromptComposer.js";
+export type { ComposerTerminalModeControl } from "./ComposerPlusMenu.js";
+export {
+  RealtimeVoiceModeDock,
+  RealtimeVoiceModeEntry,
+  type RealtimeVoiceModeCopy,
+  type RealtimeVoiceModeDockProps,
+  type RealtimeVoiceModeEntryProps,
+  type RealtimeVoiceModeInlineSettings,
+  type RealtimeVoiceModeSelectSetting,
+  type RealtimeVoiceModeSettingOption,
+  type RealtimeVoiceModeState,
+} from "./RealtimeVoiceMode.js";
+export {
+  createRealtimeVoiceSession,
+  createRealtimeVoiceSessionWithCapability,
+  executeRealtimeVoiceTool,
+  extractRealtimeVoiceFunctionCalls,
+  readRealtimeVoiceContext,
+  readRealtimeVoiceContextWith,
+  RealtimeVoiceModeBoundary,
+  RealtimeVoiceModeProvider,
+  useRealtimeVoiceMode,
+  useRealtimeVoiceModeCopy,
+  useRealtimeVoiceModeOptional,
+  type RealtimeVoiceModeApi,
+  type RealtimeVoiceModeProviderProps,
+  type RealtimeVoiceSessionAnswer,
+  type RealtimeVoiceToolResult,
+} from "./useRealtimeVoiceMode.js";
+export {
+  AGENT_PROMPT_MAX_INLINE_IMAGE_BYTES,
+  AGENT_PROMPT_MAX_INLINE_TEXT_CHARS,
+  escapePromptAttachmentAttribute,
+  formatPromptWithAttachments,
+  isInlineableAgentPromptFile,
+  readAgentPromptAttachment,
+  type AgentPromptAttachment,
+  type ReadAgentPromptAttachmentOptions,
+} from "./prompt-attachments.js";
+export { MentionPopover } from "./MentionPopover.js";
+export { useMentionSearch } from "./use-mention-search.js";
+export {
+  ComposerRuntimeAdaptersProvider,
+  useComposerRuntimeAdapters,
+  type ComposerRuntimeAdapters,
+  type ComposerTranslate,
+} from "./runtime-adapters.js";
+export type {
+  AgentComposerLayoutVariant,
+  FileResult,
+  SkillResult,
+  MentionItem,
+  Reference,
+  SlashCommand,
+} from "./types.js";

package/src/composer/model-selection.spec.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  isClaudeCodeAgentId,
+  isLunaModel,
+  resolvePreferredAgentModel,
+} from "./model-selection.js";
+
+describe("composer agent model defaults", () => {
+  const groups = [
+    {
+      engine: "builder",
+      models: ["gpt-5-6-luna"],
+      configured: true,
+    },
+    {
+      engine: "builder",
+      models: ["claude-sonnet-5"],
+      configured: true,
+    },
+  ];
+
+  it("identifies Claude Code and Luna model ids", () => {
+    expect(isClaudeCodeAgentId("claude-code")).toBe(true);
+    expect(isClaudeCodeAgentId("claude-cli")).toBe(true);
+    expect(isClaudeCodeAgentId("codex")).toBe(false);
+    expect(isLunaModel("gpt-5.6-luna")).toBe(true);
+    expect(isLunaModel("openai/gpt-5.6-sol")).toBe(false);
+  });
+
+  it("defaults Claude Code to Sonnet and other agents to Luna", () => {
+    expect(resolvePreferredAgentModel("claude-code", groups)).toEqual({
+      engine: "builder",
+      model: "claude-sonnet-5",
+    });
+    expect(resolvePreferredAgentModel("codex", groups)).toEqual({
+      engine: "builder",
+      model: "gpt-5-6-luna",
+    });
+    expect(resolvePreferredAgentModel(undefined, groups)).toEqual({
+      engine: "builder",
+      model: "gpt-5-6-luna",
+    });
+  });
+});

package/src/composer/model-selection.ts

@@ -0,0 +1,51 @@
+export interface ComposerModelGroupLike {
+  engine: string;
+  models: readonly string[];
+  configured?: boolean;
+}
+
+export function isClaudeCodeAgentId(agentId: string | undefined): boolean {
+  return agentId === "claude-code" || agentId === "claude-cli";
+}
+
+export function isLunaModel(model: string): boolean {
+  return model.toLowerCase().includes("luna");
+}
+
+export function resolvePreferredAgentModel(
+  agentId: string | undefined,
+  groups: readonly ComposerModelGroupLike[],
+): { model: string; engine: string } | undefined {
+  const candidates = groups.flatMap((group) =>
+    group.models
+      .filter((model) => model !== "auto")
+      .map((model) => ({
+        model,
+        engine: group.engine,
+        configured: group.configured !== false,
+      })),
+  );
+  const orderedCandidates = [
+    ...candidates.filter((candidate) => candidate.configured),
+    ...candidates.filter((candidate) => !candidate.configured),
+  ];
+
+  if (isClaudeCodeAgentId(agentId)) {
+    const preferred =
+      orderedCandidates.find(
+        (candidate) =>
+          candidate.model.toLowerCase().includes("sonnet") &&
+          !isLunaModel(candidate.model),
+      ) ?? orderedCandidates.find((candidate) => !isLunaModel(candidate.model));
+    return preferred
+      ? { model: preferred.model, engine: preferred.engine }
+      : undefined;
+  }
+
+  const preferred = orderedCandidates.find((candidate) =>
+    isLunaModel(candidate.model),
+  );
+  return preferred
+    ? { model: preferred.model, engine: preferred.engine }
+    : undefined;
+}

package/src/composer/pasted-text.spec.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createPastedAttachmentFile,
+  isPastedTextAttachmentName,
+  readClipboardPaste,
+  shouldConvertClipboardToAttachment,
+  shouldConvertPasteToAttachment,
+  unwrapAttachmentEnvelope,
+  type ClipboardPaste,
+} from "./pasted-text.js";
+
+function clipboard(flavors: Record<string, string>): {
+  getData(type: string): string;
+} {
+  return { getData: (type: string) => flavors[type] ?? "" };
+}
+
+describe("shouldConvertPasteToAttachment", () => {
+  it("keeps a paragraph or two inline", () => {
+    const twoParagraphs = [
+      "This is a normal paragraph pasted into the composer. ".repeat(16),
+      "This is a second paragraph with enough words to feel real, but it is nowhere near a page of text. ".repeat(
+        10,
+      ),
+    ].join("\n\n");
+
+    expect(shouldConvertPasteToAttachment(twoParagraphs)).toBe(false);
+  });
+
+  it("keeps a basic bulleted list inline", () => {
+    const list = [
+      "- Confirm project scope",
+      "- Review current designs",
+      "- Check the edge cases",
+      "- Share implementation notes",
+      "- Follow up with QA",
+      "- Update release notes",
+      "- Coordinate rollout",
+      "- Watch for support reports",
+    ].join("\n");
+
+    expect(shouldConvertPasteToAttachment(list)).toBe(false);
+  });
+
+  it("converts roughly page-sized prose to an attachment", () => {
+    const pageOfText =
+      "This is source material for the agent to review. ".repeat(72);
+
+    expect(shouldConvertPasteToAttachment(pageOfText)).toBe(true);
+  });
+
+  it("converts page-length line-oriented text to an attachment", () => {
+    const pageOfLines = Array.from(
+      { length: 24 },
+      (_, index) =>
+        `${index + 1}. A full-page outline item with supporting detail.`,
+    ).join("\n");
+
+    expect(shouldConvertPasteToAttachment(pageOfLines)).toBe(true);
+  });
+
+  it("unwraps assistant-ui text attachment envelopes with attributes", () => {
+    expect(
+      unwrapAttachmentEnvelope(
+        '<attachment name="notes.txt" contentType="text/plain">\nLine one\nLine two\n</attachment>',
+      ),
+    ).toBe("Line one\nLine two");
+  });
+});
+
+describe("readClipboardPaste", () => {
+  it("returns both flavors when present", () => {
+    const paste = readClipboardPaste(
+      clipboard({ "text/plain": "hello", "text/html": "<p>hello</p>" }),
+    );
+    expect(paste.text).toBe("hello");
+    expect(paste.html).toBe("<p>hello</p>");
+  });
+
+  it("omits an empty html flavor", () => {
+    const paste = readClipboardPaste(
+      clipboard({ "text/plain": "hello", "text/html": "   " }),
+    );
+    expect(paste.html).toBeUndefined();
+  });
+
+  it("tolerates a missing DataTransfer", () => {
+    const paste = readClipboardPaste(null);
+    expect(paste.text).toBe("");
+    expect(paste.html).toBeUndefined();
+  });
+});
+
+const pageOfHtml = `<!doctype html>\n<html><body>${"<div>Product narrative section.</div>\n".repeat(
+  80,
+)}</body></html>`;
+
+describe("createPastedAttachmentFile", () => {
+  it("stores pasted HTML source as a real .html attachment", () => {
+    const paste: ClipboardPaste = { text: pageOfHtml };
+    const file = createPastedAttachmentFile(paste);
+    expect(file.name).toMatch(/^pasted-text-.*\.html$/);
+    expect(file.type).toBe("text/html");
+    expect(isPastedTextAttachmentName(file.name)).toBe(true);
+  });
+
+  it("keeps plain prose as a .txt attachment (no html flavor)", () => {
+    const file = createPastedAttachmentFile({
+      text: "This is just a long block of plain prose. ".repeat(80),
+    });
+    expect(file.name).toMatch(/^pasted-text-.*\.txt$/);
+    expect(file.type).toBe("text/plain");
+  });
+
+  it("does NOT promote code to html just because text/html carries highlight markup", () => {
+    // VS Code / editors put syntax-highlight <span> markup in text/html even
+    // though the real content (text/plain) is plain code. Keep it as .txt.
+    const code = "const x: number = 1;\n".repeat(200);
+    const highlightHtml = `<div style="color:#abb2bf">${"<span>const</span> <span>x</span>\n".repeat(
+      200,
+    )}</div>`;
+    const file = createPastedAttachmentFile({
+      text: code,
+      html: highlightHtml,
+    });
+    expect(file.name).toMatch(/\.txt$/);
+    expect(file.type).toBe("text/plain");
+  });
+
+  it("falls back to the html flavor when there is no usable plain text", () => {
+    const file = createPastedAttachmentFile({ text: "   ", html: pageOfHtml });
+    expect(file.name).toMatch(/\.html$/);
+    expect(file.type).toBe("text/html");
+  });
+
+  it("preserves the markup verbatim in the file body", async () => {
+    const file = createPastedAttachmentFile({ text: pageOfHtml });
+    expect(await file.text()).toBe(pageOfHtml);
+  });
+});
+
+describe("shouldConvertClipboardToAttachment", () => {
+  it("converts a page-sized HTML source paste", () => {
+    expect(shouldConvertClipboardToAttachment({ text: pageOfHtml })).toBe(true);
+  });
+
+  it("converts an html-only paste with an empty plain flavor", () => {
+    expect(
+      shouldConvertClipboardToAttachment({ text: "", html: pageOfHtml }),
+    ).toBe(true);
+  });
+
+  it("keeps a short paste inline even if it carries rich html", () => {
+    expect(
+      shouldConvertClipboardToAttachment({
+        text: "two words",
+        html: "<b>two</b> <i>words</i>",
+      }),
+    ).toBe(false);
+  });
+});