agentfootprint 1.23.0 → 2.0.1

package/dist/types/lib/concepts/AgentRunner.d.ts

@@ -1,241 +0,0 @@
-/**
- * AgentRunner — executes the agent loop, manages conversation state.
- *
- * Created by Agent.build(). Not instantiated directly.
- */
-import type { FlowChart as FlowChartType } from 'footprintjs';
-import { AgentPattern } from '../loop';
-import type { InstructionOverride, AgentInstruction } from '../instructions';
-import type { AgentStreamEventHandler } from '../../streaming';
-import type { CustomRouteConfig } from './AgentBuilder';
-import { ToolRegistry } from '../../tools';
-import type { LLMProvider, AgentResult, Message, ResponseFormat } from '../../types';
-import type { MemoryPipeline } from '../../memory/pipeline';
-import type { AgentRecorder, PromptProvider, ToolProvider } from '../../core';
-/** Options for constructing an AgentRunner. Created by Agent.build(). */
-export interface AgentRunnerOptions {
-    readonly provider: LLMProvider;
-    readonly name: string;
-    readonly systemPromptText?: string;
-    readonly registry: ToolRegistry;
-    readonly maxIterations?: number;
-    readonly recorders?: AgentRecorder[];
-    readonly memoryPipeline?: MemoryPipeline;
-    readonly pattern?: AgentPattern;
-    readonly promptProvider?: PromptProvider;
-    readonly toolProvider?: ToolProvider;
-    readonly instructionOverrides?: ReadonlyMap<string, InstructionOverride>;
-    readonly agentInstructions?: readonly AgentInstruction[];
-    readonly initialDecision?: Readonly<Record<string, unknown>>;
-    readonly streaming?: boolean;
-    /** When true, narrative shows full values (no truncation). */
-    readonly verboseNarrative?: boolean;
-    /** Structured output format — passed through to LLM provider. */
-    readonly responseFormat?: ResponseFormat;
-    /** Run tool calls within a single turn concurrently. Default: false. */
-    readonly parallelTools?: boolean;
-    /** User-defined routing branches evaluated before default tool-calls/final. */
-    readonly customRoute?: CustomRouteConfig;
-    /**
-     * Consecutive-identical-failure threshold for escalation. `0` disables.
-     * Defaults to `REPEATED_FAILURE_ESCALATION_THRESHOLD` (3) when omitted.
-     */
-    readonly maxIdenticalFailures?: number;
-}
-export declare class AgentRunner {
-    private static _autoExecCounter;
-    private readonly provider;
-    readonly name: string;
-    private readonly systemPromptText?;
-    private readonly registry;
-    private readonly maxIter;
-    private readonly recorders;
-    private readonly memoryPipeline?;
-    private readonly agentPattern;
-    private readonly customPromptProvider?;
-    private readonly customToolProvider?;
-    private readonly instructionOverrides?;
-    private readonly agentInstructions?;
-    private readonly initialDecision?;
-    private readonly streamingEnabled;
-    private readonly responseFormat?;
-    private readonly parallelToolsEnabled;
-    private readonly customRoute?;
-    private readonly maxIdenticalFailures?;
-    private readonly cachedDecideFunctions?;
-    private conversationHistory;
-    /**
-     * Decision scope carried forward between `.run()` calls. Tool handlers
-     * write into `scope.decision` via `decisionUpdate`; without this carry-
-     * over, every new turn would see an empty decision and skill-gated
-     * tools (autoActivate) would disappear on follow-up messages.
-     * `resetConversation()` clears this alongside `conversationHistory` so
-     * a fresh conversation really starts fresh. Undefined before the first
-     * run — falls back to `initialDecision` from build config.
-     */
-    private lastDecision?;
-    private lastExecutor?;
-    private lastSpec?;
-    private readonly verboseNarrative;
-    private narrativeRenderer;
-    /**
-     * Persistent observer list for `runner.observe(handler)`. One dispatcher
-     * per runner instance — every `.run()` call funnels events through here
-     * in addition to any per-run `options.onEvent` callback. Used by Lens,
-     * telemetry, and anyone else who wants to watch what the agent does.
-     */
-    private readonly dispatcher;
-    private readonly pendingFollowUps;
-    /**
-     * Cached charts — built lazily on first use, reused across every
-     * `.run()` / `.toFlowChart()` call. Stream events flow through the
-     * emit channel (via a per-run `StreamEventRecorder` attached to the
-     * executor), so no per-run closure ever lands in chart stages. This
-     * lets both standalone and subflow-mode charts be pure static
-     * structures.
-     */
-    private cachedStandaloneChart?;
-    private cachedSubflowChart?;
-    /**
-     * Per-run strict follow-up that fired during tool execution. Reset at
-     * the start of each `.run()` call so state doesn't leak between turns.
-     * Populated by the `onInstructionsFired` callback wired through
-     * `buildConfig()`.
-     */
-    private runStrictFollowUp?;
-    constructor(options: AgentRunnerOptions);
-    /**
-     * Expose the agent's internal flowChart for subflow composition.
-     * Cached — built once, reused across all mount sites.
-     */
-    toFlowChart(): FlowChartType;
-    /**
-     * Lazy-build the standalone chart on first `.run()`. Stream handler
-     * flows via a per-run emit recorder attached in `run()` — the chart
-     * itself is a pure static structure and is reused forever.
-     */
-    private getStandaloneChart;
-    /** Run the agent with a user message. */
-    run(message: string, options?: {
-        signal?: AbortSignal;
-        timeoutMs?: number;
-        /** Full event stream — tool lifecycle, LLM lifecycle, tokens. */
-        onEvent?: AgentStreamEventHandler;
-        /** @deprecated Use onEvent instead. Ignored if onEvent is also provided. */
-        onToken?: (token: string) => void;
-        /**
-         * Memory identity for this turn. Forwarded to the memory pipeline
-         * (if configured via `.memoryPipeline()`). Same agent instance can
-         * serve many users by passing different identities per-run.
-         * Ignored when the agent has no memory pipeline attached.
-         */
-        identity?: {
-            tenant?: string;
-            principal?: string;
-            conversationId: string;
-        };
-        /**
-         * Run-local turn counter. Written into `MemoryEntry.source.turn` by
-         * the write subflow for cross-turn provenance. Defaults to 1.
-         */
-        turnNumber?: number;
-        /**
-         * Context-window token budget hint. Picker stage uses this to bound
-         * how much memory it injects. Defaults to 4000.
-         */
-        contextTokensRemaining?: number;
-    }): Promise<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.
-     */
-    resume(humanResponse: string): Promise<AgentResult>;
-    /**
-     * Create a scope recorder that captures LLM responses + context during traversal.
-     * Shared by run() and resume() — eliminates duplication and ensures both paths
-     * track runtimeStageId for stream bridge tool events.
-     */
-    private createLLMCaptureRecorder;
-    /** Extract AgentResult from executor state — shared by run() and resume(). */
-    private buildResult;
-    getNarrativeEntries(): import("footprintjs").CombinedNarrativeEntry[];
-    getSnapshot(): import("footprintjs").RuntimeSnapshot | undefined;
-    /**
-     * Subscribe to the agent's live stream of events — `turn_start`,
-     * `llm_start`/`llm_end`, `tool_start`/`tool_end`, `token` (when
-     * streaming), `turn_end`. The returned function unsubscribes.
-     *
-     * Multiple observers are supported; each gets every event. A throwing
-     * observer never propagates — the library error-isolates each call.
-     *
-     * @example
-     * ```ts
-     * const stop = agent.observe((e) => {
-     *   if (e.type === 'llm_end') metrics.record(e.usage);
-     * });
-     * // later:
-     * stop();
-     * ```
-     */
-    observe(handler: AgentStreamEventHandler): () => void;
-    /**
-     * Attach a recorder POST-BUILD. Mirrors the build-time `.recorder()`
-     * AgentBuilder method — the recorder participates in every subsequent
-     * `.run()` (gets `clear()` lifecycle + receives events through the
-     * executor's emit channel via `forwardEmitRecorders`).
-     *
-     * Why post-build attach matters: UI consumers like Lens receive an
-     * already-built agent via `<Lens for={agent} />` and can't influence
-     * the build-time `.recorder()` chain. Without this method they'd
-     * have to subscribe via `observe()` and get a translated AgentStreamEvent
-     * shape (no runtimeStageId, no subflowPath). With this method they
-     * get the full EmitEvent — proper recorder pattern, multi-agent ready.
-     *
-     * Returns a detach function; calling it removes the recorder from
-     * subsequent runs. Idempotent by recorder id (matching the same
-     * contract as build-time recorders).
-     *
-     * @example
-     * ```ts
-     * import { agentTimeline } from 'agentfootprint';
-     * const t = agentTimeline({ name: 'Neo' });
-     * const stop = agent.attachRecorder(t);
-     * await agent.run('hello');
-     * console.log(t.selectTurns(), t.selectActivities());
-     * stop();  // detach
-     * ```
-     */
-    attachRecorder(recorder: any): () => void;
-    getSpec(): unknown;
-    getMessages(): Message[];
-    resetConversation(): void;
-    /**
-     * Forward a strict follow-up captured during the run to the pending
-     * queue. Isolated into a method so TypeScript doesn't narrow the
-     * field type to `never` via control-flow from the earlier reset.
-     */
-    private flushStrictFollowUp;
-    /**
-     * Build the static AgentLoopConfig. Called ONCE by the cached-chart
-     * builder (`getStandaloneChart` / `toFlowChart`). Contains no per-run
-     * inputs — `onStreamEvent` flows through args per turn, and the
-     * `onInstructionsFired` callback writes into `this.runStrictFollowUp`
-     * which `run()` resets at each turn's start.
-     */
-    private buildConfig;
-}
-//# sourceMappingURL=AgentRunner.d.ts.map

package/dist/types/lib/concepts/AgentRunner.d.ts.map

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

package/dist/types/lib/concepts/index.d.ts

@@ -1,3 +0,0 @@
-export { Agent, AgentRunner } from './Agent';
-export type { AgentOptions, CustomRouteBranch, CustomRouteConfig } from './Agent';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/concepts/index.d.ts.map

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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