@strands-agents/sdk 1.3.0 → 1.5.0

package/dist/src/vended-interventions/steering/handlers/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/handlers/llm.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAA2B,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,mCAAmC,CAAA;AACnH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAA;AAEpG,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAM9C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,mBAAmB,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,YAAY,EAAE,CAAA;AAoG1G;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,YAAY,EAAE,YAAY,CAAA;IAE1B,2EAA2E;IAC3E,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb,sFAAsF;IACtF,aAAa,CAAC,EAAE,aAAa,CAAA;IAE7B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,uBAAuB,EAAE,CAAA;IAE5C;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAcD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,SAAkB,IAAI,EAAE,MAAM,CAAA;IAE9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAe;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAc;gBAEhC,MAAM,EAAE,wBAAwB;IAW7B,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;YAkB/E,OAAO;CAgBtB"}

package/dist/src/vended-interventions/steering/handlers/llm.js

@@ -0,0 +1,177 @@
+/**
+ * LLM-based steering handler that uses an LLM to provide contextual guidance.
+ */
+import { z } from 'zod';
+import { Agent } from '../../../agent/agent.js';
+import { confirm, guide, proceed } from '../../../interventions/actions.js';
+import { CachePointBlock, TextBlock } from '../../../types/messages.js';
+import { ToolLedgerProvider } from '../providers/tool-ledger.js';
+import { SteeringHandler } from './handler.js';
+/**
+ * Default prompt builder. Returns content blocks with a cache point
+ * between static instructions and dynamic context/event data.
+ *
+ * See: https://github.com/strands-agents/agent-sop
+ */
+function defaultPromptBuilder(context, toolUse) {
+    const contextStr = context.length > 0 ? JSON.stringify(context, null, 2) : 'No context available';
+    const actionType = toolUse ? 'tool call' : 'action';
+    const actionTypeTitle = toolUse ? 'Tool Call' : 'Action';
+    const eventDescription = toolUse
+        ? `Tool: ${toolUse.name}\nArguments: ${JSON.stringify(toolUse.input, null, 2)}`
+        : 'General evaluation';
+    const hasLedger = context.some((c) => c.type === 'toolLedger');
+    const ledgerExplanation = hasLedger
+        ? `
+
+### Understanding Ledger Tool States
+
+If the context includes a ledger with tool_calls, the "status" field indicates:
+
+- **"pending"**: The tool is CURRENTLY being evaluated by you (the steering agent).
+This is NOT a duplicate call — it's the tool you're deciding whether to approve.
+The tool has NOT started executing yet.
+- **"success"**: The tool completed successfully in a previous turn
+- **"error"**: The tool failed or was cancelled in a previous turn
+
+**IMPORTANT**: When you see a tool with status="pending" that matches the tool you're evaluating,
+that IS the current tool being evaluated. It is NOT already executing or a duplicate.`
+        : '';
+    // Static framing (cached): role, constraints, decision criteria, ledger semantics.
+    const instructions = `# Steering Evaluation
+
+## Overview
+
+You are a STEERING AGENT that evaluates a ${actionType} that ANOTHER AGENT is attempting to make.
+Your job is to provide contextual guidance to help the other agent navigate workflows effectively.
+You act as a safety net that can intervene when patterns in the context data suggest the agent
+should try a different approach or get human input.
+
+**YOUR ROLE:**
+- Analyze context data for concerning patterns (repeated failures, inappropriate timing, etc.)
+- Provide just-in-time guidance when the agent is going down an ineffective path
+- Allow normal operations to proceed when context shows no issues
+
+**CRITICAL CONSTRAINTS:**
+- Base decisions ONLY on the context data provided
+- Do NOT use external knowledge about domains, URLs, or tool purposes
+- Do NOT make assumptions about what tools "should" or "shouldn't" do
+- Focus ONLY on patterns in the context data${ledgerExplanation}
+
+## Steps
+
+### 1. Analyze the ${actionTypeTitle}
+
+Review ONLY the context data. Look for patterns in the data that indicate:
+
+- Previous failures or successes with this tool
+- Frequency of attempts
+- Any relevant tracking information
+
+**Constraints:**
+- You MUST base analysis ONLY on the provided context data
+- You MUST NOT use external knowledge about tool purposes or domains
+- You SHOULD identify patterns in the context data
+- You MAY reference relevant context data to inform your decision
+
+### 2. Make Steering Decision
+
+**Constraints:**
+- You MUST respond with exactly one of: "proceed", "guide", or "confirm"
+- You MUST base the decision ONLY on context data patterns
+- Your reason will be shown to the AGENT as guidance
+
+**Decision Options:**
+- "proceed" if context data shows no concerning patterns
+- "guide" if context data shows patterns requiring intervention
+- "confirm" if context data shows patterns requiring human input`;
+    // Dynamic block (uncached): per-call context and event payload.
+    const dynamic = `## Context
+
+${contextStr}
+
+## Event to Evaluate
+
+${eventDescription}`;
+    return [new TextBlock(instructions), new CachePointBlock({ cacheType: 'default' }), new TextBlock(dynamic)];
+}
+/** Schema returned by the steering LLM. */
+const STEERING_DECISION = z.object({
+    type: z
+        .enum(['proceed', 'guide', 'confirm'])
+        .describe("Steering decision: 'proceed' to continue, 'guide' to provide feedback, 'confirm' to pause for human approval"),
+    reason: z.string().describe('Clear explanation of the steering decision and any guidance provided'),
+});
+/**
+ * Steering handler that uses an LLM to provide contextual guidance.
+ *
+ * Uses natural language prompts to evaluate tool calls and produce an
+ * intervention action.
+ *
+ * Only `beforeToolCall` is implemented — model-output steering is not
+ * delegated to the LLM. Subclass and override `afterModelCall` (which
+ * carries the narrowed `Proceed | Guide` return) to add LLM-driven
+ * evaluation of model responses.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { LLMSteeringHandler } from '@strands-agents/sdk/vended-interventions/steering'
+ *
+ * const handler = new LLMSteeringHandler({
+ *   systemPrompt: `You ensure emails maintain a cheerful, positive tone.`,
+ * })
+ *
+ * const agent = new Agent({ tools: [sendEmail], interventions: [handler] })
+ * ```
+ */
+export class LLMSteeringHandler extends SteeringHandler {
+    name;
+    _promptBuilder;
+    _configuredModel;
+    _agentModel;
+    _systemPrompt;
+    constructor(config) {
+        const contextProviders = config.contextProviders === undefined ? [new ToolLedgerProvider()] : config.contextProviders;
+        super({ contextProviders });
+        this.name = config.name ?? 'strands:llm-steering-handler';
+        this._promptBuilder = config.promptBuilder ?? defaultPromptBuilder;
+        this._configuredModel = config.model;
+        this._systemPrompt = config.systemPrompt;
+    }
+    async observeAgent(agent) {
+        this._agentModel = agent.model;
+        await super.observeAgent(agent);
+    }
+    async beforeToolCall(event) {
+        const context = this.getSteeringContext();
+        const prompt = this._promptBuilder(context, event.toolUse);
+        const decision = await this._invoke(prompt);
+        switch (decision.type) {
+            case 'proceed':
+                return proceed({ reason: decision.reason });
+            case 'guide':
+                return guide(decision.reason);
+            case 'confirm':
+                return confirm(decision.reason, { reason: decision.reason });
+        }
+    }
+    // Constructs a fresh inner agent per call so the handler has no shared
+    // mutable state between invocations — this keeps it safe to attach to
+    // multiple parent agents (whose tool calls may evaluate concurrently).
+    async _invoke(prompt) {
+        const model = this._configuredModel ?? this._agentModel;
+        if (!model) {
+            throw new Error('LLMSteeringHandler has no model — pass `model` in config, or attach the handler to an agent before invoking it.');
+        }
+        const inner = new Agent({
+            model,
+            systemPrompt: this._systemPrompt,
+            structuredOutputSchema: STEERING_DECISION,
+            printer: false,
+        });
+        const result = await inner.invoke(prompt);
+        return STEERING_DECISION.parse(result.structuredOutput);
+    }
+}
+//# sourceMappingURL=llm.js.map

