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

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-membership.ts

@@ -0,0 +1,80 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  manageContextMembership,
+  submitLatestContextMembershipUpdate,
+} from "../store/index.js";
+
+const nativeResource = z.object({
+  appId: z.string().min(1),
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  expectedUpdatedAt: z.string().min(1).optional(),
+});
+const schema = z.discriminatedUnion("operation", [
+  z
+    .object({
+      operation: z.literal("submit"),
+      contextId: z.string().min(1),
+      itemId: z.string().min(1).optional(),
+      itemVersionId: z.string().min(1).optional(),
+      nativeResource: nativeResource.optional(),
+      note: z.string().max(5000).optional(),
+      rank: z.enum(["canonical", "exemplar", "normal"]).optional(),
+      purpose: z.string().max(1000).optional(),
+      confirmBroaderPublication: z.boolean().optional(),
+    })
+    .refine(
+      (value) => Boolean(value.itemId || value.nativeResource),
+      "Provide itemId or nativeResource",
+    ),
+  z.object({
+    operation: z.literal("submit-latest"),
+    contextId: z.string().min(1),
+    membershipId: z.string().min(1),
+    note: z.string().max(5000).optional(),
+    confirmBroaderPublication: z.boolean().optional(),
+  }),
+  z.object({
+    operation: z.enum(["approve", "request-changes", "withdraw", "remove"]),
+    contextId: z.string().min(1),
+    membershipId: z.string().min(1),
+    note: z.string().max(5000).optional(),
+  }),
+]);
+
+export default defineAction({
+  description:
+    "Submit an artifact or the latest accessible native-app version to a governed Creative Context, approve or request changes on a pending submission, withdraw it, or remove a published membership.",
+  schema,
+  agentInputSchema: z.object({
+    operation: z.enum([
+      "submit",
+      "submit-latest",
+      "approve",
+      "request-changes",
+      "withdraw",
+      "remove",
+    ]),
+    contextId: z.string().min(1),
+    membershipId: z.string().optional(),
+    itemId: z.string().optional(),
+    itemVersionId: z.string().optional(),
+    nativeResource: nativeResource.optional(),
+    note: z.string().optional(),
+    rank: z.enum(["canonical", "exemplar", "normal"]).optional(),
+    purpose: z.string().optional(),
+    confirmBroaderPublication: z.boolean().optional(),
+  }),
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: (args) =>
+    args.operation === "submit-latest"
+      ? submitLatestContextMembershipUpdate(args)
+      : manageContextMembership(args),
+});

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

@@ -0,0 +1,81 @@
+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(),
+    baseContextId: z.string().min(1).nullable().optional(),
+    specialtyContextId: z.string().min(1).nullable().optional(),
+    selectionReason: z.string().max(2000).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(),
+  baseContextId: z.string().min(1).nullable().optional(),
+  specialtyContextId: z.string().min(1).nullable().optional(),
+  selectionReason: z.string().max(2000).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,
+    };
+  },
+});

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

@@ -0,0 +1,151 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { CREATIVE_CONTEXT_SOURCE_KINDS } from "../types.js";
+
+const importableSourceKinds = CREATIVE_CONTEXT_SOURCE_KINDS.filter(
+  (kind) => kind !== "native-app",
+) as ["manual", "upload", "google-slides", "figma", "notion", "website"];
+
+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(importableSourceKinds),
+    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(importableSourceKinds).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-creative-context.ts

@@ -0,0 +1,73 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  archiveCreativeContext,
+  createCreativeContext,
+  setCreativeContextAppDefault,
+  updateCreativeContext,
+} from "../store/index.js";
+
+const policy = z.enum(["open", "review", "admins-only"]);
+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(),
+    kind: z.enum(["default", "specialty"]),
+    brandProfileId: z.string().min(1).nullable().optional(),
+    approvalPolicy: policy.optional(),
+  }),
+  z.object({
+    operation: z.literal("update"),
+    contextId: z.string().min(1),
+    patch: z.object({
+      name: z.string().trim().min(1).max(200).optional(),
+      description: z.string().max(5000).nullable().optional(),
+      brandProfileId: z.string().min(1).nullable().optional(),
+      approvalPolicy: policy.optional(),
+    }),
+  }),
+  z.object({ operation: z.literal("archive"), contextId: z.string().min(1) }),
+  z.object({
+    operation: z.literal("set-app-default"),
+    contextId: z.string().min(1),
+    appId: z.string().trim().min(1).max(200),
+  }),
+]);
+
+export default defineAction({
+  description:
+    "Create, govern, archive, or bind a governed Creative Context. Context sharing is managed by the shared resource actions.",
+  schema,
+  agentInputSchema: z.object({
+    operation: z.enum(["create", "update", "archive", "set-app-default"]),
+    contextId: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().nullable().optional(),
+    kind: z.enum(["default", "specialty"]).optional(),
+    brandProfileId: z.string().nullable().optional(),
+    approvalPolicy: policy.optional(),
+    appId: z.string().optional(),
+    patch: z.record(z.string(), z.unknown()).optional(),
+  }),
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+    isConsequential: true,
+  },
+  run: async (args) => {
+    if (args.operation === "create")
+      return { context: await createCreativeContext(args) };
+    if (args.operation === "update")
+      return {
+        context: await updateCreativeContext(args.contextId, args.patch),
+      };
+    if (args.operation === "archive")
+      return { context: await archiveCreativeContext(args.contextId) };
+    return {
+      context: await setCreativeContextAppDefault(args.contextId, args.appId),
+    };
+  },
+});

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,28 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { serializePublicJob } from "../server/public-serialization.js";
+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: serializePublicJob(
+        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" }),
+});