@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/composer/runtime-adapters.spec.tsx

@@ -0,0 +1,102 @@
+// @vitest-environment happy-dom
+
+import React, { act, useEffect } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  ComposerRuntimeAdaptersProvider,
+  useComposerRuntimeAdapters,
+  type ComposerRuntimeAdapters,
+} from "./runtime-adapters.js";
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+describe("ComposerRuntimeAdaptersProvider", () => {
+  it("interpolates fallback translations without a provider", () => {
+    let translated = "";
+
+    function Consumer() {
+      const runtime = useComposerRuntimeAdapters();
+      translated = runtime.translate!("attachment.tooLarge", {
+        defaultValue: '"{{name}}" is {{size}} MB (max {{maxSize}} MB)',
+        name: "report.pdf",
+        size: 12.5,
+        maxSize: 10,
+      });
+      return null;
+    }
+
+    act(() => root.render(<Consumer />));
+
+    expect(translated).toBe('"report.pdf" is 12.5 MB (max 10 MB)');
+  });
+
+  it("keeps the context value stable so consumer effects do not refire", () => {
+    const readAppState = vi.fn(() => undefined);
+    const adapters: ComposerRuntimeAdapters = { voice: { readAppState } };
+    const seen: ComposerRuntimeAdapters[] = [];
+
+    function Consumer() {
+      const runtime = useComposerRuntimeAdapters();
+      seen.push(runtime);
+      // Mirrors VoiceButton's voice-input-preference read.
+      useEffect(() => {
+        void runtime.voice!.readAppState!("voice-input-preference");
+      }, [runtime]);
+      return null;
+    }
+
+    function Tree({ tick }: { tick: number }) {
+      return (
+        <ComposerRuntimeAdaptersProvider adapters={adapters}>
+          <span>{tick}</span>
+          <Consumer />
+        </ComposerRuntimeAdaptersProvider>
+      );
+    }
+
+    act(() => root.render(<Tree tick={0} />));
+    act(() => root.render(<Tree tick={1} />));
+    act(() => root.render(<Tree tick={2} />));
+
+    expect(seen.length).toBeGreaterThan(1);
+    expect(new Set(seen).size).toBe(1);
+    expect(readAppState).toHaveBeenCalledTimes(1);
+  });
+
+  it("rebuilds the context value when the adapters prop changes", () => {
+    const seen: ComposerRuntimeAdapters[] = [];
+
+    function Consumer() {
+      seen.push(useComposerRuntimeAdapters());
+      return null;
+    }
+
+    const render = (adapters: ComposerRuntimeAdapters) =>
+      act(() =>
+        root.render(
+          <ComposerRuntimeAdaptersProvider adapters={adapters}>
+            <Consumer />
+          </ComposerRuntimeAdaptersProvider>,
+        ),
+      );
+
+    render({ resolvePath: (path) => `/a${path}` });
+    render({ resolvePath: (path) => `/b${path}` });
+
+    expect(seen.at(-1)!.resolvePath!("/x")).toBe("/b/x");
+  });
+});

package/src/composer/runtime-adapters.tsx

