agentfootprint 1.22.0 → 2.0.1

package/dist/esm/core/pause.js

@@ -0,0 +1,76 @@
+/**
+ * pause — runner-level pause/resume primitives.
+ *
+ * Pattern: Control-flow exception (PauseRequest) + typed outcome (RunnerPauseOutcome).
+ * Role:    core/ layer. Bridges footprintjs.s pause signal into the agentfootprint
+ *          Runner contract: tools call `pauseHere(data)` to raise a pause
+ *          intent; runners detect the paused executor result and return a
+ *          `RunnerPauseOutcome` instead of `TOut`. Consumers call
+ *          `runner.resume(checkpoint, input)` to continue.
+ * Emits:   N/A (types + helpers only). Event emission happens in RunnerBase.
+ *
+ * Why a control-flow "throw": tool.execute(args, ctx) doesn't receive the
+ * typed scope, so it cannot call `scope.$pause()` directly. A thrown
+ * `PauseRequest` is caught inside the Agent's tool-call stage, which then
+ * forwards the pause into the flowchart via `scope.$pause()`. This keeps
+ * the tool API clean (tools are pure-ish) while still supporting pause.
+ */
+/** Type guard — discriminates `RunnerPauseOutcome` from a normal `TOut`. */
+export function isPaused(result) {
+    return (typeof result === 'object' && result !== null && result.paused === true);
+}
+/**
+ * Control-flow error raised by `pauseHere()` inside a tool's `execute()`.
+ * Caught by the Agent's tool-call stage, which forwards to `scope.$pause()`.
+ * Never propagates to the consumer.
+ */
+export class PauseRequest extends Error {
+    data;
+    constructor(data) {
+        super('PauseRequest');
+        this.name = 'PauseRequest';
+        this.data = data;
+        // Not a real error — stack has no diagnostic value for consumers.
+        this.stack = '';
+    }
+}
+/**
+ * Called from inside a tool's `execute()` to request a pause. Throws a
+ * `PauseRequest` that the Agent catches and forwards to the flowchart.
+ *
+ * @example
+ *   const approveTool: Tool<{ action: string }, string> = {
+ *     schema: { name: 'approve', description: 'Ask human', inputSchema: {...} },
+ *     execute: async (args) => {
+ *       pauseHere({ question: `Approve ${args.action}?`, risk: 'high' });
+ *       return ''; // unreachable — pauseHere always throws
+ *     },
+ *   };
+ */
+export function pauseHere(data) {
+    throw new PauseRequest(data);
+}
+/** Type guard for a thrown `PauseRequest`. */
+export function isPauseRequest(err) {
+    return (err instanceof PauseRequest ||
+        (err instanceof Error &&
+            err.name === 'PauseRequest' &&
+            Object.prototype.hasOwnProperty.call(err, 'data')));
+}
+/**
+ * Ergonomic alias for `pauseHere(data)` — the human-in-the-loop name.
+ *
+ * `pauseHere` describes the mechanism (control-flow throw); `askHuman`
+ * describes the intent (ask a person to decide). Both work identically.
+ *
+ * @example
+ *   const approveRefund: Tool<{ amount: number }, string> = {
+ *     schema: { name: 'approve_refund', description: '...', inputSchema: {...} },
+ *     execute: async ({ amount }) => {
+ *       if (amount > 1000) askHuman({ question: `Approve $${amount}?` });
+ *       return 'auto-approved';
+ *     },
+ *   };
+ */
+export const askHuman = pauseHere;
+//# sourceMappingURL=pause.js.map

package/dist/esm/core/pause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pause.js","sourceRoot":"","sources":["../../../src/core/pause.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAkBH,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAI,MAA8B;IACxD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAK,MAA6B,CAAC,MAAM,KAAK,IAAI,CAChG,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAU;IACvB,YAAY,IAAa;QACvB,KAAK,CAAC,cAAc,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,kEAAkE;QAClE,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,OAAO,CACL,GAAG,YAAY,YAAY;QAC3B,CAAC,GAAG,YAAY,KAAK;YACnB,GAAG,CAAC,IAAI,KAAK,cAAc;YAC3B,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CACrD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,CAAC"}

package/dist/esm/core/runner.js

