agentfootprint 2.3.0 → 2.5.0

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

@@ -1,11 +0,0 @@
-/**
- * Instruction evaluator — runs the `activeWhen` predicates and
- * returns the active set + any skipped predicates.
- *
- * Pattern: Pure function. Stateless.
- * Role:    Internal helper used by Agent during pre-LLM stage.
- * Emits:   N/A — caller handles emit + observability.
- */
-import type { Instruction, InstructionContext, InstructionEvaluation } from './types.js';
-export declare function evaluateInstructions(instructions: readonly Instruction[], ctx: InstructionContext): InstructionEvaluation;
-//# 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;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,GAAG,EAAE,kBAAkB,GACtB,qBAAqB,CAwBvB"}

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

@@ -1,44 +0,0 @@
-/**
- * Instructions — declarative rule-based system-prompt injection.
- *
- * Public API for the v2 Instructions subsystem. See `types.ts` for the
- * full interface + the unified context-engineering model placement.
- *
- * ─── 7-panel design review (2026-04-28) ─────────────────────────────
- *
- *   LLM-AI system design   ✓ Maps cleanly to the unified context-
- *                            engineering model: slot=system-prompt
- *                            (+optional tools), role=system, timing=
- *                            per-iteration, decision=rule.
- *   Performance            ✓ Predicates run once per iteration (not
- *                            per token / per event). O(N) in number
- *                            of instructions; typical N ≤ 20.
- *   Scalability            ✓ Stateless evaluator; many concurrent
- *                            agents share the same instruction list
- *                            via Object.freeze.
- *   Research alignment     ✓ Mirrors v1 AgentInstruction's `activeWhen`
- *                            shape (origin/main `c6e11d0`) but drops
- *                            `onToolResult`, `safety`, decision-scope
- *                            wrapping for v2 simplicity. Equivalent
- *                            tool-result-driven behavior is expressed
- *                            via `activeWhen: (ctx) =>
- *                            ctx.lastToolResult?.toolName === 'X'`.
- *   Flexibility            ✓ Same Instruction can be active across
- *                            multiple iterations; can inject tools
- *                            in addition to prompt; predicates can
- *                            inspect history + last tool result.
- *   Abstraction-modular    ✓ Three small files: types, builder,
- *                            evaluator. Agent integration is one
- *                            call into `evaluateInstructions()`.
- *   Software engineering   ✓ Predicate errors are caught + surfaced
- *                            (no crash). Frozen instructions prevent
- *                            mutation. 7-pattern test coverage.
- *
- * ─── 7-pattern test coverage ────────────────────────────────────────
- *
- *   See `test/lib/instructions/*.test.ts`.
- */
-export { defineInstruction, type DefineInstructionOptions, } from './defineInstruction.js';
-export { evaluateInstructions, } from './evaluator.js';
-export type { Instruction, InstructionContext, InstructionEvaluation, } from './types.js';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

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

