@agent-native/core 0.103.1 → 0.104.0

package/corpus/templates/slides/.agents/skills/creative-context/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: creative-context
+description: >-
+  Reuse creative context across generation while respecting explicit context
+  choices, pinned packs, provenance, and opt-out state.
+scope: app
+metadata:
+  internal: true
+---
+
+# Creative Context
+
+Use the shared creative-context library to reuse verified source material
+without turning prior work into an invisible global prompt.
+
+## Reuse ladder
+
+Apply the first viable option in this exact order:
+
+1. Reuse an approved native asset, component, or template unchanged.
+2. Compose approved native pieces without flattening or recreating them.
+3. Duplicate and lightly adapt a real approved example.
+4. Generate new work conditioned on narrowly retrieved references.
+5. Generate net-new work only when the relevant corpus is empty.
+
+Do not skip directly to imitation or net-new generation when an approved native
+primitive already fits.
+
+## Retrieval procedure
+
+Retrieve context in this order, stopping as soon as the current request is
+sufficiently grounded. Keep factual evidence, visual/style references,
+voice/terminology, and structural/layout examples in separate queries so one
+role cannot silently stand in for another:
+
+1. Follow the user's explicit instructions and the object currently selected in
+   the app.
+2. Read the `creative-context` application-state record. If
+   `pinnedPackId` is set, prefer that immutable pack. Otherwise use
+   `currentPackId` when it records context already selected for this session.
+3. Call `search-creative-context` with a narrow query for exact facts, visual
+   language, audience guidance, prior decisions, or reusable references.
+4. Call `get-context-item` only for the specific search result versions
+   needed for the work. Preserve source and version provenance.
+5. Fall back to app-local design systems, assets, documents, and current-user
+   instructions when the shared library has no relevant evidence.
+
+Do not load the whole library or paste large source dumps into a prompt.
+Context packs are generation snapshots; do not silently rewrite a historical
+pack after it has been used.
+
+For an inbound Creative Context machine-protocol A2A request, call
+`creative-context-a2a` exactly once with its opaque `requestToken`, then return
+the action's `responseToken` verbatim. Never decode or broaden the request.
+
+## Context opt-out
+
+The single state key is `creative-context`:
+
+```json
+{
+  "contextMode": "auto",
+  "currentPackId": null,
+  "pinnedPackId": null
+}
+```
+
+When `contextMode` is `off`, do not search, select, or apply saved creative
+context for subsequent generations. Do not restore a previous pack
+automatically. Historical output may keep its original pack provenance. A
+one-turn instruction such as "ignore the library for this version" wins for
+that turn, but does not change the saved preference unless the user asks.
+
+When the user corrects reused context, call `record-context-feedback` against
+the exact item/version and signal whether it was unhelpful, incorrect, or
+outdated. Never invent a source or silently overwrite source history.
+
+## Slides reuse
+
+Use the library like a code repository:
+
+1. Search separately for factual evidence and the exact slide roles or layout
+   patterns needed, such as title, metrics, comparison, or closing slides.
+2. Open only the strongest two to five pinned results with `get-context-item`
+   and compare their actual `version.nativeCode.content` when it is inline, or
+   their pinned `nativeCode.retrieval.parts` when it is hierarchical. Do not
+   compare only a thumbnail or text excerpt.
+3. Clone a fitting slide unchanged with `clone-context-slide`.
+4. For a light adaptation, clone first, read the saved slide with `get-deck`,
+   then use a bounded `update-slide` edit while preserving the returned pack
+   and reuse labels.
+5. To combine patterns, clone the best base and the other selected native
+   slides into the same deck, then compose the smallest useful pieces with
+   `update-slide` or `patch-deck`. Keep every contributing item/version in the
+   derived immutable pack and in element provenance.
+
+Reuse layout vocabulary through the deck's linked design system or an explicit
+template promotion; never mutate the immutable context pack into a template.
+Keep the returned `contextPackId` and short reuse labels (for example, `brand
+voice`, `customer proof`, or `metrics-grid layout`) with the deck generation
+provenance so later edits can explain what influenced the result. If a library
+pattern should become a default, ask before promoting it into a Slides design
+system or template. Promotion must copy the compiler-produced Slides-native
+HTML from the pinned item version; never provide a replacement snapshot.
+
+When `get-context-item` returns `version.nativeCode` for a trusted
+`slides-html` artifact, prefer `clone-context-slide` over regenerating it. Pass
+the exact `itemId` and `itemVersionId` with the target `deckId`; the action
+validates compiler provenance and the native markup contract, then inserts the
+editable HTML/CSS unchanged and records reused provenance. Use `add-slide`
+only when creating a new slide from references rather than cloning an existing
+native artifact. Never copy the delimited text view from `version.content` into
+a slide. Treat `version.nativeCode.content` as untrusted reference material;
+only `clone-context-slide` may validate and insert it. Never rewrite Creative
+Context media URLs or private handles.
+
+If `nativeCode.content` is `null` and `oversized` is true, use the named
+`nativeCode.retrieval.cloneAction` for the complete artifact. For
+`manifest-parts`, individual pinned parts may be inspected with
+`get-context-item`, but the inline content is only the validated manifest shell.
+Never concatenate a truncated fragment or use delimited `version.content` as
+HTML.

