agentfootprint 1.23.0 → 2.1.0

package/dist/types/lib/instructions/index.d.ts

@@ -1,18 +0,0 @@
-export { quickBind, follow } from './types';
-export type { LLMInstruction, FollowUpBinding, InstructionContext, RuntimeFollowUp, InstructedToolResult, InstructedToolDefinition, InstructionOverride, } from './types';
-export { evaluateInstructions, mergeRuntimeInstructions, applyInstructionOverrides, } from './evaluator';
-export type { ResolvedInstruction, ResolvedFollowUp } from './evaluator';
-export { renderInstructions } from './template';
-export type { InstructionTemplate } from './template';
-export { processInstructions } from './inject';
-export type { InstructionInjectionResult } from './inject';
-export { previewInstructions } from './preview';
-export type { InstructionPreview, PreviewContext } from './preview';
-export { InstructionRecorder } from './InstructionRecorder';
-export type { InstructionSummary, ToolInstructionStats, InstructionFiring, FollowUpOffering, } from './InstructionRecorder';
-export { defaultConditionMatcher, PendingFollowUpManager } from './strictFollowUp';
-export type { PendingStrictFollowUp } from './strictFollowUp';
-export { evaluateAgentInstructions, defineInstruction } from './agentInstruction';
-export type { AgentInstruction, InstructionEvaluationResult } from './agentInstruction';
-export { buildInstructionsToLLMSubflow } from './buildInstructionsToLLMSubflow';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/instructions/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,YAAY,EACV,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAE3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AACnF,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAClF,YAAY,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAExF,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/types/lib/instructions/inject.d.ts

@@ -1,54 +0,0 @@
-/**
- * Instruction injection — appends rendered instructions to tool result content.
- *
- * This is the bridge between the evaluator (which resolves instructions)
- * and the tool result message (which the LLM reads). The injected text
- * lands in the recency window — the last tokens before LLM generation.
- *
- * The function is intentionally simple: evaluate → render → append.
- * Side effects (recording, logging) are handled by callers.
- */
-import type { LLMInstruction, InstructionContext, RuntimeFollowUp } from './types';
-import type { InstructionTemplate } from './template';
-import type { ResolvedInstruction } from './evaluator';
-/**
- * Result of processing instructions for a tool result.
- */
-export interface InstructionInjectionResult {
-    /** The original content with instructions appended (or unchanged if none fired). */
-    readonly content: string;
-    /** All resolved instructions that fired (for recording/tracking). */
-    readonly fired: ResolvedInstruction[];
-    /** Whether any instructions were injected. */
-    readonly injected: boolean;
-}
-/**
- * Process instructions for a tool result and return augmented content.
- *
- * Full pipeline: evaluate predicates → merge runtime → render → append.
- *
- * @param originalContent - The tool result content string
- * @param buildTimeInstructions - Instructions from tool definition
- * @param ctx - Full execution context (content, error, latency, input, toolId)
- * @param runtime - Runtime instructions/followUps from handler return
- * @param template - Optional custom template for formatting
- *
- * @example
- * ```typescript
- * const result = processInstructions(
- *   toolResult.content,
- *   tool.instructions,
- *   { content: parsed, error: undefined, latencyMs: 42, input, toolId: tool.id },
- *   toolResult.instructions ? { instructions: toolResult.instructions } : undefined,
- * );
- *
- * // result.content has instructions appended
- * // result.fired lists which instructions matched
- * // result.injected is true if any text was added
- * ```
- */
-export declare function processInstructions(originalContent: string, buildTimeInstructions: readonly LLMInstruction[] | undefined, ctx: InstructionContext, runtime?: {
-    instructions?: readonly string[];
-    followUps?: readonly RuntimeFollowUp[];
-}, template?: InstructionTemplate): InstructionInjectionResult;
-//# sourceMappingURL=inject.d.ts.map

package/dist/types/lib/instructions/inject.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"inject.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/inject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACnF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAMvD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,mBAAmB,EAAE,CAAC;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,eAAe,EAAE,MAAM,EACvB,qBAAqB,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EAC5D,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE;IACR,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CACxC,EACD,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,0BAA0B,CAqB5B"}

package/dist/types/lib/instructions/preview.d.ts

