@agent-native/core-corpus 0.214.0 → 0.216.0

package/corpus/templates/slides-2/actions/clone-context-slide.ts

@@ -0,0 +1,340 @@
+import { defineAction, embedApp, fail } from "@agent-native/core";
+import { readAppState } from "@agent-native/core/application-state";
+import { buildDeepLink } from "@agent-native/core/server";
+import { assertAccess } from "@agent-native/core/sharing";
+import {
+  nativeCreativeArtifactFromMetadata,
+  reassembleNativeCreativeArtifact,
+  validateCompiledNativeHtml,
+} from "@agent-native/creative-context";
+import {
+  assertCreativeContextLabEnabled,
+  getGenerationCreativeContext,
+  mergeCreativeContextReuseLabels,
+  recordGenerationCreativeContext,
+  replaceCreativeContextElementProvenance,
+} from "@agent-native/creative-context/server";
+import {
+  createContextPack,
+  deriveContextPack,
+  getCreativeContextItem,
+  getCreativeContextItemByExternalId,
+} from "@agent-native/creative-context/store";
+import type { ContextDetail } from "@agent-native/creative-context/types";
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { validateNativeSlideHtml } from "../app/lib/validate-native-slide-html.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 { getDeckUrl } from "./_app-url.js";
+import { assertSlides2DeckData } from "./_deck-app-scope.js";
+import {
+  assertDeckWriteApplied,
+  deckRevisionWhere,
+  nextDeckRevision,
+} from "./_deck-write.js";
+import { withDeckLock } from "./patch-deck.js";
+
+export function cloneableNativeSlide(context: ContextDetail): {
+  content: string;
+  notes?: string;
+  sourceExternalId: string;
+} {
+  const artifact = nativeCreativeArtifactFromMetadata(context.version.metadata);
+  if (
+    !artifact ||
+    artifact.app !== "slides" ||
+    artifact.format !== "slides-html" ||
+    context.version.mimeType !== "text/html"
+  ) {
+    fail("Creative Context item is not a Slides-native artifact.", {
+      errorCode: "creative_context_artifact_invalid",
+      statusCode: 422,
+    });
+  }
+  if (!context.version.content.includes("google-slides-native")) {
+    fail("Slides-native artifact code is missing its compiler root.", {
+      errorCode: "creative_context_compiler_root_missing",
+      statusCode: 422,
+    });
+  }
+  if (
+    context.item.provenance.compiler !==
+    "@agent-native/creative-context:google-slides-native"
+  ) {
+    fail("Slides-native artifact compiler provenance is untrusted.", {
+      errorCode: "creative_context_compiler_untrusted",
+      statusCode: 422,
+    });
+  }
+  validateCompiledNativeHtml(context.version.content, artifact);
+  const metadata = context.version.metadata;
+  const notes =
+    metadata &&
+    typeof metadata === "object" &&
+    !Array.isArray(metadata) &&
+    typeof (metadata as Record<string, unknown>).speakerNotes === "string"
+      ? ((metadata as Record<string, unknown>).speakerNotes as string)
+      : undefined;
+  return {
+    content: artifact.manifest
+      ? context.version.content
+      : validateNativeSlideHtml(context.version.content),
+    ...(notes ? { notes } : {}),
+    sourceExternalId: artifact.rootExternalId,
+  };
+}
+
+export default defineAction({
+  description:
+    "Clone one pinned Google Slides-native Creative Context item into an existing deck without regenerating or rewriting its editable HTML/CSS. Returns a link that opens the cloned slide in Slides.",
+  schema: z.object({
+    deckId: z.string().min(1).describe("Target Slides deck"),
+    itemId: z.string().min(1).describe("Creative Context item id"),
+    itemVersionId: z
+      .string()
+      .min(1)
+      .describe("Pinned immutable Creative Context version id"),
+    position: z.number().int().min(0).optional(),
+    slideId: z.string().min(1).optional(),
+  }),
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Cloned native slide",
+      description: "Open the exact cloned artifact in the Slides 2 editor.",
+      iframeTitle: "Agent-Native Slides 2",
+      openLabel: "Open cloned slide",
+      height: 680,
+    }),
+  },
+  http: false,
+  mcpAnnotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+  },
+  run: async ({ deckId, itemId, itemVersionId, position, slideId }) => {
+    await assertCreativeContextLabEnabled();
+    const contextState = (await readAppState("creative-context")) as {
+      contextMode?: "auto" | "off";
+    } | null;
+    if (contextState?.contextMode === "off") {
+      fail(
+        "Creative Context is off. Enable it before cloning a library slide.",
+        {
+          errorCode: "creative_context_disabled",
+          statusCode: 412,
+        },
+      );
+    }
+    const context = await getCreativeContextItem(itemId, itemVersionId);
+    if (!context || context.version.id !== itemVersionId) {
+      fail("Pinned Creative Context item version was not found.", {
+        errorCode: "creative_context_version_not_found",
+        statusCode: 404,
+      });
+    }
+    const source = cloneableNativeSlide(context);
+    const reassembled = await reassembleNativeCreativeArtifact({
+      root: context,
+      app: "slides",
+      format: "slides-html",
+      resolveChild: getCreativeContextItemByExternalId,
+    });
+    source.content = validateNativeSlideHtml(reassembled.html);
+    return withDeckLock(deckId, async () => {
+      await assertAccess("deck", deckId, "editor");
+      const db = getDb();
+      const [row] = await db
+        .select()
+        .from(schema.decks)
+        .where(eq(schema.decks.id, deckId));
+      if (!row)
+        fail(`Deck ${deckId} not found`, {
+          errorCode: "deck_not_found",
+          statusCode: 404,
+        });
+      const deck = JSON.parse(row.data) as Record<string, unknown>;
+      assertSlides2DeckData(deck);
+      const slides = Array.isArray(deck.slides)
+        ? ([...deck.slides] as Array<Record<string, unknown>>)
+        : [];
+      const newSlideId = slideId ?? `slide-${nanoid(10)}`;
+      const reuseLabel = {
+        itemId,
+        itemVersionId,
+        kind: "google-slides-native-slide",
+        label: "Cloned native Google Slides artifact",
+        dataRole: "untrusted-reference" as const,
+        elementId: newSlideId,
+        influence: "reused" as const,
+      };
+      const clonedSlide = {
+        id: newSlideId,
+        content: source.content,
+        layout: "blank",
+        notes: source.notes ?? "",
+        creativeContextReuseLabels: [reuseLabel],
+        nativeArtifactSource: {
+          itemId,
+          itemVersionId,
+          externalId: source.sourceExternalId,
+        },
+      };
+      const insertAt =
+        position === undefined
+          ? slides.length
+          : Math.max(0, Math.min(position, slides.length));
+      slides.splice(insertAt, 0, clonedSlide);
+      const now = nextDeckRevision(row.updatedAt);
+      const existingContext =
+        deck.creativeContext &&
+        typeof deck.creativeContext === "object" &&
+        !Array.isArray(deck.creativeContext)
+          ? (deck.creativeContext as Record<string, unknown>)
+          : {};
+      const existingContextPackId =
+        typeof existingContext.contextPackId === "string"
+          ? existingContext.contextPackId
+          : null;
+      const existingLabels = Array.isArray(existingContext.reuseLabels)
+        ? existingContext.reuseLabels
+        : [];
+      if (existingContext.contextMode === "off") {
+        fail(
+          "Creative Context is disabled for this deck. Enable it before cloning a library slide.",
+          { errorCode: "creative_context_disabled", statusCode: 412 },
+        );
+      }
+      const evidenceMembers = reassembled.evidence.map((entry) => ({
+        ...entry,
+        reason: "Exact native Google Slides reuse",
+      }));
+      const pack = existingContextPackId
+        ? await deriveContextPack({
+            packId: existingContextPackId,
+            name: `Clone: ${context.item.title}`.slice(0, 200),
+            addMembers: evidenceMembers,
+          })
+        : await createContextPack({
+            name: `Clone: ${context.item.title}`.slice(0, 200),
+            contextMode: "manual",
+            request: {
+              operation: "clone-native-artifact",
+              appId: "slides",
+              rootItemId: context.item.id,
+              rootItemVersionId: context.version.id,
+            },
+            members: evidenceMembers,
+          });
+      const contextMode = "pinned" as const;
+      const contextPackId = pack.id;
+      const evidenceLabels = reassembled.evidence.map((entry, index) => ({
+        ...entry,
+        kind: "google-slides-native-slide",
+        label:
+          entry.itemId === context.item.id
+            ? "Cloned native Google Slides artifact"
+            : `Native child ${index + 1}`,
+        dataRole: "untrusted-reference" as const,
+        elementId:
+          entry.itemId === context.item.id
+            ? newSlideId
+            : `${newSlideId}:evidence:${index + 1}`,
+        influence: "reused" as const,
+      }));
+      const reuseLabels = mergeCreativeContextReuseLabels(
+        existingLabels as (typeof reuseLabel)[],
+        evidenceLabels,
+      );
+      deck.slides = slides;
+      deck.updatedAt = now;
+      deck.creativeContext = { contextMode, contextPackId, reuseLabels };
+      const previousGeneration = await getGenerationCreativeContext({
+        appId: "slides-2",
+        artifactType: "deck",
+        artifactId: deckId,
+      });
+      const elementProvenance = replaceCreativeContextElementProvenance(
+        previousGeneration?.elementProvenance ?? [],
+        evidenceLabels.map((entry) => ({
+          elementId: entry.elementId,
+          itemId: entry.itemId,
+          itemVersionId: entry.itemVersionId,
+          influence: entry.influence,
+          label: entry.label,
+        })),
+      );
+
+      await db.transaction(async (tx: any) => {
+        await createDeckVersionSnapshot(
+          {
+            id: row.id,
+            title: row.title,
+            data: row.data,
+            ownerEmail: row.ownerEmail,
+          },
+          { label: "Before cloning Creative Context slide", db: tx },
+        );
+        const updateResult = await tx
+          .update(schema.decks)
+          .set({ data: JSON.stringify(deck), updatedAt: now })
+          .where(deckRevisionWhere(schema.decks, deckId, row.updatedAt));
+        assertDeckWriteApplied(
+          updateResult,
+          deckId,
+          "Creative Context slide clone",
+        );
+        await recordGenerationCreativeContext(
+          {
+            appId: "slides-2",
+            artifactType: "deck",
+            artifactId: deckId,
+            contextMode,
+            contextPackId,
+            reuseLabels,
+            elementProvenance,
+          },
+          { db: tx },
+        );
+      });
+      await notifyClients(deckId, { slideId: newSlideId, actor: "agent" });
+      return {
+        deckId,
+        slideId: newSlideId,
+        slideNumber: insertAt + 1,
+        slideCount: slides.length,
+        itemId,
+        itemVersionId,
+        contextPackId,
+        evidenceCount: reassembled.evidence.length,
+        clonedWithoutRegeneration: true,
+        deepLink: buildDeepLink({
+          app: "slides-2",
+          view: "editor",
+          params: { deckId, slideId: newSlideId },
+        }),
+        url: getDeckUrl(deckId),
+      };
+    });
+  },
+  link: ({ result }) => {
+    const value = result as { deckId?: string; deepLink?: string } | undefined;
+    if (!value?.deckId) return null;
+    return {
+      url:
+        value.deepLink ??
+        buildDeepLink({
+          app: "slides-2",
+          view: "editor",
+          params: { deckId: value.deckId },
+        }),
+      label: "Open cloned slide in Slides 2",
+      view: "editor",
+    };
+  },
+});

