@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/knowledge-lookup.d.ts

@@ -0,0 +1,178 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * A purpose based, bounded Graph lookup.
+ *
+ * This module deliberately has no knowledge of tenants, authentication
+ * tokens, internal endpoints, or a particular Graph transport.  Hosts inject
+ * those concerns through `KnowledgeLookupDependencies`; the lookup contract
+ * only decides which single bounded action to execute and how to report its
+ * evidence.
+ */
+export type KnowledgeLookupOutcome = 'retrieved' | 'empty' | 'incomplete' | 'transport_error' | 'forbidden' | 'ambiguous' | 'unsupported';
+export type KnowledgeLookupActionKind = 'search' | 'read' | 'follow_relation' | 'finish';
+export interface KnowledgeLookupScope {
+    readonly project_codes: string[];
+}
+export interface KnowledgeLookupError {
+    readonly code: string;
+    readonly message: string;
+    readonly http_status?: number;
+    readonly details?: unknown;
+}
+export type KnowledgeLookupDependencyStatus = 'ok' | 'error' | 'unavailable';
+/** The result shape expected from one host-owned Graph operation. */
+export interface KnowledgeLookupDependencyResult {
+    readonly status: KnowledgeLookupDependencyStatus;
+    readonly scope: KnowledgeLookupScope;
+    readonly data?: unknown;
+    readonly error?: KnowledgeLookupError;
+}
+export interface KnowledgeLookupSearchRequest {
+    readonly query: string;
+    readonly entity_types: string[];
+    readonly required_fields: string[];
+    readonly seed_ids?: string[];
+}
+export interface KnowledgeLookupReadRequest {
+    readonly entity_id: string;
+    readonly entity_type: string;
+    readonly required_fields: string[];
+}
+export interface KnowledgeLookupRelationRequest {
+    readonly query: string;
+    readonly entity_types: string[];
+    readonly required_fields: string[];
+    readonly seed_ids: string[];
+    readonly relation: string;
+    readonly direction: 'incoming' | 'outgoing';
+    readonly target_types?: string[];
+}
+/**
+ * A host may return any transport-specific candidate shape as long as it
+ * exposes these fields.  Unknown candidate fields are treated as data and
+ * never used to change authorization scope.
+ */
+export interface KnowledgeLookupSearchData {
+    readonly candidates?: readonly unknown[];
+    readonly coverage?: 'complete' | 'partial' | 'unknown';
+}
+export interface KnowledgeLookupReadData {
+    readonly entity?: unknown | null;
+    readonly coverage?: 'complete' | 'partial' | 'unknown';
+}
+export interface KnowledgeLookupProjection {
+    readonly body: Record<string, unknown>;
+    readonly entity_type?: string;
+}
+export type KnowledgeLookupProjectEntity = (entity: Record<string, unknown>) => KnowledgeLookupProjection;
+/**
+ * The only host boundary needed by the purpose-based lookup.  Implementations
+ * should authenticate and enforce their own source scope before returning a
+ * result.  They must not derive scope from `target_hint` or `context_hints`.
+ */
+export interface KnowledgeLookupDependencies {
+    search(input: KnowledgeLookupSearchRequest): Promise<KnowledgeLookupDependencyResult>;
+    read(input: KnowledgeLookupReadRequest): Promise<KnowledgeLookupDependencyResult>;
+    followRelation(input: KnowledgeLookupRelationRequest): Promise<KnowledgeLookupDependencyResult>;
+    readonly projectEntity: KnowledgeLookupProjectEntity;
+}
+export interface KnowledgeLookupReference {
+    readonly id: string;
+    readonly entity_type: string;
+    readonly evidence_fields: string[];
+}
+export interface KnowledgeLookupCandidateSummary {
+    readonly id: string;
+    readonly entity_type: string;
+    readonly name?: string;
+    readonly title?: string;
+    readonly display_name?: string;
+    readonly excerpt?: string;
+    readonly evidence?: Record<string, unknown>;
+}
+export interface KnowledgeLookupAction {
+    readonly kind: KnowledgeLookupActionKind;
+    readonly required_fields: string[];
+    readonly why_different?: string;
+    readonly query?: string;
+    readonly entity_types?: string[];
+    readonly seed_ids?: string[];
+    readonly entity_id?: string;
+    readonly entity_type?: string;
+    readonly relation?: string;
+    readonly direction?: 'incoming' | 'outgoing';
+    readonly target_types?: string[];
+}
+export interface KnowledgeLookupFinishProposal {
+    readonly assessment: 'sufficient' | 'insufficient';
+    readonly status: 'satisfied' | 'unresolved' | 'needs_user_input';
+    readonly reference_ids: string[];
+    readonly field_evidence: Array<{
+        field: string;
+        reference_id: string;
+        attempt_id: string;
+    }>;
+    readonly unresolved_items: string[];
+    readonly termination_reason: string;
+}
+export type KnowledgeLookupFinishValidation = {
+    readonly valid: true;
+    readonly finish: KnowledgeLookupFinishProposal;
+} | {
+    readonly valid: false;
+    readonly code: string;
+    readonly message: string;
+};
+export interface KnowledgeLookupResultData {
+    readonly lookup_id: string | null;
+    readonly revision: number | null;
+    readonly attempt_id: string | null;
+    readonly outcome: KnowledgeLookupOutcome;
+    readonly searched_scope: KnowledgeLookupScope;
+    readonly references: KnowledgeLookupReference[];
+    readonly available_fields: string[];
+    readonly missing_fields: string[];
+    readonly coverage: 'complete' | 'partial' | 'unknown';
+    readonly absence_confirmed: false;
+    readonly body: Record<string, unknown> | null;
+    readonly action: KnowledgeLookupAction;
+    readonly error_kind?: string;
+    readonly proposed_finish?: KnowledgeLookupFinishProposal;
+    readonly model_metadata?: {
+        readonly assessment?: 'sufficient' | 'insufficient';
+        readonly missing_information: string[];
+        readonly why_different?: string;
+        readonly based_on_attempt_ids: string[];
+    };
+}
+export interface KnowledgeLookupToolResult {
+    readonly status: KnowledgeLookupDependencyStatus;
+    readonly scope: KnowledgeLookupScope;
+    readonly data?: KnowledgeLookupResultData;
+    readonly error?: KnowledgeLookupError;
+}
+/** Public roots accepted in a projection. Unknown payload roots are dropped. */
+export declare const KNOWLEDGE_LOOKUP_ALLOWED_FIELD_ROOTS: Set<string>;
+/**
+ * Validate field paths at a host boundary without exposing the lookup
+ * implementation's input-error class.  The continuation host uses this
+ * result before it freezes required_fields, so both boundaries enforce the
+ * same public and forbidden roots.
+ */
+export type KnowledgeLookupFieldValidation = {
+    readonly valid: true;
+    readonly fields: string[];
+} | {
+    readonly valid: false;
+    readonly code: string;
+    readonly message: string;
+};
+export declare function validateKnowledgeLookupFields(value: unknown, label?: string): KnowledgeLookupFieldValidation;
+/**
+ * Validate and normalize the public finish proposal shape.  The continuation
+ * host calls this before its evidence checks so the API and host enforce the
+ * same bounds, identifier rules, and public field paths.
+ */
+export declare function validateKnowledgeLookupFinish(value: unknown): KnowledgeLookupFinishValidation;
+export declare const knowledgeLookupTools: Tool[];
+export declare function handleKnowledgeLookupToolCall(name: string, args: Record<string, unknown>, dependencies: KnowledgeLookupDependencies): Promise<KnowledgeLookupToolResult | null>;