@agent-native/creative-context 0.3.0 → 0.5.0

package/src/server/native-resource-capture.spec.ts

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  parseNativeCreativeArtifactKey,
+  registerNativeResourceCaptureAdapter,
+  resolveNativeCreativeResourceUpdateStatuses,
+  unregisterNativeResourceCaptureAdapter,
+} from "./native-resource-capture.js";
+
+describe("native creative resource update status", () => {
+  afterEach(() => {
+    unregisterNativeResourceCaptureAdapter("slides", "deck");
+  });
+
+  it("parses only complete native artifact identities", () => {
+    expect(parseNativeCreativeArtifactKey("slides:deck:deck-1")).toEqual({
+      appId: "slides",
+      resourceType: "deck",
+      resourceId: "deck-1",
+    });
+    expect(parseNativeCreativeArtifactKey("slides:deck:")).toBeNull();
+    expect(parseNativeCreativeArtifactKey("not-native")).toBeNull();
+  });
+
+  it("checks a resource type in one bounded adapter call", async () => {
+    const listResourceVersions = vi.fn(async (resourceIds: readonly string[]) =>
+      resourceIds.map((resourceId) => ({
+        resourceId,
+        sourceModifiedAt:
+          resourceId === "deck-current"
+            ? "2026-07-17T10:00:00Z"
+            : "2026-07-18T10:00:00Z",
+      })),
+    );
+    registerNativeResourceCaptureAdapter({
+      appId: "slides",
+      resourceType: "deck",
+      listResourceVersions,
+      async capture() {
+        throw new Error("not used");
+      },
+    });
+
+    const statuses = await resolveNativeCreativeResourceUpdateStatuses([
+      {
+        key: "membership-current",
+        appId: "slides",
+        resourceType: "deck",
+        resourceId: "deck-current",
+        publishedSourceModifiedAt: "2026-07-17T10:00:00Z",
+      },
+      {
+        key: "membership-stale",
+        appId: "slides",
+        resourceType: "deck",
+        resourceId: "deck-stale",
+        publishedSourceModifiedAt: "2026-07-17T10:00:00Z",
+      },
+    ]);
+
+    expect(listResourceVersions).toHaveBeenCalledOnce();
+    expect(listResourceVersions).toHaveBeenCalledWith([
+      "deck-current",
+      "deck-stale",
+    ]);
+    expect(statuses.get("membership-current")?.state).toBe("current");
+    expect(statuses.get("membership-stale")).toEqual({
+      key: "membership-stale",
+      state: "update-available",
+      reference: {
+        appId: "slides",
+        resourceType: "deck",
+        resourceId: "deck-stale",
+        expectedUpdatedAt: "2026-07-18T10:00:00Z",
+      },
+    });
+  });
+
+  it("omits inaccessible rows and fails closed when the adapter read fails", async () => {
+    const listResourceVersions = vi
+      .fn()
+      .mockResolvedValueOnce([])
+      .mockRejectedValueOnce(new Error("database unavailable"));
+    registerNativeResourceCaptureAdapter({
+      appId: "slides",
+      resourceType: "deck",
+      listResourceVersions,
+      async capture() {
+        throw new Error("not used");
+      },
+    });
+    const reference = {
+      key: "membership-1",
+      appId: "slides",
+      resourceType: "deck",
+      resourceId: "deck-1",
+      publishedSourceModifiedAt: "2026-07-17T10:00:00Z",
+    };
+
+    expect(
+      await resolveNativeCreativeResourceUpdateStatuses([reference]),
+    ).toEqual(new Map());
+    expect(
+      await resolveNativeCreativeResourceUpdateStatuses([reference]),
+    ).toEqual(new Map());
+  });
+
+  it("rejects unbounded status batches", async () => {
+    await expect(
+      resolveNativeCreativeResourceUpdateStatuses(
+        Array.from({ length: 101 }, (_, index) => ({
+          key: `membership-${index}`,
+          appId: "slides",
+          resourceType: "deck",
+          resourceId: `deck-${index}`,
+          publishedSourceModifiedAt: "2026-07-17T10:00:00Z",
+        })),
+      ),
+    ).rejects.toThrow("limited to 100 resources");
+  });
+});

package/src/server/native-resource-capture.ts

