@agent-native/creative-context 0.0.0-beta-20260820202238

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/prompt-provider.spec.ts

@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  readAppState: vi.fn(),
+  getBrandProfile: vi.fn(),
+  provider: null as null | {
+    load: (context: {
+      owner: string;
+      compact: boolean;
+      orgId: string | null;
+    }) => Promise<unknown> | unknown;
+  },
+}));
+
+vi.mock("@agent-native/core/application-state", () => ({
+  readAppState: mocks.readAppState,
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  registerPromptContextProvider: vi.fn((provider) => {
+    mocks.provider = provider;
+    return () => {
+      mocks.provider = null;
+    };
+  }),
+}));
+
+vi.mock("../store/brand.js", () => ({
+  getBrandProfile: mocks.getBrandProfile,
+}));
+
+import {
+  publishedBrandContextInput,
+  registerCreativeContextPromptProvider,
+} from "./prompt-provider.js";
+
+describe("creative context prompt provider", () => {
+  beforeEach(() => {
+    mocks.readAppState.mockReset();
+    mocks.getBrandProfile.mockReset();
+  });
+
+  it("maps only structured published payload fields into the compiler", () => {
+    expect(
+      publishedBrandContextInput("brand", "dna", {
+        summary: "untrusted free-form summary",
+        visual: {
+          colors: [{ role: "accent", value: "#5B4FE9" }],
+          fonts: [{ family: "Inter" }],
+        },
+        voice: { descriptors: ["direct"] },
+      }),
+    ).toEqual({
+      profileId: "brand",
+      dnaVersionId: "dna",
+      colors: [{ role: "accent", value: "#5B4FE9" }],
+      fonts: [{ family: "Inter" }],
+      numericScales: undefined,
+      voiceDescriptors: ["direct"],
+      layoutPatterns: undefined,
+      logos: undefined,
+      terminology: undefined,
+      exclusions: undefined,
+      inventory: undefined,
+    });
+  });
+
+  it("structurally omits published brand context when context mode is off", async () => {
+    mocks.readAppState.mockResolvedValue({ contextMode: "off" });
+    const unregister = registerCreativeContextPromptProvider();
+
+    await expect(
+      mocks.provider?.load({ owner: "user", compact: false, orgId: null }),
+    ).resolves.toBeNull();
+    expect(mocks.getBrandProfile).not.toHaveBeenCalled();
+    unregister();
+  });
+});

package/src/server/prompt-provider.ts