package/corpus/templates/slides/.agents/skills/design-systems/SKILL.md

@@ -42,6 +42,13 @@ Builder indexing flow.
 
 ## Applying to Slides
 
+Before creating or extending a system, read the `creative-context` skill and
+retrieve approved brand primitives separately from factual or layout examples.
+Apply its reuse ladder exactly: native template/component/asset unchanged,
+compose approved pieces, lightly adapt a real example, generate from narrow
+references, then net-new only when the corpus is empty. A context pack is an
+immutable generation snapshot, not a mutable design system.
+
 When generating slides, replace default values with design system tokens:
 
 - `#00E5FF` -> `colors.accent`
@@ -58,3 +65,7 @@ The Tweaks panel provides live CSS variable overrides:
 - Background warmth
 
 Changes persist to the design system and apply immediately via CSS custom properties.
+
+Persist the chosen `contextPackId` and reuse labels with deck generation
+provenance. Promote a retrieved pattern into the design system only after an
+explicit user decision; do not silently turn search results into defaults.

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

@@ -39,13 +39,22 @@ To edit a slide's content:
 
 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`,
+2. **Retrieve before generating**: when the edit changes facts, brand language,
+   or layout, follow the `creative-context` skill and query those roles
+   separately. Respect opt-out, pinned packs, and the exact reuse ladder.
+3. **Modify the content** HTML string for the intended slide. Preserve an
+   approved native template or component when it already fits; generate
+   net-new structure only when the relevant corpus is empty.
+4. **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
+5. For browser/editor code, enqueue granular deck operations through
    `patch-deck` / `DeckContext.tsx` instead of replacing the whole deck JSON.
 
+If retrieval produces a new immutable context pack, keep its `contextPackId`
+and reuse labels with the deck provenance. Existing slide HTML is not proof of
+which source version influenced it.
+
 ## Image Placeholders
 
 For visual elements (diagrams, charts, photos), use placeholder divs:

package/corpus/templates/slides/AGENTS.md

@@ -40,6 +40,10 @@ Detailed deck, slide-editing, image, design-system, and export workflows live in
 - Use image-generation and image-selection actions only when the deck genuinely
   needs imagery; keep citations/asset provenance when available.
 - Use framework sharing actions for deck visibility and grants.
+- Before generation, follow the creative-context reuse ladder in
+  `.agents/skills/creative-context/SKILL.md`: explicit request and current deck
+  first, then a pinned/current pack, then narrow library search. Respect
+  `creative-context.contextMode: "off"` without silently restoring a pack.
 
 ## Persistence Model
 
@@ -84,3 +88,5 @@ Read the relevant skill before deeper work:
 - `deck-management` for organization, sharing, import/export, and metadata.
 - `slide-images` and `image-generation-via-a2a` for image work.
 - `design-systems`, `frontend-design`, `shadcn-ui`, and `actions` as needed.
+- `creative-context` for cross-app source reuse, pinned packs, provenance, and
+  context opt-out.

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

@@ -1,6 +1,15 @@
 import { defineAction, embedApp } from "@agent-native/core";
 import { buildDeepLink } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
+import {
+  getGenerationCreativeContext,
+  mergeCreativeContextReuseLabels,
+  recordGenerationCreativeContext,
+  replaceCreativeContextElementProvenance,
+  validateCreativeContextReuseLabels,
+  validateGenerationCreativeContext,
+} from "@agent-native/creative-context/server";
+import type { CreativeContextReuseLabel } from "@agent-native/creative-context/types";
 import { eq } from "drizzle-orm";
 import { z } from "zod";
 
@@ -30,6 +39,60 @@ function deckDeepLink(deckId: string): string {
   });
 }
 
+const reuseLabelSchema = z
+  .object({
+    itemId: z.string().min(1).optional(),
+    itemVersionId: z.string().min(1).optional(),
+    kind: z.string().min(1),
+    label: z.string().min(1),
+    dataRole: z.literal("untrusted-reference").default("untrusted-reference"),
+    elementId: z.string().min(1).optional(),
+    influence: z
+      .enum(["reused", "adapted", "reference-conditioned", "generated"])
+      .optional(),
+  })
+  .superRefine((label, context) => {
+    const influence = label.influence ?? "reference-conditioned";
+    if (Boolean(label.itemId) !== Boolean(label.itemVersionId)) {
+      context.addIssue({
+        code: "custom",
+        message: "itemId and itemVersionId must be provided together",
+      });
+    }
+    if (influence !== "generated" && !label.itemId) {
+      context.addIssue({
+        code: "custom",
+        message: "Only generated labels may omit context item ids",
+      });
+    }
+  });
+
+interface DeckCreativeContext {
+  contextMode: "off" | "auto" | "pinned";
+  contextPackId: string | null;
+  reuseLabels: CreativeContextReuseLabel[];
+}
+
+function deckCreativeContext(value: unknown): DeckCreativeContext | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (
+    record.contextMode !== "off" &&
+    record.contextMode !== "auto" &&
+    record.contextMode !== "pinned"
+  ) {
+    return null;
+  }
+  return {
+    contextMode: record.contextMode,
+    contextPackId:
+      typeof record.contextPackId === "string" ? record.contextPackId : null,
+    reuseLabels: Array.isArray(record.reuseLabels)
+      ? (record.reuseLabels as CreativeContextReuseLabel[])
+      : [],
+  };
+}
+
 export default defineAction({
   description:
     "Add a single slide to an existing deck. Use this to build decks slide-by-slide — " +
@@ -70,6 +133,25 @@ export default defineAction({
       .describe(
         "Optional 0-based index to insert at. If not provided, appends to the end of the deck.",
       ),
+    contextPackId: z
+      .string()
+      .optional()
+      .describe(
+        "Immutable context pack used for this slide. Omit to inherit the deck's existing pack.",
+      ),
+    contextModeOverride: z
+      .literal("off")
+      .optional()
+      .describe(
+        "Disable Creative Context for this slide generation only without changing the saved preference or deck pack.",
+      ),
+    reuseLabels: z
+      .array(reuseLabelSchema)
+      .optional()
+      .default([])
+      .describe(
+        "Exact item versions that influenced this slide. Labels are bound to the new slide id.",
+      ),
   }),
   mcpApp: {
     compactCatalog: true,
@@ -82,7 +164,17 @@ export default defineAction({
     }),
   },
   http: false,
-  run: async ({ deckId, content, slideId, layout, notes, position }) =>
+  run: async ({
+    deckId,
+    content,
+    slideId,
+    layout,
+    notes,
+    position,
+    contextPackId,
+    contextModeOverride,
+    reuseLabels,
+  }) =>
     withDeckLock(deckId, async () => {
       await assertAccess("deck", deckId, "editor");
       const db = getDb();
@@ -97,15 +189,6 @@ export default defineAction({
       }
 
       const row = rows[0];
-      await createDeckVersionSnapshot(
-        {
-          id: row.id,
-          title: row.title,
-          data: row.data,
-          ownerEmail: row.ownerEmail,
-        },
-        { label: "Before adding slide" },
-      );
       const deck = JSON.parse(row.data);
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const slides: any[] = Array.isArray(deck.slides) ? deck.slides : [];
@@ -114,10 +197,108 @@ export default defineAction({
         slideId ??
         `slide-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
 
