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

package/src/server/brand-context.ts

@@ -0,0 +1,160 @@
+const HEX_COLOR = /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/i;
+const SAFE_TOKEN = /^[\p{L}\p{N}][\p{L}\p{N} ._+\-/]{0,79}$/u;
+const VOICE_DESCRIPTORS = new Set([
+  "bold",
+  "casual",
+  "concise",
+  "direct",
+  "formal",
+  "optimistic",
+  "playful",
+  "restrained",
+  "technical",
+  "warm",
+]);
+
+export interface PublishedBrandContextInput {
+  profileId: string;
+  dnaVersionId: string;
+  colors?: unknown;
+  fonts?: unknown;
+  numericScales?: unknown;
+  voiceDescriptors?: unknown;
+  layoutPatterns?: unknown;
+  logos?: unknown;
+  terminology?: unknown;
+  exclusions?: unknown;
+  inventory?: unknown;
+}
+
+function safeToken(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim().replace(/\s+/g, " ");
+  return SAFE_TOKEN.test(normalized) ? normalized : null;
+}
+
+function stringArray(value: unknown, limit = 30): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map(safeToken)
+    .filter((entry): entry is string => Boolean(entry))
+    .slice(0, limit);
+}
+
+function structuredColors(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        const value = entry.toUpperCase();
+        return HEX_COLOR.test(value) ? { value } : null;
+      }
+      if (!entry || typeof entry !== "object") return null;
+      const record = entry as Record<string, unknown>;
+      const value =
+        typeof record.value === "string" ? record.value.toUpperCase() : "";
+      if (!HEX_COLOR.test(value)) return null;
+      return {
+        ...(safeToken(record.name) ? { name: safeToken(record.name) } : {}),
+        ...(safeToken(record.role) ? { role: safeToken(record.role) } : {}),
+        value,
+      };
+    })
+    .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
+    .slice(0, 40);
+}
+
+function structuredFonts(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        const family = safeToken(entry);
+        return family ? { family } : null;
+      }
+      if (!entry || typeof entry !== "object") return null;
+      const record = entry as Record<string, unknown>;
+      const family = safeToken(record.family);
+      if (!family) return null;
+      const weight = Number(record.weight);
+      return {
+        family,
+        ...(safeToken(record.role) ? { role: safeToken(record.role) } : {}),
+        ...(Number.isInteger(weight) && weight >= 100 && weight <= 1000
+          ? { weight }
+          : {}),
+      };
+    })
+    .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
+    .slice(0, 20);
+}
+
+function numericScales(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const result: Record<string, number[]> = {};
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    const name = safeToken(key);
+    if (!name || !Array.isArray(raw)) continue;
+    const values = raw
+      .map(Number)
+      .filter((entry) => Number.isFinite(entry) && entry >= 0 && entry <= 10000)
+      .slice(0, 20);
+    if (values.length) result[name] = values;
+  }
+  return result;
+}
+
+function structuredTerminology(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) => {
+      if (!entry || typeof entry !== "object") return null;
+      const record = entry as Record<string, unknown>;
+      const use = safeToken(record.use);
+      if (!use) return null;
+      const avoid = safeToken(record.avoid);
+      return { use, ...(avoid ? { avoid } : {}) };
+    })
+    .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
+    .slice(0, 40);
+}
+
+function structuredInventory(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const result: Record<string, number> = {};
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    const name = safeToken(key);
+    const count = Number(raw);
+    if (name && Number.isInteger(count) && count >= 0 && count <= 10_000_000) {
+      result[name] = count;
+    }
+  }
+  return result;
+}
+
+export function compilePublishedBrandContext(
+  input: PublishedBrandContextInput,
+): string {
+  const voiceDescriptors = stringArray(input.voiceDescriptors).filter((value) =>
+    VOICE_DESCRIPTORS.has(value.toLowerCase()),
+  );
+  const data = {
+    profileId: safeToken(input.profileId) ?? "published-profile",
+    dnaVersionId: safeToken(input.dnaVersionId) ?? "published-version",
+    colors: structuredColors(input.colors),
+    fonts: structuredFonts(input.fonts),
+    numericScales: numericScales(input.numericScales),
+    voiceDescriptors,
+    layoutPatterns: stringArray(input.layoutPatterns),
+    logos: stringArray(input.logos),
+    terminology: structuredTerminology(input.terminology),
+    exclusions: stringArray(input.exclusions),
+    inventory: structuredInventory(input.inventory),
+  };
+  return [
+    `<brand-context profile-id=${JSON.stringify(data.profileId)} dna-version-id=${JSON.stringify(data.dnaVersionId)}>`,
+    JSON.stringify(data),
+    "Use approved company examples before generating new creative work. Search creative context for 2-5 task-relevant examples, keep style/layout examples separate from factual evidence, and preserve the resulting context pack as provenance.",
+    "</brand-context>",
+  ].join("\n");
+}

