mindgraph 0.12.0 → 0.13.0

package/dist/index.d.mts

@@ -415,6 +415,8 @@ interface RetrieveRequest {
      * reflect what the user likes.
      */
     query?: string;
+    /** Corpus Project whose member sources define the retrieval boundary. */
+    project_uid?: string;
     k?: number;
     threshold?: number;
     layer?: string;
@@ -528,6 +530,8 @@ interface IngestChunkResponse {
 interface IngestDocumentRequest {
     content: string;
     title?: string;
+    /** Corpus Project to attach the ingested document to. */
+    project_uid?: string;
     document_type?: string;
     /** Semantic content type: "article" (default), "meeting_notes", "journal". Drives default extraction layers. */
     content_type?: string;
@@ -592,6 +596,8 @@ interface IngestSessionRequest {
 }
 interface RetrieveContextRequest {
     query: string;
+    /** Corpus Project whose member sources define the retrieval boundary. */
+    project_uid?: string;
     /** Max graph nodes to return (default 10). */
     node_limit?: number;
     /** Max wiki articles to return (default 3). Set to 0 to skip. */
@@ -869,6 +875,12 @@ interface MindGraphConfig {
     apiKey?: string;
     jwt?: string;
     orgId?: string;
+    /**
+     * Non-security telemetry hint for first-party adapters. The cloud accepts
+     * only `dashboard`/`mcp`, normalizes everything else to `api`, and never
+     * uses this value for authorization or result membership.
+     */
+    telemetrySurface?: "dashboard" | "mcp";
     /** Max retries for 503 (server warming up) responses. Default: 3. Set to 0 to disable. */
     maxRetries?: number;
     /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
@@ -1146,8 +1158,10 @@ interface OntologyToolDescriptor {
     description: string;
     schema_id: string;
     object_type: string;
-    /** "search" | "object" | "object_context" */
-    maps_to: string;
+    maps_to: "search" | "object" | "object_context" | "related" | "structured_query";
+    relation?: string;
+    entry_role?: "source" | "target";
+    far_type?: string;
     input_schema: Record<string, unknown>;
 }
 interface CreateOntologySchemaRequest {
@@ -1278,20 +1292,125 @@ interface ProposeOntologySchemaRequest {
 interface OntologyQueryRequest {
     query: string;
     schema_id: string;
+    project_uid?: string;
     object_types?: string[];
     include_cognitive_context?: boolean;
     include_sources?: boolean;
     depth?: number;
     limit?: number;
 }
+type OntologyPredicateOperator = "eq" | "neq" | "in" | "contains" | "gte" | "lte" | "exists";
+interface OntologyQueryPredicate {
+    field: string;
+    op: OntologyPredicateOperator;
+    value?: unknown;
+}
+interface StructuredOntologyQueryRequest {
+    schema_id: string;
+    select: string;
+    project_uid?: string;
+    anchor?: {
+        type: string;
+        uid?: string;
+        match?: {
+            value: string;
+            field?: string;
+        };
+    };
+    path?: Array<{
+        relation: string;
+        entry_role: "source" | "target";
+    }>;
+    where?: OntologyQueryPredicate[];
+    include?: {
+        provenance?: boolean;
+        related?: string[];
+    };
+    page?: {
+        limit?: number;
+        offset?: number;
+    };
+    aggregate?: {
+        op: "count" | "customer_demand_rank";
+        group_by?: string;
+    };
+}
+interface StructuredOntologyQueryResponse {
+    plan: Record<string, unknown>;
+    rows: Array<{
+        object: DomainObject;
+        related?: Record<string, DomainObject[]>;
+    }>;
+    relations: Array<{
+        uid: string;
+        relation: string;
+        from_uid: string;
+        to_uid: string;
+        fields: unknown;
+        leg_index?: number;
+    }>;
+    provenance: Array<{
+        node_uid: string;
+        source_uid: string;
+        text_span: string;
+    }>;
+    aggregate?: unknown;
+    total_count: number;
+    total_count_exact: boolean;
+    returned_count: number;
+    has_more: boolean;
+    coverage_complete: boolean;
+    truncation_reasons: string[];
+    diagnostics: string[];
+    metrics: Record<string, unknown>;
+}
+interface RelatedDomainObjectsRequest {
+    schema_id: string;
+    entry_type: string;
+    uid: string;
+    relation: string;
+    entry_role: "source" | "target";
+    far_type: string;
+    where?: OntologyQueryPredicate[];
+    include_provenance?: boolean;
+    limit?: number;
+    offset?: number;
+    project_uid?: string;
+}
 interface OntologyQueryResponse {
     objects: GraphNode[];
-    relations: GraphEdge[];
-    cognitive_context: Record<string, GraphNode[]>;
+    relations: Array<{
+        edge_uid: string | null;
+        from_uid: string;
+        to_uid: string;
+        edge_type: string;
+        traversal_role: string;
+        depth: number;
+    }>;
+    cognitive_context: Record<string, Array<{
+        uid: string;
+        label: string;
+        node_type: string;
+        layer: string;
+        depth: number;
+    }>>;
     external_refs: unknown[];
     graph: {
-        nodes: GraphNode[];
-        edges: GraphEdge[];
+        nodes: Array<{
+            uid: string;
+            label: string;
+            node_type: string;
+            layer: string;
+            depth: number;
+        }>;
+        edges: Array<{
+            edge_uid: string | null;
+            from_uid: string;
+            to_uid: string;
+            edge_type: string;
+            traversal_role: string;
+            depth: number;
+        }>;
     };
     provenance: Array<{
         node_uid: string;
@@ -1301,6 +1420,9 @@ interface OntologyQueryResponse {
     confidence: {
         overall: number;
     };
+    returned_count: number;
+    has_more: boolean;
+    seed_cap_hit: boolean;
     truncated?: Record<string, boolean>;
 }
 interface LinkDomainObjectsRequest {
@@ -1339,6 +1461,7 @@ declare class MindGraph {
     private headers;
     private maxRetries;
     private retryBackoffMs;
+    private telemetrySurface?;
     constructor(config: MindGraphConfig);
     private request;
     private get;
@@ -1555,6 +1678,7 @@ declare class MindGraph {
         edge_type?: string;
     }): Promise<GraphEdge[]>;
     search(query: string, opts?: {
+        project_uid?: string;
         node_type?: string;
         layer?: string;
         limit?: number;
@@ -1568,6 +1692,7 @@ declare class MindGraph {
      * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
      */
     hybridSearch(query: string, opts?: {
+        project_uid?: string;
         k?: number;
         node_types?: string[];
         layer?: string;
@@ -1807,17 +1932,26 @@ declare class MindGraph {
         }[];
     }>;
     queryOntology(req: OntologyQueryRequest): Promise<OntologyQueryResponse>;
+    queryDomainStructured(req: StructuredOntologyQueryRequest): Promise<StructuredOntologyQueryResponse>;
+    queryRelatedDomainObjects(req: RelatedDomainObjectsRequest): Promise<StructuredOntologyQueryResponse>;
     /**
-     * Read-only agent tool descriptors generated from the active ontology
-     * schema(s). Each maps to a generic `/ontology` read endpoint with
-     * `object_type` bound. Used by the MCP server to expose typed per-object
-     * tools (`search_customers`, `summarize_customer`, …).
+     * Schema-qualified read-tool descriptors generated from every active
+     * ontology. Includes per-object discovery/point/context tools,
+     * relation-and-role-specific related tools, and one structured composite.
      */
     listOntologyTools(): Promise<{
         tools: OntologyToolDescriptor[];
     }>;
-    getDomainObject(uid: string): Promise<DomainObject>;
-    getDomainObjectContext(uid: string, depth?: number): Promise<OntologyQueryResponse>;
+    getDomainObject(uid: string, binding?: {
+        schema_id: string;
+        object_type: string;
+        project_uid?: string;
+    }): Promise<DomainObject>;
+    getDomainObjectContext(uid: string, depth?: number, binding?: {
+        schema_id: string;
+        object_type: string;
+        project_uid?: string;
+    }): Promise<OntologyQueryResponse>;
     getDomainObjectHistory(uid: string): Promise<{
         versions: Array<{
             version: number;
@@ -1842,12 +1976,19 @@ declare class MindGraph {
     searchDomainObjects(query: string, opts?: {
         schema_id?: string;
         object_types?: string[];
+        filters?: OntologyQueryPredicate[];
         limit?: number;
     }): Promise<{
         items: Array<{
             object: DomainObject;
             score: number;
         }>;
+        returned_count: number;
+        has_more: boolean;
+        seed_cap_hit: boolean;
+        truncation_reasons: string[];
+        total_count: null;
+        total_count_exact: false;
     }>;
     /**
      * Per-object-type coverage stats for a schema (C2f): field fill rates
@@ -1888,4 +2029,4 @@ declare class MindGraph {
     }>;
 }
 
-export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CanonicalAttachmentAuthority, type CanonicalAttachmentBinding, type CanonicalAttachmentDirection, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type CreateOntologySchemaRequest, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type FieldDefinition, type FieldSemantic, type FieldSemanticKind, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type NormativeKind, type ObjectBacking, type OntologicalBaseKind, type OntologyDuplicateAudit, type OntologyObjectType, type OntologyObjectTypeInput, type OntologyProposal, type OntologyRelationType, type OntologyRelationTypeInput, type OntologySchema, type OntologySchemaDetail, type OrganizationProps, type Participant, type ParticipantSlotKind, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type ProposalEdits, type PurgeRequest, type RankedClaimHub, type RelationBacking, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SemanticDependence, type SemanticEvidenceRef, type SemanticEvidenceSourceKind, type SemanticGeneratorRef, type SemanticIdentityMode, type SemanticMatch, type SemanticMatchAlternative, type SemanticMatchStatus, type SemanticModifier, type SemanticModifierMatch, type SemanticNegativeControl, type SemanticParticipantSlot, type SemanticRelationKind, type SemanticReviewDecision, type SemanticRigidity, type SemanticRuntimeTemplate, type SemanticSignal, type SemanticSignalKind, type SemanticTemplateRef, type SemanticTemporalMode, type SemanticTenantBindings, type SemanticValidationAuthoringMode, type SemanticValidationMode, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest, type UpdateOntologySchemaRequest };
+export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CanonicalAttachmentAuthority, type CanonicalAttachmentBinding, type CanonicalAttachmentDirection, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type CreateOntologySchemaRequest, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type FieldDefinition, type FieldSemantic, type FieldSemanticKind, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type NormativeKind, type ObjectBacking, type OntologicalBaseKind, type OntologyDuplicateAudit, type OntologyObjectType, type OntologyObjectTypeInput, type OntologyPredicateOperator, type OntologyProposal, type OntologyQueryPredicate, type OntologyRelationType, type OntologyRelationTypeInput, type OntologySchema, type OntologySchemaDetail, type OntologyToolDescriptor, type OrganizationProps, type Participant, type ParticipantSlotKind, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type ProposalEdits, type PurgeRequest, type RankedClaimHub, type RelatedDomainObjectsRequest, type RelationBacking, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SemanticDependence, type SemanticEvidenceRef, type SemanticEvidenceSourceKind, type SemanticGeneratorRef, type SemanticIdentityMode, type SemanticMatch, type SemanticMatchAlternative, type SemanticMatchStatus, type SemanticModifier, type SemanticModifierMatch, type SemanticNegativeControl, type SemanticParticipantSlot, type SemanticRelationKind, type SemanticReviewDecision, type SemanticRigidity, type SemanticRuntimeTemplate, type SemanticSignal, type SemanticSignalKind, type SemanticTemplateRef, type SemanticTemporalMode, type SemanticTenantBindings, type SemanticValidationAuthoringMode, type SemanticValidationMode, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type StructuredOntologyQueryRequest, type StructuredOntologyQueryResponse, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest, type UpdateOntologySchemaRequest };

package/dist/index.d.ts

@@ -415,6 +415,8 @@ interface RetrieveRequest {
      * reflect what the user likes.
      */
     query?: string;
+    /** Corpus Project whose member sources define the retrieval boundary. */
+    project_uid?: string;
     k?: number;
     threshold?: number;
     layer?: string;
@@ -528,6 +530,8 @@ interface IngestChunkResponse {
 interface IngestDocumentRequest {
     content: string;
     title?: string;
+    /** Corpus Project to attach the ingested document to. */
+    project_uid?: string;
     document_type?: string;
     /** Semantic content type: "article" (default), "meeting_notes", "journal". Drives default extraction layers. */
     content_type?: string;
@@ -592,6 +596,8 @@ interface IngestSessionRequest {
 }
 interface RetrieveContextRequest {
     query: string;
+    /** Corpus Project whose member sources define the retrieval boundary. */
+    project_uid?: string;
     /** Max graph nodes to return (default 10). */
     node_limit?: number;
     /** Max wiki articles to return (default 3). Set to 0 to skip. */
@@ -869,6 +875,12 @@ interface MindGraphConfig {
     apiKey?: string;
     jwt?: string;
     orgId?: string;
+    /**
+     * Non-security telemetry hint for first-party adapters. The cloud accepts
+     * only `dashboard`/`mcp`, normalizes everything else to `api`, and never
+     * uses this value for authorization or result membership.
+     */
+    telemetrySurface?: "dashboard" | "mcp";
     /** Max retries for 503 (server warming up) responses. Default: 3. Set to 0 to disable. */
     maxRetries?: number;
     /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
@@ -1146,8 +1158,10 @@ interface OntologyToolDescriptor {
     description: string;
     schema_id: string;
     object_type: string;
-    /** "search" | "object" | "object_context" */
-    maps_to: string;
+    maps_to: "search" | "object" | "object_context" | "related" | "structured_query";
+    relation?: string;
+    entry_role?: "source" | "target";
+    far_type?: string;
     input_schema: Record<string, unknown>;
 }
 interface CreateOntologySchemaRequest {
@@ -1278,20 +1292,125 @@ interface ProposeOntologySchemaRequest {
 interface OntologyQueryRequest {
     query: string;
     schema_id: string;
+    project_uid?: string;
     object_types?: string[];
     include_cognitive_context?: boolean;
     include_sources?: boolean;
     depth?: number;
     limit?: number;
 }
+type OntologyPredicateOperator = "eq" | "neq" | "in" | "contains" | "gte" | "lte" | "exists";
+interface OntologyQueryPredicate {
+    field: string;
+    op: OntologyPredicateOperator;
+    value?: unknown;
+}
+interface StructuredOntologyQueryRequest {
+    schema_id: string;
+    select: string;
+    project_uid?: string;
+    anchor?: {
+        type: string;
+        uid?: string;
+        match?: {
+            value: string;
+            field?: string;
+        };
+    };
+    path?: Array<{
+        relation: string;
+        entry_role: "source" | "target";
+    }>;
+    where?: OntologyQueryPredicate[];
+    include?: {
+        provenance?: boolean;
+        related?: string[];
+    };
+    page?: {
+        limit?: number;
+        offset?: number;
+    };
+    aggregate?: {
+        op: "count" | "customer_demand_rank";
+        group_by?: string;
+    };
+}
+interface StructuredOntologyQueryResponse {
+    plan: Record<string, unknown>;
+    rows: Array<{
+        object: DomainObject;
+        related?: Record<string, DomainObject[]>;
+    }>;
+    relations: Array<{
+        uid: string;
+        relation: string;
+        from_uid: string;
+        to_uid: string;
+        fields: unknown;
+        leg_index?: number;
+    }>;
+    provenance: Array<{
+        node_uid: string;
+        source_uid: string;
+        text_span: string;
+    }>;
+    aggregate?: unknown;
+    total_count: number;
+    total_count_exact: boolean;
+    returned_count: number;
+    has_more: boolean;
+    coverage_complete: boolean;
+    truncation_reasons: string[];
+    diagnostics: string[];
+    metrics: Record<string, unknown>;
+}
+interface RelatedDomainObjectsRequest {
+    schema_id: string;
+    entry_type: string;
+    uid: string;
+    relation: string;
+    entry_role: "source" | "target";
+    far_type: string;
+    where?: OntologyQueryPredicate[];
+    include_provenance?: boolean;
+    limit?: number;
+    offset?: number;
+    project_uid?: string;
+}
 interface OntologyQueryResponse {
     objects: GraphNode[];
-    relations: GraphEdge[];
-    cognitive_context: Record<string, GraphNode[]>;
+    relations: Array<{
+        edge_uid: string | null;
+        from_uid: string;
+        to_uid: string;
+        edge_type: string;
+        traversal_role: string;
+        depth: number;
+    }>;
+    cognitive_context: Record<string, Array<{
+        uid: string;
+        label: string;
+        node_type: string;
+        layer: string;
+        depth: number;
+    }>>;
     external_refs: unknown[];
     graph: {
-        nodes: GraphNode[];
-        edges: GraphEdge[];
+        nodes: Array<{
+            uid: string;
+            label: string;
+            node_type: string;
+            layer: string;
+            depth: number;
+        }>;
+        edges: Array<{
+            edge_uid: string | null;
+            from_uid: string;
+            to_uid: string;
+            edge_type: string;
+            traversal_role: string;
+            depth: number;
+        }>;
     };
     provenance: Array<{
         node_uid: string;
@@ -1301,6 +1420,9 @@ interface OntologyQueryResponse {
     confidence: {
         overall: number;
     };
+    returned_count: number;
+    has_more: boolean;
+    seed_cap_hit: boolean;
     truncated?: Record<string, boolean>;
 }
 interface LinkDomainObjectsRequest {
@@ -1339,6 +1461,7 @@ declare class MindGraph {
     private headers;
     private maxRetries;
     private retryBackoffMs;
+    private telemetrySurface?;
     constructor(config: MindGraphConfig);
     private request;
     private get;
@@ -1555,6 +1678,7 @@ declare class MindGraph {
         edge_type?: string;
     }): Promise<GraphEdge[]>;
     search(query: string, opts?: {
+        project_uid?: string;
         node_type?: string;
         layer?: string;
         limit?: number;
@@ -1568,6 +1692,7 @@ declare class MindGraph {
      * the "why retrieved" detail (server ≥ 1.2.0; older servers ignore it).
      */
     hybridSearch(query: string, opts?: {
+        project_uid?: string;
         k?: number;
         node_types?: string[];
         layer?: string;
@@ -1807,17 +1932,26 @@ declare class MindGraph {
         }[];
     }>;
     queryOntology(req: OntologyQueryRequest): Promise<OntologyQueryResponse>;
+    queryDomainStructured(req: StructuredOntologyQueryRequest): Promise<StructuredOntologyQueryResponse>;
+    queryRelatedDomainObjects(req: RelatedDomainObjectsRequest): Promise<StructuredOntologyQueryResponse>;
     /**
-     * Read-only agent tool descriptors generated from the active ontology
-     * schema(s). Each maps to a generic `/ontology` read endpoint with
-     * `object_type` bound. Used by the MCP server to expose typed per-object
-     * tools (`search_customers`, `summarize_customer`, …).
+     * Schema-qualified read-tool descriptors generated from every active
+     * ontology. Includes per-object discovery/point/context tools,
+     * relation-and-role-specific related tools, and one structured composite.
      */
     listOntologyTools(): Promise<{
         tools: OntologyToolDescriptor[];
     }>;
-    getDomainObject(uid: string): Promise<DomainObject>;
-    getDomainObjectContext(uid: string, depth?: number): Promise<OntologyQueryResponse>;
+    getDomainObject(uid: string, binding?: {
+        schema_id: string;
+        object_type: string;
+        project_uid?: string;
+    }): Promise<DomainObject>;
+    getDomainObjectContext(uid: string, depth?: number, binding?: {
+        schema_id: string;
+        object_type: string;
+        project_uid?: string;
+    }): Promise<OntologyQueryResponse>;
     getDomainObjectHistory(uid: string): Promise<{
         versions: Array<{
             version: number;
@@ -1842,12 +1976,19 @@ declare class MindGraph {
     searchDomainObjects(query: string, opts?: {
         schema_id?: string;
         object_types?: string[];
+        filters?: OntologyQueryPredicate[];
         limit?: number;
     }): Promise<{
         items: Array<{
             object: DomainObject;
             score: number;
         }>;
+        returned_count: number;
+        has_more: boolean;
+        seed_cap_hit: boolean;
+        truncation_reasons: string[];
+        total_count: null;
+        total_count_exact: false;
     }>;
     /**
      * Per-object-type coverage stats for a schema (C2f): field fill rates
@@ -1888,4 +2029,4 @@ declare class MindGraph {
     }>;
 }
 
-export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CanonicalAttachmentAuthority, type CanonicalAttachmentBinding, type CanonicalAttachmentDirection, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type CreateOntologySchemaRequest, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type FieldDefinition, type FieldSemantic, type FieldSemanticKind, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type NormativeKind, type ObjectBacking, type OntologicalBaseKind, type OntologyDuplicateAudit, type OntologyObjectType, type OntologyObjectTypeInput, type OntologyProposal, type OntologyRelationType, type OntologyRelationTypeInput, type OntologySchema, type OntologySchemaDetail, type OrganizationProps, type Participant, type ParticipantSlotKind, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type ProposalEdits, type PurgeRequest, type RankedClaimHub, type RelationBacking, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SemanticDependence, type SemanticEvidenceRef, type SemanticEvidenceSourceKind, type SemanticGeneratorRef, type SemanticIdentityMode, type SemanticMatch, type SemanticMatchAlternative, type SemanticMatchStatus, type SemanticModifier, type SemanticModifierMatch, type SemanticNegativeControl, type SemanticParticipantSlot, type SemanticRelationKind, type SemanticReviewDecision, type SemanticRigidity, type SemanticRuntimeTemplate, type SemanticSignal, type SemanticSignalKind, type SemanticTemplateRef, type SemanticTemporalMode, type SemanticTenantBindings, type SemanticValidationAuthoringMode, type SemanticValidationMode, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest, type UpdateOntologySchemaRequest };
+export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CanonicalAttachmentAuthority, type CanonicalAttachmentBinding, type CanonicalAttachmentDirection, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type CreateOntologySchemaRequest, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type FieldDefinition, type FieldSemantic, type FieldSemanticKind, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type NormativeKind, type ObjectBacking, type OntologicalBaseKind, type OntologyDuplicateAudit, type OntologyObjectType, type OntologyObjectTypeInput, type OntologyPredicateOperator, type OntologyProposal, type OntologyQueryPredicate, type OntologyRelationType, type OntologyRelationTypeInput, type OntologySchema, type OntologySchemaDetail, type OntologyToolDescriptor, type OrganizationProps, type Participant, type ParticipantSlotKind, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type ProposalEdits, type PurgeRequest, type RankedClaimHub, type RelatedDomainObjectsRequest, type RelationBacking, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SemanticDependence, type SemanticEvidenceRef, type SemanticEvidenceSourceKind, type SemanticGeneratorRef, type SemanticIdentityMode, type SemanticMatch, type SemanticMatchAlternative, type SemanticMatchStatus, type SemanticModifier, type SemanticModifierMatch, type SemanticNegativeControl, type SemanticParticipantSlot, type SemanticRelationKind, type SemanticReviewDecision, type SemanticRigidity, type SemanticRuntimeTemplate, type SemanticSignal, type SemanticSignalKind, type SemanticTemplateRef, type SemanticTemporalMode, type SemanticTenantBindings, type SemanticValidationAuthoringMode, type SemanticValidationMode, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type StructuredOntologyQueryRequest, type StructuredOntologyQueryResponse, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest, type UpdateOntologySchemaRequest };

package/dist/index.js

@@ -46,15 +46,21 @@ var MindGraph = class {
     if (config.orgId) {
       this.headers["X-MindGraph-Org"] = config.orgId;
     }
+    this.telemetrySurface = config.telemetrySurface;
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
+    const requestId = createRequestId();
     const init = {
       method,
-      headers: this.headers
+      headers: {
+        ...this.headers,
+        "X-MindGraph-Request-ID": requestId,
+        ...this.telemetrySurface ? { "X-MindGraph-Surface": this.telemetrySurface } : {}
+      }
     };
     if (body !== void 0) {
       init.body = JSON.stringify(body);
@@ -798,21 +804,55 @@ var MindGraph = class {
   async queryOntology(req) {
     return this.post("/ontology/query", req);
   }
+  async queryDomainStructured(req) {
+    return this.post("/ontology/query/structured", req);
+  }
+  async queryRelatedDomainObjects(req) {
+    return this.queryDomainStructured({
+      schema_id: req.schema_id,
+      select: req.far_type,
+      ...req.project_uid ? { project_uid: req.project_uid } : {},
+      anchor: { type: req.entry_type, uid: req.uid },
+      path: [{
+        relation: req.relation,
+        entry_role: req.entry_role
+      }],
+      ...req.where ? { where: req.where } : {},
+      ...req.include_provenance ? { include: { provenance: true } } : {},
+      page: {
+        ...req.limit != null ? { limit: req.limit } : {},
+        ...req.offset != null ? { offset: req.offset } : {}
+      }
+    });
+  }
   /**
-   * Read-only agent tool descriptors generated from the active ontology
-   * schema(s). Each maps to a generic `/ontology` read endpoint with
-   * `object_type` bound. Used by the MCP server to expose typed per-object
-   * tools (`search_customers`, `summarize_customer`, …).
+   * Schema-qualified read-tool descriptors generated from every active
+   * ontology. Includes per-object discovery/point/context tools,
+   * relation-and-role-specific related tools, and one structured composite.
    */
   async listOntologyTools() {
     return this.get("/v1/ontology/tools");
   }
-  async getDomainObject(uid) {
-    return this.get(`/ontology/object/${uid}`);
-  }
-  async getDomainObjectContext(uid, depth) {
-    const qs = depth != null ? `?depth=${depth}` : "";
-    return this.get(`/ontology/object/${uid}/context${qs}`);
+  async getDomainObject(uid, binding) {
+    const query = new URLSearchParams();
+    if (binding) {
+      query.set("schema_id", binding.schema_id);
+      query.set("object_type", binding.object_type);
+      if (binding.project_uid) query.set("project_uid", binding.project_uid);
+    }
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    return this.get(`/ontology/object/${uid}${suffix}`);
+  }
+  async getDomainObjectContext(uid, depth, binding) {
+    const query = new URLSearchParams();
+    if (depth != null) query.set("depth", String(depth));
+    if (binding) {
+      query.set("schema_id", binding.schema_id);
+      query.set("object_type", binding.object_type);
+      if (binding.project_uid) query.set("project_uid", binding.project_uid);
+    }
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    return this.get(`/ontology/object/${uid}/context${suffix}`);
   }
   async getDomainObjectHistory(uid) {
     return this.get(`/ontology/object/${uid}/history`);
@@ -855,6 +895,12 @@ var MindGraph = class {
     return this.post("/ontology/extract", req);
   }
 };
+function createRequestId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MindGraph,

package/dist/index.mjs

@@ -19,15 +19,21 @@ var MindGraph = class {
     if (config.orgId) {
       this.headers["X-MindGraph-Org"] = config.orgId;
     }
+    this.telemetrySurface = config.telemetrySurface;
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
+    const requestId = createRequestId();
     const init = {
       method,
-      headers: this.headers
+      headers: {
+        ...this.headers,
+        "X-MindGraph-Request-ID": requestId,
+        ...this.telemetrySurface ? { "X-MindGraph-Surface": this.telemetrySurface } : {}
+      }
     };
     if (body !== void 0) {
       init.body = JSON.stringify(body);
@@ -771,21 +777,55 @@ var MindGraph = class {
   async queryOntology(req) {
     return this.post("/ontology/query", req);
   }
+  async queryDomainStructured(req) {
+    return this.post("/ontology/query/structured", req);
+  }
+  async queryRelatedDomainObjects(req) {
+    return this.queryDomainStructured({
+      schema_id: req.schema_id,
+      select: req.far_type,
+      ...req.project_uid ? { project_uid: req.project_uid } : {},
+      anchor: { type: req.entry_type, uid: req.uid },
+      path: [{
+        relation: req.relation,
+        entry_role: req.entry_role
+      }],
+      ...req.where ? { where: req.where } : {},
+      ...req.include_provenance ? { include: { provenance: true } } : {},
+      page: {
+        ...req.limit != null ? { limit: req.limit } : {},
+        ...req.offset != null ? { offset: req.offset } : {}
+      }
+    });
+  }
   /**
-   * Read-only agent tool descriptors generated from the active ontology
-   * schema(s). Each maps to a generic `/ontology` read endpoint with
-   * `object_type` bound. Used by the MCP server to expose typed per-object
-   * tools (`search_customers`, `summarize_customer`, …).
+   * Schema-qualified read-tool descriptors generated from every active
+   * ontology. Includes per-object discovery/point/context tools,
+   * relation-and-role-specific related tools, and one structured composite.
    */
   async listOntologyTools() {
     return this.get("/v1/ontology/tools");
   }
-  async getDomainObject(uid) {
-    return this.get(`/ontology/object/${uid}`);
-  }
-  async getDomainObjectContext(uid, depth) {
-    const qs = depth != null ? `?depth=${depth}` : "";
-    return this.get(`/ontology/object/${uid}/context${qs}`);
+  async getDomainObject(uid, binding) {
+    const query = new URLSearchParams();
+    if (binding) {
+      query.set("schema_id", binding.schema_id);
+      query.set("object_type", binding.object_type);
+      if (binding.project_uid) query.set("project_uid", binding.project_uid);
+    }
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    return this.get(`/ontology/object/${uid}${suffix}`);
+  }
+  async getDomainObjectContext(uid, depth, binding) {
+    const query = new URLSearchParams();
+    if (depth != null) query.set("depth", String(depth));
+    if (binding) {
+      query.set("schema_id", binding.schema_id);
+      query.set("object_type", binding.object_type);
+      if (binding.project_uid) query.set("project_uid", binding.project_uid);
+    }
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    return this.get(`/ontology/object/${uid}/context${suffix}`);
   }
   async getDomainObjectHistory(uid) {
     return this.get(`/ontology/object/${uid}/history`);
@@ -828,6 +868,12 @@ var MindGraph = class {
     return this.post("/ontology/extract", req);
   }
 };
+function createRequestId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
 export {
   MindGraph,
   MindGraphError

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",