@@ -0,0 +1,16 @@
+/**
+ * Runner — consumer-facing interface for every primitive/composition/pattern.
+ *
+ * Pattern: Facade (GoF) over ComposableRunner + EventDispatcher.
+ * Role:    The one object consumers hold. Exposes:
+ *            - `.run()` / `.toFlowChart()` (inherited from footprintjs
+ *              ComposableRunner — composition + execution)
+ *            - `.on() / .off() / .once()` (listener subscription)
+ *            - `.attach()` (attach custom CombinedRecorder)
+ *            - `.emit()` (consumer-defined custom events on the same
+ *              dispatcher, matches DOM CustomEvent)
+ * Emits:   N/A — this file defines the INTERFACE. Concrete runners
+ *          (LLMCall, Agent, Sequence, etc.) implement it.
+ */
+export {};
+//# sourceMappingURL=runner.js.map

package/dist/esm/core/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../src/core/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/esm/core/slots/buildMessagesSlot.js

@@ -0,0 +1,101 @@
+/**
+ * Messages slot subflow builder
+ *
+ * Pattern: Builder (returns a FlowChart mountable via addSubFlowChartNext).
+ * Role:    Layer-3 context engineering. Produces InjectionRecord[] from
+ *          the current conversation history. For LLMCall, that's one
+ *          user message. For Agent, it's user + assistant + tool-result
+ *          messages accumulated over iterations.
+ * Emits:   None directly; ContextRecorder sees the writes.
+ *
+ * Minimal scope for Phase 3e: pass-through of an input message history
+ * array. Full MessageStrategy (windowing, summarizing) arrives in Phase 5.
+ */
+import { flowChart } from 'footprintjs';
+import { INJECTION_KEYS } from '../../conventions.js';
+import { COMPOSITION_KEYS } from '../../recorders/core/types.js';
+import { composeSlot, fnv1a, truncate } from './helpers.js';
+/**
+ * Build the Messages slot subflow.
+ *
+ * Mount with:
+ *   builder.addSubFlowChartNext(SUBFLOW_IDS.MESSAGES, buildMessagesSlot(cfg), 'Messages', {
+ *     inputMapper: (parent) => ({ messages: parent.messages, iteration: parent.iteration }),
+ *     outputMapper: (sf) => ({ messagesInjections: sf.messagesInjections }),
+ *   })
+ */
+export function buildMessagesSlot(config = {}) {
+    const budgetCap = config.budgetCap ?? 10000;
+    return flowChart('Compose', (scope) => {
+        const args = scope.$getArgs();
+        const messages = args.messages ?? [];
+        const iteration = args.iteration ?? 1;
+        const injections = messages.map((m, i) => ({
+            contentSummary: truncate(m.content, 80),
+            contentHash: fnv1a(`${m.role}:${i}:${m.content}`),
+            slot: 'messages',
+            source: inferSource(m.role),
+            reason: `conversation history [${i}]`,
+            rawContent: m.content,
+            asRole: m.role,
+            asRecency: (i === messages.length - 1 ? 'latest' : 'earlier'),
+            position: i,
+            ...(m.toolCallId !== undefined && { sourceId: m.toolCallId }),
+        }));
+        // Active Injections targeting the messages slot. Used by `defineFact`
+        // with `slot: 'messages'`, future RAG / Memory factories, etc.
+        const activeInjections = scope.$getValue('activeInjections') ?? [];
+        let position = injections.length;
+        for (const inj of activeInjections) {
+            const injMessages = inj.inject.messages;
+            if (!injMessages || injMessages.length === 0)
+                continue;
+            for (const msg of injMessages) {
+                injections.push({
+                    contentSummary: truncate(msg.content, 80),
+                    contentHash: fnv1a(`msg:${inj.flavor}:${inj.id}:${position}:${msg.content}`),
+                    slot: 'messages',
+                    source: inj.flavor,
+                    sourceId: inj.id,
+                    reason: inj.description ?? `${inj.flavor} '${inj.id}' active (trigger: ${inj.trigger.kind})`,
+                    rawContent: msg.content,
+                    asRole: msg.role,
+                    asRecency: 'latest',
+                    position,
+                });
+                position++;
+            }
+        }
+        scope.$setValue(INJECTION_KEYS.MESSAGES, injections);
+        scope.$setValue(COMPOSITION_KEYS.SLOT_COMPOSED, composeSlot('messages', iteration, injections, budgetCap, 'history-order'));
+    }, 'compose', undefined, 'Compose messages slot').build();
+}
+/**
+ * Map a ROLE to a baseline source tag. These represent regular LLM-API
+ * conversation flow — NOT context engineering:
+ *
+ *   - `user`      → source 'user' (the user's message, current or history replay)
+ *   - `tool`      → source 'tool-result' (tool return, current or history replay)
+ *   - `assistant` → source 'assistant' (prior LLM output replayed as history)
+ *   - `system`    → source 'base' (static system-prompt content replayed)
+ *
+ * If a memory strategy / RAG retriever re-injects a message with
+ * engineered intent, it must set its OWN source (`'memory'` / `'rag'`
+ * / etc.) at the injection site — NOT rely on role inference here.
+ * Role-based inference is the baseline fallback.
+ */
+function inferSource(role) {
+    switch (role) {
+        case 'user':
+            return 'user';
+        case 'tool':
+            return 'tool-result';
+        case 'assistant':
+            return 'assistant';
+        case 'system':
+            return 'base';
+        default:
+            return 'custom';
+    }
+}
+//# sourceMappingURL=buildMessagesSlot.js.map

