agentfootprint 1.22.0 → 2.0.1

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

@@ -1,86 +0,0 @@
-/**
- * InstructionRecorder — tracks which LLM instructions fired and follow-up usage.
- *
- * Implements AgentRecorder so it plugs into the standard `.recorder()` API.
- * Records per-tool instruction firings and follow-up accuracy for evaluation.
- *
- * @example
- * ```typescript
- * import { Agent, InstructionRecorder } from 'agentfootprint';
- *
- * const recorder = new InstructionRecorder();
- * const agent = Agent.create({ provider })
- *   .recorder(recorder)
- *   .build();
- *
- * await agent.run('Check my order');
- *
- * console.log(recorder.getSummary());
- * // {
- * //   totalFired: 2,
- * //   totalFollowUpsOffered: 1,
- * //   byTool: {
- * //     check_order: {
- * //       instructions: { 'cancelled': { fired: 1, safety: false } },
- * //       followUps: { 'get_trace': { offered: 1 } },
- * //     }
- * //   }
- * // }
- * ```
- */
-import type { AgentRecorder } from '../../core';
-import type { ResolvedInstruction } from './evaluator';
-export interface InstructionFiring {
-    /** Number of times this instruction fired. */
-    readonly fired: number;
-    /** Whether this is a safety instruction. */
-    readonly safety: boolean;
-}
-export interface FollowUpOffering {
-    /** Number of times this follow-up was offered. */
-    readonly offered: number;
-    /** Target tool ID. */
-    readonly toolId: string;
-}
-export interface ToolInstructionStats {
-    /** Instructions that fired for this tool, keyed by instruction ID. */
-    readonly instructions: Record<string, InstructionFiring>;
-    /** Follow-ups offered for this tool, keyed by follow-up toolId. */
-    readonly followUps: Record<string, FollowUpOffering>;
-}
-export interface InstructionSummary {
-    /** Total instructions fired across all tools. */
-    readonly totalFired: number;
-    /** Total follow-ups offered across all tools. */
-    readonly totalFollowUpsOffered: number;
-    /** Per-tool breakdown. */
-    readonly byTool: Record<string, ToolInstructionStats>;
-}
-export declare class InstructionRecorder implements AgentRecorder {
-    readonly id: string;
-    private firings;
-    private followUps;
-    constructor(id?: string);
-    /**
-     * Record instructions that fired for a tool invocation.
-     *
-     * Called by the agent loop after processInstructions() completes.
-     * Not an AgentRecorder hook — this is a dedicated method because
-     * instruction events don't map to the standard onLLMCall/onToolCall events.
-     */
-    recordFirings(toolId: string, fired: ResolvedInstruction[]): void;
-    /** Get summary of all instruction firings and follow-up offerings. */
-    getSummary(): InstructionSummary;
-    /** Get firing count for a specific instruction on a specific tool. */
-    getFiringCount(toolId: string, instructionId: string): number;
-    /** Get all instruction IDs that fired for a tool. */
-    getFiredInstructionIds(toolId: string): string[];
-    toSnapshot(): {
-        name: string;
-        description: string;
-        preferredOperation: "translate";
-        data: InstructionSummary;
-    };
-    clear(): void;
-}
-//# sourceMappingURL=InstructionRecorder.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"InstructionRecorder.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/InstructionRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIvD,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACvD;AAID,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,OAAO,CAAsE;IACrF,OAAO,CAAC,SAAS,CAAqE;gBAE1E,EAAE,SAAyB;IAIvC;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,GAAG,IAAI;IA2BjE,sEAAsE;IACtE,UAAU,IAAI,kBAAkB;IAkChC,sEAAsE;IACtE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IAI7D,qDAAqD;IACrD,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAKhD,UAAU;;;;;;IASV,KAAK,IAAI,IAAI;CAId"}

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

