@agent-native/core 0.157.1 → 0.157.2

package/corpus/templates/calendar/server/handlers/bookings.ts

@@ -483,7 +483,12 @@ async function resolveAvailabilityContext({
             draft
               ? and(
                   eq(schema.bookingLinks.slug, slug),
-                  accessFilter(schema.bookingLinks, schema.bookingLinkShares),
+                  accessFilter(
+                    schema.bookingLinks,
+                    schema.bookingLinkShares,
+                    undefined,
+                    "editor",
+                  ),
                 )
               : eq(schema.bookingLinks.slug, slug),
           )

package/corpus/templates/clips/actions/request-recording-access.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import { defineAction } from "@agent-native/core";
 import { notify } from "@agent-native/core/notifications";
 import {
@@ -19,7 +21,7 @@ import { and, eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
-import { nanoid, normalizeOwnerEmail } from "../server/lib/recordings.js";
+import { normalizeOwnerEmail } from "../server/lib/recordings.js";
 import {
   CLIPS_ACCESS_REQUEST_TOKEN_PREFIX,
   recordingSharePath,
@@ -27,6 +29,20 @@ import {
 
 export const CLIPS_ACCESS_REQUEST_EMAIL_ID = "clips.access-request";
 
+function accessRequestEventId(
+  recordingId: string,
+  requesterEmail: string,
+): string {
+  return (
+    "access-request-" +
+    createHash("sha256")
+      .update(recordingId)
+      .update("\0")
+      .update(requesterEmail)
+      .digest("hex")
+  );
+}
+
 function httpError(message: string, statusCode: number): Error {
   return Object.assign(new Error(message), { statusCode });
 }
@@ -211,19 +227,36 @@ export default defineAction({
       getRequestUserName()?.trim() ||
       displayNameForEmail(normalizedRequesterEmail);
     const requestedAt = new Date().toISOString();
-    await db.insert(schema.recordingEvents).values({
-      id: nanoid(),
-      recordingId,
-      viewerId: null,
-      kind: "access-request",
-      timestampMs: 0,
-      payload: JSON.stringify({
-        requesterEmail: normalizedRequesterEmail,
-        requesterName,
-        requestedAt,
-      }),
-      createdAt: requestedAt,
-    });
+    const [insertedRequest] = await db
+      .insert(schema.recordingEvents)
+      .values({
+        id: accessRequestEventId(recordingId, normalizedRequesterEmail),
+        recordingId,
+        viewerId: null,
+        kind: "access-request",
+        timestampMs: 0,
+        payload: JSON.stringify({
+          requesterEmail: normalizedRequesterEmail,
+          requesterName,
+          requestedAt,
+        }),
+        createdAt: requestedAt,
+      })
+      .onConflictDoNothing()
+      .returning({ id: schema.recordingEvents.id });
+
+    // Historical requests use random IDs, so the read above still handles
+    // them. New requests use a deterministic primary key so concurrent
+    // callers have one database-backed winner before notifications are sent.
+    if (!insertedRequest) {
+      return {
+        ok: true as const,
+        alreadyHasAccess: false,
+        alreadyRequested: true,
+        notifiedOwner: false,
+        message: "Your access request is already with the clip owner.",
+      };
+    }
 
     const ownerEmail = recording.ownerEmail
       ? normalizeOwnerEmail(recording.ownerEmail)

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/reset-chunks.post.ts

@@ -57,6 +57,7 @@ import {
   deleteResumableSession,
   getResumableSession,
   setResumableSession,
+  type StoredResumableSession,
 } from "../../../../lib/resumable-session.js";
 import { abortResumableUploadSession } from "../../../../lib/resumable-upload-cleanup.js";
 import { shouldEnableStreamingUpload } from "../../../../lib/streaming-upload-mode.js";
@@ -74,6 +75,66 @@ interface CompressionMeta {
   outputMimeType?: string;
 }
 
+interface PendingResumableCleanup {
+  recordingId: string;
+  generationId: string | null;
+  ownerGenerationId: string | null;
+  claimId: string | null;
+  session: StoredResumableSession;
+}
+
+function parsePendingResumableCleanup(
+  raw: Record<string, unknown> | null,
+  recordingId: string,
+): PendingResumableCleanup | null {
+  if (!raw) return null;
+  const session = raw.session;
+  const generationId = raw.generationId;
+  const ownerGenerationId = raw.ownerGenerationId;
+  const claimId = raw.claimId;
+  if (
+    raw.recordingId !== recordingId ||
+    !session ||
+    typeof session !== "object" ||
+    Array.isArray(session) ||
+    !(generationId === null || typeof generationId === "string") ||
+    (ownerGenerationId !== undefined &&
+      ownerGenerationId !== null &&
+      typeof ownerGenerationId !== "string") ||
+    (claimId !== undefined && claimId !== null && typeof claimId !== "string")
+  ) {
+    throw new Error(
+      `Invalid resumable cleanup state for recording ${recordingId}`,
+    );
+  }
+
+  const candidate = session as Record<string, unknown>;
+  if (
+    typeof candidate.providerId !== "string" ||
+    typeof candidate.sessionId !== "string" ||
+    !candidate.meta ||
+    typeof candidate.meta !== "object" ||
+    Array.isArray(candidate.meta) ||
+    typeof candidate.bytesUploaded !== "number" ||
+    !Number.isFinite(candidate.bytesUploaded) ||
+    (candidate.lastCommittedIndex !== undefined &&
+      typeof candidate.lastCommittedIndex !== "number")
+  ) {
+    throw new Error(
+      `Invalid resumable session in cleanup state for recording ${recordingId}`,
+    );
+  }
+
+  return {
+    recordingId,
+    generationId,
+    ownerGenerationId:
+      ownerGenerationId === undefined ? null : ownerGenerationId,
+    claimId: claimId === undefined ? null : claimId,
+    session: candidate as unknown as StoredResumableSession,
+  };
+}
+
 function normalizeVideoMimeType(value: unknown): string | null {
   if (typeof value !== "string") return null;
   const mimeType = value.split(";")[0]?.trim().toLowerCase();
@@ -219,10 +280,25 @@ export default defineEventHandler(async (event: H3Event) => {
     const nextGenerationId = useGenerationFence ? randomUUID() : null;
     const uploadStateKey = `recording-upload-${recordingId}`;
     const uploadStateSnapshot = await readAppState(uploadStateKey);
-    const discardedResumableSession = await getResumableSession(
+    const cleanupStateKey = `recording-resumable-cleanup-${recordingId}`;
+    const cleanupStateSnapshot = await readAppState(cleanupStateKey);
+    const parsedCleanup = parsePendingResumableCleanup(
+      cleanupStateSnapshot,
       recordingId,
-      existingGenerationId,
     );
+    const pendingCleanup =
+      parsedCleanup &&
+      (parsedCleanup.ownerGenerationId === null
+        ? !useGenerationFence
+        : parsedCleanup.ownerGenerationId === existingGenerationId)
+        ? parsedCleanup
+        : null;
+    const discardedGenerationId = pendingCleanup
+      ? pendingCleanup.generationId
+      : existingGenerationId;
+    const discardedResumableSession =
+      pendingCleanup?.session ??
+      (await getResumableSession(recordingId, existingGenerationId));
     const reset = await db
       .update(schema.recordings)
       .set({
@@ -257,29 +333,63 @@ export default defineEventHandler(async (event: H3Event) => {
       };
     }
 
+    let cleanupClaim: PendingResumableCleanup | null = null;
     if (discardedResumableSession) {
-      const cleaned = await abortResumableUploadSession(
-        discardedResumableSession,
-        { label: `reset-${recordingId}` },
+      // A cleanup claim belongs to the generation that won this fence. A
+      // losing reset must never resurrect a claim after the winner releases
+      // it, and a later winner must be able to transfer an unfinished claim.
+      const candidate: PendingResumableCleanup = {
+        recordingId,
+        generationId: discardedGenerationId,
+        ownerGenerationId: nextGenerationId,
+        claimId: randomUUID(),
+        session: discardedResumableSession,
+      };
+      const claimed = await compareAndSetAppState(
+        cleanupStateKey,
+        cleanupStateSnapshot,
+        candidate as unknown as Record<string, unknown>,
       );
-      if (!cleaned) {
-        setResponseStatus(event, 502);
-        return {
-          error:
-            "The previous recording upload could not be cleaned up. Retry the upload restart.",
-        };
+      if (claimed) cleanupClaim = candidate;
+    }
+
+    if (discardedResumableSession) {
+      if (cleanupClaim) {
+        const cleaned = await abortResumableUploadSession(
+          discardedResumableSession,
+          { label: `reset-${recordingId}` },
+        );
+        if (!cleaned) {
+          setResponseStatus(event, 502);
+          return {
+            error:
+              "The previous recording upload could not be cleaned up. Retry the upload restart.",
+          };
+        }
+        const released = await compareAndSetAppState(
+          cleanupStateKey,
+          cleanupClaim as unknown as Record<string, unknown>,
+          null,
+        );
+        if (!released) {
+          console.warn(
+            `[reset-chunks-${recordingId}] cleanup claim changed while releasing it`,
+          );
+        }
       }
     }
     const cleared = await deleteRecordingChunks(
       ownerEmail,
       recordingId,
-      existingGenerationId,
+      discardedGenerationId,
     );
     // Clear any stale resumable session so a buffered retry does not
     // accidentally route through handleResumableChunk with stale offsets.
-    await deleteResumableSession(recordingId, existingGenerationId).catch(
-      () => {},
-    );
+    if (!discardedResumableSession || cleanupClaim) {
+      await deleteResumableSession(recordingId, discardedGenerationId).catch(
+        () => {},
+      );
+    }
 
     let uploadMode: UploadMode = "buffered";
     let compensateStartedSession: (() => Promise<void>) | null = null;

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/notifications/routes.d.ts

@@ -11,14 +11,14 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -26,8 +26,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/docs/content/cloneable-saas.mdx

@@ -1,19 +1,17 @@
 ---
 title: "Templates"
-description: "Start from a working SaaS product and make it yours — agent included."
+description: "Start from a complete SaaS product with a UI, database, auth, and agent already built."
 ---
 
 # Templates
 
-Want to ship your own AI-powered analytics tool? Mail client? Forms builder? Pick a template, and you've got a working SaaS in minutes — agent, database, auth, and deploy pipeline already wired up.
+Agent-Native apps come in two shapes: templates, which have a full browser UI, and automation-first apps, which don't — a Slack bot, a nightly report, a webhook responder. This doc covers templates; see [Automation-First Apps](/docs/pure-agent-apps) for the other shape.
 
-Most starter templates give you a blank scaffold and a long TODO list. Agent-native flips that. Each template is a **complete, SaaS-grade product** — already runnable on day one, already shippable, and entirely yours to customize, brand, and deploy. Think of them as Cloneable SaaS, not starter kits: you're starting from a finished product, not staring at boilerplate.
-
-Building a workflow with no browser UI at all — a Slack bot, a nightly report, a webhook responder? See [Automation-First Apps](/docs/pure-agent-apps) instead; the templates on this page all ship a full browser UI alongside the agent.
+A template is a complete SaaS product: a UI, database, auth, and agent, already built and wired together. Pick one, brand it, and deploy it as your own product instead of starting from a blank scaffold. This model is called Cloneable SaaS: you start from a finished product, not a scaffold.
 
 ## Example apps {#catalog}
 
-Each one is a real app you could use today, and the launching pad for your own version of it.
+Each app is a complete product you can run today and customize into your own.
 
 | App                                       | What it is                                                                                                                   |
 | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
@@ -31,9 +29,9 @@ Each one is a real app you could use today, and the launching pad for your own v
 | [**Plan**](/docs/template-plan)           | Visual plans and PR recaps with diagrams, wireframes, and annotations.                                                       |
 | [**Dispatch**](/docs/template-dispatch)   | The workspace control plane: shared secrets, reusable integrations, Slack/Telegram, scheduled jobs.                          |
 
-Don't want a domain app? Use [Chat](/docs/template-chat) when you want a basic app users can talk to immediately and extend with actions, native results, and screens. Use [Automation-First Apps](/docs/pure-agent-apps) only when the workflow truly does not need a browser UI yet.
+If none of these match your domain, start with [Chat](/docs/template-chat) and extend it with actions, native results, and screens. Use [Automation-First Apps](/docs/pure-agent-apps) if your workflow doesn't need a browser UI.
 
-See the full catalog under [Apps](/apps), or jump straight to one — for example, [Dispatch](/docs/template-dispatch) is a great place to start if you want a workspace-style app.
+Each app has its own docs covering its architecture, actions, and customization. Browse live hosted versions at [agent-native.com/apps](/apps), or start with [Dispatch](/docs/template-dispatch) for a workspace-style app.
 
 ## Community templates {#community-templates}
 
@@ -151,20 +149,20 @@ details, the tested CLI command, and an optional hosted demo URL.
 
 ## What you get out of the box {#what-you-get}
 
-Every example app ships with the parts that normally take months to build:
+Every example app includes:
 
-- **A working agent** — already wired into the app, already able to take actions on your data, already context-aware about what you're looking at. See [Messaging the agent](/docs/messaging) for how it works.
-- **Auth** — sign in, sessions, organizations, multi-tenant isolation. Already done.
-- **A database** — every example app has its schema, queries, and migrations ready to go. Bring your own SQL database (Postgres, SQLite, Turso, D1) — the framework adapts.
-- **A real-time UI** — the screen stays in sync with what the agent does. Click "draft an email" in chat, watch the draft appear in your inbox immediately.
-- **Deploy-ready** — push to Netlify, Vercel, Cloudflare, AWS, or anywhere else that runs Node. No vendor lock-in.
-- **Branding hooks** — name, colors, logo, copy are all easy to change.
+- **A working agent** — wired into the app, able to take actions on your data, and aware of what you're looking at. See [Messaging the agent](/docs/messaging).
+- **Auth** — sign-in, sessions, organizations, and multi-tenant isolation.
+- **A database** — schema, queries, and migrations, ready to use. Bring your own SQL database (Postgres, SQLite, Turso, D1); the framework adapts.
+- **A real-time UI** — the screen stays in sync with the agent. For example, drafting an email in chat updates the inbox immediately.
+- **Deploy-ready** — deploy to Netlify, Vercel, Cloudflare, AWS, or any host that runs Node.
+- **Branding hooks** — change the name, colors, logo, and copy.
 
-This isn't a theoretical claim. The framework's author runs his actual inbox on the Mail app, his actual calendar on the Calendar app, and his actual analytics on the Analytics app. These are daily-driver apps.
+The framework's maintainer runs his email, calendar, and analytics on the Mail, Calendar, and Analytics apps.
 
 ## What you do {#what-you-do}
 
-The path from "I want my own SaaS" to "I have my own SaaS" is short:
+Four steps take you from template to deployed app:
 
 <Diagram id="doc-block-1ab5jb9" title="Start from a working app" summary="Pick a finished product, brand it, evolve it in plain English, and ship it to your own domain.">
 
@@ -214,21 +212,21 @@ The path from "I want my own SaaS" to "I have my own SaaS" is short:
 
 </Diagram>
 
-1. **Pick an example app.** Use the CLI picker, or browse the docs and pick one to start from.
+1. **Pick an app.** Use the CLI picker, or browse the docs.
 2. **Brand it.** Change the name, colors, logo, and copy. Most example apps expose this in a single config file.
 3. **Customize it.** Make source changes in your own repository and development workflow. An agent can help when its frame is intentionally granted workspace and write tooling; otherwise the embedded agent operates the resulting app through its actions, data, and configured integrations.
-4. **Ship it.** Run the deploy command. You now have your own production SaaS at your own domain.
+4. **Ship it.** Run the deploy command. You now have a production app at your own domain.
 
-Steps 2–4 typically take days, not months. Step 3 is open-ended because the app is yours to evolve, while the embedded agent remains available to operate the deployed product and can assist with source changes when code access is explicitly enabled.
+Steps 2–4 typically take a few days. Step 3 has no fixed end point — the app is yours to evolve, while the embedded agent remains available to operate the deployed product and can assist with source changes when code access is explicitly enabled.
 
 ## Why this is practical {#why}
 
-A separate-codebase-per-user model breaks down at scale: every user maintaining their own inbox sounds like a maintenance nightmare. Two framework decisions make it work:
+A separate codebase per user doesn't scale — maintaining a fork of the app for every user becomes unmanageable. Two framework decisions avoid that:
 
 1. **The app keeps the framework contract.** Your source owns the domain behavior, while Core keeps actions, SQL, state, and sync consistent as the app evolves.
 2. **Per-user customization without per-user code.** Skills, memory, instructions, connected MCP servers, and sub-agents all live in SQL. Every user gets their own customization layer; the shared codebase hosts all of them at once.
 
-The result: Claude-Code-level flexibility for each user, with normal SaaS deployment economics.
+The result: per-user customization without per-user deployments.
 
 <Diagram id="doc-block-bhg7mw" title="Why per-user customization scales" summary={"Two ideas keep the start-from-a-working-app model practical: the app keeps the framework contract, and per-user customization lives in SQL — not in per-user code."}>
 
@@ -275,11 +273,11 @@ The result: Claude-Code-level flexibility for each user, with normal SaaS deploy
 
 ## Don't want to customize? {#hosted}
 
-You don't have to. Every example app is also available as a hosted app on `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, and so on. Use the hosted version for free or paid; create your own app from a template when you want to change something the hosted version doesn't expose.
+Every example app is also available as a hosted product on `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, and so on. Use the hosted version for free or paid; create your own app from a template when you want to change something the hosted version doesn't expose.
 
 ## Try it with a skill {#try-with-a-skill}
 
-Not ready to scaffold? You can add agent-native superpowers to a coding agent you already use with a single command — no app needed. See the [Skills Guide](/docs/skills-guide#app-backed-skills).
+You can add Agent-Native capabilities to a coding agent you already use, without scaffolding an app. See the [Skills Guide](/docs/skills-guide#app-backed-skills).
 
 ## What's next
 
@@ -292,7 +290,7 @@ Not ready to scaffold? You can add agent-native superpowers to a coding agent yo
 
 ### For developers {#dev-details}
 
-If you're scaffolding now, the CLI command is:
+To scaffold a new app:
 
 ```bash
 npx @agent-native/core@latest create my-platform
@@ -306,7 +304,7 @@ scaffolded into `apps/<name>/` with every file you need. For a no-browser
 automation instead of an app UI, use
 `npx @agent-native/core@latest create my-agent --headless`.
 
-Fill in `.env` (mostly `ANTHROPIC_API_KEY` and `DATABASE_URL`), `pnpm install`, `pnpm dev`, and it works. No "TODO: implement login," no placeholder routes.
+Fill in `.env` (`ANTHROPIC_API_KEY` and `DATABASE_URL`), then run `pnpm install` and `pnpm dev`. There's no login to implement and no placeholder routes.
 
 Deploy targets: any Nitro-compatible host (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) and any Drizzle-compatible SQL database (SQLite, Postgres, Turso, D1, Supabase, Neon). For workspaces, `npx @agent-native/core@latest deploy` builds every app at once and ships them behind a single origin. See [Deployment](/docs/deployment).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.157.1",
+  "version": "0.157.2",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -423,8 +423,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.4",
-    "@agent-native/toolkit": "^0.15.1"
+    "@agent-native/toolkit": "^0.15.1",
+    "@agent-native/recap-cli": "0.5.4"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",