@agent-native/core 0.109.4 → 0.110.1

package/corpus/core/src/client/navigation/index.ts

@@ -0,0 +1,54 @@
+export {
+  agentNativePath,
+  appApiPath,
+  appBasePath,
+  appPath,
+} from "../api-path.js";
+export {
+  useAgentRouteState,
+  useSemanticNavigationState,
+  type AgentRouteLocation,
+  type SemanticNavigationCommandEnvelope,
+  type UseAgentRouteStateOptions,
+  type UseAgentRouteStateResult,
+  type UseSemanticNavigationStateOptions,
+  type UseSemanticNavigationStateResult,
+} from "../route-state.js";
+export {
+  CommandMenu,
+  openAgentSidebar,
+  openAgentSettings,
+  submitToAgent,
+  useCommandMenuShortcut,
+  type CommandMenuProps,
+  type CommandMenuDoc,
+  type CommandDocsGroupProps,
+  type CommandGroupProps,
+  type CommandItemProps,
+  type CommandShortcutProps,
+} from "../CommandMenu.js";
+export {
+  buildOpenRouteLink,
+  buildOpenRoutePath,
+  buildResourceRoute,
+  buildSettingsRoute,
+  buildStandardAppRoute,
+  buildTeamRoute,
+  createStandardOpenPathResolver,
+  STANDARD_APP_ROUTES,
+  STANDARD_SETTINGS_TABS,
+  type BuildResourceRouteOptions,
+  type BuildStandardAppRouteOptions,
+  type NavigationLink,
+  type NavigationTarget,
+  type StandardAppRouteId,
+  type StandardOpenPathResolverOptions,
+  type StandardOpenPathRoute,
+  type StandardSettingsTabId,
+} from "../../navigation/index.js";
+export {
+  postNavigate,
+  isInAgentEmbed,
+  AGENT_NAVIGATE_MESSAGE_TYPE,
+  type AgentNavigateMessage,
+} from "../embed.js";

package/corpus/core/src/client/resources/ResourcesPanel.tsx

@@ -43,6 +43,7 @@ import {
 import { PromptComposer } from "../composer/PromptComposer.js";
 import { useT } from "../i18n.js";
 import { useOrg } from "../org/hooks.js";
+import { useUploadResource } from "../uploads/use-upload-resource.js";
 import { cn } from "../utils.js";
 import { BuiltinCapabilityDetail } from "./BuiltinCapabilityDetail.js";
 import { isMcpIntegrationCatalogAvailable } from "./mcp-integration-catalog.js";
@@ -67,7 +68,6 @@ import {
   useCreateResource,
   useUpdateResource,
   useDeleteResource,
-  useUploadResource,
   withMcpServersFolder,
   withAgentScratchFolder,
   type ResourceScope,

package/corpus/core/src/client/resources/index.ts

@@ -1,5 +1,6 @@
-export { ResourcesPanel } from "./ResourcesPanel.js";
+export { ResourcesPanel, type ResourcesPanelProps } from "./ResourcesPanel.js";
 export { ResourceTree, type ResourceTreeProps } from "./ResourceTree.js";
 export { ResourceEditor, type ResourceEditorProps } from "./ResourceEditor.js";
+export { useUploadResource } from "../uploads/use-upload-resource.js";
 export * from "./use-resources.js";
 export * from "./use-builtin-capabilities.js";

package/corpus/core/src/client/resources/use-resources.ts

@@ -400,23 +400,3 @@ export function useDeleteResource() {
     },
   });
 }
-
-export function useUploadResource() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: async (formData: FormData) => {
-      const res = await fetch(
-        agentNativePath("/_agent-native/resources/upload"),
-        {
-          method: "POST",
-          body: formData,
-        },
-      );
-      if (!res.ok) throw new Error(`Upload failed: ${res.statusText}`);
-      return res.json() as Promise<Resource>;
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["resources"] });
-    },
-  });
-}

package/corpus/core/src/client/route-chunk-recovery/index.ts

@@ -0,0 +1 @@
+export * from "../route-chunk-recovery.js";

package/corpus/core/src/client/ui/index.ts

