agentfootprint 1.0.0

package/dist/esm/lib/concepts/AgentRunner.js

@@ -0,0 +1,337 @@
+/**
+ * AgentRunner — executes the agent loop, manages conversation state.
+ *
+ * Created by Agent.build(). Not instantiated directly.
+ */
+import { FlowChartExecutor, MetricRecorder } from 'footprintjs';
+import { buildAgentLoop, AgentPattern } from '../loop';
+import { PendingFollowUpManager, InstructionRecorder } from '../instructions';
+import { createAgentRenderer } from '../narrative';
+import { annotateSpecIcons } from '../../concepts/specIcons';
+import { staticPrompt } from '../../providers/prompt/static';
+import { slidingWindow } from '../../providers/messages/slidingWindow';
+import { noTools } from '../../providers/tools/noTools';
+import { staticTools } from '../../providers/tools/staticTools';
+import { lastAssistantMessage } from '../../memory';
+import { getTextContent } from '../../types/content';
+import { userMessage, toolResultMessage, assistantMessage } from '../../types';
+import { RecorderBridge } from '../../recorders/v2/RecorderBridge';
+export class AgentRunner {
+    static _autoExecCounter = 0;
+    provider;
+    name;
+    systemPromptText;
+    registry;
+    maxIter;
+    recorders;
+    memoryConfig;
+    agentPattern;
+    customPromptProvider;
+    customToolProvider;
+    instructionOverrides;
+    agentInstructions;
+    initialDecision;
+    streamingEnabled;
+    responseFormat;
+    cachedDecideFunctions;
+    conversationHistory = [];
+    lastExecutor;
+    lastSpec;
+    verboseNarrative;
+    narrativeRenderer = createAgentRenderer();
+    pendingFollowUps = new PendingFollowUpManager();
+    constructor(options) {
+        this.provider = options.provider;
+        this.name = options.name;
+        this.systemPromptText = options.systemPromptText;
+        this.registry = options.registry;
+        this.maxIter = options.maxIterations ?? 10;
+        this.recorders = [...(options.recorders ?? [])];
+        this.memoryConfig = options.memoryConfig;
+        this.agentPattern = options.pattern ?? AgentPattern.Regular;
+        this.customPromptProvider = options.promptProvider;
+        this.customToolProvider = options.toolProvider;
+        this.instructionOverrides = options.instructionOverrides;
+        this.agentInstructions = options.agentInstructions;
+        this.initialDecision = options.initialDecision;
+        this.streamingEnabled = options.streaming ?? false;
+        this.responseFormat = options.responseFormat;
+        this.verboseNarrative = options.verboseNarrative ?? false;
+        if (this.verboseNarrative) {
+            this.narrativeRenderer = createAgentRenderer({ verbose: true });
+        }
+        // Register instruction tools in the registry ONCE at construction time.
+        // Previously done inside buildAgentLoop on every run() — now runs exactly once.
+        if (this.agentInstructions?.length) {
+            for (const instr of this.agentInstructions) {
+                if (instr.tools) {
+                    for (const tool of instr.tools) {
+                        if (!this.registry.get(tool.id)) {
+                            this.registry.register(tool);
+                        }
+                    }
+                }
+            }
+        }
+        // Pre-compute decideFunctions map from agent-level instruction rules.
+        // Functions can't travel through scope (stripped on write), so captured here.
+        // Per-tool decide() functions are still collected by buildAgentLoop (they're on the registry).
+        if (this.agentInstructions?.length) {
+            const decideFns = new Map();
+            for (const instr of this.agentInstructions) {
+                if (instr.onToolResult) {
+                    for (const rule of instr.onToolResult) {
+                        if (rule.decide)
+                            decideFns.set(rule.id, rule.decide);
+                    }
+                }
+            }
+            if (decideFns.size > 0) {
+                this.cachedDecideFunctions = decideFns;
+            }
+        }
+    }
+    /** Expose the agent's internal flowChart for subflow composition. */
+    toFlowChart() {
+        const { chart, spec } = buildAgentLoop(this.buildConfig(), {
+            messages: [],
+            subflowMode: true,
+        }, { captureSpec: true });
+        this.lastSpec = annotateSpecIcons(spec);
+        return chart;
+    }
+    /** Run the agent with a user message. */
+    async run(message, options) {
+        // Resolve stream event handler: onEvent takes precedence over onToken.
+        const isDevMode = typeof process !== 'undefined' && process.env?.['NODE_ENV'] !== 'production';
+        if (options?.onEvent && options?.onToken && isDevMode) {
+            console.warn('[agentfootprint] Both onEvent and onToken provided. onToken is ignored when onEvent is set.');
+        }
+        // Wrap consumer callback with error isolation — handler errors never crash the agent.
+        const rawHandler = options?.onEvent
+            ?? (options?.onToken ? (e) => { if (e.type === 'token')
+                options.onToken(e.content); } : undefined);
+        const onStreamEvent = rawHandler
+            ? (event) => { try {
+                rawHandler(event);
+            }
+            catch { /* swallow */ } }
+            : undefined;
+        onStreamEvent?.({ type: 'turn_start', userMessage: message });
+        // Check for pending strict follow-up from previous turn
+        const pendingMatch = this.pendingFollowUps.checkAndConsume(message);
+        if (pendingMatch) {
+            const tool = this.registry.get(pendingMatch.followUp.toolId);
+            if (tool) {
+                const toolResult = await tool.handler(pendingMatch.followUp.params);
+                const autoMessages = [
+                    ...this.conversationHistory,
+                    userMessage(message),
+                    assistantMessage(`Using ${pendingMatch.followUp.description}.`, [{ id: `auto-strict-${++AgentRunner._autoExecCounter}`, name: pendingMatch.followUp.toolId, arguments: pendingMatch.followUp.params }]),
+                    toolResultMessage(toolResult.content, `auto-strict-${AgentRunner._autoExecCounter}`),
+                ];
+                this.conversationHistory = autoMessages;
+            }
+        }
+        const existingMessages = this.memoryConfig?.store ? [] : this.conversationHistory;
+        // Create bridge for recorder dispatch (before buildAgentLoop so mergedStreamEvent is available)
+        const bridge = this.recorders.length > 0 ? new RecorderBridge(this.recorders) : null;
+        const bridgeHandler = bridge?.createStreamEventBridge();
+        const mergedStreamEvent = bridgeHandler && onStreamEvent
+            ? (event) => { bridgeHandler(event); onStreamEvent(event); }
+            : bridgeHandler ?? onStreamEvent;
+        const { chart, spec, getStrictFollowUp } = buildAgentLoop(this.buildConfig(mergedStreamEvent), { messages: message ? [userMessage(message)] : [], existingMessages }, { captureSpec: true });
+        this.lastSpec = annotateSpecIcons(spec);
+        bridge?.dispatchTurnStart(message);
+        const executorOpts = { enrichSnapshots: true };
+        if (mergedStreamEvent && this.streamingEnabled) {
+            executorOpts.streamHandlers = {
+                onToken: (_streamId, token) => mergedStreamEvent({ type: 'token', content: token }),
+                onStart: () => { },
+                onEnd: () => { },
+            };
+        }
+        const executor = new FlowChartExecutor(chart, executorOpts);
+        executor.enableNarrative({ renderer: this.narrativeRenderer });
+        executor.attachRecorder(new MetricRecorder('metrics'));
+        // Capture every adapterRawResponse write — fires per LLM iteration,
+        // not just once at the end. This gives accurate LLM call counts + token totals.
+        const llmResponses = [];
+        if (bridge) {
+            const llmCapture = {
+                id: '__llm-capture',
+                onWrite(event) {
+                    if (event.key === 'adapterRawResponse' && event.value) {
+                        llmResponses.push(event.value);
+                    }
+                },
+            };
+            executor.attachRecorder(llmCapture);
+        }
+        const startMs = Date.now();
+        try {
+            await executor.run({
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
+        catch (err) {
+            this.lastExecutor = executor;
+            bridge?.dispatchError('llm', err);
+            throw err;
+        }
+        this.lastExecutor = executor;
+        // Check for pause (ask_human tool) — emit turn_end with paused flag, return early
+        if (executor.isPaused()) {
+            const pauseResult = this.buildResult(executor);
+            onStreamEvent?.({ type: 'turn_end', content: '', iterations: pauseResult.iterations, paused: true });
+            return pauseResult;
+        }
+        const agentResult = this.buildResult(executor);
+        onStreamEvent?.({ type: 'turn_end', content: agentResult.content, iterations: agentResult.iterations });
+        if (bridge) {
+            // Dispatch per-iteration LLM calls (captured by scope recorder above)
+            const perCallMs = llmResponses.length > 0
+                ? Math.round((Date.now() - startMs) / llmResponses.length)
+                : 0;
+            for (const resp of llmResponses) {
+                bridge.dispatchLLMCall(resp, perCallMs);
+            }
+            bridge.dispatchTurnComplete(agentResult.content, agentResult.messages.length, agentResult.iterations);
+        }
+        const strictFU = getStrictFollowUp();
+        if (strictFU) {
+            this.pendingFollowUps.setPending({
+                followUp: strictFU.followUp,
+                sourceToolId: strictFU.sourceToolId,
+            });
+        }
+        return agentResult;
+    }
+    /**
+     * Resume a paused agent (after ask_human tool).
+     *
+     * Provides the human's response, which becomes the tool result for ask_human.
+     * The agent loop continues from where it paused.
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.run('Process my refund');
+     * if (result.paused) {
+     *   const final = await agent.resume('Yes, order ORD-123');
+     * }
+     * ```
+     *
+     * Note: `onEvent` streaming is not yet supported on `resume()`.
+     * The resumed turn completes without emitting AgentStreamEvents.
+     * Use `result.content` and `agent.getNarrative()` for post-resume data.
+     */
+    // TODO: Add onEvent parameter to resume() for streaming event support
+    async resume(humanResponse) {
+        const executor = this.lastExecutor;
+        if (!executor || !executor.isPaused()) {
+            throw new Error('Cannot resume: agent is not paused. Call run() first.');
+        }
+        const checkpoint = executor.getCheckpoint();
+        if (!checkpoint) {
+            throw new Error('Cannot resume: no checkpoint available.');
+        }
+        // Capture LLM calls during resume (same pattern as run())
+        const bridge = this.recorders.length > 0 ? new RecorderBridge(this.recorders) : null;
+        const llmResponses = [];
+        if (bridge) {
+            const llmCapture = {
+                id: '__llm-capture-resume',
+                onWrite(event) {
+                    if (event.key === 'adapterRawResponse' && event.value) {
+                        llmResponses.push(event.value);
+                    }
+                },
+            };
+            executor.attachRecorder(llmCapture);
+        }
+        const startMs = Date.now();
+        await executor.resume(checkpoint, humanResponse);
+        if (bridge) {
+            const perCallMs = llmResponses.length > 0
+                ? Math.round((Date.now() - startMs) / llmResponses.length)
+                : 0;
+            for (const resp of llmResponses) {
+                bridge.dispatchLLMCall(resp, perCallMs);
+            }
+        }
+        return this.buildResult(executor);
+    }
+    /** Extract AgentResult from executor state — shared by run() and resume(). */
+    buildResult(executor) {
+        if (executor.isPaused()) {
+            const cp = executor.getCheckpoint();
+            const pausedMessages = executor.getSnapshot()?.sharedState?.messages ?? [];
+            this.conversationHistory = pausedMessages;
+            return {
+                content: '',
+                messages: pausedMessages,
+                iterations: executor.getSnapshot()?.sharedState?.loopCount ?? 0,
+                paused: true,
+                pauseData: cp?.pauseData,
+            };
+        }
+        const snapshot = executor.getSnapshot();
+        const state = snapshot?.sharedState ?? {};
+        const messages = state.messages ?? [];
+        const lastAsst = lastAssistantMessage(messages);
+        const result = state.result ?? (lastAsst ? getTextContent(lastAsst.content) : '');
+        const iterations = state.loopCount ?? 0;
+        this.conversationHistory = messages;
+        return { content: result, messages, iterations };
+    }
+    getNarrative() { return this.lastExecutor?.getNarrative() ?? []; }
+    getNarrativeEntries() { return this.lastExecutor?.getNarrativeEntries() ?? []; }
+    getSnapshot() { return this.lastExecutor?.getSnapshot(); }
+    getSpec() {
+        if (!this.lastSpec) {
+            const { spec } = buildAgentLoop(this.buildConfig(), { messages: [], subflowMode: true }, { captureSpec: true });
+            this.lastSpec = annotateSpecIcons(spec);
+        }
+        return this.lastSpec;
+    }
+    getMessages() { return [...this.conversationHistory]; }
+    resetConversation() { this.conversationHistory = []; }
+    buildConfig(onStreamEvent) {
+        const hasTools = this.registry.size > 0;
+        const promptProvider = this.customPromptProvider ?? staticPrompt(this.systemPromptText ?? '');
+        const toolsProvider = this.customToolProvider ?? (hasTools ? staticTools(this.registry.all()) : noTools());
+        return {
+            provider: this.provider,
+            systemPrompt: { provider: promptProvider },
+            messages: {
+                strategy: this.memoryConfig?.strategy ?? slidingWindow({ maxMessages: 100 }),
+                store: this.memoryConfig?.store,
+                conversationId: this.memoryConfig?.conversationId,
+            },
+            tools: { provider: toolsProvider },
+            toolProvider: this.customToolProvider,
+            registry: this.registry,
+            maxIterations: this.maxIter,
+            commitMemory: this.memoryConfig ? {
+                store: this.memoryConfig.store,
+                conversationId: this.memoryConfig.conversationId,
+            } : undefined,
+            pattern: this.agentPattern,
+            instructionOverrides: this.instructionOverrides,
+            agentInstructions: this.agentInstructions,
+            initialDecision: this.initialDecision,
+            decideFunctions: this.cachedDecideFunctions,
+            streaming: this.streamingEnabled,
+            responseFormat: this.responseFormat,
+            onStreamEvent,
+            onInstructionsFired: (toolId, fired) => {
+                for (const rec of this.recorders) {
+                    if (rec instanceof InstructionRecorder)
+                        rec.recordFirings(toolId, fired);
+                }
+            },
+        };
+    }
+}
+//# sourceMappingURL=AgentRunner.js.map

package/dist/esm/lib/concepts/AgentRunner.js.map

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

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

@@ -0,0 +1,2 @@
+export { Agent, AgentRunner } from './Agent';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/concepts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

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

@@ -0,0 +1,121 @@
+/**
+ * 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 } },
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
+// ── Recorder ────────────────────────────────────────────────────────────
+export class InstructionRecorder {
+    id;
+    firings = new Map();
+    followUps = new Map();
+    constructor(id = 'instruction-recorder') {
+        this.id = id;
+    }
+    /**
+     * 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, fired) {
+        for (const instr of fired) {
+            // Track instruction firing
+            if (!this.firings.has(toolId))
+                this.firings.set(toolId, new Map());
+            const toolFirings = this.firings.get(toolId);
+            const existing = toolFirings.get(instr.id);
+            if (existing) {
+                existing.count++;
+            }
+            else {
+                toolFirings.set(instr.id, { count: 1, safety: instr.safety });
+            }
+            // Track follow-up offering
+            if (instr.resolvedFollowUp) {
+                if (!this.followUps.has(toolId))
+                    this.followUps.set(toolId, new Map());
+                const toolFollowUps = this.followUps.get(toolId);
+                const fuKey = instr.resolvedFollowUp.toolId;
+                const existingFu = toolFollowUps.get(fuKey);
+                if (existingFu) {
+                    existingFu.count++;
+                }
+                else {
+                    toolFollowUps.set(fuKey, { count: 1, toolId: fuKey });
+                }
+            }
+        }
+    }
+    /** Get summary of all instruction firings and follow-up offerings. */
+    getSummary() {
+        let totalFired = 0;
+        let totalFollowUpsOffered = 0;
+        const byTool = {};
+        // All tool IDs that have any activity
+        const allToolIds = new Set([...this.firings.keys(), ...this.followUps.keys()]);
+        for (const toolId of allToolIds) {
+            const instructions = {};
+            const followUps = {};
+            const toolFirings = this.firings.get(toolId);
+            if (toolFirings) {
+                for (const [instrId, data] of toolFirings) {
+                    instructions[instrId] = { fired: data.count, safety: data.safety };
+                    totalFired += data.count;
+                }
+            }
+            const toolFollowUps = this.followUps.get(toolId);
+            if (toolFollowUps) {
+                for (const [fuToolId, data] of toolFollowUps) {
+                    followUps[fuToolId] = { offered: data.count, toolId: data.toolId };
+                    totalFollowUpsOffered += data.count;
+                }
+            }
+            byTool[toolId] = { instructions, followUps };
+        }
+        return { totalFired, totalFollowUpsOffered, byTool };
+    }
+    /** Get firing count for a specific instruction on a specific tool. */
+    getFiringCount(toolId, instructionId) {
+        return this.firings.get(toolId)?.get(instructionId)?.count ?? 0;
+    }
+    /** Get all instruction IDs that fired for a tool. */
+    getFiredInstructionIds(toolId) {
+        const toolFirings = this.firings.get(toolId);
+        return toolFirings ? [...toolFirings.keys()] : [];
+    }
+    /** Serialize for inclusion in executor.getSnapshot().recorders. */
+    toSnapshot() {
+        return { name: 'Instructions', data: this.getSummary() };
+    }
+    clear() {
+        this.firings.clear();
+        this.followUps.clear();
+    }
+}
+//# sourceMappingURL=InstructionRecorder.js.map

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

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

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

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ */
+const isDevMode = () => typeof process !== 'undefined' && process.env?.['NODE_ENV'] !== 'production';
+// ── Evaluator ──────────────────────────────────────────────────────────
+/**
+ * Check if an instruction has at least one output (prompt, tools, or onToolResult).
+ */
+function hasOutputs(instr) {
+    return !!(instr.prompt || (instr.tools && instr.tools.length > 0) || (instr.onToolResult && instr.onToolResult.length > 0));
+}
+/**
+ * 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 function evaluateAgentInstructions(instructions, decision) {
+    const empty = {
+        promptInjections: [],
+        toolInjections: [],
+        responseRules: [],
+        matchedIds: [],
+    };
+    if (!instructions || instructions.length === 0)
+        return empty;
+    // Sort by priority, safety instructions LAST (matching tool-level convention).
+    // Stable sort preserves registration order for ties.
+    const sorted = [...instructions].sort((a, b) => {
+        const aSafety = a.safety ?? false;
+        const bSafety = b.safety ?? false;
+        if (aSafety !== bSafety)
+            return aSafety ? 1 : -1;
+        return (a.priority ?? 0) - (b.priority ?? 0);
+    });
+    const promptInjections = [];
+    const toolInjections = [];
+    const responseRules = [];
+    const matchedIds = [];
+    const seenToolIds = new Set();
+    for (const instr of sorted) {
+        // Evaluate predicate
+        if (instr.activeWhen) {
+            try {
+                if (!instr.activeWhen(decision))
+                    continue;
+            }
+            catch {
+                if (instr.safety) {
+                    // Safety: fail-closed — fire when predicate errors
+                }
+                else {
+                    // Behavioral: fail-open — skip broken predicate
+                    continue;
+                }
+            }
+        }
+        // P0 review fix: warn in dev mode when safety instruction has no outputs
+        if (instr.safety && !hasOutputs(instr)) {
+            if (isDevMode()) {
+                console.warn(`[agentfootprint] Safety instruction '${instr.id}' matched but has no outputs (prompt, tools, or onToolResult). ` +
+                    `It will appear in matchedIds but inject nothing.`);
+            }
+        }
+        matchedIds.push(instr.id);
+        if (instr.prompt) {
+            promptInjections.push(instr.prompt);
+        }
+        if (instr.tools) {
+            for (const tool of instr.tools) {
+                // Deduplicate by tool ID — first registration wins
+                if (!seenToolIds.has(tool.id)) {
+                    seenToolIds.add(tool.id);
+                    toolInjections.push(tool);
+                }
+            }
+        }
+        if (instr.onToolResult) {
+            responseRules.push(...instr.onToolResult);
+        }
+    }
+    return { promptInjections, toolInjections, responseRules, matchedIds };
+}
+// ── Factory ────────────────────────────────────────────────────────────
+/**
+ * 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 function defineInstruction(config) {
+    if (!config.id) {
+        throw new Error('defineInstruction: id is required');
+    }
+    return config;
+}
+//# sourceMappingURL=agentInstruction.js.map

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

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