agentfootprint 1.0.0

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

@@ -0,0 +1,150 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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;AAM9C;;;;;;;;;;;;;;;;;;;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;AAWD;;;;;;;;;;;;;;;;;;;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

@@ -0,0 +1,56 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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,CAmCX"}

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

@@ -0,0 +1,99 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAIxG,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

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1 @@
+{"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,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxG,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,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE3H,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

@@ -0,0 +1,54 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,85 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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,CA4CpB"}

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

@@ -0,0 +1,88 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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,CA6BvF;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

@@ -0,0 +1,52 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}