package/dist/src/vended-interventions/steering/handlers/llm.js.map

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

package/dist/src/vended-interventions/steering/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Steering system for Strands agents.
+ *
+ * Provides contextual guidance for agents through modular prompting.
+ * Instead of front-loading all instructions, steering handlers provide
+ * just-in-time feedback based on context data from registered providers.
+ *
+ * Steering handlers are {@link InterventionHandler}s — register them on the
+ * agent via the `interventions:` option, not `plugins:`.
+ *
+ * Core components:
+ * - SteeringHandler: base class for guidance logic
+ * - SteeringContextProvider: interface for context data providers
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { LLMSteeringHandler } from '@strands-agents/sdk/vended-interventions/steering'
+ *
+ * const handler = new LLMSteeringHandler({
+ *   systemPrompt: '...',
+ *   model: new BedrockModel(),
+ * })
+ * const agent = new Agent({ tools: [...], interventions: [handler] })
+ * ```
+ */
+export type { SteeringContextData, SteeringContextProvider } from './providers/context-provider.js';
+export { SteeringHandler, type SteeringHandlerConfig } from './handlers/handler.js';
+export { ToolLedgerProvider, type ToolLedgerProviderConfig } from './providers/tool-ledger.js';
+export { LLMSteeringHandler, type LLMSteeringHandlerConfig, type PromptBuilder } from './handlers/llm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/vended-interventions/steering/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/vended-interventions/steering/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,YAAY,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AACnG,OAAO,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAGnF,OAAO,EAAE,kBAAkB,EAAE,KAAK,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAG9F,OAAO,EAAE,kBAAkB,EAAE,KAAK,wBAAwB,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/src/vended-interventions/steering/index.js

@@ -0,0 +1,32 @@
+/**
+ * Steering system for Strands agents.
+ *
+ * Provides contextual guidance for agents through modular prompting.
+ * Instead of front-loading all instructions, steering handlers provide
+ * just-in-time feedback based on context data from registered providers.
+ *
+ * Steering handlers are {@link InterventionHandler}s — register them on the
+ * agent via the `interventions:` option, not `plugins:`.
+ *
+ * Core components:
+ * - SteeringHandler: base class for guidance logic
+ * - SteeringContextProvider: interface for context data providers
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { LLMSteeringHandler } from '@strands-agents/sdk/vended-interventions/steering'
+ *
+ * const handler = new LLMSteeringHandler({
+ *   systemPrompt: '...',
+ *   model: new BedrockModel(),
+ * })
+ * const agent = new Agent({ tools: [...], interventions: [handler] })
+ * ```
+ */
+export { SteeringHandler } from './handlers/handler.js';
+// Context providers
+export { ToolLedgerProvider } from './providers/tool-ledger.js';
+// Handler implementations
+export { LLMSteeringHandler } from './handlers/llm.js';
+//# sourceMappingURL=index.js.map