package/dist/esm/core/slots/buildMessagesSlot.js.map

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

package/dist/esm/core/slots/buildSystemPromptSlot.js

@@ -0,0 +1,77 @@
+/**
+ * System-Prompt slot subflow builder
+ *
+ * Pattern: Builder (returns a FlowChart mountable via addSubFlowChartNext).
+ * Role:    Layer-3 context engineering; inside Layer-5 primitives
+ *          (LLMCall, Agent). Ported from v1's buildSystemPromptSubflow
+ *          to InjectionRecord + SlotComposition shape.
+ * Emits:   None directly. Writes to conventional scope keys; ContextRecorder
+ *          observes and emits context.* events.
+ *
+ * Minimal scope for Phase 3e: static prompt string OR a dynamic function
+ * of the input. Full SystemPromptProvider / Skill / RAG integration
+ * arrives in Phase 5.
+ */
+import { flowChart } from 'footprintjs';
+import { INJECTION_KEYS } from '../../conventions.js';
+import { COMPOSITION_KEYS } from '../../recorders/core/types.js';
+import { composeSlot, fnv1a, truncate } from './helpers.js';
+/**
+ * Build the System-Prompt slot subflow.
+ *
+ * Mount with:
+ *   builder.addSubFlowChartNext(SUBFLOW_IDS.SYSTEM_PROMPT, buildSystemPromptSlot(cfg), 'System Prompt', {
+ *     inputMapper: (parent) => ({ userMessage: parent.userMessage, iteration: parent.iteration }),
+ *     outputMapper: (sf) => ({ systemPromptInjections: sf.systemPromptInjections }),
+ *   })
+ */
+export function buildSystemPromptSlot(config) {
+    const budgetCap = config.budgetCap ?? 4000;
+    const reason = config.reason ?? 'static system prompt';
+    const promptSource = config.prompt;
+    return flowChart('Compose', async (scope) => {
+        const args = scope.$getArgs();
+        const resolved = typeof promptSource === 'function' ? await promptSource(args) : promptSource;
+        const injections = [];
+        // Base prompt — `source: 'base'`. Configured at build time via
+        // Agent.create({...}).system('...') OR LLMCall config. Baseline
+        // LLM API flow, not context engineering. The InjectionEngine
+        // subflow (mounted before this one) writes activeInjections[]
+        // to scope; this slot reads them and appends Injection-derived
+        // InjectionRecords below.
+        if (resolved && resolved.length > 0) {
+            injections.push({
+                contentSummary: truncate(resolved, 80),
+                contentHash: fnv1a(`sp:${resolved}`),
+                slot: 'system-prompt',
+                source: 'base',
+                reason,
+                rawContent: resolved,
+            });
+        }
+        // Active Injections targeting the system-prompt slot — the
+        // InjectionEngine subflow (mounted before this slot) wrote
+        // `activeInjections` to scope. We filter by `inject.systemPrompt`
+        // and append one InjectionRecord per active injection, tagged
+        // with the Injection's `flavor` (skill / steering / instructions /
+        // fact / etc.). ContextRecorder picks up zero-change.
+        const activeInjections = scope.$getValue('activeInjections') ?? [];
+        for (const inj of activeInjections) {
+            const promptContent = inj.inject.systemPrompt;
+            if (!promptContent || promptContent.length === 0)
+                continue;
+            injections.push({
+                contentSummary: truncate(promptContent, 80),
+                contentHash: fnv1a(`sp:${inj.flavor}:${inj.id}:${promptContent}`),
+                slot: 'system-prompt',
+                source: inj.flavor,
+                sourceId: inj.id,
+                reason: inj.description ?? `${inj.flavor} '${inj.id}' active`,
+                rawContent: promptContent,
+            });
+        }
+        scope.$setValue(INJECTION_KEYS.SYSTEM_PROMPT, injections);
+        scope.$setValue(COMPOSITION_KEYS.SLOT_COMPOSED, composeSlot('system-prompt', args.iteration ?? 1, injections, budgetCap));
+    }, 'compose', undefined, 'Compose system-prompt slot').build();
+}
+//# sourceMappingURL=buildSystemPromptSlot.js.map