@@ -0,0 +1,198 @@
+import type { NormalizedContextItem } from "../types.js";
+
+/** A native app resource reference supplied by a governed-context submission. */
+export interface NativeCreativeResourceRef {
+  appId: string;
+  resourceType: string;
+  resourceId: string;
+  expectedUpdatedAt?: string;
+}
+
+export interface NativeResourceCaptureAdapter {
+  appId: string;
+  resourceType: string;
+  /**
+   * Reads only the version marker for resources visible to the active caller.
+   * The Library calls this once per resource type with at most 100 ids.
+   */
+  listResourceVersions?(resourceIds: readonly string[]): Promise<
+    Array<{
+      resourceId: string;
+      sourceModifiedAt: string | null;
+    }>
+  >;
+  capture(reference: NativeCreativeResourceRef): Promise<{
+    artifactKey: string;
+    source: {
+      name: string;
+      kind: "native-app";
+      externalRef?: string;
+      upstreamAccess?: "available" | "restricted" | "unknown";
+      containerOwnerVerifiedAt?: string;
+      /** Server-derived from the app's source resource; never client input. */
+      access?: {
+        visibility: "private" | "org" | "public";
+        canManage: boolean;
+      };
+    };
+    items: NormalizedContextItem[];
+    /** Persisted only as internal submission metadata; never action output. */
+    privateMetadata?: Record<string, unknown>;
+  }>;
+}
+
+const REGISTRY_KEY = "__agentNativeCreativeContextNativeCaptureAdapters__";
+type Registry = Map<string, NativeResourceCaptureAdapter>;
+
+export type NativeCreativeResourceUpdateState =
+  | "current"
+  | "update-available"
+  | "unknown";
+
+export interface PublishedNativeCreativeResourceRef {
+  key: string;
+  appId: string;
+  resourceType: string;
+  resourceId: string;
+  publishedSourceModifiedAt?: string | null;
+}
+
+export interface ResolvedNativeCreativeResourceUpdateStatus {
+  key: string;
+  state: NativeCreativeResourceUpdateState;
+  reference: NativeCreativeResourceRef;
+}
+
+const MAX_RESOURCE_VERSION_BATCH = 100;
+
+function registry(): Registry {
+  const globalStore = globalThis as typeof globalThis & {
+    [REGISTRY_KEY]?: Registry;
+  };
+  return (globalStore[REGISTRY_KEY] ??= new Map());
+}
+
+function key(appId: string, resourceType: string): string {
+  return `${appId}:${resourceType}`;
+}
+
+export function registerNativeResourceCaptureAdapter(
+  adapter: NativeResourceCaptureAdapter,
+): () => void {
+  const adapterKey = key(adapter.appId, adapter.resourceType);
+  registry().set(adapterKey, adapter);
+  return () => registry().delete(adapterKey);
+}
+
+export function unregisterNativeResourceCaptureAdapter(
+  appId: string,
+  resourceType: string,
+): void {
+  registry().delete(key(appId, resourceType));
+}
+
+export async function captureNativeCreativeResource(
+  reference: NativeCreativeResourceRef,
+) {
+  const adapter = registry().get(key(reference.appId, reference.resourceType));
+  if (!adapter) {
+    throw new Error(
+      `No native creative-resource capture adapter is registered for ${reference.appId}/${reference.resourceType}`,
+    );
+  }
+  return adapter.capture(reference);
+}
+
+export function parseNativeCreativeArtifactKey(
+  artifactKey: string,
+): Omit<NativeCreativeResourceRef, "expectedUpdatedAt"> | null {
+  const firstSeparator = artifactKey.indexOf(":");
+  const secondSeparator = artifactKey.indexOf(":", firstSeparator + 1);
+  if (firstSeparator <= 0 || secondSeparator <= firstSeparator + 1) return null;
+  const appId = artifactKey.slice(0, firstSeparator);
+  const resourceType = artifactKey.slice(firstSeparator + 1, secondSeparator);
+  const resourceId = artifactKey.slice(secondSeparator + 1);
+  return resourceId ? { appId, resourceType, resourceId } : null;
+}
+
+/**
+ * Resolves update availability in bounded batches. Missing rows are omitted so
+ * an inaccessible native resource is indistinguishable from a deleted one.
+ */
+export async function resolveNativeCreativeResourceUpdateStatuses(
+  references: readonly PublishedNativeCreativeResourceRef[],
+): Promise<Map<string, ResolvedNativeCreativeResourceUpdateStatus>> {
+  if (references.length > MAX_RESOURCE_VERSION_BATCH) {
+    throw new Error(
+      `Native creative-resource status checks are limited to ${MAX_RESOURCE_VERSION_BATCH} resources`,
+    );
+  }
+
+  const groups = new Map<
+    string,
+    {
+      adapter: NativeResourceCaptureAdapter;
+      references: PublishedNativeCreativeResourceRef[];
+    }
+  >();
+  for (const reference of references) {
+    const adapter = registry().get(
+      key(reference.appId, reference.resourceType),
+    );
+    if (!adapter?.listResourceVersions) continue;
+    const adapterKey = key(reference.appId, reference.resourceType);
+    const group = groups.get(adapterKey) ?? { adapter, references: [] };
+    group.references.push(reference);
+    groups.set(adapterKey, group);
+  }
+
+  const resolved = new Map<
+    string,
+    ResolvedNativeCreativeResourceUpdateStatus
+  >();
+  await Promise.all(
+    [...groups.values()].map(
+      async ({ adapter, references: groupReferences }) => {
+        try {
+          const resourceIds = [
+            ...new Set(groupReferences.map((item) => item.resourceId)),
+          ];
+          const versions = await adapter.listResourceVersions!(resourceIds);
+          const versionByResourceId = new Map(
+            versions.map((version) => [
+              version.resourceId,
+              version.sourceModifiedAt,
+            ]),
+          );
+          for (const reference of groupReferences) {
+            if (!versionByResourceId.has(reference.resourceId)) continue;
+            const sourceModifiedAt =
+              versionByResourceId.get(reference.resourceId) ?? null;
+            const state: NativeCreativeResourceUpdateState =
+              !sourceModifiedAt || !reference.publishedSourceModifiedAt
+                ? "unknown"
+                : sourceModifiedAt === reference.publishedSourceModifiedAt
+                  ? "current"
+                  : "update-available";
+            resolved.set(reference.key, {
+              key: reference.key,
+              state,
+              reference: {
+                appId: reference.appId,
+                resourceType: reference.resourceType,
+                resourceId: reference.resourceId,
+                ...(sourceModifiedAt
+                  ? { expectedUpdatedAt: sourceModifiedAt }
+                  : {}),
+              },
+            });
+          }
+        } catch {
+          // Update status is optional metadata; a native app read must not make
+          // the governed Library itself unavailable.
+        }
+      },
+    ),
+  );
+  return resolved;
+}

