@agent-native/creative-context 0.1.0

package/src/connectors/index.ts

@@ -0,0 +1,103 @@
+import { FigmaContextConnector } from "./figma.js";
+import { GoogleSlidesContextConnector } from "./google-slides.js";
+import { ManualContextConnector } from "./manual.js";
+import { NotionContextConnector } from "./notion.js";
+import { ContextImportConnectorRegistry } from "./registry.js";
+import { UploadContextConnector } from "./upload.js";
+import { WebsiteContextConnector } from "./website.js";
+
+const DEFAULT_CONNECTORS = [
+  new ManualContextConnector(),
+  new UploadContextConnector(),
+  new GoogleSlidesContextConnector(),
+  new FigmaContextConnector(),
+  new NotionContextConnector(),
+  new WebsiteContextConnector(),
+] as const;
+
+const defaultCreativeContextConnectorRegistry =
+  new ContextImportConnectorRegistry();
+
+export function registerDefaultCreativeContextConnectors(
+  registry = defaultCreativeContextConnectorRegistry,
+): ContextImportConnectorRegistry {
+  for (const connector of DEFAULT_CONNECTORS) {
+    if (!registry.has(connector.kind)) registry.register(connector);
+  }
+  return registry;
+}
+
+export function getCreativeContextConnectorRegistry(): ContextImportConnectorRegistry {
+  return registerDefaultCreativeContextConnectors();
+}
+
+export function createDefaultContextImportConnectorRegistry(): ContextImportConnectorRegistry {
+  return registerDefaultCreativeContextConnectors(
+    new ContextImportConnectorRegistry(),
+  );
+}
+
+export {
+  createDefaultContextConnectorExecutionContext,
+  createWorkspaceConnectionResolver,
+  type CreateContextConnectorExecutionContextOptions,
+} from "./context.js";
+export { FigmaContextConnector, figmaRecommendedFileKeys } from "./figma.js";
+export {
+  fetchFigmaNativeContextItems,
+  MAX_INLINE_NATIVE_CODE_BYTES,
+  nativeFidelityReportFromEntries,
+} from "./figma-native.js";
+export {
+  GOOGLE_SLIDES_CONTEXT_OAUTH_SCOPES,
+  GoogleSlidesContextConnector,
+  googleSlidesRecommendedPresentationIds,
+} from "./google-slides.js";
+export {
+  compileGoogleSlidesPresentation,
+  type CompiledGoogleSlide,
+  type CompiledGoogleSlideChild,
+  type GoogleSlidesNativeCompileOptions,
+  type SlidesNativeAssetRequest,
+  type SlidesNativeBounds,
+  type SlidesNativeFallbackRequest,
+} from "./google-slides-native.js";
+export { ManualContextConnector } from "./manual.js";
+export {
+  NotionContextConnector,
+  notionRecommendedRootPageIds,
+} from "./notion.js";
+export {
+  parseUploadedDocument,
+  type ParseDocumentInput,
+  type ParsedDocument,
+} from "./document-parser.js";
+export { ContextImportConnectorRegistry } from "./registry.js";
+export {
+  LayeredRenderedPageProvider,
+  type LayeredRenderedPageProviderOptions,
+  type RenderedPageMethod,
+  type RenderedPageProvider,
+  type RenderedPageRequest,
+  type RenderedPageResult,
+} from "./rendered-page.js";
+export {
+  recommendContextRoots,
+  type ContextRootRecommendation,
+  type ContextRootRecommendationProvider,
+} from "./recommendations.js";
+export { smartDefaultExternalIds } from "./smart-defaults.js";
+export { UploadContextConnector } from "./upload.js";
+export { WebsiteContextConnector } from "./website.js";
+export type {
+  ContextConnectorExecutionContext,
+  ContextConnectorFetchRequest,
+  ContextConnectorFetchResult,
+  ContextConnectorInventoryItem,
+  ContextConnectorInventoryPage,
+  ContextConnectorInventoryRequest,
+  ContextConnectorKind,
+  ContextImportConnector,
+  ContextImportConnectorSummary,
+  ContextUploadContent,
+} from "./types.js";

package/src/connectors/manual.ts