@@ -0,0 +1,364 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+
+export type ComposerTranslate = (
+  key: string,
+  options?: Record<string, unknown>,
+) => string;
+
+export type ReasoningEffort =
+  | "auto"
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max";
+
+export interface EngineModelGroup {
+  engine: string;
+  label: string;
+  models: string[];
+  configured: boolean;
+  /** Provider-owned connection state shown at the far edge of the row. */
+  statusLabel?: string;
+  /** Marks a configured local subscription so setup CTAs can stay hidden. */
+  isSubscription?: boolean;
+}
+
+export interface ComposerModelState {
+  selectedModel: string;
+  selectedEngine: string;
+  selectedEffort: ReasoningEffort;
+  availableModels: EngineModelGroup[];
+  isLoading: boolean;
+  onModelChange: (model: string, engine: string) => void;
+  onEffortChange: (effort: ReasoningEffort) => void;
+}
+
+export interface ComposerBuilderConnectFlow {
+  hasFetchedStatus: boolean;
+  configured: boolean;
+  envManaged: boolean;
+  connecting: boolean;
+  statusResolved: boolean;
+  error: string | null;
+  start: () => void;
+}
+
+export interface AgentChatContextItem {
+  key: string;
+  title: string;
+  context: string;
+}
+
+export interface ComposerAgentChatMessage {
+  message: string;
+  context?: string;
+  mode?: "plan" | "act";
+  submit?: boolean;
+}
+
+export interface ComposerAgentChatContextSetOptions extends AgentChatContextItem {
+  openSidebar?: boolean;
+  focus?: boolean;
+}
+
+export interface ComposerAgentChatOpenThreadRequest {
+  threadId: string;
+  onlyIfActiveThreadId?: string;
+}
+
+export interface ComposerBuilderConnectFlowOptions {
+  enabled?: boolean;
+  popupUrl?: string;
+  trackingSource?: string;
+  trackingFlow?: string;
+  onConnected?: (state: { orgName: string | null }) => void | Promise<void>;
+}
+
+export interface AgentComposerReference {
+  label: string;
+  icon?: string;
+  source?: string;
+  refType: string;
+  refId?: string | null;
+  refPath?: string | null;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+  clearsSlots?: string[];
+  relatedReferences?: AgentComposerReference[];
+}
+export interface AgentComposerReferenceInsertPayload extends AgentComposerReference {
+  insertMessageId: string;
+}
+
+export interface VoiceContextPack {
+  surface?: string;
+  mode?: string;
+  snippets?: Array<{ label: string; value: string }>;
+  terms?: Array<{ term: string; replacement?: string }>;
+}
+
+export interface ComposerRuntimeAdapters {
+  resolvePath?: (path: string) => string;
+  translate?: ComposerTranslate;
+  formatNumber?: (value: number, options?: Intl.NumberFormatOptions) => string;
+  models?: {
+    useChatModels?: (options: { enabled: boolean }) => ComposerModelState;
+    useAgentEngineConfigured?: (enabled: boolean) => {
+      missing: boolean;
+      state: string;
+    };
+    fetchAgentEngineConfiguredState?: (
+      enabled: boolean,
+      options: { timeoutMs: number },
+    ) => Promise<"missing" | "configured" | string>;
+    BuilderSetupCard?: ComponentType<any>;
+    BuilderSetupContent?: ComponentType<any>;
+    reasoning?: {
+      defaultEffort?: ReasoningEffort;
+      getOptionsForModel?: (model?: string) => ReasoningEffort[];
+      label?: (effort: ReasoningEffort) => string;
+      resolve?: (model: string, effort?: ReasoningEffort) => ReasoningEffort;
+    };
+  };
+  agentChat?: {
+    sendToAgentChat?: (input: ComposerAgentChatMessage) => void;
+    setContextItem?: (input: ComposerAgentChatContextSetOptions) => void;
+    requestThreadOpen?: (input: ComposerAgentChatOpenThreadRequest) => void;
+    formatContextItems?: (
+      items: readonly AgentChatContextItem[] | undefined,
+    ) => string;
+    normalizeReference?: (reference: unknown) => AgentComposerReference | null;
+    StaleIndexBoundary?: ComponentType<any>;
+  };
+  builder?: {
+    useConnectFlow?: (
+      options: ComposerBuilderConnectFlowOptions,
+    ) => ComposerBuilderConnectFlow;
+    tryDelegateBuildRequest?: (text: string) => boolean;
+    isTrustedFrameMessage?: (event: MessageEvent) => boolean;
+    isTrustedBuilderMessage?: (event: MessageEvent) => boolean;
+  };
+  resources?: {
+    useOrg?: () => {
+      data?: { orgId?: string | null; role?: string | null } | null;
+    };
+    isMcpIntegrationAvailable?: () => boolean;
+    useCreateMcpServer?: () => {
+      mutateAsync: (input: any) => Promise<unknown>;
+    };
+    McpIntegrationDialog?: ComponentType<any>;
+  };
+  voice?: {
+    useProviderStatus?: () => {
+      status: { builder?: boolean; openai?: boolean } | null;
+      refresh: () => void;
+    };
+    getBrowserTabId?: () => string;
+    readAppState?: <T>(
+      key: string,
+    ) => T | null | undefined | Promise<T | null | undefined>;
+    setAppState?: (key: string, value: unknown) => void | Promise<unknown>;
+    subscribeSidebarState?: (
+      listener: (detail: { open?: boolean } | undefined) => void,
+    ) => () => void;
+    applyContextReplacements?: (
+      text: string,
+      context: VoiceContextPack | undefined,
+    ) => string;
+  };
+}
+
+const identityPath = (path: string) => path;
+const fallbackTranslate: ComposerTranslate = (key, options) => {
+  const template =
+    typeof options?.defaultValue === "string" ? options.defaultValue : key;
+
+  return template.replace(/{{\s*([\w$.-]+)\s*}}/g, (match, name: string) => {
+    const value = options?.[name];
+    return value == null ? match : String(value);
+  });
+};
+const fallbackModels = {
+  useChatModels: () => ({
+    selectedModel: "auto",
+    selectedEngine: "auto",
+    selectedEffort: "high" as ReasoningEffort,
+    availableModels: [],
+    isLoading: false,
+    onModelChange: () => {},
+    onEffortChange: () => {},
+  }),
+  useAgentEngineConfigured: () => ({ missing: false, state: "configured" }),
+  fetchAgentEngineConfiguredState: async () => "configured",
+};
+const FragmentBoundary: ComponentType<{ children?: ReactNode }> = ({
+  children,
+}) => <>{children}</>;
+const fallbackBuilderFlow = {
+  hasFetchedStatus: false,
+  configured: false,
+  envManaged: false,
+  connecting: false,
+  statusResolved: false,
+  error: null,
+  start: () => {},
+};
+
+const fallbackAdapters: Required<Pick<ComposerRuntimeAdapters, "resolvePath">> &
+  ComposerRuntimeAdapters = {
+  resolvePath: identityPath,
+  translate: fallbackTranslate,
+  formatNumber: (value, options) =>
+    new Intl.NumberFormat("en-US", options).format(value),
+  models: fallbackModels,
+  agentChat: {
+    sendToAgentChat: () => {},
+    setContextItem: () => {},
+    requestThreadOpen: () => {},
+    formatContextItems: () => "",
+    normalizeReference: (reference) =>
+      reference &&
+      typeof reference === "object" &&
+      typeof (reference as AgentComposerReference).label === "string" &&
+      typeof (reference as AgentComposerReference).refType === "string"
+        ? (reference as AgentComposerReference)
+        : null,
+    StaleIndexBoundary: FragmentBoundary,
+  },
+  builder: {
+    useConnectFlow: () => fallbackBuilderFlow,
+    tryDelegateBuildRequest: () => false,
+    isTrustedFrameMessage: () => false,
+    isTrustedBuilderMessage: () => false,
+  },
+  resources: {
+    useOrg: () => ({ data: null }),
+    isMcpIntegrationAvailable: () => false,
+    useCreateMcpServer: () => ({ mutateAsync: async () => undefined }),
+  },
+  voice: {
+    useProviderStatus: () => ({ status: null, refresh: () => {} }),
+    getBrowserTabId: () => "",
+    readAppState: () => undefined,
+    setAppState: () => {},
+    subscribeSidebarState: () => () => {},
+    applyContextReplacements: applyVoiceContextReplacements,
+  },
+};
+
+const ComposerRuntimeAdaptersContext =
+  createContext<ComposerRuntimeAdapters>(fallbackAdapters);
+
+export function ComposerRuntimeAdaptersProvider({
+  adapters,
+  children,
+}: {
+  adapters: ComposerRuntimeAdapters;
+  children: ReactNode;
+}) {
+  // Consumers key effects off this value; a fresh identity per render re-runs
+  // every one of them (app-state reads, event subscriptions) on each render.
+  const value = useMemo(
+    () => ({
+      ...fallbackAdapters,
+      ...adapters,
+      models: { ...fallbackModels, ...adapters.models },
+      agentChat: { ...fallbackAdapters.agentChat, ...adapters.agentChat },
+      builder: { ...fallbackAdapters.builder, ...adapters.builder },
+      resources: { ...fallbackAdapters.resources, ...adapters.resources },
+      voice: { ...fallbackAdapters.voice, ...adapters.voice },
+    }),
+    [adapters],
+  );
+  return (
+    <ComposerRuntimeAdaptersContext.Provider value={value}>
+      {children}
+    </ComposerRuntimeAdaptersContext.Provider>
+  );
+}
+
+export function useComposerRuntimeAdapters() {
+  return useContext(ComposerRuntimeAdaptersContext);
+}
+
+export const DEFAULT_REASONING_EFFORT: ReasoningEffort = "high";
+export function getReasoningEffortOptionsForModel(
+  _model?: string,
+): ReasoningEffort[] {
+  return ["low", "medium", "high"];
+}
+export function reasoningEffortLabel(effort: ReasoningEffort): string {
+  return effort === "xhigh"
+    ? "Extra high"
+    : effort[0].toUpperCase() + effort.slice(1);
+}
+export function resolveReasoningEffortSelection(
+  _model: string,
+  effort?: ReasoningEffort,
+): ReasoningEffort {
+  return effort ?? DEFAULT_REASONING_EFFORT;
+}
+
+export const AGENT_CHAT_INSERT_REFERENCE_EVENT =
+  "agent-native:insert-composer-reference";
+export const AGENT_CHAT_INSERT_REFERENCE_MESSAGE_TYPE =
+  "agent-native:insert-composer-reference";
+
+export function formatPromptContextItems(
+  items: AgentChatContextItem[] | undefined,
+): string {
+  return (
+    items
+      ?.map((item) => item.context ?? item.title ?? "")
+      .filter(Boolean)
+      .join("\n\n") ?? ""
+  );
+}
+
+export function applyVoiceContextReplacements(
+  text: string,
+  context: VoiceContextPack | undefined,
+): string {
+  const isAlphaNumeric = (value: string | undefined) =>
+    value != null && /[\p{L}\p{N}_]/u.test(value);
+  const isSafeBoundary = (
+    value: string,
+    index: number,
+    direction: "before" | "after",
+  ) => {
+    const char = value[index];
+    if (char == null) return true;
+    if (isAlphaNumeric(char) || "@/\\:".includes(char)) return false;
+    if (".-+".includes(char)) {
+      const neighbor =
+        direction === "before" ? value[index - 1] : value[index + 1];
+      return !isAlphaNumeric(neighbor);
+    }
+    return true;
+  };
+  let next = text;
+  for (const term of context?.terms ?? []) {
+    const source = term.term.trim();
+    const replacement = term.replacement?.trim();
+    if (!replacement || source.length < 2 || replacement === source) continue;
+    const escaped = source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    next = next.replace(new RegExp(escaped, "giu"), (match, offset: number) => {
+      const end = offset + match.length;
+      return isSafeBoundary(next, offset - 1, "before") &&
+        isSafeBoundary(next, end, "after")
+        ? replacement
+        : match;
+    });
+  }
+  return next;
+}

