@agent-native/creative-context 0.1.0

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

@@ -0,0 +1,148 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  reassembleNativeCreativeArtifact,
+  validateCompiledNativeHtml,
+} from "../native-artifact-reassembly.js";
+import { nativeCreativeArtifactFromMetadata } from "../native-artifact.js";
+import {
+  sanitizePublicString,
+  serializePublicContextDetail,
+} from "../server/public-serialization.js";
+import { ensureContextItemHydration } from "../server/retrieval.js";
+import {
+  delimitUntrustedMetadata,
+  delimitUntrustedReference,
+  UNTRUSTED_REFERENCE_ROLE,
+} from "../server/untrusted-reference.js";
+import {
+  getCreativeContextItem,
+  getCreativeContextItemByExternalId,
+} from "../store/index.js";
+
+const MAX_STORED_NATIVE_CODE_BYTES = 128 * 1024;
+
+export default defineAction({
+  description:
+    "Get one accessible curated creative-context item at a pinned immutable version.",
+  schema: z.object({
+    itemId: z.string().min(1),
+    itemVersionId: z.string().min(1).optional(),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    const context = await getCreativeContextItem(
+      args.itemId,
+      args.itemVersionId,
+    );
+    if (!context) throw new Error("Context item not found or not accessible");
+    const publicContext = serializePublicContextDetail(context);
+    const nativeArtifact = nativeCreativeArtifactFromMetadata(
+      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)
+      : null;
+    return {
+      ...publicContext,
+      pendingJobId: await ensureContextItemHydration(context.item.id),
+      dataRole: UNTRUSTED_REFERENCE_ROLE,
+      item: {
+        ...publicContext.item,
+        dataRole: UNTRUSTED_REFERENCE_ROLE,
+        externalId: sanitizePublicString(context.item.externalId),
+        title: delimitUntrustedReference(
+          sanitizePublicString(context.item.title),
+        ),
+        provenance: delimitUntrustedMetadata(publicContext.item.provenance),
+      },
+      version: {
+        ...publicContext.version,
+        dataRole: UNTRUSTED_REFERENCE_ROLE,
+        title: delimitUntrustedReference(
+          sanitizePublicString(context.version.title),
+        ),
+        content: delimitUntrustedReference(
+          sanitizePublicString(context.version.content),
+        ),
+        nativeCode:
+          nativeArtifact && nativeCode
+            ? {
+                dataRole: UNTRUSTED_REFERENCE_ROLE,
+                format: nativeArtifact.format,
+                content: nativeCode,
+              }
+            : null,
+        summary: context.version.summary
+          ? delimitUntrustedReference(
+              sanitizePublicString(context.version.summary),
+            )
+          : null,
+        sourceVersion: context.version.sourceVersion
+          ? sanitizePublicString(context.version.sourceVersion)
+          : null,
+        parseError: context.version.parseError
+          ? delimitUntrustedReference(
+              sanitizePublicString(context.version.parseError),
+            )
+          : null,
+        metadata: delimitUntrustedMetadata(publicContext.version.metadata),
+      },
+      chunks: publicContext.chunks.map((chunk) => ({
+        ...chunk,
+        dataRole: UNTRUSTED_REFERENCE_ROLE,
+        text: delimitUntrustedReference(sanitizePublicString(chunk.text)),
+        metadata: delimitUntrustedMetadata(chunk.metadata),
+      })),
+      media: publicContext.media.map((media) => ({
+        ...media,
+        dataRole: UNTRUSTED_REFERENCE_ROLE,
+        altText: media.altText
+          ? delimitUntrustedReference(sanitizePublicString(media.altText))
+          : null,
+        caption: media.caption
+          ? delimitUntrustedReference(sanitizePublicString(media.caption))
+          : null,
+        ocrText: media.ocrText
+          ? delimitUntrustedReference(sanitizePublicString(media.ocrText))
+          : null,
+        metadata: delimitUntrustedMetadata(media.metadata),
+      })),
+      edges: publicContext.edges.map((edge) => ({
+        ...edge,
+        dataRole: UNTRUSTED_REFERENCE_ROLE,
+        toExternalId: edge.toExternalId
+          ? sanitizePublicString(edge.toExternalId)
+          : null,
+        metadata: delimitUntrustedMetadata(edge.metadata),
+      })),
+    };
+  },
+});
+
+function boundedStoredNativeCode(
+  content: string,
+  artifact: Parameters<typeof validateCompiledNativeHtml>[1],
+): string | null {
+  if (Buffer.byteLength(content, "utf8") > MAX_STORED_NATIVE_CODE_BYTES) {
+    return null;
+  }
+  try {
+    validateCompiledNativeHtml(content, artifact);
+    return content;
+  } catch {
+    return null;
+  }
+}

package/src/actions/index.ts

@@ -0,0 +1,65 @@
+import type { ActionEntry } from "@agent-native/core/server";
+
+import confirmCanonicalLogo from "./confirm-canonical-logo.js";
+import continueContextImport from "./continue-context-import.js";
+import creativeContextA2A from "./creative-context-a2a.js";
+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 inferBrandDna from "./infer-brand-dna.js";
+import listCanonicalLogoCandidates from "./list-canonical-logo-candidates.js";
+import listContextConnections from "./list-context-connections.js";
+import listContextPacks from "./list-context-packs.js";
+import listContextSources from "./list-context-sources.js";
+import listContextSuggestions from "./list-context-suggestions.js";
+import manageBrandProfile from "./manage-brand-profile.js";
+import manageContextPack from "./manage-context-pack.js";
+import manageContextSource from "./manage-context-source.js";
+import manageLayoutTemplate from "./manage-layout-template.js";
+import previewContextImport from "./preview-context-import.js";
+import processContextPurge from "./process-context-purge.js";
+import proposeBrandDna from "./propose-brand-dna.js";
+import proposeCanonicalLogo from "./propose-canonical-logo.js";
+import publishBrandDna from "./publish-brand-dna.js";
+import recommendContextRoots from "./recommend-context-roots.js";
+import recordContextFeedback from "./record-context-feedback.js";
+import reviewContextItems from "./review-context-items.js";
+import runEmbeddingBakeoff from "./run-embedding-bakeoff.js";
+import searchCreativeContext from "./search-creative-context.js";
+import setBrandDna from "./set-brand-dna.js";
+import startContextEnrichment from "./start-context-enrichment.js";
+import startContextImport from "./start-context-import.js";
+
+export const creativeContextActions: Record<string, ActionEntry> = {
+  "confirm-canonical-logo": confirmCanonicalLogo,
+  "continue-context-import": continueContextImport,
+  "creative-context-a2a": creativeContextA2A,
+  "get-brand-profile": getBrandProfile,
+  "get-context-import-status": getContextImportStatus,
+  "get-context-item": getContextItem,
+  "get-context-pack": getContextPack,
+  "infer-brand-dna": inferBrandDna,
+  "list-canonical-logo-candidates": listCanonicalLogoCandidates,
+  "list-context-packs": listContextPacks,
+  "list-context-connections": listContextConnections,
+  "list-context-sources": listContextSources,
+  "list-context-suggestions": listContextSuggestions,
+  "manage-context-pack": manageContextPack,
+  "manage-brand-profile": manageBrandProfile,
+  "manage-context-source": manageContextSource,
+  "manage-layout-template": manageLayoutTemplate,
+  "preview-context-import": previewContextImport,
+  "process-context-purge": processContextPurge,
+  "propose-brand-dna": proposeBrandDna,
+  "propose-canonical-logo": proposeCanonicalLogo,
+  "publish-brand-dna": publishBrandDna,
+  "record-context-feedback": recordContextFeedback,
+  "recommend-context-roots": recommendContextRoots,
+  "review-context-items": reviewContextItems,
+  "run-embedding-bakeoff": runEmbeddingBakeoff,
+  "search-creative-context": searchCreativeContext,
+  "set-brand-dna": setBrandDna,
+  "start-context-import": startContextImport,
+  "start-context-enrichment": startContextEnrichment,
+};

package/src/actions/infer-brand-dna.ts

@@ -0,0 +1,15 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { inferBrandDnaProposalFromCorpus } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Infer a deterministic draft Design DNA proposal from hydrated corpus colors, fonts, layouts, and voice evidence. The proposal never changes published context.",
+  schema: z.object({
+    sourceId: z.string().min(1),
+    profileId: z.string().min(1).optional(),
+  }),
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: inferBrandDnaProposalFromCorpus,
+});