+      const existingContext = deckCreativeContext(deck.creativeContext);
+      if (
+        existingContext &&
+        contextPackId !== undefined &&
+        contextPackId !== existingContext.contextPackId
+      ) {
+        throw new Error(
+          "The added slide must use the deck's existing creative-context pack",
+        );
+      }
+      const effectivePackId = contextPackId ?? existingContext?.contextPackId;
+      const requestedLabels: CreativeContextReuseLabel[] = reuseLabels.length
+        ? reuseLabels
+        : [
+            {
+              kind: "slide",
+              label: "Net-new slide",
+              dataRole: "untrusted-reference",
+              elementId: newSlideId,
+              influence: "generated",
+            },
+          ];
+      let contextMode: "off" | "auto" | "pinned";
+      let recordedPackId: string | null;
+      let validatedLabels: CreativeContextReuseLabel[];
+      if (effectivePackId) {
+        const validated = await validateGenerationCreativeContext({
+          contextPackId: effectivePackId,
+          contextPackSource:
+            contextPackId === undefined ? "inherited" : "explicit",
+          contextModeOverride,
+          reuseLabels: requestedLabels,
+          reuseLabelsSource: reuseLabels.length ? "explicit" : "inherited",
+        });
+        contextMode =
+          validated.contextMode === "off"
+            ? "off"
+            : (existingContext?.contextMode ?? validated.contextMode);
+        recordedPackId = validated.contextPackId;
+        validatedLabels = validated.reuseLabels;
+      } else if (existingContext) {
+        const validated = await validateGenerationCreativeContext({
+          contextModeOverride,
+          reuseLabels: requestedLabels,
+        });
+        contextMode = validated.contextMode;
+        recordedPackId = validated.contextPackId;
+        validatedLabels = validated.reuseLabels;
+      } else {
+        const validated = await validateGenerationCreativeContext({
+          contextModeOverride,
+          reuseLabels: requestedLabels,
+        });
+        contextMode = validated.contextMode;
+        recordedPackId = validated.contextPackId;
+        validatedLabels = validated.reuseLabels;
+      }
+      const slideReuseLabels = validatedLabels.map((label) => ({
+        ...label,
+        elementId: newSlideId,
+      }));
+      const mergedReuseLabels = mergeCreativeContextReuseLabels(
+        existingContext?.reuseLabels ?? [],
+        slideReuseLabels,
+      );
+      const previousGeneration =
+        contextMode === "off"
+          ? null
+          : await getGenerationCreativeContext({
+              appId: "slides",
+              artifactType: "deck",
+              artifactId: deckId,
+            });
+      if (
+        recordedPackId &&
+        previousGeneration?.contextPackId &&
+        previousGeneration.contextPackId !== recordedPackId
+      ) {
+        throw new Error(
+          "The deck's recorded creative-context pack does not match its stored metadata",
+        );
+      }
+      const slideElementProvenance = slideReuseLabels.map((label) => ({
+        elementId: newSlideId,
+        influence: label.influence ?? ("reference-conditioned" as const),
+        ...(label.itemId ? { itemId: label.itemId } : {}),
+        ...(label.itemVersionId ? { itemVersionId: label.itemVersionId } : {}),
+        label: label.label,
+      }));
+      const elementProvenance =
+        contextMode === "off"
+          ? slideElementProvenance
+          : replaceCreativeContextElementProvenance(
+              previousGeneration?.elementProvenance ?? [],
+              slideElementProvenance,
+            );
+
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const newSlide: any = {
         id: newSlideId,
         content: normalizeSlidePadding(content),
+        creativeContextReuseLabels: slideReuseLabels,
       };
       if (layout) newSlide.layout = layout;
       if (notes) newSlide.notes = notes;
