@agent-native/creative-context 0.1.0

package/src/connectors/smart-defaults.spec.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { recommendContextRoots } from "./recommendations.js";
+import { smartDefaultExternalIds } from "./smart-defaults.js";
+import type { ContextConnectorInventoryItem } from "./types.js";
+
+describe("creative context smart defaults", () => {
+  it("ranks shared recent Slides decks and excludes drafts and tiny decks", () => {
+    const items: ContextConnectorInventoryItem[] = [
+      item("personal", "Personal launch", "2026-07-15T00:00:00.000Z"),
+      item("shared", "Shared launch", "2026-07-14T00:00:00.000Z", {
+        accessSignals: { shared: true, driveId: "drive-1" },
+        slideCount: 8,
+      }),
+      item("copy", "Copy of Launch", "2026-07-16T00:00:00.000Z"),
+      item("test", "Launch TEST deck", "2026-07-16T00:00:00.000Z"),
+      item("tiny", "Tiny deck", "2026-07-16T00:00:00.000Z", {
+        slideCount: 2,
+      }),
+      item("old", "Old deck", "2024-01-01T00:00:00.000Z"),
+    ];
+
+    expect(
+      smartDefaultExternalIds({
+        kind: "google-slides",
+        items,
+        now: new Date("2026-07-16T00:00:00.000Z"),
+      }),
+    ).toEqual(["shared", "personal"]);
+  });
+
+  it("lets canonical and pinned decks override viability filters and caps at 15", () => {
+    const items = Array.from({ length: 20 }, (_, index) =>
+      item(
+        `deck-${index}`,
+        index === 19 ? "Copy of canonical" : `Deck ${index}`,
+        `2026-07-${String((index % 15) + 1).padStart(2, "0")}T00:00:00.000Z`,
+      ),
+    );
+    const selected = smartDefaultExternalIds({
+      kind: "google-slides",
+      items,
+      canonicalExternalIds: ["deck-19"],
+      now: new Date("2026-07-16T00:00:00.000Z"),
+    });
+
+    expect(selected).toHaveLength(15);
+    expect(selected[0]).toBe("deck-19");
+  });
+
+  it("keeps explicit-boundary connectors fully selected for confirmation", () => {
+    expect(
+      smartDefaultExternalIds({
+        kind: "notion",
+        items: [item("page", "Page", "2026-07-16T00:00:00.000Z")],
+      }),
+    ).toEqual(["page"]);
+  });
+});
+
+describe("provider-backed root recommendations", () => {
+  it("uses Notion search without persisting or treating results as a boundary", async () => {
+    const executeRequest = vi.fn(async () => ({
+      results: [
+        {
+          id: "page-1",
+          url: "https://notion.so/page-1",
+          last_edited_time: "2026-07-15T00:00:00.000Z",
+          properties: {
+            Name: { title: [{ plain_text: "Brand home" }] },
+          },
+        },
+      ],
+    }));
+    const result = await recommendContextRoots(
+      { provider: "notion", connectionId: "conn-1" },
+      {
+        appId: "slides",
+        providerApi: { executeRequest },
+        resolveConnection: vi.fn(async () => "conn-1"),
+      },
+    );
+
+    expect(executeRequest).toHaveBeenCalledWith(
+      expect.objectContaining({
+        provider: "notion",
+        method: "POST",
+        path: "/search",
+        connectionId: "conn-1",
+      }),
+    );
+    expect(result).toMatchObject({
+      persisted: false,
+      requiresExplicitBoundary: true,
+      recommendations: [
+        expect.objectContaining({
+          externalId: "page-1",
+          title: "Brand home",
+          metadata: { recommendationOnly: true },
+        }),
+      ],
+    });
+  });
+
+  it("explains why Figma recommendations need an explicit team or project", async () => {
+    const executeRequest = vi.fn();
+    const result = await recommendContextRoots(
+      { provider: "figma", connectionId: "conn-1" },
+      {
+        appId: "design",
+        providerApi: { executeRequest },
+        resolveConnection: vi.fn(async () => "conn-1"),
+      },
+    );
+
+    expect(result.recommendations).toEqual([]);
+    expect(result.unavailableReason).toMatch(/no global recent-files API/i);
+    expect(executeRequest).not.toHaveBeenCalled();
+  });
+});
+
+function item(
+  externalId: string,
+  title: string,
+  sourceModifiedAt: string,
+  metadata?: Record<string, unknown>,
+): ContextConnectorInventoryItem {
+  return {
+    externalId,
+    kind: "google-slides-presentation",
+    title,
+    sourceModifiedAt,
+    metadata,
+  };
+}