@@ -1,100 +0,0 @@
-/**
- * Instructions — types.
- *
- * An Instruction is a declarative rule for conditional system-prompt
- * injection. The agent evaluates each Instruction's `activeWhen`
- * predicate at the start of every iteration; matching instructions'
- * `prompt` text is prepended to the system prompt for that iteration.
- *
- * This is the rule-based flavor of the unified context-engineering
- * model: slot=system-prompt, role=system, timing=per-iteration,
- * decision=rule. (Compare with Skills: timing=on-activation,
- * decision=LLM-guided.)
- *
- * Pattern: Strategy (GoF) — each Instruction is a strategy for
- *          "should I add this prompt to the next iteration?"
- * Role:    Consumer-facing shape. Agent.create(...).instruction(...).
- * Emits:   `agentfootprint.context.injected` with source='instruction'
- *          when an instruction activates.
- */
-import type { Tool } from '../../core/tools.js';
-/**
- * Read-only snapshot of the agent's state that an Instruction can
- * inspect to decide activation. Includes only the fields a predicate
- * can safely depend on — internal mutable state is hidden.
- */
-export interface InstructionContext {
-    /** Current ReAct iteration (1-based). */
-    readonly iteration: number;
-    /** The current user message that started this turn. */
-    readonly userMessage: string;
-    /**
-     * Conversation history up to (but not including) the current
-     * iteration's LLM call. Includes system / user / assistant / tool
-     * messages from prior iterations of the same turn.
-     */
-    readonly history: ReadonlyArray<{
-        readonly role: 'system' | 'user' | 'assistant' | 'tool';
-        readonly content: string;
-        readonly toolName?: string;
-    }>;
-    /**
-     * The most recent tool result, if the previous iteration ended in a
-     * tool call. Undefined on the first iteration of a turn.
-     */
-    readonly lastToolResult?: {
-        readonly toolName: string;
-        readonly result: string;
-    };
-    /** Custom decision-scope state the consumer placed via Agent options. */
-    readonly decision?: Readonly<Record<string, unknown>>;
-}
-/**
- * A single declarative instruction.
- *
- * @example
- *   const calmTone = defineInstruction({
- *     id: 'calm-tone',
- *     description: 'Use a calm, empathetic tone after the user expresses frustration.',
- *     activeWhen: (ctx) => ctx.userMessage.includes('frustrated')
- *                       || ctx.userMessage.includes('angry'),
- *     prompt: 'The user is upset. Respond calmly. Acknowledge feelings before facts.',
- *   });
- *
- *   const agent = Agent.create({ provider }).instruction(calmTone).build();
- */
-export interface Instruction {
-    /** Unique id — used for observability + de-duplication. */
-    readonly id: string;
-    /** Human-readable description (Lens / docs / debug). */
-    readonly description?: string;
-    /**
-     * Predicate to decide activation. Synchronous; side-effect free.
-     * If omitted, the instruction is always active. Predicates that
-     * throw are skipped (fail-open) and the error is surfaced via the
-     * emit channel for observability — they don't crash the run.
-     */
-    readonly activeWhen?: (ctx: InstructionContext) => boolean;
-    /** Text appended to the next iteration's system prompt when active. */
-    readonly prompt?: string;
-    /**
-     * Tools to add to the agent's tool registry when the instruction is
-     * active. Merged with the agent's base tools (later instructions win
-     * on duplicate ids). Empty by default.
-     */
-    readonly tools?: readonly Tool[];
-}
-/**
- * @internal
- * Branded result returned by `evaluateInstructions()`. Lets the
- * agent's pre-LLM stage consume the projection without re-running
- * the predicates.
- */
-export interface InstructionEvaluation {
-    readonly active: readonly Instruction[];
-    readonly skipped: ReadonlyArray<{
-        readonly id: string;
-        readonly error: string;
-    }>;
-}
-//# sourceMappingURL=types.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;QACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC,CAAC;IACH;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC;IAC3D,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClF"}

package/dist/types/memory/conversationHelpers.d.ts

@@ -1,19 +0,0 @@
-/**
- * Pure functions for conversation message management.
- * No state — just transformations on message arrays.
- */
-import type { Message, AssistantMessage, ToolResultMessage } from '../types';
-/** Append a message to the conversation. Returns new array. */
-export declare function appendMessage(messages: Message[], message: Message): Message[];
-/** Get the last message in the conversation. */
-export declare function lastMessage(messages: Message[]): Message | undefined;
-/** Get the last assistant message. */
-export declare function lastAssistantMessage(messages: Message[]): AssistantMessage | undefined;
-/** Check if the last assistant message has tool calls. */
-export declare function lastMessageHasToolCalls(messages: Message[]): boolean;
-/** Create tool result messages from a map of tool call ID → result. */
-export declare function createToolResults(results: Array<{
-    toolCallId: string;
-    content: string;
-}>): ToolResultMessage[];
-//# sourceMappingURL=conversationHelpers.d.ts.map

package/dist/types/memory/conversationHelpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"conversationHelpers.d.ts","sourceRoot":"","sources":["../../../src/memory/conversationHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7E,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAE9E;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,SAAS,CAEpE;AAED,sCAAsC;AACtC,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,gBAAgB,GAAG,SAAS,CAKtF;AAED,0DAA0D;AAC1D,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAGpE;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACtD,iBAAiB,EAAE,CAErB"}