package/src/composer/types.ts

@@ -0,0 +1,66 @@
+export interface FileResult {
+  path: string;
+  name: string;
+  source: "codebase" | "resource";
+  type: "file" | "folder";
+}
+
+export interface SkillResult {
+  name: string;
+  description: string;
+  path: string;
+  source: "codebase" | "resource";
+}
+
+export interface MentionItem {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: string;
+  source: string;
+  refType: string;
+  refPath?: string;
+  refId?: string;
+  section?: string;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+  clearsSlots?: string[];
+  relatedReferences?: MentionReferenceInsert[];
+}
+
+export interface Reference {
+  type: "file" | "skill" | "mention" | "agent" | "custom-agent";
+  path: string;
+  name: string;
+  source: string;
+  refType?: string;
+  refId?: string;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface MentionReferenceInsert {
+  label: string;
+  icon?: string;
+  source?: string;
+  refType: string;
+  refId?: string | null;
+  refPath?: string | null;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+  clearsSlots?: string[];
+  relatedReferences?: MentionReferenceInsert[];
+}
+
+export interface SlashCommand {
+  name: string;
+  description: string;
+  icon?: string;
+}
+
+export type ComposerMode = "skill" | "job" | "automation" | "extension";
+
+export type AgentComposerLayoutVariant = "default" | "compact" | "hero";

package/src/composer/use-file-search.ts

@@ -0,0 +1,64 @@
+import { useState, useEffect, useRef } from "react";
+
+import { useComposerRuntimeAdapters } from "./runtime-adapters.js";
+import type { FileResult } from "./types.js";
+
+export function useFileSearch(query: string, enabled: boolean) {
+  const { resolvePath = (path) => path } = useComposerRuntimeAdapters();
+  const [files, setFiles] = useState<FileResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const requestIdRef = useRef(0);
+  const abortRef = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    if (!enabled) {
+      setFiles([]);
+      setIsLoading(false);
+      return;
+    }
+
+    setIsLoading(true);
+    const id = ++requestIdRef.current;
+    // Abort any in-flight request so a superseded/unmounted query stops fetching
+    // (mirrors use-mention-search). The requestId guard still protects state.
+    abortRef.current?.abort();
+    const abort = new AbortController();
+    abortRef.current = abort;
+
+    const timer = setTimeout(
+      async () => {
+        try {
+          const res = await fetch(
+            resolvePath(
+              `/_agent-native/agent-chat/files?q=${encodeURIComponent(query)}`,
+            ),
+            { signal: abort.signal },
+          );
+          if (!res.ok) throw new Error();
+          const data = await res.json();
+          // Only update if this is still the latest request
+          if (id === requestIdRef.current) {
+            setFiles(data.files || []);
+          }
+        } catch (err) {
+          if ((err as Error)?.name === "AbortError") return;
+          if (id === requestIdRef.current) {
+            setFiles([]);
+          }
+        } finally {
+          if (id === requestIdRef.current) {
+            setIsLoading(false);
+          }
+        }
+      },
+      query.length === 0 ? 0 : 200,
+    );
+
+    return () => {
+      clearTimeout(timer);
+      abort.abort();
+    };
+  }, [query, enabled, resolvePath]);
+
+  return { files, isLoading };
+}