package/src/server/context.ts

@@ -0,0 +1,162 @@
+import { createGetDb, getDbExec, isPostgres } from "@agent-native/core/db";
+
+import {
+  createDefaultContextConnectorExecutionContext,
+  createDefaultContextImportConnectorRegistry,
+} from "../connectors/index.js";
+import type { ContextImportConnectorRegistry } from "../connectors/registry.js";
+import type { ContextConnectorExecutionContext } from "../connectors/types.js";
+import * as defaultSchema from "../schema/index.js";
+import type { PgVectorAdapter } from "../types.js";
+import type {
+  CreativeContextElementProvenance,
+  ContextMedia,
+} from "../types.js";
+import {
+  deletePgVectors,
+  queryPgVectorIndex,
+  upsertPgVector,
+} from "../vector/pgvector.js";
+
+export type CreativeContextSchema = typeof defaultSchema;
+export type CreativeContextGetDb = () => any;
+
+export interface CreativeContextServerContext {
+  getDb: CreativeContextGetDb;
+  schema: CreativeContextSchema;
+  vectorAdapter?: PgVectorAdapter;
+  connectors: ContextImportConnectorRegistry;
+  connectorContext: ContextConnectorExecutionContext;
+  projections?: CreativeContextProjectionAdapters;
+  enrichment?: CreativeContextEnrichmentAdapters;
+}
+
+export interface CreativeContextProjectionAdapters {
+  canonicalLogo?: {
+    apply(input: {
+      profileId: string | null;
+      itemId: string;
+      itemVersionId: string;
+      payload: Record<string, unknown>;
+    }): Promise<void>;
+  };
+  layoutTemplate?: {
+    promote(input: {
+      suggestionId: string;
+      itemId: string;
+      itemVersionId: string;
+      projectionItemId: string;
+      htmlSnapshot: string | null;
+    }): Promise<void>;
+    demote(input: {
+      suggestionId: string;
+      projectionItemId: string | null;
+    }): Promise<void>;
+  };
+  generation?: {
+    record(input: {
+      appId: string;
+      artifactType: string;
+      artifactId: string;
+      contextPackId: string | null;
+      elementProvenance: readonly CreativeContextElementProvenance[];
+    }): Promise<void>;
+  };
+  media?: {
+    project(input: {
+      sourceId: string;
+      itemId: string;
+      itemVersionId: string;
+      media: ContextMedia;
+      sourceType: "brand-import";
+      dedupeKey: string;
+    }): Promise<void>;
+  };
+}
+
+export interface CreativeContextEnrichmentAdapters {
+  captionImage?(input: {
+    data: Uint8Array;
+    mimeType: string;
+    itemId: string;
+    itemVersionId: string;
+    mediaId: string;
+  }): Promise<string | null>;
+  ocrImage?(input: {
+    data: Uint8Array;
+    mimeType: string;
+    itemId: string;
+    itemVersionId: string;
+    mediaId: string;
+  }): Promise<string | null>;
+}
+
+const defaultGetDb = createGetDb(defaultSchema);
+const CONTEXT_KEY = Symbol.for("@agent-native/creative-context.context");
+
+type GlobalContext = {
+  [CONTEXT_KEY]?: CreativeContextServerContext;
+};
+
+function defaultVectorAdapter(): PgVectorAdapter | undefined {
+  if (!isPostgres()) return undefined;
+  return {
+    async upsert(input) {
+      const vectorKey = input.embeddingId;
+      await upsertPgVector(getDbExec(), {
+        vectorKey,
+        embeddingSetId: input.embeddingSetId,
+        dimensions: input.vector.length,
+        vector: input.vector,
+      });
+      return { vectorKey };
+    },
+    async search(input) {
+      const hits = await queryPgVectorIndex(getDbExec(), {
+        embeddingSetId: input.embeddingSetId,
+        dimensions: input.vector.length,
+        vector: input.vector,
+        limit: input.limit,
+        allowedVectorKeys: input.allowedVectorKeys,
+      });
+      return hits.map((hit) => ({
+        embeddingId: hit.vectorKey,
+        score: hit.score,
+      }));
+    },
+    async delete(input) {
+      await deletePgVectors(getDbExec(), {
+        dimensions: input.dimensions,
+        vectorKeys: [input.vectorKey],
+      });
+    },
+  };
+}
+
+export function configureCreativeContext(
+  context: Partial<CreativeContextServerContext> = {},
+): CreativeContextServerContext {
+  const appId = context.connectorContext?.appId ?? "creative-context";
+  const configured: CreativeContextServerContext = {
+    getDb: context.getDb ?? defaultGetDb,
+    schema: context.schema ?? defaultSchema,
+    vectorAdapter: context.vectorAdapter ?? defaultVectorAdapter(),
+    connectors:
+      context.connectors ?? createDefaultContextImportConnectorRegistry(),
+    connectorContext: {
+      ...createDefaultContextConnectorExecutionContext({ appId }),
+      ...context.connectorContext,
+      appId,
+    },
+    projections: context.projections,
+    enrichment: context.enrichment,
+  };
+  (globalThis as GlobalContext)[CONTEXT_KEY] = configured;
+  return configured;
+}
+
+export function getCreativeContext(): CreativeContextServerContext {
+  return (
+    (globalThis as GlobalContext)[CONTEXT_KEY] ?? configureCreativeContext()
+  );
+}

