@opengeni/api-router 0.30.1 → 1.0.0

package/src/workspace-state-projection.ts

@@ -1,29 +1,17 @@
 import { createHash } from "node:crypto";
 import {
-  KnowledgeMemoryKind,
-  KnowledgeMemoryStatus,
-  WORKSPACE_STATE_BASE_NAME_MAX_CHARS,
   WORKSPACE_STATE_MAX_ACTIVE_POLICY_HEADS,
-  WORKSPACE_STATE_MAX_BASES,
-  WORKSPACE_STATE_MAX_GAPS,
-  WORKSPACE_STATE_MAX_TOPICS,
-  WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT,
-  WORKSPACE_STATE_TOPIC_MAX_CHARS,
+  WORKSPACE_STATE_KNOWLEDGE_SAMPLE_LIMIT,
+  type KnowledgeEntrySummary,
   WorkspaceStateResponse,
   type WorkspaceInstructionPolicyListResponse,
   type WorkspaceInstructionPolicySnapshot,
   type WorkspaceStateGovernanceDriftStatus,
-  type WorkspaceStateGap,
-  type WorkspaceStateMemoryKindCounts,
-  type WorkspaceStateMemoryStatusCounts,
   type WorkspaceStateResponse as WorkspaceStateResponseType,
 } from "@opengeni/contracts";
-import type { WorkspaceStateMemoryRecord } from "@opengeni/db";
-import type { DocumentInventory } from "@opengeni/documents";
-
 type KnowledgeProjectionInput = {
-  documents: DocumentInventory;
-  memories: WorkspaceStateMemoryRecord[];
+  entries: Pick<KnowledgeEntrySummary, "id" | "scope" | "revision" | "updatedAt">[];
+  nextCursor: string | null;
 };
 
 type PreferenceGovernanceIdentity = {
@@ -239,30 +227,6 @@ function attemptGovernanceProjection(input: WorkspaceStateProjectionInput) {
   };
 }
 