@@ -0,0 +1,55 @@
+export { ApiKeySettings } from "../components/ApiKeySettings.js";
+export {
+  RequireSession,
+  buildSignInReturnHref,
+  type RequireSessionProps,
+} from "../require-session.js";
+export {
+  NewWorkspaceAppFlow,
+  type NewWorkspaceAppFlowProps,
+  type VaultSecretOption,
+} from "../NewWorkspaceAppFlow.js";
+export { Turnstile, type TurnstileProps } from "../Turnstile.js";
+export {
+  OpenSourceBadge,
+  PoweredByBadge,
+  type OpenSourceBadgeProps,
+  type PoweredByBadgeProps,
+} from "../PoweredByBadge.js";
+export {
+  StarfieldBackground,
+  type StarfieldBackgroundProps,
+} from "../StarfieldBackground.js";
+export { FeedbackButton, type FeedbackButtonProps } from "../FeedbackButton.js";
+export {
+  ErrorReportActions,
+  type ErrorReportActionsProps,
+} from "../ErrorReportActions.js";
+export {
+  buildErrorReportTemplate,
+  buildGitHubIssueUrl,
+  type ErrorReportDebugItem,
+  type ErrorReportTemplateOptions,
+} from "../error-reporting.js";
+export { getClientSurface, type ClientSurface } from "../client-surface.js";
+export { ErrorBoundary } from "../ErrorBoundary.js";
+export { ClientOnly } from "../ClientOnly.js";
+export { DefaultSpinner } from "../DefaultSpinner.js";
+export {
+  getThemeInitScript,
+  themeInitScript,
+  type ThemePreference,
+} from "../theme.js";
+export {
+  APPEARANCE_PRESETS,
+  applyAppearance,
+  getStoredAppearance,
+  useAppearance,
+  useAppearanceSync,
+  type AppearancePresetId,
+} from "../appearance.js";
+export {
+  AppearancePicker,
+  type AppearancePickerProps,
+} from "../AppearancePicker.js";
+export { AgentNativeIcon } from "../components/icons/AgentNativeIcon.js";

package/corpus/core/src/client/uploads/index.ts

@@ -0,0 +1 @@
+export { useUploadResource } from "./use-upload-resource.js";

package/corpus/core/src/client/uploads/use-upload-resource.ts

@@ -0,0 +1,24 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { agentNativePath } from "../api-path.js";
+import type { Resource } from "../resources/use-resources.js";
+
+export function useUploadResource() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (formData: FormData) => {
+      const res = await fetch(
+        agentNativePath("/_agent-native/resources/upload"),
+        {
+          method: "POST",
+          body: formData,
+        },
+      );
+      if (!res.ok) throw new Error(`Upload failed: ${res.statusText}`);
+      return res.json() as Promise<Resource>;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["resources"] });
+    },
+  });
+}

package/corpus/core/src/client/widgets/index.ts

@@ -0,0 +1,41 @@
+export {
+  ACTION_CHAT_UI_DATA_CHART_RENDERER,
+  ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+  ACTION_CHAT_UI_DATA_TABLE_RENDERER,
+  ACTION_CHAT_UI_DATA_WIDGET_RENDERER,
+  ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER,
+  type ActionChatUIConfig,
+} from "../../action-ui.js";
+export {
+  DATA_CHART_WIDGET,
+  DATA_INSIGHTS_WIDGET,
+  DATA_TABLE_WIDGET,
+  createDataChartWidgetResult,
+  createDataInsightsWidgetResult,
+  createDataTableWidgetResult,
+  dataChartWidgetResultSchema,
+  dataChartWidgetSchema,
+  dataInsightsWidgetResultSchema,
+  dataTableWidgetResultSchema,
+  dataTableWidgetSchema,
+  dataWidgetResultSchema,
+  isDataChartWidget,
+  isDataTableWidget,
+  isDataWidgetResult,
+  normalizeDataWidgetKind,
+  normalizeDataWidgetResult,
+  type DataChartSeriesDefinition,
+  type DataChartWidget,
+  type DataChartWidgetResult,
+  type DataChartWidgetResultInput,
+  type DataInsightsWidgetResult,
+  type DataInsightsWidgetResultInput,
+  type DataTableColumn,
+  type DataTableWidget,
+  type DataTableWidgetResult,
+  type DataTableWidgetResultInput,
+  type DataWidgetDisplay,
+  type DataWidgetKind,
+  type DataWidgetResult,
+  type DataWidgetResultMetadata,
+} from "../chat/widgets/data-widget-types.js";

package/corpus/core/src/localization/default-messages.ts

