agentfootprint 10.2.0 → 10.3.1

package/dist/esm/stream.d.ts

@@ -1,92 +0,0 @@
-/**
- * stream — agent events → Server-Sent Events helpers.
- *
- * Pattern: Adapter (event stream → SSE wire format).
- * Role:    Outer ring. Subscribes to a `Runner`'s `EventDispatcher`
- *          and yields SSE-formatted strings. Drop into any HTTP
- *          framework that accepts an async iterable response body
- *          (Fetch Response, Express res.write, Hono streaming, etc.).
- * Emits:   N/A — observes only.
- *
- * Not an import path of its own since 9.0.0. This is the implementation barrel
- * behind `agentfootprint/observe`, which re-exports every name here — same
- * symbols, one door. Import from the door.
- */
-import type { AgentfootprintEvent } from './events/registry.js';
-import type { RunnerBase } from './core/RunnerBase.js';
-/**
- * Hand the runner this iterable's caller before calling `runner.run()`.
- * Yields SSE-formatted strings until the run finishes (success, error,
- * or pause). Each event becomes:
- *
- *   event: <event name>
- *   data: <JSON payload>
- *   <blank line>
- *
- * @example
- *   // Express
- *   app.post('/agent', async (req, res) => {
- *     res.setHeader('content-type', 'text/event-stream');
- *     for await (const chunk of toSSE(agent)) {
- *       res.write(chunk);
- *     }
- *     res.end();
- *     // (in parallel: await agent.run(req.body))
- *   });
- */
-export interface ToSSEOptions {
-    /**
-     * Filter predicate — return false to skip an event. Default: all events.
-     * Common: `event => event.type.startsWith('agentfootprint.stream.')`
-     * for a token-only feed. It sees each event as the run's RECORD serves it —
-     * under an agent's `redact`, the placeholder wherever the policy selected a
-     * value — in both formats.
-     */
-    readonly filter?: (event: AgentfootprintEvent) => boolean;
-    /**
-     * Output shape:
-     *   - 'full' (default) — each event is JSON-serialized verbatim: the run's
-     *     RECORD, so under an agent's `redact` policy it is the served event
-     *     (the placeholder wherever the policy selected a value).
-     *   - 'text' — only `agentfootprint.stream.token.content` is yielded,
-     *     in plain text form (no event/data prefix). Useful for piping
-     *     directly into a chat UI. This is the REPLY to the person who asked —
-     *     the caller's own answer, like `run()`'s return — so a redaction
-     *     policy never masks it.
-     */
-    readonly format?: 'full' | 'text';
-    /**
-     * Custom event name extractor. By default `event.type` is used.
-     * Useful for SSE consumers that want their own naming.
-     */
-    readonly eventName?: (event: AgentfootprintEvent) => string;
-    /**
-     * Heartbeat interval in ms. SSE connections through proxies/load
-     * balancers often die after ~30s of silence; emit `: ping` comments
-     * at this interval. Default 0 (disabled).
-     */
-    readonly heartbeatMs?: number;
-}
-/**
- * Subscribe to a runner's `EventDispatcher` and yield SSE-formatted
- * strings until the run completes.
- */
-export declare function toSSE<TIn, TOut>(runner: RunnerBase<TIn, TOut>, options?: ToSSEOptions): AsyncIterable<string>;
-/**
- * Class form for consumers who prefer `new SSEFormatter(runner).stream()`.
- * Identical behavior to `toSSE(runner)` — pick by preference.
- */
-export declare class SSEFormatter<TIn = unknown, TOut = unknown> {
-    private readonly runner;
-    private readonly options;
-    constructor(runner: RunnerBase<TIn, TOut>, options?: ToSSEOptions);
-    /** Async iterable of SSE chunks. Consume with `for await`. */
-    stream(): AsyncIterable<string>;
-}
-/**
- * Format any JSON-able payload as a single SSE event chunk.
- *
- * Useful for app-level events outside the runner's typed registry
- * (auth/error frames, app-state echoes). Most consumers won't need this.
- */
-export declare function encodeSSE(eventName: string, payload: unknown): string;

package/dist/esm/stream.js