@@ -1,150 +0,0 @@
-/**
- * Agent-level Instruction type — conditional context injection across all 3 LLM API positions.
- *
- * Unlike tool-level `LLMInstruction` (fires on a specific tool result),
- * an `AgentInstruction` fires based on accumulated Decision Scope state
- * and can inject into system prompt, tools, AND tool response rules.
- *
- * Evaluated by the InstructionsToLLM subflow BEFORE the 3 API slots.
- *
- * Naming:
- *   `activeWhen` (agent-level, reads decision scope) vs
- *   `when` (tool-level, reads tool result context) — no collision.
- */
-import type { ToolDefinition } from '../../types/tools';
-import type { LLMInstruction } from './types';
-/**
- * An instruction that spans all 3 LLM API input positions.
- *
- * Evaluated per iteration by the InstructionsToLLM subflow. When `activeWhen`
- * matches the current Decision Scope, the instruction's outputs are injected
- * into the corresponding API slot.
- *
- * @example
- * ```typescript
- * const refundInstruction: AgentInstruction<MyDecision> = {
- *   id: 'refund-handling',
- *   activeWhen: (d) => d.orderStatus === 'denied',
- *   prompt: 'Handle denied orders with empathy. Follow refund policy.',
- *   tools: [processRefund, getTrace],
- *   onToolResult: [
- *     { id: 'empathy', text: 'Be empathetic. Do NOT promise reversal.' },
- *   ],
- * };
- * ```
- */
-export interface AgentInstruction<TDecision = unknown> {
-    /** Unique instruction identifier. */
-    readonly id: string;
-    /** Human-readable description (for narrative, docs, debug). */
-    readonly description?: string;
-    /**
-     * Condition: when does this instruction activate?
-     * Receives `scope.decision` — the bounded decision scope, not the full agent state.
-     * Omit for unconditional (always active).
-     *
-     * Must be synchronous and side-effect-free.
-     * Predicates that throw are skipped (fail-open) unless `safety: true` (fail-closed).
-     */
-    readonly activeWhen?: (decision: TDecision) => boolean;
-    /**
-     * Position 1: Text merged into system prompt.
-     * Appended after the base prompt from PromptProvider.
-     */
-    readonly prompt?: string;
-    /**
-     * Position 2: Tools added to the tools list.
-     * Merged with the base tools from ToolProvider. Deduplicated by ID.
-     */
-    readonly tools?: readonly ToolDefinition[];
-    /**
-     * Position 3: Rules evaluated against tool results (in recency window).
-     * Reuses the existing LLMInstruction type — `when`, `text`, `followUp`, `safety`.
-     * These fire during tool execution, same as tool-level instructions.
-     *
-     * Note: Rules from multiple matched instructions are accumulated (not deduplicated
-     * by ID). If you need unique rules, use unique IDs per AgentInstruction.
-     */
-    readonly onToolResult?: readonly LLMInstruction[];
-    /**
-     * Priority for ordering when multiple instructions match.
-     * Lower = higher priority. Ties broken by registration order.
-     *
-     * Safety instructions are always sorted LAST regardless of priority,
-     * mirroring the tool-level `LLMInstruction` ordering convention.
-     * @default 0
-     */
-    readonly priority?: number;
-    /**
-     * Controls predicate evaluation behavior when `activeWhen` throws.
-     *
-     * - `false` (default): fail-open — broken predicate skips the instruction.
-     * - `true`: fail-closed — broken predicate fires the instruction.
-     *
-     * Safety instructions are also sorted LAST in the output (highest priority
-     * position for system prompt injection). This is the predicate-level safety
-     * flag; for Position 3 injection ordering, use `LLMInstruction.safety`
-     * on individual `onToolResult` rules.
-     *
-     * @default false
-     */
-    readonly safety?: boolean;
-}
-/** Output of evaluating agent instructions against the decision scope. */
-export interface InstructionEvaluationResult {
-    /** Prompt text fragments to merge into system prompt (Position 1). */
-    readonly promptInjections: readonly string[];
-    /** Tool definitions to merge into tools list (Position 2). */
-    readonly toolInjections: readonly ToolDefinition[];
-    /** Tool-result rules to evaluate during tool execution (Position 3). */
-    readonly responseRules: readonly LLMInstruction[];
-    /** IDs of instructions that matched (for narrative/recorder). */
-    readonly matchedIds: readonly string[];
-}
-/**
- * Evaluate agent-level instructions against the current decision scope.
- *
- * Returns categorized outputs for each of the 3 LLM API positions.
- * Instructions are sorted by priority (lower = first), with safety
- * instructions always sorted LAST (matching tool-level convention).
- *
- * Error handling follows the same pattern as tool-level instructions:
- *   - Behavioral (safety: false): predicate throws → skip (fail-open)
- *   - Safety (safety: true): predicate throws → fire (fail-closed)
- *
- * @example
- * ```typescript
- * const result = evaluateAgentInstructions(instructions, { orderStatus: 'denied' });
- * // result.promptInjections → ['Handle denied orders with empathy.']
- * // result.toolInjections → [processRefund, getTrace]
- * // result.responseRules → [{ id: 'empathy', text: '...' }]
- * // result.matchedIds → ['refund-handling']
- * ```
- */
-export declare function evaluateAgentInstructions<TDecision>(instructions: readonly AgentInstruction<TDecision>[] | undefined, decision: TDecision): InstructionEvaluationResult;
-/**
- * Create a validated agent-level instruction.
- *
- * This is the preferred way to create instructions — validates the `id` field
- * at build time and provides good TypeScript inference for the decision type.
- *
- * @example
- * ```typescript
- * interface MyDecision {
- *   orderStatus: 'pending' | 'denied' | null;
- *   riskLevel: 'low' | 'high';
- * }
- *
- * const refund = defineInstruction<MyDecision>({
- *   id: 'refund-handling',
- *   activeWhen: (d) => d.orderStatus === 'denied',
- *   prompt: 'Handle denied orders with empathy.',
- *   tools: [processRefund, getTrace],
- *   onToolResult: [
- *     { id: 'empathy', text: 'Do NOT promise reversal.' },
- *   ],
- * });
- * ```
- */
-export declare function defineInstruction<TDecision = unknown>(config: AgentInstruction<TDecision>): AgentInstruction<TDecision>;
-//# sourceMappingURL=agentInstruction.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"agentInstruction.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/agentInstruction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAO9C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB,CAAC,SAAS,GAAG,OAAO;IACnD,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,OAAO,CAAC;IAEvD;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAE3C;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAElD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAID,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,SAAS,cAAc,EAAE,CAAC;IACnD,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,SAAS,cAAc,EAAE,CAAC;IAClD,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAeD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EACjD,YAAY,EAAE,SAAS,gBAAgB,CAAC,SAAS,CAAC,EAAE,GAAG,SAAS,EAChE,QAAQ,EAAE,SAAS,GAClB,2BAA2B,CAwE7B;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,GAAG,OAAO,EACnD,MAAM,EAAE,gBAAgB,CAAC,SAAS,CAAC,GAClC,gBAAgB,CAAC,SAAS,CAAC,CAK7B"}

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

