agentfootprint 1.0.0

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

@@ -0,0 +1,394 @@
+/**
+ * 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)
+ */
+import type { ToolDefinition } from '../../types/tools';
+/**
+ * Context passed to instruction predicates — the full tool execution result.
+ *
+ * Includes the tool's return value, any error state, execution latency,
+ * and the original input for context-aware predicates.
+ *
+ * @example
+ * ```typescript
+ * // Access result content
+ * when: (ctx) => ctx.content.status === 'denied'
+ *
+ * // Access error state (tool handler threw or returned error)
+ * when: (ctx) => ctx.error?.code === 'TIMEOUT'
+ *
+ * // Access latency (slow tool response)
+ * when: (ctx) => ctx.latencyMs > 5000
+ *
+ * // Access original input
+ * when: (ctx) => ctx.input.region === 'eu'
+ * ```
+ */
+export interface InstructionContext<T = unknown> {
+    /** Tool result content — the value returned by the handler. */
+    readonly content: T;
+    /** Error info when the tool handler threw or returned `error: true`. */
+    readonly error?: {
+        code?: string;
+        message: string;
+    };
+    /** Tool execution time in milliseconds. */
+    readonly latencyMs: number;
+    /** Original input passed to the tool handler. */
+    readonly input: Record<string, unknown>;
+    /** Tool ID that produced this result. */
+    readonly toolId: string;
+}
+/**
+ * Structured follow-up action — pre-resolves the next tool call with exact identifiers.
+ *
+ * The developer defines WHAT can be done next. The framework generates the
+ * LLM-facing text via NarrativeTemplate. The LLM never needs to guess tool IDs
+ * or fabricate parameter values.
+ *
+ * @example
+ * ```typescript
+ * // Full form
+ * followUp: {
+ *   toolId: 'get_execution_trace',
+ *   params: (ctx) => ({ traceId: ctx.content.traceId }),
+ *   description: 'Retrieve detailed denial reasoning',
+ *   condition: 'User asks why or wants details',
+ * }
+ *
+ * // With quickBind shorthand
+ * followUp: quickBind('get_execution_trace', 'traceId')
+ * ```
+ */
+export interface FollowUpBinding<T = unknown> {
+    /** Target tool to call. Must exist in the agent's tool set (validated at build time). */
+    readonly toolId: string;
+    /**
+     * Resolve parameters from the tool result context.
+     * The returned object is passed directly to the target tool's handler.
+     *
+     * @example
+     * ```typescript
+     * params: (ctx) => ({ traceId: ctx.content.traceId })
+     * ```
+     */
+    readonly params: (ctx: InstructionContext<T>) => Record<string, unknown>;
+    /**
+     * What this follow-up does — human-readable.
+     * The framework uses this to generate injection text for the LLM.
+     * Required because the LLM needs to understand the action to decide whether to offer it.
+     *
+     * @example 'Retrieve detailed denial reasoning'
+     */
+    readonly description: string;
+    /**
+     * When the LLM should offer this follow-up — human-readable.
+     * Tells the LLM under what user intent to suggest or execute this action.
+     *
+     * @example 'User asks why their application was denied'
+     */
+    readonly condition: string;
+    /**
+     * When true, the framework auto-executes this follow-up when the condition matches,
+     * bypassing the LLM for the tool call construction. The LLM is only brought back
+     * to interpret the result. Prevents ID corruption on long alphanumeric identifiers.
+     *
+     * @default false
+     */
+    readonly strict?: boolean;
+}
+/**
+ * An instruction for the LLM, co-located with a tool definition.
+ *
+ * Evaluated after the tool returns a result. When the `when` predicate matches,
+ * the instruction is injected into the LLM's recency window — right next to the
+ * tool result, where the model pays the most attention.
+ *
+ * `text` and `followUp` are optional — fill in what you need:
+ *
+ * @example
+ * ```typescript
+ * // Text guidance
+ * { id: 'empathy', when: ctx => ctx.content.denied,
+ *   text: 'Be empathetic. Do NOT promise reversal.' }
+ *
+ * // Structured follow-up
+ * { id: 'details', when: ctx => ctx.content.denied,
+ *   followUp: follow('get_denial_trace', ctx => ({ traceId: ctx.content.traceId }), 'Get details') }
+ *
+ * // Both text + follow-up
+ * { id: 'flagged', when: ctx => ctx.content.flagged,
+ *   text: 'Order flagged. Do NOT confirm shipment.',
+ *   followUp: follow('get_fraud_report', ctx => ({ orderId: ctx.content.orderId }), 'View report') }
+ *
+ * // Error handling
+ * { id: 'timeout', when: ctx => ctx.error?.code === 'TIMEOUT',
+ *   text: 'Service timed out. Apologize and suggest retry.' }
+ *
+ * // Safety — always position last in recency window (highest attention)
+ * { id: 'pii', when: ctx => ctx.content.hasPII, safety: true,
+ *   text: 'Contains PII. Do NOT repeat raw values.' }
+ * ```
+ */
+export interface LLMInstruction<T = unknown> {
+    /** Unique instruction identifier. Used by InstructionRecorder and overrides. */
+    readonly id: string;
+    /**
+     * Human-readable description of this instruction.
+     * Used for: narrative, API docs, `previewInstructions()`, `generateToolGuide()`.
+     * NOT injected into LLM — the `text` field is what the LLM sees.
+     *
+     * @example 'Guide LLM to be empathetic when loan is denied'
+     */
+    readonly description?: string;
+    /**
+     * Predicate: does this instruction apply to the tool result?
+     * Must be synchronous and side-effect-free.
+     * Receives the full InstructionContext (content, error, latency, input, toolId).
+     *
+     * When omitted, the instruction always fires (unconditional).
+     */
+    readonly when?: (ctx: InstructionContext<T>) => boolean;
+    /**
+     * Text appended to the tool result in the LLM's recency window.
+     * Write actionable, specific guidance — the LLM reads this literally.
+     *
+     * Good: "Item out of stock. Suggest alternatives from the same category.
+     *        Do NOT promise availability or restock dates."
+     * Bad:  "Handle this appropriately."
+     */
+    readonly text?: string;
+    /** Structured follow-up action the LLM can take. */
+    readonly followUp?: FollowUpBinding<T>;
+    /**
+     * Priority for injection ordering. Lower number = injected first.
+     * When multiple instructions fire, they are sorted by priority.
+     * Ties are broken by array order in the `instructions` field.
+     *
+     * @default 0
+     */
+    readonly priority?: number;
+    /**
+     * When true, this instruction is never truncated by token budget
+     * and is positioned LAST in the injection (closest to LLM generation,
+     * highest attention weight). Use for safety-critical instructions.
+     *
+     * @default false
+     */
+    readonly safety?: boolean;
+    /**
+     * Set Decision Scope variables based on the tool result.
+     * Controls FUTURE instruction activation — the updated decision drives
+     * InstructionsToLLM on the next loop iteration.
+     *
+     * Tool handlers stay pure (input → content). Decision mutations are
+     * co-located with the tool's instructions — declarative, not imperative.
+     *
+     * Runs after `when` matches. Receives a mutable decision object + the tool context.
+     *
+     * @example
+     * ```typescript
+     * { id: 'classify',
+     *   decide: (decision, ctx) => {
+     *     decision.orderStatus = ctx.content.status;
+     *     decision.riskLevel = ctx.content.amount > 1000 ? 'high' : 'low';
+     *   },
+     *   text: 'Order classified.',
+     * }
+     * ```
+     */
+    readonly decide?: (decision: Record<string, unknown>, ctx: InstructionContext<T>) => void;
+}
+/**
+ * Runtime follow-up — returned by tool handler with pre-resolved params.
+ *
+ * Unlike build-time FollowUpBinding (which has a `params` function),
+ * runtime follow-ups have already-resolved parameter values.
+ *
+ * @example
+ * ```typescript
+ * handler: async (input) => {
+ *   const result = await service.evaluate(input);
+ *   return {
+ *     content: JSON.stringify(result),
+ *     followUps: result.traceId ? [{
+ *       toolId: 'get_trace',
+ *       params: { traceId: result.traceId },
+ *       description: 'Full denial reasoning trace',
+ *       condition: 'User asks why',
+ *     }] : [],
+ *   };
+ * }
+ * ```
+ */
+export interface RuntimeFollowUp {
+    readonly toolId: string;
+    readonly params: Record<string, unknown>;
+    readonly description: string;
+    readonly condition: string;
+    readonly strict?: boolean;
+}
+/**
+ * Extended tool result that can carry runtime instructions and follow-ups.
+ *
+ * Tool handlers can return this instead of plain `ToolResult` to attach
+ * context-aware guidance based on live system state.
+ *
+ * @example
+ * ```typescript
+ * handler: async (input) => {
+ *   const result = await orderService.check(input);
+ *   return {
+ *     content: JSON.stringify(result),
+ *     instructions: result.status === 'delayed'
+ *       ? ['Delivery is delayed. Apologize and offer tracking link.']
+ *       : [],
+ *     followUps: result.trackingId ? [{
+ *       toolId: 'track_package',
+ *       params: { trackingId: result.trackingId },
+ *       description: 'Track package location',
+ *       condition: 'User asks about delivery status',
+ *     }] : [],
+ *   };
+ * }
+ * ```
+ */
+export interface InstructedToolResult {
+    /** Tool result content (string for LLM consumption). */
+    readonly content: string;
+    /** Optional error flag. */
+    readonly error?: boolean;
+    /** Runtime behavioral instructions — injected as-is into recency window. */
+    readonly instructions?: readonly string[];
+    /** Runtime follow-up bindings with pre-resolved params. */
+    readonly followUps?: readonly RuntimeFollowUp[];
+}
+/**
+ * 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',
+ * })
+ * ```
+ */
+export declare function quickBind(toolId: string, paramNames: string | string[], options?: {
+    description?: string;
+    condition?: string;
+}): FollowUpBinding;
+/**
+ * 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')
+ * ```
+ */
+export declare function follow<T = unknown>(toolId: string, params: (ctx: InstructionContext<T>) => Record<string, unknown>, description: string, condition?: string): FollowUpBinding<T>;
+/**
+ * Tool definition with LLM instructions.
+ *
+ * Extends the base ToolDefinition with an optional `instructions` field
+ * for co-located behavioral guidance and structured follow-ups.
+ *
+ * @example
+ * ```typescript
+ * const orderTool = defineTool({
+ *   id: 'check_order',
+ *   description: 'Check order status',
+ *   inputSchema: { type: 'object', properties: { orderId: { type: 'string' } } },
+ *   handler: async ({ orderId }) => {
+ *     const order = await orderService.get(orderId);
+ *     return { content: JSON.stringify(order) };
+ *   },
+ *   instructions: [
+ *     { id: 'cancelled', when: ctx => ctx.content.status === 'cancelled',
+ *       text: 'Order cancelled. Be empathetic. Offer alternatives.' },
+ *     { id: 'shipped', when: ctx => ctx.content.status === 'shipped',
+ *       followUp: follow('track_package', ctx => ({ trackingId: ctx.content.trackingId }), 'Track package') },
+ *     { id: 'pii', when: ctx => ctx.content.hasPII, safety: true,
+ *       text: 'Contains PII. Do NOT repeat raw values to user.' },
+ *   ],
+ * });
+ * ```
+ */
+/**
+ * Tool definition with LLM instructions.
+ * Extends base ToolDefinition — handler can return InstructedToolResult
+ * with runtime instructions and follow-ups.
+ */
+export interface InstructedToolDefinition extends ToolDefinition {
+    readonly instructions?: readonly LLMInstruction[];
+}
+/**
+ * Agent-level instruction override for a shared tool.
+ *
+ * Tools are shared across agents, npm packages, and teams. The tool author's
+ * instructions are the baseline. Agent builders can suppress, add, or replace
+ * instructions without modifying the tool definition.
+ *
+ * @example
+ * ```typescript
+ * Agent.create({ provider })
+ *   .tool(sharedInventoryTool)
+ *   .instructionOverride('check_inventory', {
+ *     suppress: ['low-stock'],        // hide this instruction
+ *     add: [{                          // add agent-specific instruction
+ *       id: 'premium-oos',
+ *       when: (ctx) => ctx.content.quantity === 0 && ctx.content.isPremium,
+ *       text: 'Premium item. Offer to notify when back in stock.',
+ *     }],
+ *     replace: {                       // change an existing instruction's inject text
+ *       'out-of-stock': {
+ *         text: 'Unavailable. Suggest the B2B bulk channel instead.',
+ *       },
+ *     },
+ *   })
+ *   .build();
+ * ```
+ */
+export interface InstructionOverride {
+    /** Instruction IDs to suppress (remove from evaluation). */
+    readonly suppress?: readonly string[];
+    /** New instructions to add (evaluated after tool's own instructions). */
+    readonly add?: readonly LLMInstruction[];
+    /** Partial overrides for existing instructions (merge by ID). */
+    readonly replace?: Readonly<Record<string, Partial<LLMInstruction>>>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/types/lib/loop/buildAgentLoop.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Loop assembler — builds the full agent ReAct loop flowchart.
+ *
+ * Mounts the three API slots as subflows, then wires CallLLM → ParseResponse →
+ * RouteResponse (decider) with branches for tool execution and finalization.
+ *
+ * Supports two loop patterns (AgentPattern enum):
+ *
+ * Regular ReAct (default): loopTo('call-llm')
+ *   Seed → [sf-system-prompt] → [sf-messages] → [sf-tools]
+ *     → AssemblePrompt → CallLLM → ParseResponse
+ *     → RouteResponse(decider) → [CommitMemory?] → loopTo('call-llm')
+ *   Slots resolve ONCE before the loop.
+ *
+ * Dynamic ReAct: loopTo('sf-instructions-to-llm' or 'sf-system-prompt')
+ *   Same flowchart, but loop jumps back to InstructionsToLLM (when configured)
+ *   or SystemPrompt. All slots re-evaluate each iteration.
+ *   Uses arrayMerge: ArrayMergeMode.Replace on Messages/Tools outputMappers
+ *   so arrays are overwritten (not concatenated) on each iteration.
+ *
+ * Design choices:
+ *   - Seed stage initializes loopCount + maxIterations + messages
+ *   - Slot subflows use arrayMerge: Replace to avoid stale array accumulation
+ *   - Each slot is ALWAYS a subflow — zero overhead, free drill-down + narrative
+ *   - RouteResponse is a proper decider — visible in flowchart as diamond with branches
+ *   - Tool execution is a subflow — enables drill-down in BTS
+ *   - Chart is self-contained — no wrapping needed
+ */
+import type { FlowChart } from 'footprintjs';
+import type { AgentLoopConfig, AgentLoopSeedOptions } from './types';
+import type { ResolvedFollowUp } from '../instructions';
+/**
+ * Well-known scope key for the user message in subflow mode.
+ * Parent charts must set this key in their inputMapper:
+ * `inputMapper: (p) => ({ message: p.userMessage })`
+ */
+export declare const SUBFLOW_MESSAGE_KEY = "message";
+/**
+ * Build the full agent loop flowchart from config.
+ *
+ * Returns a self-contained FlowChart ready for FlowChartExecutor.
+ * Includes a Seed stage that initializes scope with the provided messages.
+ *
+ * Usage:
+ * ```typescript
+ * const chart = buildAgentLoop(config, { messages: [userMessage('hello')] });
+ * const executor = new FlowChartExecutor(chart);
+ * await executor.run();
+ * ```
+ */
+export interface StrictFollowUpResult {
+    followUp: ResolvedFollowUp;
+    sourceToolId: string;
+}
+export interface AgentLoopBuild {
+    chart: FlowChart;
+    /** Get strict follow-up that fired during the last execution (if any). */
+    getStrictFollowUp: () => StrictFollowUpResult | undefined;
+}
+export interface AgentLoopResult extends AgentLoopBuild {
+    spec: unknown;
+}
+export declare function buildAgentLoop(config: AgentLoopConfig, seed?: AgentLoopSeedOptions): AgentLoopBuild;
+export declare function buildAgentLoop(config: AgentLoopConfig, seed: AgentLoopSeedOptions | undefined, options: {
+    captureSpec: true;
+}): AgentLoopResult;
+//# sourceMappingURL=buildAgentLoop.d.ts.map

package/dist/types/lib/loop/buildAgentLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildAgentLoop.d.ts","sourceRoot":"","sources":["../../../../src/lib/loop/buildAgentLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAe7C,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAiB,MAAM,SAAS,CAAC;AAEpF,OAAO,KAAK,EAAE,gBAAgB,EAAiE,MAAM,iBAAiB,CAAC;AAqDvH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,CAAC;IACjB,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,oBAAoB,GAAG,SAAS,CAAC;CAC3D;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAAC;AACrG,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,oBAAoB,GAAG,SAAS,EAAE,OAAO,EAAE;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,GAAG,eAAe,CAAC"}

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

@@ -0,0 +1,5 @@
+export { buildAgentLoop, SUBFLOW_MESSAGE_KEY } from './buildAgentLoop';
+export type { AgentLoopResult } from './buildAgentLoop';
+export { AgentPattern } from './types';
+export type { AgentLoopConfig, AgentLoopSeedOptions, RoutingConfig, RoutingBranch } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/loop/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}