agentfootprint 1.0.0

package/dist/lib/instructions/inject.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processInstructions = void 0;
+const evaluator_1 = require("./evaluator");
+const template_1 = require("./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
+ * ```
+ */
+function processInstructions(originalContent, buildTimeInstructions, ctx, runtime, template) {
+    // 1. Evaluate build-time instructions
+    const buildTime = (0, evaluator_1.evaluateInstructions)(buildTimeInstructions, ctx);
+    // 2. Merge with runtime instructions
+    const all = (0, evaluator_1.mergeRuntimeInstructions)(buildTime, runtime);
+    if (all.length === 0) {
+        return { content: originalContent, fired: [], injected: false };
+    }
+    // 3. Render to text
+    const text = (0, template_1.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 };
+}
+exports.processInstructions = processInstructions;
+//# sourceMappingURL=inject.js.map

package/dist/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,2CAA6E;AAC7E,yCAAgD;AAgBhD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,mBAAmB,CACjC,eAAuB,EACvB,qBAA4D,EAC5D,GAAuB,EACvB,OAGC,EACD,QAA8B;IAE9B,sCAAsC;IACtC,MAAM,SAAS,GAAG,IAAA,gCAAoB,EAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAEnE,qCAAqC;IACrC,MAAM,GAAG,GAAG,IAAA,oCAAwB,EAAC,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,IAAA,6BAAkB,EAAC,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;AA9BD,kDA8BC"}

package/dist/lib/instructions/preview.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * 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' } }],
+ * // }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.previewInstructions = void 0;
+const evaluator_1 = require("./evaluator");
+const template_1 = require("./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'] },
+ * });
+ * ```
+ */
+function previewInstructions(instructions, context, options) {
+    // Apply overrides if provided
+    let effectiveInstructions = instructions;
+    if (options?.overrides && instructions) {
+        effectiveInstructions = (0, evaluator_1.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 = (0, evaluator_1.evaluateInstructions)(effectiveInstructions, ctx);
+    // Render
+    const injectedText = (0, template_1.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,
+    };
+}
+exports.previewInstructions = previewInstructions;
+//# sourceMappingURL=preview.js.map

package/dist/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,2CAA8E;AAC9E,yCAAgD;AAkChD,+DAA+D;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,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,IAAA,qCAAyB,EAAC,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,IAAA,gCAAoB,EAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAE/D,SAAS;IACT,MAAM,YAAY,GAAG,IAAA,6BAAkB,EAAC,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;AAnDD,kDAmDC"}

package/dist/lib/instructions/strictFollowUp.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PendingFollowUpManager = exports.defaultConditionMatcher = void 0;
+// ── 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)
+ * ```
+ */
+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));
+}
+exports.defaultConditionMatcher = defaultConditionMatcher;
+/**
+ * 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
+ * }
+ * ```
+ */
+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;
+    }
+}
+exports.PendingFollowUpManager = PendingFollowUpManager;
+//# sourceMappingURL=strictFollowUp.js.map

package/dist/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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"}

package/dist/lib/instructions/template.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderInstructions = void 0;
+// ── Default Template ────────────────────────────────────────────────────
+/**
+ * Default instruction template — works well across Claude, GPT, and Llama.
+ *
+ * Uses clear delimiters and structured follow-up format:
+ * ```
+ * [INSTRUCTION] Be empathetic. Do NOT promise reversal.
+ *
+ * [AVAILABLE ACTION]
+ * Action: Retrieve detailed denial reasoning
+ * Tool: get_execution_trace
+ * Parameters: {"traceId":"tr_8f3a"}
+ * Use when: User asks why or wants details
+ * ```
+ */
+function defaultFormatInject(text) {
+    return `[INSTRUCTION] ${text}`;
+}
+function defaultFormatFollowUp(fu) {
+    const lines = [
+        '[AVAILABLE ACTION]',
+        `Action: ${fu.description}`,
+        `Tool: ${fu.toolId}`,
+        `Parameters: ${JSON.stringify(fu.params)}`,
+        `Use when: ${fu.condition}`,
+    ];
+    return lines.join('\n');
+}
+function defaultFormatBlock(parts) {
+    return parts.join('\n\n');
+}
+// ── Render Function ─────────────────────────────────────────────────────
+/**
+ * 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;
+ * }
+ * ```
+ */
+function renderInstructions(instructions, template) {
+    if (instructions.length === 0)
+        return undefined;
+    const formatText = template?.formatText ?? defaultFormatInject;
+    const formatFollowUp = template?.formatFollowUp ?? defaultFormatFollowUp;
+    const formatBlock = template?.formatBlock ?? defaultFormatBlock;
+    const parts = [];
+    for (const instr of instructions) {
+        // Follow-up first (structured action), then inject (behavioral guidance)
+        // Within each instruction, follow-up before inject so the LLM reads
+        // "here's what you can do" before "here's how to behave"
+        if (instr.resolvedFollowUp) {
+            parts.push(formatFollowUp(instr.resolvedFollowUp));
+        }
+        if (instr.text) {
+            parts.push(formatText(instr.text));
+        }
+    }
+    if (parts.length === 0)
+        return undefined;
+    return formatBlock(parts);
+}
+exports.renderInstructions = renderInstructions;
+//# sourceMappingURL=template.js.map

package/dist/lib/instructions/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/lib/instructions/template.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AA6BH,2EAA2E;AAE3E;;;;;;;;;;;;;GAaG;AACH,SAAS,mBAAmB,CAAC,IAAY;IACvC,OAAO,iBAAiB,IAAI,EAAE,CAAC;AACjC,CAAC;AAED,SAAS,qBAAqB,CAAC,EAAoB;IACjD,MAAM,KAAK,GAAG;QACZ,oBAAoB;QACpB,WAAW,EAAE,CAAC,WAAW,EAAE;QAC3B,SAAS,EAAE,CAAC,MAAM,EAAE;QACpB,eAAe,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE;QAC1C,aAAa,EAAE,CAAC,SAAS,EAAE;KAC5B,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAe;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,2EAA2E;AAE3E;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,kBAAkB,CAChC,YAAmC,EACnC,QAA8B;IAE9B,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEhD,MAAM,UAAU,GAAG,QAAQ,EAAE,UAAU,IAAI,mBAAmB,CAAC;IAC/D,MAAM,cAAc,GAAG,QAAQ,EAAE,cAAc,IAAI,qBAAqB,CAAC;IACzE,MAAM,WAAW,GAAG,QAAQ,EAAE,WAAW,IAAI,kBAAkB,CAAC;IAEhE,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,yEAAyE;QACzE,oEAAoE;QACpE,yDAAyD;QACzD,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AA1BD,gDA0BC"}

package/dist/lib/instructions/types.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * LLMInstruction types — co-located behavioral guidance and structured follow-ups for tools.
+ *
+ * Instructions fire when a tool returns a matching result. The framework injects
+ * the instruction text into the LLM's recency window — right next to the tool result,
+ * where the model pays the most attention.
+ *
+ * Two optional fields — fill in what you need:
+ *   `text`: guidance appended to tool result (LLM reads this literally)
+ *   `followUp`: structured next-action binding (framework formats as string)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.follow = exports.quickBind = void 0;
+// ── quickBind ───────────────────────────────────────────────────────────
+/**
+ * One-liner shorthand for common follow-up bindings.
+ *
+ * Most follow-ups follow a simple pattern: extract a field from the tool result
+ * and pass it to a target tool with the same parameter name. `quickBind`
+ * eliminates the boilerplate.
+ *
+ * @param toolId - Target tool to call
+ * @param paramNames - Field name(s) to extract from `ctx.content` and pass to target tool.
+ *   Single string or array of strings. The field name in the result must match
+ *   the parameter name in the target tool.
+ * @param options - Optional description and condition overrides.
+ *
+ * @example
+ * ```typescript
+ * // Single param — extract traceId from result, pass to get_trace
+ * followUp: quickBind('get_execution_trace', 'traceId')
+ *
+ * // Equivalent to:
+ * followUp: {
+ *   toolId: 'get_execution_trace',
+ *   params: (ctx) => ({ traceId: ctx.content.traceId }),
+ *   description: 'Follow up with get_execution_trace',
+ *   condition: 'User asks for more details',
+ * }
+ *
+ * // Multiple params
+ * followUp: quickBind('get_step_log', ['executionId', 'stepName'])
+ *
+ * // Custom description and condition
+ * followUp: quickBind('get_trace', 'traceId', {
+ *   description: 'Retrieve denial reasoning',
+ *   condition: 'User asks why their application was denied',
+ * })
+ * ```
+ */
+function quickBind(toolId, paramNames, options) {
+    const names = Array.isArray(paramNames) ? paramNames : [paramNames];
+    return {
+        toolId,
+        params: (ctx) => {
+            const result = {};
+            const content = ctx.content;
+            for (const name of names) {
+                result[name] = content?.[name];
+            }
+            return result;
+        },
+        description: options?.description ?? `Follow up with ${toolId}`,
+        condition: options?.condition ?? 'User asks for more details',
+    };
+}
+exports.quickBind = quickBind;
+/**
+ * Create a FollowUp binding with explicit params function.
+ *
+ * Preferred over `quickBind` for computed parameters.
+ *
+ * @example
+ * ```typescript
+ * followUp: follow('get_trace', ctx => ({ traceId: ctx.content.traceId }), 'Get denial details')
+ * ```
+ */
+function follow(toolId, params, description, condition) {
+    return {
+        toolId,
+        params,
+        description,
+        condition: condition ?? 'User asks for more details',
+    };
+}
+exports.follow = follow;
+//# sourceMappingURL=types.js.map

package/dist/lib/instructions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/instructions/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AA6RH,2EAA2E;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,SAAgB,SAAS,CACvB,MAAc,EACd,UAA6B,EAC7B,OAAsD;IAEtD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAEpE,OAAO;QACL,MAAM;QACN,MAAM,EAAE,CAAC,GAAuB,EAAE,EAAE;YAClC,MAAM,MAAM,GAA4B,EAAE,CAAC;YAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAkC,CAAC;YACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,WAAW,EAAE,OAAO,EAAE,WAAW,IAAI,kBAAkB,MAAM,EAAE;QAC/D,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,4BAA4B;KAC9D,CAAC;AACJ,CAAC;AApBD,8BAoBC;AAED;;;;;;;;;GASG;AACH,SAAgB,MAAM,CACpB,MAAc,EACd,MAA+D,EAC/D,WAAmB,EACnB,SAAkB;IAElB,OAAO;QACL,MAAM;QACN,MAAM;QACN,WAAW;QACX,SAAS,EAAE,SAAS,IAAI,4BAA4B;KACrD,CAAC;AACJ,CAAC;AAZD,wBAYC"}