@@ -377,7 +377,8 @@ const messages = {
     conversation: "Conversation",
     free: "free",
     noSystemContext: "No system context is available for this scope yet.",
-    pageTitle: "Context",
+    panelTitle: "Context X-Ray",
+    snapshotsTitle: "Snapshots",
     agent: "Agent",
     headerDescription:
       "See the system instructions and conversation tokens that shape the agent.",

package/corpus/core/src/package-lifecycle/deprecated-imports.ts

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  loadMigrationManifestsForProject,
+  migrationMoveStatus,
+  resolveMigrationSymbolMove,
+  type MigrationManifest,
+  type MigrationMove,
+  type MigrationMoveStatus,
+} from "./migration-manifest.js";
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx"]);
+const SKIP_DIRECTORIES = new Set([
+  ".git",
+  ".next",
+  ".output",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+]);
+
+export interface DeprecatedImportFinding {
+  file: string;
+  line: number;
+  from: string;
+  to: string[];
+  symbols: string[];
+  status: MigrationMoveStatus;
+}
+
+export interface ScanDeprecatedImportsOptions {
+  root: string;
+  manifests?: MigrationManifest[];
+}
+
+function sourceFiles(root: string): string[] {
+  const files: string[] = [];
+  const visit = (directory: string): void => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isDirectory() && SKIP_DIRECTORIES.has(entry.name)) continue;
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        visit(entryPath);
+      } else if (
+        SOURCE_EXTENSIONS.has(path.extname(entry.name)) &&
+        !entry.name.endsWith(".d.ts")
+      ) {
+        files.push(entryPath);
+      }
+    }
+  };
+  visit(root);
+  return files.sort();
+}
+
+function mergeMoves(
+  manifests: MigrationManifest[],
+): Record<string, MigrationMove> {
+  const moves: Record<string, MigrationMove> = {};
+  for (const manifest of manifests) Object.assign(moves, manifest.moves);
+  return moves;
+}
+
+function importedNames(clause: string): string[] | null {
+  const named = clause.match(/\{([\s\S]*?)\}/);
+  if (!named) return null;
+  return named[1]
+    .split(",")
+    .map((part) => part.trim().replace(/^type\s+/, ""))
+    .filter(Boolean)
+    .map((part) => part.split(/\s+as\s+/)[0].trim());
+}
+
+function lineAt(text: string, index: number): number {
+  return text.slice(0, index).split("\n").length;
+}
+
+function matchingMoveTargets(
+  move: MigrationMove,
+  names: string[] | null,
+): Array<{
+  status: MigrationMoveStatus;
+  targets: string[];
+  symbols: string[];
+}> {
+  if (!move.symbols) {
+    return [
+      {
+        status: migrationMoveStatus(move),
+        targets: [move.to],
+        symbols: names ?? [],
+      },
+    ];
+  }
+  if (!names) {
+    const groups = new Map<MigrationMoveStatus, Set<string>>();
+    for (const importedName of Object.keys(move.symbols)) {
+      const resolved = resolveMigrationSymbolMove(move, importedName);
+      if (!resolved) continue;
+      const targets = groups.get(resolved.status) ?? new Set<string>();
+      targets.add(resolved.to);
+      groups.set(resolved.status, targets);
+    }
+    return [...groups].map(([status, targets]) => ({
+      status,
+      targets: [...targets].sort(),
+      symbols: [],
+    }));
+  }
+  const groups = new Map<
+    MigrationMoveStatus,
+    { targets: Set<string>; symbols: string[] }
+  >();
+  for (const name of names) {
+    const resolved = resolveMigrationSymbolMove(move, name);
+    if (!resolved) continue;
+    const group = groups.get(resolved.status) ?? {
+      targets: new Set<string>(),
+      symbols: [],
+    };
+    group.targets.add(resolved.to);
+    group.symbols.push(name);
+    groups.set(resolved.status, group);
+  }
+  return [...groups].map(([status, group]) => ({
+    status,
+    targets: [...group.targets].sort(),
+    symbols: group.symbols,
+  }));
+}
+
+export function scanDeprecatedImports(
+  options: ScanDeprecatedImportsOptions,
+): DeprecatedImportFinding[] {
+  const root = path.resolve(options.root);
+  const manifests = options.manifests ?? loadMigrationManifestsForProject(root);
+  const moves = mergeMoves(manifests);
+  const findings: DeprecatedImportFinding[] = [];
+  const fromDeclaration =
+    /\b(import|export)\s+([^;]*?)\s+from\s+["']([^"']+)["']\s*;?/g;
+  const sideEffectImport = /\bimport\s+["']([^"']+)["']\s*;?/g;
+
+  for (const file of sourceFiles(root)) {
+    const text = fs.readFileSync(file, "utf-8");
+    for (const match of text.matchAll(fromDeclaration)) {
+      const from = match[3];
+      const move = moves[from];
+      if (!move) continue;
+      const matches = matchingMoveTargets(move, importedNames(match[2]));
+      for (const matched of matches) {
+        findings.push({
+          file,
+          line: lineAt(text, match.index ?? 0),
+          from,
+          to: matched.targets,
+          symbols: matched.symbols,
+          status: matched.status,
+        });
+      }
+    }
+    for (const match of text.matchAll(sideEffectImport)) {
+      const from = match[1];
+      const move = moves[from];
+      if (!move || move.symbols) continue;
+      findings.push({
+        file,
+        line: lineAt(text, match.index ?? 0),
+        from,
+        to: [move.to],
+        symbols: [],
+        status: migrationMoveStatus(move),
+      });
+    }
+  }
+  return findings;
+}