package/src/composer/use-mention-search.ts

@@ -0,0 +1,90 @@
+import { useState, useEffect, useRef } from "react";
+
+import { useComposerRuntimeAdapters } from "./runtime-adapters.js";
+import type { MentionItem } from "./types.js";
+
+export function useMentionSearch(
+  query: string,
+  enabled: boolean,
+  resolvePathOverride?: (path: string) => string,
+) {
+  const { resolvePath = (path) => path } = useComposerRuntimeAdapters();
+  const resolveRequestPath = resolvePathOverride ?? resolvePath;
+  const [items, setItems] = useState<MentionItem[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const abortRef = useRef<AbortController | null>(null);
+  const requestIdRef = useRef(0);
+
+  useEffect(() => {
+    if (!enabled) {
+      setItems([]);
+      setIsLoading(false);
+      return;
+    }
+
+    // Cancel any in-flight stream
+    abortRef.current?.abort();
+    const abort = new AbortController();
+    abortRef.current = abort;
+    const id = ++requestIdRef.current;
+
+    setItems([]);
+    setIsLoading(true);
+
+    const debounceMs = query.length === 0 ? 0 : 150;
+
+    const timer = setTimeout(async () => {
+      try {
+        const res = await fetch(
+          resolveRequestPath(
+            `/_agent-native/agent-chat/mentions?q=${encodeURIComponent(query)}`,
+          ),
+          { signal: abort.signal },
+        );
+        if (!res.ok || !res.body) throw new Error();
+
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          buf += decoder.decode(value, { stream: true });
+          const lines = buf.split("\n");
+          buf = lines.pop()!; // last line may be incomplete
+
+          for (const line of lines) {
+            if (!line.trim()) continue;
+            try {
+              const { items: batch } = JSON.parse(line) as {
+                items: MentionItem[];
+              };
+              if (id === requestIdRef.current && batch?.length) {
+                setItems((prev) => {
+                  // Deduplicate by id
+                  const seen = new Set(prev.map((x) => x.id));
+                  const fresh = batch.filter((x) => !seen.has(x.id));
+                  return fresh.length ? [...prev, ...fresh] : prev;
+                });
+              }
+            } catch {}
+          }
+        }
+      } catch (err: unknown) {
+        if (err instanceof Error && err.name === "AbortError") return;
+        if (id === requestIdRef.current) setItems([]);
+      } finally {
+        if (id === requestIdRef.current) setIsLoading(false);
+      }
+    }, debounceMs);
+
+    return () => {
+      clearTimeout(timer);
+      abort.abort();
+    };
+  }, [query, enabled, resolveRequestPath]);
+
+  return { items, isLoading };
+}