agentfootprint 6.44.0 → 6.45.0

package/dist/esm/core/agent/stages/reliabilityExecution.d.ts

@@ -0,0 +1,135 @@
+/**
+ * reliabilityExecution — the retry-loop helper invoked by `callLLM`
+ * when `Agent.create(...).reliability(config)` is configured.
+ *
+ * Wraps a single-shot LLM call with rules-based reliability semantics:
+ *
+ *   PreCheck rules    → continue / fail-fast
+ *     ↓
+ *   provider call     → response | error
+ *     ↓
+ *   PostDecide rules  → ok / retry / retry-other / fallback / fail-fast
+ *     ↓
+ *   loop or commit
+ *
+ * The loop runs in JS within a SINGLE footprintjs stage execution. The
+ * trace shows one CallLLM stage that internally retried N times. Richer
+ * "every retry as a separate stage" tracing is the v2.11.6+ work via
+ * `buildReliabilityGateChart` (which trades streaming support for
+ * stage-level granularity).
+ *
+ * Streaming + reliability semantics — first-chunk arbitration:
+ *   • Pre-first-chunk failures (connection, headers, breaker-open):
+ *     full rule set fires (retry / retry-other / fallback / fail-fast).
+ *   • Post-first-chunk failures (mid-stream): rules can ONLY emit
+ *     `ok` (commit what we have) or `fail-fast`. Retry / retry-other /
+ *     fallback are escalated to fail-fast with kind
+ *     `'mid-stream-not-retryable'`. Matches LangChain's
+ *     `RunnableWithFallbacks` first-chunk arbitration pattern.
+ *
+ * On fail-fast: writes `failKind` + `failPayload` to agent scope and
+ * calls `$break(reason)`. The agent's main chart catches the break;
+ * `Agent.run()` translates it into a typed `ReliabilityFailFastError`
+ * at the API boundary (via `TranslateFailFast` stage).
+ *
+ * Closure-local state (NOT scope):
+ *   • `attempt`         — 1-indexed attempt counter
+ *   • `providerIdx`     — index into the failover list
+ *   • `breakerStates`   — per-provider breaker state (Map)
+ *   • `attemptsPerProvider` — per-provider counter
+ *
+ * Why closure-local: this is one footprintjs stage execution. Putting
+ * counters into scope would commit them across iterations of the
+ * agent's outer ReAct loop, which is not the intent.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { LLMProvider, LLMRequest, LLMResponse } from '../../../adapters/types.js';
+import type { ReliabilityConfig, ReliabilityRule, ReliabilityScope } from '../../../reliability/types.js';
+import type { AgentState } from '../types.js';
+/** A single-shot LLM call function. Built once by `callLLM.ts` and
+ *  passed into this helper; we invoke it once per loop iteration. */
+export type LLMCallFn = (request: LLMRequest, hooks: {
+    /** Called the first time a streaming chunk yields content. After
+     *  this fires, mid-stream errors will escalate retry/fallback to
+     *  fail-fast. */
+    onFirstChunk?: () => void;
+}) => Promise<LLMResponse>;
+/**
+ * v2.13 — Output-schema validation hook. Called by the reliability loop
+ * AFTER a successful LLM response, BEFORE the response is committed.
+ * Throw to signal validation failure — the gate treats the throw as a
+ * `'schema-fail'` errorKind and routes via PostDecide rules (which can
+ * `retry` with `feedbackForLLM` for Instructor-style schema retry).
+ *
+ * Sentinel error type — the loop unwraps `ValidationFailure` instances
+ * to extract `message` / `path` / `rawOutput` for the
+ * `agentfootprint.agent.output_schema_validation_failed` event payload.
+ *
+ * MUST-FIX #1 from the v2.13 7-panel review: the hook fires ONLY when
+ * `response.toolCalls.length === 0` (final-answer turn). Tool-call
+ * turns aren't terminal output and validation would be premature.
+ * Caller is responsible for the guard; this helper just runs whatever
+ * the caller passes.
+ */
+export type OutputSchemaValidator = (response: LLMResponse) => void;
+/**
+ * Sentinel error class thrown by an `OutputSchemaValidator` to signal
+ * a validation failure. Distinct subclass so the reliability loop can
+ * `instanceof` check and route to the schema-fail branch instead of
+ * treating it as a generic provider error.
+ */
+export declare class ValidationFailure extends Error {
+    readonly stage: 'json-parse' | 'schema-validate';
+    readonly path?: string;
+    readonly rawOutput?: string;
+    constructor(opts: {
+        message: string;
+        stage: 'json-parse' | 'schema-validate';
+        path?: string;
+        rawOutput?: string;
+    });
+}
+/** Sentinel kind written to scope on a mid-stream failure that the
+ *  rules wanted to retry. Surfaces in `ReliabilityFailFastError.kind`. */
+export declare const MID_STREAM_KIND = "mid-stream-not-retryable";
+/**
+ * Run the reliability retry loop. Returns the committed `LLMResponse`
+ * on success; calls `scope.$break(reason)` and returns `undefined` on
+ * fail-fast (caller short-circuits when undefined is returned).
+ */
+export declare function executeWithReliability(scope: TypedScope<AgentState>, request: LLMRequest, config: ReliabilityConfig, defaultProvider: LLMProvider, defaultProviderName: string, defaultModel: string, callFn: LLMCallFn, 
+/** v2.13 — optional output-schema validator. When supplied, the loop
+ *  invokes it after every successful LLM call WHERE
+ *  `response.toolCalls.length === 0` (final-answer turn). Throws of
+ *  type `ValidationFailure` signal schema-fail and route via
+ *  PostDecide rules. Caller is responsible for guarding tool-call
+ *  turns; this helper assumes the validator is already gated. */
+postValidate?: OutputSchemaValidator): Promise<LLMResponse | undefined>;
+/**
+ * v2.13 — stuck-loop detection helper. Returns `true` when the last
+ * `n` validation errors are IDENTICAL — a hallucinating model that
+ * keeps making the same mistake won't make progress on more retries.
+ *
+ * Default rule template — spread into your `postDecide` to short-circuit
+ * stuck loops:
+ *
+ * ```ts
+ * postDecide: [
+ *   defaultStuckLoopRule,            // ← spread first; fail-fast on stuck
+ *   { when: (s) => s.validationError !== undefined && s.attempt < 3, then: 'retry', ... },
+ * ]
+ * ```
+ *
+ * @param scope The reliability scope view passed to rule predicates.
+ * @param n How many trailing identical errors trigger detection. Default 2.
+ */
+export declare function lastNValidationErrorsMatch(scope: ReliabilityScope, n?: number): boolean;
+/**
+ * v2.13 — drop-in PostDecide rule that fail-fasts when the last 2
+ * validation errors match. Spread into `postDecide` BEFORE retry
+ * rules so it short-circuits before another wasted attempt.
+ *
+ * The matched-rule kind `'schema-stuck-loop'` surfaces on
+ * `ReliabilityFailFastError.kind` for caller branching.
+ */
+export declare const defaultStuckLoopRule: ReliabilityRule;