package/src/connectors/smart-defaults.ts

@@ -0,0 +1,87 @@
+import type {
+  ContextConnectorInventoryItem,
+  ContextConnectorKind,
+} from "./types.js";
+
+const GOOGLE_SLIDES_DEFAULT_LIMIT = 15;
+const RECENT_WINDOW_MONTHS = 12;
+
+export function smartDefaultExternalIds(input: {
+  kind: ContextConnectorKind | string;
+  items: ContextConnectorInventoryItem[];
+  canonicalExternalIds?: string[];
+  pinnedExternalIds?: string[];
+  now?: Date;
+}): string[] {
+  if (input.kind !== "google-slides") {
+    return input.items.map((item) => item.externalId);
+  }
+  const overrideIds = new Set([
+    ...(input.canonicalExternalIds ?? []),
+    ...(input.pinnedExternalIds ?? []),
+  ]);
+  const cutoff = new Date(input.now ?? new Date());
+  cutoff.setUTCMonth(cutoff.getUTCMonth() - RECENT_WINDOW_MONTHS);
+  return [...input.items]
+    .filter((item) => {
+      if (overrideIds.has(item.externalId)) return true;
+      if (isDraftLikeTitle(item.title)) return false;
+      const slideCount = knownSlideCount(item.metadata);
+      if (slideCount !== null && slideCount < 3) return false;
+      const modifiedAt = item.sourceModifiedAt
+        ? Date.parse(item.sourceModifiedAt)
+        : Number.NaN;
+      return Number.isFinite(modifiedAt) && modifiedAt >= cutoff.getTime();
+    })
+    .sort((left, right) => {
+      const leftOverride = overrideIds.has(left.externalId) ? 1 : 0;
+      const rightOverride = overrideIds.has(right.externalId) ? 1 : 0;
+      if (leftOverride !== rightOverride) return rightOverride - leftOverride;
+      const leftShared = isSharedContainerItem(left) ? 1 : 0;
+      const rightShared = isSharedContainerItem(right) ? 1 : 0;
+      if (leftShared !== rightShared) return rightShared - leftShared;
+      return modifiedTimestamp(right) - modifiedTimestamp(left);
+    })
+    .slice(0, GOOGLE_SLIDES_DEFAULT_LIMIT)
+    .map((item) => item.externalId);
+}
+
+function isDraftLikeTitle(title: string): boolean {
+  return /^copy of\b/i.test(title.trim()) || /\btest\b/i.test(title);
+}
+
+function knownSlideCount(
+  metadata: Record<string, unknown> | undefined,
+): number | null {
+  for (const key of ["slideCount", "slidesCount", "pageCount"]) {
+    const value = Number(metadata?.[key]);
+    if (Number.isInteger(value) && value >= 0) return value;
+  }
+  return null;
+}
+
+function isSharedContainerItem(item: ContextConnectorInventoryItem): boolean {
+  const accessSignals = record(item.metadata?.accessSignals);
+  return Boolean(
+    accessSignals?.shared === true ||
+    text(accessSignals?.driveId) ||
+    text(item.metadata?.sharedDriveId),
+  );
+}
+
+function modifiedTimestamp(item: ContextConnectorInventoryItem): number {
+  const timestamp = item.sourceModifiedAt
+    ? Date.parse(item.sourceModifiedAt)
+    : Number.NaN;
+  return Number.isFinite(timestamp) ? timestamp : 0;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function text(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/src/connectors/types.ts

@@ -0,0 +1,115 @@
+import type {
+  PrivateBlobHandle,
+  PrivateBlobPutInput,
+  PrivateBlobReadResult,
+} from "@agent-native/core/private-blob";
+import type { ProviderApiRuntime } from "@agent-native/core/provider-api";
+
+import type { NormalizedContextItem, UpstreamAccess } from "../types.js";
+import type { RenderedPageProvider } from "./rendered-page.js";
+
+export type ContextConnectorKind =
+  | "manual"
+  | "upload"
+  | "google-slides"
+  | "figma"
+  | "notion"
+  | "website";
+
+export interface ContextConnectorInventoryItem {
+  externalId: string;
+  kind: string;
+  title: string;
+  canonicalUrl?: string;
+  mimeType?: string;
+  sourceModifiedAt?: string;
+  sizeBytes?: number;
+  upstreamAccess?: UpstreamAccess;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ContextConnectorInventoryRequest {
+  sourceId: string;
+  config: Record<string, unknown>;
+  cursor?: string | null;
+  syncCursor?: string | null;
+  limit?: number;
+}
+
+export interface ContextConnectorInventoryPage {
+  items: ContextConnectorInventoryItem[];
+  nextCursor: string | null;
+  complete: boolean;
+  syncCursor?: string | null;
+  coverage: {
+    inspected: number;
+    returned: number;
+    truncated: boolean;
+  };
+}
+
+export interface ContextConnectorFetchRequest {
+  sourceId: string;
+  config: Record<string, unknown>;
+  item: ContextConnectorInventoryItem;
+}
+
+export interface ContextConnectorFetchResult {
+  items: NormalizedContextItem[];
+  warnings?: string[];
+}
+
+export interface ContextUploadContent {
+  text: string;
+  mimeType?: string;
+  title?: string;
+  canonicalUrl?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ContextConnectorExecutionContext {
+  appId: string;
+  ownerEmail?: string;
+  providerApi?: Pick<ProviderApiRuntime, "executeRequest">;
+  renderedPages?: RenderedPageProvider;
+  signal?: AbortSignal;
+  now?: () => Date;
+  resolveConnection?: (
+    provider: string,
+    requestedConnectionId?: string,
+  ) => Promise<string | undefined>;
+  loadUpload?: (
+    item: ContextConnectorInventoryItem,
+    config: Record<string, unknown>,
+  ) => Promise<ContextUploadContent>;
+  putPrivateBlob?: (
+    input: PrivateBlobPutInput,
+  ) => Promise<PrivateBlobHandle | null>;
+  readPrivateBlob?: (
+    handle: PrivateBlobHandle,
+  ) => Promise<PrivateBlobReadResult>;
+}
+
+export interface ContextImportConnector {
+  readonly kind: ContextConnectorKind;
+  readonly label: string;
+  readonly supportsIncremental: boolean;
+  inventory(
+    request: ContextConnectorInventoryRequest,
+    context: ContextConnectorExecutionContext,
+  ): Promise<ContextConnectorInventoryPage>;
+  fetch(
+    request: ContextConnectorFetchRequest,
+    context: ContextConnectorExecutionContext,
+  ): Promise<ContextConnectorFetchResult>;
+  verifiesContainerOwner?(input: {
+    config: Record<string, unknown>;
+    inventory: ContextConnectorInventoryItem[];
+  }): boolean;
+}
+
+export interface ContextImportConnectorSummary {
+  kind: ContextConnectorKind;
+  label: string;
+  supportsIncremental: boolean;
+}

package/src/connectors/upload.spec.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { UploadContextConnector } from "./upload.js";
+
+const handle = {
+  id: "blob-1",
+  provider: "fixture",
+  opaque: true as const,
+  encrypted: true,
+  mimeType: "image/png",
+};
+
+function pngBytes() {
+  return new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 0]);
+}
+
+describe("upload context connector images", () => {
+  it("normalizes standalone raster uploads as private media-only items", async () => {
+    const connector = new UploadContextConnector();
+    const config = {
+      items: [
+        {
+          id: "hero",
+          title: "Homepage hero",
+          fileName: "hero.png",
+          mimeType: "image/png",
+          blobHandle: handle,
+        },
+      ],
+    };
+    const context = {
+      appId: "assets",
+      readPrivateBlob: async () => ({
+        data: pngBytes(),
+        handle,
+        mimeType: "image/png",
+      }),
+    } as never;
+    const inventory = await connector.inventory(
+      { sourceId: "source-1", config },
+      context,
+    );
+    expect(inventory.items[0]).toMatchObject({ kind: "uploaded-image" });
+
+    const fetched = await connector.fetch(
+      {
+        sourceId: "source-1",
+        config,
+        item: inventory.items[0]!,
+      },
+      context,
+    );
+
+    expect(fetched.items).toHaveLength(1);
+    expect(fetched.items[0]).toMatchObject({
+      externalId: "hero",
+      kind: "uploaded-image",
+      content: "",
+      parseStatus: "parsed",
+      metadata: { parser: "standalone-image" },
+      media: [
+        expect.objectContaining({
+          kind: "image",
+          mimeType: "image/png",
+          accessMode: "private",
+          captionStatus: "pending",
+        }),
+      ],
+    });
+    expect(fetched.items[0]?.media?.[0]?.storageKey).toMatch(
+      /^creative-context-blob:v1:/,
+    );
+  });
+
+  it("rejects active SVG uploads instead of indexing executable markup", async () => {
+    const connector = new UploadContextConnector();
+    const svgHandle = { ...handle, id: "blob-svg", mimeType: "image/svg+xml" };
+    const config = {
+      items: [
+        {
+          id: "unsafe-logo",
+          title: "Unsafe logo",
+          fileName: "logo.svg",
+          mimeType: "image/svg+xml",
+          blobHandle: svgHandle,
+        },
+      ],
+    };
+    const context = {
+      appId: "assets",
+      readPrivateBlob: async () => ({
+        data: new TextEncoder().encode(
+          '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>',
+        ),
+        handle: svgHandle,
+        mimeType: "image/svg+xml",
+      }),
+    } as never;
+    const inventory = await connector.inventory(
+      { sourceId: "source-1", config },
+      context,
+    );
+
+    await expect(
+      connector.fetch(
+        {
+          sourceId: "source-1",
+          config,
+          item: inventory.items[0]!,
+        },
+        context,
+      ),
+    ).rejects.toThrow(/SVG contains active content/i);
+  });
+
+  it("sanitizes embedded Office images before private storage", async () => {
+    const connector = new UploadContextConnector();
+    const putPrivateBlob = vi.fn(async () => handle);
+    const config = {
+      items: [
+        {
+          id: "deck",
+          title: "Launch deck",
+          fileName: "launch.pptx",
+          mimeType:
+            "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+          extractedText: "fixture",
+        },
+      ],
+    };
+    const context = {
+      appId: "slides",
+      putPrivateBlob,
+      loadUpload: async () => ({
+        text: "Launch",
+        title: "Launch deck",
+        parser: "structured-pptx" as const,
+        parts: [
+          {
+            kind: "slide" as const,
+            index: 0,
+            title: "Launch",
+            text: "Launch",
+            images: [
+              {
+                name: "active.svg",
+                mimeType: "image/svg+xml",
+                data: new TextEncoder().encode(
+                  '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>',
+                ),
+              },
+            ],
+          },
+        ],
+        metadata: {},
+      }),
+    } as never;
+    const inventory = await connector.inventory(
+      { sourceId: "source-1", config },
+      context,
+    );
+
+    await expect(
+      connector.fetch(
+        {
+          sourceId: "source-1",
+          config,
+          item: inventory.items[0]!,
+        },
+        context,
+      ),
+    ).rejects.toThrow(/SVG contains active content/i);
+    expect(putPrivateBlob).not.toHaveBeenCalled();
+  });
+});