agentfootprint 1.0.0

package/dist/esm/lib/instructions/buildInstructionsToLLMSubflow.js

@@ -0,0 +1,83 @@
+/**
+ * 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 { flowChart } from 'footprintjs';
+import { evaluateAgentInstructions } 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 function buildInstructionsToLLMSubflow(instructions) {
+    // Freeze the instruction list — no mutations after build.
+    // Note: shallow freeze — individual instruction objects are readonly-typed
+    // but not deeply frozen. This is sufficient since TypeScript enforces readonly.
+    const frozenInstructions = Object.freeze([...instructions]);
+    return flowChart('EvaluateInstructions', (scope) => {
+        // Read decision scope from parent. If missing (inputMapper didn't map it),
+        // pass through as-is — predicates will see undefined and fail-open/closed
+        // according to their safety flag.
+        const decision = scope.decision;
+        const result = evaluateAgentInstructions(frozenInstructions, decision);
+        scope.promptInjections = [...result.promptInjections];
+        // Convert ToolDefinition → LLMToolDescription (strip handler for LLM consumption)
+        scope.toolInjections = result.toolInjections.map((t) => ({
+            name: t.id,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        }));
+        scope.responseRules = [...result.responseRules];
+        // Narrative enrichment — which instructions fired and why
+        if (result.matchedIds.length > 0) {
+            scope.matchedInstructions = `${result.matchedIds.length} matched: ${result.matchedIds.join(', ')}`;
+        }
+        else {
+            scope.matchedInstructions = 'none matched';
+        }
+    }, 'evaluate-instructions', undefined, 'Evaluate agent instructions against Decision Scope').build();
+}
+//# sourceMappingURL=buildInstructionsToLLMSubflow.js.map

package/dist/esm/lib/instructions/buildInstructionsToLLMSubflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildInstructionsToLLMSubflow.js","sourceRoot":"","sources":["../../../../src/lib/instructions/buildInstructionsToLLMSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,6BAA6B,CAC3C,YAAyC;IAEzC,0DAA0D;IAC1D,2EAA2E;IAC3E,gFAAgF;IAChF,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;IAE5D,OAAO,SAAS,CACd,sBAAsB,EACtB,CAAC,KAAyC,EAAE,EAAE;QAC5C,2EAA2E;QAC3E,0EAA0E;QAC1E,kCAAkC;QAClC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAChC,MAAM,MAAM,GAAG,yBAAyB,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;QAEvE,KAAK,CAAC,gBAAgB,GAAG,CAAC,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACtD,kFAAkF;QAClF,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAsB,EAAE,CAAC,CAAC;YAC3E,IAAI,EAAE,CAAC,CAAC,EAAE;YACV,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;SAC3B,CAAC,CAAC,CAAC;QACJ,KAAK,CAAC,aAAa,GAAG,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;QAEhD,0DAA0D;QAC1D,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,KAAK,CAAC,mBAAmB,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,aAAa,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACrG,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,mBAAmB,GAAG,cAAc,CAAC;QAC7C,CAAC;IACH,CAAC,EACD,uBAAuB,EACvB,SAAS,EACT,oDAAoD,CACrD,CAAC,KAAK,EAAE,CAAC;AACZ,CAAC"}

package/dist/esm/lib/instructions/evaluator.js

@@ -0,0 +1,196 @@
+/**
+ * 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).
+ */
+// ── Evaluator ───────────────────────────────────────────────────────────
+/**
+ * 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 function evaluateInstructions(instructions, ctx) {
+    if (!instructions || instructions.length === 0)
+        return [];
+    const matched = [];
+    for (const instr of instructions) {
+        // Evaluate predicate — skip on throw for behavioral, fire on throw for safety
+        if (instr.when) {
+            try {
+                if (!instr.when(ctx))
+                    continue; // predicate returned false
+            }
+            catch {
+                if (instr.safety) {
+                    // Safety: fail-closed — fire the instruction when predicate errors
+                    // Better to inject a safety instruction unnecessarily than to miss it
+                }
+                else {
+                    // Behavioral: fail-open — skip broken predicate
+                    continue;
+                }
+            }
+        }
+        // No `when` = unconditional — always fires
+        // Resolve follow-up params if present
+        let resolvedFollowUp;
+        if (instr.followUp) {
+            try {
+                const params = instr.followUp.params(ctx);
+                resolvedFollowUp = {
+                    toolId: instr.followUp.toolId,
+                    params,
+                    description: instr.followUp.description,
+                    condition: instr.followUp.condition,
+                    strict: instr.followUp.strict ?? false,
+                };
+            }
+            catch {
+                // If params resolution fails, skip the follow-up but keep the inject
+                resolvedFollowUp = undefined;
+            }
+        }
+        matched.push({
+            id: instr.id,
+            text: instr.text,
+            resolvedFollowUp,
+            safety: instr.safety ?? false,
+            priority: instr.priority ?? 0,
+        });
+    }
+    // Sort for injection order:
+    // 1. Non-safety sorted by priority (lower first), then array order (stable sort)
+    // 2. Safety instructions at the end (closest to generation = highest attention)
+    return matched.sort((a, b) => {
+        // Safety always after non-safety
+        if (a.safety !== b.safety)
+            return a.safety ? 1 : -1;
+        // Within same safety group, sort by priority
+        return a.priority - b.priority;
+    });
+}
+/**
+ * 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 function mergeRuntimeInstructions(buildTime, runtime) {
+    if (!runtime)
+        return buildTime;
+    const runtimeResolved = [];
+    // Runtime follow-ups
+    if (runtime.followUps) {
+        for (const fu of runtime.followUps) {
+            if (!fu.toolId || !fu.params)
+                continue; // validate required fields
+            runtimeResolved.push({
+                id: `runtime-followup-${fu.toolId}`,
+                resolvedFollowUp: {
+                    toolId: fu.toolId,
+                    params: fu.params,
+                    description: fu.description,
+                    condition: fu.condition,
+                    strict: fu.strict ?? false,
+                },
+                safety: false,
+                priority: 0,
+            });
+        }
+    }
+    // Runtime behavioral instructions
+    if (runtime.instructions) {
+        for (let i = 0; i < runtime.instructions.length; i++) {
+            runtimeResolved.push({
+                id: `runtime-text-${i}`,
+                text: runtime.instructions[i],
+                safety: false,
+                priority: 0,
+            });
+        }
+    }
+    // Merge: build-time non-safety → runtime → build-time safety
+    const nonSafety = buildTime.filter((r) => !r.safety);
+    const safety = buildTime.filter((r) => r.safety);
+    return [...nonSafety, ...runtimeResolved, ...safety];
+}
+/**
+ * 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 function applyInstructionOverrides(instructions, override) {
+    if (!instructions || instructions.length === 0) {
+        return [...(override.add ?? [])];
+    }
+    const suppressSet = new Set(override.suppress ?? []);
+    const replaceMap = override.replace ?? {};
+    // 1. Filter suppressed, then apply replacements
+    const result = [];
+    for (const instr of instructions) {
+        if (suppressSet.has(instr.id))
+            continue; // suppressed
+        const replacement = replaceMap[instr.id];
+        if (replacement) {
+            result.push({ ...instr, ...replacement, id: instr.id }); // merge, preserve ID
+        }
+        else {
+            result.push(instr);
+        }
+    }
+    // 2. Add new instructions
+    if (override.add) {
+        result.push(...override.add);
+    }
+    return result;
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/esm/lib/instructions/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../../../src/lib/instructions/evaluator.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/instructions/index.js

@@ -0,0 +1,10 @@
+export { quickBind, follow } from './types';
+export { evaluateInstructions, mergeRuntimeInstructions, applyInstructionOverrides } from './evaluator';
+export { renderInstructions } from './template';
+export { processInstructions } from './inject';
+export { previewInstructions } from './preview';
+export { InstructionRecorder } from './InstructionRecorder';
+export { defaultConditionMatcher, PendingFollowUpManager } from './strictFollowUp';
+export { evaluateAgentInstructions, defineInstruction } from './agentInstruction';
+export { buildInstructionsToLLMSubflow } from './buildInstructionsToLLMSubflow';
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/instructions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAW5C,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAGxG,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGhD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAG/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAGnF,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGlF,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/esm/lib/instructions/inject.js

@@ -0,0 +1,55 @@
+/**
+ * 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 { evaluateInstructions, mergeRuntimeInstructions } from './evaluator';
+import { renderInstructions } from './template';
+/**
+ * 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 function processInstructions(originalContent, buildTimeInstructions, ctx, runtime, template) {
+    // 1. Evaluate build-time instructions
+    const buildTime = evaluateInstructions(buildTimeInstructions, ctx);
+    // 2. Merge with runtime instructions
+    const all = mergeRuntimeInstructions(buildTime, runtime);
+    if (all.length === 0) {
+        return { content: originalContent, fired: [], injected: false };
+    }
+    // 3. Render to text
+    const text = renderInstructions(all, template);
+    if (!text) {
+        return { content: originalContent, fired: all, injected: false };
+    }
+    // 4. Append to tool result content
+    const augmented = originalContent + '\n\n' + text;
+    return { content: augmented, fired: all, injected: true };
+}
+//# sourceMappingURL=inject.js.map

package/dist/esm/lib/instructions/inject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject.js","sourceRoot":"","sources":["../../../../src/lib/instructions/inject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgBhD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,mBAAmB,CACjC,eAAuB,EACvB,qBAA4D,EAC5D,GAAuB,EACvB,OAGC,EACD,QAA8B;IAE9B,sCAAsC;IACtC,MAAM,SAAS,GAAG,oBAAoB,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAEnE,qCAAqC;IACrC,MAAM,GAAG,GAAG,wBAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAEzD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAClE,CAAC;IAED,oBAAoB;IACpB,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAE/C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IAED,mCAAmC;IACnC,MAAM,SAAS,GAAG,eAAe,GAAG,MAAM,GAAG,IAAI,CAAC;IAClD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5D,CAAC"}

package/dist/esm/lib/instructions/preview.js

@@ -0,0 +1,88 @@
+/**
+ * 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 { evaluateInstructions, applyInstructionOverrides } from './evaluator';
+import { renderInstructions } from './template';
+// ── Preview Function ────────────────────────────────────────
+/**
+ * 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 function previewInstructions(instructions, context, options) {
+    // Apply overrides if provided
+    let effectiveInstructions = instructions;
+    if (options?.overrides && instructions) {
+        effectiveInstructions = applyInstructionOverrides(instructions, options.overrides);
+    }
+    // Build full InstructionContext from preview context
+    const ctx = {
+        content: context.content,
+        error: context.error,
+        latencyMs: context.latencyMs ?? 0,
+        input: context.input ?? {},
+        toolId: context.toolId,
+    };
+    // Evaluate
+    const fired = evaluateInstructions(effectiveInstructions, ctx);
+    // Render
+    const injectedText = renderInstructions(fired, options?.template);
+    // Extract follow-ups
+    const followUps = fired
+        .filter((f) => f.resolvedFollowUp)
+        .map((f) => f.resolvedFollowUp);
+    // Compute skipped IDs
+    const firedIds = fired.map((f) => f.id);
+    const firedSet = new Set(firedIds);
+    const allIds = (effectiveInstructions ?? []).map((i) => i.id);
+    const skippedIds = allIds.filter((id) => !firedSet.has(id));
+    // Rough token estimate
+    const estimatedTokens = injectedText ? Math.ceil(injectedText.length / 4) : 0;
+    return {
+        fired,
+        injectedText,
+        estimatedTokens,
+        followUps,
+        firedIds,
+        skippedIds,
+    };
+}
+//# sourceMappingURL=preview.js.map

package/dist/esm/lib/instructions/preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../../../src/lib/instructions/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAkChD,+DAA+D;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,mBAAmB,CACjC,YAAmD,EACnD,OAAuB,EACvB,OAGC;IAED,8BAA8B;IAC9B,IAAI,qBAAqB,GAAG,YAAY,CAAC;IACzC,IAAI,OAAO,EAAE,SAAS,IAAI,YAAY,EAAE,CAAC;QACvC,qBAAqB,GAAG,yBAAyB,CAAC,YAAY,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACrF,CAAC;IAED,qDAAqD;IACrD,MAAM,GAAG,GAAuB;QAC9B,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC;QACjC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;IAEF,WAAW;IACX,MAAM,KAAK,GAAG,oBAAoB,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAE/D,SAAS;IACT,MAAM,YAAY,GAAG,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAElE,qBAAqB;IACrB,MAAM,SAAS,GAAG,KAAK;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;SACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAiB,CAAC,CAAC;IAEnC,sBAAsB;IACtB,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5D,uBAAuB;IACvB,MAAM,eAAe,GAAG,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9E,OAAO;QACL,KAAK;QACL,YAAY;QACZ,eAAe;QACf,SAAS;QACT,QAAQ;QACR,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/esm/lib/instructions/strictFollowUp.js

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+// ── Condition Matcher ───────────────────────────────────────────────────
+/**
+ * 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 function defaultConditionMatcher(condition, userMessage) {
+    // Extract meaningful words from condition (skip stop words)
+    const stopWords = new Set([
+        'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+        'or', 'and', 'but', 'if', 'of', 'at', 'by', 'for', 'with', 'to',
+        'in', 'on', 'it', 'its', 'this', 'that', 'from', 'as', 'into',
+        'user', 'asks', 'wants', 'about', 'more', 'any', 'some',
+    ]);
+    const conditionWords = condition
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, '')
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !stopWords.has(w));
+    if (conditionWords.length === 0)
+        return false;
+    const messageLower = userMessage.toLowerCase();
+    const messageWords = new Set(messageLower
+        .replace(/[^a-z0-9\s]/g, '')
+        .split(/\s+/)
+        .filter((w) => w.length > 2));
+    // Check if any condition keyword appears as an exact word in the message.
+    // For fuzzy/stem matching, use a custom matcher function.
+    return conditionWords.some((word) => messageWords.has(word));
+}
+/**
+ * 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 class PendingFollowUpManager {
+    pending;
+    /** Store a strict follow-up for the next user message check. */
+    setPending(followUp) {
+        this.pending = followUp;
+    }
+    /** Check if there's a pending follow-up. */
+    hasPending() {
+        return !!this.pending;
+    }
+    /** Get the pending follow-up without consuming it. */
+    getPending() {
+        return this.pending;
+    }
+    /**
+     * 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) {
+        if (!this.pending)
+            return undefined;
+        const pending = this.pending;
+        this.pending = undefined; // Always consume — one-shot
+        // Use custom matcher if provided, otherwise default keyword matcher
+        let matched;
+        try {
+            matched = pending.matcher
+                ? pending.matcher(userMessage)
+                : defaultConditionMatcher(pending.followUp.condition, userMessage);
+        }
+        catch {
+            // Broken matcher should not crash the agent — fail-safe: skip the follow-up
+            return undefined;
+        }
+        return matched ? pending : undefined;
+    }
+    /** Clear any pending follow-up. */
+    clear() {
+        this.pending = undefined;
+    }
+}
+//# sourceMappingURL=strictFollowUp.js.map

package/dist/esm/lib/instructions/strictFollowUp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strictFollowUp.js","sourceRoot":"","sources":["../../../../src/lib/instructions/strictFollowUp.ts"],"names":[],"mappings":"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"}