package/corpus/templates/slides-2/actions/clone-creative-context-deck.ts

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+
+import { defineAction, fail } from "@agent-native/core/action";
+import {
+  readPrivateBlob,
+  type PrivateBlobHandle,
+} from "@agent-native/core/private-blob";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { resolveNativeContextCloneReference } from "@agent-native/creative-context/server";
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { withSlideAssetReferencesLocked } from "../server/lib/slide-asset-references.js";
+import { getDeckUrl } from "./_app-url.js";
+import { trackDeckCreated } from "./_deck-tracking.js";
+import { assertDeckInlineImagesPersistable } from "./_render-artifacts.js";
+
+export default defineAction({
+  description:
+    "Clone one exact governed Slides deck version without exposing its native payload.",
+  schema: z.object({
+    contextId: z.string(),
+    artifactKey: z.string(),
+    resourceId: z.string(),
+    expectedUpdatedAt: z.string().optional(),
+    title: z.string().optional(),
+  }),
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  mcpAnnotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+  },
+  run: async (args, ctx) => {
+    const reference = await resolveNativeContextCloneReference({
+      appId: "slides",
+      resourceType: "deck",
+      resourceId: args.resourceId,
+      expectedUpdatedAt: args.expectedUpdatedAt,
+      contextId: args.contextId,
+      artifactKey: args.artifactKey,
+    });
+    const raw = await readPrivateBlob(
+      reference.cloneHandle as PrivateBlobHandle,
+    );
+    const data = Buffer.from(raw.data).toString("utf8");
+    const contentHash = createHash("sha256").update(data).digest("hex");
+    if (
+      raw.metadata?.appId !== "slides" ||
+      raw.metadata?.resourceType !== "deck" ||
+      raw.metadata?.resourceId !== args.resourceId ||
+      raw.metadata?.contentHash !== contentHash
+    )
+      fail("Governed deck clone payload failed integrity verification.", {
+        errorCode: "creative_context_clone_integrity_failed",
+        statusCode: 422,
+      });
+    const parsed: unknown = JSON.parse(data);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      fail("Deck not found.", {
+        errorCode: "deck_not_found",
+        statusCode: 404,
+      });
+    }
+    const deck = parsed as Record<string, unknown> & {
+      slides?: Array<Record<string, unknown>>;
+      title?: string;
+      designSystemId?: string;
+    };
+    if (Object.hasOwn(deck, "appId") && deck.appId !== "slides") {
+      fail("Deck not found.", {
+        errorCode: "deck_not_found",
+        statusCode: 404,
+      });
+    }
+    const email = getRequestUserEmail();
+    if (!email)
+      fail("no authenticated user", {
+        errorCode: "not_authenticated",
+        statusCode: 401,
+      });
+    const id = `deck-${nanoid()}`;
+    const now = new Date().toISOString();
+    const title = args.title?.trim() || `Copy of ${deck.title ?? "deck"}`;
+    deck.appId = "slides-2";
+    deck.title = title;
+    deck.createdAt = now;
+    deck.updatedAt = now;
+    deck.slides = (deck.slides ?? []).map((slide) => ({
+      ...slide,
+      id: `slide-${nanoid(8)}`,
+    }));
+    assertDeckInlineImagesPersistable(null, deck);
+    const orgId = getRequestOrgId() ?? null;
+    await withSlideAssetReferencesLocked(
+      getDb(),
+      deck,
+      { ownerEmail: email, orgId },
+      async (tx) => {
+        await tx.insert(schema.decks).values({
+          id,
+          title,
+          data: JSON.stringify(deck),
+          designSystemId: deck.designSystemId ?? null,
+          ownerEmail: email,
+          orgId,
+          createdAt: now,
+          updatedAt: now,
+        });
+      },
+    );
+    const [saved] = await getDb()
+      .select({ id: schema.decks.id, title: schema.decks.title })
+      .from(schema.decks)
+      .where(eq(schema.decks.id, id));
+    if (!saved)
+      fail("Deck clone did not persist.", {
+        errorCode: "deck_clone_persistence_unverified",
+        statusCode: 500,
+      });
+    trackDeckCreated(
+      saved.id,
+      {
+        creationMethod: "duplicate",
+        purpose: "direct",
+        slideCount: deck.slides.length,
+      },
+      ctx,
+    );
+    return {
+      id: saved.id,
+      title: saved.title,
+      slideCount: deck.slides.length,
+      url: getDeckUrl(id),
+      clonedExactVersion: reference.publishedItemVersionId,
+    };
+  },
+});

