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

package/src/actions/creative-context-a2a.spec.ts

@@ -0,0 +1,162 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getRequestUserEmail: vi.fn(),
+  decodeRequest: vi.fn(),
+  createResponseToken: vi.fn(),
+  resolveLocal: vi.fn(),
+  verifyArtifactAccess: vi.fn(),
+  getGeneration: vi.fn(),
+  recordGeneration: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  getRequestUserEmail: mocks.getRequestUserEmail,
+}));
+
+vi.mock("../server/isolated-a2a.js", () => ({
+  decodeCreativeContextA2ARequest: mocks.decodeRequest,
+  createCreativeContextA2AResponseToken: mocks.createResponseToken,
+}));
+
+vi.mock("../server/generation-context.js", () => ({
+  resolveGenerationCreativeContextLocal: mocks.resolveLocal,
+}));
+
+vi.mock("../server/generation-artifact-access.js", () => ({
+  verifyGenerationArtifactAccessCapability: mocks.verifyArtifactAccess,
+}));
+
+vi.mock("../store/generation.js", () => ({
+  getGenerationCreativeContext: mocks.getGeneration,
+  recordGenerationCreativeContext: mocks.recordGeneration,
+}));
+
+import action from "./creative-context-a2a.js";
+
+describe("creative-context-a2a receiver action", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getRequestUserEmail.mockReturnValue("alice@example.test");
+    mocks.decodeRequest.mockReturnValue({
+      protocol: "creative-context-a2a-v1",
+      requestId: "87f466ae-32f4-4d0f-9de7-96f955e69f7b",
+      operation: "resolve",
+      payload: { role: "slides", query: "launch" },
+    });
+    mocks.resolveLocal.mockResolvedValue({
+      contextMode: "auto",
+      contextPackId: null,
+      reuseLabels: [],
+      results: [],
+    });
+    mocks.createResponseToken.mockReturnValue("response-token");
+    mocks.verifyArtifactAccess.mockResolvedValue({ verified: true });
+    mocks.getGeneration.mockResolvedValue(null);
+    mocks.recordGeneration.mockResolvedValue({
+      id: "record-1",
+      appId: "slides",
+      artifactType: "deck",
+      artifactId: "deck-1",
+      contextMode: "auto",
+      contextPackId: null,
+      elementProvenance: [],
+      createdAt: "2026-07-16T00:00:00.000Z",
+    });
+  });
+
+  it("executes the local operation and returns the opaque response token", async () => {
+    await expect(
+      action.run({ requestToken: "request-token" }),
+    ).resolves.toMatchObject({
+      protocol: "creative-context-a2a-v1",
+      responseToken: "response-token",
+    });
+    expect(mocks.resolveLocal).toHaveBeenCalledWith({
+      role: "slides",
+      query: "launch",
+    });
+  });
+
+  it("rejects an A2A request without verified caller identity", async () => {
+    mocks.getRequestUserEmail.mockReturnValue(undefined);
+    await expect(action.run({ requestToken: "request-token" })).rejects.toThrow(
+      /cryptographically verified caller identity/,
+    );
+    expect(mocks.decodeRequest).not.toHaveBeenCalled();
+  });
+
+  it("keeps capability-free guessed reads owner-scoped", async () => {
+    const identity = {
+      appId: "slides",
+      artifactType: "deck",
+      artifactId: "guessed-deck",
+    };
+    mocks.decodeRequest.mockReturnValue({
+      protocol: "creative-context-a2a-v1",
+      requestId: "87f466ae-32f4-4d0f-9de7-96f955e69f7b",
+      operation: "read",
+      payload: { identity },
+    });
+
+    await action.run({ requestToken: "request-token" });
+
+    expect(mocks.verifyArtifactAccess).not.toHaveBeenCalled();
+    expect(mocks.getGeneration).toHaveBeenCalledWith(identity, {
+      artifactAccess: undefined,
+    });
+  });
+
+  it("requires a valid host capability for collaborative reads", async () => {
+    const identity = {
+      appId: "slides",
+      artifactType: "deck",
+      artifactId: "shared-deck",
+    };
+    mocks.decodeRequest.mockReturnValue({
+      protocol: "creative-context-a2a-v1",
+      requestId: "87f466ae-32f4-4d0f-9de7-96f955e69f7b",
+      operation: "read",
+      payload: {
+        identity,
+        artifactAccessCapability: "signed-capability",
+      },
+    });
+
+    await action.run({ requestToken: "request-token" });
+
+    expect(mocks.verifyArtifactAccess).toHaveBeenCalledWith(
+      "signed-capability",
+      identity,
+      "read",
+    );
+    expect(mocks.getGeneration).toHaveBeenCalledWith(identity, {
+      artifactAccess: { verified: true },
+    });
+  });
+
+  it("does not write when a guessed-artifact capability is invalid", async () => {
+    mocks.decodeRequest.mockReturnValue({
+      protocol: "creative-context-a2a-v1",
+      requestId: "87f466ae-32f4-4d0f-9de7-96f955e69f7b",
+      operation: "record",
+      payload: {
+        appId: "slides",
+        artifactType: "deck",
+        artifactId: "guessed-deck",
+        contextMode: "auto",
+        contextPackId: null,
+        reuseLabels: [],
+        artifactAccessCapability: "forged-capability",
+      },
+    });
+    mocks.verifyArtifactAccess.mockRejectedValue(
+      new Error("Invalid generation artifact access capability"),
+    );
+
+    await expect(action.run({ requestToken: "request-token" })).rejects.toThrow(
+      /invalid generation artifact access capability/i,
+    );
+    expect(mocks.recordGeneration).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,88 @@
+import { defineAction } from "@agent-native/core/action";
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import { verifyGenerationArtifactAccessCapability } from "../server/generation-artifact-access.js";
+import {
+  createCreativeContextA2AResponseToken,
+  decodeCreativeContextA2ARequest,
+} from "../server/isolated-a2a.js";
+
+export default defineAction({
+  description:
+    "Execute one authenticated, bounded Creative Context A2A protocol request. Use only for an inbound Creative Context machine-protocol message, then return responseToken verbatim.",
+  schema: z
+    .object({
+      requestToken: z.string().min(1).max(512_000),
+    })
+    .strict(),
+  publicAgent: {
+    expose: true,
+    readOnly: false,
+    requiresAuth: true,
+  },
+  run: async ({ requestToken }) => {
+    if (!getRequestUserEmail()) {
+      throw new Error(
+        "Creative Context A2A requires a cryptographically verified caller identity",
+      );
+    }
+    const request = decodeCreativeContextA2ARequest(requestToken);
+    let result: unknown;
+    switch (request.operation) {
+      case "resolve": {
+        const { resolveGenerationCreativeContextLocal } =
+          await import("../server/generation-context.js");
+        result = await resolveGenerationCreativeContextLocal(request.payload);
+        break;
+      }
+      case "validate": {
+        const { validateGenerationCreativeContextLocal } =
+          await import("../server/generation-context.js");
+        result = await validateGenerationCreativeContextLocal(request.payload);
+        break;
+      }
+      case "read": {
+        const { getGenerationCreativeContext } =
+          await import("../store/generation.js");
+        const artifactAccess = request.payload.artifactAccessCapability
+          ? await verifyGenerationArtifactAccessCapability(
+              request.payload.artifactAccessCapability,
+              request.payload.identity,
+              "read",
+            )
+          : undefined;
+        result = await getGenerationCreativeContext(request.payload.identity, {
+          artifactAccess,
+        });
+        break;
+      }
+      case "record": {
+        const { recordGenerationCreativeContext } =
+          await import("../store/generation.js");
+        const { artifactAccessCapability, ...record } = request.payload;
+        const artifactAccess = artifactAccessCapability
+          ? await verifyGenerationArtifactAccessCapability(
+              artifactAccessCapability,
+              record,
+              "record",
+            )
+          : undefined;
+        result = await recordGenerationCreativeContext(record, {
+          artifactAccess,
+        });
+        break;
+      }
+    }
+    const responseToken = createCreativeContextA2AResponseToken(
+      request,
+      result,
+    );
+    return {
+      protocol: "creative-context-a2a-v1",
+      requestId: request.requestId,
+      responseToken,
+      instruction: "Return responseToken verbatim and nothing else.",
+    };
+  },
+});

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

@@ -0,0 +1,16 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { serializePublicBrandProfile } from "../server/public-serialization.js";
+import { getBrandProfile } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Get an accessible brand profile and its current published DNA version.",
+  schema: z.object({ profileId: z.string().min(1).optional() }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (input) =>
+    serializePublicBrandProfile(await getBrandProfile(input)),
+});

package/src/actions/get-context-import-status.ts

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { serializePublicJob } from "../server/public-serialization.js";
+import { getJob } from "../store/index.js";
+
+export default defineAction({
+  description: "Get the persisted status and checkpoint progress of an import.",
+  schema: z.object({ jobId: z.string().min(1) }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ jobId }) => ({ job: serializePublicJob(await getJob(jobId)) }),
+});

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

@@ -0,0 +1 @@
+export { default } from "./get-creative-context.js";

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

@@ -0,0 +1,14 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { getContextPack } from "../store/index.js";
+
+export default defineAction({
+  description:
+    "Get an accessible context pack with exact immutable item-version evidence.",
+  schema: z.object({ packId: z.string().min(1) }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async ({ packId }) => ({ pack: await getContextPack(packId) }),
+});