package/src/actions/list-canonical-logo-candidates.ts

@@ -0,0 +1,121 @@
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, desc, eq, like, ne, or, sql } from "drizzle-orm";
+import { z } from "zod";
+
+import { creativeContextMediaUrl } from "../media-url.js";
+import { getCreativeContext } from "../server/context.js";
+
+export default defineAction({
+  description:
+    "Rank accessible exact-version logo candidates for human review; Figma vectors outrank website SVG/OG assets, which outrank deck rasters. This never sets a canonical logo.",
+  schema: z.object({
+    profileId: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async ({ profileId, limit }) => {
+    if (profileId) {
+      await assertAccess(
+        "creative-context-brand",
+        profileId,
+        "viewer",
+        undefined,
+        { skipResourceBody: true },
+      );
+    }
+    const { getDb, schema } = getCreativeContext();
+    const rows = await getDb()
+      .select({
+        mediaId: schema.contextMedia.id,
+        itemId: schema.contextItems.id,
+        itemVersionId: schema.contextMedia.itemVersionId,
+        title: schema.contextItems.title,
+        itemKind: schema.contextItems.kind,
+        sourceKind: schema.contextSources.kind,
+        mimeType: schema.contextMedia.mimeType,
+        metadata: schema.contextMedia.metadata,
+        createdAt: schema.contextMedia.createdAt,
+      })
+      .from(schema.contextMedia)
+      .innerJoin(
+        schema.contextItems,
+        eq(schema.contextItems.id, schema.contextMedia.itemId),
+      )
+      .innerJoin(
+        schema.contextSources,
+        eq(schema.contextSources.id, schema.contextItems.sourceId),
+      )
+      .where(
+        and(
+          accessFilter(schema.contextSources, schema.contextSourceShares),
+          ne(schema.contextSources.status, "archived"),
+          ne(schema.contextSources.upstreamAccess, "restricted"),
+          eq(schema.contextItems.status, "active"),
+          eq(schema.contextItems.curationStatus, "included"),
+          eq(schema.contextMedia.kind, "image"),
+          or(
+            like(
+              schema.contextMedia.metadata,
+              '%"canonicalLogoCandidate":true%',
+            ),
+            like(schema.contextMedia.metadata, '%"assetRole":"open-graph"%'),
+            sql`lower(${schema.contextItems.title}) like '%logo%'`,
+            sql`lower(${schema.contextItems.title}) like '%wordmark%'`,
+            sql`lower(${schema.contextItems.title}) like '%brandmark%'`,
+          ),
+          eq(
+            schema.contextItems.currentVersionId,
+            schema.contextMedia.itemVersionId,
+          ),
+        ),
+      )
+      .orderBy(desc(schema.contextMedia.createdAt))
+      .limit(500);
+    const candidates = rows
+      .map((row: any) => {
+        let metadata: Record<string, unknown> = {};
+        try {
+          metadata = JSON.parse(row.metadata || "{}");
+        } catch {
+          metadata = {};
+        }
+        const vector = row.mimeType === "image/svg+xml";
+        const logoNamed = /logo|wordmark|brandmark/i.test(
+          `${row.title} ${row.itemKind}`,
+        );
+        const connectorCandidate = metadata.canonicalLogoCandidate === true;
+        const tier =
+          row.sourceKind === "figma" && vector
+            ? 3
+            : row.sourceKind === "website" && vector
+              ? 2
+              : row.sourceKind === "website"
+                ? 1.5
+                : row.sourceKind === "google-slides"
+                  ? 1
+                  : 0.5;
+        return {
+          mediaId: row.mediaId,
+          itemId: row.itemId,
+          itemVersionId: row.itemVersionId,
+          title: row.title,
+          mimeType: row.mimeType,
+          thumbnailUrl: creativeContextMediaUrl({ mediaId: row.mediaId }),
+          score: tier + (connectorCandidate ? 1 : 0) + (logoNamed ? 0.4 : 0),
+          evidence: {
+            sourceKind: row.sourceKind,
+            vector,
+            logoNamed,
+            connectorCandidate,
+            rankingPolicy: "figma-vector > website-svg-og > deck-raster",
+          },
+        };
+      })
+      .sort((left: any, right: any) => right.score - left.score)
+      .slice(0, limit);
+    return { profileId: profileId ?? null, candidates };
+  },
+});

package/src/actions/list-context-connections.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+
+import { creativeContextConnectionPath } from "./list-context-connections.js";
+
+describe("creative context connection paths", () => {
+  it.each([
+    ["figma", "assets"],
+    ["google_drive", "slides"],
+    ["notion", "content"],
+  ] as const)(
+    "binds the %s OAuth flow to the consuming app and Library return tab",
+    (provider, appId) => {
+      const path = creativeContextConnectionPath({ provider, appId });
+      const url = new URL(path, "https://app.example.com");
+
+      expect(url.pathname).toBe(
+        `/_agent-native/connections/oauth/${provider}/start`,
+      );
+      expect(url.searchParams.get("appId")).toBe(appId);
+      expect(url.searchParams.get("return")).toBe("/agent#library");
+    },
+  );
+});

package/src/actions/list-context-connections.ts

@@ -0,0 +1,51 @@
+import { defineAction } from "@agent-native/core/action";
+import { listWorkspaceConnectionsForApp } from "@agent-native/core/workspace-connections";
+import { z } from "zod";
+
+import { getCreativeContext } from "../server/context.js";
+
+const CREATIVE_CONTEXT_LIBRARY_PATH = "/agent#library";
+
+export function creativeContextConnectionPath(input: {
+  provider: "google_drive" | "figma" | "notion";
+  appId: string;
+}): string {
+  const query = new URLSearchParams({
+    appId: input.appId,
+    return: CREATIVE_CONTEXT_LIBRARY_PATH,
+  });
+  return `/_agent-native/connections/oauth/${input.provider}/start?${query}`;
+}
+
+export default defineAction({
+  description:
+    "List active workspace connections explicitly available to the consuming app for creative-context source setup.",
+  schema: z.object({
+    provider: z.enum(["google_drive", "figma", "notion"]),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async ({ provider }) => {
+    const appId = getCreativeContext().connectorContext.appId;
+    const available = await listWorkspaceConnectionsForApp({ appId, provider });
+    const connections = available
+      .filter((connection) => connection.status === "connected")
+      .map((connection) => ({
+        connectionId: connection.id,
+        provider: connection.provider,
+        label: connection.accountLabel ?? connection.label,
+      }));
+    return {
+      appId,
+      provider,
+      connections,
+      autoSelectedConnectionId:
+        connections.length === 1 ? connections[0]!.connectionId : null,
+      needsPicker: connections.length > 1,
+      needsSetup: connections.length === 0,
+      connectionsPath: "/settings/connections",
+      connectPath: creativeContextConnectionPath({ provider, appId }),
+    };
+  },
+});

package/src/actions/list-context-packs.ts

@@ -0,0 +1,17 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { listContextPacks } from "../store/index.js";
+
+export default defineAction({
+  description: "List accessible immutable creative context packs.",
+  schema: z.object({
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z.string().optional(),
+    includeArchived: z.boolean().default(false),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: listContextPacks,
+});

package/src/actions/list-context-sources.ts

@@ -0,0 +1,21 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { listContextSources } from "../store/index.js";
+
+export default defineAction({
+  description: "List creative context sources visible to the current user.",
+  schema: z.object({
+    status: z.enum(["active", "paused", "archived", "error"]).optional(),
+    healthStatus: z
+      .enum(["healthy", "stale", "error", "needs_setup", "paused"])
+      .optional(),
+    kind: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: listContextSources,
+});

package/src/actions/list-context-suggestions.ts

@@ -0,0 +1,30 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { getCreativeContext } from "../server/context.js";
+import { listCreativeContextSuggestions } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "List creative-context logo and layout proposals awaiting explicit human review.",
+  schema: z.object({
+    kind: z.enum(["canonical-logo", "layout-template"]).optional(),
+    status: z
+      .enum(["proposed", "confirmed", "rejected", "promoted", "demoted"])
+      .optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  agentTool: false,
+  run: async (args) => {
+    const projections = getCreativeContext().projections;
+    return {
+      suggestions: await listCreativeContextSuggestions(args),
+      capabilities: {
+        canonicalLogo: Boolean(projections?.canonicalLogo),
+        layoutTemplate: Boolean(projections?.layoutTemplate),
+      },
+    };
+  },
+});

package/src/actions/manage-brand-profile.ts

@@ -0,0 +1,58 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  previewBrandProfilePromotion,
+  promoteBrandProfileToOrg,
+} from "../store/index.js";
+
+const schema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("preview-promotion"),
+    profileId: z.string().min(1),
+  }),
+  z.object({
+    operation: z.literal("promote-to-org"),
+    profileId: z.string().min(1),
+    confirmation: z.object({
+      profileName: z.string().min(1),
+      dnaVersionId: z.string().min(1),
+      targetOrgId: z.string().min(1),
+    }),
+  }),
+]);
+
+const agentInputSchema = z.object({
+  operation: z.enum(["preview-promotion", "promote-to-org"]),
+  profileId: z.string().min(1),
+  confirmation: z
+    .object({
+      profileName: z.string().min(1),
+      dnaVersionId: z.string().min(1),
+      targetOrgId: z.string().min(1),
+    })
+    .optional(),
+});
+
+export default defineAction({
+  description:
+    "Preview or explicitly promote a human-published brand profile to the active organization; inferred proposals are never promoted automatically.",
+  schema,
+  agentInputSchema,
+  needsApproval: (args) => args.operation === "promote-to-org",
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: async (args) =>
+    args.operation === "preview-promotion"
+      ? { promotionPreview: await previewBrandProfilePromotion(args.profileId) }
+      : {
+          promoted: await promoteBrandProfileToOrg(
+            args.profileId,
+            args.confirmation,
+          ),
+        },
+});

package/src/actions/manage-context-pack.ts

@@ -0,0 +1,75 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  archiveContextPack,
+  createContextPack,
+  deriveContextPack,
+  setContextPackPinned,
+} from "../store/index.js";
+
+const member = z.object({
+  itemId: z.string().min(1),
+  itemVersionId: z.string().min(1).optional(),
+  reason: z.string().max(2000).optional(),
+});
+
+const schema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("create"),
+    name: z.string().trim().min(1).max(200),
+    description: z.string().max(5000).nullable().optional(),
+    brandDnaVersionId: z.string().min(1).nullable().optional(),
+    members: z.array(member).max(1000),
+    pinned: z.boolean().optional(),
+  }),
+  z.object({
+    operation: z.literal("derive"),
+    packId: z.string().min(1),
+    name: z.string().trim().min(1).max(200).optional(),
+    description: z.string().max(5000).nullable().optional(),
+    addMembers: z.array(member).max(1000).optional(),
+    removeItemIds: z.array(z.string().min(1)).max(1000).optional(),
+    brandDnaVersionId: z.string().min(1).nullable().optional(),
+    pinned: z.boolean().optional(),
+  }),
+  z.object({
+    operation: z.enum(["pin", "unpin", "archive"]),
+    packId: z.string().min(1),
+  }),
+]);
+
+const agentInputSchema = z.object({
+  operation: z.enum(["create", "derive", "pin", "unpin", "archive"]),
+  packId: z.string().min(1).optional(),
+  name: z.string().trim().min(1).max(200).optional(),
+  description: z.string().max(5000).nullable().optional(),
+  brandDnaVersionId: z.string().min(1).nullable().optional(),
+  members: z.array(member).max(1000).optional(),
+  addMembers: z.array(member).max(1000).optional(),
+  removeItemIds: z.array(z.string().min(1)).max(1000).optional(),
+  pinned: z.boolean().optional(),
+});
+
+export default defineAction({
+  description:
+    "Create an immutable context pack, derive a new membership snapshot, change a separate user pin pointer, or archive a pack. Existing member rows are never mutated.",
+  schema,
+  agentInputSchema,
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: async (args) => {
+    if (args.operation === "create") {
+      return { pack: await createContextPack(args), deleted: false };
+    }
+    if (args.operation === "derive") {
+      return { pack: await deriveContextPack(args), deleted: false };
+    }
+    if (args.operation === "archive") {
+      return { pack: await archiveContextPack(args.packId), deleted: false };
+    }
+    return {
+      pack: await setContextPackPinned(args.packId, args.operation === "pin"),
+      deleted: false,
+    };
+  },
+});