agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
66 lines (65 loc) • 4 kB
TypeScript
/**
* Runtime evidence for typed negatives. Only dispatch and native tool returns write here;
* assistant text, summaries and after-tool rewrites never become observations.
* Role: core/agent, opt-in. The checker and coverage rules remain their single owners.
*/
import { type TypedScope } from 'footprintjs';
import type { MemoryIdentity } from '../../../memory/identity/types.js';
import type { SearchTool, TurnCall, TurnRecord } from '../../../integrity/negative-claim/types.js';
import type { ComposedCoverage } from '../../../semantics/coverage/composedCoverage.js';
import type { Tool, ToolExecutionContext } from '../../../tools/tools.js';
import type { ToolParty } from '../../slots/buildToolsSlot.js';
import type { SearchDispatch } from '../stages/searchCoverage.js';
import type { AgentState } from '../types.js';
export interface NegativeRuntimeCall extends TurnCall {
readonly trustedContext: boolean;
}
export interface NegativeRuntimeState {
readonly version: 1;
readonly turn: number;
readonly complete: boolean;
readonly calls: readonly NegativeRuntimeCall[];
readonly tools: Readonly<Record<string, SearchTool>>;
readonly pending: readonly string[];
readonly pausedResultId?: string;
readonly overclaims: readonly {
readonly tool: string;
readonly code: 'refusal-asserts-absence';
readonly turn: number;
}[];
/** Operational carrier only, never served or emitted. */
readonly ownerIdentity?: MemoryIdentity;
/** A per-run namespace synthesized with no caller/session/composition identity. */
readonly anonymousOwner?: true;
}
export declare function createNegativeRuntimeState(turn: number, identity?: MemoryIdentity, prior?: NegativeRuntimeState, anonymousOwner?: boolean): NegativeRuntimeState;
export interface NegativeDispatch extends SearchDispatch {
readonly args: Readonly<Record<string, unknown>>;
readonly local: boolean;
}
/** Publish the attempt before the tool's code can await, throw or pause. */
export declare function startNegativeCall(scope: TypedScope<AgentState>, input: {
tool: Tool;
party?: ToolParty;
args: Readonly<Record<string, unknown>>;
toolCallId: string;
iteration: number;
runId?: string;
dispatch?: SearchDispatch;
context: ToolExecutionContext;
}): NegativeDispatch;
/** Snapshot immediately on native return, before teardown, observers and middleware. */
export declare function captureNegativeResult(scope: TypedScope<AgentState>, dispatch: NegativeDispatch, value: unknown, tool: Tool): unknown;
export declare function captureNegativeCoverage(scope: TypedScope<AgentState>, row: ComposedCoverage): void;
/** Park the native occurrence itself; provider call ids are never a selector. */
export declare function pauseNegativeCall(scope: TypedScope<AgentState>, resultId: string): void;
export declare function pausedNegativeResultId(scope: TypedScope<AgentState>): string | undefined;
/** The terminal bracket settles an attempt; a human answer is not a native observation. */
export declare function settleNegativeCall(scope: TypedScope<AgentState>, resultId: string | undefined, outcome: TurnCall['outcome']): void;
/** Existing semantic recognition, filed as codes only; a refusal never manufactures a read. */
export declare function captureNegativeRefusal(scope: TypedScope<AgentState>, tool: string, value: unknown, args?: Readonly<Record<string, unknown>>): void;
/** The transform cannot supply evidence; unreadable delivered output also withholds its handle. */
export declare function keepNegativeResultOut(scope: TypedScope<AgentState>, resultId: string | undefined): void;
/** A framework suffix, after transforms/caps. Gap notes and periods survive; inventory names never do. */
export declare function serveNegativeHandle(scope: TypedScope<AgentState>, resultId: string | undefined, text: string): string;
export declare function negativeRecordOf(scope: TypedScope<AgentState>, runId?: string): TurnRecord;