package/src/server/public-serialization.spec.ts

@@ -32,6 +32,7 @@ describe("creative context public serialization", () => {
         token: "secret-token",
         values: [PRIVATE_HANDLE, "safe"],
       },
+      nativeClone: { handle: "opaque-native-handle" },
     });
     expect(result).toEqual({ safe: "caption", nested: { values: ["safe"] } });
   });

package/src/server/public-serialization.ts

@@ -8,7 +8,7 @@ import type {
 } from "../types.js";
 
 const BLOCKED_METADATA_KEY =
-  /(?:authorization|token|secret|password|cookie|storageKey|blobRef|rawSnapshot|downloadUrl|providerUrl|leaseToken|leaseOwner)/i;
+  /(?:authorization|token|secret|password|cookie|storageKey|blobRef|rawSnapshot|downloadUrl|providerUrl|leaseToken|leaseOwner|handle|cloneReference|privateMetadata|nativeClone)/i;
 const CAPABILITY_VALUE =
   /(?:creative-context-blob:|private-blob:|https?:\/\/)[^\s<>{}\[\]"']*/gi;
 

package/src/server/retrieval.ts

@@ -47,6 +47,7 @@ export interface CreativeContextSearchInput {
   mediaId?: string;
   sourceIds?: string[];
   packId?: string;
+  contextId?: string;
   kinds?: string[];
   tags?: string[];
   colors?: string[];
@@ -184,6 +185,7 @@ export async function performCreativeContextSearch(
   const filters = {
     sourceIds: input.sourceIds,
     packId: input.packId,
+    contextId: input.contextId,
     kinds: input.kinds,
     tags: input.tags,
     colors: input.colors,
@@ -461,6 +463,7 @@ export async function performCreativeContextSearch(
         filters: {
           sourceIds: input.sourceIds,
           packId: input.packId,
+          contextId: input.contextId,
           kinds: input.kinds,
           tags: input.tags,
           colors: input.colors,

package/src/server/safe-native-preview.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+
+import { sanitizeSafeNativePreviewHtml } from "./safe-native-preview.js";
+
+describe("safe native preview sanitizer", () => {
+  it("removes executable markup, framework handlers, and remote subresources", () => {
+    const sanitized = sanitizeSafeNativePreviewHtml(`
+      <script>alert(1)</script>
+      <iframe src="https://private.example"></iframe>
+      <link rel="stylesheet" href="https://private.example/style.css">
+      <style>@import "https://private.example/theme.css"; .hero { background: url(https://private.example/a.png) }</style>
+      <div onclick="steal()" x-data="{}">
+        <img src="https://private.example/image.png" srcset="https://private.example/2x.png 2x">
+      </div>
+    `);
+
+    expect(sanitized).not.toMatch(
+      /script|iframe|private\.example|onclick|srcset|x-data/i,
+    );
+  });
+
+  it("keeps inert inline image data for self-contained snapshots", () => {
+    const sanitized = sanitizeSafeNativePreviewHtml(
+      '<img src="data:image/png;base64,AAAA"><a href="#detail">Detail</a>',
+    );
+    expect(sanitized).toContain("data:image/png;base64,AAAA");
+    expect(sanitized).toContain('href="#detail"');
+  });
+});

package/src/server/safe-native-preview.ts

@@ -0,0 +1,200 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+
+const MAX_PREVIEW_HTML_BYTES = 512 * 1024;
+const MAX_PREVIEW_COUNT = 12;
+const MAX_PREVIEW_DIMENSION = 1_600;
+const MAX_PREVIEW_PNG_BYTES = 4 * 1024 * 1024;
+
+export interface SafeNativeHtmlPreviewInput {
+  id: string;
+  html: string;
+  width: number;
+  height: number;
+}
+
+export interface SafeNativeHtmlPreviewResult {
+  id: string;
+  data: Uint8Array;
+  width: number;
+  height: number;
+}
+
+type PlaywrightModule = {
+  chromium: import("playwright").BrowserType;
+};
+
+const SYSTEM_CHROME_EXECUTABLES = [
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/google-chrome",
+  "/usr/bin/chromium-browser",
+  "/usr/bin/chromium",
+];
+
+function safeDimension(value: number) {
+  return Math.max(200, Math.min(MAX_PREVIEW_DIMENSION, Math.round(value)));
+}
+
+export function sanitizeSafeNativePreviewHtml(html: string): string {
+  return html
+    .replace(
+      /<(script|noscript|iframe|object|embed|form|meta|base|link)\b[\s\S]*?<\/\1>/gi,
+      "",
+    )
+    .replace(
+      /<(script|noscript|iframe|object|embed|form|meta|base|link)\b[^>]*\/?>/gi,
+      "",
+    )
+    .replace(/\s+on[a-z][\w:-]*\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "")
+    .replace(
+      /\s+(?:x-[\w:-]+|@[\w:-]+|:[\w:-]+)\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi,
+      "",
+    )
+    .replace(/\s+(?:srcdoc|srcset)\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "")
+    .replace(
+      /\s+(href|src|poster|action)\s*=\s*(["'])(?!\s*(?:data:image\/(?:png|jpe?g|gif|webp|svg\+xml);|#))[^"']*\2/gi,
+      "",
+    )
+    .replace(
+      /\s+(?:href|src|poster|action)\s*=\s*(?!["'])(?!data:image\/(?:png|jpe?g|gif|webp|svg\+xml);|#)[^\s>]+/gi,
+      "",
+    )
+    .replace(/@import\s+(?:url\()?\s*["']?[^;"')]+["']?\s*\)?\s*;?/gi, "")
+    .replace(
+      /url\(\s*(["']?)(?!data:image\/(?:png|jpe?g|gif|webp|svg\+xml);)[^)]+\1\s*\)/gi,
+      "none",
+    );
+}
+
+async function importPlaywright(): Promise<PlaywrightModule> {
+  const specifier = "playwright";
+  return (await import(
+    /* @vite-ignore */ specifier
+  )) as unknown as PlaywrightModule;
+}
+
+function isMissingBrowserError(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /Executable doesn't exist|playwright install|browser.*not found|chromium.*not found/i.test(
+    message,
+  );
+}
+
+async function launchBrowser(chromium: import("playwright").BrowserType) {
+  const launchOptions = {
+    headless: true as const,
+    args: ["--no-sandbox", "--disable-dev-shm-usage"],
+  };
+  try {
+    return await chromium.launch(launchOptions);
+  } catch (error) {
+    if (!isMissingBrowserError(error)) throw error;
+    for (const executablePath of SYSTEM_CHROME_EXECUTABLES) {
+      if (!existsSync(executablePath)) continue;
+      try {
+        return await chromium.launch({ ...launchOptions, executablePath });
+      } catch {
+        continue;
+      }
+    }
+    throw error;
+  }
+}
+
+async function connectHostedBrowser(
+  chromium: import("playwright").BrowserType,
+): Promise<import("playwright").Browser> {
+  const server = (await import("@agent-native/core/server")) as unknown as {
+    requestBuilderBrowserConnection?: (input: {
+      sessionId: string;
+    }) => Promise<Record<string, unknown>>;
+  };
+  if (!server.requestBuilderBrowserConnection) {
+    throw new Error("Builder Browser is unavailable.");
+  }
+  const connection = await server.requestBuilderBrowserConnection({
+    sessionId: `creative-context-preview-${randomUUID()}`,
+  });
+  const wsUrl = typeof connection.wsUrl === "string" ? connection.wsUrl : "";
+  if (!wsUrl) throw new Error("Builder Browser did not return a connection.");
+  return chromium.connectOverCDP(wsUrl);
+}
+
+export async function renderSafeNativeHtmlPreviews(
+  inputs: SafeNativeHtmlPreviewInput[],
+): Promise<SafeNativeHtmlPreviewResult[]> {
+  const bounded = inputs.slice(0, MAX_PREVIEW_COUNT).flatMap((input) => {
+    if (Buffer.byteLength(input.html, "utf8") > MAX_PREVIEW_HTML_BYTES) {
+      return [];
+    }
+    return [
+      {
+        ...input,
+        html: sanitizeSafeNativePreviewHtml(input.html),
+        width: safeDimension(input.width),
+        height: safeDimension(input.height),
+      },
+    ];
+  });
+  if (!bounded.length) return [];
+
+  let browser: import("playwright").Browser | undefined;
+  try {
+    const playwright = await importPlaywright();
+    browser = await connectHostedBrowser(playwright.chromium).catch(() =>
+      launchBrowser(playwright.chromium),
+    );
+  } catch {
+    return [];
+  }
+
+  const results: SafeNativeHtmlPreviewResult[] = [];
+  try {
+    for (const input of bounded) {
+      const context = await browser.newContext({
+        javaScriptEnabled: false,
+        serviceWorkers: "block",
+        viewport: { width: input.width, height: input.height },
+      });
+      try {
+        await context.route("**/*", async (route) => {
+          const protocol = new URL(route.request().url()).protocol;
+          if (
+            protocol === "about:" ||
+            protocol === "data:" ||
+            protocol === "blob:"
+          ) {
+            await route.continue();
+            return;
+          }
+          await route.abort("blockedbyclient");
+        });
+        const page = await context.newPage();
+        await page.setContent(input.html, {
+          waitUntil: "domcontentloaded",
+          timeout: 5_000,
+        });
+        const png = await page.screenshot({
+          type: "png",
+          animations: "disabled",
+          timeout: 5_000,
+        });
+        if (png.byteLength <= MAX_PREVIEW_PNG_BYTES) {
+          results.push({
+            id: input.id,
+            data: new Uint8Array(png),
+            width: input.width,
+            height: input.height,
+          });
+        }
+      } catch {
+        continue;
+      } finally {
+        await context.close().catch(() => {});
+      }
+    }
+  } finally {
+    await browser.close().catch(() => {});
+  }
+  return results;
+}