@opengeni/core 3.0.0-canary.0 → 3.0.1-canary.0

package/src/domain/knowledge-preparation.test.ts

@@ -0,0 +1,251 @@
+import { expect, test } from "bun:test";
+import type { KnowledgeEntryRecord, KnowledgeEntrySummary } from "@opengeni/contracts";
+import { prepareKnowledgeSave } from "./knowledge-preparation";
+
+const context = {
+  accountId: "account",
+  workspaceId: "workspace",
+  actor: { kind: "human", review: true },
+} as never;
+const db = {} as never;
+const embedder = () => {
+  throw new Error("not used by fake search");
+};
+function group(title: string, parentIds: string[] = []): KnowledgeEntryRecord {
+  const id = crypto.randomUUID();
+  return {
+    id,
+    scope: "workspace",
+    version: 1,
+    publishedRevisionId: id,
+    latestRevisionId: id,
+    archived: false,
+    createdAt: "2026-09-14T00:00:00Z",
+    updatedAt: "2026-09-14T00:00:00Z",
+    revision: {
+      id,
+      entryId: id,
+      number: 1,
+      change: "upsert",
+      previousRevisionId: null,
+      restoredFromRevisionId: null,
+      createdAt: "2026-09-14T00:00:00Z",
+      createdBySessionId: null,
+      reviewBatchId: null,
+      outcome: "published",
+      entry: {
+        title,
+        kind: "group",
+        content: `Description of ${title}`,
+        groupIds: parentIds,
+        evidence: [],
+        relationships: [],
+      },
+    },
+  };
+}
+const summary = (record: KnowledgeEntryRecord) =>
+  ({
+    ...record,
+    revision: {
+      ...record.revision,
+      title: record.revision.entry.title,
+      kind: "group",
+      preview: "preview",
+      groupIds: record.revision.entry.groupIds,
+      sourceKind: null,
+    },
+    excerpts: [],
+  }) as KnowledgeEntrySummary;
+
+test("one read returns the complete paginated hierarchy and separately labeled duplicate candidates", async () => {
+  const parent = group("Engineering");
+  const child = group("Product UI", [parent.id]);
+  const pending = group("Proposed collection");
+  pending.revision.outcome = "pending";
+  const revoked = group("Revoked");
+  const calls: unknown[] = [];
+  const result = await prepareKnowledgeSave(
+    db,
+    context,
+    { query: "plugin setup consistency" },
+    embedder,
+    {
+      list: async (actualDb, actualContext, request) => {
+        expect(actualDb).toBe(db);
+        expect(actualContext).toBe(context);
+        calls.push(request);
+        if (request?.view === "needs_review")
+          return { entries: [summary(pending)], nextCursor: null };
+        return request?.cursor
+          ? { entries: [summary(child), summary(revoked)], nextCursor: null }
+          : { entries: [summary(parent)], nextCursor: "page2" };
+      },
+      get: async (_db, _context, id, options) => {
+        expect(options?.revisionId).toBeUndefined();
+        return [parent, child, pending].find((record) => record.id === id) ?? null;
+      },
+      search: async (_db, actualContext, request) => {
+        expect(actualContext).toBe(context);
+        expect(request.query).toBe("plugin setup consistency");
+        expect(request.groupId).toBeUndefined();
+        expect(request.scope).toBeUndefined();
+        return {
+          entries: [summary(request.view === "needs_review" ? pending : child)],
+          nextCursor: null,
+          searchMode: "hybrid",
+        };
+      },
+    },
+  );
+  expect(calls).toHaveLength(3);
+  expect(result.collections.complete).toBe(true);
+  expect(result.collections.entries.map((entry) => entry.title)).toEqual([
+    "Engineering",
+    "Product UI",
+    "Proposed collection",
+  ]);
+  expect(result.collections.entries[1]?.parentIds).toEqual([parent.id]);
+  expect(result.collections.entries[0]?.description).toBe("Description of Engineering");
+  expect(result.collections.entries[2]?.view).toBe("needs_review");
+  expect(result.matches.published.entries[0]?.id).toBe(child.id);
+  expect(result.matches.needs_review.entries[0]?.id).toBe(pending.id);
+});
+
+test("large collection maps explicitly continue and long descriptions report loss", async () => {
+  const record = group("Large collection");
+  record.revision.entry.content = "x".repeat(3000);
+  let count = 0;
+  const services: NonNullable<Parameters<typeof prepareKnowledgeSave>[4]> = {
+    list: async (_db, _context, request) => {
+      if (request?.view === "needs_review") return { entries: [], nextCursor: null };
+      return { entries: [summary(record)], nextCursor: `page${++count}` };
+    },
+    get: async () => record,
+    search: async () => ({ entries: [], nextCursor: null, searchMode: "keyword" }),
+  };
+  const result = await prepareKnowledgeSave(db, context, { query: "subject" }, embedder, services);
+  expect(result.collections.complete).toBe(false);
+  expect(result.collections.nextCursors.published).toBeTruthy();
+  expect(result.collections.nextCursors.needs_review).toBeNull();
+  expect(result.collections.entries[0]?.descriptionTruncated).toBe(true);
+  expect(result.collections.entries[0]?.description).toHaveLength(2000);
+  let requestedCursor: string | undefined;
+  await prepareKnowledgeSave(
+    db,
+    context,
+    { query: "subject", collectionCursors: result.collections.nextCursors },
+    embedder,
+    {
+      ...services,
+      list: async (_db, _context, request) => {
+        expect(request?.view).toBe("published");
+        requestedCursor = request?.cursor;
+        return { entries: [], nextCursor: null };
+      },
+    },
+  );
+  expect(requestedCursor).toBe(result.collections.nextCursors.published!);
+});
+
+test("a catalog authorization failure is not disguised as an empty complete map", async () => {
+  await expect(
+    prepareKnowledgeSave(db, context, { query: "subject" }, embedder, {
+      list: async () => {
+        throw new Error("access revoked");
+      },
+      get: async () => null,
+      search: async () => ({ entries: [], nextCursor: null, searchMode: "keyword" }),
+    }),
+  ).rejects.toThrow("access revoked");
+});
+
+test("read-only principals without proposal access fail before searching or embedding", async () => {
+  let touched = false;
+  await expect(
+    prepareKnowledgeSave(
+      db,
+      {
+        accountId: "account",
+        workspaceId: "workspace",
+        actor: { kind: "service", review: false },
+      } as never,
+      { query: "subject" },
+      () => {
+        touched = true;
+        throw new Error("must not embed");
+      },
+      {
+        list: async () => {
+          touched = true;
+          return { entries: [], nextCursor: null };
+        },
+        get: async () => {
+          touched = true;
+          return null;
+        },
+        search: async () => {
+          touched = true;
+          return { entries: [], nextCursor: null, searchMode: "keyword" };
+        },
+      },
+    ),
+  ).rejects.toMatchObject({ code: "42501" });
+  expect(touched).toBe(false);
+});
+
+test("published and pending searches reuse one query embedding", async () => {
+  let calls = 0;
+  await prepareKnowledgeSave(
+    db,
+    context,
+    { query: "plugin dialog" },
+    () => ({
+      model: "test",
+      dimensions: 2,
+      embedMany: async () => [],
+      embedQuery: async () => {
+        calls++;
+        return [1, 0];
+      },
+    }),
+    {
+      list: async () => ({ entries: [], nextCursor: null }),
+      get: async () => null,
+      search: async (_db, _context, request, queryEmbedder) => {
+        expect(await queryEmbedder().embedQuery(request.query!)).toEqual([1, 0]);
+        return { entries: [], nextCursor: null, searchMode: "hybrid" };
+      },
+    },
+  );
+  expect(calls).toBe(1);
+});
+
+test("catalog rechecks current metadata after a collection changes", async () => {
+  const old = group("Old name");
+  const current = {
+    ...old,
+    version: 2,
+    revision: {
+      ...old.revision,
+      id: crypto.randomUUID(),
+      entry: { ...old.revision.entry, title: "New name" },
+    },
+  };
+  const result = await prepareKnowledgeSave(db, context, { query: "subject" }, embedder, {
+    list: async (_db, _context, request) => ({
+      entries: request?.view === "published" ? [summary(old)] : [],
+      nextCursor: null,
+    }),
+    get: async (_db, _context, _id, options) => {
+      expect(options?.revisionId).toBeUndefined();
+      return current;
+    },
+    search: async () => ({ entries: [], nextCursor: null, searchMode: "keyword" }),
+  });
+  expect(result.collections.entries[0]).toMatchObject({
+    title: "New name",
+    version: 2,
+    revisionId: current.revision.id,
+  });
+});