package/corpus/templates/slides-2/actions/control-deck-history.ts

@@ -0,0 +1,186 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { assertAccess, ForbiddenError } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import { appStateKey } from "../shared/app-state-tabs.js";
+import {
+  deckHistoryCommandSchema,
+  deckHistoryStatusSchema,
+  DECK_HISTORY_COMMAND_KEY,
+  DECK_HISTORY_STATUS_KEY,
+  isDeckHistoryOperationAvailable,
+} from "../shared/deck-history-control.js";
+import { assertSlides2DeckData } from "./_deck-app-scope.js";
+import {
+  compareAndSetAppStateForCurrentTab,
+  getCurrentRequestBrowserTabId,
+  readAppStateForCurrentTab,
+} from "./_tab-state.js";
+
+export default defineAction({
+  title: "Undo or redo a deck edit",
+  description:
+    "Queue one Undo or Redo command in the active Slides 2 DeckEditor. Copy deckId, editorSessionId, and historyVersion from the latest view-screen result, then provide a fresh commandId. The command applies only while that tab and history state still match; call this action again with the same commandId to read its result.",
+  schema: z.object({
+    deckId: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe("Active deck ID from view-screen"),
+    operation: z.enum(["undo", "redo"]).describe("Edit history operation"),
+    commandId: z
+      .string()
+      .regex(/^[A-Za-z0-9_-]{8,128}$/)
+      .describe("Fresh unique command ID; reuse only to retry this exact call"),
+    editorSessionId: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe("Deck editor session ID from the latest view-screen result"),
+    historyVersion: z
+      .number()
+      .safe()
+      .int()
+      .nonnegative()
+      .describe(
+        "Deck editor history version from the latest view-screen result",
+      ),
+  }),
+  retrySafe: true,
+  http: false,
+  mcpAnnotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+  },
+  run: async (input) => {
+    if (!getCurrentRequestBrowserTabId()) {
+      fail("An active browser tab is required to control deck history.", {
+        statusCode: 409,
+        errorCode: "deck_history_tab_required",
+      });
+    }
+
+    let access;
+    try {
+      access = await assertAccess("deck", input.deckId, "editor");
+    } catch (error) {
+      if (error instanceof ForbiddenError) {
+        fail("Deck not found.", {
+          statusCode: 404,
+          errorCode: "deck_not_found",
+        });
+      }
+      throw error;
+    }
+    assertSlides2DeckData(access.resource.data);
+
+    const navigation = await readAppStateForCurrentTab(
+      appStateKey("navigation"),
+      { fallbackToGlobal: false },
+    );
+    if (
+      navigation?.app !== "slides-2" ||
+      navigation.view !== "editor" ||
+      navigation.deckId !== input.deckId
+    ) {
+      fail("The active tab is no longer showing this deck editor.", {
+        statusCode: 409,
+        errorCode: "deck_history_context_stale",
+      });
+    }
+
+    const commandKey = appStateKey(DECK_HISTORY_COMMAND_KEY);
+    const existingCommand = await readAppStateForCurrentTab(commandKey, {
+      fallbackToGlobal: false,
+    });
+    const parsedExisting = deckHistoryCommandSchema.safeParse(existingCommand);
+    if (!parsedExisting.success && existingCommand !== null) {
+      fail("The deck history command state is invalid.", {
+        statusCode: 409,
+        errorCode: "deck_history_command_state_invalid",
+      });
+    }
+    if (parsedExisting.success) {
+      const current = parsedExisting.data;
+      if (current.commandId === input.commandId) {
+        const sameCommand =
+          current.operation === input.operation &&
+          current.deckId === input.deckId &&
+          current.editorSessionId === input.editorSessionId &&
+          current.historyVersion === input.historyVersion;
+        if (!sameCommand) {
+          fail("That command ID was already used for different deck history.", {
+            statusCode: 409,
+            errorCode: "deck_history_command_id_conflict",
+          });
+        }
+        return {
+          commandId: current.commandId,
+          operation: current.operation,
+          status: current.status,
+          ...(current.failureCode ? { failureCode: current.failureCode } : {}),
+        };
+      }
+      if (current.status === "pending") {
+        fail("Another deck history command is still pending.", {
+          statusCode: 409,
+          errorCode: "deck_history_command_pending",
+        });
+      }
+    }
+
+    const statusState = await readAppStateForCurrentTab(
+      appStateKey(DECK_HISTORY_STATUS_KEY),
+      { fallbackToGlobal: false },
+    );
+    const status = deckHistoryStatusSchema.safeParse(statusState);
+    if (
+      !status.success ||
+      status.data.deckId !== input.deckId ||
+      status.data.editorSessionId !== input.editorSessionId ||
+      status.data.historyVersion !== input.historyVersion
+    ) {
+      fail("Deck history changed. Read view-screen again before retrying.", {
+        statusCode: 409,
+        errorCode: "deck_history_state_stale",
+      });
+    }
+    if (!isDeckHistoryOperationAvailable(status.data, input.operation)) {
+      fail(`The ${input.operation} command is not available right now.`, {
+        statusCode: 409,
+        errorCode: "deck_history_command_unavailable",
+      });
+    }
+
+    const pendingCommand = deckHistoryCommandSchema.parse({
+      protocolVersion: 1,
+      commandId: input.commandId,
+      operation: input.operation,
+      deckId: input.deckId,
+      editorSessionId: input.editorSessionId,
+      historyVersion: input.historyVersion,
+      status: "pending",
+    });
+    const didQueue = await compareAndSetAppStateForCurrentTab(
+      commandKey,
+      existingCommand,
+      pendingCommand,
+    );
+    if (!didQueue) {
+      fail(
+        "The deck history command queue changed. Read view-screen and retry.",
+        {
+          statusCode: 409,
+          errorCode: "deck_history_command_conflict",
+        },
+      );
+    }
+
+    return {
+      commandId: input.commandId,
+      operation: input.operation,
+      status: "pending",
+    };
+  },
+});