@agent-native/creative-context 0.1.0 → 0.3.0

package/src/actions/get-creative-context.spec.ts

@@ -248,6 +248,18 @@ describe("get-context-item public-agent boundary", () => {
           },
         },
       },
+      edges: [
+        {
+          id: "edge-child-1",
+          fromItemId: "item-1",
+          fromItemVersionId: "version-1",
+          toItemId: "item-child-1",
+          toItemVersionId: "version-child-1",
+          toExternalId: "figma-file:child-1",
+          relation: "contains-native-child",
+          metadata: {},
+        },
+      ],
     });
 
     const result = (await action.run({
@@ -259,6 +271,18 @@ describe("get-context-item public-agent boundary", () => {
       dataRole: "untrusted-reference",
       format: "design-html",
       content: html,
+      retrieval: {
+        mode: "manifest-parts",
+        root: { itemId: "item-1", itemVersionId: "version-1" },
+        cloneAction: "clone-creative-context-design",
+        parts: [
+          {
+            externalId: "figma-file:child-1",
+            itemId: "item-child-1",
+            itemVersionId: "version-child-1",
+          },
+        ],
+      },
     });
     expect(mocks.getCreativeContextItemByExternalId).not.toHaveBeenCalled();
   });
@@ -305,11 +329,107 @@ describe("get-context-item public-agent boundary", () => {
           },
         },
       },
+      edges: [
+        {
+          id: "edge-child-1",
+          fromItemId: "item-1",
+          fromItemVersionId: "version-1",
+          toItemId: "item-child-1",
+          toItemVersionId: "version-child-1",
+          toExternalId: "figma-file:child-1",
+          relation: "contains-native-child",
+          metadata: {},
+        },
+      ],
     });
 
     const result = (await action.run({ itemId: "item-1" })) as any;
 
-    expect(result.version.nativeCode).toBeNull();
+    expect(result.version.nativeCode).toEqual({
+      dataRole: "untrusted-reference",
+      format: "design-html",
+      content: null,
+      oversized: true,
+      byteLength: Buffer.byteLength(html, "utf8"),
+      maxInlineBytes: 128 * 1024,
+      retrieval: {
+        mode: "manifest-parts",
+        root: { itemId: "item-1", itemVersionId: "version-1" },
+        cloneAction: "clone-creative-context-design",
+        parts: [
+          {
+            externalId: "figma-file:child-1",
+            itemId: "item-child-1",
+            itemVersionId: "version-child-1",
+          },
+        ],
+      },
+      instruction: expect.stringContaining("exact clone action"),
+    });
+    expect(result.version.content).toContain(
+      "Oversized native code is omitted",
+    );
+    expect(JSON.stringify(result)).not.toContain("x".repeat(1_000));
     expect(mocks.getCreativeContextItemByExternalId).not.toHaveBeenCalled();
   });
+
+  it("returns an explicit exact-clone contract instead of oversized flat HTML", async () => {
+    const context = await mocks.getCreativeContextItem();
+    const html = `<div class="fmd-slide google-slides-native" data-source-slide-id="slide-1" style="position:relative;width:960px;height:540px"><p>${"x".repeat(128 * 1024)}</p></div>`;
+    mocks.getCreativeContextItem.mockResolvedValue({
+      ...context,
+      item: {
+        ...context.item,
+        mimeType: "text/html",
+        provenance: {
+          compiler: "@agent-native/creative-context:google-slides-native",
+        },
+      },
+      version: {
+        ...context.version,
+        mimeType: "text/html",
+        content: html,
+        metadata: {
+          nativeArtifact: {
+            schemaVersion: 1,
+            app: "slides",
+            format: "slides-html",
+            rootExternalId: "deck-1:slide-1",
+            fidelityReport: {
+              exact: { count: 1 },
+              approximated: { count: 0, reasons: [] },
+              imageFallback: { count: 0, reasons: [] },
+            },
+          },
+        },
+      },
+      edges: [],
+    });
+
+    const result = (await action.run({
+      itemId: "item-1",
+      itemVersionId: "version-1",
+    })) as any;
+
+    expect(result.version.nativeCode).toMatchObject({
+      dataRole: "untrusted-reference",
+      format: "slides-html",
+      content: null,
+      oversized: true,
+      byteLength: Buffer.byteLength(html, "utf8"),
+      maxInlineBytes: 128 * 1024,
+      retrieval: {
+        mode: "exact-clone-only",
+        root: { itemId: "item-1", itemVersionId: "version-1" },
+        cloneAction: "clone-context-slide",
+        parts: [],
+      },
+      instruction: expect.stringContaining("never concatenate"),
+    });
+    expect(result.version.nativeCode.content).toBeNull();
+    expect(result.version.content).toContain(
+      "Oversized native code is omitted",
+    );
+    expect(JSON.stringify(result)).not.toContain("x".repeat(1_000));
+  });
 });