package/src/server/enrichment.spec.ts

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  appendVersion: vi.fn(),
+  availableFamilies: vi.fn(),
+  getActiveEmbeddingSet: vi.fn(),
+  getCreativeContext: vi.fn(),
+  readMedia: vi.fn(),
+  fingerprintMedia: vi.fn(),
+  extractDominantColors: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/ingestion", () => ({
+  fingerprintMedia: mocks.fingerprintMedia,
+  extractDominantColors: mocks.extractDominantColors,
+}));
+
+vi.mock("../embeddings/providers.js", () => ({
+  availableEmbeddingFamilies: mocks.availableFamilies,
+}));
+
+vi.mock("../store/index.js", () => ({
+  appendMediaEnrichmentVersion: mocks.appendVersion,
+  getActiveEmbeddingSet: mocks.getActiveEmbeddingSet,
+  getCreativeContextItem: vi.fn(),
+  recordEmbeddingMetadata: vi.fn(),
+}));
+
+vi.mock("./context.js", () => ({
+  getCreativeContext: mocks.getCreativeContext,
+}));
+
+vi.mock("./media.js", () => ({
+  readCreativeContextMedia: mocks.readMedia,
+}));
+
+import { enrichCreativeContextMedia } from "./enrichment.js";
+
+describe("creative context media enrichment", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.readMedia.mockResolvedValue({
+      data: new Uint8Array([1, 2, 3]),
+      mimeType: "image/png",
+      itemId: "item-1",
+      itemVersionId: "version-1",
+      mediaId: "media-1",
+      media: {
+        caption: null,
+        ocrText: null,
+      },
+    });
+    mocks.fingerprintMedia.mockReturnValue({ sha256: "image-hash" });
+    mocks.extractDominantColors.mockResolvedValue(["#663399"]);
+    mocks.availableFamilies.mockResolvedValue([]);
+    mocks.getActiveEmbeddingSet.mockResolvedValue(null);
+    mocks.appendVersion.mockResolvedValue({
+      itemId: "item-1",
+      itemVersionId: "version-2",
+      mediaId: "media-2",
+      appended: true,
+    });
+    mocks.getCreativeContext.mockReturnValue({
+      vectorAdapter: null,
+      projections: undefined,
+      enrichment: {
+        captionImage: vi.fn(async () => "A purple dashboard"),
+        ocrImage: vi.fn(async () => "Ship faster"),
+      },
+    });
+  });
+
+  it("writes enrichment as a new immutable version and returns its ids", async () => {
+    await expect(
+      enrichCreativeContextMedia({ mediaId: "media-1" }),
+    ).resolves.toMatchObject({
+      mediaId: "media-2",
+      itemId: "item-1",
+      itemVersionId: "version-2",
+      versionAppended: true,
+      caption: "A purple dashboard",
+      ocrText: "Ship faster",
+      palette: ["#663399"],
+    });
+    expect(mocks.appendVersion).toHaveBeenCalledWith({
+      mediaId: "media-1",
+      palette: ["#663399"],
+      contentHash: "image-hash",
+      caption: "A purple dashboard",
+      captionStatus: "complete",
+      ocrText: "Ship faster",
+    });
+  });
+});

package/src/server/enrichment.ts