package/dist/src/vended-interventions/steering/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/vended-interventions/steering/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,eAAe,EAA8B,MAAM,uBAAuB,CAAA;AAEnF,oBAAoB;AACpB,OAAO,EAAE,kBAAkB,EAAiC,MAAM,4BAA4B,CAAA;AAE9F,0BAA0B;AAC1B,OAAO,EAAE,kBAAkB,EAAqD,MAAM,mBAAmB,CAAA"}

package/dist/src/vended-interventions/steering/providers/context-provider.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Steering context provider interface.
+ *
+ * Providers track agent activity and supply context data to steering handlers
+ * for evaluation decisions.
+ */
+import type { LocalAgent } from '../../../types/agent.js';
+import type { LifecycleObserver } from '../../../types/lifecycle-observer.js';
+import type { JSONValue } from '../../../types/json.js';
+/**
+ * Context data returned by a SteeringContextProvider.
+ * The type field identifies which provider produced the data.
+ */
+export interface SteeringContextData {
+    /** Discriminator identifying the context provider. */
+    readonly type: string;
+    /** Additional context fields. */
+    [key: string]: JSONValue;
+}
+/**
+ * A passive observer that accumulates data from agent lifecycle events.
+ *
+ * Providers self-register hook callbacks via {@link LifecycleObserver.observeAgent},
+ * which the owning {@link SteeringHandler} invokes once at registration time.
+ *
+ * Providers expose accumulated state through the `context` getter, which the
+ * handler reads when making steering decisions.
+ *
+ * @example
+ * ```typescript
+ * class CostTracker implements SteeringContextProvider {
+ *   readonly name = 'costTracker'
+ *   private _toolCalls = 0
+ *
+ *   observeAgent(agent: LocalAgent): void {
+ *     agent.addHook(AfterToolCallEvent, () => {
+ *       this._toolCalls += 1
+ *     })
+ *   }
+ *
+ *   get context(): SteeringContextData {
+ *     return { type: 'costTracker', toolCalls: this._toolCalls }
+ *   }
+ * }
+ * ```
+ */
+export interface SteeringContextProvider extends LifecycleObserver {
+    /** Identifier for this provider instance. */
+    readonly name: string;
+    /** Subscribe to hooks on the owning agent. Required for providers. */
+    observeAgent(agent: LocalAgent): void | Promise<void>;
+    /** Return the current context snapshot for steering evaluation. */
+    get context(): SteeringContextData;
+}
+//# sourceMappingURL=context-provider.d.ts.map