package/corpus/core/src/package-lifecycle/index.ts

@@ -1 +1,6 @@
 export * from "./manifest.js";
+export * from "./deprecated-imports.js";
+export * from "./migration-manifest.js";
+export * from "./migration-message.js";
+export * from "./tombstone.js";
+export * from "./upgrade-error.js";

package/corpus/core/src/package-lifecycle/migration-manifest.ts

@@ -0,0 +1,159 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface MigrationSymbolMove {
+  to: string;
+  name?: string;
+  status?: MigrationMoveStatus;
+}
+
+export interface MigrationMove {
+  to: string;
+  symbols?: Record<string, string | MigrationSymbolMove>;
+  status?: MigrationMoveStatus;
+}
+
+export type MigrationMoveStatus = "active" | "planned";
+
+export interface MigrationManifest {
+  sinceVersion: string;
+  moves: Record<string, MigrationMove>;
+}
+
+export interface ResolvedMigrationSymbolMove {
+  to: string;
+  name: string;
+  status: MigrationMoveStatus;
+}
+
+export function migrationMoveStatus(
+  move: Pick<MigrationMove, "status">,
+): MigrationMoveStatus {
+  return move.status === "planned" ? "planned" : "active";
+}
+
+export function readMigrationManifest(
+  manifestPath: string,
+): MigrationManifest | null {
+  try {
+    const parsed = JSON.parse(
+      fs.readFileSync(manifestPath, "utf-8"),
+    ) as Partial<MigrationManifest>;
+    if (
+      typeof parsed.sinceVersion !== "string" ||
+      !parsed.moves ||
+      typeof parsed.moves !== "object"
+    ) {
+      return null;
+    }
+    return parsed as MigrationManifest;
+  } catch {
+    return null;
+  }
+}
+
+export function bundledCoreMigrationManifestPath(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "../../migration-manifest.json");
+}
+
+export function bundledCorePackageVersion(): string | null {
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(
+        path.resolve(
+          path.dirname(fileURLToPath(import.meta.url)),
+          "../../package.json",
+        ),
+        "utf-8",
+      ),
+    ) as { version?: unknown };
+    return typeof manifest.version === "string" ? manifest.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function numericVersion(version: string): [number, number, number] | null {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+export function isMigrationManifestActive(
+  manifest: MigrationManifest,
+  packageVersion: string | null,
+): boolean {
+  if (!packageVersion) return false;
+  const current = numericVersion(packageVersion);
+  const since = numericVersion(manifest.sinceVersion);
+  if (!current || !since) return false;
+  for (let index = 0; index < current.length; index += 1) {
+    if (current[index] !== since[index]) return current[index] > since[index];
+  }
+  return true;
+}
+
+function resolveOptionalManifest(
+  projectRoot: string,
+  specifier: string,
+): string | null {
+  try {
+    const require = createRequire(path.join(projectRoot, "package.json"));
+    return require.resolve(specifier);
+  } catch {
+    return null;
+  }
+}
+
+export function loadMigrationManifestsForProject(
+  projectRoot: string,
+): MigrationManifest[] {
+  const paths = [
+    bundledCoreMigrationManifestPath(),
+    resolveOptionalManifest(
+      projectRoot,
+      "@agent-native/toolkit/migration-manifest.json",
+    ),
+  ];
+  return paths
+    .filter((manifestPath): manifestPath is string => Boolean(manifestPath))
+    .map(readMigrationManifest)
+    .filter((manifest): manifest is MigrationManifest => Boolean(manifest));
+}
+
+export function resolveMigrationSymbolMove(
+  move: MigrationMove,
+  importedName: string,
+): ResolvedMigrationSymbolMove | null {
+  if (!move.symbols) {
+    return {
+      to: move.to,
+      name: importedName,
+      status: migrationMoveStatus(move),
+    };
+  }
+  const symbolMove = move.symbols[importedName];
+  if (typeof symbolMove === "string") {
+    return {
+      to: move.to,
+      name: symbolMove,
+      status: migrationMoveStatus(move),
+    };
+  }
+  if (symbolMove) {
+    return {
+      to: symbolMove.to,
+      name: symbolMove.name ?? importedName,
+      status:
+        symbolMove.status === "planned"
+          ? "planned"
+          : symbolMove.status === "active"
+            ? "active"
+            : migrationMoveStatus(move),
+    };
+  }
+  return null;
+}

package/corpus/core/src/package-lifecycle/migration-message.ts

@@ -0,0 +1,6 @@
+export const AGENT_NATIVE_UPGRADE_CODEMOD_COMMAND =
+  "npx @agent-native/core@latest upgrade --codemods";
+
+export function migrationMoveMessage(from: string, to: string): string {
+  return `${from} moved to ${to}. Run: ${AGENT_NATIVE_UPGRADE_CODEMOD_COMMAND}`;
+}

package/corpus/core/src/package-lifecycle/tombstone.ts

@@ -0,0 +1,44 @@
+import {
+  migrationMoveStatus,
+  type MigrationManifest,
+} from "./migration-manifest.js";
+import { migrationMoveMessage } from "./migration-message.js";
+
+export interface TombstoneModuleOptions {
+  from: string;
+  manifest: MigrationManifest;
+  helperImport: string;
+  valueExports?: string[];
+  typeExports?: string[];
+}
+
+export function renderTombstoneModule(options: TombstoneModuleOptions): string {
+  const move = options.manifest.moves[options.from];
+  if (!move || migrationMoveStatus(move) !== "active") {
+    throw new Error(
+      `Cannot render a tombstone for ${options.from} without an active exact migration manifest move.`,
+    );
+  }
+  const to = move.to;
+  const message = migrationMoveMessage(options.from, to);
+  const lines = [
+    `import { throwMovedAgentNativeModule, type DeprecatedExport } from ${JSON.stringify(options.helperImport)};`,
+    "",
+    `throwMovedAgentNativeModule(${JSON.stringify(options.from)}, ${JSON.stringify(to)});`,
+  ];
+  for (const name of [...(options.valueExports ?? [])].sort()) {
+    lines.push(
+      "",
+      `/** @deprecated ${message} */`,
+      `export const ${name} = undefined as DeprecatedExport<${JSON.stringify(message)}>;`,
+    );
+  }
+  for (const name of [...(options.typeExports ?? [])].sort()) {
+    lines.push(
+      "",
+      `/** @deprecated ${message} */`,
+      `export type ${name} = DeprecatedExport<${JSON.stringify(message)}>;`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}

package/corpus/core/src/package-lifecycle/upgrade-error.ts

@@ -0,0 +1,19 @@
+import { migrationMoveMessage } from "./migration-message.js";
+
+declare const deprecatedExportBrand: unique symbol;
+
+export type DeprecatedExport<Message extends string> = never & {
+  readonly [deprecatedExportBrand]: Message;
+};
+
+export class AgentNativeUpgradeError extends Error {
+  override readonly name = "AgentNativeUpgradeError";
+
+  constructor(from: string, to: string) {
+    super(migrationMoveMessage(from, to));
+  }
+}
+
+export function throwMovedAgentNativeModule(from: string, to: string): never {
+  throw new AgentNativeUpgradeError(from, to);
+}

package/corpus/core/src/templates/default/.agents/skills/actions/SKILL.md

@@ -309,7 +309,7 @@ The frontend calls actions using React Query hooks from `@agent-native/core/clie
 ### `useActionQuery` — for GET actions
 
 ```ts
-import { useActionQuery } from "@agent-native/core/client";
+import { useActionQuery } from "@agent-native/core/client/hooks";
 
 function MealList() {
   // Types are auto-inferred from the action's schema + return type — no manual generic needed
@@ -323,7 +323,7 @@ function MealList() {
 ### `useActionMutation` — for POST/PUT/DELETE actions
 
 ```ts
-import { useActionMutation } from "@agent-native/core/client";
+import { useActionMutation } from "@agent-native/core/client/hooks";
 
 function AddMealButton() {
   // Types are auto-inferred — no manual generic needed
@@ -343,7 +343,7 @@ Mutations automatically invalidate all `["action"]` query keys on success, so GE
 ### `callAction` — for imperative client code
 
 ```ts
-import { callAction } from "@agent-native/core/client";
+import { callAction } from "@agent-native/core/client/hooks";
 
 const people = await callAction("search-people", { query }, { method: "GET" });
 ```