@agent-native/creative-context 0.1.0

package/src/connectors/private-artifacts.ts

@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+
+import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
+import {
+  extractDominantColors,
+  fingerprintMedia,
+  readBoundedResponseBytes,
+} from "@agent-native/core/ingestion";
+import {
+  putPrivateBlob as corePutPrivateBlob,
+  readPrivateBlob as coreReadPrivateBlob,
+  type PrivateBlobHandle,
+} from "@agent-native/core/private-blob";
+
+import type { ContextMediaInput } from "../types.js";
+import type { ContextConnectorExecutionContext } from "./types.js";
+
+const PRIVATE_BLOB_REF_PREFIX = "creative-context-blob:v1:";
+const MAX_REMOTE_ARTIFACT_BYTES = 20 * 1024 * 1024;
+
+export async function storePrivateArtifact(input: {
+  data: Uint8Array;
+  filename: string;
+  mimeType?: string;
+  context: ContextConnectorExecutionContext;
+  metadata?: Record<string, string | number | boolean | null | undefined>;
+}): Promise<{
+  handle: PrivateBlobHandle;
+  reference: string;
+  contentHash: string;
+  palette: string[];
+}> {
+  const put = input.context.putPrivateBlob ?? corePutPrivateBlob;
+  const fingerprint = fingerprintMedia(input.data, input.mimeType);
+  const ownerScope = createHash("sha256")
+    .update(
+      JSON.stringify({
+        appId: input.context.appId,
+        ownerEmail: input.context.ownerEmail ?? null,
+      }),
+    )
+    .digest("hex")
+    .slice(0, 24);
+  const handle = await put({
+    data: input.data,
+    key: `creative-context/${ownerScope}/${fingerprint.sha256}`,
+    filename: input.filename,
+    mimeType: input.mimeType,
+    ownerEmail: input.context.ownerEmail,
+    metadata: {
+      ...input.metadata,
+      sha256: fingerprint.sha256,
+      byteLength: fingerprint.byteLength,
+    },
+  });
+  if (!handle) {
+    throw new Error(
+      "Private blob storage is required for creative context artifacts.",
+    );
+  }
+  const palette = input.mimeType?.startsWith("image/")
+    ? await extractDominantColors(input.data).catch(() => [])
+    : [];
+  return {
+    handle,
+    reference: serializePrivateBlobHandle(handle),
+    contentHash: fingerprint.sha256,
+    palette,
+  };
+}
+
+export async function rehostRemoteMedia(input: {
+  url: string;
+  provenanceUrl?: string;
+  filename: string;
+  kind: ContextMediaInput["kind"];
+  mimeType?: string;
+  context: ContextConnectorExecutionContext;
+  metadata?: Record<string, unknown>;
+}): Promise<ContextMediaInput> {
+  const remote = await fetchRemoteArtifact(input.url, input.context);
+  const mimeType = input.mimeType ?? remote.mimeType;
+  const data = sanitizeRemoteArtifact({
+    data: remote.data,
+    mimeType,
+    filename: input.filename,
+  });
+  const stored = await storePrivateArtifact({
+    data,
+    filename: input.filename,
+    mimeType,
+    context: input.context,
+    metadata: { kind: input.kind, source: "creative-context-import" },
+  });
+  return {
+    kind: input.kind,
+    ...(mimeType ? { mimeType } : {}),
+    accessMode: "private",
+    storageKey: stored.reference,
+    provenanceUrl: sanitizeProvenanceUrl(
+      input.provenanceUrl ?? remote.finalUrl,
+    ),
+    contentHash: stored.contentHash,
+    ...(stored.palette.length > 0 ? { palette: stored.palette } : {}),
+    captionStatus: input.kind === "image" ? "pending" : "not-needed",
+    metadata: input.metadata,
+  };
+}
+
+export async function fetchRemoteArtifact(
+  url: string,
+  context: ContextConnectorExecutionContext,
+): Promise<{ data: Uint8Array; mimeType?: string; finalUrl: string }> {
+  const response = await ssrfSafeFetch(
+    url,
+    { signal: context.signal },
+    { maxRedirects: 5 },
+  );
+  if (!response.ok) {
+    throw new Error(`Media fetch failed (${response.status}).`);
+  }
+  return {
+    data: await readBoundedResponseBytes(response, MAX_REMOTE_ARTIFACT_BYTES),
+    mimeType: response.headers.get("content-type") ?? undefined,
+    finalUrl: sanitizeProvenanceUrl(response.url || url),
+  };
+}
+
+export function sanitizeProvenanceUrl(value: string): string {
+  try {
+    const url = new URL(value);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return "redacted-source";
+  }
+}
+
+export function sanitizeRemoteArtifact(input: {
+  data: Uint8Array;
+  mimeType?: string;
+  filename?: string;
+}): Uint8Array {
+  const mimeType = input.mimeType?.split(";")[0]?.trim().toLowerCase();
+  const prefix = new TextDecoder().decode(input.data.slice(0, 512));
+  const isSvg =
+    mimeType === "image/svg+xml" ||
+    ((!mimeType ||
+      mimeType === "application/octet-stream" ||
+      mimeType === "text/xml" ||
+      mimeType === "application/xml") &&
+      input.filename?.toLowerCase().endsWith(".svg") === true) ||
+    /^\s*(?:<\?xml[^>]*>\s*)?<svg\b/i.test(prefix);
+  if (!isSvg) return input.data;
+
+  let source: string;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(input.data);
+  } catch {
+    throw new Error("Remote SVG is not valid UTF-8.");
+  }
+  source = source
+    .replace(/^\uFEFF/, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .trim();
+  if (!/<svg\b/i.test(source)) {
+    throw new Error("Remote SVG is missing an SVG root element.");
+  }
+  const forbidden = [
+    /<\s*(?:script|foreignObject|iframe|object|embed|link|audio|video|animate|set|discard)\b/i,
+    /<!\s*(?:DOCTYPE|ENTITY)\b/i,
+    /<\?xml-stylesheet\b/i,
+    /\son[a-z][a-z0-9:_-]*\s*=/i,
+    /\b(?:javascript|vbscript)\s*:/i,
+    /\b(?:expression|behavior|-moz-binding)\s*\(/i,
+    /@import\b/i,
+  ];
+  if (forbidden.some((pattern) => pattern.test(source))) {
+    throw new Error("Remote SVG contains active content.");
+  }
+  for (const match of source.matchAll(
+    /(?:href|xlink:href)\s*=\s*(["'])(.*?)\1/gi,
+  )) {
+    const target = match[2]?.trim() ?? "";
+    if (
+      target &&
+      !target.startsWith("#") &&
+      !/^data:image\/(?:png|jpeg|gif|webp);base64,/i.test(target)
+    ) {
+      throw new Error("Remote SVG contains an external reference.");
+    }
+  }
+  for (const match of source.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gi)) {
+    const target = match[2]?.trim() ?? "";
+    if (
+      target &&
+      !target.startsWith("#") &&
+      !/^data:image\/(?:png|jpeg|gif|webp);base64,/i.test(target)
+    ) {
+      throw new Error("Remote SVG contains an external reference.");
+    }
+  }
+  return new TextEncoder().encode(source);
+}
+
+export async function readPrivateArtifact(
+  handle: PrivateBlobHandle,
+  context: ContextConnectorExecutionContext,
+): Promise<Uint8Array> {
+  const read = context.readPrivateBlob ?? coreReadPrivateBlob;
+  return (await read(handle)).data;
+}
+
+export function serializePrivateBlobHandle(handle: PrivateBlobHandle): string {
+  return `${PRIVATE_BLOB_REF_PREFIX}${Buffer.from(JSON.stringify(handle), "utf8").toString("base64url")}`;
+}
+
+export function parsePrivateBlobHandle(
+  value: unknown,
+): PrivateBlobHandle | null {
+  if (value && typeof value === "object") {
+    return validateHandle(value as Record<string, unknown>);
+  }
+  if (typeof value !== "string" || !value.startsWith(PRIVATE_BLOB_REF_PREFIX)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(
+      Buffer.from(
+        value.slice(PRIVATE_BLOB_REF_PREFIX.length),
+        "base64url",
+      ).toString("utf8"),
+    ) as Record<string, unknown>;
+    return validateHandle(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function validateHandle(
+  value: Record<string, unknown>,
+): PrivateBlobHandle | null {
+  return typeof value.id === "string" &&
+    typeof value.provider === "string" &&
+    value.opaque === true &&
+    typeof value.encrypted === "boolean"
+    ? (value as unknown as PrivateBlobHandle)
+    : null;
+}

package/src/connectors/provider-response.ts

@@ -0,0 +1,144 @@
+import type {
+  ProviderApiRequestArgs,
+  ProviderApiRuntime,
+} from "@agent-native/core/provider-api";
+
+export class ContextConnectorQuotaError extends Error {
+  readonly provider: string;
+  readonly retryAt: string;
+  readonly retryAfterMs: number;
+
+  constructor(input: {
+    provider: string;
+    retryAt: string;
+    retryAfterMs?: number;
+  }) {
+    super(`Provider quota exhausted; retry after ${input.retryAt}.`);
+    this.name = "ContextConnectorQuotaError";
+    this.provider = input.provider;
+    this.retryAt = input.retryAt;
+    this.retryAfterMs = Math.max(0, input.retryAfterMs ?? 0);
+  }
+}
+
+export function isContextConnectorQuotaError(
+  value: unknown,
+): value is ContextConnectorQuotaError {
+  return value instanceof ContextConnectorQuotaError;
+}
+
+export async function executeConnectorProviderRequest(
+  runtime: Pick<ProviderApiRuntime, "executeRequest"> | undefined,
+  args: ProviderApiRequestArgs,
+): Promise<unknown> {
+  if (!runtime) {
+    throw new Error(
+      `The ${args.provider} connector requires a provider API runtime.`,
+    );
+  }
+  const raw = (await runtime.executeRequest(args)) as Record<string, unknown>;
+  const response = asRecord(raw.response);
+  if (!response) return raw;
+  const quota = asRecord(response.quota);
+  if (quota?.exhausted === true) {
+    throw new ContextConnectorQuotaError({
+      provider: stringValue(quota.providerId) ?? String(args.provider),
+      retryAt:
+        stringValue(quota.retryAt) ??
+        new Date(
+          Date.now() + Number(quota.retryAfterMs ?? 60_000),
+        ).toISOString(),
+      retryAfterMs: Number(quota.retryAfterMs ?? 0),
+    });
+  }
+  if (response.ok !== true) {
+    const status = response.status ?? "unknown";
+    const detail = response.text ?? response.json ?? response.statusText ?? "";
+    throw new Error(
+      `Provider request failed (${String(status)}): ${brief(detail)}`,
+    );
+  }
+  if (response.json !== undefined) return response.json;
+  if (typeof response.text === "string") {
+    try {
+      return JSON.parse(response.text);
+    } catch {
+      return response.text;
+    }
+  }
+  return null;
+}
+
+export async function connectorConnectionId(
+  provider: string,
+  config: Record<string, unknown>,
+  resolve?: (
+    provider: string,
+    requestedConnectionId?: string,
+  ) => Promise<string | undefined>,
+): Promise<string | undefined> {
+  const requested = stringValue(config.connectionId);
+  const credentialMode = stringValue(config.credentialMode);
+  if (credentialMode === "admin-token" || config.useAdminToken === true) {
+    if (provider !== "figma") {
+      throw new Error(
+        `${provider} creative-context imports require a per-user granted workspace connection; admin-token mode is not allowed.`,
+      );
+    }
+    if (requested) {
+      throw new Error(
+        `${provider} connector config cannot combine connectionId with admin-token credentialMode.`,
+      );
+    }
+    return undefined;
+  }
+  if (!resolve) {
+    throw new Error(
+      `${provider} creative-context imports require a workspace connection resolver.`,
+    );
+  }
+  const resolved = await resolve(provider, requested);
+  if (!resolved) {
+    throw new Error(
+      `${provider} creative-context imports require a granted workspace connection.`,
+    );
+  }
+  return resolved;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+export function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.map(stringValue).filter((item): item is string => Boolean(item))
+    : [];
+}
+
+export function positiveLimit(
+  value: unknown,
+  fallback = 100,
+  max = 1_000,
+): number {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0
+    ? Math.min(parsed, max)
+    : fallback;
+}
+
+export function cursorOffset(cursor: string | null | undefined): number {
+  const parsed = Number(cursor ?? 0);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+}
+
+function brief(value: unknown): string {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return (text ?? "").slice(0, 500);
+}

package/src/connectors/recommendations.ts

@@ -0,0 +1,237 @@
+import {
+  asRecord,
+  connectorConnectionId,
+  executeConnectorProviderRequest,
+  positiveLimit,
+  stringValue,
+} from "./provider-response.js";
+import type { ContextConnectorExecutionContext } from "./types.js";
+
+export type ContextRootRecommendationProvider =
+  | "notion"
+  | "google-slides"
+  | "figma";
+
+export interface ContextRootRecommendation {
+  externalId: string;
+  provider: ContextRootRecommendationProvider;
+  kind: "page" | "presentation" | "file";
+  title: string;
+  canonicalUrl?: string;
+  sourceModifiedAt?: string;
+  containerRef?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export async function recommendContextRoots(
+  input: {
+    provider: ContextRootRecommendationProvider;
+    connectionId?: string;
+    limit?: number;
+    figmaProjectId?: string;
+    figmaTeamId?: string;
+  },
+  context: ContextConnectorExecutionContext,
+): Promise<{
+  recommendations: ContextRootRecommendation[];
+  persisted: false;
+  requiresExplicitBoundary: true;
+  unavailableReason?: string;
+}> {
+  const limit = positiveLimit(input.limit, 15, 50);
+  const config = input.connectionId ? { connectionId: input.connectionId } : {};
+  if (input.provider === "notion") {
+    const connectionId = await connectorConnectionId(
+      "notion",
+      config,
+      context.resolveConnection,
+    );
+    const payload = asRecord(
+      await executeConnectorProviderRequest(context.providerApi, {
+        provider: "notion",
+        method: "POST",
+        path: "/search",
+        body: {
+          filter: { property: "object", value: "page" },
+          sort: { direction: "descending", timestamp: "last_edited_time" },
+          page_size: limit,
+        },
+        connectionId,
+      }),
+    );
+    const recommendations = (
+      Array.isArray(payload?.results) ? payload.results : []
+    ).flatMap((value) => {
+      const page = asRecord(value);
+      const id = stringValue(page?.id);
+      if (!id) return [];
+      return [
+        {
+          externalId: id,
+          provider: "notion" as const,
+          kind: "page" as const,
+          title: page
+            ? (notionRecommendationTitle(page) ?? "Notion page")
+            : "Notion page",
+          ...(stringValue(page?.url)
+            ? { canonicalUrl: stringValue(page?.url) }
+            : {}),
+          ...(stringValue(page?.last_edited_time)
+            ? { sourceModifiedAt: stringValue(page?.last_edited_time) }
+            : {}),
+          metadata: { recommendationOnly: true },
+        },
+      ];
+    });
+    return recommendationResult(recommendations.slice(0, limit));
+  }
+
+  if (input.provider === "google-slides") {
+    const connectionId = await connectorConnectionId(
+      "google_drive",
+      config,
+      context.resolveConnection,
+    );
+    const payload = asRecord(
+      await executeConnectorProviderRequest(context.providerApi, {
+        provider: "google_drive",
+        method: "GET",
+        path: "/files",
+        query: {
+          q: "mimeType = 'application/vnd.google-apps.presentation' and trashed = false",
+          pageSize: limit,
+          orderBy: "modifiedTime desc",
+          fields:
+            "files(id,name,modifiedTime,webViewLink,parents,driveId,shared,ownedByMe)",
+        },
+        connectionId,
+      }),
+    );
+    const recommendations = (
+      Array.isArray(payload?.files) ? payload.files : []
+    ).flatMap((value) => {
+      const file = asRecord(value);
+      const id = stringValue(file?.id);
+      if (!id) return [];
+      return [
+        {
+          externalId: id,
+          provider: "google-slides" as const,
+          kind: "presentation" as const,
+          title: stringValue(file?.name) ?? id,
+          canonicalUrl:
+            stringValue(file?.webViewLink) ??
+            `https://docs.google.com/presentation/d/${encodeURIComponent(id)}/edit`,
+          ...(stringValue(file?.modifiedTime)
+            ? { sourceModifiedAt: stringValue(file?.modifiedTime) }
+            : {}),
+          ...(stringValue(file?.driveId)
+            ? { containerRef: `shared-drive:${stringValue(file?.driveId)}` }
+            : {}),
+          metadata: {
+            recommendationOnly: true,
+            shared: file?.shared === true,
+            ownedByMe: file?.ownedByMe === true,
+            ...(Array.isArray(file?.parents) ? { parents: file.parents } : {}),
+          },
+        },
+      ];
+    });
+    return recommendationResult(recommendations.slice(0, limit));
+  }
+
+  const connectionId = await connectorConnectionId(
+    "figma",
+    config,
+    context.resolveConnection,
+  );
+  const projectIds = new Set<string>();
+  if (input.figmaProjectId?.trim()) projectIds.add(input.figmaProjectId.trim());
+  if (input.figmaTeamId?.trim()) {
+    const projects = asRecord(
+      await executeConnectorProviderRequest(context.providerApi, {
+        provider: "figma",
+        method: "GET",
+        path: `/teams/${encodeURIComponent(input.figmaTeamId.trim())}/projects`,
+        connectionId,
+      }),
+    );
+    for (const value of Array.isArray(projects?.projects)
+      ? projects.projects
+      : []) {
+      const id = stringValue(asRecord(value)?.id);
+      if (id) projectIds.add(id);
+    }
+  }
+  if (projectIds.size === 0) {
+    return {
+      ...recommendationResult([]),
+      unavailableReason:
+        "Figma has no global recent-files API. Choose a team or project before requesting file recommendations.",
+    };
+  }
+  const recommendations: ContextRootRecommendation[] = [];
+  for (const projectId of projectIds) {
+    if (recommendations.length >= limit) break;
+    const payload = asRecord(
+      await executeConnectorProviderRequest(context.providerApi, {
+        provider: "figma",
+        method: "GET",
+        path: `/projects/${encodeURIComponent(projectId)}/files`,
+        connectionId,
+      }),
+    );
+    for (const value of Array.isArray(payload?.files) ? payload.files : []) {
+      const file = asRecord(value);
+      const key = stringValue(file?.key);
+      if (!key) continue;
+      recommendations.push({
+        externalId: key,
+        provider: "figma",
+        kind: "file",
+        title: stringValue(file?.name) ?? key,
+        canonicalUrl: `https://www.figma.com/design/${encodeURIComponent(key)}`,
+        ...(stringValue(file?.last_modified)
+          ? { sourceModifiedAt: stringValue(file?.last_modified) }
+          : {}),
+        containerRef: `project:${projectId}`,
+        metadata: { recommendationOnly: true, projectId },
+      });
+      if (recommendations.length >= limit) break;
+    }
+  }
+  recommendations.sort(
+    (left, right) =>
+      timestamp(right.sourceModifiedAt) - timestamp(left.sourceModifiedAt),
+  );
+  return recommendationResult(recommendations.slice(0, limit));
+}
+
+function recommendationResult(recommendations: ContextRootRecommendation[]) {
+  return {
+    recommendations,
+    persisted: false as const,
+    requiresExplicitBoundary: true as const,
+  };
+}
+
+function notionRecommendationTitle(
+  page: Record<string, unknown>,
+): string | undefined {
+  const properties = asRecord(page.properties);
+  for (const value of Object.values(properties ?? {})) {
+    const property = asRecord(value);
+    if (!Array.isArray(property?.title)) continue;
+    const title = property.title
+      .map((entry) => stringValue(asRecord(entry)?.plain_text) ?? "")
+      .join("")
+      .trim();
+    if (title) return title;
+  }
+  return undefined;
+}
+
+function timestamp(value: string | undefined): number {
+  const parsed = value ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : 0;
+}

package/src/connectors/registry.ts

@@ -0,0 +1,48 @@
+import type {
+  ContextImportConnector,
+  ContextImportConnectorSummary,
+  ContextConnectorKind,
+} from "./types.js";
+
+export class ContextImportConnectorRegistry {
+  readonly #connectors = new Map<
+    ContextConnectorKind,
+    ContextImportConnector
+  >();
+
+  constructor(connectors: readonly ContextImportConnector[] = []) {
+    for (const connector of connectors) this.register(connector);
+  }
+
+  register(connector: ContextImportConnector): this {
+    if (this.#connectors.has(connector.kind)) {
+      throw new Error(
+        `Context connector ${connector.kind} is already registered.`,
+      );
+    }
+    this.#connectors.set(connector.kind, connector);
+    return this;
+  }
+
+  get(kind: string): ContextImportConnector {
+    const connector = this.#connectors.get(kind as ContextConnectorKind);
+    if (!connector) {
+      throw new Error(`Unknown context connector ${kind}.`);
+    }
+    return connector;
+  }
+
+  has(kind: string): boolean {
+    return this.#connectors.has(kind as ContextConnectorKind);
+  }
+
+  list(): ContextImportConnectorSummary[] {
+    return [...this.#connectors.values()]
+      .map((connector) => ({
+        kind: connector.kind,
+        label: connector.label,
+        supportsIncremental: connector.supportsIncremental,
+      }))
+      .sort((a, b) => a.label.localeCompare(b.label));
+  }
+}