package/src/actions/get-creative-context.ts

@@ -5,7 +5,10 @@ import {
   reassembleNativeCreativeArtifact,
   validateCompiledNativeHtml,
 } from "../native-artifact-reassembly.js";
-import { nativeCreativeArtifactFromMetadata } from "../native-artifact.js";
+import {
+  nativeCreativeArtifactFromMetadata,
+  type NativeCreativeArtifact,
+} from "../native-artifact.js";
 import {
   sanitizePublicString,
   serializePublicContextDetail,
@@ -21,7 +24,7 @@ import {
   getCreativeContextItemByExternalId,
 } from "../store/index.js";
 
-const MAX_STORED_NATIVE_CODE_BYTES = 128 * 1024;
+const MAX_PUBLIC_NATIVE_CODE_BYTES = 128 * 1024;
 
 export default defineAction({
   description:
@@ -44,17 +47,11 @@ export default defineAction({
       context.version.metadata,
     );
     const nativeCode = nativeArtifact
-      ? nativeArtifact.manifest
-        ? boundedStoredNativeCode(context.version.content, nativeArtifact)
-        : ((
-            await reassembleNativeCreativeArtifact({
-              root: context,
-              app: nativeArtifact.app,
-              format: nativeArtifact.format,
-              resolveChild: getCreativeContextItemByExternalId,
-            }).catch(() => null)
-          )?.html ?? null)
+      ? await publicNativeCode(context, nativeArtifact)
       : null;
+    const nativeCodeOversized = Boolean(
+      nativeCode && "oversized" in nativeCode && nativeCode.oversized,
+    );
     return {
       ...publicContext,
       pendingJobId: await ensureContextItemHydration(context.item.id),
@@ -75,16 +72,11 @@ export default defineAction({
           sanitizePublicString(context.version.title),
         ),
         content: delimitUntrustedReference(
-          sanitizePublicString(context.version.content),
+          nativeCodeOversized
+            ? "Oversized native code is omitted from this public result. Use version.nativeCode.retrieval."
+            : sanitizePublicString(context.version.content),
         ),
-        nativeCode:
-          nativeArtifact && nativeCode
-            ? {
-                dataRole: UNTRUSTED_REFERENCE_ROLE,
-                format: nativeArtifact.format,
-                content: nativeCode,
-              }
-            : null,
+        nativeCode: nativeArtifact && nativeCode ? nativeCode : null,
         summary: context.version.summary
           ? delimitUntrustedReference(
               sanitizePublicString(context.version.summary),
@@ -132,17 +124,74 @@ export default defineAction({
   },
 });
 
-function boundedStoredNativeCode(
-  content: string,
-  artifact: Parameters<typeof validateCompiledNativeHtml>[1],
-): string | null {
-  if (Buffer.byteLength(content, "utf8") > MAX_STORED_NATIVE_CODE_BYTES) {
-    return null;
-  }
+async function publicNativeCode(
+  context: NonNullable<Awaited<ReturnType<typeof getCreativeContextItem>>>,
+  artifact: NativeCreativeArtifact,
+) {
   try {
+    const content = artifact.manifest
+      ? context.version.content
+      : (
+          await reassembleNativeCreativeArtifact({
+            root: context,
+            app: artifact.app,
+            format: artifact.format,
+            resolveChild: getCreativeContextItemByExternalId,
+          })
+        ).html;
     validateCompiledNativeHtml(content, artifact);
-    return content;
+    const byteLength = Buffer.byteLength(content, "utf8");
+    if (byteLength <= MAX_PUBLIC_NATIVE_CODE_BYTES) {
+      return {
+        dataRole: UNTRUSTED_REFERENCE_ROLE,
+        format: artifact.format,
+        content,
+        ...(artifact.manifest
+          ? { retrieval: nativeCodeRetrieval(context, artifact) }
+          : {}),
+      };
+    }
+    return {
+      dataRole: UNTRUSTED_REFERENCE_ROLE,
+      format: artifact.format,
+      content: null,
+      oversized: true,
+      byteLength,
+      maxInlineBytes: MAX_PUBLIC_NATIVE_CODE_BYTES,
+      retrieval: nativeCodeRetrieval(context, artifact),
+      instruction:
+        "Use the exact clone action for the complete artifact. For a manifest artifact, inspect individually pinned parts with get-context-item; never concatenate a truncated HTML fragment.",
+    };
   } catch {
     return null;
   }
 }
+
+function nativeCodeRetrieval(
+  context: NonNullable<Awaited<ReturnType<typeof getCreativeContextItem>>>,
+  artifact: NativeCreativeArtifact,
+) {
+  return {
+    mode: artifact.manifest ? "manifest-parts" : "exact-clone-only",
+    root: {
+      itemId: context.item.id,
+      itemVersionId: context.version.id,
+    },
+    cloneAction:
+      artifact.app === "slides"
+        ? "clone-context-slide"
+        : "clone-creative-context-design",
+    parts: (artifact.manifest?.children ?? []).map((child) => {
+      const edge = context.edges.find(
+        (candidate) =>
+          candidate.relation === "contains-native-child" &&
+          candidate.toExternalId === child.externalId,
+      );
+      return {
+        externalId: sanitizePublicString(child.externalId),
+        itemId: edge?.toItemId ?? null,
+        itemVersionId: edge?.toItemVersionId ?? null,
+      };
+    }),
+  };
+}

package/src/actions/get-google-picker-session.spec.ts

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const resolveProviderApiOAuthAccessToken = vi.fn();
+const resolveSecret = vi.fn();
+
+vi.mock("@agent-native/core/provider-api", () => ({
+  resolveProviderApiOAuthAccessToken,
+}));
+vi.mock("@agent-native/core/server", () => ({ resolveSecret }));
+vi.mock("../server/context.js", () => ({
+  getCreativeContext: () => ({ connectorContext: { appId: "slides" } }),
+}));
+
+const { default: action } = await import("./get-google-picker-session.js");
+
+describe("get-google-picker-session", () => {
+  beforeEach(() => {
+    resolveProviderApiOAuthAccessToken.mockReset();
+    resolveSecret.mockReset();
+    resolveProviderApiOAuthAccessToken.mockResolvedValue({
+      accessToken: "short-lived-access-token",
+      accountLabel: "Work Google",
+    });
+    resolveSecret.mockImplementation(async (key: string) =>
+      key === "GOOGLE_PICKER_API_KEY"
+        ? "browser-restricted-key"
+        : key === "GOOGLE_PICKER_APP_ID"
+          ? "123456789"
+          : null,
+    );
+  });
+
+  it("is UI-only and returns a Picker session for an app-scoped connection", async () => {
+    expect(action.agentTool).toBe(false);
+    expect(action.toolCallable).toBe(false);
+    expect(action.requiresAuth).toBe(true);
+
+    await expect(
+      action.run({ connectionId: "drive-connection" }),
+    ).resolves.toEqual({
+      accessToken: "short-lived-access-token",
+      accountLabel: "Work Google",
+      apiKey: "browser-restricted-key",
+      appId: "123456789",
+    });
+    expect(resolveProviderApiOAuthAccessToken).toHaveBeenCalledWith(
+      { provider: "google_drive", connectionId: "drive-connection" },
+      expect.objectContaining({
+        appId: "slides",
+        providerIds: ["google_drive"],
+      }),
+    );
+  });
+
+  it("fails closed when the browser-restricted Picker config is absent", async () => {
+    resolveSecret.mockResolvedValue(null);
+
+    await expect(
+      action.run({ connectionId: "drive-connection" }),
+    ).rejects.toThrow(/Google Picker is not configured/);
+  });
+});

package/src/actions/get-google-picker-session.ts

@@ -0,0 +1,45 @@
+import { defineAction } from "@agent-native/core/action";
+import { resolveProviderApiOAuthAccessToken } from "@agent-native/core/provider-api";
+import { resolveSecret } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { getCreativeContext } from "../server/context.js";
+
+export default defineAction({
+  description:
+    "Return a short-lived Google Picker session for the signed-in Library UI.",
+  schema: z.object({
+    connectionId: z.string().min(1),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  requiresAuth: true,
+  agentTool: false,
+  toolCallable: false,
+  run: async ({ connectionId }) => {
+    const { connectorContext } = getCreativeContext();
+    const [oauth, apiKey, appId] = await Promise.all([
+      resolveProviderApiOAuthAccessToken(
+        { provider: "google_drive", connectionId },
+        {
+          appId: connectorContext.appId,
+          providerIds: ["google_drive"],
+          localCredentialSource: "creative_context_picker",
+        },
+      ),
+      resolveSecret("GOOGLE_PICKER_API_KEY"),
+      resolveSecret("GOOGLE_PICKER_APP_ID"),
+    ]);
+    if (!apiKey || !appId) {
+      throw new Error(
+        "Google Picker is not configured. Set GOOGLE_PICKER_API_KEY and GOOGLE_PICKER_APP_ID.",
+      );
+    }
+    return {
+      accessToken: oauth.accessToken,
+      accountLabel: oauth.accountLabel,
+      apiKey,
+      appId,
+    };
+  },
+});

package/src/actions/index.ts

@@ -7,6 +7,7 @@ import getBrandProfile from "./get-brand-profile.js";
 import getContextImportStatus from "./get-context-import-status.js";
 import getContextItem from "./get-context-item.js";
 import getContextPack from "./get-context-pack.js";
+import getGooglePickerSession from "./get-google-picker-session.js";
 import inferBrandDna from "./infer-brand-dna.js";
 import listCanonicalLogoCandidates from "./list-canonical-logo-candidates.js";
 import listContextConnections from "./list-context-connections.js";
@@ -39,6 +40,7 @@ export const creativeContextActions: Record<string, ActionEntry> = {
   "get-context-import-status": getContextImportStatus,
   "get-context-item": getContextItem,
   "get-context-pack": getContextPack,
+  "get-google-picker-session": getGooglePickerSession,
   "infer-brand-dna": inferBrandDna,
   "list-canonical-logo-candidates": listCanonicalLogoCandidates,
   "list-context-packs": listContextPacks,

package/src/actions/job-public-serialization.spec.ts

@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  continueJob: vi.fn(),
+  createJob: vi.fn(),
+  getContextSource: vi.fn(),
+  dispatchCreativeContextImportJob: vi.fn(async () => undefined),
+}));
+
+vi.mock("../store/index.js", () => ({
+  continueJob: mocks.continueJob,
+  createJob: mocks.createJob,
+  getContextSource: mocks.getContextSource,
+}));
+
+vi.mock("../jobs/index.js", () => ({
+  dispatchCreativeContextImportJob: mocks.dispatchCreativeContextImportJob,
+}));
+
+vi.mock("../server/context.js", () => ({
+  getCreativeContext: () => ({ connectorContext: { appId: "slides" } }),
+}));
+
+import continueImport from "./continue-context-import.js";
+import startEnrichment from "./start-context-enrichment.js";
+import startImport from "./start-context-import.js";
+
+const privateJob = {
+  id: "job-1",
+  ownerEmail: "owner@example.test",
+  orgId: "org-secret",
+  sourceId: "source-1",
+  kind: "import",
+  status: "running",
+  mode: "incremental",
+  progressCurrent: 2,
+  progressTotal: 4,
+  attempts: 1,
+  leaseOwner: "worker-private",
+  leaseToken: "lease-private",
+  leaseExpiresAt: "2026-07-16T02:00:00.000Z",
+  nextResumeAt: null,
+  budget: { token: "budget-private" },
+  checkpoint: {
+    blobRef: "creative-context-blob:v1:checkpoint-private",
+    warning:
+      "Fetched https://provider.example/private?X-Amz-Signature=checkpoint-private",
+  },
+  request: {
+    providerUrl:
+      "https://provider.example/private?X-Amz-Signature=request-private",
+  },
+  result: {
+    processed: 2,
+    warning:
+      "Failed https://provider.example/private?X-Amz-Signature=result-private",
+  },
+  error:
+    "Provider https://provider.example/private?X-Amz-Signature=error-private failed",
+  createdAt: "2026-07-16T00:00:00.000Z",
+  startedAt: "2026-07-16T00:01:00.000Z",
+  completedAt: null,
+};
+
+function expectPublicJob(result: unknown) {
+  expect(result).toMatchObject({
+    job: {
+      id: "job-1",
+      sourceId: "source-1",
+      result: { processed: 2, warning: "Failed [redacted]" },
+      error: "Provider [redacted] failed",
+    },
+  });
+  const serialized = JSON.stringify(result);
+  expect(serialized).not.toMatch(
+    /owner@example|org-secret|worker-private|lease-private|checkpoint-private|request-private|result-private|error-private|creative-context-blob|X-Amz-Signature/i,
+  );
+  expect(serialized).not.toMatch(
+    /ownerEmail|orgId|leaseOwner|leaseToken|leaseExpiresAt|checkpoint|request|budget/i,
+  );
+}
+
+describe("creative context job action serialization", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.continueJob.mockResolvedValue(privateJob);
+    mocks.createJob.mockResolvedValue(privateJob);
+    mocks.getContextSource.mockResolvedValue({
+      id: "source-1",
+      ownerEmail: "owner@example.test",
+    });
+  });
+
+  it("redacts continuation job capabilities and provider URLs", async () => {
+    expectPublicJob(await continueImport.run({ jobId: "job-1" }));
+  });
+
+  it("redacts newly queued import job capabilities and provider URLs", async () => {
+    expectPublicJob(
+      await startImport.run({
+        sourceId: "source-1",
+        mode: "incremental",
+      }),
+    );
+    expect(mocks.dispatchCreativeContextImportJob).toHaveBeenCalledWith({
+      jobId: "job-1",
+      ownerEmail: "owner@example.test",
+      orgId: "org-secret",
+      appId: "slides",
+    });
+  });
+
+  it("redacts newly queued enrichment job capabilities and provider URLs", async () => {
+    expectPublicJob(
+      await startEnrichment.run({
+        sourceId: "source-1",
+        operation: "enrich-media",
+        eagerLimit: 25,
+      }),
+    );
+  });
+});

package/src/actions/start-context-enrichment.ts

@@ -1,6 +1,7 @@
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
+import { serializePublicJob } from "../server/public-serialization.js";
 import { createJob } from "../store/index.js";
 
 const schema = z.object({
@@ -24,8 +25,8 @@ export default defineAction({
   schema,
   needsApproval: true,
   publicAgent: { expose: true, readOnly: false, requiresAuth: true },
-  run: async (args) => ({
-    job: await createJob({
+  run: async (args) => {
+    const job = await createJob({
       sourceId: args.sourceId,
       kind:
         args.operation === "enrich-media"
@@ -45,6 +46,7 @@ export default defineAction({
         eagerLimit: args.eagerLimit,
         remainingMode: "pending-on-demand",
       },
-    }),
-  }),
+    });
+    return { job: serializePublicJob(job) };
+  },
 });

package/src/actions/start-context-import.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { dispatchCreativeContextImportJob } from "../jobs/index.js";
 import { getCreativeContext } from "../server/context.js";
+import { serializePublicJob } from "../server/public-serialization.js";
 import { createJob } from "../store/index.js";
 import { getContextSource } from "../store/index.js";
 
@@ -32,6 +33,6 @@ export default defineAction({
       orgId: job.orgId,
       appId: getCreativeContext().connectorContext.appId,
     });
-    return { job };
+    return { job: serializePublicJob(job) };
   },
 });