@@ -1,183 +0,0 @@
-/**
- * stream — agent events → Server-Sent Events helpers.
- *
- * Pattern: Adapter (event stream → SSE wire format).
- * Role:    Outer ring. Subscribes to a `Runner`'s `EventDispatcher`
- *          and yields SSE-formatted strings. Drop into any HTTP
- *          framework that accepts an async iterable response body
- *          (Fetch Response, Express res.write, Hono streaming, etc.).
- * Emits:   N/A — observes only.
- *
- * Not an import path of its own since 9.0.0. This is the implementation barrel
- * behind `agentfootprint/observe`, which re-exports every name here — same
- * symbols, one door. Import from the door.
- */
-import { runnerLive } from './core/runnerLive.js';
-import { toWireJson } from './lib/wireJson.js';
-/**
- * Subscribe to a runner's `EventDispatcher` and yield SSE-formatted
- * strings until the run completes.
- */
-export async function* toSSE(runner, options = {}) {
-    const filter = options.filter;
-    const format = options.format ?? 'full';
-    const eventName = options.eventName ?? ((e) => e.type);
-    const heartbeatMs = options.heartbeatMs ?? 0;
-    // Pull the dispatcher off the runner. RunnerBase exposes it as
-    // protected — we cast to access. No public dispatcher() method
-    // exists ; runners forward .on/.off via their public API.
-    const dispatcher = runner.dispatcher;
-    // Bounded queue: events drained as the consumer iterates.
-    const queue = [];
-    let waiter = null;
-    let done = false;
-    const wakeup = () => {
-        if (waiter) {
-            const w = waiter;
-            waiter = null;
-            w.resolve();
-        }
-    };
-    // Every event — and so every event the consumer's `filter` sees — is the
-    // RECORD: served under the run's redaction policy like every other
-    // listener's. 'text' then streams the REPLY to the person who asked, the
-    // caller's own answer, which a policy never masks: each token's text is
-    // taken from the run's real-value path (`core/runnerLive.ts` ·
-    // `runnerLive`) — matched to its served event by the token's address (its
-    // stage, iteration and index, none of which a policy selects), so a served
-    // token that never arrives cannot shift the ones after it — and never
-    // handed to consumer code. A runner that is not a RunnerBase has no
-    // redaction and no live taps: its events are the record and the reply at once.
-    const live = format === 'text' ? runnerLive(runner) : undefined;
-    const replies = new Map();
-    const offReplies = live?.onRealEvent((event) => {
-        if (event.type !== 'agentfootprint.stream.token')
-            return;
-        const content = event.payload?.content;
-        const key = tokenAddress(event);
-        const waiting = replies.get(key);
-        const text = typeof content === 'string' ? content : '';
-        if (waiting === undefined)
-            replies.set(key, [text]);
-        else
-            waiting.push(text);
-    });
-    const replyFor = (event) => {
-        const key = tokenAddress(event);
-        const waiting = replies.get(key);
-        const text = waiting?.shift();
-        if (waiting !== undefined && waiting.length === 0)
-            replies.delete(key);
-        return text;
-    };
-    const listener = (event) => {
-        // Taken before the filter, so a filtered-out token still consumes its text.
-        const reply = live !== undefined && event.type === 'agentfootprint.stream.token'
-            ? replyFor(event)
-            : undefined;
-        if (filter && !filter(event))
-            return;
-        queue.push(reply !== undefined
-            ? { type: event.type, payload: { content: reply } }
-            : event);
-        wakeup();
-        // `agent.turn_end` (or composition exit on the outermost runner)
-        // ends the stream naturally; the consumer's `for await` finishes
-        // when the iterator returns.
-        if (event.type === 'agentfootprint.agent.turn_end' ||
-            event.type === 'agentfootprint.error.fatal') {
-            done = true;
-            wakeup();
-        }
-    };
-    const offRecord = dispatcher.on('*', listener);
-    const unsub = () => {
-        offRecord();
-        offReplies?.();
-    };
-    let heartbeat;
-    if (heartbeatMs > 0) {
-        heartbeat = setInterval(() => {
-            queue.push({ type: '__heartbeat' });
-            wakeup();
-        }, heartbeatMs);
-    }
-    try {
-        while (!done || queue.length > 0) {
-            while (queue.length > 0) {
-                // queue.length > 0 guards the shift; result is defined.
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                const event = queue.shift();
-                if (event.type === '__heartbeat') {
-                    yield ': ping\n\n';
-                    continue;
-                }
-                if (format === 'text') {
-                    if (event.type === 'agentfootprint.stream.token') {
-                        const payload = event.payload;
-                        if (payload?.content)
-                            yield payload.content;
-                    }
-                }
-                else {
-                    yield encodeSSE(eventName(event), event);
-                }
-            }
-            if (done)
-                break;
-            await new Promise((resolve) => {
-                waiter = { resolve };
-            });
-        }
-    }
-    finally {
-        unsub();
-        if (heartbeat)
-            clearInterval(heartbeat);
-    }
-}
-/**
- * Class form for consumers who prefer `new SSEFormatter(runner).stream()`.
- * Identical behavior to `toSSE(runner)` — pick by preference.
- */
-export class SSEFormatter {
-    runner;
-    options;
-    constructor(runner, options = {}) {
-        this.runner = runner;
-        this.options = options;
-    }
-    /** Async iterable of SSE chunks. Consume with `for await`. */
-    stream() {
-        return toSSE(this.runner, this.options);
-    }
-}
-/**
- * Format any JSON-able payload as a single SSE event chunk.
- *
- * Useful for app-level events outside the runner's typed registry
- * (auth/error frames, app-state echoes). Most consumers won't need this.
- */
-export function encodeSSE(eventName, payload) {
-    // The wire rule (`lib/wireJson.ts`): an Error in a payload streams as its
-    // name, message, code and cause — never its custom properties or stack.
-    const json = toWireJson(payload);
-    // Escape newlines inside JSON (rare with stringify) so the data field
-    // stays single-line. SSE's data: lines can be repeated, but the
-    // canonical encoder keeps it simple.
-    return `event: ${eventName}\ndata: ${json}\n\n`;
-}
-/**
- * A token event's address — the stage that emitted it, its iteration and its
- * index: the same on the real-value path and on its served twin, and never a
- * name a redaction policy selects. `toSSE`'s 'text' pairing key.
- */
-function tokenAddress(event) {
-    const payload = event.payload;
-    return [
-        event.meta?.runtimeStageId ?? '',
-        String(payload?.iteration ?? ''),
-        String(payload?.tokenIndex ?? ''),
-    ].join('\u001f');
-}
-//# sourceMappingURL=stream.js.map