package/dist/src/vended-interventions/steering/providers/context-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-provider.d.ts","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/providers/context-provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAEvD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iCAAiC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,sEAAsE;IACtE,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErD,mEAAmE;IACnE,IAAI,OAAO,IAAI,mBAAmB,CAAA;CACnC"}

package/dist/src/vended-interventions/steering/providers/context-provider.js

@@ -0,0 +1,8 @@
+/**
+ * Steering context provider interface.
+ *
+ * Providers track agent activity and supply context data to steering handlers
+ * for evaluation decisions.
+ */
+export {};
+//# sourceMappingURL=context-provider.js.map

package/dist/src/vended-interventions/steering/providers/context-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-provider.js","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/providers/context-provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/src/vended-interventions/steering/providers/tool-ledger.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Ledger context provider for comprehensive agent activity tracking.
+ *
+ * Tracks tool call history with inputs, outputs, timing, and success/failure status.
+ * This audit trail enables steering handlers to make informed guidance decisions
+ * based on agent behavior patterns and history.
+ */
+import type { LocalAgent } from '../../../types/agent.js';
+import type { SteeringContextData, SteeringContextProvider } from './context-provider.js';
+/**
+ * Configuration for {@link ToolLedgerProvider}.
+ */
+export interface ToolLedgerProviderConfig {
+    /** Maximum number of tool calls to retain. Older entries are dropped. Defaults to 100. */
+    maxEntries?: number;
+    /** Identifier for this provider instance. Defaults to `'strands:steering:toolLedger'`. */
+    name?: string;
+}
+/**
+ * Context provider that tracks tool call history within a single invocation.
+ *
+ * Records every tool invocation with inputs, execution time, and success/failure status.
+ * The ledger is available to steering handlers for pattern detection
+ * (e.g., repeated failures, excessive retries).
+ *
+ * When the ledger exceeds maxEntries, the oldest entries are dropped.
+ *
+ * @example
+ * ```typescript
+ * const handler = new LLMSteeringHandler({
+ *   systemPrompt: '...',
+ *   contextProviders: [new ToolLedgerProvider()],
+ * })
+ * ```
+ */
+export declare class ToolLedgerProvider implements SteeringContextProvider {
+    readonly name: string;
+    private readonly _maxEntries;
+    private readonly _toolCalls;
+    constructor(config?: ToolLedgerProviderConfig);
+    observeAgent(agent: LocalAgent): void;
+    private _onBeforeToolCall;
+    private _onAfterToolCall;
+    /**
+     * Return the current ledger snapshot.
+     */
+    get context(): SteeringContextData;
+}
+//# sourceMappingURL=tool-ledger.d.ts.map

package/dist/src/vended-interventions/steering/providers/tool-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-ledger.d.ts","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/providers/tool-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAGzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAwBzF;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAmB,YAAW,uBAAuB;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;gBAEtC,MAAM,CAAC,EAAE,wBAAwB;IAO7C,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAKrC,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,gBAAgB;IAcxB;;OAEG;IACH,IAAI,OAAO,IAAI,mBAAmB,CAKjC;CACF"}

package/dist/src/vended-interventions/steering/providers/tool-ledger.js

