@agent-native/core 0.115.4 → 0.117.0

package/corpus/templates/clips/changelog/2026-07-22-clips-transcripts-now-retry-brain-export.md

@@ -0,0 +1,5 @@
+---
+type: improved
+---
+
+Ready clip transcripts now keep an export receipt and retry Brain delivery after temporary failures.

package/corpus/templates/clips/changelog/2026-07-22-german-umlauts-and-other-non-ascii-characters-now-paste-corr.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-22
+---
+
+German umlauts and other non-ASCII characters now paste correctly from macOS dictation

package/corpus/templates/clips/desktop/src-tauri/src/clips/mod.rs

@@ -1854,7 +1854,21 @@ mod tests {
 
     #[cfg(target_os = "macos")]
     mod macos_only {
-        use super::super::chunk_graphemes_by_utf16_units;
+        use super::super::{chunk_graphemes_by_utf16_units, utf8_pasteboard_command};
+        use std::ffi::OsStr;
+
+        #[test]
+        fn pasteboard_commands_force_utf8_for_gui_launches() {
+            let command = utf8_pasteboard_command("pbcopy");
+            let env_value = |key: &str| {
+                command
+                    .get_envs()
+                    .find(|(name, _)| *name == OsStr::new(key))
+                    .and_then(|(_, value)| value)
+            };
+            assert_eq!(env_value("LANG"), Some(OsStr::new("en_US.UTF-8")));
+            assert_eq!(env_value("LC_ALL"), Some(OsStr::new("en_US.UTF-8")));
+        }
 
         #[test]
         fn never_splits_a_zwj_family_emoji_across_chunks() {
@@ -1892,9 +1906,18 @@ mod tests {
     }
 }
 
+#[cfg(target_os = "macos")]
+fn utf8_pasteboard_command(program: &str) -> Command {
+    let mut command = Command::new(program);
+    command
+        .env("LANG", "en_US.UTF-8")
+        .env("LC_ALL", "en_US.UTF-8");
+    command
+}
+
 #[cfg(target_os = "macos")]
 fn write_clipboard(text: &str) -> Result<(), String> {
-    let mut child = Command::new("pbcopy")
+    let mut child = utf8_pasteboard_command("pbcopy")
         .stdin(Stdio::piped())
         .spawn()
         .map_err(|e| format!("pbcopy spawn: {e}"))?;
@@ -1926,7 +1949,7 @@ fn write_clipboard(_text: &str) -> Result<(), String> {
 /// content on the clipboard are not preserved by the later restore.
 #[cfg(target_os = "macos")]
 fn read_clipboard() -> Option<String> {
-    let out = Command::new("pbpaste").output().ok()?;
+    let out = utf8_pasteboard_command("pbpaste").output().ok()?;
     if !out.status.success() {
         return None;
     }

package/corpus/templates/clips/jobs/emit-netlify-brain-export-cron.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env tsx
+
+import { randomBytes } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const FUNCTIONS_DIR = path.join(ROOT, ".netlify", "functions-internal");
+const SERVER_DIR = path.join(FUNCTIONS_DIR, "server");
+export const SCHEDULED_NAME = "clips-brain-export-cron";
+export const WORKER_NAME = "clips-brain-export-sweep-background";
+export const ROUTE_PATH = "/api/clips/brain-export/run";
+export const SCHEDULE = "* * * * *";
+
+function ensureDir(dir: string) {
+  mkdirSync(dir, { recursive: true });
+}
+
+export function scheduledTriggerSource(token: string) {
+  return `const WORKER_PATH = "/.netlify/functions/${WORKER_NAME}";
+const CRON_TOKEN = ${JSON.stringify(token)};
+
+export default async function handler(request) {
+  const response = await fetch(new URL(WORKER_PATH, new URL(request.url).origin), {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-agent-native-clips-brain-export-cron": CRON_TOKEN },
+    body: JSON.stringify({ scheduled: true }),
+  });
+  if (!response.ok && response.status !== 202) console.error("[clips-brain-export-cron] Background sweep trigger failed:", response.status);
+}
+
+export const config = {
+  name: "Clips Brain export cron trigger",
+  generator: "agent-native clips build",
+  schedule: ${JSON.stringify(SCHEDULE)},
+};
+`;
+}
+
+export function backgroundWorkerSource(token: string) {
+  return `globalThis.__AGENT_NATIVE_CLIPS_BRAIN_EXPORT_SCHEDULED_RUNTIME__ = true;
+const CRON_TOKEN = ${JSON.stringify(token)};
+const ROUTE_PATH = ${JSON.stringify(ROUTE_PATH)};
+let cachedHandler;
+
+function timingSafeEquals(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+export default async function handler(request, context) {
+  const token = request.headers.get("x-agent-native-clips-brain-export-cron") || "";
+  if (!timingSafeEquals(token, CRON_TOKEN)) return new Response("Unauthorized", { status: 401 });
+  cachedHandler ??= (await import("./main.mjs")).default;
+  const url = new URL(request.url);
+  url.pathname = ROUTE_PATH;
+  url.search = "";
+  return cachedHandler(new Request(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ scheduled: true }),
+  }), context);
+}
+
+export const config = {
+  name: "Clips Brain export background sweep",
+  generator: "agent-native clips build",
+  background: true,
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  preferStatic: false,
+};
+`;
+}
+
+export function emitNetlifyBrainExportCron(
+  options: {
+    functionsDir?: string;
+    serverDir?: string;
+    token?: string;
+  } = {},
+) {
+  const functionsDir = options.functionsDir ?? FUNCTIONS_DIR;
+  const serverDir = options.serverDir ?? SERVER_DIR;
+  if (!existsSync(serverDir))
+    throw new Error(
+      "Expected Nitro Netlify server output before emitting Clips Brain export functions.",
+    );
+  const token = options.token ?? randomBytes(32).toString("hex");
+  const scheduledDir = path.join(functionsDir, SCHEDULED_NAME);
+  const workerDir = path.join(functionsDir, WORKER_NAME);
+  rmSync(scheduledDir, { recursive: true, force: true });
+  rmSync(workerDir, { recursive: true, force: true });
+  ensureDir(scheduledDir);
+  cpSync(serverDir, workerDir, { recursive: true });
+  rmSync(path.join(workerDir, "server.mjs"), { force: true });
+  writeFileSync(
+    path.join(scheduledDir, `${SCHEDULED_NAME}.mjs`),
+    scheduledTriggerSource(token),
+  );
+  writeFileSync(
+    path.join(workerDir, `${WORKER_NAME}.mjs`),
+    backgroundWorkerSource(token),
+  );
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  emitNetlifyBrainExportCron();
+  console.log(
+    "[clips-brain-export-cron] Emitted scheduled export sweep and background worker.",
+  );
+}

package/corpus/templates/clips/netlify.toml

@@ -1,6 +1,6 @@
 [build]
 ignore = "node ./scripts/netlify-ignore-build.mjs clips"
-command = "export DATABASE_URL=${NETLIFY_DATABASE_URL:-$DATABASE_URL} && pnpm install && NITRO_PRESET=netlify pnpm --filter clips build"
+command = "export DATABASE_URL=${NETLIFY_DATABASE_URL:-$DATABASE_URL} && pnpm install && NITRO_PRESET=netlify pnpm --filter clips build && pnpm exec tsx templates/clips/jobs/emit-netlify-brain-export-cron.ts"
 publish = "templates/clips/dist"
 functions = "templates/clips/.netlify/functions-internal"
 
@@ -25,3 +25,6 @@ AGENT_NATIVE_SERVERLESS_FFMPEG_ARCH = "x64"
 # auto-continuation path can hand off before Netlify kills the function.
 [functions."*"]
 timeout = 75
+
+[functions.clips-brain-export-sweep-background]
+timeout = 120

package/corpus/templates/clips/scripts/configure-prod-brain-export.ts

@@ -0,0 +1,92 @@
+import { readFile } from "node:fs/promises";
+
+import { writeAppState } from "@agent-native/core/application-state";
+import { saveCredential } from "@agent-native/core/credentials";
+import { getDbExec } from "@agent-native/core/db";
+import { runWithRequestContext } from "@agent-native/core/server";
+
+const tokenFile = process.env.BRAIN_CLIPS_TOKEN_FILE;
+if (!tokenFile) throw new Error("BRAIN_CLIPS_TOKEN_FILE is required");
+const token = (await readFile(tokenFile, "utf8")).trim();
+if (!token.startsWith("brain_") || token.length < 32) {
+  throw new Error("The Brain ingest token is invalid");
+}
+
+const db = getDbExec();
+const { rows } = await db.execute({
+  sql: `SELECT id, owner_email, org_id, created_at
+    FROM recordings
+    WHERE status = ? AND trashed_at IS NULL AND created_at >= ?
+      AND EXISTS (
+        SELECT 1 FROM recording_transcripts
+        WHERE recording_transcripts.recording_id = recordings.id
+          AND recording_transcripts.status = ?
+          AND LENGTH(TRIM(COALESCE(recording_transcripts.full_text, ''))) > 0
+      )
+    ORDER BY created_at DESC
+    LIMIT ?`,
+  args: [
+    "ready",
+    new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString(),
+    "ready",
+    20,
+  ],
+});
+if (rows.length === 0)
+  throw new Error("No recent ready Clips recordings found");
+
+const recordings = rows as Array<{
+  id: string;
+  owner_email: string;
+  org_id?: string | null;
+}>;
+const ownerEmail = recordings[0]!.owner_email;
+const orgId = recordings[0]!.org_id?.trim();
+if (!ownerEmail || !orgId) {
+  throw new Error(
+    "Recent Clips recordings are missing owner or organization scope",
+  );
+}
+if (
+  recordings.some(
+    (recording) =>
+      recording.owner_email !== ownerEmail ||
+      recording.org_id?.trim() !== orgId,
+  )
+) {
+  throw new Error(
+    "Recent Clips recordings span multiple owners or organizations",
+  );
+}
+
+await saveCredential(
+  "BRAIN_INGEST_URL",
+  "https://brain.agent-native.com/api/_agent-native/brain/ingest",
+  { userEmail: ownerEmail, orgId, scope: "org" },
+);
+await saveCredential("BRAIN_INGEST_TOKEN", token, {
+  userEmail: ownerEmail,
+  orgId,
+  scope: "org",
+});
+
+await runWithRequestContext({ userEmail: ownerEmail, orgId }, async () => {
+  const now = new Date().toISOString();
+  for (const recording of recordings) {
+    await writeAppState(`clips-brain-export-${recording.id}`, {
+      recordingId: recording.id,
+      status: "pending",
+      attempts: 0,
+      updatedAt: now,
+      nextAttemptAt: now,
+    });
+  }
+});
+
+console.log(
+  JSON.stringify({
+    configured: true,
+    queued: recordings.length,
+    organizationScoped: true,
+  }),
+);

package/corpus/templates/clips/server/jobs/brain-export.ts

@@ -0,0 +1,182 @@
+import { getDbExec } from "@agent-native/core/db";
+import { runWithRequestContext } from "@agent-native/core/server";
+import { and, eq, isNull } from "drizzle-orm";
+
+import exportToBrain from "../../actions/export-to-brain.js";
+import { getDb, schema } from "../db/index.js";
+import {
+  BRAIN_EXPORT_STATE_PREFIX,
+  parseBrainExportState,
+  writeBrainExportState,
+} from "../lib/brain-export-state.js";
+import { ownerEmailMatches } from "../lib/recordings.js";
+
+const SWEEP_INTERVAL_MS = 60_000;
+const MAX_ATTEMPTS = 8;
+const SWEEP_LIMIT = 4;
+const DISCOVERY_LIMIT = 20;
+const BACKFILL_DAYS = 7;
+let skippingLogged = false;
+
+async function seedRecentBrainExports(): Promise<void> {
+  const now = new Date();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT recordings.id, recordings.owner_email, recordings.org_id
+      FROM recordings
+      INNER JOIN recording_transcripts
+        ON recording_transcripts.recording_id = recordings.id
+      WHERE recordings.status = ?
+        AND recordings.trashed_at IS NULL
+        AND recordings.org_id IS NOT NULL
+        AND recordings.created_at >= ?
+        AND recording_transcripts.status = ?
+        AND LENGTH(TRIM(COALESCE(recording_transcripts.full_text, ''))) > 0
+        AND NOT EXISTS (
+          SELECT 1 FROM application_state
+          WHERE application_state.session_id = recordings.owner_email
+            AND application_state.key = ? || recordings.id
+        )
+      ORDER BY recordings.created_at DESC
+      LIMIT ?`,
+    args: [
+      "ready",
+      new Date(
+        now.getTime() - BACKFILL_DAYS * 24 * 60 * 60 * 1000,
+      ).toISOString(),
+      "ready",
+      BRAIN_EXPORT_STATE_PREFIX,
+      DISCOVERY_LIMIT,
+    ],
+  });
+  for (const row of rows as Array<{
+    id?: unknown;
+    owner_email?: unknown;
+    org_id?: unknown;
+  }>) {
+    const recordingId = typeof row.id === "string" ? row.id.trim() : "";
+    const ownerEmail =
+      typeof row.owner_email === "string" ? row.owner_email.trim() : "";
+    const orgId = typeof row.org_id === "string" ? row.org_id.trim() : "";
+    if (!recordingId || !ownerEmail || !orgId) continue;
+    await runWithRequestContext({ userEmail: ownerEmail, orgId }, () =>
+      writeBrainExportState({
+        recordingId,
+        status: "pending",
+        attempts: 0,
+        updatedAt: now.toISOString(),
+        nextAttemptAt: now.toISOString(),
+      }),
+    );
+  }
+}
+
+export async function runBrainExportSweepOnce(): Promise<void> {
+  await seedRecentBrainExports();
+  const { rows } = await getDbExec().execute({
+    sql: "SELECT session_id, key, value FROM application_state WHERE key LIKE ? AND (value LIKE ? OR value LIKE ?) ORDER BY updated_at ASC LIMIT ?",
+    args: [
+      `${BRAIN_EXPORT_STATE_PREFIX}%`,
+      '%"status":"pending"%',
+      '%"status":"failed"%',
+      SWEEP_LIMIT,
+    ],
+  });
+  const now = Date.now();
+  for (const row of rows as Array<{
+    session_id?: unknown;
+    key?: unknown;
+    value?: unknown;
+  }>) {
+    const ownerEmail =
+      typeof row.session_id === "string" ? row.session_id.trim() : "";
+    const key = typeof row.key === "string" ? row.key : "";
+    const recordingId = key.slice(BRAIN_EXPORT_STATE_PREFIX.length);
+    let raw: unknown;
+    try {
+      raw = JSON.parse(typeof row.value === "string" ? row.value : "");
+    } catch {
+      continue;
+    }
+    const state = parseBrainExportState(raw);
+    if (
+      !ownerEmail ||
+      !recordingId ||
+      !state ||
+      state.recordingId !== recordingId ||
+      !["pending", "failed"].includes(state.status) ||
+      state.attempts >= MAX_ATTEMPTS ||
+      Date.parse(state.nextAttemptAt ?? "") > now
+    )
+      continue;
+    try {
+      const [recording] = await getDb()
+        .select({
+          ownerEmail: schema.recordings.ownerEmail,
+          orgId: schema.recordings.orgId,
+        })
+        .from(schema.recordings)
+        .where(
+          and(
+            eq(schema.recordings.id, recordingId),
+            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+            eq(schema.recordings.status, "ready"),
+            isNull(schema.recordings.trashedAt),
+          ),
+        )
+        .limit(1);
+      if (!recording) continue;
+      await runWithRequestContext(
+        {
+          userEmail: recording.ownerEmail,
+          orgId: recording.orgId ?? undefined,
+        },
+        () =>
+          exportToBrain.run({ recordingId, retryAttempt: state.attempts + 1 }),
+      );
+    } catch (error) {
+      const attempts = state.attempts + 1;
+      await runWithRequestContext({ userEmail: ownerEmail }, () =>
+        writeBrainExportState({
+          recordingId,
+          status: "failed",
+          attempts,
+          reason: "brain-export-worker-failed",
+          updatedAt: new Date().toISOString(),
+          nextAttemptAt: new Date(
+            Date.now() +
+              Math.min(15 * 60_000, 30_000 * 2 ** Math.max(0, attempts - 1)),
+          ).toISOString(),
+        }),
+      );
+      console.warn("[brain-export] sweep item failed", {
+        recordingId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}
+
+export default function registerBrainExportJob(): void {
+  if (process.env.NETLIFY === "true") return;
+  const enabled =
+    process.env.RUN_BACKGROUND_JOBS === "1" ||
+    (process.env.NODE_ENV === "production" &&
+      process.env.RUN_BACKGROUND_JOBS !== "0");
+  if (!enabled) {
+    if (process.env.DEBUG && !skippingLogged) {
+      console.log(
+        "[brain-export] Skipping background sweep (set RUN_BACKGROUND_JOBS=1 to enable in dev).",
+      );
+      skippingLogged = true;
+    }
+    return;
+  }
+  setInterval(() => {
+    runBrainExportSweepOnce().catch((error) =>
+      console.error("[brain-export] interval failed:", error),
+    );
+  }, SWEEP_INTERVAL_MS);
+  console.log(
+    `[brain-export] Recurring recovery sweep every ${SWEEP_INTERVAL_MS / 1000}s.`,
+  );
+}

package/corpus/templates/clips/server/lib/brain-export-state.ts

@@ -0,0 +1,42 @@
+import { writeAppState } from "@agent-native/core/application-state";
+
+export const BRAIN_EXPORT_STATE_PREFIX = "clips-brain-export-";
+
+export type BrainExportState = {
+  recordingId: string;
+  status: "pending" | "exported" | "quarantined" | "failed" | "skipped";
+  attempts: number;
+  updatedAt: string;
+  nextAttemptAt?: string;
+  captureId?: string;
+  sensitivityReceiptId?: string;
+  sensitivityDisposition?: string;
+  reason?: string;
+};
+
+export function brainExportStateKey(recordingId: string): string {
+  return `${BRAIN_EXPORT_STATE_PREFIX}${recordingId}`;
+}
+
+export async function writeBrainExportState(state: BrainExportState) {
+  await writeAppState(brainExportStateKey(state.recordingId), state);
+}
+
+export function parseBrainExportState(value: unknown): BrainExportState | null {
+  if (!value || typeof value !== "object") return null;
+  const state = value as Partial<BrainExportState>;
+  if (
+    typeof state.recordingId !== "string" ||
+    !state.recordingId ||
+    !["pending", "exported", "quarantined", "failed", "skipped"].includes(
+      String(state.status),
+    ) ||
+    typeof state.attempts !== "number" ||
+    !Number.isInteger(state.attempts) ||
+    state.attempts < 0 ||
+    typeof state.updatedAt !== "string"
+  ) {
+    return null;
+  }
+  return state as BrainExportState;
+}

package/corpus/templates/clips/server/lib/post-finalize-dispatch.ts

@@ -7,7 +7,11 @@ import {
   signScopedAgentAccessToken,
 } from "@agent-native/core/server";
 
-export type PostFinalizeJobKind = "media-ready" | "seekable" | "transcript";
+export type PostFinalizeJobKind =
+  | "media-ready"
+  | "seekable"
+  | "transcript"
+  | "brain-export";
 
 export const POST_FINALIZE_JOB_TOKEN_KIND = "clips-post-finalize-job";
 

package/corpus/templates/clips/server/plugins/calendar-jobs.ts

@@ -5,6 +5,7 @@
  * pattern).
  */
 
+import registerBrainExportJob from "../jobs/brain-export.js";
 import registerBuilderMediaCompressionJob from "../jobs/builder-media-compression.js";
 import registerMediaVerificationJob from "../jobs/media-verification.js";
 import registerMeetingRemindersJob from "../jobs/meeting-reminders.js";
@@ -17,6 +18,7 @@ export default () => {
   // background loop is off.
   registerMeetingRemindersJob();
   registerBuilderMediaCompressionJob();
+  registerBrainExportJob();
   registerMediaVerificationJob();
   registerPollCalendarsJob();
   registerStaleMeetingSweeperJob();

package/corpus/templates/clips/server/register-secrets.ts

@@ -219,6 +219,48 @@ registerRequiredSecret({
   required: false,
 });
 
+// ── Brain transcript ingest ──────────────────────────────────────────
+// Both values are workspace-scoped: every clip in the workspace must reach
+// the same Brain source, while the encrypted secret store keeps the token out
+// of action responses, application state, and client bundles.
+
+registerRequiredSecret({
+  key: "BRAIN_INGEST_URL",
+  label: "Brain ingest URL",
+  description:
+    "Signed Brain generic-ingest endpoint for ready Clips transcripts. Pair with BRAIN_INGEST_TOKEN.",
+  scope: "workspace",
+  kind: "api-key",
+  required: false,
+  validator: (value) => {
+    if (!value) return true;
+    try {
+      const url = new URL(value);
+      return url.protocol === "http:" || url.protocol === "https:"
+        ? true
+        : { ok: false, error: "Use an HTTP or HTTPS URL." };
+    } catch {
+      return { ok: false, error: "Enter a valid ingest URL." };
+    }
+  },
+});
+
+registerRequiredSecret({
+  key: "BRAIN_INGEST_TOKEN",
+  label: "Brain ingest token",
+  description:
+    "Bearer token for the configured Brain ingest URL. Stored encrypted and never returned to Clips clients or export receipts.",
+  scope: "workspace",
+  kind: "api-key",
+  required: false,
+  validator: (value) => {
+    if (!value) return true;
+    return typeof value === "string" && value.trim().length >= 8
+      ? true
+      : { ok: false, error: "Token looks too short." };
+  },
+});
+
 // ── Dark-launched media worker plumbing ──────────────────────────────
 // These are optional until the ai-services worker is deployed. When enabled,
 // Clips enqueues background video compression jobs there instead of using

package/corpus/templates/clips/server/routes/api/_agent-native-background/post-finalize-worker.post.ts

@@ -11,6 +11,7 @@ import {
 } from "h3";
 import { z } from "zod";
 
+import exportToBrain from "../../../../actions/export-to-brain.js";
 import finalizeRecording from "../../../../actions/finalize-recording.js";
 import { ensureRecordingSeekable } from "../../../../actions/lib/ensure-seekable-video.js";
 import requestTranscript from "../../../../actions/request-transcript.js";
@@ -23,7 +24,7 @@ import {
 
 const bodySchema = z.object({
   recordingId: z.string().min(1).max(200),
-  kind: z.enum(["media-ready", "seekable", "transcript"]),
+  kind: z.enum(["media-ready", "seekable", "transcript", "brain-export"]),
   token: z.string().min(1),
   delayMs: z.number().int().min(0).max(30_000).optional(),
   retryAttempt: z.number().int().min(1).max(10).optional(),
@@ -111,6 +112,14 @@ export default defineEventHandler(async (event: H3Event) => {
         return { ok: true, kind, result };
       }
 
+      if (kind === "brain-export") {
+        const result = await exportToBrain.run({
+          recordingId,
+          retryAttempt,
+        });
+        return { ok: true, kind, result };
+      }
+
       const result = await requestTranscript.run({
         recordingId,
         force: true,

package/corpus/templates/clips/server/routes/api/clips/brain-export/run.post.ts

@@ -0,0 +1,45 @@
+import { timingSafeEqual } from "node:crypto";
+
+import { createError, defineEventHandler, getHeader } from "h3";
+
+import { runBrainExportSweepOnce } from "../../../../jobs/brain-export.js";
+
+declare global {
+  var __AGENT_NATIVE_CLIPS_BRAIN_EXPORT_SCHEDULED_RUNTIME__:
+    | boolean
+    | undefined;
+}
+
+function productionLike() {
+  return (
+    process.env.NODE_ENV === "production" || process.env.NETLIFY === "true"
+  );
+}
+
+function headerMatchesSecret(header: string | undefined, secret: string) {
+  const expected = `Bearer ${secret}`;
+  const value = header?.trim() ?? "";
+  return (
+    value.length === expected.length &&
+    timingSafeEqual(Buffer.from(value), Buffer.from(expected))
+  );
+}
+
+export default defineEventHandler(async (event) => {
+  const scheduled =
+    globalThis.__AGENT_NATIVE_CLIPS_BRAIN_EXPORT_SCHEDULED_RUNTIME__ === true;
+  const secret = process.env.CLIPS_BRAIN_EXPORT_JOBS_SECRET?.trim(); // guard:allow-env-credential — deployment scheduler route secret
+  if (!secret && productionLike() && !scheduled)
+    throw createError({
+      statusCode: 503,
+      statusMessage: "CLIPS_BRAIN_EXPORT_JOBS_SECRET is required",
+    });
+  if (
+    secret &&
+    !scheduled &&
+    !headerMatchesSecret(getHeader(event, "authorization"), secret)
+  )
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  await runBrainExportSweepOnce();
+  return { ok: true };
+});

package/corpus/templates/content/.agents/skills/agent-native-toolkit/SKILL.md

@@ -85,7 +85,10 @@ in the moment of agent use.
   approval, generative UI, progress, and screen-state exposure.
 - **Chat history kit**: presentational chat lists and recent-chat rails belong
   in Toolkit; Core keeps thread persistence, agent execution, transport, and
-  page-to-sidebar handoff. Apps inject routing, labels, and domain actions.
+  page-to-sidebar handoff. Use Toolkit's `ChatHistoryRail` for the standard
+  five-item sidebar preview and a footer row with New chat followed by an
+  ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
+  actions.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home