package/dist/esm/stream.js.map

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

package/dist/esm/tool-providers/skillScopedTools.d.ts

@@ -1,56 +0,0 @@
-/**
- * skillScopedTools — ToolProvider that exposes a tool subset only while a
- * specific Skill is the one the model most recently loaded.
- *
- * **You probably don't need this.** If the tools belong to the skill, hand them
- * to the skill: `defineSkill({ tools: [...], autoActivate: 'currentSkill' })`
- * already narrows the LLM's tool list to the active skill, with no provider
- * wiring at all. This provider is for tools that CAN'T ride on the skill —
- * a list assembled elsewhere, discovered at runtime, or owned by another module.
- *
- * Three facts worth knowing before you wire it:
- *
- * 1. **`ctx.activeSkillId` is the last `read_skill` activation, not the graph
- *    cursor.** The runtime fills it from the tail of `scope.activatedInjectionIds`,
- *    which only `read_skill` ever appends to. A skill that activated because an
- *    entry RULE matched, or because a `skillGraph()` edge routed into it, does
- *    NOT set it — `list(ctx)` will return `[]` for that skill. Scope by graph
- *    position with the skill's own `tools:[]` instead.
- * 2. **One ToolProvider per agent.** `AgentBuilder.toolProvider()` throws on the
- *    second call. Compose several scopes into ONE provider (see the example
- *    below) rather than calling it in a loop.
- * 3. It is pure compute — no Agent-runtime dependency — so it is equally usable
- *    from a test or a design-time inspection.
- *
- * @example  One skill's tools, scoped by activation
- *   const billingTools = skillScopedTools('billing', [refundTool, chargeTool]);
- *   billingTools.list({ iteration: 1, activeSkillId: 'billing' });
- *   // → [refundTool, chargeTool]
- *   billingTools.list({ iteration: 1, activeSkillId: 'refund' });
- *   // → [] (a different skill was loaded)
- *   billingTools.list({ iteration: 1 });
- *   // → [] (nothing loaded via read_skill — see fact 1 above)
- *
- * @example  Compose with baseline + multiple skills
- *   const baseline   = staticTools([lookupOrderTool, listSkills, readSkill]);
- *   const billingTbx = skillScopedTools('billing', [refundTool, chargeTool]);
- *   const refundTbx  = skillScopedTools('refund',  [reverseTool]);
- *
- *   // ONE provider for the agent (see fact 2) — concatenate the scopes:
- *   const provider: ToolProvider = {
- *     id: 'composite',
- *     list: (ctx) => [
- *       ...baseline.list(ctx),
- *       ...billingTbx.list(ctx),
- *       ...refundTbx.list(ctx),
- *     ],
- *   };
- *   Agent.create({ provider: llm, model }).toolProvider(provider).build();
- */
-import type { Tool } from '../core/tools.js';
-import type { ToolProvider } from './types.js';
-/** The `ToolProvider.id` prefix every `skillScopedTools(...)` carries. */
-export declare const SKILL_SCOPED_TOOLS_ID_PREFIX = "skill-scoped:";
-/** Recover the skill id from a `skillScopedTools` provider id, or `undefined`. */
-export declare function skillScopedToolsTarget(providerId: string | undefined): string | undefined;
-export declare function skillScopedTools(skillId: string, tools: readonly Tool[]): ToolProvider;