@@ -1,56 +0,0 @@
-/**
- * InstructionsToLLM subflow — evaluates agent-level instructions before the 3 API slots.
- *
- * Runs once per loop iteration (Dynamic pattern) or once before the loop (Regular).
- * Reads the current Decision Scope, evaluates all registered instructions'
- * `activeWhen` predicates, and outputs categorized injections for each slot:
- *
- *   promptInjections → consumed by SystemPrompt slot
- *   toolInjections   → consumed by Tools slot
- *   responseRules    → consumed by tool execution subflow
- *
- * The instruction registry is baked into the subflow via closure at build time.
- * This is a footprintjs flowchart subflow — visible in narrative/BTS.
- *
- * Loop position:
- *   Seed → [InstructionsToLLM] → [SystemPrompt] → [Messages] → [Tools] → ...
- */
-import type { FlowChart } from 'footprintjs';
-import type { AgentInstruction } from './agentInstruction';
-/**
- * Build the InstructionsToLLM subflow from a registry of agent-level instructions.
- *
- * The instructions array is captured by closure — immutable after build (shallow freeze).
- * The subflow reads `scope.decision` (from parent inputMapper) and writes
- * the categorized outputs for downstream slots to consume.
- *
- * **Parent state requirements:** The parent chart's `inputMapper` MUST map the
- * `decision` field. If `decision` is missing (undefined), all instructions with
- * `activeWhen` predicates will evaluate against `undefined` — behavioral predicates
- * will throw and be skipped (fail-open), safety predicates will fire (fail-closed).
- *
- * The `outputMapper` should map the 3 output fields back to the parent state:
- * `promptInjections`, `toolInjections`, `responseRules` (and optionally
- * `matchedInstructions` for narrative enrichment).
- *
- * @param instructions - Agent-level instructions registered via `.instruction()`.
- *   Empty array is valid (subflow becomes a no-op pass-through).
- *
- * @example
- * ```typescript
- * const subflow = buildInstructionsToLLMSubflow([refundInstruction, complianceInstruction]);
- *
- * // Mount in agent loop (parent state must include matching fields):
- * builder.addSubFlowChartNext('sf-instructions-to-llm', subflow, 'InstructionsToLLM', {
- *   inputMapper: (parent) => ({ decision: parent.decision }),
- *   outputMapper: (sf) => ({
- *     promptInjections: sf.promptInjections,
- *     toolInjections: sf.toolInjections,
- *     responseRules: sf.responseRules,
- *     matchedInstructions: sf.matchedInstructions,
- *   }),
- * });
- * ```
- */
-export declare function buildInstructionsToLLMSubflow(instructions: readonly AgentInstruction[]): FlowChart;
-//# sourceMappingURL=buildInstructionsToLLMSubflow.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"buildInstructionsToLLMSubflow.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/buildInstructionsToLLMSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAGzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,SAAS,gBAAgB,EAAE,GACxC,SAAS,CAuCX"}

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