package/dist/esm/core/slots/buildSystemPromptSlot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildSystemPromptSlot.js","sourceRoot":"","sources":["../../../../src/core/slots/buildSystemPromptSlot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AA6B5D;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA8B;IAClE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,sBAAsB,CAAC;IACvD,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC;IAEnC,OAAO,SAAS,CACd,SAAS,EACT,KAAK,EAAE,KAA2C,EAAE,EAAE;QACpD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAgD,CAAC;QAC5E,MAAM,QAAQ,GAAG,OAAO,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;QAE9F,MAAM,UAAU,GAAsB,EAAE,CAAC;QAEzC,+DAA+D;QAC/D,gEAAgE;QAChE,6DAA6D;QAC7D,8DAA8D;QAC9D,+DAA+D;QAC/D,0BAA0B;QAC1B,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,UAAU,CAAC,IAAI,CAAC;gBACd,cAAc,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;gBACtC,WAAW,EAAE,KAAK,CAAC,MAAM,QAAQ,EAAE,CAAC;gBACpC,IAAI,EAAE,eAAe;gBACrB,MAAM,EAAE,MAAM;gBACd,MAAM;gBACN,UAAU,EAAE,QAAQ;aACrB,CAAC,CAAC;QACL,CAAC;QAED,2DAA2D;QAC3D,2DAA2D;QAC3D,kEAAkE;QAClE,8DAA8D;QAC9D,mEAAmE;QACnE,sDAAsD;QACtD,MAAM,gBAAgB,GACnB,KAAK,CAAC,SAAS,CAAC,kBAAkB,CAA4C,IAAI,EAAE,CAAC;QACxF,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;YACnC,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC;YAC9C,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAC3D,UAAU,CAAC,IAAI,CAAC;gBACd,cAAc,EAAE,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC;gBAC3C,WAAW,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,aAAa,EAAE,CAAC;gBACjE,IAAI,EAAE,eAAe;gBACrB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,QAAQ,EAAE,GAAG,CAAC,EAAE;gBAChB,MAAM,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,UAAU;gBAC7D,UAAU,EAAE,aAAa;aAC1B,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,cAAc,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QAC1D,KAAK,CAAC,SAAS,CACb,gBAAgB,CAAC,aAAa,EAC9B,WAAW,CAAC,eAAe,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,CACzE,CAAC;IACJ,CAAC,EACD,SAAS,EACT,SAAS,EACT,4BAA4B,CAC7B,CAAC,KAAK,EAAE,CAAC;AACZ,CAAC"}

package/dist/esm/core/slots/buildToolsSlot.js

