@agent-native/creative-context 0.1.0

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

@@ -0,0 +1,154 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  archiveContextSource,
+  createContextSource,
+  deleteContextSource,
+  previewContextSourcePromotion,
+  promoteContextSource,
+  restoreContextSource,
+  toSourceSummary,
+  updateContextSource,
+} from "../store/index.js";
+
+const upstreamAccess = z.enum(["available", "restricted", "unknown"]);
+const sourceStatus = z.enum(["active", "paused", "archived", "error"]);
+const schema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("create"),
+    name: z.string().trim().min(1).max(200),
+    kind: z.enum([
+      "manual",
+      "upload",
+      "google-slides",
+      "figma",
+      "notion",
+      "website",
+    ]),
+    externalRef: z.string().max(2000).optional(),
+    connectionId: z.string().max(500).optional(),
+    config: z.record(z.string(), z.unknown()).optional(),
+    upstreamAccess: upstreamAccess.optional(),
+  }),
+  z.object({
+    operation: z.literal("update"),
+    sourceId: z.string().min(1),
+    patch: z.object({
+      name: z.string().trim().min(1).max(200).optional(),
+      externalRef: z.string().max(2000).nullable().optional(),
+      connectionId: z.string().max(500).nullable().optional(),
+      config: z.record(z.string(), z.unknown()).optional(),
+      status: sourceStatus.optional(),
+      upstreamAccess: upstreamAccess.optional(),
+    }),
+  }),
+  z.object({
+    operation: z.enum(["archive", "restore", "delete"]),
+    sourceId: z.string().min(1),
+  }),
+  z.object({
+    operation: z.literal("preview-promotion"),
+    sourceId: z.string().min(1),
+  }),
+  z.object({
+    operation: z.literal("promote"),
+    sourceId: z.string().min(1),
+    confirmation: z.object({
+      containerRef: z.string().min(1),
+      boundaryHash: z.string().length(64),
+      itemCount: z.number().int().min(0),
+    }),
+  }),
+]);
+
+const agentInputSchema = z.object({
+  operation: z.enum([
+    "create",
+    "update",
+    "archive",
+    "restore",
+    "delete",
+    "preview-promotion",
+    "promote",
+  ]),
+  sourceId: z.string().min(1).optional(),
+  name: z.string().trim().min(1).max(200).optional(),
+  kind: z
+    .enum(["manual", "upload", "google-slides", "figma", "notion", "website"])
+    .optional(),
+  externalRef: z.string().max(2000).optional(),
+  connectionId: z.string().max(500).optional(),
+  config: z.record(z.string(), z.unknown()).optional(),
+  upstreamAccess: upstreamAccess.optional(),
+  patch: z
+    .object({
+      name: z.string().trim().min(1).max(200).optional(),
+      externalRef: z.string().max(2000).nullable().optional(),
+      connectionId: z.string().max(500).nullable().optional(),
+      config: z.record(z.string(), z.unknown()).optional(),
+      status: sourceStatus.optional(),
+      upstreamAccess: upstreamAccess.optional(),
+    })
+    .optional(),
+  confirmation: z
+    .object({
+      containerRef: z.string().min(1),
+      boundaryHash: z.string().length(64),
+      itemCount: z.number().int().min(0),
+    })
+    .optional(),
+});
+
+export default defineAction({
+  description:
+    "Create or update a private source, archive/restore it, preview a deliberate org promotion, promote after confirming container and count, or tombstone it and enqueue purge.",
+  schema,
+  agentInputSchema,
+  needsApproval: (args) =>
+    args.operation === "delete" || args.operation === "promote",
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: async (args) => {
+    if (args.operation === "create") {
+      const source = await createContextSource(args);
+      return { source: toSourceSummary(source), deleted: false };
+    }
+    if (args.operation === "update") {
+      const source = await updateContextSource(args.sourceId, args.patch);
+      return { source: toSourceSummary(source), deleted: false };
+    }
+    if (args.operation === "archive") {
+      const source = await archiveContextSource(args.sourceId);
+      return { source: toSourceSummary(source), deleted: false };
+    }
+    if (args.operation === "restore") {
+      const source = await restoreContextSource(args.sourceId);
+      return { source: toSourceSummary(source), deleted: false };
+    }
+    if (args.operation === "preview-promotion") {
+      return {
+        source: null,
+        deleted: false,
+        promotionPreview: await previewContextSourcePromotion(args.sourceId),
+      };
+    }
+    if (args.operation === "promote") {
+      const source = await promoteContextSource(
+        args.sourceId,
+        args.confirmation,
+      );
+      return { source: toSourceSummary(source), deleted: false };
+    }
+    const deleted = await deleteContextSource(args.sourceId);
+    return {
+      source: toSourceSummary(deleted.source),
+      deleted: true,
+      purgeJobId: deleted.purgeJobId,
+    };
+  },
+});