@@ -0,0 +1,166 @@
+import { randomUUID } from "node:crypto";
+
+import {
+  extractDominantColors,
+  fingerprintMedia,
+} from "@agent-native/core/ingestion";
+import { eq } from "drizzle-orm";
+
+import { availableEmbeddingFamilies } from "../embeddings/providers.js";
+import {
+  appendMediaEnrichmentVersion,
+  getActiveEmbeddingSet,
+  getCreativeContextItem,
+  recordEmbeddingMetadata,
+} from "../store/index.js";
+import { getCreativeContext } from "./context.js";
+import { readCreativeContextMedia } from "./media.js";
+
+export async function projectCreativeContextMedia(mediaId: string) {
+  const { getDb, schema, projections } = getCreativeContext();
+  if (!projections?.media) return { mediaId, projected: false as const };
+  const rows = await getDb()
+    .select({
+      itemId: schema.contextMedia.itemId,
+      itemVersionId: schema.contextMedia.itemVersionId,
+    })
+    .from(schema.contextMedia)
+    .where(eq(schema.contextMedia.id, mediaId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) throw new Error("Creative context media was not found.");
+  const detail = await getCreativeContextItem(row.itemId, row.itemVersionId);
+  const media = detail?.media.find((entry) => entry.id === mediaId);
+  if (!detail || !media) {
+    throw new Error("Creative context media is not accessible.");
+  }
+  await projections.media.project({
+    sourceId: detail.item.sourceId,
+    itemId: detail.item.id,
+    itemVersionId: detail.version.id,
+    media,
+    sourceType: "brand-import",
+    dedupeKey: `${media.id}:${detail.version.id}`,
+  });
+  return { mediaId, projected: true as const };
+}
+
+export async function enrichCreativeContextMedia(input: {
+  mediaId: string;
+  paletteLimit?: number;
+}) {
+  const loaded = await readCreativeContextMedia({ mediaId: input.mediaId });
+  if (
+    loaded.mimeType !== "image/png" &&
+    loaded.mimeType !== "image/jpeg" &&
+    loaded.mimeType !== "image/webp" &&
+    loaded.mimeType !== "image/gif"
+  ) {
+    throw new Error(
+      "Creative context media enrichment supports PNG, JPEG, WebP, or GIF images.",
+    );
+  }
+  const { vectorAdapter, enrichment } = getCreativeContext();
+  const fingerprint = fingerprintMedia(loaded.data, loaded.mimeType);
+  const palette = await extractDominantColors(
+    loaded.data,
+    input.paletteLimit ?? 6,
+  ).catch(() => []);
+  const [caption, ocrText] = await Promise.all([
+    enrichment?.captionImage?.({
+      data: loaded.data,
+      mimeType: loaded.mimeType,
+      itemId: loaded.itemId,
+      itemVersionId: loaded.itemVersionId,
+      mediaId: input.mediaId,
+    }) ?? Promise.resolve(null),
+    enrichment?.ocrImage?.({
+      data: loaded.data,
+      mimeType: loaded.mimeType,
+      itemId: loaded.itemId,
+      itemVersionId: loaded.itemVersionId,
+      mediaId: input.mediaId,
+    }) ?? Promise.resolve(null),
+  ]);
+  const nextCaption = caption ?? loaded.media?.caption ?? null;
+  const nextCaptionStatus = enrichment?.captionImage
+    ? caption
+      ? ("complete" as const)
+      : ("failed" as const)
+    : ("pending" as const);
+  const nextOcrText = ocrText ?? loaded.media?.ocrText ?? null;
+  const snapshot = await appendMediaEnrichmentVersion({
+    mediaId: input.mediaId,
+    palette,
+    contentHash: fingerprint.sha256,
+    caption: nextCaption,
+    captionStatus: nextCaptionStatus,
+    ocrText: nextOcrText,
+  });
+
+  const families = await availableEmbeddingFamilies();
+  const set = await getActiveEmbeddingSet();
+  const family = set
+    ? (families.find(
+        (candidate) =>
+          candidate.id === set!.family &&
+          candidate.model === set!.model &&
+          candidate.version === set!.version,
+      ) ?? null)
+    : null;
+  let embeddingId: string | null = null;
+  const imageMimeSupported =
+    !family?.supportedImageMimeTypes ||
+    family.supportedImageMimeTypes.includes(loaded.mimeType);
+  if (set && family && vectorAdapter && imageMimeSupported) {
+    const [vector] = await family.embed(
+      [
+        {
+          text: [caption, ocrText].filter(Boolean).join("\n") || undefined,
+          images: [
+            {
+              mimeType: loaded.mimeType,
+              base64: Buffer.from(loaded.data).toString("base64"),
+            },
+          ],
+        },
+      ],
+      "document",
+    );
+    if (vector) {
+      embeddingId = `ccem_${randomUUID()}`;
+      const stored = await vectorAdapter.upsert({
+        embeddingId,
+        embeddingSetId: set.id,
+        vector,
+      });
+      await recordEmbeddingMetadata({
+        embeddingSetId: set.id,
+        itemId: snapshot.itemId,
+        itemVersionId: snapshot.itemVersionId,
+        targetType: "media",
+        targetId: snapshot.mediaId,
+        vectorKey: stored.vectorKey,
+        dimensions: vector.length,
+        checksum: fingerprint.sha256,
+      });
+    }
+  }
+  await projectCreativeContextMedia(snapshot.mediaId);
+  return {
+    mediaId: snapshot.mediaId,
+    itemId: snapshot.itemId,
+    itemVersionId: snapshot.itemVersionId,
+    versionAppended: snapshot.appended,
+    palette,
+    caption: nextCaption,
+    ocrText: nextOcrText,
+    contentHash: fingerprint.sha256,
+    embeddingId,
+    embeddingFamily: family?.id ?? null,
+    embeddingSkippedReason:
+      set && family && !imageMimeSupported
+        ? `Active embedding family ${family.id} does not accept ${loaded.mimeType}.`
+        : null,
+  };
+}

package/src/server/generation-artifact-access.spec.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  assertAccess: vi.fn(),
+  getRequestUserEmail: vi.fn(),
+  getRequestOrgId: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/sharing", () => ({
+  assertAccess: mocks.assertAccess,
+}));
+
+vi.mock("@agent-native/core/server/request-context", () => ({
+  getRequestUserEmail: mocks.getRequestUserEmail,
+  getRequestOrgId: mocks.getRequestOrgId,
+}));
+
+import {
+  assertGenerationArtifactAccessProof,
+  createGenerationArtifactAccessCapability,
+  verifyGenerationArtifactAccessCapability,
+} from "./generation-artifact-access.js";
+
+const originalKey = process.env.CREATIVE_CONTEXT_A2A_KEY;
+const identity = {
+  appId: "slides",
+  artifactType: "deck",
+  artifactId: "deck-1",
+};
+
+describe("generation artifact access capabilities", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env.CREATIVE_CONTEXT_A2A_KEY = "test-capability-signing-key";
+    mocks.getRequestUserEmail.mockReturnValue("alice@example.test");
+    mocks.getRequestOrgId.mockReturnValue("org-1");
+    mocks.assertAccess.mockResolvedValue({ role: "editor" });
+  });
+
+  afterEach(() => {
+    if (originalKey === undefined) delete process.env.CREATIVE_CONTEXT_A2A_KEY;
+    else process.env.CREATIVE_CONTEXT_A2A_KEY = originalKey;
+  });
+
+  it("mints a short-lived capability only after host artifact access succeeds", async () => {
+    const token = await createGenerationArtifactAccessCapability(
+      identity,
+      { resourceType: "deck", resourceId: "deck-1" },
+      "record",
+    );
+    expect(mocks.assertAccess).toHaveBeenCalledWith(
+      "deck",
+      "deck-1",
+      "editor",
+      undefined,
+      { skipResourceBody: true },
+    );
+
+    const proof = await verifyGenerationArtifactAccessCapability(
+      token,
+      identity,
+      "record",
+    );
+    expect(() =>
+      assertGenerationArtifactAccessProof(identity, proof, "editor"),
+    ).not.toThrow();
+  });
+
+  it("binds the capability to caller, artifact identity, and operation", async () => {
+    const token = await createGenerationArtifactAccessCapability(
+      identity,
+      { resourceType: "deck", resourceId: "deck-1" },
+      "read",
+    );
+
+    await expect(
+      verifyGenerationArtifactAccessCapability(
+        token,
+        { ...identity, artifactId: "guessed-deck" },
+        "read",
+      ),
+    ).rejects.toThrow(/invalid generation artifact access capability/i);
+    await expect(
+      verifyGenerationArtifactAccessCapability(token, identity, "record"),
+    ).rejects.toThrow(/invalid generation artifact access capability/i);
+    mocks.getRequestUserEmail.mockReturnValue("mallory@example.test");
+    await expect(
+      verifyGenerationArtifactAccessCapability(token, identity, "read"),
+    ).rejects.toThrow(/invalid generation artifact access capability/i);
+  });
+
+  it("rejects forged capability bytes", async () => {
+    const token = await createGenerationArtifactAccessCapability(
+      identity,
+      { resourceType: "deck", resourceId: "deck-1" },
+      "read",
+    );
+    const forged = `${token.slice(0, -1)}${token.endsWith("a") ? "b" : "a"}`;
+
+    await expect(
+      verifyGenerationArtifactAccessCapability(forged, identity, "read"),
+    ).rejects.toThrow(/invalid generation artifact access capability/i);
+  });
+});