package/dist/esm/core/agent/stages/route.d.ts

@@ -0,0 +1,18 @@
+/**
+ * route — decider that branches the ReAct loop into 'tool-calls' or 'final'.
+ *
+ * Runs after CallLLM. If the LLM returned tool calls AND we haven't hit
+ * `maxIterations`, route to the tool execution branch (which loops back
+ * to PromptBuilder). Otherwise route to the final-branch subflow which
+ * persists memory writes and breaks the loop.
+ *
+ * Emits `agentfootprint.agent.route_decided` with the chosen branch +
+ * a human-readable rationale (visible in narrative + observability).
+ *
+ * Pure function — no closure over Agent class state. Imported and
+ * passed directly to `addDeciderFunction(...)` in buildAgentChart.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { AgentState } from '../types.js';
+export type RouteBranch = 'tool-calls' | 'final';
+export declare const routeDeciderStage: (scope: TypedScope<AgentState>) => RouteBranch;

package/dist/esm/core/agent/stages/seed.d.ts

@@ -0,0 +1,53 @@
+/**
+ * seed — initial stage of the agent's chart. Initializes every mutable
+ * field of `AgentState` from the consumer's input.
+ *
+ * Runs once per `agent.run({ input })`. The chart is built once at
+ * Agent construction, so seed has access to BOTH:
+ *
+ *   • CHART-BUILD-TIME constants (maxIterations, cachingDisabled,
+ *     toolSchemas) — passed as direct values to the factory.
+ *   • PER-RUN MUTABLE state (pendingResumeHistory from
+ *     resumeOnError(), currentRunContext.runId set per run) —
+ *     passed as accessor closures over the Agent instance, since
+ *     these change between consecutive `agent.run()` invocations.
+ *
+ * The accessor pattern keeps `seed` decoupled from the Agent class
+ * while preserving the per-run mutability the resume + identity
+ * features need.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { LLMMessage, LLMToolSchema } from '../../../adapters/types.js';
+import type { AgentState } from '../types.js';
+export interface SeedStageDeps {
+    /** Resolved `clampIterations(opts.maxIterations ?? 10)`. Frozen at
+     *  chart-build time. */
+    readonly maxIterations: number;
+    /** Resolved cache kill switch from `Agent.create({ caching: 'off' })`. */
+    readonly cachingDisabled: boolean;
+    /** Static tool schemas resolved at chart-build time. The tools slot
+     *  subflow can OVERRIDE this per-iteration via `dynamicToolSchemas`,
+     *  but seed populates the initial value so iter 1 has it. */
+    readonly toolSchemas: readonly LLMToolSchema[];
+    /**
+     * Read-AND-CLEAR accessor for the resume side-channel. Called exactly
+     * once per `agent.run()` from inside seed. If `resumeOnError(checkpoint)`
+     * was invoked before `run()`, this returns the checkpointed history
+     * and clears the field so the NEXT `run()` starts fresh. Returns
+     * `undefined` for the normal (non-resume) path.
+     */
+    readonly consumePendingResumeHistory: () => readonly LLMMessage[] | undefined;
+    /**
+     * Accessor for the current run's id, used to default the memory
+     * identity when consumer didn't pass `agent.run({ identity })`. Set
+     * by RunnerBase on every `agent.run()` call before the chart starts.
+     * Returns `undefined` only in degenerate (test) cases.
+     */
+    readonly getCurrentRunId: () => string | undefined;
+}
+/**
+ * Build the seed stage function for an Agent instance. Captures both
+ * the chart-build-time constants and the per-run mutable accessors
+ * via the deps object.
+ */
+export declare function buildSeedStage(deps: SeedStageDeps): (scope: TypedScope<AgentState>) => void;