package/src/actions/manage-layout-template.ts

@@ -0,0 +1,51 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  proposeCreativeContextSuggestion,
+  applyLayoutTemplateSuggestion,
+} from "../store/index.js";
+
+const schema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("propose"),
+    profileId: z.string().min(1).optional(),
+    itemId: z.string().min(1),
+    itemVersionId: z.string().min(1).optional(),
+    reason: z.string().max(5000).optional(),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  }),
+  z.object({
+    operation: z.enum(["promote", "demote", "reject"]),
+    suggestionId: z.string().min(1),
+  }),
+]);
+
+const agentInputSchema = z.object({
+  operation: z.enum(["propose", "promote", "demote", "reject"]),
+  profileId: z.string().min(1).optional(),
+  itemId: z.string().min(1).optional(),
+  itemVersionId: z.string().min(1).optional(),
+  reason: z.string().max(5000).optional(),
+  payload: z.record(z.string(), z.unknown()).optional(),
+  suggestionId: z.string().min(1).optional(),
+});
+
+export default defineAction({
+  description:
+    "Propose, promote, demote, or reject a reusable layout-template suggestion pinned to an exact item version.",
+  schema,
+  agentInputSchema,
+  needsApproval: (args) => args.operation !== "propose",
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: (args) =>
+    args.operation === "propose"
+      ? proposeCreativeContextSuggestion({
+          ...args,
+          kind: "layout-template",
+        })
+      : applyLayoutTemplateSuggestion({
+          suggestionId: args.suggestionId,
+          operation: args.operation,
+        }),
+});

package/src/actions/preview-context-import.spec.ts

@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getContextSource: vi.fn(),
+  inventory: vi.fn(),
+}));
+
+vi.mock("../store/index.js", () => ({
+  getContextSource: mocks.getContextSource,
+}));
+
+vi.mock("../server/context.js", () => ({
+  getCreativeContext: vi.fn(() => ({
+    connectors: { get: () => ({ inventory: mocks.inventory }) },
+    connectorContext: {},
+  })),
+}));
+
+import action from "./preview-context-import.js";
+
+describe("preview-context-import public boundary", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getContextSource.mockResolvedValue({
+      id: "source-1",
+      kind: "upload",
+      config: {},
+      connectionId: null,
+      ownerEmail: "alice@example.test",
+    });
+    mocks.inventory.mockResolvedValue({
+      items: [
+        {
+          externalId: "upload-1",
+          kind: "uploaded-document",
+          title: "Launch deck",
+          metadata: {
+            entryIndex: 0,
+            storageKey: "creative-context-blob:v1:private-value",
+            warning:
+              "Fetched https://provider.example/private?token=secret-value",
+          },
+        },
+      ],
+      nextCursor: null,
+      complete: true,
+      coverage: { inspected: 1, returned: 1, truncated: false },
+    });
+  });
+
+  it("does not expose upload handles or substring capability URLs", async () => {
+    const result = (await action.run({
+      sourceId: "source-1",
+      limit: 50,
+    })) as any;
+
+    expect(result.items[0].metadata).toEqual({
+      entryIndex: 0,
+      warning: "Fetched [redacted]",
+    });
+    expect(JSON.stringify(result)).not.toContain("creative-context-blob");
+    expect(JSON.stringify(result)).not.toContain("secret-value");
+  });
+});

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