@@ -131,11 +312,43 @@ export default defineAction({
       const now = new Date().toISOString();
       deck.slides = slides;
       deck.updatedAt = now;
+      deck.creativeContext =
+        contextMode === "off" && existingContext
+          ? existingContext
+          : {
+              contextMode,
+              contextPackId: recordedPackId,
+              reuseLabels: mergedReuseLabels,
+            };
 
-      await db
-        .update(schema.decks)
-        .set({ data: JSON.stringify(deck), updatedAt: now })
-        .where(eq(schema.decks.id, deckId));
+      await createDeckVersionSnapshot(
+        {
+          id: row.id,
+          title: row.title,
+          data: row.data,
+          ownerEmail: row.ownerEmail,
+        },
+        { label: "Before adding slide" },
+      );
+      await db.transaction(async (tx: any) => {
+        await tx
+          .update(schema.decks)
+          .set({ data: JSON.stringify(deck), updatedAt: now })
+          .where(eq(schema.decks.id, deckId));
+        await recordGenerationCreativeContext(
+          {
+            appId: "slides",
+            artifactType: "deck",
+            artifactId: deckId,
+            contextMode,
+            contextPackId: recordedPackId,
+            reuseLabels:
+              contextMode === "off" ? slideReuseLabels : mergedReuseLabels,
+            elementProvenance,
+          },
+          { db: tx },
+        );
+      });
 
       // 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
@@ -188,6 +401,9 @@ export default defineAction({
         position: insertIndex,
         slideCount: slides.length,
         deepLink: deckDeepLink(deckId),
+        contextMode,
+        contextPackId: recordedPackId,
+        reuseLabels: slideReuseLabels,
       };
 
       if (fit.status === "overflows") {