@strands-agents/sdk 1.15.0 → 1.17.0

package/dist/src/background-tasks/in-process/manager.d.ts

@@ -0,0 +1,41 @@
+import type { Agent } from '../../agent/agent.js';
+import type { ToolUseData } from '../../hooks/events.js';
+import type { ExecuteToolContext } from '../../middleware/index.js';
+import type { InvocationState } from '../../types/agent.js';
+import { type InterruptResponse } from '../../types/interrupt.js';
+import { type ToolResultBlock } from '../../types/messages.js';
+import type { Tool, ToolContext } from '../../tools/tool.js';
+import type { BackgroundTaskManager } from '../manager.js';
+import { type BackgroundTask } from '../types.js';
+/** Configures in-process background task execution. @internal */
+export interface InProcessTaskManagerConfig {
+    /** Maximum number of physically executing background tasks. Defaults to `4`. */
+    readonly maxConcurrency?: number;
+    /** Per-execution timeout in milliseconds. Defaults to `Infinity`. */
+    readonly timeout?: number;
+    readonly onTaskUpdated?: (task: BackgroundTask) => void;
+}
+/** Executes approved tool calls as in-process background tasks. @internal */
+export declare class InProcessTaskManager implements BackgroundTaskManager {
+    private readonly _agent;
+    private readonly _executeTool;
+    private readonly _engine;
+    private readonly _executions;
+    private readonly _taskIdBySubmission;
+    private readonly _taskWaiters;
+    constructor(agent: Agent, executeTool: (tool: Tool, context: ToolContext, middlewareInterrupt: ExecuteToolContext['interrupt']) => Promise<ToolResultBlock>, config?: InProcessTaskManagerConfig);
+    submit(toolUse: Readonly<ToolUseData>, invocationState: InvocationState, passId: string, tool: Tool): Promise<BackgroundTask>;
+    get(taskId: string): Promise<BackgroundTask | undefined>;
+    list(): Promise<readonly BackgroundTask[]>;
+    hasTasks(): boolean;
+    cancel(taskId: string): Promise<BackgroundTask>;
+    wait(taskId: string): Promise<BackgroundTask>;
+    waitForIdle(options?: {
+        readonly timeout?: number;
+    }): Promise<void>;
+    resume(taskId: string, responses: readonly InterruptResponse[]): Promise<BackgroundTask>;
+    remove(taskIds: readonly string[]): Promise<void>;
+    private _executeToolTask;
+    private _notifyTaskWaiters;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/src/background-tasks/in-process/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../src/background-tasks/in-process/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAkD,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAEjH,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAS5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAA;AAQvE,iEAAiE;AACjE,MAAM,WAAW,0BAA0B;IACzC,gFAAgF;IAChF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAA;CACxD;AAED,6EAA6E;AAC7E,qBAAa,oBAAqB,YAAW,qBAAqB;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAO;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAA;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA4B;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyD;gBAGpF,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,CACX,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,WAAW,EACpB,mBAAmB,EAAE,kBAAkB,CAAC,WAAW,CAAC,KACjD,OAAO,CAAC,eAAe,CAAC,EAC7B,MAAM,GAAE,0BAA+B;IAqBnC,MAAM,CACV,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC9B,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,cAAc,CAAC;IAoBpB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAKxD,IAAI,IAAI,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;IAIhD,QAAQ,IAAI,OAAO;IAIb,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAI/C,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAmB7C,WAAW,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAqBxF,MAAM,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAiBzC,gBAAgB;IAsC9B,OAAO,CAAC,kBAAkB;CAK3B"}

package/dist/src/background-tasks/in-process/manager.js

@@ -0,0 +1,214 @@
+import { InterruptError, InterruptState } from '../../interrupt.js';
+import { createMiddlewareInterrupt } from '../../middleware/interrupt.js';
+import { InterruptResponseContent } from '../../types/interrupt.js';
+import { TextBlock } from '../../types/messages.js';
+import { BackgroundTaskNotFoundError, BackgroundTaskTimeoutError } from '../errors.js';
+import { assertTimerDelay } from '../timer.js';
+import { InProcessTaskEngine } from './engine.js';
+import {} from './types.js';
+import { isTaskStatusTerminal } from '../types.js';
+/** Executes approved tool calls as in-process background tasks. @internal */
+export class InProcessTaskManager {
+    _agent;
+    _executeTool;
+    _engine;
+    _executions = new Map();
+    _taskIdBySubmission = new Map();
+    _taskWaiters = new Map();
+    constructor(agent, executeTool, config = {}) {
+        this._agent = agent;
+        this._executeTool = executeTool;
+        this._engine = new InProcessTaskEngine({
+            maxConcurrency: config.maxConcurrency ?? 4,
+            timeout: config.timeout ?? Infinity,
+            execute: (context) => this._executeToolTask(context),
+            onTaskUpdated: (record) => {
+                const task = toBackgroundTask(record);
+                if (isTaskStatusTerminal(record.status)) {
+                    this._executions.delete(record.invocationStateId);
+                }
+                if (record.status === 'input_required' || isTaskStatusTerminal(record.status)) {
+                    this._notifyTaskWaiters(task);
+                }
+                config.onTaskUpdated?.(task);
+            },
+        });
+    }
+    async submit(toolUse, invocationState, passId, tool) {
+        const submissionKey = JSON.stringify([passId, toolUse.toolUseId]);
+        const existingTaskId = this._taskIdBySubmission.get(submissionKey);
+        if (existingTaskId)
+            return toBackgroundTask(this._engine.get(existingTaskId));
+        const invocationStateId = globalThis.crypto.randomUUID();
+        this._executions.set(invocationStateId, {
+            toolUse: globalThis.structuredClone(toolUse),
+            invocationState,
+            tool,
+        });
+        const record = this._engine.submit({
+            toolName: toolUse.name,
+            toolUseId: toolUse.toolUseId,
+            invocationStateId,
+        });
+        this._taskIdBySubmission.set(submissionKey, record.taskId);
+        return toBackgroundTask(record);
+    }
+    async get(taskId) {
+        const record = this._engine.get(taskId);
+        return record ? toBackgroundTask(record) : undefined;
+    }
+    async list() {
+        return this._engine.list().map(toBackgroundTask);
+    }
+    hasTasks() {
+        return this._taskIdBySubmission.size > 0;
+    }
+    async cancel(taskId) {
+        return toBackgroundTask(this._engine.cancel(taskId, { reason: 'Cancellation requested' }));
+    }
+    async wait(taskId) {
+        const current = this._engine.get(taskId);
+        if (!current)
+            throw new BackgroundTaskNotFoundError(taskId);
+        if (current.status === 'input_required' || isTaskStatusTerminal(current.status)) {
+            return toBackgroundTask(current);
+        }
+        return new Promise((resolve) => {
+            const waiters = this._taskWaiters.get(taskId) ?? new Set();
+            const onTaskUpdated = (task) => {
+                waiters.delete(onTaskUpdated);
+                if (waiters.size === 0)
+                    this._taskWaiters.delete(taskId);
+                resolve(task);
+            };
+            waiters.add(onTaskUpdated);
+            this._taskWaiters.set(taskId, waiters);
+        });
+    }
+    async waitForIdle(options) {
+        const timeout = options?.timeout;
+        if (timeout !== undefined)
+            assertTimerDelay('wait timeout', timeout);
+        if (timeout === undefined)
+            return this._engine.waitForIdle();
+        const cancelSignal = AbortSignal.timeout(timeout);
+        try {
+            await this._engine.waitForIdle({ cancelSignal });
+        }
+        catch (error) {
+            if (error === cancelSignal.reason)
+                throw new BackgroundTaskTimeoutError(timeout);
+            throw error;
+        }
+    }
+    async resume(taskId, responses) {
+        return toBackgroundTask(this._engine.resume(taskId, (state) => {
+            const taskState = InterruptState.fromJSON(state);
+            taskState.resume(responses.map((response) => new InterruptResponseContent({
+                interruptId: response.interruptId,
+                response: response.response,
+            })));
+            return {
+                state: taskState.toJSON(),
+                ready: taskState.getUnansweredInterrupts().length === 0,
+            };
+        }));
+    }
+    async remove(taskIds) {
+        const uniqueTaskIds = new Set(taskIds);
+        for (const taskId of uniqueTaskIds) {
+            const task = this._engine.get(taskId);
+            if (!task)
+                throw new BackgroundTaskNotFoundError(taskId);
+            if (!isTaskStatusTerminal(task.status)) {
+                throw new Error(`Background task '${taskId}' cannot be removed before reaching a terminal status`);
+            }
+        }
+        for (const taskId of uniqueTaskIds) {
+            this._engine.remove(taskId);
+        }
+        for (const [submissionKey, taskId] of this._taskIdBySubmission) {
+            if (uniqueTaskIds.has(taskId))
+                this._taskIdBySubmission.delete(submissionKey);
+        }
+    }
+    async _executeToolTask(context) {
+        const execution = this._executions.get(context.invocationStateId);
+        if (!execution)
+            throw new Error('Background task live execution state is unavailable');
+        const interruptState = context.state ? InterruptState.fromJSON(context.state) : new InterruptState();
+        try {
+            return toolTaskOutcome(await this._executeTool(execution.tool, {
+                agent: this._agent,
+                invocationState: execution.invocationState,
+                cancelSignal: context.cancelSignal,
+                toolUse: execution.toolUse,
+                interrupt: (params) => interruptTool(interruptState, context.taskId, params),
+            }, createMiddlewareInterrupt(interruptState, `middleware:${context.taskId}`)));
+        }
+        catch (error) {
+            if (error instanceof InterruptError) {
+                const taskOwnsInterrupts = error.interrupts.length > 0 &&
+                    error.interrupts.every((interrupt) => (interrupt.source === 'middleware' || interrupt.source === 'tool') &&
+                        interrupt.id.startsWith(`${interrupt.source}:${context.taskId}:`));
+                if (!taskOwnsInterrupts)
+                    throw error;
+                for (const interrupt of error.interrupts)
+                    interruptState.registerInterrupt(interrupt);
+                interruptState.activate();
+                return { status: 'input_required', state: interruptState.toJSON() };
+            }
+            throw error;
+        }
+    }
+    _notifyTaskWaiters(task) {
+        const waiters = this._taskWaiters.get(task.taskId);
+        if (!waiters)
+            return;
+        for (const waiter of waiters)
+            waiter(task);
+    }
+}
+function toolTaskOutcome(resultBlock) {
+    const result = resultBlock.toJSON().toolResult;
+    if (resultBlock.status === 'success')
+        return { status: 'completed', result };
+    return {
+        status: 'failed',
+        failure: {
+            type: 'toolError',
+            message: resultBlock.error?.message ??
+                resultBlock.content.find((content) => content instanceof TextBlock)?.text ??
+                'Tool returned an error without a message',
+        },
+        result,
+    };
+}
+function interruptTool(state, taskId, params) {
+    const interrupt = state.getOrCreateInterrupt(`tool:${taskId}:${params.name}`, params.name, params.reason, params.response, 'tool');
+    if (interrupt.response !== undefined)
+        return interrupt.response;
+    throw new InterruptError(interrupt);
+}
+function toBackgroundTask(record) {
+    const interrupts = record.state ? InterruptState.fromJSON(record.state).getUnansweredInterrupts() : [];
+    return {
+        taskId: record.taskId,
+        toolUseId: record.toolUseId,
+        toolName: record.toolName,
+        status: record.status,
+        createdAt: record.createdAt,
+        lastUpdatedAt: record.lastUpdatedAt,
+        ...(record.result && {
+            result: { content: record.result.content },
+        }),
+        ...(record.failure && {
+            error: {
+                type: record.failure.type,
+                message: record.failure.message,
+            },
+        }),
+        ...(interrupts.length > 0 && { interrupts }),
+    };
+}
+//# sourceMappingURL=manager.js.map

package/dist/src/background-tasks/in-process/manager.js.map

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

package/dist/src/background-tasks/in-process/types.d.ts

@@ -1,9 +1,6 @@
 import type { InterruptStateData } from '../../interrupt.js';
 import type { ToolResultBlockData } from '../../types/messages.js';
-/** Background task lifecycle status. @internal */
-export type TaskStatus = 'queued' | 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
-/** Background task failure category. @internal */
-export type TaskFailureType = 'toolError' | 'executionError' | 'timeout';
+import type { BackgroundTaskFailureType, BackgroundTaskStatus } from '../types.js';
 /** Options and callbacks for bounded in-process task execution. @internal */
 export interface InProcessTaskEngineOptions {
     /** Maximum number of task executions that may run concurrently. */
@@ -11,7 +8,7 @@ export interface InProcessTaskEngineOptions {
     /** Per-execution timeout in milliseconds, or `Infinity` to disable timeouts. */
     readonly timeout: number;
     /** Runs one task execution and returns whether it completed, requires input, or failed. */
-    readonly execute: (context: InProcessTaskExecutionContext) => Promise<TaskExecutionOutcome>;
+    readonly execute: (context: InProcessTaskExecutionContext) => Promise<InProcessTaskExecutionOutcome>;
     /** Receives committed task updates without blocking or failing the engine. */
     readonly onTaskUpdated: (task: InProcessTaskRecord) => void;
 }
@@ -21,7 +18,7 @@ export interface InProcessTaskExecutionContext {
     readonly taskId: string;
     /** Identifier of the tool use. */
     readonly toolUseId: string;
-    /** Name of the tool to execute. */
+    /** Tool name from the original model request. */
     readonly toolName: string;
     /** Identifier of the manager-owned live execution state. */
     readonly invocationStateId: string;
@@ -31,7 +28,7 @@ export interface InProcessTaskExecutionContext {
     readonly cancelSignal: AbortSignal;
 }
 /** Outcome returned by one in-process task execution. @internal */
-export type TaskExecutionOutcome = {
+export type InProcessTaskExecutionOutcome = {
     readonly status: 'completed';
     readonly result: ToolResultBlockData;
 } | {
@@ -40,7 +37,7 @@ export type TaskExecutionOutcome = {
 } | {
     readonly status: 'failed';
     readonly failure: {
-        readonly type: TaskFailureType;
+        readonly type: BackgroundTaskFailureType;
         readonly message: string;
     };
     readonly result?: ToolResultBlockData;
@@ -49,28 +46,26 @@ export type TaskExecutionOutcome = {
 export interface InProcessTaskRecord {
     /** Identifier of the logical task. */
     readonly taskId: string;
-    /** Optional key used to deduplicate task admission. */
-    readonly idempotencyKey?: string;
     /** Identifier of the tool use. */
     readonly toolUseId: string;
-    /** Name of the tool to execute. */
+    /** Tool name from the original model request. */
     readonly toolName: string;
     /** Identifier of the manager-owned live execution state. */
     readonly invocationStateId: string;
     /** Current task lifecycle status. */
-    status: TaskStatus;
+    status: BackgroundTaskStatus;
     /** Interrupt state, required while the task needs input and retained while resuming. */
     state?: InterruptStateData;
     /** Execution result, required while completed and optional while failed. */
     result?: ToolResultBlockData;
     /** Failure details recorded when the task fails. */
     failure?: {
-        readonly type: TaskFailureType;
+        readonly type: BackgroundTaskFailureType;
         readonly message: string;
     };
     /** ISO-8601 creation timestamp. */
     readonly createdAt: string;
     /** ISO-8601 timestamp of the latest transition. */
-    updatedAt: string;
+    lastUpdatedAt: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/src/background-tasks/in-process/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/background-tasks/in-process/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAElE,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEvG,kDAAkD;AAClD,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,gBAAgB,GAAG,SAAS,CAAA;AAExE,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,6BAA6B,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAC3F,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAA;CAC5D;AAED,mEAAmE;AACnE,MAAM,WAAW,6BAA6B;IAC5C,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAA;IACnC,sDAAsD;IACtD,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAA;CACnC;AAED,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAC5B;IACE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;CACrC,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CACnC,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;QAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;CACtC,CAAA;AAEL,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,qCAAqC;IACrC,MAAM,EAAE,UAAU,CAAA;IAClB,wFAAwF;IACxF,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B,oDAAoD;IACpD,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;QAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAA;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/background-tasks/in-process/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAClE,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAElF,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,6BAA6B,KAAK,OAAO,CAAC,6BAA6B,CAAC,CAAA;IACpG,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAA;CAC5D;AAED,mEAAmE;AACnE,MAAM,WAAW,6BAA6B;IAC5C,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAA;IACnC,sDAAsD;IACtD,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAA;CACnC;AAED,mEAAmE;AACnE,MAAM,MAAM,6BAA6B,GACrC;IACE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;CACrC,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CACnC,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAA;QACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;CACtC,CAAA;AAEL,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,qCAAqC;IACrC,MAAM,EAAE,oBAAoB,CAAA;IAC5B,wFAAwF;IACxF,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B,oDAAoD;IACpD,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAA;QACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAA;CACtB"}

package/dist/src/background-tasks/manager.d.ts

@@ -0,0 +1,59 @@
+import type { ToolUseData } from '../hooks/events.js';
+import type { Tool } from '../tools/tool.js';
+import type { InvocationState } from '../types/agent.js';
+import type { InterruptResponse } from '../types/interrupt.js';
+import type { BackgroundTask } from './types.js';
+/** Background task lifecycle operations used by an Agent integration. @internal */
+export interface BackgroundTaskManager {
+    /**
+     * Submits an approved tool call for background execution.
+     *
+     * Repeated submission of the same pending tool call returns its existing task; removing that task allows the
+     * submission to create a new task.
+     */
+    submit(toolUse: Readonly<ToolUseData>, invocationState: InvocationState, passId: string, tool: Tool): Promise<BackgroundTask>;
+    /** Gets one task by its stable identifier. */
+    get(taskId: string): Promise<BackgroundTask | undefined>;
+    /** Lists the tasks currently tracked by the manager. */
+    list(): Promise<readonly BackgroundTask[]>;
+    /** Whether the manager is tracking any tasks (including terminal ones not yet removed). */
+    hasTasks(): boolean;
+    /**
+     * Requests cancellation of one task.
+     *
+     * @throws BackgroundTaskNotFoundError if the task does not exist.
+     */
+    cancel(taskId: string): Promise<BackgroundTask>;
+    /**
+     * Waits until one task requires input or reaches a terminal state.
+     *
+     * @throws BackgroundTaskNotFoundError if the task does not exist.
+     */
+    wait(taskId: string): Promise<BackgroundTask>;
+    /**
+     * Waits until the manager has no queued or executing tasks.
+     *
+     * Tasks in `input_required` do not block this wait.
+     *
+     * @throws TypeError if the timeout is invalid.
+     * @throws BackgroundTaskTimeoutError if the configured wait timeout elapses.
+     */
+    waitForIdle(options?: {
+        readonly timeout?: number;
+    }): Promise<void>;
+    /**
+     * Applies interrupt responses to one task that requires input.
+     *
+     * @throws BackgroundTaskNotFoundError if the task does not exist.
+     * @throws Error if the task cannot accept the interrupt responses.
+     */
+    resume(taskId: string, responses: readonly InterruptResponse[]): Promise<BackgroundTask>;
+    /**
+     * Removes terminal tasks.
+     *
+     * @throws BackgroundTaskNotFoundError if a task does not exist.
+     * @throws Error if a task has not reached a terminal state.
+     */
+    remove(taskIds: readonly string[]): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/src/background-tasks/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/background-tasks/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,MAAM,CACJ,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC9B,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,cAAc,CAAC,CAAA;IAC1B,8CAA8C;IAC9C,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAA;IACxD,wDAAwD;IACxD,IAAI,IAAI,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAA;IAC1C,2FAA2F;IAC3F,QAAQ,IAAI,OAAO,CAAA;IACnB;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC/C;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IAC7C;;;;;;;OAOG;IACH,WAAW,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnE;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;IACxF;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClD"}

package/dist/src/background-tasks/manager.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manager.js.map

package/dist/src/background-tasks/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/background-tasks/manager.ts"],"names":[],"mappings":""}

package/dist/src/background-tasks/timer.d.ts

@@ -0,0 +1,3 @@
+/** Validates a delay accepted by JavaScript timers. @internal */
+export declare function assertTimerDelay(name: string, value: number): void;
+//# sourceMappingURL=timer.d.ts.map

package/dist/src/background-tasks/timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.d.ts","sourceRoot":"","sources":["../../../src/background-tasks/timer.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOlE"}

package/dist/src/background-tasks/timer.js

@@ -0,0 +1,11 @@
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+/** Validates a delay accepted by JavaScript timers. @internal */
+export function assertTimerDelay(name, value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive finite integer, got ${value}`);
+    }
+    if (value > MAX_TIMER_DELAY_MS) {
+        throw new TypeError(`${name} must be at most ${MAX_TIMER_DELAY_MS}ms, got ${value}`);
+    }
+}
+//# sourceMappingURL=timer.js.map

package/dist/src/background-tasks/timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.js","sourceRoot":"","sources":["../../../src/background-tasks/timer.ts"],"names":[],"mappings":"AAAA,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;AAEtC,iEAAiE;AACjE,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,KAAa;IAC1D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,2CAA2C,KAAK,EAAE,CAAC,CAAA;IAChF,CAAC;IACD,IAAI,KAAK,GAAG,kBAAkB,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,oBAAoB,kBAAkB,WAAW,KAAK,EAAE,CAAC,CAAA;IACtF,CAAC;AACH,CAAC"}

package/dist/src/background-tasks/types.d.ts

@@ -0,0 +1,60 @@
+import type { Interrupt } from '../interrupt.js';
+import type { Tool } from '../tools/tool.js';
+import type { ToolResultContentData } from '../types/messages.js';
+/** Configures background tool execution. */
+export interface BackgroundTasksConfig {
+    /** Wait for background work before an invocation returns. Defaults to `true`. */
+    readonly waitForCompletion?: boolean;
+    /** Tools or registered tool names whose execution mode is selected by the model. Defaults to `['*']`. */
+    readonly agentic?: readonly (Tool | string)[];
+    /** Tools or registered tool names that always execute in the background. */
+    readonly always?: readonly (Tool | string)[];
+    /** Tools or registered tool names that never execute in the background. */
+    readonly never?: readonly (Tool | string)[];
+    /** Maximum number of physically executing background tasks. Defaults to `4`. */
+    readonly maxConcurrency?: number;
+    /** Per-execution timeout in milliseconds. Defaults to `Infinity`. */
+    readonly timeout?: number;
+}
+/** Background task lifecycle status. @internal */
+export type BackgroundTaskStatus = 'queued' | 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+/** Background task failure category. @internal */
+export type BackgroundTaskFailureType = 'toolError' | 'executionError' | 'timeout';
+/** Read-only snapshot of a background task. @internal */
+export interface BackgroundTask {
+    /** Stable identifier for task inspection and cancellation. */
+    readonly taskId: string;
+    /** Tool-use identifier from the original model request. */
+    readonly toolUseId: string;
+    /** Tool name from the original model request. */
+    readonly toolName: string;
+    /** Current task lifecycle status. */
+    readonly status: BackgroundTaskStatus;
+    /** ISO timestamp recorded when the task was admitted. */
+    readonly createdAt: string;
+    /** ISO timestamp recorded at the latest task state change. */
+    readonly lastUpdatedAt: string;
+    /** Tool result when execution produced one. */
+    readonly result?: {
+        /** Tool-result content blocks. */
+        readonly content: readonly ToolResultContentData[];
+    };
+    /** Task failure details. */
+    readonly error?: {
+        /** Failure category. */
+        readonly type: BackgroundTaskFailureType;
+        /** Failure message. */
+        readonly message: string;
+    };
+    /** Unanswered interrupts when the task requires input. */
+    readonly interrupts?: readonly Readonly<Interrupt>[];
+}
+/**
+ * Checks whether a background task status is terminal.
+ *
+ * @param status - Status to check.
+ * @returns Whether the status is terminal.
+ * @internal
+ */
+export declare function isTaskStatusTerminal(status: BackgroundTaskStatus): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/background-tasks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/background-tasks/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAEjE,4CAA4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;IACpC,yGAAyG;IACzG,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,IAAI,GAAG,MAAM,CAAC,EAAE,CAAA;IAC7C,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,IAAI,GAAG,MAAM,CAAC,EAAE,CAAA;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,IAAI,GAAG,MAAM,CAAC,EAAE,CAAA;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,kDAAkD;AAClD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,SAAS,GAAG,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEjH,kDAAkD;AAClD,MAAM,MAAM,yBAAyB,GAAG,WAAW,GAAG,gBAAgB,GAAG,SAAS,CAAA;AAElF,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;IACrC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,kCAAkC;QAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAA;KACnD,CAAA;IACD,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,wBAAwB;QACxB,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAA;QACxC,uBAAuB;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KACzB,CAAA;IACD,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAA;CACrD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAE1E"}

package/dist/src/background-tasks/types.js

@@ -0,0 +1,11 @@
+/**
+ * Checks whether a background task status is terminal.
+ *
+ * @param status - Status to check.
+ * @returns Whether the status is terminal.
+ * @internal
+ */
+export function isTaskStatusTerminal(status) {
+    return status === 'completed' || status === 'failed' || status === 'cancelled';
+}
+//# sourceMappingURL=types.js.map

package/dist/src/background-tasks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/background-tasks/types.ts"],"names":[],"mappings":"AAwDA;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAC/D,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,WAAW,CAAA;AAChF,CAAC"}

package/dist/src/context-manager/context-manager.d.ts

@@ -4,8 +4,10 @@
  * On overflow, runs the strategy pipeline (including an emergency truncation as the final step).
  */
 import type { Plugin } from '../plugins/plugin.js';
+import type { Tool } from '../tools/tool.js';
 import type { LocalAgent } from '../types/agent.js';
 import type { ContextManagerConfig } from './types.js';
+import { Stash } from './stash.js';
 /**
  * Manages context reduction for an agent's conversation.
  *
@@ -18,13 +20,32 @@ import type { ContextManagerConfig } from './types.js';
  * overflow recovery — no separate ConversationManager is needed.
  *
  * @experimental
- * @internal
  */
 export declare class ContextManager implements Plugin {
     readonly name = "strands:context-manager";
     private readonly _strategies;
+    private readonly _stashStorage;
+    private readonly _enableRetrievalTool;
+    private readonly _retrievalToolUseIds;
+    private _stash;
+    private _stashIsDurable;
+    private _retrievalTool;
     constructor(config?: ContextManagerConfig);
+    getTools(): Tool[];
     initAgent(agent: LocalAgent): void;
+    /**
+     * The L1 stash instance, if stash is enabled and the agent has been initialized.
+     *
+     * @returns The stash, or undefined if stash is disabled or initAgent has not run
+     */
+    get stash(): Stash | undefined;
+    /**
+     * Whether the stash is backed by durable storage that survives process restarts.
+     * When true, stash data does not need to be embedded in session snapshots.
+     *
+     * @returns true if the stash storage is not ephemeral
+     */
+    get stashIsDurable(): boolean;
     private _runStrategies;
 }
 //# sourceMappingURL=context-manager.d.ts.map

package/dist/src/context-manager/context-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-manager.d.ts","sourceRoot":"","sources":["../../../src/context-manager/context-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAInD,OAAO,KAAK,EAAE,oBAAoB,EAAiC,MAAM,YAAY,CAAA;AAGrF;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,YAAW,MAAM;IAC3C,QAAQ,CAAC,IAAI,6BAA4B;IAEzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;gBAEnC,MAAM,CAAC,EAAE,oBAAoB;IAUzC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;YAkCpB,cAAc;CA2B7B"}
+{"version":3,"file":"context-manager.d.ts","sourceRoot":"","sources":["../../../src/context-manager/context-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAOnD,OAAO,KAAK,EAAE,oBAAoB,EAAiC,MAAM,YAAY,CAAA;AAErF,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAGlC;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,YAAW,MAAM;IAC3C,QAAQ,CAAC,IAAI,6BAA4B;IAEzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAoB;IACzD,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,cAAc,CAAkB;gBAE5B,MAAM,CAAC,EAAE,oBAAoB;IAczC,QAAQ,IAAI,IAAI,EAAE;IASlB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAiDlC;;;;OAIG;IACH,IAAI,KAAK,IAAI,KAAK,GAAG,SAAS,CAE7B;IAED;;;;;OAKG;IACH,IAAI,cAAc,IAAI,OAAO,CAE5B;YAEa,cAAc;CA4B7B"}