package/dist/esm/tool-providers/skillScopedTools.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"skillScopedTools.js","sourceRoot":"","sources":["../../../src/tool-providers/skillScopedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,4BAA4B,GAAG,eAAe,CAAC;AAE5D,kFAAkF;AAClF,MAAM,UAAU,sBAAsB,CAAC,UAA8B;IACnE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,4BAA4B,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5E,MAAM,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACjE,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACxC,CAAC;AAED,uCAAuC;AACvC,uGAAuG;AACvG,wGAAwG;AACxG,+FAA+F;AAC/F,iIAAiI;AACjI,mFAAmF;AACnF,2BAA2B;AAC3B,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,KAAsB;IACtE,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,kEAAkE;IAClE,+DAA+D;IAC/D,2DAA2D;IAC3D,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC5B,8EAA8E;IAC9E,IAAI,oBAAoB,GAAG,KAAK,CAAC;IACjC,OAAO;QACL,EAAE,EAAE,GAAG,4BAA4B,GAAG,OAAO,EAAE;QAC/C,IAAI,CAAC,GAAwB;YAC3B,2CAA2C;YAC3C,IAAI,GAAG,CAAC,aAAa,KAAK,OAAO,EAAE,CAAC;gBAClC,6EAA6E;gBAC7E,2EAA2E;gBAC3E,8EAA8E;gBAC9E,6EAA6E;gBAC7E,uEAAuE;gBACvE,yEAAyE;gBACzE,6EAA6E;gBAC7E,0CAA0C;gBAC1C,IAAI,SAAS,EAAE,IAAI,CAAC,oBAAoB,IAAI,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBAClF,oBAAoB,GAAG,IAAI,CAAC;oBAC5B,sCAAsC;oBACtC,OAAO,CAAC,IAAI,CACV,oCAAoC,OAAO,cAAc,OAAO,iBAAiB;wBAC/E,aAAa,GAAG,CAAC,SAAS,gDAAgD;wBAC1E,kFAAkF;wBAClF,kFAAkF;wBAClF,oFAAoF;wBACpF,qEAAqE,CACxE,CAAC;gBACJ,CAAC;gBACD,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC;AACD,8BAA8B"}

package/dist/esm/tool-providers/types.d.ts