package/src/domain/knowledge-preparation.ts

@@ -0,0 +1,126 @@
+import {
+  KnowledgeSavePreparationRequest,
+  type KnowledgeSavePreparationResponse,
+} from "@opengeni/contracts";
+import {
+  getKnowledgeEntry,
+  listKnowledgeEntries,
+  type Database,
+  type KnowledgeContext,
+} from "@opengeni/db";
+import type { DocumentEmbedder } from "@opengeni/documents";
+import { searchKnowledgeEntries } from "./knowledge-search";
+
+const defaults = {
+  get: getKnowledgeEntry,
+  list: listKnowledgeEntries,
+  search: searchKnowledgeEntries,
+};
+// Normal workspaces return the whole map in one call. Larger maps explicitly
+// continue at a complete page boundary, never silently omit collections.
+const CATALOG_PAGE_SIZE = 25;
+const CATALOG_PAGE_BUDGET = 40;
+const DESCRIPTION_CHARS = 2000;
+const CATALOG_BYTES = 256 * 1024;
+
+export async function prepareKnowledgeSave(
+  db: Database,
+  context: KnowledgeContext,
+  input: KnowledgeSavePreparationRequest,
+  embedder: () => DocumentEmbedder,
+  services = defaults,
+): Promise<KnowledgeSavePreparationResponse> {
+  const request = KnowledgeSavePreparationRequest.parse(input);
+  if (context.actor.kind !== "agent" && !(context.actor.kind === "human" && context.actor.review)) {
+    throw Object.assign(
+      new Error("Preparing Knowledge requires a live agent or human Knowledge reviewer"),
+      { code: "42501" },
+    );
+  }
+  let provider: DocumentEmbedder | undefined;
+  let queryEmbedding: Promise<number[]> | undefined;
+  const sharedEmbedder = (): DocumentEmbedder => {
+    provider ??= embedder();
+    const current = provider;
+    return {
+      model: current.model,
+      dimensions: current.dimensions,
+      embedMany: (texts) => current.embedMany(texts),
+      embedQuery: (query) => (queryEmbedding ??= current.embedQuery(query)),
+    };
+  };
+  const collections: KnowledgeSavePreparationResponse["collections"] = {
+    entries: [],
+    complete: true,
+    nextCursors: { published: null, needs_review: null },
+  };
+  // Search is independent of collection placement and always includes the
+  // separate unapproved view. No authoring policy or write is invoked here.
+  const matches = {
+    published: await services.search(
+      db,
+      context,
+      { query: request.query, limit: request.limit, view: "published" },
+      sharedEmbedder,
+    ),
+    needs_review: await services.search(
+      db,
+      context,
+      { query: request.query, limit: request.limit, view: "needs_review" },
+      sharedEmbedder,
+    ),
+  };
+  for (const view of ["published", "needs_review"] as const) {
+    if (request.collectionCursors && request.collectionCursors[view] === null) continue;
+    let cursor = request.collectionCursors?.[view] ?? undefined;
+    let bytes = 0;
+    for (let pageNumber = 0; pageNumber < CATALOG_PAGE_BUDGET; pageNumber++) {
+      const page = await services.list(db, context, {
+        kind: "group",
+        view,
+        limit: CATALOG_PAGE_SIZE,
+        ...(cursor ? { cursor } : {}),
+      });
+      const records: Array<Awaited<ReturnType<typeof getKnowledgeEntry>>> = [];
+      for (let offset = 0; offset < page.entries.length; offset += 4) {
+        records.push(
+          ...(await Promise.all(
+            page.entries
+              .slice(offset, offset + 4)
+              .map((summary) => services.get(db, context, summary.id, { view })),
+          )),
+        );
+      }
+      for (const record of records) {
+        // Re-read the current view: an exact historical revision may remain
+        // readable after replacement and must not be called the current map.
+        if (
+          !record ||
+          record.archived ||
+          record.revision.entry.kind !== "group" ||
+          record.revision.outcome !== (view === "published" ? "published" : "pending")
+        )
+          continue;
+        const entry = record.revision.entry;
+        const descriptor = {
+          id: record.id,
+          revisionId: record.revision.id,
+          version: record.version,
+          scope: record.scope,
+          view,
+          title: entry.title,
+          description: entry.content.slice(0, DESCRIPTION_CHARS),
+          descriptionTruncated: entry.content.length > DESCRIPTION_CHARS,
+          parentIds: entry.groupIds,
+        };
+        collections.entries.push(descriptor);
+        bytes += Buffer.byteLength(JSON.stringify(descriptor), "utf8");
+      }
+      cursor = page.nextCursor ?? undefined;
+      if (!cursor || bytes >= CATALOG_BYTES) break;
+    }
+    collections.nextCursors[view] = cursor ?? null;
+    if (cursor) collections.complete = false;
+  }
+  return { collections, matches };
+}

