agentfootprint/dist/esm/artifacts/datasetResult.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/** Declared datasets -> scope-bound artifacts. No transport, row discovery or domain vocabulary. */
import type { Tool } from '../tools/tools.js';
import type { ToolArtifactPutInput, ToolArtifacts } from './capability.js';
import { type ArtifactMeta } from './types.js';
/** Producer-owned payloads. A source is an optional artifact, not an inferred fact. */
export interface DatasetArtifactInput {
    readonly key: string;
    readonly artifact: ToolArtifactPutInput;
    readonly source?: ToolArtifactPutInput;
}
/** A failed write or a ticket no longer held is never advertised as a stored payload. */
export type DatasetArtifactReceipt = {
    readonly status: 'stored';
    readonly meta: ArtifactMeta;
} | {
    readonly status: 'unavailable';
    readonly reason: 'store-unavailable' | 'missing-or-expired';
};
export interface DatasetPublication {
    readonly key: string;
    readonly artifact: DatasetArtifactReceipt;
    readonly source?: DatasetArtifactReceipt;
}
/** Projection owns field meanings, coverage envelopes and inline policy; receipts contain no rows. */
export interface DatasetResultPlan<TProjected = unknown> {
    readonly datasets: readonly DatasetArtifactInput[];
    project(publications: readonly DatasetPublication[]): TProjected | Promise<TProjected>;
}
export interface DatasetResultAdapter<TArgs = Record<string, unknown>, TResult = unknown, TProjected = unknown> {
    /** Undefined is an intentional pass-through (for example a declared absence). */
    describe(result: TResult, args: TArgs): DatasetResultPlan<TProjected> | undefined | Promise<DatasetResultPlan<TProjected> | undefined>;
}
/**
 * Adapt any local, HTTP-backed or MCP Tool using the SAME already-bound execution capability.
 * Claim-check: the host configures storage; the model carries tickets between tools. No UI required.
 * No store: pass through without calling the adapter; the host's normal result policy still applies.
 * Writes are independent, not a transaction. A failed source does not hide otherwise readable data;
 * its unavailable receipt must remain explicit in the producer's projection. Recheck tickets after
 * the batch because a later put can evict an earlier one. Expiry after publication remains possible.
 * This stages materialized payloads; it does not add remote handles, streaming or query pushdown.
 */
export declare function withDatasetArtifacts<TArgs, TResult, TProjected>(tool: Tool<TArgs, TResult>, adapter: DatasetResultAdapter<TArgs, TResult, TProjected>): Tool<TArgs, TResult | TProjected>;
/** The same staging step for an existing tool pipeline that already owns execution and projection. */
export declare function stageDatasetArtifacts(datasets: readonly DatasetArtifactInput[], artifacts: ToolArtifacts): Promise<readonly DatasetPublication[]>;