Context Engine TypeScript API

ingest

Ingest one document. Exactly one of file, content or text must be given; text skips extraction. Size and row caps (ingest.maxFileBytes, ingest.maxRows) are checked before any connection is opened. A failure while processing the document does not throw: it comes back as status: "failed" in the report. There is no principals option: ingest is a trusted, host-side call.

ingest(opts?: {
  file?: unknown;               // a path, a Buffer, a multer-style { buffer, originalname }, or a handle with read()
  content?: Buffer | null;
  filename?: string | null;
  text?: string | null;
  name?: string | null;
  description?: string | null;
  sourceId?: string | null;
  externalId?: string | null;
  metaData?: Record<string, unknown> | null;
  acl?: string[] | null;
  mode?: "hybrid" | "graph";
  extractStructured?: boolean;
  fieldHints?: Record<string, unknown>[] | null;
  mimeType?: string | null;
}): Promise<IngestReport>

Returns: IngestReport: { documents: DocumentReport[], totals: { files, failed, units, graphUnits } }. The error on each document report is masked by the configured output redaction policy.

Errors: Error unless exactly one of file, content or text is given; IngestTooLarge over a cap; Error for mode: "graph" with graph disabled, for extractStructured without a model, and for fieldHints without extractStructured.

const report = await engine.ingest({
  file: "./handbook.pdf",
  sourceId: "hr-handbook",
  externalId: "handbook-2026",
  acl: ["group:hr"],
});
const doc = report.documents[0];
if (doc.status === "failed") console.warn(doc.failureReason, doc.failureMessage);

resumeEmbeddings

Fill in the vectors an interrupted or failed run did not reach. Chunks are stored before they are embedded, so only rows still missing a vector are sent; nothing is re-extracted or re-chunked and the source file is not needed. Omit documentId to sweep resumable documents, oldest first (up to 100 per call). A document with nothing pending is completed and otherwise left alone, so this is safe to run from a cron job.

resumeEmbeddings(documentId?: string | null): Promise<IngestReport>

Returns: An IngestReport covering every document it touched.

await engine.resumeEmbeddings(documentId); // one document
await engine.resumeEmbeddings();           // every resumable document

resumeDocuments

Ask your model or embedder again for every document parked as waiting_model after it threw ModelDeferred. It re-runs the parked stage under the same request keys; a document that defers again parks again with rounds incremented. Omit documentIds to sweep the parked documents whose retry_at has passed (the database clock), oldest first, in pages of 100, each claimed with one compare-and-set, so a cron on several workers never asks you twice. Every call also fills the community summaries a source is still missing (that needs storage.poolMax of at least 2). See Batch mode.

resumeDocuments(opts?: {
  documentIds?: string[] | null;
  contentSource?: ContentSource | null;
}): Promise<ResumeReport>

Returns: ResumeReport: { documents, skipped, superseded, communitiesResumed }. skipped is { documentId, reason } per document left parked on this call (no_content_source, content_mismatch, redaction_mismatch); superseded is one SupersededPark (documentId, requestKeys, supersededAt, reason: "superseded" or "failed") per set of keys nobody will ask for again, reported once.

const report = await engine.resumeDocuments({ contentSource: (doc) => blobs.get(doc.documentId) });
for (const park of report.superseded) await batch.drop(park.requestKeys); // nobody asks for these again

search

Hybrid retrieval (full text, trigram and vector legs, fused) plus an optional graph leg. With mode omitted or null, the graph leg runs only when the deployment has a graph, it is reachable, and the query names an entity the caller can see. "graph" forces the leg; a query that names no entity still gets the hybrid answer. The graph leg adds to the hybrid legs, never replaces them.