@@ -0,0 +1,61 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { stringArray } from "../connectors/provider-response.js";
+import { smartDefaultExternalIds } from "../connectors/smart-defaults.js";
+import { getCreativeContext } from "../server/context.js";
+import { sanitizePublicMetadata } from "../server/public-serialization.js";
+import { getContextSource } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Preview source inventory metadata without fetching or returning item content.",
+  schema: z.object({
+    sourceId: z.string().min(1),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const source = await getContextSource(args.sourceId);
+    if (!source) throw new Error("Context source not found or not accessible");
+    const { connectors, connectorContext } = getCreativeContext();
+    const page = await connectors.get(source.kind).inventory(
+      {
+        sourceId: source.id,
+        config: {
+          ...source.config,
+          ...(source.connectionId ? { connectionId: source.connectionId } : {}),
+        },
+        cursor: args.cursor ?? null,
+        limit: args.limit,
+      },
+      { ...connectorContext, ownerEmail: source.ownerEmail },
+    );
+    const items = page.items.map((item) => ({
+      externalId: item.externalId,
+      kind: item.kind,
+      title: item.title,
+      canonicalUrl: item.canonicalUrl,
+      mimeType: item.mimeType,
+      sourceModifiedAt: item.sourceModifiedAt,
+      sizeBytes: item.sizeBytes,
+      metadata: sanitizePublicMetadata(item.metadata),
+      upstreamAccess: item.upstreamAccess,
+    }));
+    return {
+      sourceId: source.id,
+      items,
+      smartDefaultExternalIds: smartDefaultExternalIds({
+        kind: source.kind,
+        items: page.items,
+        canonicalExternalIds: stringArray(source.config.canonicalExternalIds),
+        pinnedExternalIds: stringArray(source.config.pinnedExternalIds),
+        now: connectorContext.now?.() ?? new Date(),
+      }),
+      nextCursor: page.nextCursor ?? undefined,
+      total: page.complete ? page.coverage.inspected : undefined,
+    };
+  },
+});

package/src/actions/process-context-purge.ts

@@ -0,0 +1,25 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  getJob,
+  purgeContextSourceArtifacts,
+  updateJob,
+} from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Process an already-approved source purge job: remove private blobs, derived search indexes, corpus children, and deprecate promoted derivatives.",
+  schema: z.object({ jobId: z.string().min(1) }),
+  run: async ({ jobId }) => {
+    const job = await getJob(jobId);
+    if (!job || job.kind !== "purge" || !job.sourceId) {
+      throw new Error("Pending creative-context purge job not found");
+    }
+    const result = await purgeContextSourceArtifacts(job.sourceId);
+    return {
+      job: await updateJob(job.id, { status: "completed", result }),
+      result,
+    };
+  },
+});

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

@@ -0,0 +1,22 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { saveBrandDnaCandidate } from "../store/index.js";
+
+const dna = z
+  .object({ summary: z.string().trim().min(1).max(20_000) })
+  .catchall(z.unknown());
+
+export default defineAction({
+  description:
+    "Save an inferred immutable brand DNA proposal pinned to exact evidence without overwriting published context.",
+  schema: z.object({
+    profileId: z.string().min(1).optional(),
+    name: z.string().trim().min(1).max(200).optional(),
+    description: z.string().max(5000).nullable().optional(),
+    dna,
+    evidenceItemIds: z.array(z.string().min(1)).max(500).optional(),
+  }),
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: (args) => saveBrandDnaCandidate({ ...args, status: "proposed" }),
+});

package/src/actions/propose-canonical-logo.ts

@@ -0,0 +1,19 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { proposeCreativeContextSuggestion } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Propose an exact versioned creative-context item as the canonical logo for review.",
+  schema: z.object({
+    profileId: z.string().min(1).optional(),
+    itemId: z.string().min(1),
+    itemVersionId: z.string().min(1).optional(),
+    reason: z.string().max(5000).optional(),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  }),
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: (args) =>
+    proposeCreativeContextSuggestion({ ...args, kind: "canonical-logo" }),
+});

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