@@ -1,163 +0,0 @@
-/**
- * ToolProvider — abstraction over tool dispatch.
- *
- * v2.4 shipped tools as a flat array on the agent (registered via
- * `agent.tool(t)` / `agent.tools(arr)`). That model breaks down once
- * production agents need:
- *   1. Permission gating per-tool, per-caller (read-only roles, etc.)
- *   2. Per-skill tool gating (only show the active skill's tools to
- *      the LLM each turn)
- *   3. Composable filters (a `withReadonly` decorator over a `withSkill`
- *      decorator over the base tool list)
- *
- * `ToolProvider` is the answer: a chainable abstraction over "what
- * tools does the LLM see right now?". The agent asks the provider
- * each iteration; the provider returns the visible tool set computed
- * from whatever predicates / role gates / skill filters the consumer
- * composed.
- *
- * Pattern: Strategy (GoF) — each ToolProvider is a strategy for
- *          "compute the visible tool list given current context".
- *          Decorator (GoF) — `gatedTools(inner, predicate)` wraps any
- *          provider with an additional filter, mirroring how `withRetry`
- *          / `withFallback` decorate `LLMProvider`.
- * Role:    Layer-3 tool-dispatch primitive. Agent calls `provider.list(ctx)`
- *          each iteration to compute the visible tool set.
- * Emits:   N/A (pure compute; permission denials emit elsewhere via the
- *          permission subsystem).
- *
- * @example  Static tool list (90% case — what `.tools(arr)` does today)
- *   const provider = staticTools([weather, lookupOrder]);
- *
- * @example  Read-only enforcement (role-based gate)
- *   const readOnlyProvider = gatedTools(
- *     staticTools([weather, lookupOrder, processRefund]),
- *     (toolName) => policy.isAllowed(toolName),
- *   );
- *
- * @example  Skill-gated dispatch (only active skill's tools visible)
- *   const skillGated = gatedTools(
- *     staticTools(allTools),
- *     (toolName, ctx) => ctx.activeSkillId
- *       ? skillsToolMap[ctx.activeSkillId].includes(toolName)
- *       : alwaysVisible.includes(toolName),
- *   );
- *
- * @example  Stack: read-only over skill-gated
- *   const provider = gatedTools(
- *     gatedTools(staticTools(allTools), readOnlyPredicate),
- *     skillGatePredicate,
- *   );
- */
-import type { Tool } from '../core/tools.js';
-/**
- * Read-only context the provider receives each iteration. Pure data
- * — providers MUST NOT mutate. Used by gating predicates to inspect
- * the current activation state.
- */
-export interface ToolDispatchContext {
-    /** Current ReAct iteration (1-based). */
-    readonly iteration: number;
-    /**
-     * The id of the currently-activated Skill, if any.
-     * Set by `read_skill(id)` activation; cleared between turns.
-     * Used by `autoActivate`-driven per-skill tool gating.
-     *
-     * **This is the last `read_skill` activation, not the graph's position.** It is
-     * filled from the tail of `activatedInjectionIds`, which only `read_skill` ever
-     * appends to. For "which skills are actually loaded right now", including the ones
-     * an entry rule or a `skillGraph()` edge activated, read {@link activeSkillIds}.
-     */
-    readonly activeSkillId?: string;
-    /**
-     * **Every skill active on this iteration** — the real active set, however each one
-     * got there: a `read_skill` activation, an entry rule, a `skillGraph()` route, a
-     * decision-tree leaf. Added in 8.7.0.
-     *
-     * `activeSkillId` answers "what did the model most recently open"; this answers
-     * "what is loaded". A provider that wants to follow the graph's POSITION — which
-     * `skillScopedTools`' own docs said was impossible — reads this one:
-     *
-     * ```ts
-     * const graphScoped = (id: string, tools: Tool[]): ToolProvider => ({
-     *   id: `graph-scoped:${id}`,
-     *   list: (ctx) => (ctx.activeSkillIds?.includes(id) ? tools : []),
-     * });
-     * ```
-     *
-     * Optional for forward-compat: a provider written before 8.7.0 sees `undefined` and
-     * behaves exactly as it always did.
-     */
-    readonly activeSkillIds?: readonly string[];
-    /**
-     * Caller identity tuple — passed through from `agent.run({ identity })`.
-     * Permission predicates can role-check based on `identity.principal`
-     * or `identity.tenant`.
-     */
-    readonly identity?: {
-        readonly tenant?: string;
-        readonly principal?: string;
-        readonly conversationId: string;
-    };
-    /**
-     * Optional abort signal propagated from the agent's `run({ env })` /
-     * AbortController. Async providers (network discovery, MCP catalog
-     * fetch, registry pull) MUST honor this — abandon the in-flight
-     * request when the agent is cancelled mid-discovery, otherwise the
-     * provider holds the run open past abort. Sync providers can ignore
-     * it.
-     */
-    readonly signal?: AbortSignal;
-}
-/**
- * The provider interface. A `ToolProvider` answers ONE question per
- * iteration: "what tools should the LLM see right now?"
- *
- * Implementations are PURE — given the same context, return the same
- * tool list (no observable mutation; reentrant; safe under concurrent
- * calls).
- *
- * **Sync vs async.** Most providers (`staticTools`, `gatedTools`,
- * `skillScopedTools`) compute the answer synchronously and return
- * `readonly Tool[]` — the agent's hot path skips the await microtask
- * entirely via a runtime `instanceof Promise` check. Discovery-style
- * providers (MCP catalog fetch, registry pull, dynamic skill resolution)
- * may return `Promise<readonly Tool[]>`; the agent awaits only when
- * the value is actually a Promise. Sync providers pay zero overhead.
- *
- * **Caching.** The agent calls `list(ctx)` once per iteration. For
- * expensive lookups (network calls, hub queries), the provider is
- * responsible for caching — typically TTL- or iteration-keyed. The
- * framework deliberately does NOT cache for you because the cache
- * key depends on which fields of `ctx` matter to your provider
- * (e.g., per-skill vs per-tenant vs per-iteration).
- *
- * **Errors.** A throwing or rejecting provider emits
- * `agentfootprint.tools.discovery_failed` and aborts the iteration —
- * the run continues only if a configured `reliability` rule routes
- * the error (`fail-fast`, `retry`, etc.). Discovery failure is loud
- * by design; silently dropping tools mid-conversation produces
- * non-deterministic agent behavior that's harder to debug than a
- * crash.
- */
-export interface ToolProvider {
-    /**
-     * Return the tool list visible to the LLM for the current iteration.
-     * Sync return is the fast path; Promise return is supported for
-     * discovery-style providers. The returned array MUST be a NEW
-     * reference each call (the agent compares for change detection).
-     * Order is preserved — the LLM may use position as a hint when tool
-     * descriptions are ambiguous.
-     */
-    list(ctx: ToolDispatchContext): readonly Tool[] | Promise<readonly Tool[]>;
-    /**
-     * Optional: stable id for observability / debugging. Defaults to
-     * `'static'` for `staticTools`, `'gated'` for `gatedTools`. Custom
-     * implementations should set their own id — surfaces on
-     * `agentfootprint.tools.discovery_failed.providerId` so consumers
-     * can route alerts to the right hub adapter.
-     */
-    readonly id?: string;
-}
-/** Predicate for `gatedTools` — runs per tool, per iteration. */
-export type ToolGatePredicate = (toolName: string, ctx: ToolDispatchContext) => boolean;

