@promptev/context-engine 0.0.3 → 0.0.5

package/dist/index.d.cts

@@ -5,13 +5,38 @@ import { H as Hooks, R as RedactionPolicy, U as UsageEvent, P as ProgressEvent,
 export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitProgress, f as emitToolCall, g as emitUsage, h as graphUnits, u as unitsForFile } from './redaction-BqD_DEUQ.cjs';
 import { E as Embedder, S as StorageBackend, F as FetchImpl } from './storage-Dvpq2xAC.cjs';
 export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-Dvpq2xAC.cjs';
-import { P as Principals, U as Unset, S as ScopeInput, K as KnowledgeComputeFn, T as Trusted } from './mcp-BKSmxayM.cjs';
-export { a as KNOWLEDGE_ACTIONS, b as KNOWLEDGE_TOOL_DESCRIPTION, c as KnowledgeAction, d as Scope, e as TRUSTED, f as UNSCOPED, g as UNSET, h as callKnowledgeTool, i as createMcpApp, k as knowledgeToolDefinition, n as narrowToCeiling, r as resolvePrincipals, j as resolveScope } from './mcp-BKSmxayM.cjs';
+import { P as Principals, U as Unset, S as ScopeInput, K as KnowledgeComputeFn, T as Trusted } from './mcp-uirRbluA.cjs';
+export { a as KNOWLEDGE_ACTIONS, b as KNOWLEDGE_TOOL_DESCRIPTION, c as KnowledgeAction, d as Scope, e as TRUSTED, f as UNSCOPED, g as UNSET, h as callKnowledgeTool, i as createMcpApp, k as knowledgeToolDefinition, n as narrowToCeiling, r as resolvePrincipals, j as resolveScope } from './mcp-uirRbluA.cjs';
 import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-P9pRb4Ol.cjs';
 export { c as ToolKind, d as configSchema } from './governance-P9pRb4Ol.cjs';
 import 'zod';
 import 'node:http';
 
