@better-agent/plugins 0.1.0-canary.5 → 0.2.0-beta.1

package/dist/index.mjs

@@ -1,114 +1,25 @@
 import { BetterAgentError } from "@better-agent/shared/errors";
 import { defineTool } from "@better-agent/core";
 
-//#region src/shared/json.ts
-/** Creates a JSON response with a default content type. */
-function jsonResponse(body, init) {
-	const headers = new Headers(init?.headers);
-	if (!headers.has("content-type")) headers.set("content-type", "application/json");
-	return new Response(JSON.stringify(body), {
-		...init,
-		headers
-	});
-}
-
-//#endregion
-//#region src/auth/responses.ts
-/** Creates the default unauthorized response. */
-function createUnauthorizedResponse() {
-	return jsonResponse({
-		error: "unauthorized",
-		message: "Invalid API key."
-	}, { status: 401 });
-}
-
-//#endregion
-//#region src/shared/validation.ts
-/** Creates a plugin validation error. */
-function createValidationError$1(message, at) {
-	return BetterAgentError.fromCode("VALIDATION_FAILED", message, { trace: [{ at }] });
-}
-/** Requires a positive finite number. */
-function requirePositiveNumber(value, name, at) {
-	if (!Number.isFinite(value) || value <= 0) throw createValidationError$1(`\`${name}\` must be a positive number.`, at);
-}
-/** Requires a non-empty array. */
-function requireNonEmptyArray(value, name, at) {
-	if (!value || value.length === 0) throw createValidationError$1(`\`${name}\` must contain at least one value.`, at);
-}
-
-//#endregion
-//#region src/auth/validate.ts
-/** Validates `authPlugin` configuration. */
-function validateAuthPluginConfig(config) {
-	if (!config.validate && (!config.apiKeys || config.apiKeys.length === 0)) throw createValidationError$1("`authPlugin` requires either `apiKeys` or `validate`.", "plugins.authPlugin");
-	if (config.header !== void 0 && config.header.trim().length === 0) throw createValidationError$1("`authPlugin` requires `header` to be a non-empty string when provided.", "plugins.authPlugin");
-	if (config.apiKeys) {
-		if (config.apiKeys.filter((key) => typeof key === "string").map((key) => key.trim()).filter((key) => key.length > 0).length === 0 && !config.validate) throw createValidationError$1("`authPlugin` requires `apiKeys` to contain at least one non-empty key.", "plugins.authPlugin");
-	}
-}
-
-//#endregion
-//#region src/auth/plugin.ts
-/**
-* Creates an API-key auth plugin.
-*
-* Provide either `apiKeys` or `validate`.
-*
-* @example
-* ```ts
-* const plugin = authPlugin({
-*   apiKeys: ["dev-key"],
-* });
-* ```
-*/
-const authPlugin = (config) => {
-	validateAuthPluginConfig(config);
-	const header = config.header?.trim() || "x-api-key";
-	const apiKeys = new Set((config.apiKeys ?? []).map((key) => key.trim()).filter(Boolean));
-	return {
-		id: config.id ?? "auth",
-		guards: [async (ctx) => {
-			const keyValue = config.getKey ? await config.getKey({
-				agentName: ctx.agentName,
-				mode: ctx.mode,
-				request: ctx.request
-			}) : ctx.request.headers.get(header);
-			const key = typeof keyValue === "string" && keyValue.trim().length > 0 ? keyValue : null;
-			if (config.validate ? await config.validate({
-				key,
-				agentName: ctx.agentName,
-				mode: ctx.mode,
-				request: ctx.request
-			}) : key !== null && apiKeys.has(key)) return null;
-			return config.onUnauthorized ? await config.onUnauthorized({
-				key,
-				agentName: ctx.agentName,
-				mode: ctx.mode,
-				request: ctx.request
-			}) : createUnauthorizedResponse();
-		}]
-	};
-};
-
-//#endregion
 //#region src/ip-allowlist/ip.ts
 /** Parses an IPv4 string. */
 function parseIpv4(input) {
 	const parts = input.split(".");
 	if (parts.length !== 4) return null;
 	let value = 0n;
+	const normalizedParts = [];
 	for (const part of parts) {
 		if (!/^\d+$/.test(part)) return null;
 		const octet = Number(part);
 		if (octet < 0 || octet > 255) return null;
 		value = value << 8n | BigInt(octet);
+		normalizedParts.push(String(octet));
 	}
 	return {
 		kind: "ipv4",
 		value,
 		bits: 32,
-		normalized: parts.join(".")
+		normalized: normalizedParts.join(".")
 	};
 }
 /** Expands an IPv6 string into eight normalized segments. */
@@ -210,6 +121,18 @@ function parseAllowEntry(input) {
 	};
 }
 
+//#endregion
+//#region src/shared/json.ts
+/** Creates a JSON response with a default content type. */
+function jsonResponse(body, init) {
+	const headers = new Headers(init?.headers);
+	if (!headers.has("content-type")) headers.set("content-type", "application/json");
+	return new Response(JSON.stringify(body), {
+		...init,
+		headers
+	});
+}
+
 //#endregion
 //#region src/ip-allowlist/responses.ts
 /** Creates the default IP denied response. */
@@ -220,12 +143,27 @@ function createIpDeniedResponse() {
 	}, { status: 403 });
 }
 
+//#endregion
+//#region src/shared/validation.ts
+/** Creates a plugin validation error. */
+function createValidationError$1(message, at) {
+	return BetterAgentError.fromCode("VALIDATION_FAILED", message, { trace: [{ at }] });
+}
+/** Requires a positive finite number. */
+function requirePositiveNumber(value, name, at) {
+	if (!Number.isFinite(value) || value <= 0) throw createValidationError$1(`\`${name}\` must be a positive number.`, at);
+}
+/** Requires a non-empty array. */
+function requireNonEmptyArray(value, name, at) {
+	if (!value || value.length === 0) throw createValidationError$1(`\`${name}\` must contain at least one value.`, at);
+}
+
 //#endregion
 //#region src/ip-allowlist/validate.ts