package/src/domain/organization-integration-catalog.ts

@@ -0,0 +1,83 @@
+import { CORE_INTEGRATION_DEFINITIONS } from "@opengeni/capabilities";
+import {
+  assertOrganizationIntegrationAllowed,
+  type IntegrationSource,
+  type OrganizationIntegrationPolicy,
+} from "@opengeni/contracts";
+
+/** Admission for source discovery, before any credential-bearing network work.
+ * Auto-detection may try only protocols the organization actually permits.
+ */
+export function integrationSourceForOrganizationPolicy(
+  policy: OrganizationIntegrationPolicy,
+  source: IntegrationSource,
+): IntegrationSource {
+  const snapshot = structuredClone(source);
+  if (policy.mode === "unrestricted") return snapshot;
+  if (snapshot.kind === "definition") {
+    const definition = CORE_INTEGRATION_DEFINITIONS.find(
+      (item) => item.id === snapshot.definitionId,
+    );
+    assertOrganizationIntegrationAllowed(policy, definition?.id ?? null);
+    return snapshot;
+  }
+  if (snapshot.kind !== "auto") {
+    assertOrganizationIntegrationAllowed(policy, `custom:${snapshot.kind}`);
+    return snapshot;
+  }
+  const openapi = policy.allowedIntegrationKeys.includes("custom:openapi");
+  const graphql = policy.allowedIntegrationKeys.includes("custom:graphql");
+  if (openapi && graphql) return snapshot;
+  if (openapi) return { ...snapshot, kind: "openapi" };
+  if (graphql) return { kind: "graphql", endpoint: snapshot.url };
+  assertOrganizationIntegrationAllowed(policy, null);
+  return snapshot;
+}
+
+const dedicated = [
+  { key: "gmail", label: "Gmail" },
+  { key: "atlassian", label: "Atlassian (Jira and Confluence)" },
+  { key: "slack-personal", label: "Slack personal accounts" },
+  { key: "slack-bot", label: "Slack workspace bots" },
+  { key: "github-personal", label: "GitHub personal accounts" },
+  { key: "github-app", label: "GitHub App installations" },
+  { key: "github-lens", label: "GitHub PR review" },
+  { key: "fiken", label: "Fiken" },
+  { key: "x", label: "X" },
+  { key: "reddit", label: "Reddit" },
+] as const;
+
+/** Product identities owned by the server, independent of mutable workspace catalogs. */
+export function organizationIntegrationCatalog(): {
+  integrations: Array<{ key: string; label: string; kind: "curated" | "custom" }>;
+} {
+  return {
+    integrations: [
+      ...CORE_INTEGRATION_DEFINITIONS.map((definition) => ({
+        key: definition.id,
+        label: definition.name,
+        kind: "curated" as const,
+      })),
+      ...dedicated.map((item) => ({ ...item, kind: "curated" as const })),
+      { key: "custom:mcp", label: "Custom MCP servers", kind: "custom" },
+      { key: "custom:openapi", label: "Custom OpenAPI services", kind: "custom" },
+      { key: "custom:graphql", label: "Custom GraphQL services", kind: "custom" },
+    ],
+  };
+}
+
+/** Only use for a validated built-in Connect adapter, never caller-authored catalog metadata. */
+export function integrationKeyForConnectProvider(providerId: string): string | null {
+  if (CORE_INTEGRATION_DEFINITIONS.some((definition) => definition.id === providerId))
+    return providerId;
+  if (dedicated.some((item) => item.key === providerId)) return providerId;
+  if (providerId === "fiken-token" || providerId === "fiken-oauth") return "fiken";
+  if (providerId === "google-drive-knowledge" || providerId === "google-drive-publish")
+    return "google-drive";
+  if (["mcp-oauth", "mcp-headers", "mcp-bearer", "mcp-install"].includes(providerId))
+    return "custom:mcp";
+  if (providerId === "openapi") return "custom:openapi";
+  if (providerId === "graphql") return "custom:graphql";
+  // Unknown adapter identities do not inherit an allowed provider's authority.
+  return null;
+}

package/src/domain/product-integration-pack.ts

@@ -22,7 +22,7 @@ export const OPENGENI_PRODUCT_INTEGRATION_PACK = {
     "Help an implementation agent add OpenGeni to an external product with adaptive discovery, tenant-safe boundaries, framework-native UI, authorized data tools, and the customer's chosen delivery autonomy. Installation stays inactive until one implementation session selects the Skill.",
   role: "software-engineering",
   category: "product-integration",
-  version: "0.2.0",
+  version: "0.2.1",
   skills: [OPENGENI_PRODUCT_INTEGRATION_SKILL],
   components: [],
   tools: [],