@agent-native/core 0.114.15 → 0.115.1

package/corpus/templates/clips/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs and source bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
+  features.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`. When examples,
+imports, or implementation details matter, inspect the packaged source corpus
+too.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you. It also includes a source-only corpus of core and
+first-party templates so agents can replicate current best-practice patterns
+without needing the framework monorepo checkout.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+pnpm action source-search --query "<pattern>"
+pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
+pnpm action source-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
+
+If the action runner is unavailable, search the package directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`. For source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
+
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
+
+## Reuse Proven Patterns (rg + cp)
+
+Version-matched installed source outranks web docs or memory: it is the exact
+code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
+holds source for every first-party template, not just the one this app started
+from, so a pattern from the mail template is fair game for a tasks app. Grep
+across it, then copy a whole file as a starting point instead of writing the
+pattern from scratch:
+
+```bash
+# Find how other templates solved a similar problem
+rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
+
+# Grab a proven action file as a starting point, then adapt names/schema
+cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
+   actions/archive-item.ts
+
+# Read the full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+Copying template-level app code (actions, components, skill files) is the
+expected reuse path — templates exist to be forked. This is different from
+copying `core`/`toolkit` **runtime internals**: for those, follow
+`customizing-agent-native`'s configure/compose/eject ladder instead of
+hand-duplicating framework logic.
+
+## Useful Slugs
+
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.
+- Do not copy framework runtime internals when a public API or narrow UI copy
+  will do; read `customizing-agent-native` for the supported override ladder.

package/corpus/templates/clips/AGENTS.md

@@ -21,6 +21,13 @@ ladder.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use actions for recording metadata, transcripts, cleanup, summaries, chapters,
   comments, spaces/folders, meetings, and sharing. Do not bypass access helpers.
+- Use `prepare-crm-call-evidence` only for a viewer-accessible recording
+  explicitly identified by a user action or the exact approved CRM A2A recipe.
+  It returns an opaque clip ID, durable HTTPS `/r/<id>` page, and optional
+  capture time for CRM; it never returns the event media URL, a transcript,
+  temporary token, quote, or summary. A CRM recipe may install a Clips-owned
+  `clip.created` trigger only through an exact user-approved A2A automation
+  definition.
 - Organization admins can use `set-organization-branding` with
   `defaultVisibility=public|org|private` to choose the visibility applied when
   new recordings omit an explicit visibility. The default remains `public`, and

package/corpus/templates/clips/actions/prepare-crm-call-evidence.ts

@@ -0,0 +1,58 @@
+import { defineAction } from "@agent-native/core/action";
+import { getRequestContext } from "@agent-native/core/server";
+import { assertAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import { getServerAppBasePath } from "../server/lib/public-agent-context.js";
+
+function clipsOrigin(): string {
+  const raw = getRequestContext()?.requestOrigin || process.env.APP_URL;
+  if (!raw) {
+    throw new Error(
+      "Clips needs an HTTPS APP_URL before it can prepare CRM evidence links.",
+    );
+  }
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(
+      "Clips needs a valid HTTPS APP_URL before it can prepare CRM evidence links.",
+    );
+  }
+  if (url.protocol !== "https:") {
+    throw new Error(
+      "Clips needs an HTTPS APP_URL before it can prepare CRM evidence links.",
+    );
+  }
+  return url.origin;
+}
+
+export default defineAction({
+  description:
+    "Prepare one access-gated Clips recording as bounded CRM call evidence. Returns only an opaque recording id, durable HTTPS recording page, and optional capture time; never media, a transcript, or a temporary access token.",
+  schema: z.object({
+    recordingId: z.string().trim().min(1).max(256),
+  }),
+  readOnly: true,
+  run: async ({ recordingId }) => {
+    const access = await assertAccess("recording", recordingId, "viewer");
+    const recording = access.resource as {
+      id: string;
+      createdAt?: string | null;
+      archivedAt?: string | null;
+      trashedAt?: string | null;
+    };
+    if (recording.archivedAt || recording.trashedAt) {
+      throw new Error("Archived or trashed Clips cannot be attached to CRM.");
+    }
+    const sourceUrl = `${clipsOrigin()}${getServerAppBasePath()}/r/${encodeURIComponent(recording.id)}`;
+    return {
+      sourceApp: "clips" as const,
+      artifactType: "call-evidence" as const,
+      artifactId: recording.id,
+      sourceUrl,
+      ...(recording.createdAt ? { capturedAt: recording.createdAt } : {}),
+    };
+  },
+});

package/corpus/templates/clips/app/components/library/bulk-action-toolbar.tsx

@@ -27,6 +27,8 @@ export interface BulkMoveTarget {
 
 interface BulkActionToolbarProps {
   count: number;
+  allSelected?: boolean;
+  onSelectAll?: () => void;
   onArchive?: () => void;
   onMove?: (folderId: string | null) => void;
   onTrash?: () => void;
@@ -38,6 +40,8 @@ interface BulkActionToolbarProps {
 
 export function BulkActionToolbar({
   count,
+  allSelected = false,
+  onSelectAll,
   onArchive,
   onMove,
   onTrash,
@@ -53,17 +57,30 @@ export function BulkActionToolbar({
   return (
     <div
       className={cn(
-        "flex w-fit max-w-full items-center gap-1 rounded-xl border border-border bg-popover px-3 py-2 shadow-lg",
+        "flex w-fit max-w-full items-center gap-1 rounded-xl bg-foreground px-3 py-2 text-background shadow-2xl ring-1 ring-black/10 dark:ring-white/10",
       )}
     >
-      <span className="pe-2 text-xs font-medium text-foreground">
+      <span className="pe-2 text-xs font-medium">
         {t("clipsFinalRaw.selectedCount", { count })}
       </span>
-      <div className="h-4 w-px bg-border" />
+      {onSelectAll && (
+        <Button
+          variant="ghost"
+          size="sm"
+          className="h-8 gap-1.5 text-background hover:bg-background/15 hover:text-background"
+          onClick={onSelectAll}
+          disabled={isPending}
+        >
+          {allSelected
+            ? t("clipsFinalRaw.deselectAll")
+            : t("clipsFinalRaw.selectAll")}
+        </Button>
+      )}
+      <div className="h-4 w-px bg-background/20" />
       <Button
         variant="ghost"
         size="sm"
-        className="h-8 gap-1.5"
+        className="h-8 gap-1.5 text-background hover:bg-background/15 hover:text-background"
         onClick={onArchive}
         disabled={isPending}
       >
@@ -75,7 +92,7 @@ export function BulkActionToolbar({
             <Button
               variant="ghost"
               size="sm"
-              className="h-8 gap-1.5"
+              className="h-8 gap-1.5 text-background hover:bg-background/15 hover:text-background"
               disabled={isPending}
             >
               <IconFolder className="h-3.5 w-3.5" /> {t("clipsFinalRaw.move")}
@@ -121,17 +138,17 @@ export function BulkActionToolbar({
       <Button
         variant="ghost"
         size="sm"
-        className="h-8 gap-1.5 text-destructive hover:text-destructive"
+        className="h-8 gap-1.5 text-red-400 hover:bg-background/15 hover:text-red-400"
         onClick={onTrash}
         disabled={isPending}
       >
         <IconTrash className="h-3.5 w-3.5" /> {t("navigation.trash")}
       </Button>
-      <div className="h-4 w-px bg-border mx-1" />
+      <div className="mx-1 h-4 w-px bg-background/20" />
       <button
         type="button"
         onClick={onClear}
-        className="rounded p-1 text-muted-foreground hover:bg-accent"
+        className="rounded p-1 text-background/70 hover:bg-background/15 hover:text-background"
         aria-label={t("clipsFinalRaw.clearSelection")}
       >
         <IconX className="h-3.5 w-3.5" />

package/corpus/templates/clips/app/components/library/library-grid.tsx

@@ -3,8 +3,12 @@ import {
   setClientAppState,
 } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
-import { IconAlertTriangle } from "@tabler/icons-react";
-import { useEffect, useMemo, useState } from "react";
+import {
+  IconAlertTriangle,
+  IconChevronLeft,
+  IconChevronRight,
+} from "@tabler/icons-react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { toast } from "sonner";
 
 import { CreateFolderDialog } from "@/components/library/create-folder-dialog";
@@ -13,6 +17,7 @@ import { Button } from "@/components/ui/button";
 import {
   useFolders,
   useRecordings,
+  useRecordingsCount,
   useTrashRecording,
   useArchiveRecording,
   useRestoreRecording,
@@ -54,6 +59,8 @@ function Skeleton() {
   );
 }
 
+const PAGE_SIZE = 100;
+
 interface FolderTargetRow {
   id: string;
   parentId: string | null;
@@ -105,13 +112,38 @@ export function LibraryGrid({
   const t = useT();
   const [sort, setSort] = useState<SortKey>("recent");
   const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [lastSelectedId, setLastSelectedId] = useState<string | null>(null);
   const selectionMode = selected.size > 0;
   const [sharingRec, setSharingRec] = useState<RecordingSummary | null>(null);
   const [createFolderTarget, setCreateFolderTarget] =
     useState<CreateFolderTarget | null>(null);
   const [isBulkPending, setIsBulkPending] = useState(false);
+  const [page, setPage] = useState(1);
   const selectionStateKey = useMemo(() => `selection:${getBrowserTabId()}`, []);
 
+  useEffect(() => {
+    setPage(1);
+    setSelected(new Set());
+    setLastSelectedId(null);
+  }, [view, folderId, spaceId, tagFilter, sort]);
+
+  const countArgs = useMemo(
+    () => ({
+      view,
+      folderId: folderId ?? null,
+      spaceId: spaceId ?? null,
+      tag: tagFilter ?? null,
+    }),
+    [view, folderId, spaceId, tagFilter],
+  );
+  const { data: totalCount } = useRecordingsCount(countArgs);
+  const total = totalCount ?? 0;
+  const totalPages = Math.max(1, Math.ceil(total / PAGE_SIZE));
+
+  useEffect(() => {
+    if (page > totalPages) setPage(totalPages);
+  }, [page, totalPages]);
+
   const args: ListRecordingsArgs = useMemo(
     () => ({
       view,
@@ -119,8 +151,10 @@ export function LibraryGrid({
       spaceId: spaceId ?? null,
       tag: tagFilter ?? null,
       sort,
+      limit: PAGE_SIZE,
+      offset: (page - 1) * PAGE_SIZE,
     }),
-    [view, folderId, spaceId, tagFilter, sort],
+    [view, folderId, spaceId, tagFilter, sort, page],
   );
 
   const { data, isLoading, isError, refetch, isRefetching } =
@@ -189,17 +223,53 @@ export function LibraryGrid({
     };
   }, [selectionStateKey]);
 
-  const toggleSelect = (id: string) => {
+  const handleToggleSelect = useCallback(
+    (id: string, shiftKey = false) => {
+      setSelected((prev) => {
+        if (shiftKey && lastSelectedId && lastSelectedId !== id) {
+          const ids = recordings.map((r) => r.id);
+          const fromIndex = ids.indexOf(lastSelectedId);
+          const toIndex = ids.indexOf(id);
+          if (fromIndex !== -1 && toIndex !== -1) {
+            const [start, end] =
+              fromIndex < toIndex ? [fromIndex, toIndex] : [toIndex, fromIndex];
+            const next = new Set(prev);
+            for (let i = start; i <= end; i++) next.add(ids[i]);
+            return next;
+          }
+        }
+        const next = new Set(prev);
+        if (next.has(id)) next.delete(id);
+        else next.add(id);
+        return next;
+      });
+      setLastSelectedId(id);
+    },
+    [lastSelectedId, recordings],
+  );
+
+  const allSelected =
+    recordings.length > 0 && recordings.every(({ id }) => selected.has(id));
+
+  const toggleSelectAll = useCallback(() => {
     setSelected((prev) => {
       const next = new Set(prev);
-      if (next.has(id)) next.delete(id);
-      else next.add(id);
+      const visibleIds = recordings.map(({ id }) => id);
+      const allVisibleSelected = visibleIds.every((id) => prev.has(id));
+
+      for (const id of visibleIds) {
+        if (allVisibleSelected) next.delete(id);
+        else next.add(id);
+      }
+
       return next;
     });
-  };
+    setLastSelectedId(null);
+  }, [recordings]);
 
   const clearSelection = () => {
     setSelected(new Set());
+    setLastSelectedId(null);
   };
 
   const moveRecordings = async (
@@ -321,7 +391,7 @@ export function LibraryGrid({
       )}
 
       {/* Grid body */}
-      <div className="relative flex min-h-0 flex-1 overflow-hidden">
+      <div className="relative flex min-h-0 flex-1 flex-col overflow-hidden">
         <div
           className={cn(
             "min-h-0 flex-1 overflow-y-auto",
@@ -371,7 +441,7 @@ export function LibraryGrid({
                     }
                     selectionMode={canManageRecordings && selectionMode}
                     onToggleSelect={
-                      canManageRecordings ? toggleSelect : undefined
+                      canManageRecordings ? handleToggleSelect : undefined
                     }
                     onShare={(rec) => setSharingRec(rec)}
                     moveTargets={moveTargets}
@@ -426,12 +496,51 @@ export function LibraryGrid({
           </div>
         </div>
 
+        {!isLoading && recordings.length > 0 && totalPages > 1 && (
+          <div className="flex shrink-0 items-center justify-between gap-3 border-t border-border px-5 py-2.5">
+            <span className="text-xs text-muted-foreground">
+              {t("libraryGrid.paginationRange", {
+                start: (page - 1) * PAGE_SIZE + 1,
+                end: (page - 1) * PAGE_SIZE + recordings.length,
+                total,
+              })}
+            </span>
+            <div className="flex items-center gap-2">
+              <Button
+                variant="outline"
+                size="sm"
+                className="gap-1"
+                onClick={() => setPage((p) => Math.max(1, p - 1))}
+                disabled={page <= 1}
+              >
+                <IconChevronLeft className="h-3.5 w-3.5" />
+                {t("libraryGrid.paginationPrevious")}
+              </Button>
+              <span className="text-xs text-muted-foreground">
+                {t("libraryGrid.paginationPage", { page, totalPages })}
+              </span>
+              <Button
+                variant="outline"
+                size="sm"
+                className="gap-1"
+                onClick={() => setPage((p) => Math.min(totalPages, p + 1))}
+                disabled={page >= totalPages}
+              >
+                {t("libraryGrid.paginationNext")}
+                <IconChevronRight className="h-3.5 w-3.5" />
+              </Button>
+            </div>
+          </div>
+        )}
+
         {/* Keep selected-library actions visible while the recording list scrolls. */}
         {canManageRecordings && selected.size > 0 && (
           <div className="pointer-events-none absolute inset-x-0 bottom-0 z-30 flex justify-center px-4 pb-4">
             <div className="pointer-events-auto max-w-full overflow-x-auto">
               <BulkActionToolbar
                 count={selected.size}
+                allSelected={allSelected}
+                onSelectAll={toggleSelectAll}
                 moveTargets={moveTargets}
                 onArchive={async () => {
                   setIsBulkPending(true);

package/corpus/templates/clips/app/components/library/library-layout.tsx

@@ -566,7 +566,7 @@ export function LibraryLayout({ children }: LibraryLayoutProps) {
         browserTabId={getBrowserTabId()}
       >
         {/* Main content area */}
-        <div className="flex min-w-0 flex-1 flex-col">
+        <div className="flex min-h-0 min-w-0 flex-1 flex-col">
           {!pageOwnsToolbar && (
             <header className="flex shrink-0 items-center gap-3 border-b border-border px-5 py-3">
               <button

package/corpus/templates/clips/app/components/library/recording-card.tsx

@@ -65,7 +65,7 @@ interface RecordingCardProps {
   recording: RecordingSummary;
   selected?: boolean;
   selectionMode?: boolean;
-  onToggleSelect?: (id: string) => void;
+  onToggleSelect?: (id: string, shiftKey: boolean) => void;
   onShare?: (rec: RecordingSummary) => void;
   onMove?: (rec: RecordingSummary, folderId: string | null) => void;
   moveTargets?: BulkMoveTarget[];
@@ -147,18 +147,18 @@ export function RecordingCard({
   const handleLinkClick = useCallback(
     (event: React.MouseEvent<HTMLAnchorElement>) => {
       if (
-        !selectionMode ||
+        !onToggleSelect ||
         event.button !== 0 ||
         event.metaKey ||
         event.ctrlKey ||
-        event.shiftKey ||
-        event.altKey
+        event.altKey ||
+        (!selectionMode && !event.shiftKey)
       ) {
         return;
       }
 
       event.preventDefault();
-      onToggleSelect?.(recording.id);
+      onToggleSelect(recording.id, event.shiftKey);
     },
     [onToggleSelect, recording.id, selectionMode],
   );
@@ -166,7 +166,7 @@ export function RecordingCard({
   const handleCheckbox = useCallback(
     (e: React.MouseEvent) => {
       e.stopPropagation();
-      onToggleSelect?.(recording.id);
+      onToggleSelect?.(recording.id, e.shiftKey);
     },
     [onToggleSelect, recording.id],
   );
@@ -243,8 +243,10 @@ export function RecordingCard({
           >
             <Checkbox
               checked={selected}
-              onCheckedChange={() => onToggleSelect?.(recording.id)}
-              onClick={(e) => e.stopPropagation()}
+              onClick={(e) => {
+                e.stopPropagation();
+                onToggleSelect?.(recording.id, e.shiftKey);
+              }}
               className="h-3.5 w-3.5"
             />
           </div>