@agent-native/core 0.85.6 → 0.86.0

package/corpus/templates/plan/server/lib/plan-versions.ts

@@ -152,6 +152,79 @@ export function summarizePlanVersion(row: VersionRow): PlanVersionSummary {
   };
 }
 
+/** Derived summary fields computed from a snapshot, stored alongside the row at
+ * write time so list reads don't need to parse snapshot_json. */
+function summaryColumnsFromSnapshot(snapshot: PlanVersionSnapshot) {
+  return {
+    status: snapshot.plan.status,
+    source: snapshot.plan.source,
+    blockCount: blockCount(snapshot),
+    sectionCount: snapshot.sections.length,
+    hasCanvas: Boolean(snapshot.plan.content?.canvas),
+    hasPrototype: Boolean(snapshot.plan.content?.prototype),
+    previewText: snapshotPreview(snapshot),
+  };
+}
+
+/** Row shape needed by `summarizePlanVersionRow`: the small always-selected
+ * columns, the denormalized summary columns, and `snapshotJson` only as a
+ * fallback for legacy rows (see below). Callers project just this shape
+ * instead of the full `VersionRow` in the common case. */
+type SummaryRow = Pick<
+  VersionRow,
+  | "id"
+  | "planId"
+  | "title"
+  | "changeLabel"
+  | "createdBy"
+  | "createdAt"
+  | "status"
+  | "source"
+  | "blockCount"
+  | "sectionCount"
+  | "hasCanvas"
+  | "hasPrototype"
+  | "previewText"
+> & { snapshotJson?: string | null };
+
+/**
+ * Like `summarizePlanVersion`, but reads the denormalized summary columns
+ * instead of parsing `snapshotJson` when they're populated. Only rows written
+ * before this column set existed have `blockCount === null`; for those,
+ * `snapshotJson` must be provided so this can fall back to the legacy
+ * parse-on-read path.
+ */
+export function summarizePlanVersionRow(row: SummaryRow): PlanVersionSummary {
+  const base = {
+    id: row.id,
+    planId: row.planId,
+    title: row.title,
+    label: row.changeLabel,
+    createdBy: row.createdBy,
+    createdAt: row.createdAt,
+  };
+  if (row.blockCount == null) {
+    if (row.snapshotJson == null) {
+      throw new Error(
+        `Plan version ${row.id} has no summary columns and no snapshotJson to fall back to`,
+      );
+    }
+    const snapshot = parsePlanVersionSnapshot(row.snapshotJson);
+    const summary = summaryColumnsFromSnapshot(snapshot);
+    return { ...base, ...summary, preview: summary.previewText };
+  }
+  return {
+    ...base,
+    status: row.status ?? "draft",
+    source: row.source ?? "manual",
+    blockCount: row.blockCount,
+    sectionCount: row.sectionCount ?? 0,
+    hasCanvas: Boolean(row.hasCanvas),
+    hasPrototype: Boolean(row.hasPrototype),
+    preview: row.previewText ?? "",
+  };
+}
+
 export async function createPlanVersionSnapshot(
   planId: string,
   options: {
@@ -179,7 +252,9 @@ export async function createPlanVersionSnapshot(
       asc(schema.planSections.order),
       asc(schema.planSections.createdAt),
     );
-  const snapshotJson = JSON.stringify(snapshotFromRows(plan, sections));
+  const snapshot = snapshotFromRows(plan, sections);
+  const snapshotJson = JSON.stringify(snapshot);
+  const summaryColumns = summaryColumnsFromSnapshot(snapshot);
 
   const [latestVersion] = await db
     .select({
@@ -245,6 +320,13 @@ export async function createPlanVersionSnapshot(
     changeLabel: options.label,
     createdBy: options.createdBy ?? "agent",
     createdAt: new Date().toISOString(),
+    status: summaryColumns.status,
+    source: summaryColumns.source,
+    blockCount: summaryColumns.blockCount,
+    sectionCount: summaryColumns.sectionCount,
+    hasCanvas: summaryColumns.hasCanvas,
+    hasPrototype: summaryColumns.hasPrototype,
+    previewText: summaryColumns.previewText,
   });
 
   return { created: true, id };

package/corpus/templates/plan/server/lib/public-action-paths.ts

@@ -9,8 +9,6 @@ export const PUBLIC_PLAN_ACTION_PATHS = [
   "/_agent-native/actions/get-plan-blocks",
   "/_agent-native/actions/validate-local-plan-source",
   "/_agent-native/actions/read-visual-plan-source",
-  "/_agent-native/actions/get-plan-version",
-  "/_agent-native/actions/list-plan-versions",
   // Write — comments/patches from public reviewers, local-mode authoring
   "/_agent-native/actions/update-visual-plan",
   "/_agent-native/actions/patch-visual-plan-source",

package/corpus/templates/plan/server/plans.ts

@@ -8,7 +8,7 @@ import {
   currentAccess,
   resolveAccess,
 } from "@agent-native/core/sharing";
-import { and, asc, eq, inArray, isNull } from "drizzle-orm";
+import { and, asc, desc, eq, inArray, isNull } from "drizzle-orm";
 import { z } from "zod";
 
 import {
@@ -764,12 +764,19 @@ export async function loadPlanBundle(planId: string): Promise<PlanBundle> {
       .select()
       .from(schema.planEvents)
       .where(eq(schema.planEvents.planId, planId))
-      .orderBy(asc(schema.planEvents.createdAt)),
+      // plan_events is an append-only log with no cap; loadPlanBundle is polled
+      // every 3s while a plan is open (usePlan refetchInterval), so fetching
+      // every event ever written grows unbounded with plan age. Cap to the most
+      // recent 50 and reverse back to ascending order — downstream consumers
+      // (get-plan-feedback, PlansPage) only ever take the last 6-10 of a given
+      // event type, well within this window.
+      .orderBy(desc(schema.planEvents.createdAt))
+      .limit(50),
   ]);
 
   const sections = sectionRows.map(toSection);
   const comments = commentRows.map(toComment);
-  const events = eventRows.map(toEvent);
+  const events = eventRows.reverse().map(toEvent);
   return {
     plan: {
       id: plan.id,
@@ -807,6 +814,22 @@ export async function loadPlanBundle(planId: string): Promise<PlanBundle> {
   };
 }
 
+/**
+ * Full append-only event log for a plan, ascending. `loadPlanBundle` caps its
+ * events at the most recent 50 because it sits on a 3s poll; durable receipts
+ * (export-visual-plan) call this instead so the exported history stays
+ * complete. Callers must have already resolved access to the plan.
+ */
+export async function loadFullPlanEvents(planId: string): Promise<PlanEvent[]> {
+  const db = getDb();
+  const rows = await db
+    .select()
+    .from(schema.planEvents)
+    .where(eq(schema.planEvents.planId, planId))
+    .orderBy(asc(schema.planEvents.createdAt));
+  return rows.map(toEvent);
+}
+
 export function summarizePlan(
   sections: PlanSection[],
   comments: PlanComment[],

package/corpus/templates/plan/server/plugins/db.ts

@@ -1,8 +1,36 @@
 // guard:allow-unscoped -- schema migrations and data backfills run system-wide
 // during startup, not in a user-scoped request path.
-import { runMigrations } from "@agent-native/core/db";
+import {
+  ensureAdditiveColumns,
+  getDbExec,
+  runMigrations,
+} from "@agent-native/core/db";
 
-export default runMigrations(
+import * as schema from "../db/schema.js";
+
+/**
+ * Every Drizzle table exported from schema.ts. Filters out type-only and
+ * helper exports the same way db.spec.ts's `isDrizzleTable` regression guard
+ * does: a real table carries a Symbol-keyed drizzle metadata bag, plain
+ * exports don't.
+ */
+function isDrizzleTable(value: unknown): value is object {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    Object.getOwnPropertySymbols(value).some((s) =>
+      s.toString().includes("drizzle"),
+    )
+  );
+}
+
+const schemaTables = Object.values(schema).filter(isDrizzleTable);
+
+// Convention: every new migration below MUST set a unique `name:` slug (see
+// packages/core/src/db/migrations.ts for the full rationale). Version numbers
+// alone are not a safe identity across parallel branches that each extend
+// this list independently.
+const runPlanMigrations = runMigrations(
   [
     {
       version: 1,
@@ -350,6 +378,81 @@ CREATE INDEX IF NOT EXISTS plans_source_pr_idx ON plans(source_repo, source_pr_n
 CREATE INDEX IF NOT EXISTS plan_comments_plan_deleted_created_idx ON plan_comments(plan_id, deleted_at, created_at)`,
       },
     },
+    {
+      // Denormalized summary fields for plan_versions, populated at snapshot-write
+      // time (createPlanVersionSnapshot). list-plan-versions previously ran a
+      // bare `.select()` that pulled every row's full snapshot_json (the entire
+      // plan + sections blob) just to JSON.parse it and compute these same small
+      // values via summarizePlanVersion on every list call. Nullable so existing
+      // rows fall back to the legacy parse-on-read path until they're
+      // re-snapshotted.
+      //
+      // Confirmed swallowed on the live plan Neon DB: plans_migrations' recorded
+      // MAX(version) was 36 (this v37 entry had never actually run — a parallel
+      // branch's DB state advanced past v37 without ever applying this specific
+      // DDL), and information_schema confirmed plan_versions was missing all
+      // seven of these columns. Named so it applies by name on next boot
+      // regardless of any database's recorded MAX(version) — its SQL was
+      // already idempotent (ADD COLUMN IF NOT EXISTS on postgres) before this
+      // name was added.
+      version: 37,
+      name: "plan-versions-summary-columns",
+      sql: {
+        postgres: `ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS summary_status TEXT;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS summary_source TEXT;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS block_count INTEGER;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS section_count INTEGER;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS has_canvas BOOLEAN;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS has_prototype BOOLEAN;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS preview_text TEXT`,
+        // `ADD COLUMN IF NOT EXISTS` is required on BOTH dialects: this entry
+        // is tracked by `name:`, so it re-applies on any database that already
+        // ran it under the legacy version gate. SQLite has no native
+        // IF NOT EXISTS for ADD COLUMN, but the migration runner emulates it
+        // (strips the clause and swallows duplicate-column errors) only for
+        // statements that originally carry it — a plain ADD COLUMN would
+        // throw on re-apply and crash local dev boot.
+        sqlite: `ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS summary_status TEXT;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS summary_source TEXT;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS block_count INTEGER;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS section_count INTEGER;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS has_canvas INTEGER;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS has_prototype INTEGER;
+ALTER TABLE plan_versions ADD COLUMN IF NOT EXISTS preview_text TEXT`,
+      },
+    },
   ],
   { table: "plans_migrations" },
 );
+
+/**
+ * The migration list above is the authoritative source for tables, indexes,
+ * and data transforms. `ensureAdditiveColumns` runs after it as a
+ * belt-and-braces safety net for the failure mode where a column is added to
+ * schema.ts without a matching hand-written ALTER migration, which silently
+ * 500s every query touching a pre-existing production table. It only ever
+ * adds missing columns — never drops, renames, or retypes anything — and any
+ * failure here is logged and swallowed so it can never fail boot.
+ */
+export default async (nitroApp: any): Promise<void> => {
+  await runPlanMigrations(nitroApp);
+  try {
+    const summary = await ensureAdditiveColumns({
+      db: getDbExec(),
+      tables: schemaTables,
+    });
+    if (summary.errors.length > 0) {
+      console.warn(
+        "[db] ensureAdditiveColumns completed with errors:",
+        summary.errors,
+      );
+    }
+  } catch (err) {
+    // Never fail boot over the safety net itself — the authoritative
+    // migrations above already ran.
+    console.warn(
+      "[db] ensureAdditiveColumns failed (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
+};

package/corpus/templates/slides/.agents/skills/slide-editing/SKILL.md

@@ -37,10 +37,14 @@ All generated slides follow these conventions:
 
 To edit a slide's content:
 
-1. **Get the deck**: `pnpm action get-deck --id=<deckId>`
-2. **Parse the JSON**, find the slide by ID
-3. **Modify the content** HTML string
-4. **Update the deck** via `PUT /api/decks/:id` with the full updated deck JSON
+1. **Inspect the current context**: call `view-screen` to get the active deck,
+   slide ID, HTML, and any `slides-selection` style/edit target.
+2. **Modify the content** HTML string for the intended slide.
+3. **Update the slide** with the `update-slide` action using `deckId`,
+   `slideId`, and `fullContent`. Do not write deck rows directly and do not add
+   raw `/api/decks/:id` PUT calls for normal slide edits.
+4. For browser/editor code, enqueue granular deck operations through
+   `patch-deck` / `DeckContext.tsx` instead of replacing the whole deck JSON.
 
 ## Image Placeholders
 

package/corpus/templates/slides/AGENTS.md

@@ -51,6 +51,10 @@ extending the editor's save path, enqueue a granular op (`patch-slide`,
 ## Application State
 
 - `navigation` exposes the current deck, slide, selection, and editor view.
+- `slides-selection` exposes the active visual editing context: selected slide
+  element(s), tool mode, transient selectors, text/image hints, and compact
+  computed style data. Use `view-screen` before a visual/style edit so you can
+  act on the same object the user clicked.
 - `navigate` moves the UI to decks, slides, imports, and exports.
 - Use app actions for full deck/slide data instead of relying on ambient context.
 

package/corpus/templates/slides/actions/_agent-presence.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared agent-presence attribution for slide-editing actions.
+ *
+ * When the agent edits a slide, we upsert its awareness entry on the DECK
+ * presence doc (`deck-<deckId>`, the same doc `use-deck-presence` reads) so the
+ * editor UI lights up the agent on the exact slide it is editing:
+ *   - `metadata.slide` places the agent on that slide (sidebar avatars +
+ *     SameSlidePresenceIndicator).
+ *   - the `edit` descriptor `{ kind: "paths", paths: ["slides.<id>"] }` feeds
+ *     the lingering "AI edited" highlight over the slide thumbnail/canvas.
+ *
+ * All of this is best-effort: presence must NEVER fail the underlying write, so
+ * callers wrap this in try/catch (and it also swallows its own errors).
+ */
+import { agentTouchDocument } from "@agent-native/core/collab";
+
+/** Human-friendly label for a slide, used on the lingering edit tag. */
+export function slideLabelFor(
+  slide: { content?: unknown } | undefined,
+  slideIndex: number,
+): string {
+  const content = typeof slide?.content === "string" ? slide.content : "";
+  const match = content.match(/<h[12][^>]*>([^<]+)<\/h[12]>/i);
+  const title = match?.[1]?.trim();
+  return title || `Slide ${slideIndex + 1}`;
+}
+
+/**
+ * Record an agent slide edit on the deck presence doc. Safe to call from any
+ * action — refcount-neutral (no enter/leave needed) and never throws.
+ */
+export function touchAgentSlidePresence(args: {
+  deckId: string;
+  slideId: string;
+  label: string;
+}): void {
+  try {
+    agentTouchDocument(`deck-${args.deckId}`, {
+      metadata: { slide: args.slideId },
+      edit: {
+        descriptor: { kind: "paths", paths: [`slides.${args.slideId}`] },
+        label: args.label,
+      },
+    });
+  } catch {
+    // Presence is best-effort — swallow so it never breaks the write.
+  }
+}

package/corpus/templates/slides/actions/add-slide.ts

@@ -8,6 +8,7 @@ import { normalizeSlidePadding } from "../app/lib/normalize-slide-padding.js";
 import { getDb, schema } from "../server/db/index.js";
 import { notifyClients } from "../server/handlers/decks.js";
 import { createDeckVersionSnapshot } from "../server/lib/deck-versions.js";
+import { slideLabelFor, touchAgentSlidePresence } from "./_agent-presence.js";
 import {
   awaitLayoutFitCheck,
   formatOverflowForTool,
@@ -16,6 +17,10 @@ import {
   readAppStateForCurrentTab,
   writeAppStateForCurrentTab,
 } from "./_tab-state.js";
+// Use the shared, globalThis-pinned per-deck lock so add-slide, update-slide,
+// and the browser's patch-deck all serialise against the SAME lock — writes to
+// different slides of the same deck can never clobber each other.
+import { withDeckLock } from "./patch-deck.js";
 
 function deckDeepLink(deckId: string): string {
   return buildDeepLink({
@@ -25,23 +30,6 @@ function deckDeepLink(deckId: string): string {
   });
 }
 
-// In-process serialization per deckId. `add-slide` is intentionally advertised
-// as a sequential write, but the lock still protects against accidental
-// concurrent calls and any direct integrations that bypass agent guidance.
-const deckLocks = new Map<string, Promise<unknown>>();
-
-function withDeckLock<T>(deckId: string, fn: () => Promise<T>): Promise<T> {
-  const prev = deckLocks.get(deckId) ?? Promise.resolve();
-  const next = prev.then(fn, fn);
-  deckLocks.set(deckId, next);
-  next
-    .finally(() => {
-      if (deckLocks.get(deckId) === next) deckLocks.delete(deckId);
-    })
-    .catch(() => {});
-  return next;
-}
-
 export default defineAction({
   description:
     "Add a single slide to an existing deck. Use this to build decks slide-by-slide — " +
@@ -148,8 +136,18 @@ export default defineAction({
         .set({ data: JSON.stringify(deck), updatedAt: now })
         .where(eq(schema.decks.id, deckId));
 
+      // Best-effort agent presence: light the agent up on the newly-added slide
+      // in open editors and drop a lingering "AI edited" highlight for it. Uses
+      // the NEW slide's id. Never blocks or fails the write.
+      touchAgentSlidePresence({
+        deckId,
+        slideId: newSlideId,
+        label: slideLabelFor(newSlide, insertIndex),
+      });
+
       // Broadcast to any open editors so the new slide appears immediately.
-      notifyClients(deckId);
+      // Include the new slideId + agent actor (backwards-compatible payload).
+      notifyClients(deckId, { slideId: newSlideId, actor: "agent" });
 
       // Nudge any open editor onto the new slide so the renderer measures
       // IT (not whichever slide was previously selected). Only fires when an

package/corpus/templates/slides/actions/patch-deck.ts

@@ -76,6 +76,7 @@ const PatchSlideOp = z.object({
 const DeleteSlideOp = z.object({
   op: z.literal("delete-slide"),
   slideId: z.string(),
+  allowEmpty: z.boolean().optional(),
 });
 
 /**
@@ -166,8 +167,9 @@ export function applyOperation(deck: any, op: Operation): void {
     case "delete-slide": {
       const idx = slides.findIndex((s: { id: string }) => s.id === op.slideId);
       if (idx !== -1) slides.splice(idx, 1);
-      // Ensure at least one slide remains (mirrors client-side behaviour)
-      if (slides.length === 0) {
+      // Ensure at least one slide remains for direct user deletes. Undoing an
+      // add-slide from a legitimately empty deck opts into preserving empty.
+      if (slides.length === 0 && !op.allowEmpty) {
         slides.push({
           id: `slide-${Date.now()}-fallback`,
           content: `<div class="fmd-slide" style="padding: 80px 110px; display: flex; flex-direction: column; justify-content: center;"><div style="font-size: 28px; font-weight: 600; color: rgba(255,255,255,0.4);">Double-click to edit</div></div>`,