@@ -0,0 +1,81 @@
+/**
+ * Tools slot subflow builder
+ *
+ * Pattern: Builder (returns a FlowChart mountable via addSubFlowChartNext).
+ * Role:    Layer-3 context engineering. Resolves the tools list the LLM
+ *          sees on this iteration — one InjectionRecord per exposed tool.
+ * Emits:   None directly; ContextRecorder sees the writes.
+ *
+ * Minimal scope for Phase 3e: static tool registry, all exposed every
+ * iteration. Full permission gating / skill activation / context-aware
+ * tool filtering arrives in Phase 5.
+ */
+import { flowChart } from 'footprintjs';
+import { INJECTION_KEYS } from '../../conventions.js';
+import { COMPOSITION_KEYS } from '../../recorders/core/types.js';
+import { composeSlot, fnv1a, truncate } from './helpers.js';
+/**
+ * Build the Tools slot subflow.
+ *
+ * Mount with:
+ *   builder.addSubFlowChartNext(SUBFLOW_IDS.TOOLS, buildToolsSlot(cfg), 'Tools', {
+ *     inputMapper: (parent) => ({ iteration: parent.iteration }),
+ *     outputMapper: (sf) => ({ toolsInjections: sf.toolsInjections, toolSchemas: sf.toolSchemas }),
+ *   })
+ */
+export function buildToolsSlot(config) {
+    const budgetCap = config.budgetCap ?? 2000;
+    const tools = config.tools;
+    return flowChart('Compose', (scope) => {
+        const args = scope.$getArgs();
+        const iteration = args.iteration ?? 1;
+        const injections = tools.map((t, i) => {
+            const summary = `${t.name}: ${t.description}`;
+            // `source: 'registry'` — tools configured at build time via
+            // `.tool(...)` are baseline API flow (the static tool list
+            // sent to the LLM), NOT context engineering. Skills /
+            // Instructions that gate tools dynamically tag their
+            // injections with their flavor below.
+            return {
+                contentSummary: truncate(summary, 80),
+                contentHash: fnv1a(`tool:${t.name}:${t.description}`),
+                slot: 'tools',
+                source: 'registry',
+                sourceId: t.name,
+                reason: 'tool registry',
+                rawContent: summary,
+                position: i,
+            };
+        });
+        // Active Injections targeting the tools slot (Skills with
+        // tools=[…]). Filter activeInjections by `inject.tools`.
+        const activeInjections = scope.$getValue('activeInjections') ?? [];
+        const dynamicSchemas = [];
+        for (const inj of activeInjections) {
+            const injTools = inj.inject.tools;
+            if (!injTools || injTools.length === 0)
+                continue;
+            for (const tool of injTools) {
+                const schema = tool.schema;
+                dynamicSchemas.push(schema);
+                const summary = `${schema.name}: ${schema.description}`;
+                injections.push({
+                    contentSummary: truncate(summary, 80),
+                    contentHash: fnv1a(`tool:${inj.flavor}:${inj.id}:${schema.name}`),
+                    slot: 'tools',
+                    source: inj.flavor,
+                    sourceId: inj.id,
+                    reason: `${inj.flavor} '${inj.id}' unlocked tool '${schema.name}'`,
+                    rawContent: summary,
+                    position: tools.length + dynamicSchemas.length - 1,
+                });
+            }
+        }
+        scope.$setValue(INJECTION_KEYS.TOOLS, injections);
+        // Pass merged schemas (registry + active injection-supplied) so
+        // the Agent sends ALL of them to the provider on this iteration.
+        scope.toolSchemas = [...tools, ...dynamicSchemas];
+        scope.$setValue(COMPOSITION_KEYS.SLOT_COMPOSED, composeSlot('tools', iteration, injections, budgetCap, 'registry+injections'));
+    }, 'compose', undefined, 'Compose tools slot').build();
+}
+//# sourceMappingURL=buildToolsSlot.js.map

package/dist/esm/core/slots/buildToolsSlot.js.map

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

package/dist/esm/core/slots/helpers.js

