@agent-native/core 0.86.1 → 0.88.0

package/corpus/core/src/sharing/actions/create-agent-resource-link.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import {
+  buildAgentAccessApiUrl,
+  buildAgentAccessUrl,
+  createScopedAgentAccessGrant,
+} from "../../server/agent-access.js";
+import { getConfiguredAppBasePath } from "../../server/app-base-path.js";
+import {
+  getRequestContext,
+  getRequestUserEmail,
+} from "../../server/request-context.js";
+import { ForbiddenError, resolveAccess } from "../access.js";
+import { requireShareableResource } from "../registry.js";
+
+function appOrigin(): string {
+  const origin =
+    getRequestContext()?.requestOrigin ||
+    process.env.APP_URL ||
+    process.env.BETTER_AUTH_URL ||
+    "http://localhost:3000";
+  try {
+    return new URL(origin).origin;
+  } catch {
+    return "http://localhost:3000";
+  }
+}
+
+export default defineAction({
+  description:
+    "Create a temporary, read-only, agent-readable link for a registered shareable resource. The token is scoped to exactly one resource and does not change the resource visibility.",
+  schema: z.object({
+    resourceType: z.string().describe("Shareable resource type"),
+    resourceId: z.string().describe("Resource ID"),
+  }),
+  readOnly: true,
+  run: async (args) => {
+    const reg = requireShareableResource(args.resourceType);
+    const agentReadable = reg.agentReadable;
+    if (!agentReadable) {
+      throw new ForbiddenError(
+        `${reg.displayName} does not expose an agent-readable context endpoint.`,
+      );
+    }
+
+    const access = await resolveAccess(args.resourceType, args.resourceId);
+    if (!access) {
+      throw new ForbiddenError(
+        `No access to ${args.resourceType} ${args.resourceId}`,
+      );
+    }
+
+    const pagePath =
+      agentReadable.getPagePath?.(access.resource) ??
+      reg.getResourcePath?.(access.resource);
+    const contextPath = agentReadable.getContextPath(access.resource);
+    if (!pagePath || !contextPath) {
+      throw new ForbiddenError(`${reg.displayName} is not agent-readable yet.`);
+    }
+
+    const grant = createScopedAgentAccessGrant({
+      resourceKind: agentReadable.resourceKind,
+      resourceId: args.resourceId,
+      viewerEmail: getRequestUserEmail() || undefined,
+      ttlSeconds: agentReadable.ttlSeconds,
+    });
+    const origin = appOrigin();
+    const basePath = getConfiguredAppBasePath();
+
+    return {
+      resourceType: args.resourceType,
+      resourceId: args.resourceId,
+      url: buildAgentAccessUrl({
+        path: pagePath,
+        origin,
+        basePath,
+        token: grant.token,
+      }),
+      contextUrl: buildAgentAccessApiUrl({
+        endpoint: contextPath,
+        resourceId: args.resourceId,
+        origin,
+        basePath,
+        token: grant.token,
+      }),
+      expiresAt: grant.expiresAt,
+      ttlSeconds: grant.ttlSeconds,
+    };
+  },
+});

package/corpus/core/src/sharing/registry.ts

@@ -105,6 +105,25 @@ export interface ShareableResourceRegistration {
    * Default: `false`.
    */
   ownerAccessIgnoresOrg?: boolean;
+  /**
+   * Optional external-agent read handoff. When set, the framework-level
+   * `create-agent-resource-link` action can mint a short-lived, read-only
+   * `agent_access` URL for this resource. The context endpoint is owned by the
+   * template so it can expose the same intentionally shareable shape as the
+   * public page, not a generic raw database row.
+   */
+  agentReadable?:
+    | false
+    | {
+        /** Token scope. Include the app name to avoid cross-app collisions. */
+        resourceKind: string;
+        /** App-relative JSON endpoint that accepts `id` + `agent_access`. */
+        getContextPath: (resource: any) => string | undefined;
+        /** Optional override for the page URL. Defaults to getResourcePath. */
+        getPagePath?: (resource: any) => string | undefined;
+        /** Optional override for the default two-hour token lifetime. */
+        ttlSeconds?: number;
+      };
 }
 
 // Stash the registry on globalThis so it survives SSR bundle duplication.