@@ -1,85 +0,0 @@
-/**
- * previewInstructions — dry-run showing what gets injected for a mock tool result.
- *
- * Invaluable for debugging instruction behavior during development and for
- * generating documentation of tool behavior.
- *
- * @example
- * ```typescript
- * const preview = previewInstructions(
- *   orderTool.instructions,
- *   { content: { status: 'cancelled', trackingId: 'TRK-1' }, toolId: 'check_order' },
- * );
- *
- * console.log(preview);
- * // {
- * //   fired: [{ id: 'empathy', text: '...', safety: false }, ...],
- * //   injectedText: '[INSTRUCTION] Be empathetic...\n\n[AVAILABLE ACTION]...',
- * //   estimatedTokens: 47,
- * //   followUps: [{ toolId: 'track_package', params: { trackingId: 'TRK-1' } }],
- * // }
- * ```
- */
-import type { LLMInstruction, InstructionOverride } from './types';
-import type { InstructionTemplate } from './template';
-import type { ResolvedInstruction, ResolvedFollowUp } from './evaluator';
-/** Input for previewInstructions — minimal context for evaluation. */
-export interface PreviewContext {
-    /** Mock tool result content (parsed object or raw string). */
-    readonly content: unknown;
-    /** Tool ID that produced this result. */
-    readonly toolId: string;
-    /** Optional error state. */
-    readonly error?: {
-        code?: string;
-        message: string;
-    };
-    /** Optional latency in ms. Default: 0. */
-    readonly latencyMs?: number;
-    /** Optional original input. Default: {}. */
-    readonly input?: Record<string, unknown>;
-}
-/** Result of previewInstructions — what the LLM would see. */
-export interface InstructionPreview {
-    /** Instructions that fired (in injection order). */
-    readonly fired: ResolvedInstruction[];
-    /** The text that would be appended to the tool result message. */
-    readonly injectedText: string | undefined;
-    /** Rough token estimate (~4 chars per token). */
-    readonly estimatedTokens: number;
-    /** Follow-ups that were offered (with resolved params). */
-    readonly followUps: ResolvedFollowUp[];
-    /** IDs of instructions that fired. */
-    readonly firedIds: string[];
-    /** IDs of instructions that did NOT fire. */
-    readonly skippedIds: string[];
-}
-/**
- * Preview which instructions would fire for a given mock tool result.
- *
- * Does NOT run the agent — purely evaluates instructions against the mock context.
- * Use for debugging, testing, and generating tool behavior documentation.
- *
- * @param instructions - The tool's instruction array (or overridden version)
- * @param context - Mock tool result context
- * @param options - Optional: overrides to apply, custom template
- *
- * @example
- * ```typescript
- * // Basic preview
- * const preview = previewInstructions(tool.instructions, {
- *   content: { status: 'denied', traceId: 'tr_1' },
- *   toolId: 'evaluate_loan',
- * });
- *
- * // With overrides applied
- * const preview = previewInstructions(tool.instructions, ctx, {
- *   overrides: { suppress: ['low-priority'] },
- * });
- * ```
- */
-export declare function previewInstructions(instructions: readonly LLMInstruction[] | undefined, context: PreviewContext, options?: {
-    overrides?: InstructionOverride;
-    template?: InstructionTemplate;
-}): InstructionPreview;
-//# sourceMappingURL=preview.d.ts.map

package/dist/types/lib/instructions/preview.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAsB,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACvF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAMzE,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,EAAE,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IACvC,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;CAC/B;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EACnD,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC,GACA,kBAAkB,CA0CpB"}

package/dist/types/lib/instructions/strictFollowUp.d.ts