@@ -0,0 +1,73 @@
+import { readAppState } from "@agent-native/core/application-state";
+import { registerPromptContextProvider } from "@agent-native/core/server";
+
+import { getBrandProfile } from "../store/brand.js";
+import type { BrandDnaPayload } from "../types.js";
+import {
+  compilePublishedBrandContext,
+  type PublishedBrandContextInput,
+} from "./brand-context.js";
+
+const PROVIDER_ID = "creative-context";
+let unregisterProvider: (() => void) | null = null;
+
+function objectValue(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function publishedBrandContextInput(
+  profileId: string,
+  dnaVersionId: string,
+  payload: BrandDnaPayload,
+): PublishedBrandContextInput {
+  const visual = objectValue(payload.visual);
+  const voice = objectValue(payload.voice);
+  return {
+    profileId,
+    dnaVersionId,
+    colors: payload.colors ?? visual.colors,
+    fonts: payload.fonts ?? visual.fonts,
+    numericScales:
+      payload.numericScales ?? visual.numericScales ?? visual.scales,
+    voiceDescriptors:
+      payload.voiceDescriptors ?? voice.descriptors ?? voice.tone,
+    layoutPatterns:
+      payload.layoutPatterns ?? visual.layoutPatterns ?? payload.motifs,
+    logos: payload.logos ?? visual.logos,
+    terminology: payload.terminology,
+    exclusions: payload.exclusions ?? payload.constraints,
+    inventory: payload.inventory,
+  };
+}
+
+export function registerCreativeContextPromptProvider(): () => void {
+  if (unregisterProvider) return unregisterProvider;
+  const unregister = registerPromptContextProvider({
+    id: PROVIDER_ID,
+    async load() {
+      const state = await readAppState("creative-context").catch(() => null);
+      if (state?.contextMode === "off") return null;
+      const { profile, dna } = await getBrandProfile({});
+      if (!profile || !dna || dna.status !== "published") return null;
+      return {
+        label: "Published brand context",
+        content: compilePublishedBrandContext(
+          publishedBrandContextInput(profile.id, dna.id, dna.payload),
+        ),
+        provenance: "runtime-context",
+        governance: profile.visibility === "org" ? "inherited" : "user",
+        sourceRef: {
+          scope: profile.visibility === "org" ? "organization" : "personal",
+          path: "context/brand-context.md",
+        },
+      };
+    },
+  });
+  unregisterProvider = () => {
+    unregister();
+    unregisterProvider = null;
+  };
+  return unregisterProvider;
+}

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

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  sanitizePublicMetadata,
+  serializePublicBrandProfile,
+  serializePublicContextDetail,
+  serializePublicJob,
+  serializePublicReviewItems,
+} from "./public-serialization.js";
+
+const PRIVATE_HANDLE = "creative-context-blob:private-object";
+
+function serialized(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function expectNoCapabilities(value: unknown) {
+  const output = serialized(value);
+  expect(output).not.toContain(PRIVATE_HANDLE);
+  expect(output).not.toMatch(
+    /storageKey|blobRef|rawSnapshotBlobRef|providerUrl|leaseToken|leaseOwner|secret-token/i,
+  );
+}
+
+describe("creative context public serialization", () => {
+  it("recursively removes capability-looking keys and values", () => {
+    const result = sanitizePublicMetadata({
+      safe: "caption",
+      nested: {
+        storageKey: PRIVATE_HANDLE,
+        providerUrl: "https://provider.example/private",
+        token: "secret-token",
+        values: [PRIVATE_HANDLE, "safe"],
+      },
+      nativeClone: { handle: "opaque-native-handle" },
+    });
+    expect(result).toEqual({ safe: "caption", nested: { values: ["safe"] } });
+  });
+
+  it("redacts capability URLs embedded inside warning and error strings", () => {
+    expect(
+      sanitizePublicMetadata(
+        "Fetch failed for https://provider.example/private?token=example: timeout",
+      ),
+    ).toBe("Fetch failed for [redacted] timeout");
+    expect(
+      sanitizePublicMetadata(
+        "Warning: creative-context-blob:v1:opaque-example is unavailable",
+      ),
+    ).toBe("Warning: [redacted] is unavailable");
+  });
+
+  it("replaces context item media handles with an access-scoped id URL", () => {
+    const result = serializePublicContextDetail({
+      item: {
+        id: "item-1",
+        thumbnailBlobRef: PRIVATE_HANDLE,
+        canonicalUrl: "https://provider.example/private?token=example",
+        provenance: {
+          warning:
+            "Source https://provider.example/private?token=example failed",
+          role: "hero",
+        },
+      },
+      version: {
+        id: "version-1",
+        rawSnapshotBlobRef: PRIVATE_HANDLE,
+        metadata: { blobRef: PRIVATE_HANDLE, role: "hero" },
+      },
+      chunks: [{ id: "chunk-1", metadata: { storageKey: PRIVATE_HANDLE } }],
+      media: [
+        {
+          id: "media-1",
+          storageKey: PRIVATE_HANDLE,
+          provenanceUrl: "https://provider.example/private",
+          url: null,
+          metadata: { providerUrl: "https://provider.example/private" },
+        },
+      ],
+      edges: [{ id: "edge-1", metadata: { label: "derived" } }],
+    } as any);
+    expect(result.item.hasThumbnail).toBe(true);
+    expect(result.item).toMatchObject({
+      canonicalUrl: null,
+      provenance: { warning: "Source [redacted] failed", role: "hero" },
+    });
+    expect(result.media[0]?.url).toBe(
+      "/_agent-native/creative-context/media?mediaId=media-1",
+    );
+    expect(result.media[0]?.hasOriginal).toBe(true);
+    expectNoCapabilities(result);
+  });
+
+  it("omits leases, requests, checkpoints, and nested result capabilities", () => {
+    const result = serializePublicJob({
+      id: "job-1",
+      sourceId: "source-1",
+      kind: "import",
+      status: "running",
+      mode: "incremental",
+      progressCurrent: 2,
+      progressTotal: 4,
+      attempts: 1,
+      leaseOwner: "worker-secret",
+      leaseToken: "secret-token",
+      leaseExpiresAt: "tomorrow",
+      nextResumeAt: null,
+      budget: { token: "secret-token" },
+      checkpoint: { blobRef: PRIVATE_HANDLE },
+      request: { providerUrl: "https://provider.example/private" },
+      result: { safe: 2, nested: { storageKey: PRIVATE_HANDLE } },
+      error: null,
+      createdAt: "now",
+      startedAt: "now",
+      completedAt: null,
+    });
+    expect(result).toMatchObject({ id: "job-1", result: { safe: 2 } });
+    expectNoCapabilities(result);
+  });
+
+  it("sanitizes brand payloads and review provenance", () => {
+    const brand = serializePublicBrandProfile({
+      profile: { id: "brand-1" } as any,
+      dna: {
+        id: "dna-1",
+        payload: {
+          summary: "Safe",
+          visual: { layoutPatterns: [{ thumbnailBlobRef: PRIVATE_HANDLE }] },
+        },
+      } as any,
+      versions: [],
+    });
+    const review = serializePublicReviewItems([
+      {
+        id: "item-1",
+        thumbnailBlobRef: PRIVATE_HANDLE,
+        provenance: {
+          providerUrl: "https://provider.example/private",
+          source: "figma",
+        },
+      } as any,
+    ]);
+    expect(review[0]).toMatchObject({
+      id: "item-1",
+      hasThumbnail: true,
+      provenance: { source: "figma" },
+    });
+    expectNoCapabilities({ brand, review });
+  });
+});