package/corpus/core/src/templates/workspace-core/.agents/skills/agent-native-toolkit/SKILL.md

@@ -0,0 +1,92 @@
+# Agent-Native Toolkit
+
+Use this skill when deciding whether app chrome, settings, collaboration,
+sharing, navigation, organization, setup, history, comments, or agent UX should
+be built app-locally or moved into reusable framework/toolkit pieces.
+
+## Core Rule
+
+Apps own domain models, domain actions, and product-specific workflows. The
+framework and `@agent-native/toolkit` own repeated workspace behavior users
+expect to work the same everywhere.
+
+Move behavior into shared toolkit primitives when it is:
+
+- workspace-wide, such as settings, nav, search, org membership, or setup
+- agent-visible, such as context, actions, run progress, or proof-of-done
+- governed, such as secrets, permissions, sharing, audit, or billing
+- repeated by two or more apps
+- not tied to one domain model
+
+Keep behavior app-local when the abstraction would hide important domain
+language or make a simple app-specific workflow harder to understand.
+
+## Settings Direction
+
+Durable settings belong in the Settings app or a registered settings route. The
+agent sidebar should not become a second settings app. It can show contextual
+quick controls and deep links such as:
+
+- `/settings/ai`
+- `/settings/connections`
+- `/settings/secrets`
+- `/settings/usage`
+- `/settings/apps/:appId`
+
+When adding a new API key, OAuth grant, provider connection, model selector, app
+preference, notification preference, or usage/billing surface, register it as a
+settings tab or app settings panel first. Only add sidebar UI when it is needed
+in the moment of agent use.
+
+## Reusable Kits
+
+- **Settings kit**: account, workspace, AI models, LLM keys, connections,
+  secrets, usage, notifications, changelog, and app-specific panels.
+- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
+  remote selections, recent edit highlights, real-time sync indicators, and
+  undo/redo grouping.
+- **Sharing kit**: private/workspace/org/public-link access, invites, roles,
+  expirations, agent-readable links, and resource registration.
+- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,
+  command palette entries, recent resources, pinned resources, and global search.
+- **Organization kit**: folders, tags, favorites, archive, trash, ownership,
+  membership, and common resource metadata.
+- **Setup and connections kit**: declarative setup requirements, model readiness,
+  missing-secret states, OAuth grants, and provider connection health.
+- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
+  approval, generative UI, progress, and screen-state exposure.
+- **History and recovery kit**: audit log, activity feed, version history,
+  checkpoints, undo, redo, restore, and proof-of-done.
+- **Comments and review kit**: anchored comments, pins, mentions, review
+  requests, resolved threads, agent follow-up tasks, and notifications.
+- **Workflow and observability kit**: notifications, approvals, scheduled work,
+  background runs, recurring jobs, traces, evals, feedback, and run timelines.
+
+## Implementation Checklist
+
+When adding or refactoring one of these areas:
+
+1. Search existing framework and template code for duplicated UI or actions.
+2. Decide the shared contract: data shape, action API, React component/hook, and
+   app adapter points.
+3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
+4. Expose the same capability to the UI and agent through actions or documented
+   client helpers.
+5. Register app-specific labels, routes, resource adapters, and settings panels
+   instead of hardcoding app names in core UI.
+6. Update docs and relevant skills so future apps discover the shared path.
+
+## Related Skills
+
+Read these alongside this skill when the work touches the specific area:
+
+- `sharing`
+- `real-time-collab`
+- `real-time-sync`
+- `client-side-routing`
+- `context-awareness`
+- `onboarding`
+- `secrets`
+- `audit-log`
+- `observability`
+- `frontend-design`

package/corpus/core/src/vite/client.ts