package/dist/esm/tool-providers/types.js

@@ -1,53 +0,0 @@
-/**
- * ToolProvider — abstraction over tool dispatch.
- *
- * v2.4 shipped tools as a flat array on the agent (registered via
- * `agent.tool(t)` / `agent.tools(arr)`). That model breaks down once
- * production agents need:
- *   1. Permission gating per-tool, per-caller (read-only roles, etc.)
- *   2. Per-skill tool gating (only show the active skill's tools to
- *      the LLM each turn)
- *   3. Composable filters (a `withReadonly` decorator over a `withSkill`
- *      decorator over the base tool list)
- *
- * `ToolProvider` is the answer: a chainable abstraction over "what
- * tools does the LLM see right now?". The agent asks the provider
- * each iteration; the provider returns the visible tool set computed
- * from whatever predicates / role gates / skill filters the consumer
- * composed.
- *
- * Pattern: Strategy (GoF) — each ToolProvider is a strategy for
- *          "compute the visible tool list given current context".
- *          Decorator (GoF) — `gatedTools(inner, predicate)` wraps any
- *          provider with an additional filter, mirroring how `withRetry`
- *          / `withFallback` decorate `LLMProvider`.
- * Role:    Layer-3 tool-dispatch primitive. Agent calls `provider.list(ctx)`
- *          each iteration to compute the visible tool set.
- * Emits:   N/A (pure compute; permission denials emit elsewhere via the
- *          permission subsystem).
- *
- * @example  Static tool list (90% case — what `.tools(arr)` does today)
- *   const provider = staticTools([weather, lookupOrder]);
- *
- * @example  Read-only enforcement (role-based gate)
- *   const readOnlyProvider = gatedTools(
- *     staticTools([weather, lookupOrder, processRefund]),
- *     (toolName) => policy.isAllowed(toolName),
- *   );
- *
- * @example  Skill-gated dispatch (only active skill's tools visible)
- *   const skillGated = gatedTools(
- *     staticTools(allTools),
- *     (toolName, ctx) => ctx.activeSkillId
- *       ? skillsToolMap[ctx.activeSkillId].includes(toolName)
- *       : alwaysVisible.includes(toolName),
- *   );
- *
- * @example  Stack: read-only over skill-gated
- *   const provider = gatedTools(
- *     gatedTools(staticTools(allTools), readOnlyPredicate),
- *     skillGatePredicate,
- *   );
- */
-export {};
-//# sourceMappingURL=types.js.map

package/dist/esm/tool-providers/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/tool-providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG"}