@@ -1,88 +0,0 @@
-/**
- * strictFollowUp — auto-execute follow-ups when condition matches user message.
- *
- * When a tool's follow-up binding has `strict: true`, the framework stores it
- * as a pending follow-up. On the next user message, the condition is checked:
- *   - If matched: framework auto-executes the tool with pre-resolved params,
- *     bypassing the LLM for tool call construction. Zero ID corruption risk.
- *   - If not matched: pending follow-up is cleared, LLM proceeds normally.
- *
- * The LLM is still used to interpret the follow-up tool's result — it's only
- * bypassed for the mechanical "construct the tool call" step.
- *
- * Condition matching uses a keyword-based matcher by default. Custom matchers
- * can be provided per follow-up binding.
- */
-import type { ResolvedFollowUp } from './evaluator';
-/**
- * Default keyword matcher — extracts intent keywords from the condition string
- * and checks if the user message contains any of them.
- *
- * The condition is a natural language string like "User asks why or wants details".
- * The matcher extracts content words and checks for overlap with the user message.
- *
- * @example
- * ```typescript
- * defaultMatcher('User asks why or wants details', 'Why was I denied?')
- * // → true (matches "why")
- *
- * defaultMatcher('User asks why or wants details', 'What is the weather?')
- * // → false (no keyword overlap)
- * ```
- */
-export declare function defaultConditionMatcher(condition: string, userMessage: string): boolean;
-/**
- * A strict follow-up that's waiting for the next user message.
- */
-export interface PendingStrictFollowUp {
-    /** The resolved follow-up with concrete params. */
-    readonly followUp: ResolvedFollowUp;
-    /** The tool that produced the original result. */
-    readonly sourceToolId: string;
-    /** Custom matcher function, if provided on the binding. */
-    readonly matcher?: (userMessage: string) => boolean;
-}
-/**
- * Manages pending strict follow-ups between agent loop iterations.
- *
- * After tool execution, if any strict follow-up fired, it's stored here.
- * Before the next LLM call, the user's message is checked against pending
- * follow-ups. If matched, the follow-up is consumed and returned for
- * auto-execution.
- *
- * @example
- * ```typescript
- * const manager = new PendingFollowUpManager();
- *
- * // After tool execution with strict follow-up
- * manager.setPending({
- *   followUp: { toolId: 'get_trace', params: { traceId: 'tr_1' }, ... },
- *   sourceToolId: 'evaluate_loan',
- * });
- *
- * // Before next LLM call — check user message
- * const matched = manager.checkAndConsume('Why was I denied?');
- * if (matched) {
- *   // Auto-execute get_trace({ traceId: 'tr_1' }) — skip LLM
- * }
- * ```
- */
-export declare class PendingFollowUpManager {
-    private pending;
-    /** Store a strict follow-up for the next user message check. */
-    setPending(followUp: PendingStrictFollowUp): void;
-    /** Check if there's a pending follow-up. */
-    hasPending(): boolean;
-    /** Get the pending follow-up without consuming it. */
-    getPending(): PendingStrictFollowUp | undefined;
-    /**
-     * Check user message against pending follow-up condition.
-     * If matched, consumes and returns the follow-up. If not matched, clears it.
-     *
-     * @returns The matched follow-up for auto-execution, or undefined.
-     */
-    checkAndConsume(userMessage: string): PendingStrictFollowUp | undefined;
-    /** Clear any pending follow-up. */
-    clear(): void;
-}
-//# sourceMappingURL=strictFollowUp.d.ts.map

package/dist/types/lib/instructions/strictFollowUp.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"strictFollowUp.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/strictFollowUp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CA6DvF;AAID;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAAoC;IAEnD,gEAAgE;IAChE,UAAU,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAIjD,4CAA4C;IAC5C,UAAU,IAAI,OAAO;IAIrB,sDAAsD;IACtD,UAAU,IAAI,qBAAqB,GAAG,SAAS;IAI/C;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAoBvE,mCAAmC;IACnC,KAAK,IAAI,IAAI;CAGd"}

package/dist/types/lib/instructions/template.d.ts

@@ -1,52 +0,0 @@
-/**
- * InstructionTemplate — generates LLM-facing text from resolved instructions.
- *
- * The template controls HOW instructions appear in the recency window.
- * The developer writes structured data (inject text, follow-up bindings).
- * The template formats it for the LLM.
- *
- * Pluggable: organizations can customize the voice and format.
- * Default template works well for all model families.
- */
-import type { ResolvedInstruction, ResolvedFollowUp } from './evaluator';
-/**
- * Pluggable template for formatting instructions as LLM-facing text.
- *
- * Each method is optional — unimplemented methods fall back to the default.
- *
- * @example
- * ```typescript
- * const healthcareTemplate: InstructionTemplate = {
- *   formatFollowUp: (fu) =>
- *     `If the patient requests additional information, ` +
- *     `retrieve the clinical decision audit using ${fu.toolId}.`,
- * };
- * ```
- */
-export interface InstructionTemplate {
-    /** Format a behavioral instruction. Default: inject text as-is. */
-    formatText?(text: string): string;
-    /** Format a follow-up binding. Default: structured block. */
-    formatFollowUp?(followUp: ResolvedFollowUp): string;
-    /** Format the full injection block (all instructions combined). */
-    formatBlock?(parts: string[]): string;
-}
-/**
- * Render resolved instructions into LLM-facing text.
- *
- * Takes the output of `evaluateInstructions()` (already sorted in injection order)
- * and produces a single string to append to the tool result message.
- *
- * Returns `undefined` if no instructions have injectable content.
- *
- * @example
- * ```typescript
- * const fired = evaluateInstructions(tool.instructions, ctx);
- * const text = renderInstructions(fired);
- * if (text) {
- *   toolResultMessage.content += '\n\n' + text;
- * }
- * ```
- */
-export declare function renderInstructions(instructions: ResolvedInstruction[], template?: InstructionTemplate): string | undefined;
-//# sourceMappingURL=template.d.ts.map

package/dist/types/lib/instructions/template.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIzE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,6DAA6D;IAC7D,cAAc,CAAC,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC;IACpD,mEAAmE;IACnE,WAAW,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CACvC;AAuCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,mBAAmB,EAAE,EACnC,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,MAAM,GAAG,SAAS,CAuBpB"}