@@ -0,0 +1,25 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { publishBrandDna } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Publish an immutable brand DNA version pinned to exact evidence item versions and refresh transparent brand context.",
+  schema: z.object({
+    profileId: z.string().min(1),
+    proposalVersionId: z.string().min(1),
+    confirmation: z.object({
+      proposalVersionId: z.string().min(1),
+      contentHash: z.string().length(64),
+    }),
+  }),
+  needsApproval: true,
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: publishBrandDna,
+});

package/src/actions/recommend-context-roots.ts

@@ -0,0 +1,24 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { recommendContextRoots } from "../connectors/recommendations.js";
+import { getCreativeContext } from "../server/context.js";
+
+export default defineAction({
+  description:
+    "Return read-only provider-backed source recommendations for confirmation. Recommendations are never an import boundary and are not persisted.",
+  schema: z.object({
+    provider: z.enum(["notion", "google-slides", "figma"]),
+    connectionId: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(50).default(15),
+    figmaProjectId: z.string().min(1).optional(),
+    figmaTeamId: z.string().min(1).optional(),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    const { connectorContext } = getCreativeContext();
+    return recommendContextRoots(args, connectorContext);
+  },
+});

package/src/actions/record-context-feedback.ts

@@ -0,0 +1,16 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { recordContextFeedback } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Record a usefulness, correctness, or freshness signal against an exact context item version.",
+  schema: z.object({
+    itemId: z.string().min(1),
+    itemVersionId: z.string().min(1).optional(),
+    signal: z.enum(["helpful", "not-helpful", "incorrect", "outdated"]),
+    note: z.string().max(5000).optional(),
+  }),
+  run: recordContextFeedback,
+});

package/src/actions/review-context-items.ts

@@ -0,0 +1,69 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { serializePublicReviewItems } from "../server/public-serialization.js";
+import { reviewContextItems } from "../store/index.js";
+
+const schema = z.discriminatedUnion("operation", [
+  z.object({
+    sourceId: z.string().min(1),
+    operation: z.literal("list"),
+    queue: z.enum(["restricted", "all"]).default("restricted"),
+    limit: z.coerce.number().int().min(1).max(500).default(100),
+  }),
+  z.object({
+    sourceId: z.string().min(1),
+    operation: z.enum([
+      "approve",
+      "exclude",
+      "exemplar",
+      "normal",
+      "ignore",
+      "star",
+      "unstar",
+      "deprecate",
+      "restore",
+    ]),
+    itemIds: z.array(z.string().min(1)).min(1).max(500),
+  }),
+]);
+
+const agentInputSchema = z.object({
+  sourceId: z.string().min(1),
+  operation: z.enum([
+    "list",
+    "approve",
+    "exclude",
+    "exemplar",
+    "normal",
+    "ignore",
+    "star",
+    "unstar",
+    "deprecate",
+    "restore",
+  ]),
+  queue: z.enum(["restricted", "all"]).optional(),
+  limit: z.coerce.number().int().min(1).max(500).optional(),
+  itemIds: z.array(z.string().min(1)).min(1).max(500).optional(),
+});
+
+export default defineAction({
+  description:
+    "List pending restricted metadata without content, or approve/exclude selected items after user confirmation.",
+  schema,
+  agentInputSchema,
+  needsApproval: (args) => args.operation !== "list",
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: async (input) => {
+    const result = await reviewContextItems(input);
+    return {
+      ...result,
+      items: serializePublicReviewItems(result.items),
+    };
+  },
+});

package/src/actions/run-embedding-bakeoff.ts

