@agent-native/core 0.92.9 → 0.92.11

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

@@ -579,7 +579,10 @@ class CollabDocConnection {
     this.awareness.setLocalStateField("visible", !isDocumentHidden());
   }
 
-  private handleAwarenessChange = (): void => {
+  private handleAwarenessChange = (
+    _changes?: { added: number[]; updated: number[]; removed: number[] },
+    origin?: unknown,
+  ): void => {
     const users: CollabUser[] = [];
     let hasAgent = false;
     this.awareness.getStates().forEach((state, clientId) => {
@@ -616,12 +619,20 @@ class CollabDocConnection {
       this.setSnapshot({ activeUsers, agentPresent: hasAgent });
     }
 
-    // Fast awareness push: whenever awareness changes (e.g. cursor moves,
-    // setPresence() calls), schedule a throttled POST so peers receive updates
-    // at ~150ms instead of waiting for the next poll cycle. Only active once a
+    // Fast awareness push: whenever OUR OWN awareness state changes (e.g.
+    // cursor moves, setPresence() calls), schedule a throttled POST so peers
+    // receive updates at ~150ms instead of waiting for the next poll cycle.
+    // Gated on origin === "local": this listener also fires for remote
+    // awareness changes (poll/SSE call `awareness.emit("change", [changes,
+    // "remote"])` after reconciling incoming states — see
+    // applyAwarenessEvent/poll above). Without the origin check, every
+    // peer's cursor move would also re-trigger THIS client to re-broadcast
+    // its own unchanged state, turning one person moving their mouse into
+    // O(n) redundant POSTs from every other connected client (an awareness
+    // storm that gets worse as more people join the doc). Only active once a
     // local user identity has been published (matches the previous per-hook
     // gating on `user`). The poll cycle remains the authoritative baseline.
-    if (this.lastSetUser && !this.disposed) {
+    if (this.lastSetUser && origin === "local" && !this.disposed) {
       scheduleAwarenessPush(
         this.baseUrl,
         this.docId,

package/corpus/core/src/collab/index.ts

@@ -126,6 +126,10 @@ export {
   type AwarenessEntry,
   type AwarenessChangeEvent,
 } from "./awareness.js";
+export {
+  loadAwarenessRows,
+  loadAwarenessRowsStrict,
+} from "./awareness-store.js";
 
 // Presence kit
 export {

package/corpus/core/src/collab/recent-edits.ts

@@ -21,6 +21,7 @@ import {
   RECENT_EDIT_TTL_MS,
   type AttributedRecentEdit,
   type RecentEdit,
+  type RecentEditDescriptor,
 } from "@agent-native/toolkit/collab-ui";
 import { useEffect, useRef, useState } from "react";
 
@@ -34,16 +35,78 @@ export {
   type RecentEditDescriptor,
 } from "@agent-native/toolkit/collab-ui";
 
+/**
+ * Hard cap on any single string carried in a recentEdits entry (quote,
+ * selector, path segment, label). Callers are expected to pass short
+ * excerpts already (existing call sites trim to 80–120 chars for a "what
+ * changed" snippet), but this is the ring's own size ceiling — a caller that
+ * forgets to trim (e.g. passing a whole paragraph/document as `quote`) must
+ * not blow up the awareness payload every connected client receives on the
+ * fast-push path, nor the `_collab_awareness` SQL row it gets mirrored into.
+ */
+const RECENT_EDIT_STRING_MAX = 500;
+
+function truncateString(value: string): string {
+  return value.length > RECENT_EDIT_STRING_MAX
+    ? value.slice(0, RECENT_EDIT_STRING_MAX)
+    : value;
+}
+
+function truncateDescriptor(
+  descriptor: RecentEditDescriptor,
+): RecentEditDescriptor {
+  // The union's last member (`{ kind: string; [key: string]: unknown }`) is an
+  // open-ended catch-all whose `kind` is a plain `string`, so a `switch` on
+  // `descriptor.kind` can't discriminate it away from the literal-kind
+  // members for the compiler — every property still type-checks as
+  // `unknown`. Read/write through an untyped view instead and lean on
+  // runtime checks; the return value is cast back to the real type below.
+  const d = descriptor as Record<string, unknown> & { kind: string };
+  if (d.kind === "text" && typeof d.quote === "string") {
+    return { ...d, quote: truncateString(d.quote) } as RecentEditDescriptor;
+  }
+  if (d.kind === "selector" && typeof d.selector === "string") {
+    return {
+      ...d,
+      selector: truncateString(d.selector),
+    } as RecentEditDescriptor;
+  }
+  if (d.kind === "paths" && Array.isArray(d.paths)) {
+    return {
+      ...d,
+      paths: d.paths.map((p) =>
+        typeof p === "string" ? truncateString(p) : p,
+      ),
+    } as RecentEditDescriptor;
+  }
+  if (d.kind === "doc") {
+    return descriptor;
+  }
+  // Open-ended shape — trim any string-valued fields defensively without
+  // knowing their names.
+  const trimmed: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(d)) {
+    trimmed[key] = typeof value === "string" ? truncateString(value) : value;
+  }
+  return trimmed as RecentEditDescriptor;
+}
+
 /**
  * Append an edit to a recentEdits ring, keeping the newest
- * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array.
+ * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array. Descriptor
+ * strings and the label are truncated to {@link RECENT_EDIT_STRING_MAX}
+ * characters as a defensive cap on the awareness payload size.
  */
 export function appendRecentEdit(
   existing: RecentEdit[] | undefined,
   edit: RecentEdit,
 ): RecentEdit[] {
   const ring = Array.isArray(existing) ? existing.slice() : [];
-  ring.push(edit);
+  ring.push({
+    ...edit,
+    descriptor: truncateDescriptor(edit.descriptor),
+    label: edit.label ? truncateString(edit.label) : edit.label,
+  });
   if (ring.length > RECENT_EDITS_MAX) {
     ring.splice(0, ring.length - RECENT_EDITS_MAX);
   }

package/corpus/core/src/deploy/build.ts

@@ -2437,6 +2437,90 @@ export const config = {
 const NETLIFY_DEFAULT_FUNCTION_URL_REDIRECT =
   "/* /.netlify/functions/server 200";
 
+function hasBareYjsRuntimeImport(source: string): boolean {
+  return /\b(?:from\s*|import\s*\(\s*|import\s*)["']yjs(?:\/[^"']*)?["']/.test(
+    source,
+  );
+}
+
+function hasUnsupportedYjsSubpathImport(source: string): boolean {
+  return /\b(?:from\s*|import\s*\(\s*|import\s*)["']yjs\/[^"']*["']/.test(
+    source,
+  );
+}
+
+function walkServerJavaScriptFiles(
+  dir: string,
+  onFile: (filePath: string) => void,
+): void {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkServerJavaScriptFiles(entryPath, onFile);
+      continue;
+    }
+    if (/\.(?:[cm]?js)$/.test(entry.name)) onFile(entryPath);
+  }
+}
+
+/**
+ * Nitro can preserve Vite's `yjs` external in a split server chunk even when
+ * its own server build has emitted `_libs/yjs.mjs`. Netlify does not install
+ * that bare package at runtime, so make every emitted server chunk use the
+ * bundled copy before its function is packaged.
+ */
+export function rewriteBareYjsImportsForServerlessOutput(
+  serverDir: string,
+): string[] {
+  const bareImports: string[] = [];
+  const unsupportedSubpathImports: string[] = [];
+  const bundledYjsPath = path.join(serverDir, "_libs", "yjs.mjs");
+
+  walkServerJavaScriptFiles(serverDir, (filePath) => {
+    const source = fs.readFileSync(filePath, "utf-8");
+    if (!hasBareYjsRuntimeImport(source)) return;
+    if (hasUnsupportedYjsSubpathImport(source)) {
+      unsupportedSubpathImports.push(filePath);
+      return;
+    }
+    bareImports.push(filePath);
+  });
+
+  if (unsupportedSubpathImports.length > 0) {
+    throw new Error(
+      `[deploy] Serverless output left unsupported yjs subpath imports in ${unsupportedSubpathImports.join(", ")}`,
+    );
+  }
+  if (bareImports.length === 0) return [];
+  if (!fs.existsSync(bundledYjsPath)) {
+    throw new Error(
+      `[deploy] Serverless output left yjs as a runtime import but did not emit ${bundledYjsPath}`,
+    );
+  }
+
+  for (const filePath of bareImports) {
+    const bundledImport = path
+      .relative(path.dirname(filePath), bundledYjsPath)
+      .split(path.sep)
+      .join("/");
+    const relativeBundledImport = bundledImport.startsWith(".")
+      ? bundledImport
+      : `./${bundledImport}`;
+    const source = fs.readFileSync(filePath, "utf-8");
+    fs.writeFileSync(
+      filePath,
+      source.replace(
+        /(\b(?:from\s*|import\s*\(\s*|import\s*))(["'])yjs\2/g,
+        (_match, importPrefix: string, quote: string) =>
+          `${importPrefix}${quote}${relativeBundledImport}${quote}`,
+      ),
+    );
+  }
+
+  return bareImports;
+}
+
 export function assertSingleTemplateNetlifyBuildOutput(
   projectCwd: string,
 ): void {
@@ -2519,6 +2603,23 @@ export function assertSingleTemplateNetlifyBuildOutput(
     }
   }
 
+  // Netlify's function packager does not install arbitrary runtime package
+  // imports left in Nitro chunks. A bare Yjs import here would deploy
+  // successfully but fail on the first SSR request with ERR_MODULE_NOT_FOUND.
+  // Keep this check adjacent to the output guard so both local builds and CI
+  // reject that artifact before it reaches Netlify.
+  const bareYjsImports: string[] = [];
+  walkServerJavaScriptFiles(serverDir, (filePath) => {
+    if (hasBareYjsRuntimeImport(fs.readFileSync(filePath, "utf-8"))) {
+      bareYjsImports.push(path.relative(projectCwd, filePath));
+    }
+  });
+  if (bareYjsImports.length > 0) {
+    failures.push(
+      `Netlify server bundle leaves yjs as a runtime import: ${bareYjsImports.join(", ")}`,
+    );
+  }
+
   if (isDurableBackgroundDeployEnabled()) {
     const backgroundDir = path.join(
       internalDir,
@@ -2969,6 +3070,32 @@ const BROWSER_ONLY_SERVER_LIBS = [
   "mermaid",
 ];
 
+/**
+ * Dependencies that must be bundled into every Nitro server output instead of
+ * being left as runtime package imports.
+ *
+ * `yjs` is a direct core dependency, but it is deliberately externalized from
+ * the intermediate Vite SSR graph so that Vite and Nitro do not create two
+ * incompatible Yjs constructors. On file-traced serverless presets, leaving it
+ * external at Nitro's final build can emit `import "yjs"` into a function
+ * chunk without placing the package in that function's `node_modules`. Bundle
+ * it in Nitro's final output so every template receives the one portable copy.
+ */
+export const NITRO_SERVER_RUNTIME_BUNDLED_DEPS = ["yjs"] as const;
+
+/**
+ * Edge runtimes have no node_modules, while Node/serverless outputs only need
+ * the small set above bundled to keep their package manifests traceable.
+ */
+export function nitroNoExternalsForPreset(
+  targetPreset: string,
+): true | readonly string[] {
+  return targetPreset.startsWith("cloudflare") ||
+    targetPreset.startsWith("deno")
+    ? true
+    : NITRO_SERVER_RUNTIME_BUNDLED_DEPS;
+}
+
 /**
  * Rolldown plugin for the Nitro server bundle that replaces the browser-only
  * renderers above with an inert proxy module.
@@ -3124,11 +3251,11 @@ export default bundle;
       ? { plugins: [providedPluginsNitroPlugin] }
       : {}),
     routeRules: mcpEmbedStaticAssetRouteRules(appBasePath),
-    // For edge presets (cloudflare, deno), bundle all deps — node_modules
-    // aren't available at runtime. Netlify/Vercel/Node have node_modules.
-    ...(preset.startsWith("cloudflare") || preset.startsWith("deno")
-      ? { noExternals: true }
-      : {}),
+    // Edge presets (cloudflare, deno) bundle all deps because node_modules are
+    // unavailable at runtime. Node/serverless presets also bundle Yjs: Nitro's
+    // file tracer otherwise leaves a bare import that Netlify function bundles
+    // cannot resolve under pnpm.
+    noExternals: nitroNoExternalsForPreset(preset),
   } as any);
 
   await runNitroBuildPipeline({
@@ -3145,6 +3272,7 @@ export default bundle;
     copyInstalledResvgPackages(nitro.options.output.serverDir);
     copyInstalledFfmpegStaticPackage(nitro.options.output.serverDir);
     sanitizeServerlessFunctionPackageManifest(nitro.options.output.serverDir);
+    rewriteBareYjsImportsForServerlessOutput(nitro.options.output.serverDir);
   }
 
   // Durable background agent runs (default-OFF / opt-in; enable with a truthy

package/corpus/core/src/index.browser.ts

@@ -10,6 +10,7 @@ export {
   refreshAgentChatContext,
   removeAgentChatContextItem,
   sendToAgentChat,
+  sendToAgentChatAndConfirm,
   setAgentChatContextItem,
   setContextToAgentChat,
   isEmbedMcpChatBridgeActive,

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -8561,10 +8561,34 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
       // covers the initial dispatch (a connected client is polling the claim),
       // but a server-chained CONTINUATION handoff has no foreground watching
       // it: if the dispatch is lost after the successor row was inserted, the
-      // row would sit at dispatch_mode='background' forever and the turn hangs
-      // silently. This sweep reaps such rows into a loud, attributable error
-      // (`background_worker_never_started`) that the client renders, instead
-      // of an idle spinner. Cheap: one indexed-ish query per 2-min window.
+      // row would otherwise sit at dispatch_mode='background' forever and the
+      // turn hangs silently. `chainServerDrivenContinuation` (production-agent.ts)
+      // leaves exactly such a row behind — status='running', dispatch_mode=
+      // 'background', `dispatch_payload` intact — when it exhausts its own
+      // dispatch retry budget, instead of erroring it immediately. This sweep
+      // gives that row a real chance to RECOVER: within
+      // `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS` of its original
+      // `started_at` it redispatches the handoff (same `_process-run`
+      // processor, same persisted payload); past that bound it falls back to
+      // the existing loud reap (`background_worker_never_started`) so a
+      // genuinely dead handoff still fails loud, never silently. A
+      // redispatch is always safe to attempt — even a duplicate or
+      // late-arriving one — because the worker's `claimBackgroundRun` atomic
+      // CAS (status='running' AND dispatch_mode='background' -> 'background-
+      // processing') is the sole gate on actual execution; a row that was
+      // already claimed or already reaped by a concurrent path just loses the
+      // CAS and no-ops. Cheap: one indexed-ish query per 2-min window.
+      //
+      // THREE-SITE INVARIANT (keep in lockstep): this sweep only ever sees the
+      // deferred successor because the ~1s client poll in
+      // `getActiveRunForThreadAsync` (run-manager.ts) skips its own
+      // `reapUnclaimedBackgroundRun` while the row is within the redispatch
+      // bound (`shouldRedispatchUnclaimedBackgroundRun`). If a future change
+      // makes that client poll reap deferred successors at the 25s grace
+      // again, this sweep will almost never win the race for connected clients.
+      // Do not edit one site without the others (producer:
+      // chainServerDrivenContinuation in production-agent.ts; guard:
+      // run-manager.ts; recovery actor: here).
       (() => {
         let lastSweep = 0;
         const SWEEP_INTERVAL_MS = 2 * 60 * 1000;
@@ -8577,22 +8601,85 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
 
             (async () => {
               const {
-                listUnclaimedBackgroundRunIds,
+                listUnclaimedBackgroundRunRows,
                 reapUnclaimedBackgroundRun,
+                updateRunHeartbeat,
+                shouldRedispatchUnclaimedBackgroundRun,
               } = await import("../agent/run-store.js");
-              let runIds: string[];
+              const { resolveAgentChatProcessRunDispatchPath } =
+                await import("../agent/durable-background.js");
+              const { fireInternalDispatch } =
+                await import("./self-dispatch.js");
+              let rows: { id: string; startedAt: number }[];
               try {
-                runIds = await listUnclaimedBackgroundRunIds();
+                rows = await listUnclaimedBackgroundRunRows();
               } catch {
                 return; // Table may not exist yet on first boot
               }
-              for (const staleRunId of runIds) {
+              for (const row of rows) {
                 try {
-                  const reaped = await reapUnclaimedBackgroundRun(staleRunId);
+                  if (shouldRedispatchUnclaimedBackgroundRun(row)) {
+                    // Bump liveness BEFORE attempting the redispatch so the
+                    // row doesn't look freshly-stale again the instant this
+                    // tick returns — best-effort, the CAS is what actually
+                    // matters for correctness, not this timing.
+                    await updateRunHeartbeat(row.id).catch(() => {});
+                    try {
+                      // DELIBERATE: this marker omits `continuationCount`.
+                      // `chainServerDrivenContinuation` (production-agent.ts)
+                      // reads `backgroundRunMarker.continuationCount` to
+                      // compute `backgroundContinuationCount`, defaulting to 0
+                      // when absent — so a chunk recovered here always starts
+                      // a fresh nested-dispatch segment at depth 0, regardless
+                      // of how deep the chain was before this sweep picked it
+                      // up. This is what makes the sweep a genuine CHAIN
+                      // BREAK, not just a retry: this redispatch fires from an
+                      // unrelated, timer-driven invocation rather than from
+                      // inside the prior chain's own live execution, so
+                      // starting its nested-depth count over at 0 here is
+                      // correct — see `MAX_NESTED_SELF_DISPATCH_DEPTH` in
+                      // production-agent.ts for why nested depth is bounded
+                      // and how this reset keeps a long turn progressing past
+                      // Netlify's undocumented self-invocation loop-protection
+                      // limit instead of dying at it. Do not "fix" this by
+                      // adding `continuationCount` back without re-reading
+                      // that constant's doc comment.
+                      await fireInternalDispatch({
+                        path: resolveAgentChatProcessRunDispatchPath(),
+                        taskId: row.id,
+                        body: {
+                          internalContinuation: true,
+                          [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
+                            runId: row.id,
+                            payloadRef: true,
+                          },
+                        },
+                        awaitResponse: true,
+                        responseTimeoutMs: 15_000,
+                      });
+                      console.error(
+                        "[agent-chat] redispatched unclaimed background run (handoff recovery):",
+                        row.id,
+                      );
+                    } catch (redispatchErr) {
+                      console.error(
+                        "[agent-chat] unclaimed background run redispatch attempt failed (retrying until the redispatch bound, then reaping):",
+                        row.id,
+                        redispatchErr instanceof Error
+                          ? redispatchErr.message
+                          : redispatchErr,
+                      );
+                    }
+                    continue;
+                  }
+                  // Redispatch bound exceeded — this handoff is not
+                  // recovering. Fall back to the pre-existing loud reap so
+                  // the turn fails loud instead of retrying forever.
+                  const reaped = await reapUnclaimedBackgroundRun(row.id);
                   if (reaped) {
                     console.error(
-                      "[agent-chat] swept unclaimed background run (handoff lost):",
-                      staleRunId,
+                      "[agent-chat] swept unclaimed background run (handoff lost, redispatch bound exceeded):",
+                      row.id,
                     );
                   }
                 } catch {

package/corpus/core/src/server/builder-design-systems.ts

@@ -16,6 +16,21 @@ export interface BuilderDesignSystemCodeFileInput {
   filename: string;
   content: string;
   mimeType?: string;
+  /**
+   * How `content` is encoded. Defaults to `"utf8"` (existing behavior,
+   * unchanged for every current text-file caller). Pass `"base64"` for
+   * binary files -- most importantly `.fig` (a zip/kiwi binary container,
+   * never valid UTF-8 text). Without this, a `.fig` upload silently
+   * corrupts: `mimeTypeForBuilderDesignSystemFilename` already special-cases
+   * `.fig` as `application/octet-stream`, but the actual byte pipeline ran
+   * every file through `TextEncoder().encode()` regardless, which mangles
+   * any byte >= 0x80 in a binary-as-string payload (or, if the caller
+   * base64-encoded first with no decode step here, stores the literal
+   * base64 text instead of the decoded binary). Callers sending `.fig`/PDF/
+   * other binary bytes must base64-encode `content` and set this to
+   * `"base64"`.
+   */
+  encoding?: "utf8" | "base64";
 }
 
 export interface BuildBuilderDesignSystemIndexFilesOptions {
@@ -184,9 +199,20 @@ export function buildBuilderDesignSystemIndexFiles({
   const files: BuilderDesignSystemIndexFile[] = [];
   let totalBytes = 0;
 
-  function pushTextFile(filename: string, content: string, mimeType?: string) {
+  function pushFile(
+    filename: string,
+    content: string,
+    mimeType?: string,
+    encoding?: "utf8" | "base64",
+  ) {
     const normalizedName = filename.replace(/^\/+/, "") || "code.txt";
-    const data = encoder.encode(content);
+    // `.fig`/PDF/other binary payloads must round-trip through base64, not
+    // UTF-8 -- TextEncoder().encode() on a binary-as-string payload mangles
+    // any byte >= 0x80. See BuilderDesignSystemCodeFileInput.encoding.
+    const data =
+      encoding === "base64"
+        ? new Uint8Array(Buffer.from(content, "base64"))
+        : encoder.encode(content);
     if (data.byteLength === 0) return;
     if (totalBytes + data.byteLength > maxTotalCodeBytes) return;
     totalBytes += data.byteLength;
@@ -201,7 +227,7 @@ export function buildBuilderDesignSystemIndexFiles({
   }
 
   if (designMd?.trim()) {
-    pushTextFile(
+    pushFile(
       designMdFilename?.trim() || "design.md",
       designMd,
       "text/markdown",
@@ -209,7 +235,7 @@ export function buildBuilderDesignSystemIndexFiles({
   }
 
   for (const file of (codeFiles ?? []).slice(0, maxCodeFiles)) {
-    pushTextFile(file.filename, file.content, file.mimeType);
+    pushFile(file.filename, file.content, file.mimeType, file.encoding);
   }
 
   return files;

package/corpus/templates/clips/.agents/skills/ai-video-tools/SKILL.md

@@ -126,7 +126,7 @@ Transcription takes an audio file and returns text + segments. That's not a prom
 **Provider priority:**
 
 1. **Native (highest priority).** The browser's Web Speech API, desktop local Whisper/macOS SFSpeech when available, and desktop Web Speech fallback on non-mac run during recording and save results via `save-browser-transcript`. This gives an instant transcript with no API key when the local/browser recognizer is available. When `request-transcript` runs afterward, it preserves the ready native transcript and only falls back to a cloud provider if native text is missing.
-2. **Cloud fallback — Builder.io managed (Gemini).** When a Builder account is connected (`BUILDER_PRIVATE_KEY` or per-user OAuth, no separate API key needed), `request-transcript` calls `transcribeWithBuilder()`, which routes audio to Builder.io's managed Gemini transcription. Returns text plus timestamped segments.
+2. **Cloud fallback — Builder.io managed (Gemini).** When a Builder account is connected (`BUILDER_PRIVATE_KEY` or per-user OAuth, no separate API key needed), `request-transcript` calls `transcribeWithBuilder()`, which routes audio to Builder.io's managed Gemini transcription. Returns text plus timestamped segments. Retry a failed transcript with `force: true`; pass `regenerate: true` to replace an existing ready transcript from the stored recording media. Regeneration keeps the prior ready transcript available if the new provider attempt fails.
 3. **Cloud fallback — Groq Whisper.** `GROQ_API_KEY` → `https://api.groq.com/openai/v1/audio/transcriptions`, model `whisper-large-v3-turbo`. Fast (~$0.04/hour of audio) Whisper-compatible speech-to-text used when Builder is unavailable.
 
 Clips never routes recording/meeting audio to OpenAI for transcription. (Groq's endpoint is OpenAI-_compatible_ in request shape only — the audio goes to Groq, not OpenAI.)

package/corpus/templates/clips/.agents/skills/video-sharing/SKILL.md

@@ -14,6 +14,12 @@ description: >-
 
 Recording sharing uses the framework `sharing` system — not a custom share table. Recordings are registered via `registerShareableResource({ type: "recording", ... })` in `server/db/index.ts`. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted and handle per-user grants, per-org grants, and the three visibility levels (`private` / `org` / `public`).
 
+Unlike the framework-wide private default, normal Clips recordings and uploaded
+videos default to **public** so their copied share links work immediately.
+Embedded bug-report recordings are the exception and default to organization
+visibility. Callers can still explicitly create a private or organization-only
+recording, and owners/admins can change visibility from the Share dialog.
+
 Clips **adds two things** on top of the framework system:
 
 1. **Password** — an optional bcrypt'd string on the `recordings` row. When set, all non-owner viewers must enter it to play the recording.
@@ -62,7 +68,7 @@ import { ShareDialog } from "@agent-native/core/client";
     </>
   }
   embedTabContent={<EmbedSnippetAndOptions recordingId={recording.id} />}
-/>
+/>;
 ```
 
 - `shareUrl` / `embedUrl` — the copy-link and embed URLs the framework renders in its tabs.
@@ -163,11 +169,11 @@ Required Slack app setup:
 Recordings can expose URLs meant for external agents without handing over raw
 video bytes:
 
-| Endpoint | Meaning |
-| -------- | ------- |
-| `/api/agent-context.json?id=<recordingId>` | Clip metadata, transcript summary, recommended frames, and API discovery links |
-| `/api/agent-transcript.json?id=<recordingId>` | Timestamped transcript segments with `startMs`, `endMs`, `timestamp`, `range`, `text`, and optional `source` |
-| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | JPEG frame extracted from the video at the requested original-video timestamp |
+| Endpoint                                          | Meaning                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `/api/agent-context.json?id=<recordingId>`        | Clip metadata, transcript summary, recommended frames, and API discovery links                               |
+| `/api/agent-transcript.json?id=<recordingId>`     | Timestamped transcript segments with `startMs`, `endMs`, `timestamp`, `range`, `text`, and optional `source` |
+| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | JPEG frame extracted from the video at the requested original-video timestamp                                |
 
 These endpoints follow the same access model as `/api/public-recording`, plus a
 temporary agent-link path:

package/corpus/templates/clips/AGENTS.md

@@ -34,6 +34,10 @@ Detailed media, meeting, dictation, editing, and sharing rules live in
   download the original from Loom and use "Upload video".
 - Native transcript first. Cleanup and title generation can run in the
   background; do not hide a usable native transcript behind a failed cleanup.
+- Use `request-transcript --recordingId=<id> --force=true` to retry a failed
+  transcript. Pass `--regenerate=true` to replace an existing ready transcript
+  from the stored recording media; if regeneration fails, keep the prior ready
+  transcript available.
 - Dictation cleanup, Clip title/cleanup, and meeting summaries should pass
   bounded `voiceContext` to the shared cleanup/transcription path when active
   app context, learned vocabulary, user notes, or AGENTS.md preferences are

package/corpus/templates/clips/actions/create-recording.ts

@@ -24,6 +24,7 @@ import {
 } from "../server/lib/recordings.js";
 import { setResumableSession } from "../server/lib/resumable-session.js";
 import { shouldEnableStreamingUpload } from "../server/lib/streaming-upload-mode.js";
+import { allowsSqlRecordingChunkScratch } from "../server/lib/video-storage.js";
 import { createRecordingSchema } from "./lib/create-recording-schema.js";
 import { DEFAULT_RECORDING_TITLE } from "./lib/title-source.js";
 
@@ -92,6 +93,7 @@ export default defineAction({
       shouldEnableStreamingUpload({
         client: args.streamingUploadClient,
         mimeType: args.mimeType,
+        bufferedFallbackAvailable: allowsSqlRecordingChunkScratch(),
       }) &&
       uploadProvider?.resumable
     ) {

package/corpus/templates/clips/actions/lib/create-recording-schema.ts

@@ -62,8 +62,10 @@ export const createRecordingSchema = z.object({
     .describe("Height of the recording in pixels (may be 0 until finalized)"),
   visibility: z
     .enum(["private", "org", "public"])
-    .optional()
-    .describe("Initial share visibility for the recording"),
+    .default("public")
+    .describe(
+      "Initial share visibility for the recording (defaults to public)",
+    ),
   mimeType: z
     .string()
     .optional()
@@ -74,7 +76,7 @@ export const createRecordingSchema = z.object({
     .boolean()
     .optional()
     .describe(
-      "Request the resumable streaming upload path. Deployments must also set CLIPS_ENABLE_STREAMING_UPLOAD; otherwise recordings use the buffered fallback.",
+      "Request the resumable streaming upload path. Hosted deployments use it automatically because SQL chunk buffering is unavailable; local deployments can opt in with CLIPS_ENABLE_STREAMING_UPLOAD.",
     ),
   streamingUploadClient: z
     .enum(["desktop-native"])