@agent-native/core 0.144.0 → 0.144.1

package/corpus/templates/slides/server/lib/source-import.ts

@@ -0,0 +1,167 @@
+export type SourceImportFormat = "pdf" | "pptx";
+
+export interface SourceImportSlideSnapshot {
+  id: string;
+  text: string;
+  notes: string;
+  imageUrls: string[];
+  editableText: boolean;
+}
+
+export interface SourceImportMetadata {
+  mode: "source-preserving";
+  format: SourceImportFormat;
+  fidelity: "source-faithful" | "partial";
+  importedAt: string;
+  slideCount: number;
+  slideIds: string[];
+  slides: SourceImportSlideSnapshot[];
+  imagesSkipped?: number;
+}
+
+export function buildSourceImportMetadata(args: {
+  format: SourceImportFormat;
+  importedAt?: string;
+  slides: SourceImportSlideSnapshot[];
+  imagesSkipped?: number;
+}): SourceImportMetadata {
+  const importedAt = args.importedAt ?? new Date().toISOString();
+  const imagesSkipped = args.imagesSkipped ?? 0;
+  return {
+    mode: "source-preserving",
+    format: args.format,
+    fidelity: imagesSkipped > 0 ? "partial" : "source-faithful",
+    importedAt,
+    slideCount: args.slides.length,
+    slideIds: args.slides.map((slide) => slide.id),
+    slides: args.slides,
+    ...(imagesSkipped > 0 ? { imagesSkipped } : {}),
+  };
+}
+
+export function mergeSourceImportMetadata(
+  existing: SourceImportMetadata | null,
+  incoming: SourceImportMetadata,
+): SourceImportMetadata {
+  if (!existing) return incoming;
+  if (existing.format !== incoming.format) {
+    throw new Error(
+      `Cannot append a ${incoming.format.toUpperCase()} source import to a ${existing.format.toUpperCase()} source-imported deck. Import matching source formats separately so every slide keeps its provenance.`,
+    );
+  }
+
+  const slidesById = new Map<string, SourceImportSlideSnapshot>();
+  for (const slide of existing.slides) slidesById.set(slide.id, slide);
+  for (const slide of incoming.slides) slidesById.set(slide.id, slide);
+  const slides = [...slidesById.values()];
+  const imagesSkipped =
+    (existing.imagesSkipped ?? 0) + (incoming.imagesSkipped ?? 0);
+
+  return {
+    ...incoming,
+    fidelity:
+      existing.fidelity === "partial" || incoming.fidelity === "partial"
+        ? "partial"
+        : "source-faithful",
+    slideCount: slides.length,
+    slideIds: slides.map((slide) => slide.id),
+    slides,
+    ...(imagesSkipped > 0 ? { imagesSkipped } : {}),
+  };
+}
+
+export function sourceImportForDeck(
+  value: unknown,
+): SourceImportMetadata | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Partial<SourceImportMetadata>;
+  if (
+    record.mode !== "source-preserving" ||
+    (record.format !== "pdf" && record.format !== "pptx") ||
+    !Array.isArray(record.slides)
+  ) {
+    return null;
+  }
+  return record as SourceImportMetadata;
+}
+
+function extractImageUrls(content: string): string[] {
+  const urls: string[] = [];
+  const seen = new Set<string>();
+  const imagePattern = /<img\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/gi;
+  for (const match of content.matchAll(imagePattern)) {
+    const url = match[1]
+      ?.replace(/&amp;/g, "&")
+      .replace(/&quot;/g, '"')
+      .trim();
+    if (url && !seen.has(url)) {
+      seen.add(url);
+      urls.push(url);
+    }
+  }
+  return urls;
+}
+
+function sourceWords(value: string): Set<string> {
+  return new Set(
+    value
+      .toLowerCase()
+      .match(/[a-z0-9][a-z0-9'-]{3,}/g)
+      ?.map((word) => word.replace(/^['-]+|['-]+$/g, "")) ?? [],
+  );
+}
+
+/**
+ * Protects an imported deck from the common "make it prettier" failure mode:
+ * the agent replaces a source slide with a generic card and silently drops the
+ * original artwork or most of its factual copy. Explicit rewrite requests can
+ * opt out with preserveSource=false.
+ */
+export function assertSourceSlidePreserved(args: {
+  metadata: SourceImportMetadata | null;
+  slideId: string;
+  nextContent?: string;
+  nextNotes?: string;
+  preserveSource?: boolean;
+}): void {
+  if (args.preserveSource === false || !args.metadata) return;
+  const snapshot = args.metadata.slides.find(
+    (slide) => slide.id === args.slideId,
+  );
+  if (!snapshot) return;
+
+  if (
+    args.nextNotes !== undefined &&
+    snapshot.notes.length > 0 &&
+    args.nextNotes !== snapshot.notes
+  ) {
+    throw new Error(
+      `Source-preserving edit would remove or change imported speaker notes on slide ${args.slideId}. Preserve the source notes, or pass preserveSource=false only when the user explicitly asks for a rewrite.`,
+    );
+  }
+
+  if (args.nextContent === undefined) return;
+
+  const nextImageUrls = new Set(extractImageUrls(args.nextContent));
+  const missingImages = snapshot.imageUrls.filter(
+    (url) => !nextImageUrls.has(url),
+  );
+  if (missingImages.length > 0) {
+    throw new Error(
+      `Source-preserving edit would remove ${missingImages.length} original image(s) from slide ${args.slideId}. Keep every existing source image, or pass preserveSource=false only when the user explicitly asks for a rewrite.`,
+    );
+  }
+
+  if (!snapshot.editableText) return;
+  const originalWords = sourceWords(snapshot.text);
+  if (originalWords.size < 12) return;
+  const nextWords = sourceWords(args.nextContent.replace(/<[^>]+>/g, " "));
+  const retainedWords = [...originalWords].filter((word) =>
+    nextWords.has(word),
+  ).length;
+  if (retainedWords / originalWords.size < 0.35) {
+    throw new Error(
+      `Source-preserving edit would drop most of the original factual copy from slide ${args.slideId}. Preserve the source text, or pass preserveSource=false only when the user explicitly asks for a rewrite.`,
+    );
+  }
+}

package/corpus/templates/slides/server/plugins/agent-chat.ts

@@ -15,6 +15,8 @@ const INITIAL_TOOL_NAMES = [
   "get-layout-overflows",
   "list-decks",
   "get-deck",
+  "get-design-system",
+  "get-workspace-defaults",
   "get-deck-reference-context",
   "create-deck",
   "add-slide",
@@ -50,6 +52,12 @@ export default createAgentChatPlugin({
   prepareRequest: prepareSlidesChatAttachments,
   systemPrompt: `You are an AI deck assistant. You create, edit, import, export, style, share, and navigate decks through actions and shared application state. For a newly created presentation, use create-deck with slides: [] only when you are creating the deck yourself, then add-slide sequentially with full rendered HTML. The legacy generate-slides-ai action returns Markdown drafts and is not part of the persisted presentation workflow.
 
+When the user asks to improve, beautify, restyle, or make an uploaded/existing deck on-brand, treat it as an in-place source-preserving edit unless the user explicitly asks to rewrite the story or change slide count. First call view-screen when the active deck is unclear, then get-deck. If get-deck.sourceImport exists, preserve its slide count, order, IDs, factual copy, notes, images, charts, tables, diagrams, freeform objects, and source aspect ratio. Use update-slide on existing slide IDs. Do not use add-slide, delete, reorder, or replace source imagery with generic cards for this workflow. Verify the same slide IDs and count with get-deck after editing. If sourceImport.fidelity is partial or imagesSkipped is nonzero, stop and report the exact fidelity warning instead of claiming a reliable improvement.
+
+For source-faithful PDF slides, keep the original full-page image and style around it with restrained design-system chrome such as a frame, edge treatment, caption, or safe overlay that does not obscure source content; never OCR-reconstruct the page from extracted text. For PPTX slides, preserve the imported positioned HTML and every uploaded source image. The update-slide action enforces these preservation rules by default; pass preserveSource=false only when the user explicitly requests a rewrite of that slide.
+
+If the deck has designSystemId, call get-design-system before writing and follow its exact agentContext tokens, assets, and custom instructions. If the user asks for on-brand styling and no design system is linked, call get-workspace-defaults, link its usable design system with patch-deck, then call get-design-system. Do not improvise a generic Builder-like palette when configured Builder.io design-system context is available.
+
 Layout-fit workflow is strict. When the user asks to fix overflow, first call view-screen and inspect the deck-wide layout-fit section. If it says measurements are unknown, do not claim the deck fits. Call get-layout-overflows when you need the structured per-slide results. Read the affected slides with get-deck, then make one bounded structural repair pass with one patch-slide operation per affected slide in a single patch-deck call. Wait for the action result and verify the persisted HTML with get-deck before saying it is fixed. If a fresh measurement still reports overflow, make at most one focused follow-up repair based on that measurement; never loop, repeatedly re-measure, or claim success after a chat response alone.
 
 Fit means the main content fits the native content area. A small outer-wrapper spill is tolerated by the measurement, but cards, text, columns, and other visible content must fit. Never use zoom, transform: scale(), overflow: hidden/scroll, clipping, or a smaller-than-16px body font to hide overflow. Preserve manually positioned freeform objects and their data-slide-object-id values; repair normal-flow structure, copy, gaps, or slide padding instead. A successful action result must include the affected slide IDs; if it does not, report that no verified write occurred.

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/jobs/scheduler.js

@@ -14,7 +14,10 @@ export function buildJobContent(meta, body) {
     return buildJobResourceContent(meta, body);
 }
 const MAX_CONCURRENT_SCHEDULED_JOBS = 8;
+const MAX_IDENTITY_PREFLIGHTS_PER_TICK = MAX_CONCURRENT_SCHEDULED_JOBS * 4;
+const IDENTITY_FAILURE_RETRY_MS = 5 * 60_000;
 const _activeScheduledJobs = new Set();
+const _preflightingScheduledJobs = new Set();
 // Skip the DB query on every tick if we recently confirmed no jobs exist.
 // `_hasJobsCache` is invalidated whenever a `jobs/*` resource is written or
 // deleted (subscribed below), and refreshed at most every 5 minutes.
@@ -88,7 +91,7 @@ export async function processRecurringJobs(deps) {
         if (!_hasJobsCache)
             return;
         const now = new Date();
-        const dueJobs = [];
+        const dueJobCandidates = [];
         for (const resource of jobResources) {
             // Skip non-markdown or .keep files
             if (!resource.path.endsWith(".md"))
@@ -136,14 +139,56 @@ export async function processRecurringJobs(deps) {
             // Skip if body is empty
             if (!body.trim())
                 continue;
+            if (hasRecentIdentityFailure(meta, now))
+                continue;
             const key = `${resource.owner}:${resource.path}`;
-            if (_activeScheduledJobs.has(key))
+            if (_activeScheduledJobs.has(key) ||
+                _preflightingScheduledJobs.has(key)) {
                 continue;
-            if (_activeScheduledJobs.size >= MAX_CONCURRENT_SCHEDULED_JOBS)
+            }
+            dueJobCandidates.push({ key, resource, meta, body });
+        }
+        const preflightCandidates = [];
+        for (const candidate of dueJobCandidates) {
+            if (_activeScheduledJobs.size >= MAX_CONCURRENT_SCHEDULED_JOBS ||
+                preflightCandidates.length >= MAX_IDENTITY_PREFLIGHTS_PER_TICK) {
+                break;
+            }
+            if (_activeScheduledJobs.has(candidate.key) ||
+                _preflightingScheduledJobs.has(candidate.key)) {
                 continue;
-            _activeScheduledJobs.add(key);
-            reservedJobKeys.add(key);
-            dueJobs.push({ key, resource, meta, body });
+            }
+            preflightCandidates.push(candidate);
+        }
+        // Identity checks can reject stale jobs that remain due for admin review.
+        // Bound the checks so a large blocked backlog cannot consume the whole
+        // invocation or make valid jobs wait behind an unbounded stale queue.
+        const dueJobs = [];
+        for (const candidate of preflightCandidates) {
+            _preflightingScheduledJobs.add(candidate.key);
+            try {
+                const identity = await resolveBackgroundAutomationIdentity({
+                    name: candidate.resource.path
+                        .replace(/^jobs\//, "")
+                        .replace(/\.md$/, ""),
+                    meta: candidate.meta,
+                    body: candidate.body,
+                    resource: candidate.resource,
+                });
+                if (!identity.ok) {
+                    await recordIdentityFailure(candidate.resource, candidate.meta, candidate.body, now, identity.reason);
+                    continue;
+                }
+                if (_activeScheduledJobs.size >= MAX_CONCURRENT_SCHEDULED_JOBS) {
+                    break;
+                }
+                _activeScheduledJobs.add(candidate.key);
+                reservedJobKeys.add(candidate.key);
+                dueJobs.push(candidate);
+            }
+            finally {
+                _preflightingScheduledJobs.delete(candidate.key);
+            }
         }
         if (dueJobs.length > 0)
             dispatchedAt = Date.now();
@@ -219,6 +264,33 @@ async function recoverStaleAutomationHistory(owner, path) {
     }
 }
 export const jobRunCutOffReason = backgroundRunCutOffReason;
+async function recordIdentityFailure(resource, meta, body, now, reason, historyId) {
+    const jobName = resource.path.replace(/^jobs\//, "").replace(/\.md$/, "");
+    console.warn(`[recurring-jobs] Skipping job "${jobName}": ${reason}. ` +
+        `User/membership no longer valid — leaving cron entry for admin review.`);
+    // Keep blocked jobs due so an admin can find them, but do not let their
+    // persistent failure consume an execution slot on every scheduler sweep.
+    const alreadyRecorded = meta.lastStatus === "skipped" && meta.lastError === reason;
+    meta.lastCheck = now.toISOString();
+    meta.lastStatus = "skipped";
+    meta.lastError = reason;
+    if (!alreadyRecorded)
+        await updateResource(resource, meta, body);
+    if (historyId) {
+        await finishAutomationRun(historyId, "error", `Automation did not run: ${reason}. No delivery was confirmed.`);
+    }
+    return { status: "skipped", error: reason };
+}
+function hasRecentIdentityFailure(meta, now) {
+    if (meta.lastStatus !== "skipped" || !meta.lastCheck || !meta.lastError) {
+        return false;
+    }
+    const lastCheckMs = Date.parse(meta.lastCheck);
+    const elapsedMs = now.getTime() - lastCheckMs;
+    return (Number.isFinite(lastCheckMs) &&
+        elapsedMs >= 0 &&
+        elapsedMs < IDENTITY_FAILURE_RETRY_MS);
+}
 async function executeJob(resource, meta, body, deps, now, options = {}) {
     const jobName = resource.path.replace(/^jobs\//, "").replace(/\.md$/, "");
     const jobContext = {
@@ -234,23 +306,7 @@ async function executeJob(resource, meta, body, deps, now, options = {}) {
     // failure; leave the cron entry alone so an admin can purge after
     // investigation.
     if (!identity.ok) {
-        console.warn(`[recurring-jobs] Skipping job "${jobName}": ${identity.reason}. ` +
-            `User/membership no longer valid — leaving cron entry for admin review.`);
-        // Mark as skipped without resetting nextRun so an admin can find it.
-        // `lastRun` is deliberately untouched: the job did not run, and stamping
-        // it here made a permanently blocked job look like it ran every minute.
-        // Re-writing an unchanged resource on every tick also churns the poll
-        // stream, so only persist when the failure state actually changed.
-        const alreadyRecorded = meta.lastStatus === "skipped" && meta.lastError === identity.reason;
-        meta.lastCheck = now.toISOString();
-        meta.lastStatus = "skipped";
-        meta.lastError = identity.reason;
-        if (!alreadyRecorded)
-            await updateResource(resource, meta, body);
-        if (options.historyId) {
-            await finishAutomationRun(options.historyId, "error", `Automation did not run: ${identity.reason}. No delivery was confirmed.`);
-        }
-        return { status: "skipped", error: identity.reason };
+        return recordIdentityFailure(resource, meta, body, now, identity.reason, options.historyId);
     }
     const jobUserEmail = identity.identity.userEmail;
     const jobOrgId = identity.identity.orgId;

package/dist/notifications/routes.d.ts

@@ -28,6 +28,6 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
 } | {
     count?: undefined;
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -42,22 +42,22 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     avgEvalScore: number;
 } | {
     error?: undefined;
+    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    ok?: undefined;
 } | {
     error?: undefined;
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
-    ok?: undefined;
 } | {
     error?: undefined;
     summary?: undefined;

package/dist/progress/routes.d.ts

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

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/docs/content/creating-templates.mdx

@@ -49,7 +49,7 @@ npx @agent-native/core@latest create my-platform
 
 Chat gives you auth, durable chat threads, SQL-backed resources, tools, application state, actions, and polling sync. You add the domain model and product UI.
 
-If you are not building a reusable UI template yet, use the headless on-ramp in [Getting Started](/docs/getting-started#create-your-app): define one action, run it with `pnpm agent`, and add UI later when the workflow needs a durable surface.
+If you are not building a reusable UI template yet, use [Automation-First Apps](/docs/pure-agent-apps): define actions, run them without a browser, and add UI later when the workflow needs a durable surface.
 
 ## Project Structure {#project-structure}