@@ -1739,6 +1739,7 @@ function ssrStubPlugin(packages: string[]): Plugin | null {
     "captureException",
     "common",
     "createLowlight",
+    "createNodeFromContent",
     "defaultUrlTransform",
     "extensions",
     "findTable",

package/corpus/templates/analytics/AGENTS.md

@@ -177,6 +177,10 @@ details live in `.agents/skills/`.
   scoped to one recording for two hours; SSR embeds an agent discovery payload
   and the JSON APIs expose only summary/timeline metadata plus bounded event
   reads.
+- Use `@agent-native/core/server` and `@agent-native/core/shared` agent-access
+  helpers for scoped token mint/verify and bot-visible URL construction. Keep
+  replay chunk/blob authorization, diagnostics payloads, and the session detail
+  UI in Analytics.
 - Recordings also capture console logs and network request metadata (request
   bodies/headers never captured; response bodies captured only as bounded,
   redacted 5xx snippets; scrubbed URLs, truncated messages, per-session

package/corpus/templates/analytics/actions/get-sql-dashboard.ts

@@ -6,97 +6,12 @@ import {
 } from "@agent-native/core/server";
 import { z } from "zod";
 
-import { buildDashboardPanelGroups } from "../app/pages/adhoc/sql-dashboard/dashboard-layout";
 import {
-  clampDashboardColumns,
-  type SqlPanel,
-} from "../app/pages/adhoc/sql-dashboard/types";
+  buildDashboardAgentContext,
+  buildDashboardSeedAgentContext,
+} from "../server/lib/agent-readable-resource-context";
 import { loadDashboardSeed } from "../server/lib/dashboard-seeds";
 import { getDashboard } from "../server/lib/dashboards-store";
-import { getPanelOrder } from "./dashboard-panel-order";
-
-function dashboardLayoutSummary(config: Record<string, unknown>) {
-  const panels = Array.isArray(config.panels)
-    ? (config.panels as SqlPanel[])
-    : [];
-  const columns = clampDashboardColumns(config.columns);
-  const groups = buildDashboardPanelGroups(panels, columns);
-  const panelOrder = getPanelOrder(config);
-  let visibleRowNumber = 1;
-
-  return {
-    panelCount: panelOrder.length,
-    panelOrder,
-    firstPanelIds: panelOrder.slice(0, 10),
-    groups: groups.map((group) => ({
-      key: group.key,
-      sectionId: group.section?.id ?? null,
-      sectionTitle: group.section?.title ?? null,
-      columns: group.columns,
-      rows: group.rows.map((row, rowIndex) => {
-        const rowNumber = visibleRowNumber++;
-        return {
-          rowNumber,
-          rowIndex,
-          panelIds: row.panels.map((panel) => panel.id),
-        };
-      }),
-    })),
-  };
-}
-
-function panelSummaries(config: Record<string, unknown>) {
-  const panels = Array.isArray(config.panels)
-    ? (config.panels as Array<Record<string, unknown>>)
-    : [];
-  return panels.map((panel, index) => {
-    const panelConfig =
-      panel.config &&
-      typeof panel.config === "object" &&
-      !Array.isArray(panel.config)
-        ? (panel.config as Record<string, unknown>)
-        : {};
-    return {
-      index,
-      id: typeof panel.id === "string" ? panel.id : "",
-      title: typeof panel.title === "string" ? panel.title : "",
-      chartType: typeof panel.chartType === "string" ? panel.chartType : "",
-      source: typeof panel.source === "string" ? panel.source : undefined,
-      width: typeof panel.width === "number" ? panel.width : undefined,
-      columns: typeof panel.columns === "number" ? panel.columns : undefined,
-      tab: typeof panel.tab === "string" ? panel.tab : undefined,
-      description:
-        typeof panelConfig.description === "string"
-          ? panelConfig.description
-          : undefined,
-    };
-  });
-}
-
-function seededResponse(
-  id: string,
-  seed: Record<string, unknown>,
-  includeConfig: boolean,
-): Record<string, unknown> {
-  const base = {
-    id,
-    name: typeof seed.name === "string" ? seed.name : id,
-    description:
-      typeof seed.description === "string" ? seed.description : undefined,
-    filters: seed.filters,
-    variables: seed.variables,
-    columns: seed.columns,
-    panels: panelSummaries(seed),
-    layout: dashboardLayoutSummary(seed),
-    ownerEmail: null,
-    orgId: null,
-    visibility: "org",
-    archivedAt: null,
-    hiddenAt: null,
-    hiddenBy: null,
-  };
-  return includeConfig ? { ...base, ...seed } : base;
-}
 
 export default defineAction({
   description:
@@ -149,34 +64,15 @@ export default defineAction({
     if (!dash || dash.kind !== "sql") {
       const seed = loadDashboardSeed(args.id);
       if (seed)
-        return seededResponse(args.id, seed, args.includeConfig === true);
+        return buildDashboardSeedAgentContext(args.id, seed, {
+          includeConfig: args.includeConfig === true,
+        });
       throw Object.assign(new Error("Dashboard not found"), {
         statusCode: 404,
       });
     }
-    const config = dash.config as Record<string, unknown>;
-    const base = {
-      id: args.id,
-      name: typeof config.name === "string" ? config.name : args.id,
-      description:
-        typeof config.description === "string" ? config.description : undefined,
-      filters: config.filters,
-      variables: config.variables,
-      columns: config.columns,
-      panels: panelSummaries(config),
-      layout: dashboardLayoutSummary(config),
-      ownerEmail: dash.ownerEmail,
-      orgId: dash.orgId,
-      visibility: dash.visibility,
-      role: dash.role,
-      canEdit: dash.canEdit,
-      canManage: dash.canManage,
-      archivedAt: dash.archivedAt,
-      hiddenAt: dash.hiddenAt,
-      hiddenBy: dash.hiddenBy,
-      createdAt: dash.createdAt,
-      updatedAt: dash.updatedAt,
-    };
-    return args.includeConfig === true ? { ...base, ...config } : base;
+    return buildDashboardAgentContext(dash, {
+      includeConfig: args.includeConfig === true,
+    });
   },
 });

package/corpus/templates/analytics/app/components/InlineMetric.tsx

@@ -1,5 +1,5 @@
-import { Card, CardContent } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
+import { Card, CardContent } from "@agent-native/toolkit/ui/card";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 
 interface InlineMetricProps {
   title: string;

package/corpus/templates/analytics/app/components/dashboard/CumulativeNetChart.tsx

@@ -1,4 +1,11 @@
 import { useT } from "@agent-native/core/client";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@agent-native/toolkit/ui/card";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import {
   Area,
   AreaChart,
@@ -10,8 +17,6 @@ import {
   YAxis,
 } from "recharts";
 
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
 import {
   chartAxisStroke,
   chartGridStroke,

package/corpus/templates/analytics/app/components/dashboard/DataTable.tsx

@@ -1,21 +1,19 @@
 import { useT } from "@agent-native/core/client";
+import { Button } from "@agent-native/toolkit/ui/button";
 import {
-  IconArrowsUpDown,
-  IconChevronLeft,
-  IconChevronRight,
-} from "@tabler/icons-react";
-import { useState, useMemo } from "react";
-
-import { Button } from "@/components/ui/button";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@agent-native/toolkit/ui/card";
 import {
   Select,
   SelectContent,
   SelectItem,
   SelectTrigger,
   SelectValue,
-} from "@/components/ui/select";
-import { Skeleton } from "@/components/ui/skeleton";
+} from "@agent-native/toolkit/ui/select";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import {
   Table,
   TableBody,
@@ -23,7 +21,14 @@ import {
   TableHead,
   TableHeader,
   TableRow,
-} from "@/components/ui/table";
+} from "@agent-native/toolkit/ui/table";
+import {
+  IconArrowsUpDown,
+  IconChevronLeft,
+  IconChevronRight,
+} from "@tabler/icons-react";
+import { useState, useMemo } from "react";
+
 import { cn } from "@/lib/utils";
 
 const PAGE_SIZE_OPTIONS = [10, 25, 50, 100];

package/corpus/templates/analytics/app/components/dashboard/DateRangePicker.tsx

@@ -1,4 +1,5 @@
-import { Button } from "@/components/ui/button";
+import { Button } from "@agent-native/toolkit/ui/button";
+
 import { cn } from "@/lib/utils";
 
 export type DateRange = "7d" | "30d" | "90d";

package/corpus/templates/analytics/app/components/dashboard/MetricCard.tsx

@@ -1,5 +1,10 @@
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@agent-native/toolkit/ui/card";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 
 interface MetricCardProps {
   title: string;

package/corpus/templates/analytics/app/components/dashboard/RecentActivity.tsx

@@ -1,13 +1,16 @@
 import { useT } from "@agent-native/core/client";
-
-import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+} from "@agent-native/toolkit/ui/avatar";
 import {
   Card,
   CardContent,
   CardHeader,
   CardTitle,
   CardDescription,
-} from "@/components/ui/card";
+} from "@agent-native/toolkit/ui/card";
 
 const activities = [
   {

package/corpus/templates/analytics/app/components/dashboard/RevenueChart.tsx

@@ -1,4 +1,10 @@
 import { useT } from "@agent-native/core/client";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@agent-native/toolkit/ui/card";
 import {
   Area,
   AreaChart,
@@ -9,7 +15,6 @@ import {
   YAxis,
 } from "recharts";
 
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import {
   chartAxisStroke,
   chartGridStroke,

package/corpus/templates/analytics/app/components/dashboard/RevenueComparisonChart.tsx

@@ -1,4 +1,11 @@
 import { useT } from "@agent-native/core/client";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@agent-native/toolkit/ui/card";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import {
   Bar,
   CartesianGrid,
@@ -12,8 +19,6 @@ import {
   YAxis,
 } from "recharts";
 
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
 import { chartAxisStroke, chartGridStroke } from "@/lib/chart-theme";
 
 interface RevenueComparisonChartProps {

package/corpus/templates/analytics/app/components/dashboard/SqlChart.tsx

@@ -1,5 +1,20 @@
 import { useT } from "@agent-native/core/client";
 import { EmbeddedExtension } from "@agent-native/core/client/extensions";
+import { Button } from "@agent-native/toolkit/ui/button";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@agent-native/toolkit/ui/card";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@agent-native/toolkit/ui/select";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import {
   IconArrowsSort,
   IconSortAscending,
@@ -42,17 +57,6 @@ import {
   YAxis,
 } from "recharts";
 
-import { Button } from "@/components/ui/button";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "@/components/ui/select";
-import { Skeleton } from "@/components/ui/skeleton";
-
 const PAGE_SIZE_OPTIONS = [10, 25, 50, 100];
 import { useSqlQuery } from "@/lib/sql-query";
 import { serializePanelSql } from "@/pages/adhoc/sql-dashboard/panel-sql";

package/corpus/templates/analytics/app/components/dashboard/StatsCard.tsx

@@ -1,4 +1,10 @@
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@agent-native/toolkit/ui/card";
+
 import { cn } from "@/lib/utils";
 
 interface StatsCardProps {

package/corpus/templates/analytics/app/components/dashboard/TimeSeriesChart.tsx

@@ -1,4 +1,11 @@
 import { useT } from "@agent-native/core/client";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@agent-native/toolkit/ui/card";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import {
   Area,
   AreaChart,
@@ -9,8 +16,6 @@ import {
   YAxis,
 } from "recharts";
 
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import { Skeleton } from "@/components/ui/skeleton";
 import {
   chartAxisStroke,
   chartGridStroke,

package/corpus/templates/analytics/app/components/layout/CommandPalette.tsx

@@ -8,6 +8,22 @@ import {
   useT,
 } from "@agent-native/core/client";
 import { extensionPath } from "@agent-native/core/client/extensions";
+import {
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+} from "@agent-native/toolkit/ui/command";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@agent-native/toolkit/ui/dialog";
+import { Label } from "@agent-native/toolkit/ui/label";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import {
   IconFlask,
   IconTool,
@@ -23,22 +39,6 @@ import { useTheme } from "next-themes";
 import { useEffect, useState, useCallback } from "react";
 import { useNavigate } from "react-router";
 
-import {
-  CommandDialog,
-  CommandInput,
-  CommandList,
-  CommandEmpty,
-  CommandGroup,
-  CommandItem,
-} from "@/components/ui/command";
-import {
-  Dialog,
-  DialogContent,
-  DialogHeader,
-  DialogTitle,
-} from "@/components/ui/dialog";
-import { Label } from "@/components/ui/label";
-import { Skeleton } from "@/components/ui/skeleton";
 import { dashboards } from "@/pages/adhoc/registry";
 
 import changelog from "../../../CHANGELOG.md?raw";

package/corpus/templates/analytics/app/components/layout/HeaderActions.tsx

@@ -1,4 +1,5 @@
 import { useT } from "@agent-native/core/client";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import {
   useEffect,
   useSyncExternalStore,
@@ -6,8 +7,6 @@ import {
   type FC,
 } from "react";
 
-import { Skeleton } from "@/components/ui/skeleton";
-
 /**
  * External store for the page's header title + actions. We use an external
  * store (not React context) so that pages can inject ReactNode without