agentfootprint 2.11.1 → 2.11.2

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

@@ -0,0 +1,54 @@
+/**
+ * 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;
+//# sourceMappingURL=seed.d.ts.map

package/dist/types/core/agent/stages/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE5E,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B;4BACwB;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;iEAE6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,2BAA2B,EAAE,MAAM,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;IAC9E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CAmE3F"}

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

@@ -0,0 +1,50 @@
+/**
+ * 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 { Tool } from '../../tools.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;
+    /** 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;
+}
+/**
+ * Build the pausable tool-call handler for the agent's chart.
+ */
+export declare function buildToolCallsHandler(deps: ToolCallsHandlerDeps): PausableHandler<TypedScope<AgentState>>;
+//# sourceMappingURL=toolCalls.d.ts.map

package/dist/types/core/agent/stages/toolCalls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolCalls.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/toolCalls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGhF,OAAO,KAAK,EAAuB,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAE1F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,oBAAoB;IACnC;;4DAEwD;IACxD,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnD;;qDAEiD;IACjD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,YAAY,CAAC;IAC7C;;4DAEwD;IACxD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,GACzB,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CA2NzC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.11.1",
+  "version": "2.11.2",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",