@@ -1,99 +0,0 @@
-/**
- * Instruction evaluator — matches instructions against tool results.
- *
- * Evaluates `when` predicates, sorts by priority, and orders for injection:
- *   1. Follow-up bindings (structured actions)
- *   2. Behavioral instructions (free text guidance)
- *   3. Safety instructions LAST (closest to LLM generation = highest attention)
- *
- * Predicates that throw are skipped with a warning (fail-open for behavioral,
- * fail-closed for safety). This is the defensive behavior — a broken predicate
- * should not prevent the agent from working, but safety instructions should
- * fail-closed (fire when in doubt).
- */
-import type { LLMInstruction, InstructionContext, RuntimeFollowUp, InstructionOverride } from './types';
-/** A resolved instruction — ready for injection into the recency window. */
-export interface ResolvedInstruction {
-    /** Instruction ID (for recording/tracking). */
-    readonly id: string;
-    /** Text appended to tool result (if any). */
-    readonly text?: string;
-    /** Resolved follow-up with concrete params (if any). */
-    readonly resolvedFollowUp?: ResolvedFollowUp;
-    /** Whether this is a safety instruction. */
-    readonly safety: boolean;
-    /** Original priority value. */
-    readonly priority: number;
-}
-/** Follow-up binding with params already resolved from the tool result. */
-export interface ResolvedFollowUp {
-    readonly toolId: string;
-    readonly params: Record<string, unknown>;
-    readonly description: string;
-    readonly condition: string;
-    readonly strict: boolean;
-}
-/**
- * Evaluate build-time instructions against a tool result context.
- *
- * Returns resolved instructions sorted for injection:
- *   1. Non-safety with follow-up only (structured actions first)
- *   2. Non-safety with inject (behavioral guidance)
- *   3. Safety instructions (LAST = highest attention weight)
- *
- * Within each group, sorted by priority (lower = first), then array order.
- *
- * @example
- * ```typescript
- * const fired = evaluateInstructions(tool.instructions, {
- *   content: { status: 'denied', traceId: 'tr_8f3a' },
- *   error: undefined,
- *   latencyMs: 42,
- *   input: { applicantId: 'a-1' },
- *   toolId: 'evaluate_loan',
- * });
- *
- * // fired: [{ id: 'denial-empathy', text: '...', resolvedFollowUp: {...} }]
- * ```
- */
-export declare function evaluateInstructions(instructions: readonly LLMInstruction[] | undefined, ctx: InstructionContext): ResolvedInstruction[];
-/**
- * Merge build-time resolved instructions with runtime instructions/followUps.
- *
- * Runtime instructions (from handler return) are appended after build-time
- * behavioral instructions but before safety instructions.
- *
- * @example
- * ```typescript
- * const buildTime = evaluateInstructions(tool.instructions, ctx);
- * const runtime = {
- *   instructions: ['Service degraded. Set expectations.'],
- *   followUps: [{ toolId: 'status_page', params: {}, description: '...', condition: '...' }],
- * };
- * const merged = mergeRuntimeInstructions(buildTime, runtime);
- * ```
- */
-export declare function mergeRuntimeInstructions(buildTime: ResolvedInstruction[], runtime?: {
-    instructions?: readonly string[];
-    followUps?: readonly RuntimeFollowUp[];
-}): ResolvedInstruction[];
-/**
- * Apply agent-level overrides to a tool's instructions.
- *
- * Returns a new instruction array with overrides applied:
- * 1. Suppress: remove instructions by ID
- * 2. Replace: merge partial overrides into existing instructions by ID
- * 3. Add: append new instructions at the end
- *
- * @example
- * ```typescript
- * const original = tool.instructions;
- * const overridden = applyInstructionOverrides(original, {
- *   suppress: ['low-stock'],
- *   add: [{ id: 'premium-oos', when: ..., text: '...' }],
- *   replace: { 'out-of-stock': { text: 'Suggest B2B channel.' } },
- * });
- * ```
- */
-export declare function applyInstructionOverrides(instructions: readonly LLMInstruction[] | undefined, override: InstructionOverride): LLMInstruction[];
-//# sourceMappingURL=evaluator.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAIjB,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EACnD,GAAG,EAAE,kBAAkB,GACtB,mBAAmB,EAAE,CA0DvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,mBAAmB,EAAE,EAChC,OAAO,CAAC,EAAE;IACR,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CACxC,GACA,mBAAmB,EAAE,CAwCvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EACnD,QAAQ,EAAE,mBAAmB,GAC5B,cAAc,EAAE,CA2BlB"}

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"}