@promptev/context-engine 0.0.2 → 0.0.3

package/dist/mcp-BKSmxayM.d.cts

@@ -0,0 +1,204 @@
+import * as node_http from 'node:http';
+
+/**
+ * Sentinels distinguishing omitted arguments from real values, including null.
+ *
+ * UNSET: "argument omitted" vs null (e.g. updateDocument acl=null means unrestricted).
+ * TRUSTED: trusted caller, ACL filtering disabled. Truthy on purpose so
+ * `if (principals)` does not treat a trusted caller as anonymous.
+ */
+declare const UNSET: unique symbol;
+type Unset = typeof UNSET;
+declare const TRUSTED: unique symbol;
+declare const UNSCOPED: unique symbol;
+type Trusted = typeof TRUSTED;
+type Principals = string[] | null | typeof TRUSTED | undefined;
+declare function resolvePrincipals(value: Principals, method: string): string[] | null;
+
+/**
+ * `search_knowledge_base` — ONE tool with actions, as a plain library call.
+ *
+ * The four knowledge tools became sub-actions of one because that is better
+ * for the model calling them: one description carries the decision rules once,
+ * `discover` says what exists before it guesses, and there is one name to
+ * route through. Nothing here knows what MCP is.
+ *
+ * **Why it lives here and not in `mcp.ts`.** MCP is one way to reach the tool,
+ * not the only one. `engine.searchKnowledgeBase(...)` calls this directly;
+ * `mcp.ts` registers a tool that resolves the caller's identity and scope and
+ * then calls exactly the same function. Two doors, one implementation, so they
+ * cannot drift apart.
+ *
+ * **Identity and scope are arguments, never defaults.** This module invents
+ * neither a caller nor a ceiling. Both come from the program that mounted the
+ * tool — a model may ask for any source id it likes, and a tool that believed
+ * it would let one customer read another's files.
+ */
+
+declare const KNOWLEDGE_ACTIONS: readonly ["discover", "search", "get_doc", "list", "query_meta", "compute", "get_chunks", "get_docs", "map_reduce", "traverse", "find_related", "get_neighbors", "community_summary"];
+type KnowledgeAction = (typeof KNOWLEDGE_ACTIONS)[number];
+declare const KNOWLEDGE_TOOL_DESCRIPTION: string;
+/**
+ * The tool as data: name, description and input schema as JSON Schema.
+ *
+ * Exported so a host wiring this into its own agent loop, or into a protocol
+ * this library does not speak, never hand-writes the schema — that would be a
+ * third copy of the action list, and a third place for it to fall behind.
+ *
+ * `readOnlyHint` is false on purpose. Most actions only read, but `compute`
+ * runs generated code, and a host deciding whether to auto-approve a call must
+ * not read "knowledge base" and assume a reader.
+ */
+declare function knowledgeToolDefinition(): {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    annotations: Record<string, boolean>;
+};
+/**
+ * The documents a mounted tool may ever reach.
+ *
+ * Deliberately only the nouns the engine already knows: source ids, and
+ * optionally some document ids within them. Not project, workspace, tenant or
+ * agent — those are a host's words, and baking one in would make every other
+ * host translate its word into ours.
+ */
+type Scope = {
+    sourceIds: string[] | null;
+    documentIds: string[] | null;
+};
+type ScopeInput = typeof UNSCOPED | string[] | Partial<Scope> | null | undefined;
+/**
+ * Normalise what a host supplies into a `Scope`. `UNSCOPED` means no ceiling.
+ * `null`/omitted throws: it is what a host that forgot looks like, and
+ * defaulting it to "no ceiling" is the corpus-wide search this exists to stop.
+ */
+declare function resolveScope(value: ScopeInput): Scope;
+/**
+ * Intersect what the caller asked for with what the host allows.
+ *
+ * Narrow, never widen. `null` requested means the whole ceiling, never the
+ * whole corpus. An id outside the ceiling is DROPPED rather than refused,
+ * because an error would tell the caller which ids are real.
+ *
+ * The return value distinguishes two things that must never be confused: an
+ * array (possibly EMPTY — the caller asked only for things it may not have, so
+ * the answer is nothing) from `null` (no ceiling and no narrowing, no filter).
+ */
+declare function narrowToCeiling(requested: string[] | null | undefined, ceiling: string[] | null): string[] | null;
+/**
+ * A host's own compute. Running generated code is where a host has its own
+ * rules about permission, billing and approval, so it can replace ours rather
+ * than intercept the action before the tool is reached.
+ */
+type KnowledgeComputeFn = (instruction: string, opts: {
+    sourceIds: string[] | null;
+    documentIds: string[] | null;
+    principals: unknown;
+}) => Promise<Record<string, unknown>>;
+type Engine$1 = {
+    config: {
+        llm?: unknown;
+        enableCodeExecution?: boolean;
+        graph?: {
+            enabled?: boolean;
+        };
+    };
+    search: (query: string, opts?: Record<string, unknown>) => Promise<{
+        hits: unknown[];
+        usage?: unknown;
+    }>;
+    getDocument: (id: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    listDocuments: (opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    queryStructured?: (question: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    compute?: (instruction: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    ensurePool?: () => Promise<unknown>;
+    embedder?: unknown;
+    getChunks?: (id: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    getDocuments?: (ids: string[], opts?: Record<string, unknown>) => Promise<Array<Record<string, unknown>>>;
+    mapReduce?: (instruction: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+type KnowledgeToolArgs = {
+    action: string;
+    principals: unknown;
+    scope: ScopeInput;
+    query?: string | null;
+    document_id?: string | null;
+    source_ids?: string[] | null;
+    document_ids?: string[] | null;
+    entity?: string | null;
+    depth?: number | null;
+    category?: string | null;
+    label?: string | null;
+    entity_type?: string | null;
+    top_k?: number | null;
+    mode?: string | null;
+    limit?: number | null;
+    cursor?: unknown;
+    /** Overrides the deployment's configured policy for this call only. */
+    redaction?: unknown;
+    /** Replaces the built-in compute action. */
+    compute?: KnowledgeComputeFn | null;
+    /** Replaces the built-in map_reduce action — the other expensive one. */
+    map_reduce?: ((instruction: string, opts: Record<string, unknown>) => Promise<Record<string, unknown>>) | null;
+    start?: number | null;
+    end?: number | null;
+    max_chars?: number | null;
+};
+/** Run one action of the knowledge tool. */
+declare function callKnowledgeTool(engine: Engine$1, args: KnowledgeToolArgs): Promise<Record<string, unknown>>;
+
+type PrincipalsFn = () => unknown | Promise<unknown>;
+/** Zero-argument, sync or async, resolved fresh per execution — the same
+ * contract as `PrincipalsFn`. Returns the opaque approval scope (a run id is
+ * the expected shape) or `null` for the unscoped legacy path. */
+type ApprovalScopeFn = () => unknown | Promise<unknown>;
+
+type Engine = {
+    config: {
+        llm?: unknown;
+        enableCodeExecution?: boolean;
+    };
+    search: (query: string, opts?: Record<string, unknown>) => Promise<{
+        hits: unknown[];
+        usage?: unknown;
+    }>;
+    getDocument: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    listDocuments: (opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    queryStructured?: (question: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    compute?: (instruction: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    searchTools: (query: string, opts?: Record<string, unknown>) => Promise<unknown[]>;
+    executeTool: (name: string, args: Record<string, unknown> | null, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+declare function createMcpApp(engine: Engine, opts: {
+    principals: PrincipalsFn;
+    /**
+     * REQUIRED ceiling of source ids (or a `Scope`) this mounted tool may
+     * ever reach — resolved fresh per call like `principals` and NEVER a tool
+     * argument. A model can ask for any source id it likes, and a tool that
+     * believed it would let one caller read another's documents. A host with
+     * one shared corpus says so on purpose with `scope: UNSCOPED`.
+     */
+    scope: ScopeInput | (() => ScopeInput | Promise<ScopeInput>);
+    /**
+     * Overrides `config.redaction` per call, so a per-project or
+     * per-customer policy reaches this tool the way it already reaches
+     * `search`. Never a tool argument.
+     */
+    redaction?: unknown | (() => unknown | Promise<unknown>);
+    /**
+     * Optionally REPLACES the built-in compute action with the host's own
+     * callable. Running generated code is where a host has its own rules
+     * about permission, billing and approval; supplying one here means it
+     * does not have to intercept the action before the tool is reached, and
+     * makes the action available whatever `enableCodeExecution` says.
+     */
+    compute?: KnowledgeComputeFn | null;
+    /** The same seam for the other expensive action — one LLM call per document. */
+    mapReduce?: ((instruction: string, opts: Record<string, unknown>) => Promise<Record<string, unknown>>) | null;
+    approvalScope?: ApprovalScopeFn | null;
+}): Promise<((req: node_http.IncomingMessage, res: node_http.ServerResponse) => Promise<void>) & {
+    mcp: unknown;
+}>;
+
+export { type KnowledgeComputeFn as K, type Principals as P, type ScopeInput as S, type Trusted as T, type Unset as U, KNOWLEDGE_ACTIONS as a, KNOWLEDGE_TOOL_DESCRIPTION as b, type KnowledgeAction as c, type Scope as d, TRUSTED as e, UNSCOPED as f, UNSET as g, callKnowledgeTool as h, createMcpApp as i, resolveScope as j, knowledgeToolDefinition as k, narrowToCeiling as n, resolvePrincipals as r };

package/dist/mcp-BKSmxayM.d.ts

@@ -0,0 +1,204 @@
+import * as node_http from 'node:http';
+
+/**
+ * Sentinels distinguishing omitted arguments from real values, including null.
+ *
+ * UNSET: "argument omitted" vs null (e.g. updateDocument acl=null means unrestricted).
+ * TRUSTED: trusted caller, ACL filtering disabled. Truthy on purpose so
+ * `if (principals)` does not treat a trusted caller as anonymous.
+ */
+declare const UNSET: unique symbol;
+type Unset = typeof UNSET;
+declare const TRUSTED: unique symbol;
+declare const UNSCOPED: unique symbol;
+type Trusted = typeof TRUSTED;
+type Principals = string[] | null | typeof TRUSTED | undefined;
+declare function resolvePrincipals(value: Principals, method: string): string[] | null;
+
+/**
+ * `search_knowledge_base` — ONE tool with actions, as a plain library call.
+ *
+ * The four knowledge tools became sub-actions of one because that is better
+ * for the model calling them: one description carries the decision rules once,
+ * `discover` says what exists before it guesses, and there is one name to
+ * route through. Nothing here knows what MCP is.
+ *
+ * **Why it lives here and not in `mcp.ts`.** MCP is one way to reach the tool,
+ * not the only one. `engine.searchKnowledgeBase(...)` calls this directly;
+ * `mcp.ts` registers a tool that resolves the caller's identity and scope and
+ * then calls exactly the same function. Two doors, one implementation, so they
+ * cannot drift apart.
+ *
+ * **Identity and scope are arguments, never defaults.** This module invents
+ * neither a caller nor a ceiling. Both come from the program that mounted the
+ * tool — a model may ask for any source id it likes, and a tool that believed
+ * it would let one customer read another's files.
+ */
+
+declare const KNOWLEDGE_ACTIONS: readonly ["discover", "search", "get_doc", "list", "query_meta", "compute", "get_chunks", "get_docs", "map_reduce", "traverse", "find_related", "get_neighbors", "community_summary"];
+type KnowledgeAction = (typeof KNOWLEDGE_ACTIONS)[number];
+declare const KNOWLEDGE_TOOL_DESCRIPTION: string;
+/**
+ * The tool as data: name, description and input schema as JSON Schema.
+ *
+ * Exported so a host wiring this into its own agent loop, or into a protocol
+ * this library does not speak, never hand-writes the schema — that would be a
+ * third copy of the action list, and a third place for it to fall behind.
+ *
+ * `readOnlyHint` is false on purpose. Most actions only read, but `compute`
+ * runs generated code, and a host deciding whether to auto-approve a call must
+ * not read "knowledge base" and assume a reader.
+ */
+declare function knowledgeToolDefinition(): {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    annotations: Record<string, boolean>;
+};
+/**
+ * The documents a mounted tool may ever reach.
+ *
+ * Deliberately only the nouns the engine already knows: source ids, and
+ * optionally some document ids within them. Not project, workspace, tenant or
+ * agent — those are a host's words, and baking one in would make every other
+ * host translate its word into ours.
+ */
+type Scope = {
+    sourceIds: string[] | null;
+    documentIds: string[] | null;
+};
+type ScopeInput = typeof UNSCOPED | string[] | Partial<Scope> | null | undefined;
+/**
+ * Normalise what a host supplies into a `Scope`. `UNSCOPED` means no ceiling.
+ * `null`/omitted throws: it is what a host that forgot looks like, and
+ * defaulting it to "no ceiling" is the corpus-wide search this exists to stop.
+ */
+declare function resolveScope(value: ScopeInput): Scope;
+/**
+ * Intersect what the caller asked for with what the host allows.
+ *
+ * Narrow, never widen. `null` requested means the whole ceiling, never the
+ * whole corpus. An id outside the ceiling is DROPPED rather than refused,
+ * because an error would tell the caller which ids are real.
+ *
+ * The return value distinguishes two things that must never be confused: an
+ * array (possibly EMPTY — the caller asked only for things it may not have, so
+ * the answer is nothing) from `null` (no ceiling and no narrowing, no filter).
+ */
+declare function narrowToCeiling(requested: string[] | null | undefined, ceiling: string[] | null): string[] | null;
+/**
+ * A host's own compute. Running generated code is where a host has its own
+ * rules about permission, billing and approval, so it can replace ours rather
+ * than intercept the action before the tool is reached.
+ */
+type KnowledgeComputeFn = (instruction: string, opts: {
+    sourceIds: string[] | null;
+    documentIds: string[] | null;
+    principals: unknown;
+}) => Promise<Record<string, unknown>>;
+type Engine$1 = {
+    config: {
+        llm?: unknown;
+        enableCodeExecution?: boolean;
+        graph?: {
+            enabled?: boolean;
+        };
+    };
+    search: (query: string, opts?: Record<string, unknown>) => Promise<{
+        hits: unknown[];
+        usage?: unknown;
+    }>;
+    getDocument: (id: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    listDocuments: (opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    queryStructured?: (question: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    compute?: (instruction: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    ensurePool?: () => Promise<unknown>;
+    embedder?: unknown;
+    getChunks?: (id: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    getDocuments?: (ids: string[], opts?: Record<string, unknown>) => Promise<Array<Record<string, unknown>>>;
+    mapReduce?: (instruction: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+type KnowledgeToolArgs = {
+    action: string;
+    principals: unknown;
+    scope: ScopeInput;
+    query?: string | null;
+    document_id?: string | null;
+    source_ids?: string[] | null;
+    document_ids?: string[] | null;
+    entity?: string | null;
+    depth?: number | null;
+    category?: string | null;
+    label?: string | null;
+    entity_type?: string | null;
+    top_k?: number | null;
+    mode?: string | null;
+    limit?: number | null;
+    cursor?: unknown;
+    /** Overrides the deployment's configured policy for this call only. */
+    redaction?: unknown;
+    /** Replaces the built-in compute action. */
+    compute?: KnowledgeComputeFn | null;
+    /** Replaces the built-in map_reduce action — the other expensive one. */
+    map_reduce?: ((instruction: string, opts: Record<string, unknown>) => Promise<Record<string, unknown>>) | null;
+    start?: number | null;
+    end?: number | null;
+    max_chars?: number | null;
+};
+/** Run one action of the knowledge tool. */
+declare function callKnowledgeTool(engine: Engine$1, args: KnowledgeToolArgs): Promise<Record<string, unknown>>;
+
+type PrincipalsFn = () => unknown | Promise<unknown>;
+/** Zero-argument, sync or async, resolved fresh per execution — the same
+ * contract as `PrincipalsFn`. Returns the opaque approval scope (a run id is
+ * the expected shape) or `null` for the unscoped legacy path. */
+type ApprovalScopeFn = () => unknown | Promise<unknown>;
+
+type Engine = {
+    config: {
+        llm?: unknown;
+        enableCodeExecution?: boolean;
+    };
+    search: (query: string, opts?: Record<string, unknown>) => Promise<{
+        hits: unknown[];
+        usage?: unknown;
+    }>;
+    getDocument: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    listDocuments: (opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    queryStructured?: (question: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    compute?: (instruction: string, opts?: Record<string, unknown>) => Promise<unknown>;
+    searchTools: (query: string, opts?: Record<string, unknown>) => Promise<unknown[]>;
+    executeTool: (name: string, args: Record<string, unknown> | null, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+declare function createMcpApp(engine: Engine, opts: {
+    principals: PrincipalsFn;
+    /**
+     * REQUIRED ceiling of source ids (or a `Scope`) this mounted tool may
+     * ever reach — resolved fresh per call like `principals` and NEVER a tool
+     * argument. A model can ask for any source id it likes, and a tool that
+     * believed it would let one caller read another's documents. A host with
+     * one shared corpus says so on purpose with `scope: UNSCOPED`.
+     */
+    scope: ScopeInput | (() => ScopeInput | Promise<ScopeInput>);
+    /**
+     * Overrides `config.redaction` per call, so a per-project or
+     * per-customer policy reaches this tool the way it already reaches
+     * `search`. Never a tool argument.
+     */
+    redaction?: unknown | (() => unknown | Promise<unknown>);
+    /**
+     * Optionally REPLACES the built-in compute action with the host's own
+     * callable. Running generated code is where a host has its own rules
+     * about permission, billing and approval; supplying one here means it
+     * does not have to intercept the action before the tool is reached, and
+     * makes the action available whatever `enableCodeExecution` says.
+     */
+    compute?: KnowledgeComputeFn | null;
+    /** The same seam for the other expensive action — one LLM call per document. */
+    mapReduce?: ((instruction: string, opts: Record<string, unknown>) => Promise<Record<string, unknown>>) | null;
+    approvalScope?: ApprovalScopeFn | null;
+}): Promise<((req: node_http.IncomingMessage, res: node_http.ServerResponse) => Promise<void>) & {
+    mcp: unknown;
+}>;
+
+export { type KnowledgeComputeFn as K, type Principals as P, type ScopeInput as S, type Trusted as T, type Unset as U, KNOWLEDGE_ACTIONS as a, KNOWLEDGE_TOOL_DESCRIPTION as b, type KnowledgeAction as c, type Scope as d, TRUSTED as e, UNSCOPED as f, UNSET as g, callKnowledgeTool as h, createMcpApp as i, resolveScope as j, knowledgeToolDefinition as k, narrowToCeiling as n, resolvePrincipals as r };