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

package/src/server/isolated-a2a.ts

@@ -0,0 +1,416 @@
+import { getRequestUserEmail } from "@agent-native/core/server";
+import { z } from "zod";
+
+import type {
+  CreativeContextElementProvenance,
+  CreativeContextGenerationRecord,
+  CreativeContextReuseLabel,
+} from "../types.js";
+import type {
+  CreativeGenerationRole,
+  ResolveGenerationCreativeContextInput,
+} from "./generation-context.js";
+
+const PROTOCOL = "creative-context-a2a-v1";
+const RESPONSE_PREFIX = "CREATIVE_CONTEXT_A2A_RESPONSE_V1";
+const MAX_TOKEN_LENGTH = 512_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+const boundedId = z.string().min(1).max(256);
+const reuseInfluence = z.enum([
+  "reused",
+  "adapted",
+  "reference-conditioned",
+  "generated",
+]);
+const reuseLabelSchema = z
+  .object({
+    itemId: boundedId.optional(),
+    itemVersionId: boundedId.optional(),
+    kind: z.string().min(1).max(100),
+    label: z.string().min(1).max(2_000),
+    dataRole: z.literal("untrusted-reference"),
+    elementId: boundedId.optional(),
+    influence: reuseInfluence.optional(),
+  })
+  .strict();
+const elementProvenanceSchema = z
+  .object({
+    elementId: boundedId,
+    influence: reuseInfluence,
+    itemId: boundedId.optional(),
+    itemVersionId: boundedId.optional(),
+    label: z.string().max(2_000).optional(),
+  })
+  .strict();
+const generationIdentitySchema = z
+  .object({
+    appId: z.string().min(1).max(100),
+    artifactType: z.string().min(1).max(100),
+    artifactId: boundedId,
+  })
+  .strict();
+const generationRecordInputSchema = generationIdentitySchema
+  .extend({
+    contextMode: z.enum(["off", "auto", "pinned"]),
+    contextPackId: boundedId.nullable(),
+    reuseLabels: z.array(reuseLabelSchema).max(100),
+    elementProvenance: z.array(elementProvenanceSchema).max(500).optional(),
+  })
+  .strict();
+const artifactAccessCapabilitySchema = z.string().min(1).max(8_192);
+const generationRecordPayloadSchema = generationRecordInputSchema
+  .extend({
+    artifactAccessCapability: artifactAccessCapabilitySchema.optional(),
+  })
+  .strict();
+const generationRecordSchema = generationIdentitySchema
+  .extend({
+    id: boundedId,
+    contextMode: z.enum(["off", "auto", "pinned"]),
+    contextPackId: boundedId.nullable(),
+    elementProvenance: z.array(elementProvenanceSchema).max(500),
+    createdAt: z.iso.datetime(),
+  })
+  .strict();
+const remoteContextResultSchema = z
+  .object({
+    itemId: boundedId,
+    itemVersionId: boundedId,
+    kind: z.string().min(1).max(100),
+    title: z.string().max(20_000),
+    excerpt: z.string().max(20_000),
+    dataRole: z.literal("untrusted-reference"),
+  })
+  .strict();
+const resolvedContextSchema = z
+  .object({
+    contextMode: z.enum(["off", "auto", "pinned"]),
+    contextPackId: boundedId.nullable(),
+    reuseLabels: z.array(reuseLabelSchema).max(100),
+    results: z.array(remoteContextResultSchema).max(20),
+  })
+  .strict();
+
+const resolvePayloadSchema = z
+  .object({
+    query: z.string().max(1_000).optional(),
+    role: z.enum(["slides", "design", "assets", "content", "analytics"]),
+    limit: z.number().int().min(1).max(20).optional(),
+    contextPackId: boundedId.optional(),
+    contextPackSource: z.enum(["explicit", "inherited"]).optional(),
+    selectedContextId: boundedId.nullable().optional(),
+  })
+  .strict();
+const validatePayloadSchema = z
+  .object({
+    contextPackId: boundedId.nullable().optional(),
+    contextPackSource: z.enum(["explicit", "inherited"]).optional(),
+    reuseLabels: z.array(reuseLabelSchema).max(100).optional(),
+    reuseLabelsSource: z.enum(["explicit", "inherited"]).optional(),
+  })
+  .strict();
+const readPayloadSchema = z
+  .object({
+    identity: generationIdentitySchema,
+    artifactAccessCapability: artifactAccessCapabilitySchema.optional(),
+  })
+  .strict();
+
+export const creativeContextA2ARequestSchema = z.discriminatedUnion(
+  "operation",
+  [
+    z
+      .object({
+        protocol: z.literal(PROTOCOL),
+        requestId: z.uuid(),
+        operation: z.literal("resolve"),
+        payload: resolvePayloadSchema,
+      })
+      .strict(),
+    z
+      .object({
+        protocol: z.literal(PROTOCOL),
+        requestId: z.uuid(),
+        operation: z.literal("validate"),
+        payload: validatePayloadSchema,
+      })
+      .strict(),
+    z
+      .object({
+        protocol: z.literal(PROTOCOL),
+        requestId: z.uuid(),
+        operation: z.literal("read"),
+        payload: readPayloadSchema,
+      })
+      .strict(),
+    z
+      .object({
+        protocol: z.literal(PROTOCOL),
+        requestId: z.uuid(),
+        operation: z.literal("record"),
+        payload: generationRecordPayloadSchema,
+      })
+      .strict(),
+  ],
+);
+
+export type CreativeContextA2ARequest = z.infer<
+  typeof creativeContextA2ARequestSchema
+>;
+export type CreativeContextA2AOperation =
+  CreativeContextA2ARequest["operation"];
+
+type RemoteResultByOperation = {
+  resolve: z.infer<typeof resolvedContextSchema>;
+  validate: z.infer<typeof resolvedContextSchema>;
+  read: CreativeContextGenerationRecord | null;
+  record: CreativeContextGenerationRecord;
+};
+
+const responseEnvelopeSchema = z
+  .object({
+    protocol: z.literal(PROTOCOL),
+    requestId: z.uuid(),
+    operation: z.enum(["resolve", "validate", "read", "record"]),
+    ok: z.literal(true),
+    result: z.unknown(),
+  })
+  .strict();
+
+export function hasIsolatedCreativeContextA2A(): boolean {
+  return Boolean(process.env.CREATIVE_CONTEXT_A2A_URL?.trim());
+}
+
+export function decodeCreativeContextA2ARequest(
+  requestToken: string,
+): CreativeContextA2ARequest {
+  if (!requestToken || requestToken.length > MAX_TOKEN_LENGTH) {
+    throw new Error("Creative Context A2A request exceeds the protocol limit");
+  }
+  return creativeContextA2ARequestSchema.parse(
+    JSON.parse(Buffer.from(requestToken, "base64url").toString("utf8")),
+  );
+}
+
+export function createCreativeContextA2AResponseToken(
+  request: CreativeContextA2ARequest,
+  result: unknown,
+): string {
+  const response = {
+    protocol: PROTOCOL,
+    requestId: request.requestId,
+    operation: request.operation,
+    ok: true as const,
+    result: normalizeRemoteResult(request.operation, result),
+  };
+  const encoded = Buffer.from(JSON.stringify(response), "utf8").toString(
+    "base64url",
+  );
+  if (encoded.length > MAX_TOKEN_LENGTH) {
+    throw new Error("Creative Context A2A response exceeds the protocol limit");
+  }
+  return `${RESPONSE_PREFIX}:${request.requestId}:${encoded}`;
+}
+
+export async function callIsolatedCreativeContextA2A<
+  TOperation extends CreativeContextA2AOperation,
+>(
+  operation: TOperation,
+  payload: Extract<
+    CreativeContextA2ARequest,
+    { operation: TOperation }
+  >["payload"],
+  options: {
+    callAgent?: typeof import("@agent-native/core/a2a").callAgent;
+  } = {},
+): Promise<RemoteResultByOperation[TOperation]> {
+  const url = parseConfiguredUrl();
+  const userEmail = getRequestUserEmail()?.trim().toLowerCase();
+  if (!userEmail) {
+    throw new Error(
+      "Isolated Creative Context requires an authenticated caller identity",
+    );
+  }
+  const orgSecret = process.env.CREATIVE_CONTEXT_A2A_KEY?.trim();
+  if (!orgSecret && !process.env.A2A_SECRET?.trim()) {
+    throw new Error(
+      "CREATIVE_CONTEXT_A2A_URL requires CREATIVE_CONTEXT_A2A_KEY or A2A_SECRET",
+    );
+  }
+  const request = creativeContextA2ARequestSchema.parse({
+    protocol: PROTOCOL,
+    requestId: crypto.randomUUID(),
+    operation,
+    payload,
+  }) as Extract<CreativeContextA2ARequest, { operation: TOperation }>;
+  const requestToken = Buffer.from(JSON.stringify(request), "utf8").toString(
+    "base64url",
+  );
+  const prompt = [
+    "Creative Context machine protocol request.",
+    "Call the creative-context-a2a action exactly once with this JSON input:",
+    JSON.stringify({ requestToken }),
+    "Return only the responseToken string from that action. Do not summarize or modify it.",
+  ].join("\n");
+  const callAgent =
+    options.callAgent ?? (await import("@agent-native/core/a2a")).callAgent;
+  let responseText: string;
+  try {
+    responseText = await callAgent(url, prompt, {
+      userEmail,
+      orgDomain: emailDomain(userEmail),
+      orgSecret,
+      async: true,
+      timeoutMs: configuredTimeoutMs(),
+      returnRecoverableArtifactsOnTimeout: false,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Isolated Creative Context A2A request failed: ${message}`);
+  }
+  if (responseText.length > MAX_TOKEN_LENGTH + 1_000) {
+    throw new Error(
+      "Isolated Creative Context A2A response exceeds the protocol limit",
+    );
+  }
+  const tokenPattern = new RegExp(
+    `${RESPONSE_PREFIX}:${request.requestId}:([A-Za-z0-9_-]+)`,
+  );
+  const encoded = tokenPattern.exec(responseText)?.[1];
+  if (!encoded) {
+    throw new Error(
+      "Isolated Creative Context returned a malformed protocol response",
+    );
+  }
+  let envelope: z.infer<typeof responseEnvelopeSchema>;
+  try {
+    envelope = responseEnvelopeSchema.parse(
+      JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")),
+    );
+  } catch {
+    throw new Error(
+      "Isolated Creative Context returned a malformed protocol response",
+    );
+  }
+  if (
+    envelope.requestId !== request.requestId ||
+    envelope.operation !== operation
+  ) {
+    throw new Error(
+      "Isolated Creative Context response did not match the request",
+    );
+  }
+  return normalizeRemoteResult(
+    operation,
+    envelope.result,
+  ) as RemoteResultByOperation[TOperation];
+}
+
+function normalizeRemoteResult(
+  operation: CreativeContextA2AOperation,
+  result: unknown,
+): RemoteResultByOperation[CreativeContextA2AOperation] {
+  switch (operation) {
+    case "resolve":
+    case "validate": {
+      const value = result as Record<string, unknown>;
+      const rows = Array.isArray(value?.results) ? value.results : [];
+      return resolvedContextSchema.parse({
+        contextMode: value?.contextMode,
+        contextPackId: value?.contextPackId,
+        reuseLabels: value?.reuseLabels,
+        results: rows.map((entry) => {
+          const row = entry as Record<string, unknown>;
+          return {
+            itemId: row.itemId,
+            itemVersionId: row.itemVersionId,
+            kind: row.kind,
+            title: row.title,
+            excerpt: row.excerpt,
+            dataRole: row.dataRole,
+          };
+        }),
+      });
+    }
+    case "read":
+      return result === null
+        ? null
+        : generationRecordSchema.parse(canonicalGenerationRecord(result));
+    case "record":
+      return generationRecordSchema.parse(canonicalGenerationRecord(result));
+  }
+}
+
+function canonicalGenerationRecord(result: unknown) {
+  const value = result as Record<string, unknown>;
+  return {
+    id: value?.id,
+    appId: value?.appId,
+    artifactType: value?.artifactType,
+    artifactId: value?.artifactId,
+    contextMode: value?.contextMode,
+    contextPackId: value?.contextPackId,
+    elementProvenance: value?.elementProvenance,
+    createdAt: value?.createdAt,
+  };
+}
+
+function parseConfiguredUrl(): string {
+  const value = process.env.CREATIVE_CONTEXT_A2A_URL?.trim();
+  if (!value) throw new Error("CREATIVE_CONTEXT_A2A_URL is not configured");
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("CREATIVE_CONTEXT_A2A_URL must be a valid HTTP(S) URL");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error("CREATIVE_CONTEXT_A2A_URL must be a valid HTTP(S) URL");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+function configuredTimeoutMs(): number {
+  const parsed = Number(process.env.CREATIVE_CONTEXT_A2A_TIMEOUT_MS);
+  if (!Number.isFinite(parsed)) return DEFAULT_TIMEOUT_MS;
+  return Math.max(1_000, Math.min(60_000, Math.floor(parsed)));
+}
+
+function emailDomain(email: string): string | undefined {
+  const domain = email.split("@")[1]?.trim().toLowerCase();
+  return domain || undefined;
+}
+
+export type IsolatedResolvePayload = {
+  query?: string;
+  role: CreativeGenerationRole;
+  limit?: number;
+  contextPackId?: string;
+  contextPackSource?: "explicit" | "inherited";
+  selectedContextId?: string | null;
+};
+
+export function isolatedResolvePayload(
+  input: ResolveGenerationCreativeContextInput,
+): IsolatedResolvePayload {
+  return {
+    query: input.query,
+    role: input.role,
+    limit: input.limit,
+    contextPackId: input.contextPackId,
+    contextPackSource: input.contextPackSource,
+    selectedContextId: input.selectedContextId ?? undefined,
+  };
+}
+
+export type IsolatedRecordPayload = {
+  appId: string;
+  artifactType: string;
+  artifactId: string;
+  contextMode: "off" | "auto" | "pinned";
+  contextPackId: string | null;
+  reuseLabels: CreativeContextReuseLabel[];
+  elementProvenance?: CreativeContextElementProvenance[];
+  artifactAccessCapability?: string;
+};

package/src/server/media.spec.ts

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  handler: null as null | ((event: any) => Promise<Response>),
+  getSession: vi.fn(),
+  runWithRequestContext: vi.fn(async (_context, fn) => fn()),
+  readPrivateArtifact: vi.fn(async () => new Uint8Array([1, 2, 3])),
+  getCreativeContextItem: vi.fn(),
+  readPendingCreativeContextMedia: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/server", () => ({
+  getH3App: vi.fn(() => ({
+    use: vi.fn((_path: string, handler: (event: any) => Promise<Response>) => {
+      mocks.handler = handler;
+    }),
+  })),
+  getSession: mocks.getSession,
+  runWithRequestContext: mocks.runWithRequestContext,
+}));
+
+vi.mock("../connectors/private-artifacts.js", () => ({
+  parsePrivateBlobHandle: vi.fn(() => ({
+    id: "blob-example",
+    provider: "test",
+    opaque: true,
+    encrypted: true,
+    mimeType: "image/png",
+  })),
+  readPrivateArtifact: mocks.readPrivateArtifact,
+}));
+
+vi.mock("../store/index.js", () => ({
+  getCreativeContextItem: mocks.getCreativeContextItem,
+  readPendingCreativeContextMedia: mocks.readPendingCreativeContextMedia,
+}));
+
+vi.mock("./context.js", () => ({
+  getCreativeContext: vi.fn(() => ({ connectorContext: {} })),
+}));
+
+const { createCreativeContextMediaPlugin } = await import("./media.js");
+
+function event() {
+  return {
+    req: {
+      method: "GET",
+      url: "http://app.example/_agent-native/creative-context/media?itemId=item-1&itemVersionId=version-1",
+      headers: new Headers({ origin: "http://app.example" }),
+    },
+  };
+}
+
+describe("creative context media route", () => {
+  beforeEach(async () => {
+    mocks.handler = null;
+    mocks.getSession.mockReset();
+    mocks.runWithRequestContext.mockClear();
+    mocks.getCreativeContextItem.mockReset().mockResolvedValue({
+      item: {
+        id: "item-1",
+        thumbnailBlobRef: "creative-context-blob:v1:example",
+      },
+      version: { id: "version-1" },
+      media: [],
+    });
+    mocks.readPendingCreativeContextMedia.mockReset().mockResolvedValue(null);
+    await createCreativeContextMediaPlugin()({});
+  });
+
+  it("rejects requests without an authenticated session", async () => {
+    mocks.getSession.mockResolvedValue(null);
+    const response = await mocks.handler!(event());
+    expect(response.status).toBe(401);
+    expect(mocks.runWithRequestContext).not.toHaveBeenCalled();
+    expect(mocks.getCreativeContextItem).not.toHaveBeenCalled();
+  });
+
+  it("runs access-scoped reads under the authenticated request context", async () => {
+    mocks.getSession.mockResolvedValue({
+      email: "Alice@Example.test ",
+      orgId: "org-1",
+    });
+    const response = await mocks.handler!(event());
+    expect(response.status).toBe(200);
+    expect(mocks.runWithRequestContext).toHaveBeenCalledWith(
+      { userEmail: "alice@example.test", orgId: "org-1" },
+      expect.any(Function),
+    );
+    expect(mocks.getCreativeContextItem).toHaveBeenCalledWith(
+      "item-1",
+      "version-1",
+    );
+  });
+
+  it("uses the narrow pending-submission path only after generic item access fails", async () => {
+    mocks.getSession.mockResolvedValue({
+      email: "bob@example.test",
+      orgId: "org-1",
+    });
+    mocks.getCreativeContextItem.mockResolvedValue(null);
+    mocks.readPendingCreativeContextMedia.mockResolvedValue({
+      itemId: "item-1",
+      itemVersionId: "version-1",
+      mediaId: null,
+      storageKey: "creative-context-blob:v1:example",
+      mimeType: "image/png",
+    });
+
+    const response = await mocks.handler!(event());
+
+    expect(response.status).toBe(200);
+    expect(mocks.readPendingCreativeContextMedia).toHaveBeenCalledWith({
+      itemId: "item-1",
+      itemVersionId: "version-1",
+      mediaId: undefined,
+    });
+    expect(await response.text()).not.toContain("creative-context-blob");
+  });
+});

package/src/server/media.ts

@@ -0,0 +1,136 @@
+import {
+  getH3App,
+  getSession,
+  runWithRequestContext,
+  type NitroPluginDef,
+} from "@agent-native/core/server";
+import { eq } from "drizzle-orm";
+
+import {
+  parsePrivateBlobHandle,
+  readPrivateArtifact,
+} from "../connectors/private-artifacts.js";
+import { CREATIVE_CONTEXT_MEDIA_ROUTE } from "../media-url.js";
+import {
+  getCreativeContextItem,
+  readPendingCreativeContextMedia,
+} from "../store/index.js";
+import { getCreativeContext } from "./context.js";
+
+const SAFE_MIME_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+  "image/svg+xml",
+  "video/mp4",
+  "video/webm",
+]);
+
+export function createCreativeContextMediaPlugin(): NitroPluginDef {
+  return async (nitroApp: object) => {
+    getH3App(nitroApp).use(CREATIVE_CONTEXT_MEDIA_ROUTE, async (event: any) => {
+      if (event?.req?.method !== "GET") {
+        return new Response("Method not allowed", { status: 405 });
+      }
+      const session = await getSession(event).catch(() => null);
+      const userEmail = session?.email?.trim().toLowerCase();
+      if (!userEmail) {
+        return new Response("Authentication required", { status: 401 });
+      }
+      const orgId = session?.orgId;
+      const url = new URL(
+        event.req.url,
+        event.req.headers?.get?.("origin") ?? "http://localhost",
+      );
+      const mediaId = url.searchParams.get("mediaId");
+      let loaded: Awaited<ReturnType<typeof readCreativeContextMedia>> | null;
+      try {
+        loaded = await runWithRequestContext({ userEmail, orgId }, () =>
+          readCreativeContextMedia({
+            mediaId: mediaId ?? undefined,
+            itemId: url.searchParams.get("itemId") ?? undefined,
+            itemVersionId: url.searchParams.get("itemVersionId") ?? undefined,
+          }),
+        );
+      } catch {
+        loaded = null;
+      }
+      if (!loaded) return new Response("Not found", { status: 404 });
+      const { data, mimeType } = loaded;
+      if (!SAFE_MIME_TYPES.has(mimeType)) {
+        return new Response("Unsupported media type", { status: 415 });
+      }
+      const body = data.buffer.slice(
+        data.byteOffset,
+        data.byteOffset + data.byteLength,
+      ) as ArrayBuffer;
+      return new Response(body, {
+        headers: {
+          "Cache-Control": "private, max-age=300",
+          "Content-Type": mimeType,
+          "Content-Security-Policy":
+            "sandbox; default-src 'none'; style-src 'unsafe-inline'",
+          "X-Content-Type-Options": "nosniff",
+        },
+      });
+    });
+  };
+}
+
+export async function readCreativeContextMedia(input: {
+  mediaId?: string;
+  itemId?: string;
+  itemVersionId?: string;
+}) {
+  let itemId = input.itemId;
+  let itemVersionId = input.itemVersionId;
+  if (input.mediaId) {
+    const { getDb, schema } = getCreativeContext();
+    const rows = await getDb()
+      .select({
+        itemId: schema.contextMedia.itemId,
+        itemVersionId: schema.contextMedia.itemVersionId,
+      })
+      .from(schema.contextMedia)
+      .where(eq(schema.contextMedia.id, input.mediaId))
+      .limit(1);
+    itemId = rows[0]?.itemId;
+    itemVersionId = rows[0]?.itemVersionId;
+  }
+  if (!itemId) throw new Error("Creative context media was not found");
+  const detail = await getCreativeContextItem(itemId, itemVersionId);
+  const pending = detail
+    ? null
+    : await readPendingCreativeContextMedia({
+        mediaId: input.mediaId,
+        itemId,
+        itemVersionId,
+      });
+  if (!detail && !pending)
+    throw new Error("Creative context media is not accessible");
+  const media =
+    detail && input.mediaId
+      ? (detail.media.find((entry) => entry.id === input.mediaId) ?? null)
+      : null;
+  const storageKey = detail
+    ? (media?.storageKey ?? detail.item.thumbnailBlobRef)
+    : pending?.storageKey;
+  const handle = parsePrivateBlobHandle(storageKey);
+  if (!handle) throw new Error("Creative context media has no private blob");
+  return {
+    data: await readPrivateArtifact(
+      handle,
+      getCreativeContext().connectorContext,
+    ),
+    mimeType:
+      media?.mimeType ??
+      (detail ? detail.version.mimeType : pending?.mimeType) ??
+      handle.mimeType ??
+      "application/octet-stream",
+    itemId: detail?.item.id ?? pending!.itemId,
+    itemVersionId: detail?.version.id ?? pending!.itemVersionId,
+    mediaId: media?.id ?? pending?.mediaId ?? null,
+    media,
+  };
+}