@@ -0,0 +1,75 @@
+/**
+ * Ledger context provider for comprehensive agent activity tracking.
+ *
+ * Tracks tool call history with inputs, outputs, timing, and success/failure status.
+ * This audit trail enables steering handlers to make informed guidance decisions
+ * based on agent behavior patterns and history.
+ */
+import { AfterToolCallEvent, BeforeToolCallEvent } from '../../../hooks/events.js';
+/**
+ * Context provider that tracks tool call history within a single invocation.
+ *
+ * Records every tool invocation with inputs, execution time, and success/failure status.
+ * The ledger is available to steering handlers for pattern detection
+ * (e.g., repeated failures, excessive retries).
+ *
+ * When the ledger exceeds maxEntries, the oldest entries are dropped.
+ *
+ * @example
+ * ```typescript
+ * const handler = new LLMSteeringHandler({
+ *   systemPrompt: '...',
+ *   contextProviders: [new ToolLedgerProvider()],
+ * })
+ * ```
+ */
+export class ToolLedgerProvider {
+    name;
+    _maxEntries = 100;
+    _toolCalls = [];
+    constructor(config) {
+        this.name = config?.name ?? 'strands:steering:toolLedger';
+        if (config?.maxEntries !== undefined) {
+            this._maxEntries = config.maxEntries;
+        }
+    }
+    observeAgent(agent) {
+        agent.addHook(BeforeToolCallEvent, (event) => this._onBeforeToolCall(event));
+        agent.addHook(AfterToolCallEvent, (event) => this._onAfterToolCall(event));
+    }
+    _onBeforeToolCall(event) {
+        this._toolCalls.push({
+            startTime: new Date().toISOString(),
+            id: event.toolUse.toolUseId,
+            name: event.toolUse.name,
+            args: event.toolUse.input,
+            status: 'pending',
+        });
+        if (this._toolCalls.length > this._maxEntries) {
+            this._toolCalls.splice(0, this._toolCalls.length - this._maxEntries);
+        }
+    }
+    _onAfterToolCall(event) {
+        const toolUseId = event.toolUse.toolUseId;
+        for (let i = this._toolCalls.length - 1; i >= 0; i--) {
+            const call = this._toolCalls[i];
+            if (call?.id === toolUseId) {
+                call.endTime = new Date().toISOString();
+                call.status = event.result.status;
+                call.result = event.result.content.map((block) => block.toJSON());
+                call.error = event.error ? event.error.message : null;
+                break;
+            }
+        }
+    }
+    /**
+     * Return the current ledger snapshot.
+     */
+    get context() {
+        return {
+            type: 'toolLedger',
+            calls: this._toolCalls,
+        };
+    }
+}
+//# sourceMappingURL=tool-ledger.js.map

package/dist/src/vended-interventions/steering/providers/tool-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-ledger.js","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/providers/tool-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAsClF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,kBAAkB;IACpB,IAAI,CAAQ;IACJ,WAAW,GAAW,GAAG,CAAA;IACzB,UAAU,GAAqB,EAAE,CAAA;IAElD,YAAY,MAAiC;QAC3C,IAAI,CAAC,IAAI,GAAG,MAAM,EAAE,IAAI,IAAI,6BAA6B,CAAA;QACzD,IAAI,MAAM,EAAE,UAAU,KAAK,SAAS,EAAE,CAAC;YACrC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,CAAA;QACtC,CAAC;IACH,CAAC;IAED,YAAY,CAAC,KAAiB;QAC5B,KAAK,CAAC,OAAO,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAA;QAC5E,KAAK,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAA;IAC5E,CAAC;IAEO,iBAAiB,CAAC,KAA0B;QAClD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,SAAS;YAC3B,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI;YACxB,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK;YACzB,MAAM,EAAE,SAAS;SAClB,CAAC,CAAA;QACF,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,CAAA;QACtE,CAAC;IACH,CAAC;IAEO,gBAAgB,CAAC,KAAyB;QAChD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAA;QACzC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACrD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;YAC/B,IAAI,IAAI,EAAE,EAAE,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;gBACvC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAA;gBACjC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAc,CAAA;gBAC9E,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAA;gBACrD,MAAK;YACP,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,OAAO;QACT,OAAO;YACL,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,IAAI,CAAC,UAAkC;SAC/C,CAAA;IACH,CAAC;CACF"}

package/dist/src/vended-memory-stores/bedrock-knowledge-base/__tests__/bedrock-knowledge-base-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bedrock-knowledge-base-store.test.d.ts.map

package/dist/src/vended-memory-stores/bedrock-knowledge-base/__tests__/bedrock-knowledge-base-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bedrock-knowledge-base-store.test.d.ts","sourceRoot":"","sources":["../../../../../src/vended-memory-stores/bedrock-knowledge-base/__tests__/bedrock-knowledge-base-store.test.ts"],"names":[],"mappings":""}