-function emptyMemoryStatusCounts(): WorkspaceStateMemoryStatusCounts {
-  return Object.fromEntries(
-    KnowledgeMemoryStatus.options.map((status) => [status, 0]),
-  ) as WorkspaceStateMemoryStatusCounts;
-}
-
-function emptyMemoryKindCounts(): WorkspaceStateMemoryKindCounts {
-  return Object.fromEntries(
-    KnowledgeMemoryKind.options.map((kind) => [kind, 0]),
-  ) as WorkspaceStateMemoryKindCounts;
-}
-
-function boundedLabel(value: string, maxChars: number, fallback: string): string {
-  const normalized = value.normalize("NFKC").trim().replace(/\s+/gu, " ");
-  return (normalized || fallback).slice(0, maxChars);
-}
-
-function newestTimestamp(values: Array<string | null>): string | null {
-  return values.reduce<string | null>((latest, value) => {
-    if (!value) return latest;
-    return latest === null || value > latest ? value : latest;
-  }, null);
-}
-
 function comparePolicyTargets(
   left: WorkspaceInstructionPolicyListResponse["activeHeads"][number],
   right: WorkspaceInstructionPolicyListResponse["activeHeads"][number],
@@ -330,116 +294,22 @@ function preferenceProjection(input: CurrentPreferenceProjectionInput) {
 }
 
 function availableKnowledgeProjection(knowledge: KnowledgeProjectionInput) {
-  const inventory = knowledge.documents;
-  const selectedBases = inventory.bases.slice(0, WORKSPACE_STATE_MAX_BASES);
-  const aggregateStatuses = { ...inventory.statusCounts };
-  const aggregateSources = { ...inventory.sourceKindCounts };
-  const topicCounts = new Map<string, number>();
-  const projectedBases = selectedBases.map((base) => {
-    return {
-      id: base.id,
-      name: boundedLabel(base.name, WORKSPACE_STATE_BASE_NAME_MAX_CHARS, "Untitled base"),
-      visibleDocumentCount: base.visibleDocumentCount,
-      statusCounts: base.statusCounts,
-      latestUpdatedAt: base.latestUpdatedAt,
-    };
-  });
-
-  for (const topic of inventory.topics) {
-    const name = boundedLabel(topic.name, WORKSPACE_STATE_TOPIC_MAX_CHARS, "Unlabeled topic");
-    topicCounts.set(name, (topicCounts.get(name) ?? 0) + topic.documentCount);
-  }
-
-  const sortedTopics = [...topicCounts.entries()]
-    .sort(
-      ([leftName, leftCount], [rightName, rightCount]) =>
-        rightCount - leftCount || leftName.localeCompare(rightName),
-    )
-    .map(([name, documentCount]) => ({ name, documentCount }));
-  const topics = sortedTopics.slice(0, WORKSPACE_STATE_MAX_TOPICS);
-  const memories = knowledge.memories.slice(0, WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT);
-  const memoryStatuses = emptyMemoryStatusCounts();
-  const memoryKinds = emptyMemoryKindCounts();
-  for (const memory of memories) {
-    memoryStatuses[memory.status] += 1;
-    memoryKinds[memory.kind] += 1;
-  }
-
-  const inspectedVisibleDocumentCount = inventory.visibleDocumentCount;
-  const basesTruncated = inventory.baseCount > projectedBases.length;
-  const memoryLimitReached = memories.length === WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT;
-  const inventoryPartial = basesTruncated || inventory.topicsTruncated || memoryLimitReached;
-  const gaps: WorkspaceStateGap[] = [];
-  const addGap = (gap: WorkspaceStateGap): void => {
-    if (gaps.length < WORKSPACE_STATE_MAX_GAPS) gaps.push(gap);
-  };
-  if (inventory.baseCount === 0) {
-    addGap({ code: "no_document_bases", severity: "info", relatedCount: 0 });
-  } else if (inspectedVisibleDocumentCount === 0) {
-    addGap({ code: "no_visible_documents", severity: "info", relatedCount: 0 });
-  }
-  if (aggregateStatuses.failed > 0) {
-    addGap({
-      code: "failed_documents",
-      severity: "warning",
-      relatedCount: aggregateStatuses.failed,
-    });
-  }
-  const processingCount = aggregateStatuses.queued + aggregateStatuses.indexing;
-  if (processingCount > 0) {
-    addGap({
-      code: "processing_documents",
-      severity: "info",
-      relatedCount: processingCount,
-    });
-  }
-  if (aggregateStatuses.ready > 0 && sortedTopics.length === 0) {
-    addGap({
-      code: "missing_topic_coverage",
-      severity: "info",
-      relatedCount: aggregateStatuses.ready,
-    });
-  }
-  if (memories.length === 0) {
-    addGap({ code: "no_memory_records", severity: "info", relatedCount: 0 });
-  }
-  if (memoryStatuses.proposed > 0) {
-    addGap({
-      code: "pending_memory_review",
-      severity: "info",
-      relatedCount: memoryStatuses.proposed,
-    });
-  }
-  if (inventoryPartial) {
-    addGap({ code: "partial_inventory", severity: "info", relatedCount: null });
-  }
-
   return {
     availability: "available" as const,
-    coverage: inventoryPartial ? ("partial" as const) : ("complete" as const),
-    baseCount: inventory.baseCount,
-    bases: projectedBases,
-    basesTruncated,
-    inspectedVisibleDocumentCount,
-    documentStatusCounts: aggregateStatuses,
-    sourceKindCounts: aggregateSources,
-    authorityKindCounts: { ...inventory.authorityKindCounts },
-    topics,
-    topicsTruncated: inventory.topicsTruncated || sortedTopics.length > topics.length,
-    latestDocumentUpdatedAt: inventory.latestUpdatedAt,
-    memorySample: {
-      recordCount: memories.length,
-      sampleLimit: WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT,
-      limitReached: memoryLimitReached,
-      statusCounts: memoryStatuses,
-      kindCounts: memoryKinds,
-      preferenceAuthority: {
-        kindCountSource: "knowledge_memories_legacy_observations" as const,
-        activeAuthority: "structured_preference_registry" as const,
-      },
-      latestUpdatedAt: newestTimestamp(memories.map((memory) => memory.updatedAt)),
-    },
-    gaps,
+    authority: "knowledge_entries" as const,
+    coverage:
+      knowledge.nextCursor || knowledge.entries.length > WORKSPACE_STATE_KNOWLEDGE_SAMPLE_LIMIT
+        ? ("partial" as const)
+        : ("complete" as const),
+    sampleLimit: WORKSPACE_STATE_KNOWLEDGE_SAMPLE_LIMIT,
+    entries: knowledge.entries.slice(0, WORKSPACE_STATE_KNOWLEDGE_SAMPLE_LIMIT).map((entry) => ({
+      id: entry.id,
+      revisionId: entry.revision.id,
+      title: entry.revision.title,
+      kind: entry.revision.kind,
+      scope: entry.scope,
+      updatedAt: entry.updatedAt,
+    })),
   };
 }
 

package/src/workspace-tool-gateway-observability.ts

@@ -0,0 +1,100 @@
+import type { ToolGatewayCatalogEntry } from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+
+export type WorkspaceToolGatewayAdapter = "http" | "mcp";
+export type WorkspaceToolGatewayOperation = "approval" | "call";
+export type WorkspaceToolGatewayOutcome =
+  | "ok"
+  | "tool_error"
+  | "approval_required"
+  | "catalog_stale"
+  | "invalid_input"
+  | "not_found"
+  | "rate_limited"
+  | "failed";
+
+const DURATION_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
+
+/**
+ * Low-cardinality gateway telemetry shared by HTTP/SDK/Site and aggregate MCP
+ * adapters. Tool names, workspace/subject ids, arguments, results, credentials,
+ * and approval tokens are excluded by construction.
+ */
+export function startWorkspaceToolGatewayObservation(
+  observability: Observability | null | undefined,
+  input: {
+    adapter: WorkspaceToolGatewayAdapter;
+    operation: WorkspaceToolGatewayOperation;
+    source: ToolGatewayCatalogEntry["source"] | "aggregate";
+  },
+): { end: (outcome: WorkspaceToolGatewayOutcome) => void } {
+  const startedAt = performance.now();
+  let span: ReturnType<Observability["startSpan"]> | undefined;
+  try {
+    span = observability?.startSpan("opengeni.tool_gateway.operation", {
+      surface: "workspace_tool_gateway",
+      op: `${input.adapter}.${input.operation}`,
+      provider: input.source,
+    });
+  } catch {
+    // Telemetry must never change gateway execution truth.
+  }
+  let ended = false;
+  return {
+    end: (outcome) => {
+      if (ended) return;
+      ended = true;
+      const durationMs = Math.max(0, performance.now() - startedAt);
+      try {
+        observability?.incrementCounter({
+          name: "opengeni_tool_gateway_operations_total",
+          help: "Workspace tool gateway operations by bounded adapter, operation, source, and outcome.",
+          labels: {
+            adapter: input.adapter,
+            operation: input.operation,
+            source: input.source,
+            outcome,
+          },
+        });
+        observability?.observeHistogram({
+          name: "opengeni_tool_gateway_operation_duration_seconds",
+          help: "Workspace tool gateway operation duration in seconds.",
+          labels: {
+            adapter: input.adapter,
+            operation: input.operation,
+            source: input.source,
+          },
+          buckets: DURATION_BUCKETS,
+          value: durationMs / 1_000,
+        });
+        observability?.info("Workspace tool gateway operation completed", {
+          surface: "workspace_tool_gateway",
+          op: `${input.adapter}.${input.operation}`,
+          provider: input.source,
+          outcome,
+          durationMs: Math.round(durationMs),
+        });
+      } catch {
+        try {
+          observability?.incrementCounter({
+            name: "opengeni_observability_observer_errors_total",
+            help: "Observability observer failures isolated from product execution.",
+            labels: { observer: "workspace_tool_gateway" },
+          });
+        } catch {
+          // Telemetry must never change gateway execution truth.
+        }
+      }
+      try {
+        span?.end({
+          attributes: {
+            outcome,
+            "opengeni.duration_ms": Math.round(durationMs),
+          },
+        });
+      } catch {
+        // Telemetry must never change gateway execution truth.
+      }
+    },
+  };
+}