@@ -0,0 +1,58 @@
+/**
+ * Shared helpers for slot subflow builders.
+ *
+ * Pattern: utility module.
+ * Role:    Tiny pure functions the slot builders share — hash, truncate,
+ *          breakdown. Kept co-located to avoid cross-package import churn.
+ */
+/** Non-cryptographic stable hash — sufficient for InjectionRecord dedup. */
+export function fnv1a(input) {
+    let h = 2166136261;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0).toString(16);
+}
+/** Truncate with ellipsis for contentSummary fields. */
+export function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, n - 1) + '…';
+}
+/** Aggregate injection chars/count per source — payload for SlotComposition. */
+export function breakdown(injections) {
+    const out = {};
+    for (const r of injections) {
+        const chars = r.rawContent?.length ?? r.contentSummary.length;
+        const existing = out[r.source];
+        if (existing) {
+            out[r.source] = {
+                chars: existing.chars + chars,
+                count: existing.count + 1,
+            };
+        }
+        else {
+            out[r.source] = { chars, count: 1 };
+        }
+    }
+    return out;
+}
+/**
+ * Build a SlotComposition summary record from injections + budget cap.
+ * Drop tracking is opt-in — pass `dropped` when the slot actually
+ * evicted anything during composition.
+ */
+export function composeSlot(slot, iteration, injections, budgetCap, orderingStrategy, dropped) {
+    const used = injections.reduce((sum, r) => sum + (r.rawContent?.length ?? r.contentSummary.length), 0);
+    return {
+        slot,
+        iteration,
+        budget: { cap: budgetCap, used, headroomChars: Math.max(0, budgetCap - used) },
+        sourceBreakdown: breakdown(injections),
+        ...(orderingStrategy !== undefined && { orderingStrategy }),
+        droppedCount: dropped?.count ?? 0,
+        droppedSummaries: dropped?.summaries ?? [],
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/esm/core/slots/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../src/core/slots/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,4EAA4E;AAC5E,MAAM,UAAU,KAAK,CAAC,KAAa;IACjC,IAAI,CAAC,GAAG,UAAU,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,CAAS;IAC3C,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;AACjC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,SAAS,CACvB,UAAsC;IAEtC,MAAM,GAAG,GAAqE,EAAE,CAAC;IACjF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,CAAC,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC;QAC9D,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,QAAQ,EAAE,CAAC;YACb,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG;gBACd,KAAK,EAAE,QAAQ,CAAC,KAAK,GAAG,KAAK;gBAC7B,KAAK,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC;aAC1B,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,IAAiB,EACjB,SAAiB,EACjB,UAAsC,EACtC,SAAiB,EACjB,gBAAyB,EACzB,OAAyD;IAEzD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAC5B,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,EACnE,CAAC,CACF,CAAC;IACF,OAAO;QACL,IAAI;QACJ,SAAS;QACT,MAAM,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC,EAAE;QAC9E,eAAe,EAAE,SAAS,CAAC,UAAU,CAAC;QACtC,GAAG,CAAC,gBAAgB,KAAK,SAAS,IAAI,EAAE,gBAAgB,EAAE,CAAC;QAC3D,YAAY,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QACjC,gBAAgB,EAAE,OAAO,EAAE,SAAS,IAAI,EAAE;KAC3C,CAAC;AACJ,CAAC"}

package/dist/esm/core/tools.js

@@ -0,0 +1,38 @@
+/**
+ * Tool types — Agent's tool-call contract.
+ *
+ * Pattern: Strategy (GoF) — each Tool is a strategy for "how to execute
+ *          this named operation given these args".
+ * Role:    Consumer-facing shape. Agent.tool(...) accepts these.
+ * Emits:   N/A (types only).
+ */
+/**
+ * Ergonomic builder for `Tool`. Equivalent to constructing an object
+ * literal with `schema` + `execute`, but flatter and safer — the name
+ * + description live alongside the executor so they can't drift.
+ *
+ * @example
+ *   const weather = defineTool<{ city: string }, string>({
+ *     name: 'weather',
+ *     description: 'Get current weather for a city',
+ *     inputSchema: {
+ *       type: 'object',
+ *       properties: { city: { type: 'string' } },
+ *       required: ['city'],
+ *     },
+ *     execute: async ({ city }) => `${city}: 72°F sunny`,
+ *   });
+ *
+ *   const agent = Agent.create({ provider }).tool(weather).build();
+ */
+export function defineTool(options) {
+    return {
+        schema: {
+            name: options.name,
+            description: options.description,
+            inputSchema: options.inputSchema ?? { type: 'object', properties: {} },
+        },
+        execute: options.execute,
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/esm/core/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmDH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,UAAU,CACxB,OAA0C;IAE1C,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACvE;QACD,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC"}