@opengeni/core 2.10.0-canary.0 → 2.10.0-canary.2

package/src/domain/host-mcp-task-admission.ts

@@ -2,11 +2,13 @@ import { HTTPException } from "hono/http-exception";
 import type { Settings } from "@opengeni/config";
 import type { ToolRef, ScheduledTask, AccessGrant } from "@opengeni/contracts";
 import {
-  HostMcpBindingDefinition,
+  hostMcpBindingMatchesSelection,
   HostMcpCreateSelections,
 } from "@opengeni/contracts/host-mcp-bindings";
 import {
   captureHostMcpTaskAuthorities,
+  getHostMcpBinding,
+  getHostMcpDelegation,
   HostMcpDelegationAuthorityError,
   inheritHostMcpTaskAuthoritiesFromAttempt,
   type Database,
@@ -55,23 +57,36 @@ export function prepareHostMcpTaskAdmission(input: {
         message: "Host task selection must match a selected configured server",
       });
     assertHostMcpAuthoritySourceAdmissionEnabled(input.settings, server.connectionRef);
-    const { hostBinding, ...connectionRef } = server.connectionRef;
     return {
       delegationId: selection.delegationId,
       generation: selection.generation,
-      bindingId: hostBinding.bindingId,
-      bindingGeneration: hostBinding.generation,
-      definition: HostMcpBindingDefinition.parse({
+      configured: structuredClone({
         serverId: selection.serverId,
         destinationUrl: server.url,
-        connectionRef,
+        connectionRef: server.connectionRef,
       }),
     };
   });
   return async (tx, task) => {
     const owner = await reauthorize(tx);
     try {
-      if (prepared.length) await captureHostMcpTaskAuthorities(tx, owner, task, prepared);
+      const selected = [];
+      for (const selection of prepared) {
+        const delegation = await getHostMcpDelegation(tx, owner, selection.delegationId);
+        const binding = delegation
+          ? await getHostMcpBinding(tx, owner, delegation.bindingId)
+          : null;
+        if (!binding || !hostMcpBindingMatchesSelection(binding, selection.configured))
+          throw new HostMcpDelegationAuthorityError("Host task selection changed");
+        selected.push({
+          delegationId: selection.delegationId,
+          generation: selection.generation,
+          bindingId: binding.id,
+          bindingGeneration: binding.generation,
+          definition: binding.definition,
+        });
+      }
+      if (selected.length) await captureHostMcpTaskAuthorities(tx, owner, task, selected);
     } catch (error) {
       if (error instanceof HostMcpDelegationAuthorityError)
         throw new HTTPException(403, { message: error.message });
@@ -94,17 +109,12 @@ export function prepareInheritedHostMcpTaskAdmission(
     )
       return [];
     assertHostMcpAuthoritySourceAdmissionEnabled(settings, server.connectionRef);
-    const { hostBinding, ...connectionRef } = server.connectionRef;
     return [
-      {
-        bindingId: hostBinding.bindingId,
-        bindingGeneration: hostBinding.generation,
-        definition: HostMcpBindingDefinition.parse({
-          serverId: server.id,
-          destinationUrl: server.url,
-          connectionRef,
-        }),
-      },
+      structuredClone({
+        serverId: server.id,
+        destinationUrl: server.url,
+        connectionRef: server.connectionRef,
+      }),
     ];
   });
   return (tx, task) => inheritHostMcpTaskAuthoritiesFromAttempt(tx, task, source, configured);

package/src/domain/knowledge-files.ts

@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+import {
+  completeKnowledgeFilePreparation,
+  inspectKnowledgeFilePreparation,
+  type KnowledgeContext,
+} from "@opengeni/db";
+import { retryWhileMissing } from "@opengeni/storage";
+import type { ApiRouteDeps } from "../dependencies";
+
+/** Existing original -> one source revision, through the ordinary task policy. */
+export async function prepareKnowledgeFile(
+  deps: Pick<ApiRouteDeps, "db" | "objectStorage" | "getDocumentServices">,
+  context: KnowledgeContext,
+  fileId: string,
+) {
+  const inspected = await inspectKnowledgeFilePreparation(deps.db, context, fileId);
+  if (inspected.status !== "prepare") return inspected;
+  if (!deps.objectStorage) throw new Error("File storage is unavailable");
+  const object = await retryWhileMissing(() =>
+    deps.objectStorage!.getObjectBytes(inspected.file.objectKey),
+  );
+  if (!object) throw new Error("The original file is unavailable");
+  const sourceVersion = createHash("sha256").update(object.bytes).digest("hex");
+  if (
+    object.bytes.byteLength !== inspected.file.sizeBytes ||
+    (inspected.file.sha256 && inspected.file.sha256.toLowerCase() !== sourceVersion)
+  ) {
+    throw new Error("The original file no longer matches its retained metadata");
+  }
+  const parsed = await deps.getDocumentServices().parser.parse(object.bytes, inspected.file);
+  // Empty extraction is a visible failure, not a searchable-ready receipt.
+  if (!parsed.text.trim()) throw new Error("No searchable text could be extracted from this file");
+  return completeKnowledgeFilePreparation(deps.db, context, {
+    fileId,
+    title: inspected.file.filename,
+    sourceVersion,
+    content: parsed.text,
+  });
+}

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

@@ -0,0 +1,91 @@
+import { afterAll, beforeEach, expect, mock, test } from "bun:test";
+const actor = {
+  kind: "agent",
+  sessionId: "session-a",
+  turnId: "turn-a",
+  attemptId: "attempt-a",
+  executionGeneration: 1,
+} as const;
+const context = { accountId: "account", workspaceId: "workspace", actor };
+let event: any;
+let existing: any;
+const policy = mock(async () => ({ defaultScope: "personal", subjectId: "user-a" }));
+const save = mock(async (_db: any, _context: any, request: any) => ({
+  entryId: request.entryId,
+  revisionId: "revision",
+  outcome: "pending",
+}));
+mock.module("@opengeni/db", () => ({
+  freezeAgentLearningPolicy: policy,
+  nestedPostgresSqlState: (error: any) => error.code,
+  getSessionTurn: async () => ({ sessionId: "session-a", triggerEventId: "message-a" }),
+  getSessionEvent: async () => event,
+  getKnowledgeEntry: async () => existing,
+  saveKnowledgeEntry: save,
+}));
+const { retainKnowledgeMessage } = await import("./knowledge-messages");
+afterAll(() => mock.restore());
+beforeEach(() => {
+  event = {
+    id: "message-a",
+    sessionId: "session-a",
+    type: "user.message",
+    payload: { text: "I confirm it is 21k.\nKeep this exact." },
+    occurredAt: "2026-09-11T12:00:00Z",
+  };
+  existing = null;
+  save.mockClear();
+});
+test("retains exact text with message identity and preserves the review receipt", async () => {
+  const result = await retainKnowledgeMessage({} as never, context);
+  expect(result).toMatchObject({ retained: true, outcome: "pending", messageId: "message-a" });
+  expect(save.mock.calls[0]?.[2].entry).toMatchObject({
+    content: event.payload.text,
+    source: {
+      kind: "conversation",
+      sessionId: "session-a",
+      externalId: "message-a",
+      capturedAt: event.occurredAt,
+    },
+  });
+  expect(save.mock.calls[0]?.[2].scope).toBeUndefined();
+});
+test("refuses foreign-session and non-user events without writing", async () => {
+  event.sessionId = "private-foreign";
+  expect(await retainKnowledgeMessage({} as never, context, "foreign-event")).toMatchObject({
+    retained: false,
+  });
+  event.sessionId = "session-a";
+  event.type = "assistant.message";
+  expect(await retainKnowledgeMessage({} as never, context)).toMatchObject({ retained: false });
+  expect(save).not.toHaveBeenCalled();
+});
+test("reuses a retained message without creating another review request", async () => {
+  existing = {
+    archived: false,
+    revision: {
+      id: "already-retained",
+      outcome: "pending",
+      entry: { content: event.payload.text },
+    },
+  };
+  expect(await retainKnowledgeMessage({} as never, context)).toMatchObject({
+    retained: true,
+    reused: true,
+    revisionId: "already-retained",
+    outcome: "pending",
+  });
+  expect(save).not.toHaveBeenCalled();
+});
+test("never revives rejected, archived, or edited retained content", async () => {
+  for (const revision of [
+    { outcome: "rejected", content: event.payload.text },
+    { outcome: "published", content: "edited" },
+  ]) {
+    existing = { archived: false, revision: { ...revision, entry: { content: revision.content } } };
+    expect(await retainKnowledgeMessage({} as never, context)).toMatchObject({ retained: false });
+  }
+  existing.archived = true;
+  expect(await retainKnowledgeMessage({} as never, context)).toMatchObject({ retained: false });
+  expect(save).not.toHaveBeenCalled();
+});

package/src/domain/knowledge-messages.ts

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import {
+  freezeAgentLearningPolicy,
+  getKnowledgeEntry,
+  getSessionEvent,
+  getSessionTurn,
+  nestedPostgresSqlState,
+  saveKnowledgeEntry,
+  type Database,
+  type KnowledgeContext,
+} from "@opengeni/db";
+
+function stableId(value: string) {
+  const hex = createHash("sha256").update(value).digest("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+
+/** Retain actual message bytes, never a model-authored reconstruction of a confirmation. */
+export async function retainKnowledgeMessage(
+  db: Database,
+  context: KnowledgeContext,
+  messageId?: string,
+) {
+  if (context.actor.kind !== "agent") throw new Error("An exact agent attempt is required");
+  // Validates the live attempt and resolves its frozen personal/shared authoring scope.
+  const policy = await freezeAgentLearningPolicy(db, context);
+  const turn = await getSessionTurn(db, context.workspaceId, context.actor.turnId);
+  if (!turn || turn.sessionId !== context.actor.sessionId) throw new Error("Message unavailable");
+  const eventId = messageId ?? turn.triggerEventId;
+  const event = eventId ? await getSessionEvent(db, context.workspaceId, eventId) : null;
+  const payload = event?.payload;
+  const text =
+    payload && typeof payload === "object" && "text" in payload ? payload.text : undefined;
+  if (
+    !event ||
+    event.sessionId !== context.actor.sessionId ||
+    event.type !== "user.message" ||
+    typeof text !== "string" ||
+    !text.trim()
+  ) {
+    return {
+      retained: false,
+      reason:
+        "Choose a user message from this conversation. The current turn may have been triggered by a tool or scheduled event.",
+    };
+  }
+  const key = `${context.accountId}:${context.workspaceId}:${policy.defaultScope}:${policy.subjectId ?? ""}:${event.id}`;
+  const entryId = stableId(`knowledge-message:${key}`);
+  for (const view of ["published", "needs_review"] as const) {
+    const existing = await getKnowledgeEntry(db, context, entryId, { view });
+    if (!existing) continue;
+    if (
+      existing.archived ||
+      existing.revision.outcome === "rejected" ||
+      existing.revision.entry.content !== text
+    ) {
+      return {
+        retained: false,
+        reason:
+          "This retained message was edited, archived or rejected. Inspect its history; it has not been overwritten or revived.",
+        entryId,
+      };
+    }
+    return {
+      retained: true,
+      entryId,
+      revisionId: existing.revision.id,
+      outcome: existing.revision.outcome,
+      messageId: event.id,
+      reused: true,
+    };
+  }
+  let receipt;
+  try {
+    receipt = await saveKnowledgeEntry(db, context, {
+      operationId: crypto.randomUUID(),
+      entryId,
+      expectedVersion: 0,
+      entry: {
+        kind: "source",
+        title: `Chat: ${text.replace(/\s+/g, " ").slice(0, 100)}`,
+        content: text,
+        source: {
+          kind: "conversation",
+          sessionId: event.sessionId,
+          externalId: event.id,
+          capturedAt: event.occurredAt,
+          retention: "full_text",
+        },
+      },
+    });
+  } catch (error) {
+    // An inaccessible archived/rejected source or a concurrent creation must not
+    // be overwritten. The stable entry ID makes retries converge without a new copy.
+    if (nestedPostgresSqlState(error) === "40001")
+      return {
+        retained: false,
+        entryId,
+        reason:
+          "This message already has a retained source or changed concurrently. Inspect available Knowledge before retrying; no source was overwritten or revived.",
+      };
+    throw error;
+  }
+  return { retained: true, ...receipt, messageId: event.id };
+}

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

@@ -0,0 +1,45 @@
+import { afterAll, expect, mock, test } from "bun:test";
+const list = mock(
+  async (_db: unknown, _context: unknown, _request: unknown, _embedding?: unknown) => ({
+    entries: [],
+    nextCursor: null,
+  }),
+);
+mock.module("@opengeni/db", () => ({ listKnowledgeEntries: list }));
+const { searchKnowledgeEntries } = await import("./knowledge-search");
+afterAll(() => mock.restore());
+const unavailable = () => {
+  throw new Error("embedding unavailable");
+};
+test("hybrid fallback keeps lexical recall and passes the exact scope and cursor", async () => {
+  const result = await searchKnowledgeEntries(
+    {} as never,
+    {} as never,
+    {
+      query: "Acme renewal renew contract expiration renewal date",
+      scope: "workspace",
+      cursor: "page-2",
+    },
+    unavailable,
+  );
+  expect(result.searchMode).toBe("keyword");
+  expect(list.mock.calls.at(-1)?.[2]).toMatchObject({
+    query: '"Acme" OR "renewal" OR "renew" OR "contract" OR "expiration" OR "date"',
+    mode: "keyword",
+    scope: "workspace",
+    cursor: "page-2",
+  });
+});
+test("keyword and explicit search syntax remain unchanged", async () => {
+  for (const query of ['"Acme renewal"', "Acme -expired", "Acme OR renewal"]) {
+    await searchKnowledgeEntries({} as never, {} as never, { query }, unavailable);
+    expect(list.mock.calls.at(-1)?.[2]).toMatchObject({ query });
+  }
+  await searchKnowledgeEntries(
+    {} as never,
+    {} as never,
+    { query: "Acme renewal", mode: "keyword" },
+    unavailable,
+  );
+  expect(list.mock.calls.at(-1)?.[2]).toMatchObject({ query: "Acme renewal", mode: "keyword" });
+});

package/src/domain/knowledge-search.ts

@@ -0,0 +1,55 @@
+import { KnowledgeEntryListRequest } from "@opengeni/contracts";
+import { listKnowledgeEntries, type Database, type KnowledgeContext } from "@opengeni/db";
+import type { DocumentEmbedder } from "@opengeni/documents";
+import type { z } from "zod";
+
+/** Shared search path for HTTP and both first-party retrieval servers. */
+export async function searchKnowledgeEntries(
+  db: Database,
+  context: KnowledgeContext,
+  input: z.input<typeof KnowledgeEntryListRequest>,
+  embedder: () => DocumentEmbedder,
+) {
+  const request = KnowledgeEntryListRequest.parse(input);
+  if (!request.query || request.mode === "keyword") {
+    return {
+      ...(await listKnowledgeEntries(db, context, request)),
+      searchMode: "keyword" as const,
+    };
+  }
+  // Hybrid queries are natural language, not a conjunction of every synonym.
+  // Keep lexical recall useful when embeddings or vector indexing are unavailable.
+  // Explicit keyword syntax and keyword-mode queries retain their exact semantics.
+  const lexicalQuery =
+    /^[\p{L}\p{N}\s]+$/u.test(request.query) && !/\bOR\b/i.test(request.query)
+      ? [...new Set(request.query.trim().split(/\s+/u))].map((term) => `"${term}"`).join(" OR ")
+      : request.query;
+  const lexicalRequest = KnowledgeEntryListRequest.safeParse({ ...request, query: lexicalQuery });
+  const retrievalRequest =
+    request.mode === "hybrid" && lexicalRequest.success ? lexicalRequest.data : request;
+  let embedding: { model: string; values: number[] };
+  try {
+    const provider = embedder();
+    const values = await provider.embedQuery(request.query);
+    if (
+      values.length !== provider.dimensions ||
+      values.some((value) => !Number.isFinite(value)) ||
+      !values.some((value) => value !== 0)
+    ) {
+      throw new Error("Knowledge query embedding is unavailable");
+    }
+    embedding = { model: provider.model, values };
+  } catch (error) {
+    // Exact vector requests cannot silently change meaning. Hybrid search can
+    // continue using the transactional keyword index while a provider is down.
+    if (request.mode === "vector") throw error;
+    return {
+      ...(await listKnowledgeEntries(db, context, { ...retrievalRequest, mode: "keyword" })),
+      searchMode: "keyword" as const,
+    };
+  }
+  return {
+    ...(await listKnowledgeEntries(db, context, retrievalRequest, embedding)),
+    searchMode: request.mode,
+  };
+}

package/src/domain/knowledge.ts

@@ -0,0 +1,133 @@
+import type { AccessGrant, KnowledgeEntryScope, Permission } from "@opengeni/contracts";
+import type { KnowledgeContext } from "@opengeni/db";
+import { hasPermission, type AccessGrantAuthorization } from "../access";
+import { requireLiveAgentAttemptAuthorization } from "../session-authorization";
+import type { ApiRouteDeps } from "../dependencies";
+import { HTTPException } from "hono/http-exception";
+
+/** A delegated MCP gateway can retrieve shared Knowledge. Its subject label
+ * does not establish personal ownership or human review authority. */
+export async function knowledgeContextForGateway(
+  deps: Pick<ApiRouteDeps, "db">,
+  grant: AccessGrant,
+): Promise<KnowledgeContext> {
+  if (!hasPermission(grant.permissions, "documents:search"))
+    throw new HTTPException(403, { message: "Missing permission: documents:search" });
+  if (grant.principalKind === "agent_attempt") {
+    const sessionId = grant.metadata?.sessionId;
+    if (typeof sessionId !== "string")
+      throw new HTTPException(403, { message: "Knowledge attempt unavailable" });
+    const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor: {
+        kind: "agent",
+        sessionId: attempt.callerSessionId,
+        turnId: attempt.turnId,
+        attemptId: attempt.attemptId,
+        executionGeneration: attempt.executionGeneration,
+      },
+    };
+  }
+  return {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    actor: {
+      kind: "service",
+      principalKind: "mcp_gateway",
+      subjectId: grant.subjectId,
+      writeScopes: [],
+      review: false,
+      settingsScopes: [],
+    },
+  };
+}
+
+/** One host boundary for HTTP, SDK-through-HTTP and first-party Knowledge tools. */
+export async function knowledgeContextForAccess(
+  deps: Pick<ApiRouteDeps, "db">,
+  access: AccessGrantAuthorization,
+  permission: Permission,
+): Promise<KnowledgeContext> {
+  const { grant } = access;
+  if (!hasPermission(grant.permissions, permission)) {
+    throw new HTTPException(403, { message: `Missing permission: ${permission}` });
+  }
+  if (grant.principalKind === "agent_attempt") {
+    const sessionId = grant.metadata?.sessionId;
+    if (typeof sessionId !== "string")
+      throw new HTTPException(403, { message: "Knowledge attempt unavailable" });
+    const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor: {
+        kind: "agent",
+        sessionId: attempt.callerSessionId,
+        turnId: attempt.turnId,
+        attemptId: attempt.attemptId,
+        executionGeneration: attempt.executionGeneration,
+      },
+    };
+  }
+  if (
+    grant.principalKind === "service" ||
+    grant.principalKind === "api_key" ||
+    grant.principalKind === "configured_key"
+  ) {
+    const writeScopes: Array<"workspace" | "organization"> = hasPermission(
+      grant.permissions,
+      "documents:manage",
+    )
+      ? ["workspace"]
+      : [];
+    if (writeScopes.length && access.accountGrant?.permissions.includes("account:admin"))
+      writeScopes.push("organization");
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor: {
+        kind: "service",
+        principalKind: grant.principalKind,
+        subjectId: grant.subjectId,
+        writeScopes,
+        review: false,
+        settingsScopes: [],
+      },
+    };
+  }
+  if (
+    grant.principalKind !== "human_session" ||
+    !access.contextIntegrity ||
+    access.authenticatedSubjectId !== grant.subjectId ||
+    grant.serviceInitiator ||
+    grant.serviceInitiatorContext ||
+    grant.metadata?.attemptId !== undefined ||
+    grant.metadata?.turnId !== undefined
+  ) {
+    throw new HTTPException(403, {
+      message: "Knowledge management requires an authenticated human or agent attempt",
+    });
+  }
+  const canWrite = hasPermission(grant.permissions, "documents:manage");
+  const writeScopes: KnowledgeEntryScope[] = canWrite ? ["workspace", "personal"] : [];
+  // Organization authority does not follow from the workspace-admin wildcard.
+  if (canWrite && access.accountGrant?.permissions.includes("account:admin"))
+    writeScopes.push("organization");
+  return {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    actor: {
+      kind: "human",
+      principalKind: "human_session",
+      subjectId: access.authenticatedSubjectId,
+      writeScopes,
+      review: canWrite,
+      settingsScopes: [
+        "personal",
+        ...(hasPermission(grant.permissions, "workspace:admin") ? ["workspace" as const] : []),
+      ],
+    },
+  };
+}