@@ -0,0 +1,132 @@
+import { normalizeContextItem } from "./normalize.js";
+import {
+  asRecord,
+  cursorOffset,
+  positiveLimit,
+  stringValue,
+} from "./provider-response.js";
+import type {
+  ContextConnectorExecutionContext,
+  ContextConnectorFetchRequest,
+  ContextConnectorFetchResult,
+  ContextConnectorInventoryItem,
+  ContextConnectorInventoryPage,
+  ContextConnectorInventoryRequest,
+  ContextImportConnector,
+} from "./types.js";
+
+interface ManualEntry {
+  id: string;
+  title: string;
+  text: string;
+  kind: string;
+  canonicalUrl?: string;
+  mimeType?: string;
+  sourceModifiedAt?: string;
+  summary?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export class ManualContextConnector implements ContextImportConnector {
+  readonly kind = "manual" as const;
+  readonly label = "Manual text";
+  readonly supportsIncremental = false;
+
+  async inventory(
+    request: ContextConnectorInventoryRequest,
+    _context: ContextConnectorExecutionContext,
+  ): Promise<ContextConnectorInventoryPage> {
+    const entries = parseManualEntries(request.config);
+    const offset = cursorOffset(request.cursor);
+    const limit = positiveLimit(request.limit, 100, 1_000);
+    const slice = entries.slice(offset, offset + limit);
+    const nextOffset = offset + slice.length;
+    return {
+      items: slice.map((entry, index) => ({
+        externalId: entry.id,
+        kind: entry.kind,
+        title: entry.title,
+        ...(entry.canonicalUrl ? { canonicalUrl: entry.canonicalUrl } : {}),
+        ...(entry.mimeType ? { mimeType: entry.mimeType } : {}),
+        ...(entry.sourceModifiedAt
+          ? { sourceModifiedAt: entry.sourceModifiedAt }
+          : {}),
+        metadata: { entryIndex: offset + index },
+      })),
+      nextCursor: nextOffset < entries.length ? String(nextOffset) : null,
+      complete: nextOffset >= entries.length,
+      coverage: {
+        inspected: slice.length,
+        returned: slice.length,
+        truncated: nextOffset < entries.length,
+      },
+    };
+  }
+
+  async fetch(
+    request: ContextConnectorFetchRequest,
+    _context: ContextConnectorExecutionContext,
+  ): Promise<ContextConnectorFetchResult> {
+    const entry = findManualEntry(request.config, request.item);
+    return {
+      items: [
+        normalizeContextItem({
+          externalId: entry.id,
+          kind: entry.kind,
+          title: entry.title,
+          content: entry.text,
+          canonicalUrl: entry.canonicalUrl,
+          mimeType: entry.mimeType,
+          summary: entry.summary,
+          sourceModifiedAt: entry.sourceModifiedAt,
+          metadata: entry.metadata,
+        }),
+      ],
+    };
+  }
+}
+
+function parseManualEntries(config: Record<string, unknown>): ManualEntry[] {
+  if (!Array.isArray(config.items)) {
+    throw new Error("Manual connector config.items must be an array.");
+  }
+  return config.items.map((value, index) => {
+    const item = asRecord(value);
+    const id = stringValue(item?.id) ?? `manual-${index + 1}`;
+    const title = stringValue(item?.title) ?? `Manual context ${index + 1}`;
+    const text = stringValue(item?.text);
+    if (!text) throw new Error(`Manual context ${id} requires text.`);
+    if (text.length > 250_000) {
+      throw new Error(
+        `Manual context ${id} is too large for inline text; use the upload connector.`,
+      );
+    }
+    return {
+      id,
+      title,
+      text,
+      kind: stringValue(item?.kind) ?? "manual-document",
+      canonicalUrl: stringValue(item?.canonicalUrl),
+      mimeType: stringValue(item?.mimeType) ?? "text/plain",
+      sourceModifiedAt: stringValue(item?.sourceModifiedAt),
+      summary: stringValue(item?.summary),
+      metadata: asRecord(item?.metadata) ?? undefined,
+    };
+  });
+}
+
+function findManualEntry(
+  config: Record<string, unknown>,
+  inventoryItem: ContextConnectorInventoryItem,
+): ManualEntry {
+  const entries = parseManualEntries(config);
+  const index = Number(inventoryItem.metadata?.entryIndex);
+  const byIndex = Number.isInteger(index) ? entries[index] : undefined;
+  const entry =
+    byIndex?.id === inventoryItem.externalId
+      ? byIndex
+      : entries.find((candidate) => candidate.id === inventoryItem.externalId);
+  if (!entry)
+    throw new Error(`Manual context ${inventoryItem.externalId} not found.`);
+  return entry;
+}

package/src/connectors/normalize.ts

@@ -0,0 +1,277 @@
+import { createHash } from "node:crypto";
+
+import type {
+  ContextCurationRank,
+  ContextCurationStatus,
+  ContextEdgeInput,
+  ContextMediaInput,
+  NormalizedContextChunk,
+  NormalizedContextItem,
+  UpstreamAccess,
+} from "../types.js";
+
+const DEFAULT_CHUNK_CHARS = 4_000;
+
+export interface NormalizeContextItemInput {
+  externalId: string;
+  kind: string;
+  title: string;
+  content: string;
+  preserveContent?: boolean;
+  canonicalUrl?: string;
+  mimeType?: string;
+  summary?: string;
+  sourceModifiedAt?: string;
+  sourceVersion?: string;
+  rawSnapshotBlobRef?: string;
+  parseStatus?: "pending" | "parsed" | "failed";
+  parseError?: string;
+  upstreamAccess?: UpstreamAccess;
+  curationStatus?: ContextCurationStatus;
+  curationRank?: ContextCurationRank;
+  thumbnailBlobRef?: string;
+  provenance?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  chunks?: NormalizedContextChunk[];
+  media?: ContextMediaInput[];
+  edges?: ContextEdgeInput[];
+}
+
+export function normalizeContextItem(
+  input: NormalizeContextItemInput,
+): NormalizedContextItem {
+  const externalId = required(input.externalId, "externalId");
+  const title = required(input.title, "title");
+  const nativeArtifact =
+    input.metadata &&
+    typeof input.metadata === "object" &&
+    !Array.isArray(input.metadata) &&
+    input.metadata.nativeArtifact &&
+    typeof input.metadata.nativeArtifact === "object" &&
+    !Array.isArray(input.metadata.nativeArtifact)
+      ? (input.metadata.nativeArtifact as Record<string, unknown>)
+      : null;
+  const preserveContent =
+    input.preserveContent === true ||
+    (input.mimeType === "text/html" &&
+      (nativeArtifact?.format === "slides-html" ||
+        nativeArtifact?.format === "design-html"));
+  const content = preserveContent
+    ? input.content.replace(/\r\n?/g, "\n").trim()
+    : normalizeWhitespace(input.content);
+  const summary = input.summary
+    ? normalizeWhitespace(input.summary)
+    : undefined;
+  const chunks = input.chunks ?? chunkContextText(content);
+  const normalized = {
+    externalId,
+    kind: required(input.kind, "kind"),
+    title,
+    ...(input.canonicalUrl ? { canonicalUrl: input.canonicalUrl } : {}),
+    ...(input.mimeType ? { mimeType: input.mimeType } : {}),
+    content,
+    ...(summary ? { summary } : {}),
+    ...(input.sourceModifiedAt
+      ? { sourceModifiedAt: input.sourceModifiedAt }
+      : {}),
+    ...(input.sourceVersion ? { sourceVersion: input.sourceVersion } : {}),
+    ...(input.rawSnapshotBlobRef
+      ? { rawSnapshotBlobRef: input.rawSnapshotBlobRef }
+      : {}),
+    ...(input.parseStatus ? { parseStatus: input.parseStatus } : {}),
+    ...(input.parseError ? { parseError: input.parseError } : {}),
+    ...(input.upstreamAccess ? { upstreamAccess: input.upstreamAccess } : {}),
+    ...(input.curationStatus ? { curationStatus: input.curationStatus } : {}),
+    ...(input.curationRank ? { curationRank: input.curationRank } : {}),
+    ...(input.thumbnailBlobRef
+      ? { thumbnailBlobRef: input.thumbnailBlobRef }
+      : {}),
+    ...(input.provenance ? { provenance: input.provenance } : {}),
+    ...(input.metadata ? { metadata: input.metadata } : {}),
+    ...(chunks.length > 0 ? { chunks } : {}),
+    ...(input.media?.length ? { media: input.media } : {}),
+    ...(input.edges?.length ? { edges: input.edges } : {}),
+  };
+  return {
+    ...normalized,
+    contentHash: hashContextVersion(normalized),
+  };
+}
+
+export function hashContextContent(value: unknown): string {
+  return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+export function hashContextVersion(
+  item: Omit<NormalizedContextItem, "contentHash">,
+): string {
+  return hashContextContent({
+    externalId: item.externalId,
+    kind: item.kind,
+    title: item.title,
+    content: item.content,
+    summary: item.summary ?? null,
+    mimeType: item.mimeType ?? null,
+    sourceVersion: item.sourceVersion ?? null,
+    rawSnapshotBlobRef: item.rawSnapshotBlobRef ?? null,
+    parseStatus: item.parseStatus ?? "parsed",
+    parseError: item.parseError ?? null,
+    metadata: withoutVolatileCaptureMetadata(item.metadata ?? {}),
+    chunks: canonicalUnordered(item.chunks ?? [], (chunk) => ({
+      ordinal: chunk.ordinal,
+      kind: chunk.kind ?? "text",
+      text: chunk.text,
+      startOffset: chunk.startOffset ?? null,
+      endOffset: chunk.endOffset ?? null,
+      tokenCount: chunk.tokenCount ?? null,
+      metadata: chunk.metadata ?? {},
+    })),
+    media: canonicalUnordered(item.media ?? [], (entry) => ({
+      id: entry.id ?? null,
+      kind: entry.kind,
+      mimeType: entry.mimeType ?? null,
+      accessMode: entry.accessMode ?? "public",
+      url: entry.url ?? null,
+      storageKey: entry.storageKey ?? null,
+      provenanceUrl: entry.provenanceUrl ?? null,
+      altText: entry.altText ?? null,
+      caption: entry.caption ?? null,
+      captionStatus: entry.captionStatus ?? "pending",
+      ocrText: entry.ocrText ?? null,
+      palette: entry.palette ?? [],
+      contentHash: entry.contentHash ?? null,
+      width: entry.width ?? null,
+      height: entry.height ?? null,
+      durationMs: entry.durationMs ?? null,
+      metadata: entry.metadata ?? {},
+    })),
+    edges: canonicalUnordered(item.edges ?? [], (edge) => ({
+      id: edge.id ?? null,
+      relation: edge.relation,
+      toItemId: edge.toItemId ?? null,
+      toItemVersionId: edge.toItemVersionId ?? null,
+      toExternalId: edge.toExternalId ?? null,
+      metadata: edge.metadata ?? {},
+    })),
+  });
+}
+
+export function chunkContextText(
+  input: string,
+  maxChars = DEFAULT_CHUNK_CHARS,
+): NormalizedContextChunk[] {
+  const text = normalizeWhitespace(input);
+  if (!text) return [];
+  const chunks: NormalizedContextChunk[] = [];
+  let start = 0;
+  while (start < text.length) {
+    let end = Math.min(text.length, start + maxChars);
+    if (end < text.length) {
+      const boundary = Math.max(
+        text.lastIndexOf("\n\n", end),
+        text.lastIndexOf(". ", end),
+      );
+      if (boundary > start + Math.floor(maxChars / 2)) {
+        end = boundary + (text.startsWith("\n\n", boundary) ? 2 : 1);
+      }
+    }
+    const chunk = text.slice(start, end).trim();
+    if (chunk) {
+      chunks.push({
+        ordinal: chunks.length,
+        kind: "text",
+        text: chunk,
+        startOffset: start,
+        endOffset: end,
+      });
+    }
+    start = end;
+  }
+  return chunks;
+}
+
+export function collectProviderText(
+  value: unknown,
+  options: { skipKeys?: readonly string[]; maxChars?: number } = {},
+): string {
+  const skip = new Set([
+    "id",
+    "url",
+    "href",
+    "etag",
+    "thumbnailUrl",
+    ...(options.skipKeys ?? []),
+  ]);
+  const values: string[] = [];
+  const maxChars = options.maxChars ?? 2_000_000;
+  const visit = (current: unknown, key?: string): void => {
+    if (values.join("\n").length >= maxChars || skip.has(key ?? "")) return;
+    if (typeof current === "string") {
+      const normalized = normalizeWhitespace(current);
+      if (normalized && !looksLikeOpaqueId(normalized)) values.push(normalized);
+      return;
+    }
+    if (Array.isArray(current)) {
+      for (const item of current) visit(item);
+      return;
+    }
+    if (!current || typeof current !== "object") return;
+    for (const [childKey, child] of Object.entries(current)) {
+      visit(child, childKey);
+    }
+  };
+  visit(value);
+  return normalizeWhitespace(values.join("\n")).slice(0, maxChars);
+}
+
+export function normalizeWhitespace(value: string): string {
+  return value
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\t\f\v ]+/g, " ")
+    .replace(/ *\n */g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+function canonicalUnordered<T, U>(
+  values: readonly T[],
+  canonicalize: (value: T) => U,
+): U[] {
+  return values
+    .map(canonicalize)
+    .sort((left, right) =>
+      stableJson(left) < stableJson(right)
+        ? -1
+        : stableJson(left) > stableJson(right)
+          ? 1
+          : 0,
+    );
+}
+
+function withoutVolatileCaptureMetadata(
+  metadata: Record<string, unknown>,
+): Record<string, unknown> {
+  const { capturedAt: _capturedAt, ...stableMetadata } = metadata;
+  return stableMetadata;
+}
+
+function required(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`${label} is required.`);
+  return normalized;
+}
+
+function looksLikeOpaqueId(value: string): boolean {
+  return value.length > 30 && /^[A-Za-z0-9_-]+$/.test(value);
+}