search(query: string, opts?: {
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  topK?: number;
  mode?: "hybrid" | "graph" | null;
  compressToTokens?: number | null;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<SearchResult>

Returns: SearchResult: { hits: Hit[], usage }. usage carries kind, units, mode (asked for), modeUsed (what ran), graph ({ applied, reason, entities }, reason from GRAPH_REASONS), graphLeg, degraded, scopes, legs, legHits, candidates, returned, reranked, compressed, providerTokens, and redaction when a rule fired.

Errors: TypeError for a non-array principals; ExtraMissingError when graph mode is on but its peer packages are missing. With an explicit mode: "graph", a failure to resolve the query’s entities throws instead of falling back.

const { hits, usage } = await engine.search("what did the CFO say about Q3", {
  principals: ["group:finance"],
  mode: "graph",
});
usage.modeUsed;       // "hybrid" when the query named no known entity
usage.graph.reason;   // e.g. "no_entities_in_query"

documentsByName

Find documents by their name rather than their text; the knowledge tool’s search uses it when a query names a file. Metered like a search (one unit per scope) only when something matched; a name query that matched nothing is free and emits no usage event.

documentsByName(filename: string, opts?: {
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  limit?: number;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<{ documents: DocumentByName[]; usage: Record<string, unknown> }>

Returns: documents: [{ document_id, name, score, snippet, source_id, chunk_idx }]; usage with kind: "search", matched_by: "filename", units, scopes, empty legs and legHits, and returned.

getDocument

One document with its full text. Output redaction masks text, documentType, structuredData and error; name, description and metaData are caller-set and left as stored.

getDocument(documentId: string, opts?: {
  principals?: string[] | typeof TRUSTED;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<Record<string, unknown>>

Returns: { id, sourceId, externalId, name, description, metaData, acl, mode, mimeType, lang, text, status, error, failureReason, chunks, documentType, structuredData, createdAt, updatedAt, startedAt, completedAt, unreadableReason, unreadablePages, embeddingProgress }

Errors: EngineActionError for an id that is not a UUID; DocumentNotFoundError when the document is missing or not visible (one message for both, so a caller cannot tell them apart).

const doc = await engine.getDocument(id, { principals: ["group:hr"] });
doc.status;            // "embedding" is non-terminal: in flight or stopped part-way
doc.embeddingProgress; // { done, total, tokens } or null

getDocumentText

Just the text, untruncated, masked by the configured output policy. Token budgeting is the caller’s job.

getDocumentText(documentId: string, opts?: { principals?: string[] | typeof TRUSTED }): Promise<string>

Returns: The document text.

Errors: Same as getDocument.

getDocuments

Several documents, each ACL-checked like getDocument. An id that is missing or not visible is left out of the result, never reported.

getDocuments(documentIds: string[], opts?: {
  principals?: string[] | typeof TRUSTED;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<Array<Record<string, unknown>>>

Returns: An array of the same objects getDocument returns.

getChunks

Read one document in order, a range of chunks at a time. At most 25 chunks per call; end is inclusive and clamped to that window.

getChunks(documentId: string, opts?: {
  principals?: string[] | typeof TRUSTED;
  start?: number | null;
  end?: number | null;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<Record<string, unknown>>

Returns: { document_id, total_chunks, start, end, chunks: [{ position, text, language }], has_more, next_start }

Errors: Same as getDocument.

let page = await engine.getChunks(id, { principals: TRUSTED });
while (page.has_more) {
  page = await engine.getChunks(id, { principals: TRUSTED, start: page.next_start as number });
}

listDocuments

Page through visible documents, newest first, with keyset pagination. Output redaction masks documentType.

listDocuments(opts?: {
  sourceId?: string | null;
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  cursor?: unknown;
  limit?: number;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<Record<string, unknown>>

Returns: { documents, count, hasMore, nextCursor? }. Each document: id, sourceId, externalId, name, description, mode, mimeType, lang, status, failureReason, documentType, createdAt, updatedAt, unreadableReason, unreadablePages, embeddingProgress, acl. nextCursor ({ time, id }) is present only when hasMore.

let page = await engine.listDocuments({ sourceId: "hr-handbook", principals: ["group:hr"] });
while (page.hasMore) {
  page = await engine.listDocuments({
    sourceId: "hr-handbook", principals: ["group:hr"], cursor: page.nextCursor,
  });
}

updateDocument

Change caller-set attributes without re-sending content. PATCH semantics: only fields you pass change. acl: null makes the document unrestricted; omit the field (or pass UNSET) to leave it alone. metaData is merged into the stored object, not replaced. Passing acl always re-syncs the ACL onto the chunks.

updateDocument(documentId: string, opts?: {
  acl?: string[] | null | typeof UNSET;
  name?: string | null | typeof UNSET;
  description?: string | null | typeof UNSET;
  metaData?: Record<string, unknown> | null | typeof UNSET;
  principals?: string[] | typeof TRUSTED;
}): Promise<string[]>

Returns: The fields that actually changed, from "acl", "name", "description", "meta_data". An empty array when nothing changed.

Errors: Same as getDocument; checked before anything is written.

const changed = await engine.updateDocument(id, {
  acl: ["group:legal"],
  metaData: { reviewed: true },
  principals: ["group:hr"],
}); // ["acl", "meta_data"]

deleteDocument

Delete a document and all of its chunks. With graph mode on it also repairs the graph mirror the document leaves behind; a failure there is logged and sent to onError with stage: "delete_document_graph" and never fails the delete.

deleteDocument(documentId: string, opts?: { principals?: string[] | typeof TRUSTED }): Promise<void>

Returns: Nothing.

Errors: Same as getDocument, checked before anything is deleted.

stats

Counts for the whole corpus or one source, as the caller sees it: TRUSTED counts everything, [] only unrestricted rows, a list the rows its acl overlaps. Omitted, it counts everything, as before.

stats(sourceId?: string | null, opts?: { principals?: Principals }): Promise<Record<string, unknown>>

Returns: { sourceId, documents, chunks, byStatus: { [status]: count }, embedding: { provider, model, dim } }

await engine.stats();              // whole corpus
await engine.stats("hr-handbook"); // one source

resyncGraph

Bring Neo4j back in line with the Postgres graph. Only a deployment with graph.neo4jUri set has anything to do here: Postgres is written first and is always complete, and a Neo4j write that still fails after its retries leaves that document out of Neo4j, reported as graphBackendStale on the document, through onError with stage graph_sync, and as graph_sync_pending in the document’s metadata. With no argument this replays every document recorded that way, each with its own entities and relationships, and retries every removal Neo4j still owes. full: true replays the whole corpus (every entity, every graph document, every relationship), then removes from Neo4j what Postgres no longer has; its cost follows the corpus. Run the full replay once after upgrading, and whenever the two stores must be made identical whatever happened before. Idempotent, calls no model, bills nothing. Needs graph mode. A maintenance call for the host: it takes no principals, and no router, tool or MCP action reaches it.

resyncGraph(opts?: {
  documentId?: string | null;
  sourceId?: string | null;
  full?: boolean;
}): Promise<ResyncResult>

Returns: { documents, synced, failed }, where failed lists document ids that keep their record. Three more keys appear only when they have something to say: removals: { done, failed }; with full, removed: { chunks, relationships, entities }; and error, a failure of a corpus-wide step of the full replay. Without a neo4jUri the result is all zeros.

Errors: InvalidInputError without graph mode, when both documentId and sourceId are given, or when full is combined with either. DocumentNotFoundError when documentId names no document.

await engine.resyncGraph();                     // documents recorded as pending
await engine.resyncGraph({ sourceId: "hr-handbook" });
await engine.resyncGraph({ full: true });       // once after upgrading

rebuildCommunities

Detect, summarise and store one source’s communities again, reading and writing only that source. Use it for a source whose communities are missing (none built yet, or removed by a delete) and that gets no graph ingest to rebuild them. Needs graph mode. Summaries and their embeddings are written only with graph.communitySummaries on; off, it detects and stores the communities with no model call, bills 0 units, and drops the source’s existing summaries. Metered to onUsage as graph units with detail.operation === "rebuild_communities".

rebuildCommunities(sourceId: string | null): Promise<Record<string, unknown>>

Returns: { communities_detected, communities_summarized, primary_communities, units }

await engine.rebuildCommunities("hr-handbook");

enableBm25

Opt this database in to the experimental search.lexicalRank: "bm25". Installs four triggers on the chunk table (its lock is taken briefly, with a 2-second timeout and retries) and counts the chunks already stored without blocking ingest. Idempotent; running it again recounts. Until it has finished, a bm25 search ranks with ts_rank_cd, reports a LexicalRankFallback to onError and says so in usage.lexical. disableBm25() removes the triggers and statistics; compactBm25Stats() folds the statistics rows each write adds and never blocks a writer. Also npx context-engine bm25-enable.

enableBm25(): Promise<Bm25EnableReport>

Returns: { createdTriggers, sources: [{ sourceId, chunks }] }

await engine.enableBm25();

spreadsheetSchema

Sheet names, column headers and row counts for the named spreadsheets, so a model can write one correct compute call. ACL and scope are applied again; a document that is not visible, not in scope or not tabular is simply absent. An empty documentIds returns an empty array. Output redaction masks sheet names and headers.

spreadsheetSchema(opts: {
  documentIds: string[];
  sourceIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<SpreadsheetDescription[]>

Returns: [{ document_id, name, source_id, sheets, schema_unavailable? }]. sheets is null (with a reason) for a document past the read budget.

documentStructure

What is inside each named document whatever its type: sheets and columns for a workbook, sections and the last page for a document with headings, top-level keys for JSON, and a chunk count for everything.

documentStructure(opts: {
  documentIds: string[];
  sourceIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  bounded?: boolean;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<Record<string, DocumentStructure>>

Returns: An object keyed by document id.

tabularScope

Whether everything in scope is a spreadsheet, and what the first one looks like. One grouped query over the document table.

tabularScope(opts?: {
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<TabularScope>

Returns: { documents, tabular, all_tabular, sheet, frame_key }

documentTypes

A census of the visible corpus. kind comes from the mime type and is always known; type is the LLM-written document type and exists only where structured extraction ran.

documentTypes(opts?: {
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<DocumentTypeCount[]>

Returns: [{ kind: "spreadsheet" | "text", type, documents, with_fields }]

fieldSummary

Extracted structured field names grouped by the same (kind, type) pair documentTypes uses, counted over the documents the caller can see.

fieldSummary(opts?: {
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<FieldGroup[]>

Returns: [{ kind, type, fields: [{ field, type, documents }], more_fields? }]. more_fields lists the names past the per-group cap and is absent when nothing was left out.

queryStructured

Filter documents by the structured fields extraction stored for them. The question is resolved to known field names first.

queryStructured(question: string, opts?: {
  sourceIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  docType?: string | null;
  limit?: number;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<Record<string, unknown>>

Returns: { question, resolvedFields, documents, count }

Errors: EngineActionError for an empty question.

compute

Answer a question over every row of the in-scope spreadsheets (CSV, TSV, XLSX): an LLM writes code, which runs over dataframes in a sandbox, with one retry on failure. Off by default: set enableCodeExecution: true only where execution is isolated. Pass a codeRunner to the constructor to run the code in your own isolation boundary. Needs the danfojs-node and isolated-vm peers.

compute(instruction: string, opts?: {
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  principals?: string[] | typeof TRUSTED;
  modelCfg?: LLMConfig | null;
  timeout?: number;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
  model?: ModelFn | null;
}): Promise<Record<string, unknown>>

Returns: { success, result, code, stdout, error, executionTime, documentsUsed, providerTokens: { llm_input, llm_output }, attempts }

Errors: EngineActionError when code execution is disabled, when no tabular document is in scope, or when more than 50 are; Error with no LLM configured; ExtraMissingError without danfojs-node.

const out = await engine.compute("total revenue by region for 2025", {
  sourceIds: ["finance"],
  principals: ["group:finance"],
});
if (out.success) console.log(out.result);

mapReduce

Ask the same question of every document in scope, one LLM call per document, newest first. A document that fails is reported in the results, not thrown.

mapReduce(instruction: string, opts?: {
  principals?: string[] | typeof TRUSTED;
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  limit?: number | null;
  maxConcurrency?: number | null;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
}): Promise<Record<string, unknown>>

Returns: { results, processed, failed, considered }. Each result carries document_id and document_name with data, or an error.

Errors: EngineActionError when no LLM is configured.

mapReduceTargets

The document ids mapReduce would read, newest first, without calling a model.

mapReduceTargets(opts?: {
  principals?: string[] | typeof TRUSTED;
  sourceIds?: string[] | null;
  documentIds?: string[] | null;
  limit?: number | null;
}): Promise<string[]>

Returns: An array of document ids.

searchKnowledgeBase

The one knowledge tool as a library call: the same function the MCP server serves, for a host running its own agent loop. Arguments use the tool’s snake_case names. scope is required: pass the source ids this call may reach, or UNSCOPED to mean the whole corpus on purpose; ids the model asks for outside the ceiling are dropped. The actions and their answers are documented on the knowledge tool page.

searchKnowledgeBase(args: {
  action: string;               // one of KNOWLEDGE_ACTIONS
  principals?: string[] | typeof TRUSTED;
  scope: ScopeInput;            // required ceiling: source ids, a Scope, or UNSCOPED
  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;
  start?: number | null;
  end?: number | null;
  max_chars?: number | null;
  redaction?: RedactionPolicy | null;
  secret_key?: string | null;
  compute?: KnowledgeComputeFn | null;
  map_reduce?: ((instruction: string, opts: Record<string, unknown>) => Promise<Record<string, unknown>>) | null;
}): Promise<Record<string, unknown>>

Returns: The action’s answer. An action the deployment cannot serve answers { success: false, error }.

Errors: Error when scope is null or omitted.

import { knowledgeToolDefinition } from "@promptev/context-engine";

const tool = knowledgeToolDefinition(); // { name, description, input_schema, annotations }

// inside your agent loop, when the model calls the tool:
const answer = await engine.searchKnowledgeBase({
  ...modelArgs,                 // action, query, document_id, ...
  principals: ["user:alice"],   // from your session, never from the model
  scope: ["hr-handbook"],
});

registerTool

Persist an http, db or mcp tool. Its config is encrypted at rest with config.secretKey. The model-facing call name is the kind prefix plus the name: http_, db_, mcp_.

registerTool(tc: ToolConfig): Promise<string>

Returns: The new tool id (a UUID).

Errors: Error for an invalid response_mode or a config that still holds the __redacted__ placeholder. ConfigTemplateError for an mcp config with an invalid connection setting or a URL that carries a user name or password.

import { ToolConfig } from "@promptev/context-engine";

const id = await engine.registerTool(new ToolConfig({
  name: "get_weather",
  kind: "http",
  description: "Fetch the current weather for a city",
  config: {
    method: "GET",
    url: "https://api.example.com/weather",
    headers: { Authorization: "Bearer YOUR_TOKEN" },
    llmQueryParameters: { properties: { city: { type: "string" } }, required: ["city"] },
  },
  acl: ["group:ops"],
})); // call name "http_get_weather"

registerFunctionTool

Register a plain function as an in-memory tool (not persisted; re-register on start). The call name is fn_ plus the function’s name. Parameter names are read from the function’s source and every parameter is described as a string; fn.length decides which are required. A doc property on the function becomes the description. executeTool passes arguments by name. The same schema is available without registering from the exported functionTool(fn).

registerFunctionTool(fn: (...args: never[]) => unknown): string

Returns: The call name.

function add(a: string, b: string) {
  return Number(a) + Number(b);
}
engine.registerFunctionTool(add); // "fn_add"
await engine.executeTool("fn_add", { a: "2", b: "3" }, { principals: TRUSTED });

updateTool

Update a stored tool. Accepted fields: name, kind, description, sourceId, acl, requiresApproval, approvalPolicy, enabled, metaData, config (snake_case spellings also work). __redacted__ values in a new config keep the stored secret for that key.

updateTool(id: string, opts?: Record<string, unknown> & {
  principals?: string[] | typeof TRUSTED;
}): Promise<ToolConfig>

Returns: The updated ToolConfig.

Errors: EngineActionError tool not found when missing or not visible; Error for placeholder misuse or an undecryptable stored config.

deleteTool

Delete a stored tool.

deleteTool(id: string, opts?: { principals?: string[] | typeof TRUSTED }): Promise<void>

Returns: Nothing.

Errors: EngineActionError tool not found when missing or not visible.

listTools

Every tool the caller may see: stored tools plus function tools.

listTools(opts?: { sourceId?: string | null; principals?: string[] | typeof TRUSTED }): Promise<Record<string, unknown>[]>

Returns: [{ name, tool_id, kind, description, params_schema, requires_approval }]. name is the call name.

searchTools

Keyword search over visible tools’ names and descriptions. query ranks and also excludes tools none of its terms match; kind, nameContains (case-insensitive) and requiresApproval filter, combined with AND. An empty query with filters lists the filtered set.

searchTools(query: string, opts?: {
  sourceId?: string | null;
  principals?: string[] | typeof TRUSTED;
  limit?: number;
  kind?: string | string[] | null;
  nameContains?: string | null;
  requiresApproval?: boolean | null;
  cursor?: string | null;
}): Promise<ToolSearchPage>

Returns: An array of the same objects listTools returns, with a non-enumerable nextCursor property when more remain.

testTool

Probe a tool configuration before saving it, under the same egress policy the executor uses.

testTool(tc: ToolConfig): Promise<Record<string, unknown>>

Returns: An object with ok. A failed probe is a result carrying error (a category), not an exception; an mcp probe that succeeds also lists the server’s tools, and an HTTP+SSE or WebSocket MCP URL is reported as unsupported_transport.

Errors: Error when the config holds the __redacted__ placeholder. ConfigTemplateError for an mcp config with an invalid connection setting (protocol, redirects, the two elicitation keys) or a URL that carries a user name or password.

executeTool

Run a visible tool and write an audit row. A tool that requires approval (or whose approvalPolicy.condition matches the arguments) does not run: it returns an approval_required record until the approval is resolved, then the same call runs once. Argument keys starting with an underscore are stripped. Every call whose tool was started leaves one audit row: if the full row cannot be written a last-resort row is (input_args set to { "_unstorable": true }, no result, output_truncated true, an error note naming what failed), and it depends on no other row. A tool or an approval deleted while the call ran costs the row only its reference: the row keeps its real arguments and result, with tool_id and approval_id NULL and a note in error_message, so filter audit rows on success, not on error_message. A tool that throws anything is a failed call with a failed row. JavaScript cannot cancel a promise: a caller that races executeTool against a timeout only stops waiting, and the call runs on to its audit row, so the Python package’s tools.audit_cancel_wait_s has no counterpart here. What cannot be recorded is a process that dies between the tool running and the insert. On the route handlers, over MCP and in the audit row a result keeps its JSON form: a Date is ISO 8601 text, and a value with a toJSON method is what that returns. Only a value JSON cannot carry is changed: a lone surrogate becomes U+FFFD, a non-finite number the text "NaN", "Infinity" or "-Infinity", U+0000 is removed, a bigint becomes its digits as text, and a property whose value is undefined is sent as null. A generator, an iterator or an async iterator has no JSON form and is sent and stored as {}: return an array. Called in process, the tool’s own value is returned unchanged. An approval matches its arguments exactly, by canonical JSON form: key order does not matter, and 1, true and "1" are three different arguments, while two spellings of one number are the same argument (1e16 and 10000000000000000, 0 and -0).

executeTool(callName: string, args: Record<string, unknown> | null, opts?: {
  sourceId?: string | null;
  principals?: string[] | typeof TRUSTED;
  actor?: Record<string, unknown> | null;
  source?: string;
  approvalScope?: string | null;
  resultMaxChars?: number | null;
  resultMaxRows?: number | null;
  responseMode?: "json" | "tsv" | null;
  redaction?: RedactionPolicy | null;
  secretKey?: string | null;
  toolId?: string | null;
  overrides?: { headers?: Record<string, string>; query?: Record<string, unknown>; body?: Record<string, unknown> } | null;
}): Promise<Record<string, unknown>>

Returns: { result, usage: { units: 1, kind: "tool", tool_name, tool_id, truncated } }, or { approval_required: { approval_id, tool_name, tool_id, args, reason, expires_at } }.

Errors: EngineActionError tool not found (unknown, invisible or wrong id all read the same) and tool execution failed; AmbiguousToolError when the name matches more than one visible tool and no toolId is given. InvalidInputError before the tool runs, and before any approval is opened, when an argument cannot be stored: broken Unicode (a lone surrogate), a non-finite number, nesting deeper than 64 levels, or a value that is not a JSON value (a Map, a Date, a function, any class instance); the message names the argument’s path and never its value. A NUL character (U+0000) in an argument is removed, not refused. ToolAuditFailed when the tool ran and no audit row could be written at all, with tools.auditOnFailure at "fail": it carries the result, so do not send the call again.

import { resolveApproval } from "@promptev/context-engine";

const out = await engine.executeTool("http_get_weather", { city: "Lahore" }, {
  principals: ["user:a"],
  approvalScope: "run-42",
});
if ("approval_required" in out) {
  const { approval_id } = out.approval_required as { approval_id: string };
  await resolveApproval(engine, approval_id, "approved", "boss");
  // the same call with the same approvalScope runs, exactly once
}

withRedaction

A view of the engine for one tenant: every method on it applies policy (its ingest and output rules) and hashes with secretKey, while sharing the pool, embedder, graph store, hooks, function tools and host seams. A per-call redaction option still overrides it. The view snapshots the config when built, does not re-redact stored content, and does not scope function tools. Closing a view is a no-op.

withRedaction(policy: RedactionPolicy, secretKey?: string | null): ContextEngine

Returns: A new ContextEngine view.

Errors: TypeError when policy is not a RedactionPolicy (pass new RedactionPolicy() to turn redaction off); Error for an empty secretKey, or a hash rule with no key at all. Falling back to config.secretKey for a hash rule logs one warning per engine.

import { RedactionPolicy } from "@promptev/context-engine";

const tenant = engine.withRedaction(
  new RedactionPolicy({ rules: [{ name: "email", detector: "email", action: "hash" }] }),
  tenantSecret,
);
await tenant.search("invoice from acme", { principals: ["tenant:acme"] });

aclose

Release what the engine opened: the embedder, the graph store and the Postgres pool. Construction is lazy, so only what was built is torn down. Safe to call more than once; a later call rebuilds lazily. On a withRedaction view it does nothing.

aclose(): Promise<void>
[Symbol.asyncDispose](): Promise<void>

Returns: Nothing.