@@ -0,0 +1,90 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { availableEmbeddingFamilies } from "../embeddings/providers.js";
+import {
+  bakeOffEmbeddingFamilies,
+  CREATIVE_CONTEXT_GOLD_DOCUMENTS,
+  CREATIVE_CONTEXT_GOLD_TASKS,
+  embeddingBakeoffPasses,
+} from "../eval/index.js";
+import { createEmbeddingSet } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Run the checked-in retrieval bake-off across configured embedding families and persist the winning family/model/version/dimensions as the active corpus choice.",
+  schema: z.object({ confirmProviderCosts: z.literal(true) }),
+  needsApproval: true,
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: async () => {
+    const families = await availableEmbeddingFamilies();
+    if (!families.length) {
+      throw new Error(
+        "Configure at least one GEMINI_API_KEY, COHERE_API_KEY, or VOYAGE_API_KEY before running the embedding bake-off.",
+      );
+    }
+    const results = await bakeOffEmbeddingFamilies({
+      families,
+      documents: Object.fromEntries(
+        CREATIVE_CONTEXT_GOLD_DOCUMENTS.map((document) => [
+          document.key,
+          {
+            text: `${document.title}\n${document.text}`,
+            ...(document.imageBase64
+              ? {
+                  images: [
+                    {
+                      mimeType: "image/png" as const,
+                      base64: document.imageBase64,
+                    },
+                  ],
+                }
+              : {}),
+          },
+        ]),
+      ),
+      tasks: CREATIVE_CONTEXT_GOLD_TASKS,
+      allowedDocumentKeys: CREATIVE_CONTEXT_GOLD_DOCUMENTS.filter(
+        (document) =>
+          document.owner !== "other-organization" &&
+          document.status === "active",
+      ).map((document) => document.key),
+    });
+    const winner = results.find((result) =>
+      embeddingBakeoffPasses(result.metrics),
+    );
+    if (!winner) {
+      throw new Error(
+        "No embedding family passed the hard multimodal retrieval and zero-leak thresholds; no active winner was persisted.",
+      );
+    }
+    const set = await createEmbeddingSet({
+      name: `Creative context ${winner.family.provider} bake-off winner`,
+      provider: winner.family.provider,
+      family: winner.family.id,
+      model: winner.family.model,
+      version: winner.family.version,
+      dimensions: winner.family.dimensions,
+      metadata: {
+        metrics: winner.metrics,
+        evaluatedAt: new Date().toISOString(),
+      },
+    });
+    return {
+      winner: set,
+      results: results.map((result) => ({
+        family: result.family.id,
+        provider: result.family.provider,
+        model: result.family.model,
+        version: result.family.version,
+        dimensions: result.family.dimensions,
+        metrics: result.metrics,
+      })),
+    };
+  },
+});

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

@@ -0,0 +1,47 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { performCreativeContextSearch } from "../server/retrieval.js";
+
+const schema = z
+  .object({
+    query: z.string().trim().min(1).max(1000).optional(),
+    imageBlobRef: z.string().min(1).max(20_000).optional(),
+    mediaId: z.string().min(1).optional(),
+    sourceIds: z.array(z.string().min(1)).max(100).optional(),
+    packId: z.string().min(1).optional(),
+    kinds: z.array(z.string().min(1)).max(50).optional(),
+    tags: z.array(z.string().min(1)).max(100).optional(),
+    colors: z.array(z.string().min(1)).max(100).optional(),
+    updatedAfter: z.iso.datetime().optional(),
+    updatedBefore: z.iso.datetime().optional(),
+    statuses: z
+      .array(z.enum(["active", "deprecated"]))
+      .max(2)
+      .optional(),
+    matchMode: z
+      .enum(["allTerms", "anyTerm", "phrase", "regex"])
+      .default("allTerms"),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    cursor: z.string().optional(),
+    maxPerSource: z.coerce.number().int().min(1).max(20).default(5),
+    snapshot: z.boolean().default(true),
+    contextPackName: z.string().trim().min(1).max(200).optional(),
+  })
+  .refine(
+    (value) => Boolean(value.query || value.imageBlobRef || value.mediaId),
+    {
+      message: "Provide query, imageBlobRef, or mediaId",
+    },
+  )
+  .refine((value) => !(value.imageBlobRef && value.mediaId), {
+    message: "Provide imageBlobRef or mediaId, not both",
+  });
+
+export default defineAction({
+  description:
+    "Search accessible curated creative context through portable lexical, Postgres FTS, and same-database pgvector lanes; fuse and diversify results, collapse revisions, and snapshot exact evidence by default.",
+  schema,
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: performCreativeContextSearch,
+});