package/dist/esm/core/agent/stages/toolCalls.d.ts

@@ -0,0 +1,76 @@
+/**
+ * toolCalls — pausable handler for executing the LLM-requested tool
+ * calls in the agent's ReAct loop.
+ *
+ *   • `execute` iterates `scope.llmLatestToolCalls`, dispatches each
+ *     tool, appends results to scope.history, and increments
+ *     `scope.iteration`. If a tool throws `PauseRequest` (via
+ *     `pauseHere()`), commits partial state and returns the pause
+ *     payload so footprintjs captures a checkpoint.
+ *   • `resume` runs after the consumer supplies the human's answer.
+ *     Treats that answer as the paused tool's result, appends to
+ *     history, then continues the ReAct iteration loop.
+ *
+ * Dispatch resolution order:
+ *   1. Static registry built at chart-build time (registryByName).
+ *   2. External `ToolProvider.list(ctx).find(...)` if a `.toolProvider()`
+ *      was wired and the tool isn't in the static registry.
+ *
+ * Permission gate (when `permissionChecker` is configured) runs BEFORE
+ * `tool.execute`. Deny → tool not executed; result is a synthetic
+ * denial string. Allow / gate_open → execution proceeds.
+ *
+ * `read_skill` is the auto-attached activation tool — when the LLM
+ * calls it with a valid Skill id, the next InjectionEngine pass
+ * activates that Skill (lifetime: turn).
+ */
+import type { PausableHandler, TypedScope } from 'footprintjs';
+import type { PermissionChecker } from '../../../adapters/types.js';
+import type { ToolProvider } from '../../../tool-providers/types.js';
+import type { CredentialProvider } from '../../../identity/types.js';
+import type { ProviderToolCache } from '../../slots/buildToolsSlot.js';
+import type { Tool } from '../../tools.js';
+import { type ToolArgValidationMode } from '../toolArgsValidation.js';
+import type { AgentState } from '../types.js';
+export interface ToolCallsHandlerDeps {
+    /** Map from tool name → Tool instance, built from the augmented
+     *  registry (static .tool() entries + read_skill if any skills +
+     *  shared skill tools). The dispatch primary lookup. */
+    readonly registryByName: ReadonlyMap<string, Tool>;
+    /** Optional external `.toolProvider()` for per-iteration dynamic
+     *  tools (skill-scoped, multi-tenant, etc.). Consulted only when
+     *  the static registry doesn't have the tool. */
+    readonly externalToolProvider?: ToolProvider;
+    /**
+     * Cache populated by `buildToolsSlot` after each `provider.list(ctx)`
+     * call this iteration. Read here to avoid a second `list()` call
+     * (vital for async / network-backed providers). Same closure shared
+     * within one chart build.
+     */
+    readonly providerToolCache?: ProviderToolCache;
+    /** Optional permission gate. When present, every tool dispatch
+     *  awaits `check({capability: 'tool_call', ...})` BEFORE executing.
+     *  Throwing checkers are treated as deny-by-default. */
+    readonly permissionChecker?: PermissionChecker;
+    /** Optional credential provider (declare-and-push). When present, a tool's
+     *  declared `needs` is resolved BEFORE execute and injected as `ctx.credential`;
+     *  `ctx.credentials` exposes it for the pull escape hatch. */
+    readonly credentialProvider?: CredentialProvider;
+    /** Tool-args validation mode (#9). Default 'enforce': LLM-produced args
+     *  are checked against the tool's `inputSchema` BEFORE dispatch; a
+     *  mismatch rejects the call with a model-visible retry message.
+     *  'warn' emits the event but executes anyway; 'off' skips validation. */
+    readonly toolArgValidation?: ToolArgValidationMode;
+    /**
+     * Skill-graph read_skill GATE (`graph.reachableSkills`). When present, a
+     * `read_skill('id')` whose `id` is not reachable from the current cursor is
+     * REJECTED — the model gets a synthetic re-prompt naming the allowed ids and
+     * the cursor/activations stay unchanged, so it can't leave the graph mid-run.
+     * Undefined → no gate (plain read_skill agents append as before).
+     */
+    readonly allowedSkillIds?: (currentSkillId?: string) => readonly string[];
+}
+/**
+ * Build the pausable tool-call handler for the agent's chart.
+ */
+export declare function buildToolCallsHandler(deps: ToolCallsHandlerDeps): PausableHandler<TypedScope<AgentState>>;

