mindgraph 0.12.0 → 0.14.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Shuruheel Ahamed
+Copyright (c) 2024 Syed Shan-E-Haider Rizvi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/index.d.mts

@@ -190,7 +190,7 @@ interface CaptureRequest {
     agent_id?: string;
 }
 interface EntityRequest {
-    action: "create" | "alias" | "resolve" | "fuzzy_resolve" | "merge" | "relate";
+    action: "create" | "resolve_identity" | "alias" | "resolve" | "fuzzy_resolve" | "merge" | "relate";
     label?: string;
     text?: string;
     canonical_uid?: string;
@@ -203,6 +203,14 @@ interface EntityRequest {
     edge_type?: string;
     props?: Record<string, unknown>;
     agent_id?: string;
+    /** Server-canonicalized exact identity. Values may contain only strings and integers. */
+    identity?: {
+        namespace: string;
+        key_version: 1;
+        key: unknown;
+    };
+    /** Explicit writable Project/repository/agent Space for an identity-backed create. */
+    identity_space_uid?: string;
 }
 interface ArgumentRequest {
     claim: {
@@ -330,6 +338,9 @@ interface SessionRequest {
     salience?: number;
     session_uid?: string;
     relevant_node_uids?: string[];
+    harness?: "claude-code" | "codex" | "generic";
+    harness_session_id?: string;
+    model?: string;
     props?: Record<string, unknown>;
     agent_id?: string;
 }
@@ -342,6 +353,10 @@ interface DistillRequest {
     salience?: number;
     summarizes_uids?: string[];
     session_uid?: string;
+    work_uid?: string;
+    execution_uid?: string;
+    idempotency_key?: string;
+    supersedes_uid?: string;
     props?: Record<string, unknown>;
     agent_id?: string;
 }
@@ -354,8 +369,31 @@ interface MemoryConfigRequest {
     props?: Record<string, unknown>;
     agent_id?: string;
 }
+interface MemorySyncRequest {
+    action: "scan" | "begin" | "record" | "finalize" | "status" | "abandon";
+    provider?: string;
+    repo_id?: string;
+    logical_path?: string;
+    content_hash?: string;
+    content?: string;
+    source_uid?: string;
+    execution_uid?: string;
+    assertion_fingerprint?: string;
+    planned_fingerprints?: string[];
+    current_fingerprints?: string[];
+    source_selector?: Record<string, unknown>;
+    capture_type?: "lesson" | "journal" | "claim" | "decision" | "risk";
+    label?: string;
+    summary?: string;
+    props?: Record<string, unknown>;
+    expected_execution_version?: number;
+    baseline_version?: number;
+    repo_space_uid?: string;
+    file_present?: boolean;
+    agent_id?: string;
+}
 interface PlanRequest {
-    action: "create_task" | "create_plan" | "add_step" | "update_status" | "get_plan";
+    action: "create_task" | "create_plan" | "add_step" | "update_status" | "get_plan" | "resume_work" | "claim_task" | "heartbeat" | "start_iteration" | "checkpoint_iteration" | "block_task" | "complete_task" | "abandon_iteration";
     label?: string;
     summary?: string;
     confidence?: number;
@@ -363,15 +401,39 @@ interface PlanRequest {
     goal_uid?: string;
     task_uid?: string;
     plan_uid?: string;
+    step_uid?: string;
+    execution_uid?: string;
+    session_uid?: string;
     depends_on_uids?: string[];
     target_uid?: string;
     status?: string;
+    task_status?: string;
+    step_status?: string;
+    execution_status?: "completed" | "failed" | "abandoned";
+    expected_version?: number;
+    lease_epoch?: number;
+    lease_ttl_secs?: number;
+    idempotency_key?: string;
+    allow_takeover?: boolean;
+    release_lease?: boolean;
+    override_reason?: string;
+    scope_uids?: string[];
+    limit?: number;
+    input_snapshot?: Record<string, unknown>;
+    output_snapshot?: Record<string, unknown>;
+    side_effects?: string[];
+    outcome?: string;
+    error?: string;
+    next_action?: string;
+    checkpoint_summary?: string;
+    test_summary?: string;
+    produces_node_uids?: string[];
     related_uids?: string[];
     props?: Record<string, unknown>;
     agent_id?: string;
 }
 interface GovernanceRequest {
-    action: "create_policy" | "set_budget" | "request_approval" | "resolve_approval" | "get_pending";
+    action: "create_policy" | "set_budget" | "request_approval" | "resolve_approval" | "get_pending" | "check";
     label?: string;
     summary?: string;
     confidence?: number;
@@ -380,9 +442,30 @@ interface GovernanceRequest {
     approval_uid?: string;
     approved?: boolean;
     requires_plan_uid?: string;
+    act?: string;
+    target?: GovernanceTarget;
+    purpose?: string;
+    context?: Record<string, unknown>;
+    mode?: "permit_default" | "deny_default";
+    tier?: "native" | "checkpoint" | "advisory" | "dry_run";
     props?: Record<string, unknown>;
     agent_id?: string;
 }
+interface GovernanceTarget {
+    node_uid?: string;
+    document_uid?: string;
+    node_type?: string;
+    ontology_class?: string;
+    tags?: string[];
+    space?: string;
+    classifications?: string[];
+    tool_name?: string;
+    tool_annotations?: string[];
+    execution_uid?: string;
+    action?: string;
+    mutability?: "read" | "write";
+    target_uids?: string[];
+}
 interface ExecutionRequest {
     action: "start" | "complete" | "fail" | "register_agent" | "get_executions";
     label?: string;
@@ -391,10 +474,16 @@ interface ExecutionRequest {
     salience?: number;
     plan_uid?: string;
     executor_uid?: string;
+    affordance_uid?: string;
     execution_uid?: string;
     produces_node_uid?: string;
     filter_plan_uid?: string;
     related_uids?: string[];
+    input_snapshot?: Record<string, unknown>;
+    output_snapshot?: Record<string, unknown>;
+    side_effects?: string[];
+    outcome?: string;
+    error?: string;
     props?: Record<string, unknown>;
     agent_id?: string;
 }
@@ -415,6 +504,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 +619,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 +685,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 +964,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 +1247,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 +1381,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 +1509,9 @@ interface OntologyQueryResponse {
     confidence: {
         overall: number;
     };
+    returned_count: number;
+    has_more: boolean;
+    seed_cap_hit: boolean;
     truncated?: Record<string, boolean>;
 }
 interface LinkDomainObjectsRequest {
@@ -1339,6 +1550,7 @@ declare class MindGraph {
     private headers;
     private maxRetries;
     private retryBackoffMs;
+    private telemetrySurface?;
     constructor(config: MindGraphConfig);
     private request;
     private get;
@@ -1462,6 +1674,7 @@ declare class MindGraph {
     }): Promise<unknown>;
     distill(req: DistillRequest): Promise<unknown>;
     memoryConfig(req: MemoryConfigRequest): Promise<unknown>;
+    memorySync(req: MemorySyncRequest): Promise<unknown>;
     plan(req: PlanRequest): Promise<unknown>;
     governance(req: GovernanceRequest): Promise<unknown>;
     execution(req: ExecutionRequest): Promise<unknown>;
@@ -1555,6 +1768,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 +1782,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 +2022,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 +2066,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 +2119,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 GovernanceTarget, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, type MemorySyncRequest, 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 };