+/**
+ * Tool result formats — one helper every tool kind shares. Mirrors
+ * `context_engine/tools/response_mode.py`.
+ *
+ * `formatResult(result, responseMode)` hands a JSON-ish tool result back
+ * unchanged for `"json"`, and for `"tsv"` turns every outermost non-empty
+ * array of objects in it into a TSV string under the same key. A result that
+ * IS such an array becomes the string; a result holding none comes back
+ * unchanged.
+ *
+ * The cell encoding is PostgreSQL's COPY TEXT convention, not CSV quoting:
+ * `\N` is NULL, and tab, newline, CR and backslash inside a value are
+ * backslash-escaped. Quoting would leave a real newline inside a quoted
+ * value, so one row could span several lines — which breaks cutting a table
+ * at whole rows (`shapeResult`) and is harder for a model to read. Values
+ * that are not strings are written as compact JSON (dates as ISO strings).
+ */
+declare const RESPONSE_MODES: readonly ["json", "tsv"];
+type ResponseMode = (typeof RESPONSE_MODES)[number];
+/** A list of objects as one TSV string, header first. */
+declare function rowsToTsv(rows: Array<Record<string, unknown>>): string;
+/** `result` unchanged for `"json"` (the default); every array of objects in
+ * it as TSV for `"tsv"`. Throws for an unknown mode. */
+declare function formatResult(result: unknown, responseMode?: ResponseMode): unknown;
+
 type Mode$1 = "hybrid" | "graph";
 interface IngestRequest {
     content?: Buffer | null;
@@ -71,6 +96,13 @@ declare function listDocuments(opts: {
     sourceId?: string | null;
     /** OR-of-many, ONE keyset-paged query across all of them; with `sourceId`, their union. */
     sourceIds?: string[] | null;
+    /**
+     * Narrows to specific documents IN SQL, not after the page is built: three
+     * named documents that happen to sit on page four would otherwise come back
+     * as an empty page rather than as themselves. An empty array means nothing
+     * is in scope and stays empty.
+     */
+    documentIds?: string[] | null;
     principals?: string[] | null;
     cursor?: unknown;
     limit?: number;
@@ -78,6 +110,167 @@ declare function listDocuments(opts: {
     secretKey?: string | Buffer | null;
     hooks?: Hooks;
 }): Promise<Record<string, unknown>>;
+type SpreadsheetDescription = {
+    document_id: string;
+    name: unknown;
+    source_id: unknown;
+    sheets: SheetSchema[] | null;
+    schema_unavailable?: string;
+};
+/**
+ * Sheet names, column headers and row counts for the named spreadsheets.
+ *
+ * `documentIds` comes from a listing the caller has already been shown, but
+ * the ACL and the source scope are applied AGAIN here: "we already filtered
+ * the list" is exactly how a batch read ends up reading one row it should
+ * not have. A document that is not visible, is not in scope, or is not
+ * tabular simply does not appear in the result.
+ *
+ * Reading document bodies is the cost, so it is bounded twice: the caller
+ * passes only the page it is describing, and `budget` caps the total
+ * characters of stored text this will pull. Documents past the budget are
+ * still LISTED, with `sheets: null` and a reason — a silently shortened
+ * schema would read as "that workbook has no sheets".
+ *
+ * `redaction` masks sheet names and column headers, which are derived from
+ * the document body exactly like `search`'s chunk text. The document `name`
+ * is not masked, matching `listDocuments`: it is caller-set at ingest.
+ */
+declare function spreadsheetSchema(opts: {
+    pool: Pool;
+    documentIds: string[];
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    budget?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<SpreadsheetDescription[]>;
+type DocumentStructure = Record<string, unknown>;
+/**
+ * What is INSIDE each of the named documents, whatever its type.
+ *
+ * Returns `{documentId: structure}`. The shape of `structure` follows the
+ * document, because the thing a model needs to know differs by type:
+ *
+ * | document | structure |
+ * |---|---|
+ * | CSV / XLSX / TSV | `sheets: [{name, columns, row_count}]` |
+ * | markdown, Word, HTML, a transcribed PDF | `sections: [...]`, `last_page` |
+ * | JSON | `keys: [...]` |
+ * | anything else | just `chunks` |
+ *
+ * `chunks` is on every one of them, and is the floor: a plain `.txt` has no
+ * headings to report, but a model still has to know whether `get_chunks` is
+ * worth calling. A document that is present but described by nothing at all
+ * reads as an empty document, which is why there is no "no structure" case.
+ *
+ * Everything but the spreadsheet columns comes from `meta_data` on the chunk
+ * rows, which the chunkers already wrote at ingest (`section_title`, `page`,
+ * `top_level_key`) — one grouped query over small rows, no document body read
+ * and no LLM. Columns are the exception: the header row is not in chunk
+ * metadata, so the tabular half still parses stored text, under the same
+ * budget (see `spreadsheetSchema`).
+ */
+declare function documentStructure(opts: {
+    pool: Pool;
+    documentIds: string[];
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    budget?: number;
+    /**
+     * Cap every list at `MAX_STRUCTURE_ITEMS` and report the remainder as a
+     * count. One rule decides it, and the caller above applies it: **the cap is
+     * for the call that did NOT name its documents.** A `discover` describing a
+     * whole page has a context budget to keep; a caller that asked about one
+     * document asked for all of it, exactly like `spreadsheetSchema`.
+     */
+    bounded?: boolean;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<Record<string, DocumentStructure>>;
+type DocumentTypeCount = {
+    kind: "spreadsheet" | "text";
+    type: string | null;
+    documents: number;
+    with_fields: number;
+};
+/**
+ * The corpus census: `[{kind, type, documents, with_fields}]`.
+ *
+ * Keyed by TWO things, because only one of them is always known:
+ *
+ * - `kind` is derived from the mime (`isTabularMime`, the same predicate
+ *   `compute` selects on), so it is known for every document ever ingested.
+ * - `type` is the document's `document_type`, which is unconstrained free
+ *   text an LLM wrote during structured extraction — and extraction is
+ *   opt-in (`extractStructured`, off by default). On a deployment that never
+ *   enabled it, `type` is null on every row. A census keyed on `type` alone
+ *   would therefore be a single null bucket, which tells a model nothing
+ *   about a corpus it is about to query.
+ *
+ * `with_fields` counts documents whose `structured_data` is a non-empty
+ * object. Extraction that ran and legitimately found nothing stores `{}`, and
+ * counting that as coverage would point a model at `query_meta` for a type
+ * that has nothing to filter on.
+ */
+declare function documentTypes(opts: {
+    pool: Pool;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    documentIds?: string[] | null;
+    limit?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<DocumentTypeCount[]>;
+type FieldDescription = {
+    field: string;
+    type: string;
+    documents: number;
+};
+type FieldGroup = {
+    kind: "spreadsheet" | "text";
+    type: string | null;
+    fields: FieldDescription[];
+    more_fields?: string[];
+};
+/**
+ * Extracted structured field names grouped by document kind AND type.
+ *
+ * Returns `[{kind, type, fields: [{field, type, documents}], more_fields}]` —
+ * one row per group, keyed by the SAME pair `documentTypes` is keyed by. That
+ * pairing is the point: `document_type` is a label an LLM wrote, so two
+ * different kinds can share one ("invoice" for both a PDF and a CSV of
+ * invoice rows). Keyed on the label alone, their fields merge into one group
+ * and a model reads a spreadsheet's columns as a PDF's extracted fields.
+ *
+ * `more_fields` holds the NAMES the per-group detail cap left out, not a
+ * count: nothing is dropped silently, and a name is all a caller needs to
+ * reach a field through `query_meta`. It is absent when nothing was left out.
+ *
+ * Counted over the documents the CALLER can see, not over the learned field
+ * registry (`context_engine_structured_keys`), which carries no ACL: a
+ * registry-wide answer would tell an anonymous caller the field names of
+ * every restricted document in the corpus. Counting from `structured_data`
+ * also makes `documents` mean what it says — how many in-scope documents
+ * actually carry the field.
+ *
+ * The type is `inferDataType`, the same function that labelled the registry,
+ * so the vocabulary a model reads here is the one the rest of the engine
+ * uses.
+ */
+declare function fieldSummary(opts: {
+    pool: Pool;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    documentIds?: string[] | null;
+    maxFieldsPerType?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<FieldGroup[]>;
 /**
  * Answer a natural-language question against documents' `structuredData`.
  *
@@ -102,6 +295,24 @@ declare function queryStructured(question: string, opts: {
     secretKey?: string | Buffer | null;
     hooks?: Hooks;
 }): Promise<Record<string, unknown>>;
+type SheetSchema = {
+    name: string;
+    columns: string[];
+    row_count: number;
+};
+/**
+ * The schema of one stored spreadsheet: `[{name, columns, row_count}]`.
+ *
+ * Header row and row count per SHEET, not unioned across the workbook — two
+ * sheets that both have an `amount` column are two different frames to
+ * `compute`, and a union would hide which one has the column a question
+ * needs. `row_count` counts DATA rows (the header is not one of them).
+ *
+ * Needs no danfo: `discover` must stay callable on an install that never
+ * enabled code execution, which is exactly the install where a model most
+ * needs the columns before it writes a query.
+ */
+declare function spreadsheetSchemaFromText(text: string | null | undefined): SheetSchema[];
 /**
  * Compute an answer to `instruction` over in-scope spreadsheet documents.
  *
@@ -569,11 +780,66 @@ declare class ContextEngine implements ToolEngine {
     listDocuments(opts?: {
         sourceId?: string | null;
         sourceIds?: string[] | null;
+        documentIds?: string[] | null;
         principals?: Principals;
         cursor?: unknown;
         limit?: number;
         redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Sheet names, columns and row counts for the named spreadsheets.
+     *
+     * See `actions.spreadsheetSchema`. This is the half of `discover` that lets
+     * a model write ONE `compute` call: sheet names here are the keys it will
+     * index `dfs` by, and columns are the names it will use inside the code it
+     * writes.
+     */
+    spreadsheetSchema(opts: {
+        documentIds: string[];
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        redaction?: RedactionPolicy | null;
+    }): Promise<SpreadsheetDescription[]>;
+    /**
+     * What is inside each of the named documents, whatever its type.
+     *
+     * See `actions.documentStructure`. 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 — so `discover` describes the
+     * whole corpus rather than only the spreadsheets in it.
+     */
+    documentStructure(opts: {
+        documentIds: string[];
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        bounded?: boolean;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Record<string, DocumentStructure>>;
+    /**
+     * The corpus census — `[{kind, type, documents, with_fields}]`.
+     *
+     * See `actions.documentTypes`. `kind` comes from the mime and is always
+     * known; `type` is the LLM-written document type and exists only where
+     * structured extraction was opted into.
+     */
+    documentTypes(opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        documentIds?: string[] | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<DocumentTypeCount[]>;
+    /**
+     * Extracted structured field names grouped by document kind and type.
+     *
+     * See `actions.fieldSummary`. One row per group, keyed by the same
+     * `(kind, type)` pair `documentTypes` uses.
+     */
+    fieldSummary(opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        documentIds?: string[] | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<FieldGroup[]>;
     queryStructured(question: string, opts?: {
         sourceIds?: string[] | null;
         principals?: Principals;
@@ -614,6 +880,13 @@ declare class ContextEngine implements ToolEngine {
         /** Opaque claim scope for approvals (e.g. a run id) — separate from
          * `sourceId`. See `governance.executeTool`. */
         approvalScope?: string | null;
+        /** Budget for the returned `result`: omitted = 8,000 chars / 100 rows,
+         * `null` = no limit. See `governance.executeTool`. */
+        resultMaxChars?: number | null;
+        resultMaxRows?: number | null;
+        /** `"json"` or `"tsv"` — every array of objects in the result as a TSV
+         * string. Omitted, an http tool uses its config's `response_mode`, else json. */
+        responseMode?: ResponseMode | null;
     }): Promise<Record<string, unknown>>;
 }
 
@@ -933,4 +1206,4 @@ declare function functionTool(fn: (...args: never[]) => unknown): CanonicalTool;
 /** Bumped by CI on every main merge; 0.0.0 = pre-first-release. */
 declare const __version__ = "0.0.0";
 
-export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, type ComputeDocument, type ComputeFrames, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, KnowledgeComputeFn, LLMClient, LLMConfig, Principals, ProgressEvent, RedactionPolicy, RerankerConfig, ScopeInput, type SearchResult, StorageBackend, type TaskRunner, type TaskStatus, ToolConfig, Trusted, Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, computeOverFrames, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };
+export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, type ComputeDocument, type ComputeFrames, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, KnowledgeComputeFn, LLMClient, LLMConfig, Principals, ProgressEvent, RedactionPolicy, RerankerConfig, type ResponseMode, ScopeInput, type SearchResult, StorageBackend, type TaskRunner, type TaskStatus, ToolConfig, Trusted, Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, computeOverFrames, decryptDict, documentStructure, documentTypes, encryptDict, extract, extractStructuredData, fieldSummary, formatResult, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, rowsToTsv, rrfFuse, runMigrate, runSearch, shouldRequireApproval, spreadsheetSchema, spreadsheetSchemaFromText, upsertRegistry };

package/dist/index.d.ts

@@ -5,13 +5,38 @@ import { H as Hooks, R as RedactionPolicy, U as UsageEvent, P as ProgressEvent,
 export { D as DocumentReport, a as RedactionRule, b as RedactionRuleInit, c as applyRedaction, e as emitError, d as emitProgress, f as emitToolCall, g as emitUsage, h as graphUnits, u as unitsForFile } from './redaction-BqD_DEUQ.js';
 import { E as Embedder, S as StorageBackend, F as FetchImpl } from './storage-CJrKgJeJ.js';
 export { C as ChunkRow, a as EmbedKind, P as PostgresBackend, b as SearchScope, c as buildEmbedder } from './storage-CJrKgJeJ.js';
-import { P as Principals, U as Unset, S as ScopeInput, K as KnowledgeComputeFn, T as Trusted } from './mcp-BKSmxayM.js';
-export { a as KNOWLEDGE_ACTIONS, b as KNOWLEDGE_TOOL_DESCRIPTION, c as KnowledgeAction, d as Scope, e as TRUSTED, f as UNSCOPED, g as UNSET, h as callKnowledgeTool, i as createMcpApp, k as knowledgeToolDefinition, n as narrowToCeiling, r as resolvePrincipals, j as resolveScope } from './mcp-BKSmxayM.js';
+import { P as Principals, U as Unset, S as ScopeInput, K as KnowledgeComputeFn, T as Trusted } from './mcp-uirRbluA.js';
+export { a as KNOWLEDGE_ACTIONS, b as KNOWLEDGE_TOOL_DESCRIPTION, c as KnowledgeAction, d as Scope, e as TRUSTED, f as UNSCOPED, g as UNSET, h as callKnowledgeTool, i as createMcpApp, k as knowledgeToolDefinition, n as narrowToCeiling, r as resolvePrincipals, j as resolveScope } from './mcp-uirRbluA.js';
 import { T as ToolEngine, C as CanonicalTool, b as ToolHttpClient, a as ToolConfig } from './governance-BLPK7NMe.js';
 export { c as ToolKind, d as configSchema } from './governance-BLPK7NMe.js';
 import 'zod';
 import 'node:http';
 
+/**
+ * Tool result formats — one helper every tool kind shares. Mirrors
+ * `context_engine/tools/response_mode.py`.
+ *
+ * `formatResult(result, responseMode)` hands a JSON-ish tool result back
+ * unchanged for `"json"`, and for `"tsv"` turns every outermost non-empty
+ * array of objects in it into a TSV string under the same key. A result that
+ * IS such an array becomes the string; a result holding none comes back
+ * unchanged.
+ *
+ * The cell encoding is PostgreSQL's COPY TEXT convention, not CSV quoting:
+ * `\N` is NULL, and tab, newline, CR and backslash inside a value are
+ * backslash-escaped. Quoting would leave a real newline inside a quoted
+ * value, so one row could span several lines — which breaks cutting a table
+ * at whole rows (`shapeResult`) and is harder for a model to read. Values
+ * that are not strings are written as compact JSON (dates as ISO strings).
+ */
+declare const RESPONSE_MODES: readonly ["json", "tsv"];
+type ResponseMode = (typeof RESPONSE_MODES)[number];
+/** A list of objects as one TSV string, header first. */
+declare function rowsToTsv(rows: Array<Record<string, unknown>>): string;
+/** `result` unchanged for `"json"` (the default); every array of objects in
+ * it as TSV for `"tsv"`. Throws for an unknown mode. */
+declare function formatResult(result: unknown, responseMode?: ResponseMode): unknown;
+
 type Mode$1 = "hybrid" | "graph";
 interface IngestRequest {
     content?: Buffer | null;
@@ -71,6 +96,13 @@ declare function listDocuments(opts: {
     sourceId?: string | null;
     /** OR-of-many, ONE keyset-paged query across all of them; with `sourceId`, their union. */
     sourceIds?: string[] | null;
+    /**
+     * Narrows to specific documents IN SQL, not after the page is built: three
+     * named documents that happen to sit on page four would otherwise come back
+     * as an empty page rather than as themselves. An empty array means nothing
+     * is in scope and stays empty.
+     */
+    documentIds?: string[] | null;
     principals?: string[] | null;
     cursor?: unknown;
     limit?: number;
@@ -78,6 +110,167 @@ declare function listDocuments(opts: {
     secretKey?: string | Buffer | null;
     hooks?: Hooks;
 }): Promise<Record<string, unknown>>;
+type SpreadsheetDescription = {
+    document_id: string;
+    name: unknown;
+    source_id: unknown;
+    sheets: SheetSchema[] | null;
+    schema_unavailable?: string;
+};
+/**
+ * Sheet names, column headers and row counts for the named spreadsheets.
+ *
+ * `documentIds` comes from a listing the caller has already been shown, but
+ * the ACL and the source scope are applied AGAIN here: "we already filtered
+ * the list" is exactly how a batch read ends up reading one row it should
+ * not have. A document that is not visible, is not in scope, or is not
+ * tabular simply does not appear in the result.
+ *
+ * Reading document bodies is the cost, so it is bounded twice: the caller
+ * passes only the page it is describing, and `budget` caps the total
+ * characters of stored text this will pull. Documents past the budget are
+ * still LISTED, with `sheets: null` and a reason — a silently shortened
+ * schema would read as "that workbook has no sheets".
+ *
+ * `redaction` masks sheet names and column headers, which are derived from
+ * the document body exactly like `search`'s chunk text. The document `name`
+ * is not masked, matching `listDocuments`: it is caller-set at ingest.
+ */
+declare function spreadsheetSchema(opts: {
+    pool: Pool;
+    documentIds: string[];
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    budget?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<SpreadsheetDescription[]>;
+type DocumentStructure = Record<string, unknown>;
+/**
+ * What is INSIDE each of the named documents, whatever its type.
+ *
+ * Returns `{documentId: structure}`. The shape of `structure` follows the
+ * document, because the thing a model needs to know differs by type:
+ *
+ * | document | structure |
+ * |---|---|
+ * | CSV / XLSX / TSV | `sheets: [{name, columns, row_count}]` |
+ * | markdown, Word, HTML, a transcribed PDF | `sections: [...]`, `last_page` |
+ * | JSON | `keys: [...]` |
+ * | anything else | just `chunks` |
+ *
+ * `chunks` is on every one of them, and is the floor: a plain `.txt` has no
+ * headings to report, but a model still has to know whether `get_chunks` is
+ * worth calling. A document that is present but described by nothing at all
+ * reads as an empty document, which is why there is no "no structure" case.
+ *
+ * Everything but the spreadsheet columns comes from `meta_data` on the chunk
+ * rows, which the chunkers already wrote at ingest (`section_title`, `page`,
+ * `top_level_key`) — one grouped query over small rows, no document body read
+ * and no LLM. Columns are the exception: the header row is not in chunk
+ * metadata, so the tabular half still parses stored text, under the same
+ * budget (see `spreadsheetSchema`).
+ */
+declare function documentStructure(opts: {
+    pool: Pool;
+    documentIds: string[];
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    budget?: number;
+    /**
+     * Cap every list at `MAX_STRUCTURE_ITEMS` and report the remainder as a
+     * count. One rule decides it, and the caller above applies it: **the cap is
+     * for the call that did NOT name its documents.** A `discover` describing a
+     * whole page has a context budget to keep; a caller that asked about one
+     * document asked for all of it, exactly like `spreadsheetSchema`.
+     */
+    bounded?: boolean;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<Record<string, DocumentStructure>>;
+type DocumentTypeCount = {
+    kind: "spreadsheet" | "text";
+    type: string | null;
+    documents: number;
+    with_fields: number;
+};
+/**
+ * The corpus census: `[{kind, type, documents, with_fields}]`.
+ *
+ * Keyed by TWO things, because only one of them is always known:
+ *
+ * - `kind` is derived from the mime (`isTabularMime`, the same predicate
+ *   `compute` selects on), so it is known for every document ever ingested.
+ * - `type` is the document's `document_type`, which is unconstrained free
+ *   text an LLM wrote during structured extraction — and extraction is
+ *   opt-in (`extractStructured`, off by default). On a deployment that never
+ *   enabled it, `type` is null on every row. A census keyed on `type` alone
+ *   would therefore be a single null bucket, which tells a model nothing
+ *   about a corpus it is about to query.
+ *
+ * `with_fields` counts documents whose `structured_data` is a non-empty
+ * object. Extraction that ran and legitimately found nothing stores `{}`, and
+ * counting that as coverage would point a model at `query_meta` for a type
+ * that has nothing to filter on.
+ */
+declare function documentTypes(opts: {
+    pool: Pool;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    documentIds?: string[] | null;
+    limit?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<DocumentTypeCount[]>;
+type FieldDescription = {
+    field: string;
+    type: string;
+    documents: number;
+};
+type FieldGroup = {
+    kind: "spreadsheet" | "text";
+    type: string | null;
+    fields: FieldDescription[];
+    more_fields?: string[];
+};
+/**
+ * Extracted structured field names grouped by document kind AND type.
+ *
+ * Returns `[{kind, type, fields: [{field, type, documents}], more_fields}]` —
+ * one row per group, keyed by the SAME pair `documentTypes` is keyed by. That
+ * pairing is the point: `document_type` is a label an LLM wrote, so two
+ * different kinds can share one ("invoice" for both a PDF and a CSV of
+ * invoice rows). Keyed on the label alone, their fields merge into one group
+ * and a model reads a spreadsheet's columns as a PDF's extracted fields.
+ *
+ * `more_fields` holds the NAMES the per-group detail cap left out, not a
+ * count: nothing is dropped silently, and a name is all a caller needs to
+ * reach a field through `query_meta`. It is absent when nothing was left out.
+ *
+ * Counted over the documents the CALLER can see, not over the learned field
+ * registry (`context_engine_structured_keys`), which carries no ACL: a
+ * registry-wide answer would tell an anonymous caller the field names of
+ * every restricted document in the corpus. Counting from `structured_data`
+ * also makes `documents` mean what it says — how many in-scope documents
+ * actually carry the field.
+ *
+ * The type is `inferDataType`, the same function that labelled the registry,
+ * so the vocabulary a model reads here is the one the rest of the engine
+ * uses.
+ */
+declare function fieldSummary(opts: {
+    pool: Pool;
+    sourceIds?: string[] | null;
+    principals?: string[] | null;
+    documentIds?: string[] | null;
+    maxFieldsPerType?: number;
+    redaction?: RedactionPolicy | null;
+    secretKey?: string | Buffer | null;
+    hooks?: Hooks;
+}): Promise<FieldGroup[]>;
 /**
  * Answer a natural-language question against documents' `structuredData`.
  *
@@ -102,6 +295,24 @@ declare function queryStructured(question: string, opts: {
     secretKey?: string | Buffer | null;
     hooks?: Hooks;
 }): Promise<Record<string, unknown>>;
+type SheetSchema = {
+    name: string;
+    columns: string[];
+    row_count: number;
+};
+/**
+ * The schema of one stored spreadsheet: `[{name, columns, row_count}]`.
+ *
+ * Header row and row count per SHEET, not unioned across the workbook — two
+ * sheets that both have an `amount` column are two different frames to
+ * `compute`, and a union would hide which one has the column a question
+ * needs. `row_count` counts DATA rows (the header is not one of them).
+ *
+ * Needs no danfo: `discover` must stay callable on an install that never
+ * enabled code execution, which is exactly the install where a model most
+ * needs the columns before it writes a query.
+ */
+declare function spreadsheetSchemaFromText(text: string | null | undefined): SheetSchema[];
 /**
  * Compute an answer to `instruction` over in-scope spreadsheet documents.
  *
@@ -569,11 +780,66 @@ declare class ContextEngine implements ToolEngine {
     listDocuments(opts?: {
         sourceId?: string | null;
         sourceIds?: string[] | null;
+        documentIds?: string[] | null;
         principals?: Principals;
         cursor?: unknown;
         limit?: number;
         redaction?: RedactionPolicy | null;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Sheet names, columns and row counts for the named spreadsheets.
+     *
+     * See `actions.spreadsheetSchema`. This is the half of `discover` that lets
+     * a model write ONE `compute` call: sheet names here are the keys it will
+     * index `dfs` by, and columns are the names it will use inside the code it
+     * writes.
+     */
+    spreadsheetSchema(opts: {
+        documentIds: string[];
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        redaction?: RedactionPolicy | null;
+    }): Promise<SpreadsheetDescription[]>;
+    /**
+     * What is inside each of the named documents, whatever its type.
+     *
+     * See `actions.documentStructure`. 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 — so `discover` describes the
+     * whole corpus rather than only the spreadsheets in it.
+     */
+    documentStructure(opts: {
+        documentIds: string[];
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        bounded?: boolean;
+        redaction?: RedactionPolicy | null;
+    }): Promise<Record<string, DocumentStructure>>;
+    /**
+     * The corpus census — `[{kind, type, documents, with_fields}]`.
+     *
+     * See `actions.documentTypes`. `kind` comes from the mime and is always
+     * known; `type` is the LLM-written document type and exists only where
+     * structured extraction was opted into.
+     */
+    documentTypes(opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        documentIds?: string[] | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<DocumentTypeCount[]>;
+    /**
+     * Extracted structured field names grouped by document kind and type.
+     *
+     * See `actions.fieldSummary`. One row per group, keyed by the same
+     * `(kind, type)` pair `documentTypes` uses.
+     */
+    fieldSummary(opts?: {
+        sourceIds?: string[] | null;
+        principals?: Principals;
+        documentIds?: string[] | null;
+        redaction?: RedactionPolicy | null;
+    }): Promise<FieldGroup[]>;
     queryStructured(question: string, opts?: {
         sourceIds?: string[] | null;
         principals?: Principals;
@@ -614,6 +880,13 @@ declare class ContextEngine implements ToolEngine {
         /** Opaque claim scope for approvals (e.g. a run id) — separate from
          * `sourceId`. See `governance.executeTool`. */
         approvalScope?: string | null;
+        /** Budget for the returned `result`: omitted = 8,000 chars / 100 rows,
+         * `null` = no limit. See `governance.executeTool`. */
+        resultMaxChars?: number | null;
+        resultMaxRows?: number | null;
+        /** `"json"` or `"tsv"` — every array of objects in the result as a TSV
+         * string. Omitted, an http tool uses its config's `response_mode`, else json. */
+        responseMode?: ResponseMode | null;
     }): Promise<Record<string, unknown>>;
 }
 
@@ -933,4 +1206,4 @@ declare function functionTool(fn: (...args: never[]) => unknown): CanonicalTool;
 /** Bumped by CI on every main merge; 0.0.0 = pre-first-release. */
 declare const __version__ = "0.0.0";
 
-export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, type ComputeDocument, type ComputeFrames, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, KnowledgeComputeFn, LLMClient, LLMConfig, Principals, ProgressEvent, RedactionPolicy, RerankerConfig, ScopeInput, type SearchResult, StorageBackend, type TaskRunner, type TaskStatus, ToolConfig, Trusted, Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, computeOverFrames, decryptDict, encryptDict, extract, extractStructuredData, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, rrfFuse, runMigrate, runSearch, shouldRequireApproval, upsertRegistry };
+export { ApprovalExpired, ApprovalNotPending, type ApprovalRecord, CeleryRunner, CodeExecutionError, CodeExecutionTimeout, type ComputeDocument, type ComputeFrames, ContextEngine, ContextEngineConfig, DEFAULT_LEG_WEIGHT, DocumentNotFoundError, EXTRACTION_VERSION, Embedder, EngineActionError, ExtraMissingError, Extracted, ExtractionConfig, type ExtractionResult, GraphLegUnavailable, type Hit, Hooks, InProcessRunner, IngestReport, KnowledgeComputeFn, LLMClient, LLMConfig, Principals, ProgressEvent, RedactionPolicy, RerankerConfig, type ResponseMode, ScopeInput, type SearchResult, StorageBackend, type TaskRunner, type TaskStatus, ToolConfig, Trusted, Unset, UsageEvent, __version__, buildLlmClient, callLlm, compute, computeOverFrames, decryptDict, documentStructure, documentTypes, encryptDict, extract, extractStructuredData, fieldSummary, formatResult, functionTool, getDocumentText, getSecretKey, listDocuments, queryStructured, redactHits, rerank, resolveApproval, resolveFields, rowsToTsv, rrfFuse, runMigrate, runSearch, shouldRequireApproval, spreadsheetSchema, spreadsheetSchemaFromText, upsertRegistry };