package/dist/esm/core/agent/toolArgsValidation.d.ts

@@ -0,0 +1,62 @@
+/**
+ * toolArgsValidation — validate LLM-produced tool args against the tool's
+ * declared `inputSchema` BEFORE dispatch (backlog #9).
+ *
+ * Pattern: pure function module — no state, no events; the toolCalls stage
+ *          owns when to call it and what to do with the verdict.
+ * Role:    The model writes tool args as free-form JSON; nothing guaranteed
+ *          they match the schema the tool advertised. Dispatching garbage
+ *          surfaced as deep tool stack traces (or worse, silent misbehavior).
+ *          Validating at the boundary turns a malformed call into a
+ *          MODEL-VISIBLE structured tool result, so the LLM corrects its
+ *          args and retries on the next ReAct iteration.
+ *
+ * ── Honest-subset contract ────────────────────────────────────────────────
+ * This is NOT a full JSON Schema implementation. It enforces the core that
+ * tool schemas in the wild actually use, and IGNORES everything else
+ * (permissive on unknown keywords — a schema using `pattern`/`oneOf`/`$ref`
+ * still validates the supported core, never false-rejects on the rest):
+ *
+ *   ENFORCED: `type` (object/array/string/number/integer/boolean/null,
+ *             union arrays), `required`, `properties` (recursive),
+ *             `items` (single-schema, recursive), `enum` (primitives),
+ *             `additionalProperties: false` ONLY when explicitly set.
+ *   IGNORED:  format, pattern, min/max*, oneOf/anyOf/allOf/not, $ref,
+ *             const, dependencies, …
+ *
+ * ── Security: never echo VALUES ───────────────────────────────────────────
+ * Issues name the PATH, the EXPECTED shape, and the TYPE of what arrived —
+ * never the supplied value itself. The message flows into history (LLM),
+ * the emit channel, and traces; arg values can carry PII or injection
+ * payloads. Enum expectations echo SCHEMA values only (already LLM-visible
+ * in the tools block).
+ */
+/** When to enforce: 'enforce' rejects before dispatch (default), 'warn'
+ *  emits the event but executes anyway, 'off' skips validation entirely. */
+export type ToolArgValidationMode = 'enforce' | 'warn' | 'off';
+/** One schema violation. `got` is a TYPE NAME, never a value. */
+export interface ToolArgIssue {
+    /** Dot/bracket path from the args root, '' for the root itself. */
+    readonly path: string;
+    readonly expected: string;
+    readonly got: string;
+}
+export interface ToolArgValidationResult {
+    readonly ok: boolean;
+    readonly issues: readonly ToolArgIssue[];
+}
+/**
+ * Validate tool-call args against the tool's `inputSchema`.
+ *
+ * Total function: a malformed/exotic SCHEMA never throws — anything outside
+ * the honest subset is ignored, so the worst a bad schema can do is
+ * under-validate (never block a legitimate call).
+ */
+export declare function validateToolArgs(args: unknown, inputSchema: Readonly<Record<string, unknown>> | undefined): ToolArgValidationResult;
+/**
+ * Render the MODEL-VISIBLE tool result for a rejected call. Names paths,
+ * expectations, and received TYPES — never received values. The model
+ * already has the full schema in its tools block; pointing at the issues
+ * is what makes the retry converge.
+ */
+export declare function formatToolArgIssues(toolName: string, issues: readonly ToolArgIssue[]): string;