@workerdeck/core 0.22.0 → 0.23.0

package/build/index.d.mts

@@ -510,7 +510,21 @@ type AiSdkRunnerConfig = Omit<CreateSessionRequest, 'cwd'> & {
     timeoutMs?: number;
     memoryLimitBytes?: number;
   }; /** Which backend the executor represents, for `execution_dispatched` events. */
-  executionBackend?: ToolExecutionBackend; /** Swap models mid-session (`set_model`). Unset = setModel() is rejected. */
+  executionBackend?: ToolExecutionBackend;
+  /**
+   * Decide per call whether the user must approve a tool execution before it
+   * dispatches. When the session's permission mode is `'default'` and this
+   * callback returns `true`, the runner emits `permission_requested`, parks,
+   * and waits for {@link AiSdkRunner.resolvePermission}. Modes
+   * `'bypassPermissions'` and `'dontAsk'` skip the check entirely.
+   *
+   * Unset = every tool dispatches immediately (the pre-§7 behavior).
+   */
+  shouldApprove?: (call: {
+    toolName: string;
+    input: unknown;
+  }) => boolean; /** Timeout for permission prompts, in ms. Default 120 000 (2 min). */
+  approvalTimeoutMs?: number; /** Swap models mid-session (`set_model`). Unset = setModel() is rejected. */
   resolveModel?: (modelId: string | undefined) => LanguageModel$1;
   /**
    * Live MCP status for this session, when the host wired MCP at all. Unlike
@@ -656,7 +670,7 @@ declare class AiSdkRunner implements Runner {
   resolveToolCall(toolCallId: string, output: ToolCallOutput, options?: {
     isError?: boolean;
   }): boolean;
-  resolvePermission(_requestId: string, _decision: PermissionDecision): boolean;
+  resolvePermission(requestId: string, decision: PermissionDecision): boolean;
   /** Emit `file_delivered` — the deliver_file tool's hand-over event (wired by
    * createEngineSession via ToolContextOptions.onFileDelivered). */
   emitFileDelivered(file: {
@@ -1114,9 +1128,21 @@ type EngineSessionOptions = {
    * Executor for sandboxed tools. Return the browser bridge when a client is
    * attached and the server sandbox otherwise; the seam makes them
    * interchangeable, so this is the only place the choice is made.
+   *
+   * A function accepting a {@link ToolExecutionCall} selects **per call**:
+   * `eval_script` may run on the in-process sandbox while a custom tool goes
+   * to the browser, with no coupling between them.
    */
-  selectExecutor: () => ToolExecutor; /** Which backend `selectExecutor` returned, for the execution_* events. */
-  backend?: 'server' | 'browser' | 'managed' | 'remote'; /** Backends for the granted capabilities. Omitted ones are simply not granted. */
+  selectExecutor: (() => ToolExecutor) | ((call: ToolExecutionCall) => ToolExecutor);
+  /**
+   * Which backend `selectExecutor` returned, for the `execution_dispatched`
+   * events. A function returns the backend per call — pair it with a per-call
+   * `selectExecutor` so the event matches the executor that actually ran.
+   *
+   * When `selectExecutor` is per-call and `backend` is static, every call is
+   * reported under one label. When omitted, falls back to `'server'`.
+   */
+  backend?: 'server' | 'browser' | 'managed' | 'remote' | ((call: ToolExecutionCall) => 'server' | 'browser' | 'managed' | 'remote'); /** Backends for the granted capabilities. Omitted ones are simply not granted. */
   capabilities?: {
     search?: ToolContextOptions['search'];
     download?: ToolContextOptions['download'];
@@ -1175,6 +1201,21 @@ type EngineSessionOptions = {
     timeoutMs?: number;
     memoryLimitBytes?: number;
   };
+  /**
+   * Gate tool execution behind user approval. When this returns `true` for a
+   * given call and the session's permission mode is `'default'`, the runner
+   * emits `permission_requested` and waits for the user to approve or deny
+   * before dispatching. Bypass modes skip the check entirely.
+   *
+   * By default nothing requires approval — tools dispatch as soon as the model
+   * calls them, which is the right call for trusted pipelines and the pre-§7
+   * behavior.
+   */
+  shouldApprove?: (call: {
+    toolName: string;
+    input: unknown;
+  }) => boolean; /** Timeout for permission prompts (ms). Default 120 000. */
+  approvalTimeoutMs?: number;
   /**
    * Initial scratch-filesystem contents for a **new** session, and the safe way
    * to seed one: it is ignored outright when `config.restore` is set, because a

package/build/index.mjs

@@ -1899,6 +1899,8 @@ var AiSdkRunner = class {
 	/** Model alias as requested (not the resolved provider id) — what set_model was
 	* given, so a rehydrated session can re-resolve the same choice. */
 	#modelAlias;
+	/** Permission prompts awaiting a client decision. Keyed by request id. */
+	#pendingApprovals = /* @__PURE__ */ new Map();
 	constructor(config, id = randomUUID()) {
 		const mode = config.permissionMode ?? "default";
 		if (!SUPPORTED_PERMISSION_MODES.includes(mode)) throw new Error(`permission mode '${mode}' is not supported by the AI SDK engine`);
@@ -1957,7 +1959,7 @@ var AiSdkRunner = class {
 		return [...this.#pendingToolCalls.values()];
 	}
 	get pendingApprovals() {
-		return [];
+		return [...this.#pendingApprovals.values()].map((a) => a.request);
 	}
 	/** The session's scratch filesystem (see Runner.vfs) — the server's file
 	* routes serve deliverables straight from it. */
@@ -1971,14 +1973,17 @@ var AiSdkRunner = class {
 			cwd: this.#config.cwd ?? "",
 			profile: this.#config.profile,
 			engine: "provider",
-			capabilities: ENGINE_CAPABILITIES.provider,
+			capabilities: this.#config.shouldApprove ? {
+				...ENGINE_CAPABILITIES.provider,
+				interactiveApprovals: true
+			} : ENGINE_CAPABILITIES.provider,
 			model: this.#modelId(),
 			permissionMode: this.#permissionMode,
 			createdAt: this.createdAt,
 			lastSeq: this.#seq,
 			activityCount: this.#activityCount,
 			contextUsage: this.#contextUsage,
-			pendingPermissionCount: 0,
+			pendingPermissionCount: this.#pendingApprovals.size,
 			meta: this.#config.meta,
 			scope: this.#config.scope,
 			title: this.#title(),
@@ -2163,8 +2168,38 @@ var AiSdkRunner = class {
 		});
 		return true;
 	}
-	resolvePermission(_requestId, _decision) {
-		return false;
+	resolvePermission(requestId, decision) {
+		const approval = this.#pendingApprovals.get(requestId);
+		if (!approval) return false;
+		clearTimeout(approval.timer);
+		this.#pendingApprovals.delete(requestId);
+		const source = "client";
+		if (decision.behavior === "allow") {
+			this.#emit({
+				type: "permission_resolved",
+				requestId,
+				behavior: "allow",
+				resolvedBy: source
+			});
+			this.#dispatchSingle(approval.toolCallId);
+		} else {
+			const message = decision.message ?? "Permission denied by user";
+			this.#emit({
+				type: "permission_resolved",
+				requestId,
+				behavior: "deny",
+				resolvedBy: source,
+				message
+			});
+			this.#applyExecutionResult(approval.toolCallId, {
+				status: "failed",
+				reason: "permission_denied",
+				error: message
+			});
+			if (decision.interrupt) this.interrupt();
+		}
+		if (this.#pendingApprovals.size === 0 && this.#pendingToolCalls.size === 0) {}
+		return true;
 	}
 	/** Emit `file_delivered` — the deliver_file tool's hand-over event (wired by
 	* createEngineSession via ToolContextOptions.onFileDelivered). */
@@ -2283,6 +2318,8 @@ var AiSdkRunner = class {
 		this.#abort?.abort();
 		this.#pendingToolCalls.clear();
 		this.#dispatched.clear();
+		for (const { timer } of this.#pendingApprovals.values()) clearTimeout(timer);
+		this.#pendingApprovals.clear();
 		this.#emit({
 			type: "session_closed",
 			reason
@@ -2315,50 +2352,111 @@ var AiSdkRunner = class {
 		this.#applyExecutionResult(executionId, result);
 		return true;
 	}
-	/** Hand every parked call the executor owns to it. */
+	/** Hand every parked call the executor owns to it, gating on approval when
+	* the permission mode requires it. */
 	#dispatchPending() {
 		const executor = this.#config.executor;
 		if (!executor) return;
 		const executable = this.#config.executableTools;
+		const needsApproval = this.#permissionMode === "default" && this.#config.shouldApprove;
 		const inFlight = [];
 		let anyDeferred = false;
+		let anyAwaiting = false;
 		for (const call of Array.from(this.#pendingToolCalls.values())) {
 			if (executable && !executable.includes(call.toolName)) continue;
 			if (this.#dispatched.has(call.toolCallId)) continue;
-			this.#dispatched.add(call.toolCallId);
-			const toolCall = {
-				executionId: call.toolCallId,
-				sessionId: this.id,
-				tool: call.toolName,
-				input: call.input,
-				vfs: this.#config.vfs,
-				limits: this.#config.executionLimits,
-				signal: this.#abort?.signal
-			};
-			const profile = executor.describe?.(toolCall) ?? {};
-			call.deferred = profile.deferred === true ? true : void 0;
-			call.expiresAt = profile.timeoutMs === void 0 ? void 0 : Date.now() + profile.timeoutMs;
-			anyDeferred ||= call.deferred === true;
-			this.#emit({
-				type: "execution_dispatched",
-				executionId: call.toolCallId,
+			if (needsApproval && needsApproval({
 				toolName: call.toolName,
-				backend: profile.backend ?? this.#config.executionBackend ?? "server",
-				deferred: call.deferred,
-				expiresAt: call.expiresAt
-			});
-			inFlight.push(executor.dispatch(toolCall).then((dispatch) => {
-				if (dispatch.status === "settled") this.#applyExecutionResult(call.toolCallId, dispatch.result);
-			}).catch((error) => {
-				this.#applyExecutionResult(call.toolCallId, {
-					status: "failed",
-					reason: "dispatch_error",
-					error: error instanceof Error ? error.message : String(error)
+				input: call.input
+			})) {
+				if ([...this.#pendingApprovals.values()].some((a) => a.toolCallId === call.toolCallId)) {
+					anyAwaiting = true;
+					continue;
+				}
+				const requestId = randomUUID();
+				const timeoutMs = this.#config.approvalTimeoutMs ?? 12e4;
+				const request = {
+					id: requestId,
+					toolName: call.toolName,
+					input: call.input,
+					toolUseId: call.toolCallId,
+					title: `Agent wants to run ${call.toolName}`,
+					displayName: call.toolName,
+					expiresAt: Date.now() + timeoutMs
+				};
+				const timer = setTimeout(() => {
+					if (!this.#pendingApprovals.has(requestId)) return;
+					this.resolvePermission(requestId, {
+						behavior: "deny",
+						message: "Approval timed out"
+					});
+				}, timeoutMs);
+				this.#pendingApprovals.set(requestId, {
+					request,
+					toolCallId: call.toolCallId,
+					timer
 				});
-			}));
+				this.#emit({
+					type: "permission_requested",
+					request
+				});
+				anyAwaiting = true;
+				continue;
+			}
+			this.#dispatched.add(call.toolCallId);
+			const dispatched = this.#dispatchCall(executor, call);
+			anyDeferred ||= dispatched.deferred;
+			inFlight.push(dispatched.promise);
 		}
+		if (anyAwaiting) this.#setStatus("awaiting_approval");
 		if (anyDeferred) Promise.allSettled(inFlight).then(() => this.#announceParked());
 	}
+	/** Dispatch a single tool call that was held behind an approval gate. */
+	#dispatchSingle(toolCallId) {
+		const executor = this.#config.executor;
+		if (!executor) return;
+		const call = this.#pendingToolCalls.get(toolCallId);
+		if (!call || this.#dispatched.has(toolCallId)) return;
+		this.#dispatched.add(toolCallId);
+		const dispatched = this.#dispatchCall(executor, call);
+		if (dispatched.deferred) dispatched.promise.then(() => this.#announceParked());
+	}
+	/** The actual dispatch + event emission for one tool call. */
+	#dispatchCall(executor, call) {
+		const toolCall = {
+			executionId: call.toolCallId,
+			sessionId: this.id,
+			tool: call.toolName,
+			input: call.input,
+			vfs: this.#config.vfs,
+			limits: this.#config.executionLimits,
+			signal: this.#abort?.signal
+		};
+		const profile = executor.describe?.(toolCall) ?? {};
+		call.deferred = profile.deferred === true ? true : void 0;
+		call.expiresAt = profile.timeoutMs === void 0 ? void 0 : Date.now() + profile.timeoutMs;
+		this.#emit({
+			type: "execution_dispatched",
+			executionId: call.toolCallId,
+			toolName: call.toolName,
+			backend: profile.backend ?? this.#config.executionBackend ?? "server",
+			deferred: call.deferred,
+			expiresAt: call.expiresAt
+		});
+		const promise = executor.dispatch(toolCall).then((dispatch) => {
+			if (dispatch.status === "settled") this.#applyExecutionResult(call.toolCallId, dispatch.result);
+		}).catch((error) => {
+			this.#applyExecutionResult(call.toolCallId, {
+				status: "failed",
+				reason: "dispatch_error",
+				error: error instanceof Error ? error.message : String(error)
+			});
+		});
+		return {
+			deferred: call.deferred === true,
+			promise
+		};
+	}
 	/**
 	* The turn has come to rest on deferred executions: nothing is in flight, and
 	* only a host-delivered result can move it. `status_changed: 'parked'` is the
@@ -3579,7 +3677,19 @@ const CAPABILITY_TOOLS = {
 */
 function createEngineSession(options) {
 	const vfs = options.config.vfs ?? createVfs(options.config.restore ? options.config.restore.vfs : options.seedVfs);
-	const executor = options.selectExecutor();
+	const executor = options.selectExecutor.length > 0 ? {
+		describe(call) {
+			const target = options.selectExecutor(call);
+			const backend = typeof options.backend === "function" ? options.backend(call) : options.backend;
+			return {
+				...target.describe?.(call),
+				...backend ? { backend } : {}
+			};
+		},
+		dispatch(call) {
+			return options.selectExecutor(call).dispatch(call);
+		}
+	} : options.selectExecutor();
 	const granted = options.config.capabilities ?? options.profile?.session?.capabilities;
 	const isGranted = (key) => granted === void 0 || granted.includes(CAPABILITY_TOOLS[key]);
 	let runner;
@@ -3613,8 +3723,10 @@ function createEngineSession(options) {
 		vfs,
 		executor,
 		executableTools: context.sandboxedToolNames,
-		executionBackend: options.backend ?? "server",
+		executionBackend: typeof options.backend === "function" ? void 0 : options.backend ?? "server",
 		executionLimits: options.executionLimits,
+		shouldApprove: options.shouldApprove,
+		approvalTimeoutMs: options.approvalTimeoutMs,
 		reportMcpServers: options.mcp ? () => Promise.resolve(declaredServers === void 0 ? options.mcp.servers : options.mcp.servers.filter((s) => declaredServers.includes(s.name))) : void 0
 	}, options.id);
 	return runner;