-/** Validates `ipAllowlistPlugin` configuration. */
-function validateIpAllowlistPluginConfig(config) {
-	requireNonEmptyArray(config.allow, "allow", "plugins.ipAllowlistPlugin");
-	for (const entry of config.allow) if (typeof entry !== "string" || !parseAllowEntry(entry)) throw createValidationError$1(`\`ipAllowlistPlugin\` received an invalid allow entry: '${String(entry)}'.`, "plugins.ipAllowlistPlugin");
+/** Validates `ipAllowlist` configuration. */
+function validateIpAllowlistConfig(config) {
+	requireNonEmptyArray(config.allow, "allow", "plugins.ipAllowlist");
+	for (const entry of config.allow) if (typeof entry !== "string" || !parseAllowEntry(entry)) throw createValidationError$1(`\`ipAllowlist\` received an invalid allow entry: '${String(entry)}'.`, "plugins.ipAllowlist");
 }
 
 //#endregion
@@ -261,13 +199,13 @@ function getDirectIp(request) {
 *
 * @example
 * ```ts
-* const plugin = ipAllowlistPlugin({
+* const plugin = ipAllowlist({
 *   allow: ["127.0.0.1", "10.0.0.0/8"],
 * });
 * ```
 */
-const ipAllowlistPlugin = (config) => {
-	validateIpAllowlistPluginConfig(config);
+const ipAllowlist = (config) => {
+	validateIpAllowlistConfig(config);
 	const matchers = config.allow.map((entry) => {
 		const matcher = parseAllowEntry(entry);
 		if (!matcher) throw new Error(`Invalid allowlist entry: ${entry}`);
@@ -278,7 +216,6 @@ const ipAllowlistPlugin = (config) => {
 		guards: [async (ctx) => {
 			const resolvedIp = config.getIp ? await config.getIp({
 				agentName: ctx.agentName,
-				mode: ctx.mode,
 				request: ctx.request
 			}) : config.trustProxy ? getProxyIp(ctx.request) : getDirectIp(ctx.request);
 			const normalizedIp = typeof resolvedIp === "string" && resolvedIp.trim().length > 0 ? normalizeIp(resolvedIp) : null;
@@ -287,7 +224,6 @@ const ipAllowlistPlugin = (config) => {
 			return config.onDenied ? await config.onDenied({
 				ip: normalizedIp,
 				agentName: ctx.agentName,
-				mode: ctx.mode,
 				request: ctx.request
 			}) : createIpDeniedResponse();
 		}]
@@ -325,11 +261,6 @@ function redactHeaders(headers, extraHeaders) {
 	return result;
 }
 
-//#endregion
-//#region src/logging/validate.ts
-/** Validates `loggingPlugin` configuration. */
-function validateLoggingPluginConfig(_config) {}
-
 //#endregion
 //#region src/logging/plugin.ts
 function safeInvoke(fn, payload) {
@@ -338,6 +269,14 @@ function safeInvoke(fn, payload) {
 		fn(payload);
 	} catch {}
 }
+function safeMap(fn, input) {
+	if (!fn) return input;
+	try {
+		return fn(input);
+	} catch {
+		return input;
+	}
+}
 /** Resolves the logger methods for the configured sink. */
 function getLoggerMethods(config) {
 	return {
@@ -350,7 +289,7 @@ function getLoggerMethods(config) {
 /** Emits one log entry. */
 function emitLog(config, entry) {
 	if (!shouldLog(config.level ?? "info", entry)) return;
-	const output = config.format ? config.format(entry) : entry;
+	const output = safeMap(config.format, entry);
 	safeInvoke(getLoggerMethods(config)[entry.level], output);
 }
 /** Maps one runtime event to a log level. */
@@ -358,16 +297,25 @@ function getEventLevel(event) {
 	if (event.type.endsWith("_ERROR")) return "error";
 	return "info";
 }
-/** Creates request log data. */
-function createRequestData(ctx) {
+function createRedactedRequestData(ctx, config) {
 	return {
-		mode: ctx.mode,
 		url: ctx.request.url,
 		method: ctx.request.method,
-		headers: redactHeaders(ctx.request.headers),
+		headers: redactHeaders(ctx.request.headers, config.redactHeaders),
 		input: ctx.input
 	};
 }
+function redactBody(config, phase, body) {
+	if (!config.redactBody) return body;
+	try {
+		return config.redactBody({
+			body,
+			phase
+		});
+	} catch {
+		return body;
+	}
+}
 /** Creates step log data. */
 function createStepData(ctx) {
 	return {
@@ -376,49 +324,36 @@ function createStepData(ctx) {
 		messageCount: ctx.messages.length
 	};
 }
-/** Creates save log data. */
-function createSaveData(ctx) {
-	const messageCount = ctx.items.filter((item) => item.type === "message").length;
-	return {
-		itemCount: ctx.items.length,
-		messageCount
-	};
-}
 /**
 * Creates a logging plugin.
 *
 * @example
 * ```ts
-* const plugin = loggingPlugin({
+* const plugin = logging({
 *   level: "info",
 *   include: { requests: true, toolCalls: true },
 * });
 * ```
 */
-const loggingPlugin = (config = {}) => {
-	/* @__PURE__ */ validateLoggingPluginConfig(config);
+const logging = (config = {}) => {
 	const include = {
 		requests: config.include?.requests ?? true,
 		events: config.include?.events ?? true,
 		steps: config.include?.steps ?? true,
 		modelCalls: config.include?.modelCalls ?? true,
 		toolCalls: config.include?.toolCalls ?? true,
-		saves: config.include?.saves ?? false,
 		errors: config.include?.errors ?? true
 	};
 	const plugin = { id: config.id ?? "logging" };
 	if (include.requests) plugin.guards = [async (ctx) => {
-		const body = config.redactBody ? config.redactBody({
-			body: ctx.input,
-			phase: "request"
-		}) : ctx.input;
+		const body = config.redactBody ? redactBody(config, "request", ctx.input) : ctx.input;
 		emitLog(config, {
 			level: "info",
 			event: "request.received",
 			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 			agentName: ctx.agentName,
 			data: {
-				...createRequestData(ctx),
+				...createRedactedRequestData(ctx, config),
 				input: body
 			}
 		});
@@ -430,10 +365,10 @@ const loggingPlugin = (config = {}) => {
 		emitLog(config, {
 			level,
 			event: "run.event",
-			timestamp: new Date(event.timestamp).toISOString(),
+			timestamp: new Date(event.timestamp ?? Date.now()).toISOString(),
 			agentName: ctx.agentName,
 			runId: ctx.runId,
-			conversationId: ctx.conversationId,
+			conversationId: ctx.threadId,
 			data: { type: event.type }
 		});
 	};
@@ -444,7 +379,7 @@ const loggingPlugin = (config = {}) => {
 			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 			agentName: ctx.agentName,
 			runId: ctx.runId,
-			conversationId: ctx.conversationId,
+			conversationId: ctx.threadId,
 			data: createStepData(ctx)
 		});
 	};
@@ -456,10 +391,10 @@ const loggingPlugin = (config = {}) => {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 				agentName: ctx.agentName,
 				runId: ctx.runId,
-				conversationId: ctx.conversationId,
+				conversationId: ctx.threadId,
 				data: {
 					stepIndex: ctx.stepIndex,
-					inputCount: ctx.input.length,
+					inputCount: ctx.messages.length,
 					toolCount: ctx.tools.length,
 					toolChoice: ctx.toolChoice
 				}
@@ -472,13 +407,10 @@ const loggingPlugin = (config = {}) => {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 				agentName: ctx.agentName,
 				runId: ctx.runId,
-				conversationId: ctx.conversationId,
+				conversationId: ctx.threadId,
 				data: {
 					stepIndex: ctx.stepIndex,
-					response: config.redactBody ? config.redactBody({
-						body: ctx.response,
-						phase: "response"
-					}) : ctx.response
+					response: config.redactBody ? redactBody(config, "response", ctx.response) : ctx.response
 				}
 			});
 		};
@@ -491,14 +423,11 @@ const loggingPlugin = (config = {}) => {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 				agentName: ctx.agentName,
 				runId: ctx.runId,
-				conversationId: ctx.conversationId,
+				conversationId: ctx.threadId,
 				data: {
 					toolName: ctx.toolName,
 					toolCallId: ctx.toolCallId,
-					args: config.redactBody ? config.redactBody({
-						body: ctx.args,
-						phase: "tool_args"
-					}) : ctx.args
+					args: config.redactBody ? redactBody(config, "tool_args", ctx.input) : ctx.input
 				}
 			});
 		};
@@ -509,36 +438,16 @@ const loggingPlugin = (config = {}) => {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 				agentName: ctx.agentName,
 				runId: ctx.runId,
-				conversationId: ctx.conversationId,
+				conversationId: ctx.threadId,
 				data: {
 					toolName: ctx.toolName,
 					toolCallId: ctx.toolCallId,
 					error: ctx.error,
-					result: config.redactBody ? config.redactBody({
-						body: ctx.result,
-						phase: "tool_result"
-					}) : ctx.result
+					result: config.redactBody ? redactBody(config, "tool_result", ctx.result) : ctx.result
 				}
 			});
 		};
 	}
-	if (include.saves) plugin.onBeforeSave = async (ctx) => {
-		emitLog(config, {
-			level: "debug",
-			event: "save.before",
-			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-			agentName: ctx.agentName,
-			runId: ctx.runId,
-			conversationId: ctx.conversationId,
-			data: {
-				...createSaveData(ctx),
-				items: config.redactBody ? config.redactBody({
-					body: ctx.items,
-					phase: "save"
-				}) : ctx.items
-			}
-		});
-	};
 	return plugin;
 };
 
@@ -562,17 +471,29 @@ function createBucket(params) {
 /** Creates an in-memory CAS store for rate limiting. */
 function createMemoryStore() {
 	const rows = /* @__PURE__ */ new Map();
+	const pruneExpiredRows = (bucket) => {
+		const nowMs = bucket.now.getTime();
+		for (const [id, row] of rows) if (row.windowEndMs <= nowMs) rows.delete(id);
+	};
+	const toStoredRow = (bucket, state) => ({
+		...state,
+		windowEndMs: bucket.windowEnd.getTime()
+	});
 	return {
-		read: async ({ bucket }) => rows.get(bucket.id) ?? null,
+		read: async ({ bucket }) => {
+			pruneExpiredRows(bucket);
+			return rows.get(bucket.id) ?? null;
+		},
 		write: async ({ bucket, prevVersion, next }) => {
+			pruneExpiredRows(bucket);
 			const current = rows.get(bucket.id) ?? null;
 			if (prevVersion === null) {
 				if (current) return false;
-				rows.set(bucket.id, next);
+				rows.set(bucket.id, toStoredRow(bucket, next));
 				return true;
 			}
 			if (!current || current.version !== prevVersion) return false;
-			rows.set(bucket.id, next);
+			rows.set(bucket.id, toStoredRow(bucket, next));
 			return true;
 		}
 	};
@@ -609,16 +530,16 @@ function createRateLimitStorageUnavailableResponse() {
 }
 /** Creates the CAS retries exceeded error. */
 function createCasRetriesExceededError() {
-	return BetterAgentError.fromCode("INTERNAL", "Rate limit write failed after CAS retries.", { trace: [{ at: "plugins.rateLimitPlugin" }] });
+	return BetterAgentError.fromCode("INTERNAL", "Rate limit write failed after CAS retries.", { trace: [{ at: "plugins.rateLimit" }] });
 }
 
 //#endregion
 //#region src/rate-limit/validate.ts
-/** Validates `rateLimitPlugin` configuration. */
-function validateRateLimitPluginConfig(config) {
-	requirePositiveNumber(config.windowMs, "windowMs", "plugins.rateLimitPlugin");
-	requirePositiveNumber(config.max, "max", "plugins.rateLimitPlugin");
-	requirePositiveNumber(config.casRetries ?? 8, "casRetries", "plugins.rateLimitPlugin");
+/** Validates `rateLimit` configuration. */
+function validateRateLimitConfig(config) {
+	requirePositiveNumber(config.windowMs, "windowMs", "plugins.rateLimit");
+	requirePositiveNumber(config.max, "max", "plugins.rateLimit");
+	requirePositiveNumber(config.casRetries ?? 8, "casRetries", "plugins.rateLimit");
 }
 
 //#endregion
@@ -630,23 +551,23 @@ function validateRateLimitPluginConfig(config) {
 *
 * @example
 * ```ts
-* const plugin = rateLimitPlugin({
+* const plugin = rateLimit({
 *   windowMs: 60_000,
 *   max: 30,
 * });
 * ```
 */
-const rateLimitPlugin = (config) => {
-	validateRateLimitPluginConfig(config);
+const rateLimit = (config) => {
+	validateRateLimitConfig(config);
 	const casRetries = config.casRetries ?? 8;
 	const storage = config.storage ?? createMemoryStore();
 	return {
 		id: config.id ?? "rate-limit",
 		guards: [async (ctx) => {
 			const request = {
-				mode: ctx.mode,
 				agentName: ctx.agentName,
-				request: ctx.request
+				request: ctx.request,
+				auth: ctx.auth
 			};
 			const now = /* @__PURE__ */ new Date();
 			const nowMs = now.getTime();
@@ -722,27 +643,28 @@ const normalizeFileEntries = (files) => files.map((entry) => ({
 	path: entry.path ?? entry.name ?? "",
 	type: entry.type ?? (entry.isDir ? "directory" : "file")
 }));
-/** Creates a sandbox client backed by the Daytona SDK. */
+/**
+* Creates a sandbox client backed by the Daytona SDK.
+*/
 function createDaytonaSandboxClient(config = {}) {
 	const clientConfig = removeUndefined$1({
 		apiKey: config.apiKey,
 		apiUrl: config.apiUrl,
 		target: config.target
 	});
+	const toProviderMinutes = (value) => value !== void 0 ? Math.max(1, Math.ceil(value / 6e4)) : void 0;
 	const buildCreateParams = (overrides) => {
-		const template = overrides?.template ?? config.template;
+		const template = overrides?.template;
 		const templateKind = config.templateKind ?? "snapshot";
 		return removeUndefined$1({
 			language: config.language,
-			envVars: overrides?.envs ?? config.envs,
-			labels: overrides?.metadata ?? config.metadata,
+			envVars: overrides?.envs,
+			labels: overrides?.metadata,
 			public: config.public,
-			autoStopInterval: config.autoStopInterval,
-			autoArchiveInterval: config.autoArchiveInterval,
-			autoDeleteInterval: config.autoDeleteInterval,
-			...template !== void 0 ? templateKind === "image" ? { image: template } : { snapshot: template } : {},
-			...config.snapshot !== void 0 ? { snapshot: config.snapshot } : {},
-			...config.image !== void 0 ? { image: config.image } : {}
+			autoStopInterval: toProviderMinutes(overrides?.lifecycle?.idleStopMs),
+			autoArchiveInterval: toProviderMinutes(overrides?.lifecycle?.archiveAfterMs),
+			autoDeleteInterval: toProviderMinutes(overrides?.lifecycle?.deleteAfterMs),
+			...template !== void 0 ? templateKind === "image" ? { image: template } : { snapshot: template } : {}
 		});
 	};
 	const getClient = async () => {
@@ -780,7 +702,7 @@ function createDaytonaSandboxClient(config = {}) {
 		},
 		async createSandbox(params) {
 			const client = await getClient();
-			const timeout = toSeconds(params?.timeoutMs ?? config.timeoutMs);
+			const timeout = toSeconds(params?.startupTimeoutMs);
 			return { sandboxId: (await client.create(buildCreateParams(params), { ...timeout !== void 0 ? { timeout } : {} })).id };
 		},
 		async runCommand(params) {
@@ -874,7 +796,9 @@ const loadE2B = async () => {
 		});
 	}
 };
-/** Creates a sandbox client backed by the E2B SDK. */
+/**
+* Creates a sandbox client backed by the E2B SDK.
+*/
 function createE2BSandboxClient(config = {}) {
 	const connectionOptions = removeUndefined({
 		apiKey: config.apiKey,
@@ -882,11 +806,11 @@ function createE2BSandboxClient(config = {}) {
 		domain: config.domain,
 		requestTimeoutMs: config.requestTimeoutMs
 	});
-	const toCreateOptions = (overrides) => removeUndefined({
+	const toCreateOptions = (params) => removeUndefined({
 		...connectionOptions,
-		timeoutMs: overrides?.timeoutMs ?? config.timeoutMs,
-		envs: overrides?.envs ?? config.envs,
-		metadata: overrides?.metadata ?? config.metadata
+		timeoutMs: params?.lifecycle?.ttlMs,
+		envs: params?.envs,
+		metadata: params?.metadata
 	});
 	const connectSandbox = async (sandboxId) => {
 		const { Sandbox } = await loadE2B();
@@ -910,7 +834,7 @@ function createE2BSandboxClient(config = {}) {
 		},
 		async createSandbox(params) {
 			const { Sandbox } = await loadE2B();
-			const template = params?.template ?? config.template;
+			const template = params?.template;
 			const options = toCreateOptions(params);
 			return { sandboxId: (template !== void 0 ? await Sandbox.create(template, options) : await Sandbox.create(options)).sandboxId };
 		},
@@ -965,11 +889,28 @@ function createMemorySandboxSessionStore() {
 
 //#endregion
 //#region src/sandbox/validate.ts
-/** Validates `sandboxPlugin` configuration. */
-function validateSandboxPluginConfig(config) {
+const hasLifecycleValues = (lifecycle) => Boolean(lifecycle?.ttlMs !== void 0 || lifecycle?.idleStopMs !== void 0 || lifecycle?.archiveAfterMs !== void 0 || lifecycle?.deleteAfterMs !== void 0);
+function validateSandboxCreateParams(clientProvider, params) {
+	const provider = clientProvider?.trim().toLowerCase();
+	if (!provider) return;
+	if (provider === "daytona") {
+		if (params.lifecycle?.ttlMs !== void 0) throw createValidationError$1("`lifecycle.ttlMs` is not supported by the Daytona sandbox client. Use `startupTimeoutMs` for creation readiness and Daytona lifecycle fields like `idleStopMs`, `archiveAfterMs`, or `deleteAfterMs` instead.", "plugins.sandbox.createConfig.lifecycle.ttlMs");
+		return;
+	}
+	if (provider === "e2b") {
+		if (params.startupTimeoutMs !== void 0) throw createValidationError$1("`startupTimeoutMs` is not supported by the E2B sandbox client. Use `lifecycle.ttlMs` to control sandbox lifetime.", "plugins.sandbox.createConfig.startupTimeoutMs");
+		if (params.lifecycle?.idleStopMs !== void 0 || params.lifecycle?.archiveAfterMs !== void 0 || params.lifecycle?.deleteAfterMs !== void 0) throw createValidationError$1("`lifecycle.idleStopMs`, `lifecycle.archiveAfterMs`, and `lifecycle.deleteAfterMs` are not supported by the E2B sandbox client.", "plugins.sandbox.createConfig.lifecycle");
+		return;
+	}
+	if (hasLifecycleValues(params.lifecycle) || params.startupTimeoutMs !== void 0) return;
+}
+/** Validates `sandbox` configuration. */
+function validateSandboxConfig(config) {
 	const client = config.client;
-	if (!client || typeof client !== "object") throw createValidationError$1("`sandboxPlugin` requires a `client`.", "plugins.sandboxPlugin");
-	if (config.prefix !== void 0 && config.prefix.trim().length === 0) throw createValidationError$1("`sandboxPlugin` requires `prefix` to be a non-empty string when provided.", "plugins.sandboxPlugin");
+	if (!client || typeof client !== "object") throw createValidationError$1("`sandbox` requires a `client`.", "plugins.sandbox");
+	if (config.prefix !== void 0 && config.prefix.trim().length === 0) throw createValidationError$1("`sandbox` requires `prefix` to be a non-empty string when provided.", "plugins.sandbox");
+	if (config.createConfig) validateSandboxCreateParams(config.client.provider, config.createConfig);
+	if (config.createDefaults) validateSandboxCreateParams(config.client.provider, config.createDefaults);
 }
 
 //#endregion
@@ -983,10 +924,29 @@ const createValidationError = (message, at, context) => BetterAgentError.fromCod
 	...context !== void 0 ? { context } : {},
 	trace: [{ at }]
 });
+const resolveCreateParams = (overrides, createConfig, createDefaults) => ({
+	template: createConfig?.template ?? overrides?.template ?? createDefaults?.template,
+	startupTimeoutMs: createConfig?.startupTimeoutMs ?? overrides?.startupTimeoutMs ?? createDefaults?.startupTimeoutMs,
+	envs: createDefaults?.envs || overrides?.envs || createConfig?.envs ? {
+		...createDefaults?.envs ?? {},
+		...overrides?.envs ?? {},
+		...createConfig?.envs ?? {}
+	} : void 0,
+	metadata: createDefaults?.metadata || overrides?.metadata || createConfig?.metadata ? {
+		...createDefaults?.metadata ?? {},
+		...overrides?.metadata ?? {},
+		...createConfig?.metadata ?? {}
+	} : void 0,
+	lifecycle: createDefaults?.lifecycle || overrides?.lifecycle || createConfig?.lifecycle ? {
+		...createDefaults?.lifecycle ?? {},
+		...overrides?.lifecycle ?? {},
+		...createConfig?.lifecycle ?? {}
+	} : void 0
+});
 /**
 * Adds sandbox tools.
 *
-* By default, the plugin reuses one sandbox per `conversationId`.
+* By default, the plugin reuses one sandbox per `threadId`.
 * Use `sessionKey` to customize reuse, or return `null`/`undefined`
 * to disable reuse for a specific tool call.
 *
@@ -994,31 +954,33 @@ const createValidationError = (message, at, context) => BetterAgentError.fromCod
 *
 * @example
 * ```ts
-* import { sandboxPlugin, createE2BSandboxClient } from "@better-agent/plugins";
+* import { sandbox, createE2BSandboxClient } from "@better-agent/plugins";
 *
-* const plugin = sandboxPlugin({
+* const plugin = sandbox({
 *   client: createE2BSandboxClient({
 *     apiKey: process.env.E2B_API_KEY,
 *   }),
-*   defaults: {
+*   createConfig: {
 *     template: "base",
-*     timeoutMs: 10 * 60_000,
+*   },
+*   createDefaults: {
+*     startupTimeoutMs: 90_000,
 *   },
 * });
 * ```
 */
-const sandboxPlugin = (config) => {
-	validateSandboxPluginConfig(config);
-	const sandboxClient = config.client;
-	const store = config.store ?? createMemorySandboxSessionStore();
-	const prefix = trimToUndefined(config.prefix) ?? "sandbox";
+const sandbox = (pluginConfig) => {
+	validateSandboxConfig(pluginConfig);
+	const sandboxClient = pluginConfig.client;
+	const store = pluginConfig.store ?? createMemorySandboxSessionStore();
+	const prefix = trimToUndefined(pluginConfig.prefix) ?? "sandbox";
 	const nameFor = (suffix) => `${prefix}_${suffix}`;
 	const getSessionPolicy = (ctx, toolName) => {
-		if (config.sessionKey) {
-			const custom = trimToUndefined(config.sessionKey({
+		if (pluginConfig.sessionKey) {
+			const custom = trimToUndefined(pluginConfig.sessionKey({
 				runId: ctx.runId,
-				agentName: ctx.agentName,
-				...ctx.conversationId !== void 0 ? { conversationId: ctx.conversationId } : {},
+				agentName: ctx.agentName ?? "",
+				...ctx.threadId !== void 0 ? { threadId: ctx.threadId } : {},
 				toolName
 			}) ?? void 0);
 			return custom !== void 0 ? {
@@ -1026,25 +988,22 @@ const sandboxPlugin = (config) => {
 				sessionKey: custom
 			} : { kind: "disabled" };
 		}
-		return ctx.conversationId ? {
+		return ctx.threadId ? {
 			kind: "managed",
-			sessionKey: `conversation:${ctx.conversationId}`
+			sessionKey: `thread:${ctx.threadId}`
 		} : { kind: "disabled" };
 	};
 	const getExplicitSandboxId = (value) => {
 		if (value === void 0) return;
 		const trimmed = value.trim();
-		if (!trimmed) throw createValidationError("`sandboxId` must be a non-empty string when provided.", "plugins.sandboxPlugin.sandboxId");
+		if (!trimmed) throw createValidationError("`sandboxId` must be a non-empty string when provided.", "plugins.sandbox.sandboxId");
 		return trimmed;
 	};
 	const createSandbox = async (params, ctx, toolName) => {
 		const sessionPolicy = getSessionPolicy(ctx, toolName);
-		const created = await sandboxClient.createSandbox({
-			template: params?.template ?? config.defaults?.template,
-			timeoutMs: params?.timeoutMs ?? config.defaults?.timeoutMs,
-			envs: params?.envs ?? config.defaults?.envs,
-			metadata: params?.metadata ?? config.defaults?.metadata
-		});
+		const resolvedParams = resolveCreateParams(params, pluginConfig.createConfig, pluginConfig.createDefaults);
+		validateSandboxCreateParams(sandboxClient.provider, resolvedParams);
+		const created = await sandboxClient.createSandbox(resolvedParams);
 		if (sessionPolicy.kind === "managed") await store.set(sessionPolicy.sessionKey, created.sandboxId);
 		return {
 			sandboxId: created.sandboxId,
@@ -1067,10 +1026,9 @@ const sandboxPlugin = (config) => {
 				created: false
 			};
 		}
-		if (!params.createIfMissing) throw createValidationError(`No sandbox is available for this ${params.ctx.conversationId ? "conversation" : "run"}. Create one first with '${nameFor("create")}' or pass a sandboxId explicitly.`, "plugins.sandboxPlugin.resolveSandbox.missing", {
+		if (!params.createIfMissing) throw createValidationError(`No sandbox is available for this ${params.ctx.threadId ? "thread" : "run"}. Create one first with '${nameFor("create")}' or pass a sandboxId explicitly.`, "plugins.sandbox.resolveSandbox.missing", {
 			runId: params.ctx.runId,
-			agentName: params.ctx.agentName,
-			conversationId: params.ctx.conversationId,
+			threadId: params.ctx.threadId,
 			toolName: params.toolName
 		});
 		return await createSandbox(params.createParams, params.ctx, params.toolName);
@@ -1088,7 +1046,7 @@ const sandboxPlugin = (config) => {
 		properties: {
 			forceNew: { type: "boolean" },
 			template: { type: "string" },
-			timeoutMs: {
+			startupTimeoutMs: {
 				type: "number",
 				exclusiveMinimum: 0
 			},
@@ -1099,6 +1057,28 @@ const sandboxPlugin = (config) => {
 			metadata: {
 				type: "object",
 				additionalProperties: { type: "string" }
+			},
+			lifecycle: {
+				type: "object",
+				properties: {
+					ttlMs: {
+						type: "number",
+						exclusiveMinimum: 0
+					},
+					idleStopMs: {
+						type: "number",
+						exclusiveMinimum: 0
+					},
+					archiveAfterMs: {
+						type: "number",
+						exclusiveMinimum: 0
+					},
+					deleteAfterMs: {
+						type: "number",
+						exclusiveMinimum: 0
+					}
+				},
+				additionalProperties: false
 			}
 		},
 		additionalProperties: false
@@ -1108,12 +1088,16 @@ const sandboxPlugin = (config) => {
 		type: "string",
 		minLength: 1
 	};
-	const tools = [
-		defineTool({
-			name: nameFor("create"),
-			description: "Create a sandbox, or reuse the current conversation sandbox unless forceNew is true.",
-			schema: createSchema
-		}).server(async (input, ctx) => {
+	const envsSchema = {
+		type: "object",
+		additionalProperties: { type: "string" }
+	};
+	const createTool = defineTool({
+		name: nameFor("create"),
+		description: "Create a sandbox, or reuse the current thread sandbox unless forceNew is true.",
+		target: "server",
+		inputSchema: createSchema,
+		execute: async (input, ctx) => {
 			if (!input.forceNew) {
 				const sessionPolicy = getSessionPolicy(ctx, nameFor("create"));
 				if (sessionPolicy.kind === "managed") {
@@ -1128,9 +1112,10 @@ const sandboxPlugin = (config) => {
 			}
 			const resolved = await createSandbox({
 				template: input.template,
-				timeoutMs: input.timeoutMs,
+				startupTimeoutMs: input.startupTimeoutMs,
 				envs: input.envs,
-				metadata: input.metadata
+				metadata: input.metadata,
+				lifecycle: input.lifecycle
 			}, ctx, nameFor("create"));
 			return {
 				sandboxId: resolved.sandboxId,
@@ -1138,33 +1123,32 @@ const sandboxPlugin = (config) => {
 				created: true,
 				...resolved.sessionKey !== void 0 ? { sessionKey: resolved.sessionKey } : {}
 			};
-		}),
-		defineTool({
-			name: nameFor("exec"),
-			description: "Run one shell command inside a sandbox. Creates a sandbox automatically when none exists for the conversation.",
-			schema: {
-				type: "object",
-				properties: {
-					sandboxId: sandboxIdSchema,
-					cmd: {
-						type: "string",
-						minLength: 1
-					},
-					cwd: { type: "string" },
-					timeoutMs: {
-						type: "number",
-						exclusiveMinimum: 0
-					},
-					envs: {
-						type: "object",
-						additionalProperties: { type: "string" }
-					}
+		}
+	});
+	const execTool = defineTool({
+		name: nameFor("exec"),
+		description: "Run one shell command inside a sandbox. Creates a sandbox automatically when none exists for the thread.",
+		target: "server",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sandboxId: sandboxIdSchema,
+				cmd: {
+					type: "string",
+					minLength: 1
 				},
-				required: ["cmd"],
-				additionalProperties: false
+				cwd: { type: "string" },
+				timeoutMs: {
+					type: "number",
+					exclusiveMinimum: 0
+				},
+				envs: envsSchema
 			},
-			approval: config.approvals?.exec
-		}).server(async (input, ctx) => {
+			required: ["cmd"],
+			additionalProperties: false
+		},
+		approval: pluginConfig.approvals?.exec,
+		execute: async (input, ctx) => {
 			const resolved = await resolveSandbox({
 				sandboxId: input.sandboxId,
 				createIfMissing: true,
@@ -1183,20 +1167,22 @@ const sandboxPlugin = (config) => {
 				createdSandbox: resolved.created,
 				...result
 			};
-		}),
-		defineTool({
-			name: nameFor("read_file"),
-			description: "Read one text file from a sandbox. Creates a sandbox automatically when none exists for the conversation.",
-			schema: {
-				type: "object",
-				properties: {
-					sandboxId: sandboxIdSchema,
-					path: pathSchema
-				},
-				required: ["path"],
-				additionalProperties: false
-			}
-		}).server(async (input, ctx) => {
+		}
+	});
+	const readFileTool = defineTool({
+		name: nameFor("read_file"),
+		description: "Read one text file from a sandbox. Creates a sandbox automatically when none exists for the thread.",
+		target: "server",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sandboxId: sandboxIdSchema,
+				path: pathSchema
+			},
+			required: ["path"],
+			additionalProperties: false
+		},
+		execute: async (input, ctx) => {
 			const resolved = await resolveSandbox({
 				sandboxId: input.sandboxId,
 				createIfMissing: true,
@@ -1211,22 +1197,24 @@ const sandboxPlugin = (config) => {
 					path: input.path
 				})
 			};
-		}),
-		defineTool({
-			name: nameFor("write_file"),
-			description: "Write one text file into a sandbox. Creates a sandbox automatically when none exists for the conversation.",
-			schema: {
-				type: "object",
-				properties: {
-					sandboxId: sandboxIdSchema,
-					path: pathSchema,
-					content: { type: "string" }
-				},
-				required: ["path", "content"],
-				additionalProperties: false
+		}
+	});
+	const writeFileTool = defineTool({
+		name: nameFor("write_file"),
+		description: "Write one text file into a sandbox. Creates a sandbox automatically when none exists for the thread.",
+		target: "server",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sandboxId: sandboxIdSchema,
+				path: pathSchema,
+				content: { type: "string" }
 			},
-			approval: config.approvals?.writeFile
-		}).server(async (input, ctx) => {
+			required: ["path", "content"],
+			additionalProperties: false
+		},
+		approval: pluginConfig.approvals?.writeFile,
+		execute: async (input, ctx) => {
 			const resolved = await resolveSandbox({
 				sandboxId: input.sandboxId,
 				createIfMissing: true,
@@ -1243,20 +1231,22 @@ const sandboxPlugin = (config) => {
 				createdSandbox: resolved.created,
 				path: result.path
 			};
-		}),
-		defineTool({
-			name: nameFor("list_files"),
-			description: "List directory entries inside a sandbox. Creates a sandbox automatically when none exists for the conversation.",
-			schema: {
-				type: "object",
-				properties: {
-					sandboxId: sandboxIdSchema,
-					path: pathSchema
-				},
-				required: ["path"],
-				additionalProperties: false
-			}
-		}).server(async (input, ctx) => {
+		}
+	});
+	const listFilesTool = defineTool({
+		name: nameFor("list_files"),
+		description: "List directory entries inside a sandbox. Creates a sandbox automatically when none exists for the thread.",
+		target: "server",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sandboxId: sandboxIdSchema,
+				path: pathSchema
+			},
+			required: ["path"],
+			additionalProperties: false
+		},
+		execute: async (input, ctx) => {
 			const resolved = await resolveSandbox({
 				sandboxId: input.sandboxId,
 				createIfMissing: true,
@@ -1271,20 +1261,22 @@ const sandboxPlugin = (config) => {
 					path: input.path
 				})
 			};
-		}),
-		defineTool({
-			name: nameFor("make_dir"),
-			description: "Create a directory inside a sandbox. Creates a sandbox automatically when none exists for the conversation.",
-			schema: {
-				type: "object",
-				properties: {
-					sandboxId: sandboxIdSchema,
-					path: pathSchema
-				},
-				required: ["path"],
-				additionalProperties: false
-			}
-		}).server(async (input, ctx) => {
+		}
+	});
+	const makeDirTool = defineTool({
+		name: nameFor("make_dir"),
+		description: "Create a directory inside a sandbox. Creates a sandbox automatically when none exists for the thread.",
+		target: "server",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sandboxId: sandboxIdSchema,
+				path: pathSchema
+			},
+			required: ["path"],
+			additionalProperties: false
+		},
+		execute: async (input, ctx) => {
 			const resolved = await resolveSandbox({
 				sandboxId: input.sandboxId,
 				createIfMissing: true,
@@ -1300,21 +1292,23 @@ const sandboxPlugin = (config) => {
 				path: input.path,
 				created: result.created
 			};
-		}),
-		defineTool({
-			name: nameFor("remove_path"),
-			description: "Remove a file or directory from a sandbox.",
-			schema: {
-				type: "object",
-				properties: {
-					sandboxId: sandboxIdSchema,
-					path: pathSchema
-				},
-				required: ["path"],
-				additionalProperties: false
+		}
+	});
+	const removePathTool = defineTool({
+		name: nameFor("remove_path"),
+		description: "Remove a file or directory from a sandbox.",
+		target: "server",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sandboxId: sandboxIdSchema,
+				path: pathSchema
 			},
-			approval: config.approvals?.removePath
-		}).server(async (input, ctx) => {
+			required: ["path"],
+			additionalProperties: false
+		},
+		approval: pluginConfig.approvals?.removePath,
+		execute: async (input, ctx) => {
 			const resolved = await resolveSandbox({
 				sandboxId: input.sandboxId,
 				createIfMissing: false,
@@ -1330,24 +1324,26 @@ const sandboxPlugin = (config) => {
 				removed: true,
 				path: input.path
 			};
-		}),
-		defineTool({
-			name: nameFor("get_host"),
-			description: "Expose one sandbox port as a host URL so callers can reach an app running inside the sandbox.",
-			schema: {
-				type: "object",
-				properties: {
-					sandboxId: sandboxIdSchema,
-					port: {
-						type: "number",
-						minimum: 1,
-						maximum: 65535
-					}
-				},
-				required: ["port"],
-				additionalProperties: false
-			}
-		}).server(async (input, ctx) => {
+		}
+	});
+	const getHostTool = defineTool({
+		name: nameFor("get_host"),
+		description: "Expose one sandbox port as a host URL so callers can reach an app running inside the sandbox.",
+		target: "server",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sandboxId: sandboxIdSchema,
+				port: {
+					type: "number",
+					minimum: 1,
+					maximum: 65535
+				}
+			},
+			required: ["port"],
+			additionalProperties: false
+		},
+		execute: async (input, ctx) => {
 			const resolved = await resolveSandbox({
 				sandboxId: input.sandboxId,
 				createIfMissing: false,
@@ -1366,17 +1362,19 @@ const sandboxPlugin = (config) => {
 				host,
 				...preview?.token !== void 0 ? { token: preview.token } : {}
 			};
-		}),
-		defineTool({
-			name: nameFor("kill"),
-			description: "Terminate a sandbox and clear the current conversation sandbox when applicable.",
-			schema: {
-				type: "object",
-				properties: { sandboxId: sandboxIdSchema },
-				additionalProperties: false
-			},
-			approval: config.approvals?.killSandbox
-		}).server(async (input, ctx) => {
+		}
+	});
+	const killTool = defineTool({
+		name: nameFor("kill"),
+		description: "Terminate a sandbox and clear the current thread sandbox when applicable.",
+		target: "server",
+		inputSchema: {
+			type: "object",
+			properties: { sandboxId: sandboxIdSchema },
+			additionalProperties: false
+		},
+		approval: pluginConfig.approvals?.killSandbox,
+		execute: async (input, ctx) => {
 			const resolved = await resolveSandbox({
 				sandboxId: input.sandboxId,
 				createIfMissing: false,
@@ -1390,14 +1388,26 @@ const sandboxPlugin = (config) => {
 				killed: true,
 				...clearedSessionKey !== void 0 ? { clearedSessionKey } : {}
 			};
-		})
+		}
+	});
+	const toAnyTool = (tool) => tool;
+	const tools = [
+		toAnyTool(createTool),
+		toAnyTool(execTool),
+		toAnyTool(readFileTool),
+		toAnyTool(writeFileTool),
+		toAnyTool(listFilesTool),
+		toAnyTool(makeDirTool),
+		toAnyTool(removePathTool),
+		toAnyTool(getHostTool),
+		toAnyTool(killTool)
 	];
 	return {
-		id: config.id ?? "sandbox",
+		id: pluginConfig.id ?? "sandbox",
 		tools
 	};
 };
 
 //#endregion
-export { authPlugin, createDaytonaSandboxClient, createE2BSandboxClient, createMemorySandboxSessionStore, ipAllowlistPlugin, loggingPlugin, rateLimitPlugin, sandboxPlugin };
+export { createDaytonaSandboxClient, createE2BSandboxClient, createMemorySandboxSessionStore, ipAllowlist, logging, rateLimit, sandbox };
 //# sourceMappingURL=index.mjs.map