@agent-native/toolkit 0.225.2-nightly-20261106152255 → 0.226.0

package/src/app/chat/agentkit-chat/root.tsx

@@ -1,10 +1,18 @@
 import { describeModelForEngine } from "@agent-native/core/agent/model-catalog";
+import {
+  getAgentNativeAgentKitUploadDriver,
+  clearAgentNativeAgentKitUploads,
+} from "@agent-native/core/client/agentkit-chat/transport";
 import { callAction } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
-import { useMemo } from "react";
+import { readFileUploadStatus } from "@agent-native/core/client/uploads";
+import { useSession } from "@agent-native/core/client/use-session";
+import { useMemo, useEffect } from "react";
 
+import { CoreFileStorageSetupContext } from "../../agentkit/react/core-file-storage.js";
 import { AgentKitRoot } from "../../agentkit/react/root.js";
 import type { AgentKitRootProps } from "../../agentkit/react/root.js";
+import { FileStorageSetupPopover } from "../FileStorageSetupPopover.js";
 import { AgentKitActionWidget } from "./action-widget.js";
 import { CoreAgentKitApproval } from "./approval-card.js";
 import { agentKitWorkStepLabels } from "./work-step-labels.js";
@@ -31,6 +39,76 @@ function coreModelDisplayName(model: string): string {
 
 export function CoreAgentKitRoot(props: AgentKitRootProps) {
   const t = useT();
+  const nativeUpload = props.transport
+    ? getAgentNativeAgentKitUploadDriver(props.transport)
+    : undefined;
+  const { session } = useSession();
+  const scopeKey = JSON.stringify([
+    session?.email ?? null,
+    session?.orgId ?? null,
+    session?.authUserId ?? null,
+  ]);
+  const storageScope = useMemo(
+    () =>
+      nativeUpload
+        ? {
+            scopeKey,
+            readStatus: readFileUploadStatus,
+            Setup: FileStorageSetupPopover,
+          }
+        : null,
+    [nativeUpload, scopeKey],
+  );
+  useEffect(
+    () => () => {
+      if (props.transport) clearAgentNativeAgentKitUploads(props.transport);
+    },
+    [props.transport, scopeKey],
+  );
+  const upload = useMemo(
+    () =>
+      nativeUpload
+        ? async (...args: Parameters<typeof nativeUpload>) => {
+            try {
+              await nativeUpload(...args);
+            } catch (cause) {
+              const code =
+                cause && typeof cause === "object" && "code" in cause
+                  ? cause.code
+                  : undefined;
+              const key =
+                code === "upload_too_large"
+                  ? "agentChat.composer.fileTooLarge"
+                  : code === "upload_session_expired"
+                    ? "agentChat.composer.sessionExpired"
+                    : code === "upload_unsupported_type"
+                      ? "agentChat.composer.unsupportedFileType"
+                      : code === "upload_network_error"
+                        ? "agentChat.composer.uploadOffline"
+                        : code === "upload_unavailable"
+                          ? "agentChat.composer.uploadUnavailable"
+                          : "agentChat.composer.uploadFailed";
+              throw Object.assign(new Error(t(key, { size: 25 }), { cause }), {
+                code,
+                ...(cause && typeof cause === "object" && "status" in cause
+                  ? { status: cause.status }
+                  : {}),
+                ...(cause && typeof cause === "object" && "retryable" in cause
+                  ? { retryable: cause.retryable }
+                  : {}),
+              });
+            }
+          }
+        : undefined,
+    [nativeUpload, t],
+  );
+  const clientOptions = useMemo(
+    () => ({
+      ...props.clientOptions,
+      ...(!props.clientOptions?.upload && upload ? { upload } : {}),
+    }),
+    [props.clientOptions, upload],
+  );
   const slots = useMemo(
     () => ({
       ...props.slots,
@@ -109,13 +187,18 @@ export function CoreAgentKitRoot(props: AgentKitRootProps) {
     }),
     [props.labels, t],
   );
+  const rootProps: AgentKitRootProps = props.controller
+    ? props
+    : { ...props, clientOptions };
   return (
-    <AgentKitRoot
-      {...props}
-      slots={slots}
-      labels={labels}
-      loadRunUsage={props.loadRunUsage ?? loadCoreRunUsage}
-      formatModelName={props.formatModelName ?? coreModelDisplayName}
-    />
+    <CoreFileStorageSetupContext.Provider value={storageScope}>
+      <AgentKitRoot
+        {...rootProps}
+        slots={slots}
+        labels={labels}
+        loadRunUsage={props.loadRunUsage ?? loadCoreRunUsage}
+        formatModelName={props.formatModelName ?? coreModelDisplayName}
+      />
+    </CoreFileStorageSetupContext.Provider>
   );
 }

package/src/app/chat/chat/surface-types.ts

@@ -51,6 +51,7 @@ export interface AssistantChatSendOptions {
   trackInRunsTray?: boolean;
   requestMode?: AgentRequestMode;
   attachments?: AgentChatAttachment[];
+  references?: AgentChatMessage["references"];
   /** Correlates with `AGENT_CHAT_SUBMIT_RESULT_EVENT` — see agent-chat.ts. */
   submitMessageId?: string;
   /** Drop a queued submit instead of handing it to chat after this time. */

package/src/app/chat/composer/runtime-adapters.tsx

@@ -50,6 +50,7 @@ import {
 import { BuilderSetupCard, BuilderSetupContent } from "../chat/run-recovery.js";
 import { AssistantUiStaleIndexErrorBoundary } from "./assistant-ui-recovery.js";
 import { coreComposerModelAdapters } from "./model-runtime-adapters.js";
+import { useWorkspaceComposerMenu } from "./use-workspace-composer-menu.js";
 
 const REALTIME_VOICE_REQUEST_SOURCE = "realtime-voice";
 
@@ -102,6 +103,7 @@ export const coreComposerAdapters: CoreComposerRuntimeAdapters = {
     isTrustedFrameMessage,
   },
   resources: {
+    useWorkspaceMenu: useWorkspaceComposerMenu,
     useOrg,
     isMcpIntegrationAvailable: isMcpIntegrationCatalogAvailable,
     useCreateMcpServer,

package/src/app/chat/composer/use-agentkit-capabilities.hardening.spec.tsx

@@ -71,8 +71,9 @@ describe("AgentKit capability lifecycle", () => {
   let container: HTMLDivElement;
   let result: ReturnType<typeof useAgentKitCapabilities>;
   let unmounted: boolean;
+  let enabled = true;
   function Harness() {
-    result = useAgentKitCapabilities();
+    result = useAgentKitCapabilities({ enabled });
     return null;
   }
   async function render() {
@@ -102,6 +103,7 @@ describe("AgentKit capability lifecycle", () => {
     document.body.append(container);
     root = createRoot(container);
     unmounted = false;
+    enabled = true;
   });
   afterEach(async () => {
     if (!unmounted) await act(async () => root.unmount());
@@ -110,6 +112,29 @@ describe("AgentKit capability lifecycle", () => {
     vi.unstubAllGlobals();
   });
 
+  it("loads only on demand while preserving identity and cached results when the menu closes", async () => {
+    enabled = false;
+    await render();
+    const identity = result.scopeKey;
+    expect(mocks.call).not.toHaveBeenCalled();
+    expect(result.integrationsLoading).toBe(false);
+    enabled = true;
+    await render();
+    await settle();
+    expect(result.data).toEqual(catalog);
+    enabled = false;
+    await render();
+    expect(result.scopeKey).toBe(identity);
+    expect(result.data).toEqual(catalog);
+    mocks.call.mockResolvedValueOnce(empty);
+    await act(async () => {
+      await result.refetchIntegrations();
+    });
+    await settle();
+    expect(result.scopeKey).toBe(identity);
+    expect(result.data).toEqual(empty);
+  });
+
   it.each(["account", "organization", "app"] as const)(
     "isolates data and cancels stale requests across a change of %s",
     async (change) => {

package/src/app/chat/composer/use-agentkit-capabilities.ts

@@ -25,16 +25,16 @@ export function agentKitCapabilityQueryKey(
   ] as const;
 }
 
-export function useAgentKitCapabilities() {
+export function useAgentKitCapabilities(options: { enabled?: boolean } = {}) {
   const { session, status, error: sessionError } = useSession();
   const queryClient = useQueryClient();
-  const enabled =
+  const authorized =
     status === "authenticated" &&
     Boolean(session?.email.trim()) &&
     !agentNativeApiDisabledReason();
   const queryKey = agentKitCapabilityQueryKey(
     agentNativePath("/_agent-native/actions/get-agentkit-capabilities"),
-    enabled ? session : null,
+    authorized ? session : null,
   );
   const scopeKey = JSON.stringify(queryKey);
   const scope = useMemo(() => ({ key: scopeKey }), [scopeKey]);
@@ -55,10 +55,9 @@ export function useAgentKitCapabilities() {
         undefined,
         { method: "GET", signal },
       ),
-    enabled,
+    enabled: authorized && options.enabled !== false,
     staleTime: 15_000,
     gcTime: 0,
-    placeholderData: undefined,
     refetchOnMount: "always",
     refetchOnWindowFocus: "always",
     retry: defaultActionQueryRetry,
@@ -66,7 +65,7 @@ export function useAgentKitCapabilities() {
   });
 
   useEffect(() => {
-    if (!enabled) return;
+    if (!authorized) return;
     const invalidate = () => {
       void queryClient.invalidateQueries({
         queryKey: ["action", "get-agentkit-capabilities"],
@@ -86,12 +85,12 @@ export function useAgentKitCapabilities() {
       unsubscribe();
       removeCompleteListener();
     };
-  }, [enabled, queryClient]);
+  }, [authorized, queryClient]);
 
   const { refetch: refetchCapabilities } = capabilityQuery;
   const refetchIntegrations = useCallback(async () => {
     const assertCurrent = () => {
-      if (!enabled || activeScope.current !== scope) {
+      if (!authorized || activeScope.current !== scope) {
         throw new DOMException("The operation was aborted.", "AbortError");
       }
     };
@@ -99,14 +98,15 @@ export function useAgentKitCapabilities() {
     const result = await refetchCapabilities({ throwOnError: true });
     assertCurrent();
     return result;
-  }, [enabled, scope, refetchCapabilities]);
+  }, [authorized, scope, refetchCapabilities]);
 
   return {
     ...capabilityQuery,
     data:
-      enabled && !capabilityQuery.isError ? capabilityQuery.data : undefined,
+      authorized && !capabilityQuery.isError ? capabilityQuery.data : undefined,
     integrationsLoading:
-      status === "loading" || (enabled && capabilityQuery.isPending),
+      options.enabled !== false &&
+      (status === "loading" || (authorized && capabilityQuery.isPending)),
     integrationsError: sessionError ?? capabilityQuery.error,
     scopeKey,
     refetchIntegrations,

package/src/app/chat/composer/use-agentkit-integration-menu.spec.tsx

@@ -93,7 +93,6 @@ describe("shared AgentKit integration submenu", () => {
       container.querySelector('button[aria-label="Add context"]')!,
       "ArrowDown",
     );
-    await key(row("Add context"), "ArrowRight");
     expect(row("Integrations").getAttribute("aria-haspopup")).toBe("menu");
     await key(row("Integrations"), "ArrowRight");
   }
@@ -101,7 +100,7 @@ describe("shared AgentKit integration submenu", () => {
     await render();
     await open();
     expect(pathname).toBe("/home");
-    expect(document.querySelectorAll('[role="menu"]')).toHaveLength(3);
+    expect(document.querySelectorAll('[role="menu"]')).toHaveLength(2);
     expect(document.body.textContent).toContain(
       "No integrations available for this app.",
     );
@@ -130,7 +129,6 @@ describe("shared AgentKit integration submenu", () => {
       "ArrowDown",
     );
     expect(document.body.textContent).not.toContain("GitHub");
-    await key(row("Add context"), "ArrowRight");
     await key(row("Integrations"), "ArrowRight");
     expect(row("GitHub").querySelector("svg")).toBeNull();
     expect(row("Slack")).toBeDefined();
@@ -174,7 +172,7 @@ describe("shared AgentKit integration submenu", () => {
     await render();
     await open();
     await key(row("Connect an integration…"), "Escape");
-    expect(document.querySelectorAll('[role="menu"]')).toHaveLength(2);
+    expect(document.querySelectorAll('[role="menu"]')).toHaveLength(1);
     expect(document.activeElement).toBe(row("Integrations"));
     expect(pathname).toBe("/home");
   });

package/src/app/chat/composer/use-workspace-composer-menu.spec.tsx

@@ -0,0 +1,174 @@
+import type { WorkspaceComposerMenuContribution } from "@agent-native/toolkit/composer/runtime-adapters";
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import englishMessages from "../../i18n/catalogs/en-US.js";
+import { useWorkspaceComposerMenu } from "./use-workspace-composer-menu.js";
+
+const mocks = vi.hoisted(() => ({
+  capabilities: vi.fn(),
+  refetch: vi.fn(),
+  select: vi.fn(),
+  org: { orgId: "alpha", role: "member" },
+}));
+vi.mock("./use-agentkit-capabilities.js", () => ({
+  useAgentKitCapabilities: mocks.capabilities,
+}));
+vi.mock("@agent-native/core/client/i18n", () => ({
+  useT: () => (key: string) =>
+    (englishMessages as Record<string, string>)[
+      key.replace(/^agentChat\./, "")
+    ],
+}));
+vi.mock("@agent-native/core/client/org", () => ({
+  useOrg: () => ({ data: mocks.org }),
+}));
+vi.mock("@agent-native/core/client/resources", () => ({
+  isMcpIntegrationCatalogAvailable: () => true,
+  useCreateMcpServer: () => ({ mutateAsync: vi.fn() }),
+}));
+vi.mock("../../resources/index.js", () => ({
+  McpIntegrationDialogDeferred: ({
+    open,
+    defaultScope,
+  }: {
+    open: boolean;
+    defaultScope: string;
+  }) =>
+    open ? (
+      <div role="dialog" data-scope={defaultScope}>
+        Connect tools
+      </div>
+    ) : null,
+}));
+
+let root: ReturnType<typeof createRoot>;
+let container: HTMLDivElement;
+let contribution: WorkspaceComposerMenuContribution;
+let enabled = false;
+let state: {
+  scopeKey: string;
+  data:
+    | {
+        sources: { figma: { available: boolean } };
+        integrations: { id: string; label: string; kind: "mcp" }[];
+      }
+    | undefined;
+  integrationsLoading: boolean;
+  integrationsError: Error | null;
+  refetchIntegrations: typeof mocks.refetch;
+};
+function Harness() {
+  contribution = useWorkspaceComposerMenu({
+    enabled,
+    onSelectIntegration: mocks.select,
+  });
+  return (
+    <>
+      {contribution.items.map((item) => (
+        <button key={item.id} onClick={() => item.onSelect?.()}>
+          {item.label}
+        </button>
+      ))}
+      {contribution.error && <span role="alert">{contribution.error}</span>}
+      {contribution.overlays}
+    </>
+  );
+}
+async function render() {
+  await act(async () => root.render(<Harness />));
+}
+beforeEach(() => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  mocks.select.mockReset();
+  mocks.refetch.mockReset();
+  mocks.capabilities.mockReset();
+  state = {
+    scopeKey: "chat:member:alpha",
+    data: {
+      sources: { figma: { available: false } },
+      integrations: [{ id: "mcp:tools", label: "Tools", kind: "mcp" }],
+    },
+    integrationsLoading: false,
+    integrationsError: null,
+    refetchIntegrations: mocks.refetch,
+  };
+  mocks.capabilities.mockImplementation(() => state);
+  mocks.org = { orgId: "alpha", role: "member" };
+  enabled = false;
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+});
+afterEach(async () => {
+  await act(async () => root.unmount());
+  container.remove();
+  vi.unstubAllGlobals();
+});
+
+describe("workspace composer contributions", () => {
+  it("stages real integration references and offers the shared setup primitive separately", async () => {
+    await render();
+    expect(mocks.capabilities).toHaveBeenLastCalledWith({ enabled: false });
+    enabled = true;
+    await render();
+    expect(mocks.capabilities).toHaveBeenLastCalledWith({ enabled: true });
+    await act(async () => container.querySelector("button")!.click());
+    expect(mocks.select).toHaveBeenCalledWith({
+      label: "Tools",
+      refType: "integration",
+      refId: "mcp:tools",
+      refPath: "mcp:tools",
+      source: "workspace-integration",
+      icon: "integration",
+    });
+    expect(
+      contribution.items.every((item) => item.section === "integrations"),
+    ).toBe(true);
+    await act(async () =>
+      [...container.querySelectorAll("button")]
+        .find((button) => button.textContent === "Connect an integration…")!
+        .click(),
+    );
+    expect(
+      container.querySelector('[role="dialog"]')?.getAttribute("data-scope"),
+    ).toBe("user");
+  });
+  it("starts organization administrators in their allowed shared scope", async () => {
+    mocks.org = { orgId: "alpha", role: "owner" };
+    await render();
+    await act(async () =>
+      [...container.querySelectorAll("button")]
+        .find((button) => button.textContent === "Connect an integration…")!
+        .click(),
+    );
+    expect(
+      container.querySelector('[role="dialog"]')?.getAttribute("data-scope"),
+    ).toBe("org");
+  });
+
+  it("rejects an old selection after identity changes away and back, and keeps unreadable catalogs visible as errors", async () => {
+    await render();
+    const select = contribution.items[0].onSelect!;
+    state = { ...state, scopeKey: "chat:member:beta" };
+    await render();
+    state = { ...state, scopeKey: "chat:member:alpha" };
+    await render();
+    expect(select).toThrow();
+    expect(mocks.select).not.toHaveBeenCalled();
+    state = {
+      ...state,
+      data: undefined,
+      integrationsError: new Error("permission lookup unavailable"),
+    };
+    await render();
+    expect(container.querySelector('[role="alert"]')?.textContent).toBe(
+      "Could not load integrations.",
+    );
+    expect(contribution.items.map((item) => item.id)).toEqual([
+      "workspace-connect-integrations",
+    ]);
+  });
+});

package/src/app/chat/composer/use-workspace-composer-menu.tsx

@@ -0,0 +1,122 @@
+import { useT } from "@agent-native/core/client/i18n";
+import { useOrg } from "@agent-native/core/client/org";
+import {
+  isMcpIntegrationCatalogAvailable,
+  useCreateMcpServer,
+} from "@agent-native/core/client/resources";
+import { mcpIntegrationLogo } from "@agent-native/core/client/resources/mcp-integration-logos";
+import type { ComposerContextMenuItem } from "@agent-native/toolkit/composer";
+import type {
+  WorkspaceComposerMenuContribution,
+  WorkspaceComposerMenuOptions,
+} from "@agent-native/toolkit/composer/runtime-adapters";
+import { IconPlugConnected, IconPlus } from "@tabler/icons-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { McpIntegrationDialogDeferred } from "../../resources/index.js";
+import { useAgentKitCapabilities } from "./use-agentkit-capabilities.js";
+
+export function useWorkspaceComposerMenu({
+  onSelectIntegration,
+  onRestoreFocus,
+  enabled,
+}: WorkspaceComposerMenuOptions): WorkspaceComposerMenuContribution {
+  const t = useT();
+  const capabilities = useAgentKitCapabilities({ enabled });
+  const { data: org } = useOrg();
+  const createMcp = useCreateMcpServer();
+  const canCreateOrgMcp =
+    !org?.orgId || org.role === "owner" || org.role === "admin";
+  const [open, setOpen] = useState(false);
+  const scope = useMemo(
+    () => ({ key: capabilities.scopeKey }),
+    [capabilities.scopeKey],
+  );
+  const latest = useRef({ capabilities, onSelectIntegration, scope });
+  latest.current = { capabilities, onSelectIntegration, scope };
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  useEffect(() => setOpen(false), [scope]);
+  const items: ComposerContextMenuItem[] = (
+    capabilities.data?.integrations ?? []
+  ).map((integration) => ({
+    id: `workspace-integration:${integration.id}`,
+    section: "integrations",
+    label: integration.label,
+    icon: mcpIntegrationLogo(integration.id) ? (
+      <img
+        src={mcpIntegrationLogo(integration.id)}
+        alt=""
+        className="size-4 object-contain"
+      />
+    ) : (
+      <IconPlugConnected />
+    ),
+    onSelect: () => {
+      const current = latest.current;
+      if (
+        !mounted.current ||
+        current.scope !== scope ||
+        current.capabilities.integrationsError ||
+        current.capabilities.integrationsLoading ||
+        !current.capabilities.data?.integrations.some(
+          (entry) => entry.id === integration.id,
+        )
+      ) {
+        throw new Error(t("agentChat.composer.integrations.loadFailed"));
+      }
+      current.onSelectIntegration({
+        label: integration.label,
+        refType: "integration",
+        refId: integration.id,
+        refPath: integration.id,
+        source: "workspace-integration",
+        icon: "integration",
+      });
+    },
+  }));
+  if (isMcpIntegrationCatalogAvailable())
+    items.push({
+      id: "workspace-connect-integrations",
+      section: "integrations",
+      order: 1000,
+      opensDialog: true,
+      label: t("agentChat.composer.integrations.connect"),
+      icon: <IconPlus />,
+      onSelect: () => setOpen(true),
+    });
+  return {
+    items,
+    scopeKey: capabilities.scopeKey,
+    loading: capabilities.integrationsLoading,
+    ...(capabilities.integrationsError
+      ? { error: t("agentChat.composer.integrations.loadFailed") }
+      : {}),
+    onRetry: capabilities.refetchIntegrations,
+    overlays: (
+      <McpIntegrationDialogDeferred
+        open={open}
+        onOpenChange={setOpen}
+        onCloseAutoFocus={(event) => {
+          if (
+            onRestoreFocus &&
+            mounted.current &&
+            latest.current.scope === scope
+          ) {
+            event.preventDefault();
+            onRestoreFocus();
+          }
+        }}
+        defaultScope={org?.orgId && !canCreateOrgMcp ? "user" : "org"}
+        canCreateOrgMcp={canCreateOrgMcp}
+        hasOrg={Boolean(org?.orgId)}
+        onCreateMcpServer={(args) => createMcp.mutateAsync(args)}
+      />
+    ),
+  };
+}

package/src/app/chat/index.ts

@@ -80,3 +80,4 @@ export {
   type McpAppRendererProps,
 } from "./mcp-apps/McpAppRenderer.js";
 export type { AgentChatContextItem } from "@agent-native/core/client/agent-chat";
+export { preparePromptComposerAgentHandoff } from "./prepare-prompt-composer-agent-handoff.js";