libre-webui 0.29.0 → 0.31.0

package/backend/dist/services/workAgentService.js

@@ -18,6 +18,9 @@ import workModelProviderService, { WORK_TOOL_ARGUMENTS_ERROR_METADATA_KEY, WORK_
 import workEventService from './workEventService.js';
 import { buildWorkAgentSystemPrompt, buildWorkBudgetExhaustionPrompt, buildWorkComputerAmbiguityPrompt, buildWorkComputerStallPrompt, buildWorkEmptyRoundNudgePrompt, buildWorkScreenshotsUnsupportedPrompt, buildWorkStatusBlurbPrompt, workAgentSkillsForContext, WORK_WRITE_FILE_RECOMMENDED_CHARS, workToolCallBudget, } from './workAgentGuidance.js';
 import workPolicyService from './workPolicyService.js';
+import workApprovalService, { GATED_WORK_TOOLS, } from './workApprovalService.js';
+import { actorCanUseTools, buildToolCatalog, executeToolCall, } from './toolGatewayService.js';
+import { getToolServer, hasToolServerCredential } from './toolServerService.js';
 import workRuntimeService, { WORK_COMPUTER_ACTION_LIMIT, } from './workRuntimeService.js';
 import workScreenControlService, { WORK_SCREEN_ASSIST_TIMEOUT_MS, } from './workScreenControlService.js';
 import workComputerTeachService from './workComputerTeachService.js';
@@ -91,6 +94,31 @@ export const WORK_WEB_SEARCH_TOOL_SCHEMA = functionTool('web_search', 'Search th
         description: "Optional result count. Defaults to 5, capped by the server's configured limit.",
     },
 }, ['query']);
+const externalToolSchema = (tool) => ({
+    type: 'function',
+    function: {
+        name: tool.name,
+        description: tool.description ??
+            `Tool ${tool.toolName} on the connected server ${tool.serverName ?? tool.serverId ?? ''}`.trim(),
+        parameters: tool.paramsSchema ?? { type: 'object', properties: {} },
+    },
+});
+// How long an unanswered takeover request keeps the screen session alive
+// after its wait times out, so a user arriving late from the notification
+// still finds the screen the agent was blocked on.
+export const WORK_TAKEOVER_GRACE_MS = 15 * 60000;
+// Delegation stays shallow by design: a delegated run cannot delegate
+// further, so two agents can never ping-pong requests at each other.
+export const WORK_DELEGATION_MAX_PEERS = 12;
+const WORK_DELEGATION_MESSAGE_MAX_CHARS = 8000;
+const WORK_DELEGATION_REPORT_MAX_CHARS = 20000;
+// Offered per run, only to hired agents with at least one peer and never
+// inside a delegated run: coordination flows by messages between separate
+// sandboxes, not by shared computers.
+export const WORK_MESSAGE_AGENT_TOOL_SCHEMA = functionTool('message_agent', "Delegate a request to another of the user's hired agents by name. Asynchronous: this returns immediately, the other agent works in its own separate workspace, and its report arrives in this conversation as a message when it finishes. The other agent cannot see this conversation or this workspace.", {
+    agent: stringProperty("The target agent's exact name, as listed in your peer roster."),
+    message: stringProperty('The request to send. Include every detail the agent needs, because it cannot see this conversation.'),
+}, ['agent', 'message']);
 // Offered only when the task's policy enables the Work Computer and the
 // task has network access: the agent's eyes and hands on the GUI session.
 export const WORK_COMPUTER_TOOL_SCHEMAS = [
@@ -180,8 +208,11 @@ export const WORK_COMPUTER_TOOL_SCHEMAS = [
         reason: stringProperty('What you need the user to do on the screen, stated concretely.'),
     }, ['reason']),
 ];
-export async function workToolSchemasForTask(task) {
+export async function workToolSchemasForTask(task, options = {}) {
     const schemas = [...WORK_TOOL_SCHEMAS];
+    if (options.messageAgent === true) {
+        schemas.push(WORK_MESSAGE_AGENT_TOOL_SCHEMA);
+    }
     if (task.networkEnabled &&
         (await isWebSearchAvailable()) &&
         (await userCanUseWebSearch(await userModel.getUserById(task.userId)))) {
@@ -192,6 +223,27 @@ export async function workToolSchemasForTask(task) {
     }
     return schemas;
 }
+/** The delegation marker on the message that started a run, if any. */
+export function delegationSourceOf(messages, runId) {
+    for (const message of messages) {
+        if (message.runId !== runId || message.role !== 'user')
+            continue;
+        const delegation = message.metadata?.delegation;
+        if (!delegation || typeof delegation !== 'object')
+            continue;
+        const source = delegation;
+        if (typeof source.fromTaskId === 'string' &&
+            typeof source.fromRunId === 'string' &&
+            typeof source.fromAgent === 'string') {
+            return {
+                fromTaskId: source.fromTaskId,
+                fromRunId: source.fromRunId,
+                fromAgent: source.fromAgent,
+            };
+        }
+    }
+    return undefined;
+}
 export class WorkAgentService {
     constructor() {
         this.controllers = new Map();
@@ -515,6 +567,7 @@ export class WorkAgentService {
         const durableAttemptIdentity = String((await getDurableJobRuntime().service.getByIdempotency(userId, WORK_EXECUTE_IDEMPOTENCY_SCOPE, runId))?.attemptCount ?? 0);
         this.controllers.set(runId, controller);
         let task;
+        let runDelegation;
         let releaseExecutionLease;
         let executionContainerSettled = false;
         const settleExecutionContainer = async () => {
@@ -604,7 +657,29 @@ export class WorkAgentService {
             };
             const providerRoutingFingerprint = await workModelProviderService.getRoutingFingerprint(run.model, providerSelection, userId);
             const providerStateScope = await workModelProviderService.getResponsesStateScope(run.model, providerSelection, userId);
-            const messages = await this.contextMessages(task, roundLimit, computerAvailable, taughtSkills, providerStateScope, run, persona);
+            // A5 approvals: whether side-effecting tool calls pause for review.
+            // Resolved once per run — the policy force-flag or the task opt-in;
+            // per-call rules are re-read at gate time so an Always-allow decision
+            // takes effect on the very next call.
+            const approvalsActive = (await workPolicyService.resolve(task.policyId)).approvalsRequired ===
+                true || task.approvalsEnabled === true;
+            // A6 delegation: a run started by another agent reports back on
+            // completion and cannot delegate further (no ping-pong loops). Peers
+            // are the user's other hired agents, injected into the roster.
+            runDelegation = delegationSourceOf(await workTaskService.getMessages(taskId), runId);
+            const peerAgents = task.isAgent === true && !runDelegation
+                ? (await workTaskService.listTaskRecords(userId))
+                    .filter(record => record.isAgent && record.id !== task.id)
+                    .slice(0, WORK_DELEGATION_MAX_PEERS)
+                    .map(record => ({
+                    name: record.title,
+                    ...(record.statusBlurb ? { status: record.statusBlurb } : {}),
+                }))
+                : [];
+            // Connected tool servers (MCP/OpenAPI): resolved once per run so the
+            // offered set is stable across rounds.
+            const externalTools = await this.externalToolsForRun(task);
+            const messages = await this.contextMessages(task, roundLimit, computerAvailable, taughtSkills, providerStateScope, run, persona, approvalsActive, peerAgents, runDelegation, externalTools ? [...externalTools.byName.keys()] : []);
             let totalToolCalls = 0;
             let accumulatedInputTokens = 0;
             let accumulatedOutputTokens = 0;
@@ -680,7 +755,12 @@ export class WorkAgentService {
                     response = await workModelProviderService.generateChatStreamResponse({
                         model: run.model,
                         messages,
-                        tools: await workToolSchemasForTask(task),
+                        tools: [
+                            ...(await workToolSchemasForTask(task, {
+                                messageAgent: peerAgents.length > 0,
+                            })),
+                            ...(externalTools?.schemas ?? []),
+                        ],
                         stream: true,
                     }, providerSelection, userId, {
                         onContent: delta => contentStream.push(delta),
@@ -844,10 +924,15 @@ export class WorkAgentService {
                             sourceKey: `work-run:${runId}:completed`,
                         });
                     }
+                    await this.reportDelegationOutcome(task, runDelegation, 'completed', finalContent);
                     return;
                 }
                 const toolValidationErrors = new Map();
                 for (const call of toolCalls) {
+                    // Connected tools validate their own arguments in the gateway;
+                    // static validation only covers the built-in registry.
+                    if (externalTools?.byName.has(call.function.name))
+                        continue;
                     const validationError = validateToolCallArguments(call);
                     if (validationError)
                         toolValidationErrors.set(call, validationError);
@@ -873,8 +958,18 @@ export class WorkAgentService {
                 }
                 for (const call of toolCalls) {
                     await this.throwIfCancelled(runId, controller);
+                    const externalEntry = externalTools?.byName.get(call.function.name);
                     const toolCallMetadata = {
                         ...summarizeToolCall(call),
+                        ...(externalEntry
+                            ? {
+                                external: true,
+                                ...(externalEntry.serverName
+                                    ? { server: externalEntry.serverName }
+                                    : {}),
+                                argumentsPreview: JSON.stringify(call.function.arguments ?? {}).slice(0, 500),
+                            }
+                            : {}),
                         round: round + 1,
                     };
                     const toolCallMessage = await workTaskService.addMessage(taskId, runId, 'assistant', 'tool_call', `Calling ${call.function.name}`, toolCallMetadata);
@@ -908,14 +1003,34 @@ export class WorkAgentService {
                         if (hasInvalidToolArguments) {
                             throw new WorkAgentHttpError('This tool call was not executed because another call in the same model response had incomplete or invalid arguments. Retry the batch with smaller payloads.', 400, 'WORK_TOOL_BATCH_NOT_EXECUTED');
                         }
-                        const result = await this.executeTool(task, call, {
-                            signal: controller.signal,
-                            computer: computerContext,
-                            runId,
-                        });
-                        toolOutput = result.content;
-                        toolImages = result.images;
-                        toolMetadata = { ...toolMetadata, ...result.metadata };
+                        const approvalVerdict = approvalsActive &&
+                            (GATED_WORK_TOOLS.has(call.function.name) ||
+                                externalTools?.byName.get(call.function.name)?.sideEffect ===
+                                    true)
+                            ? await this.awaitToolApproval(task, call, toolCallMetadata, runId, userId, controller.signal, durableAttemptIdentity)
+                            : 'approved';
+                        if (approvalVerdict === 'denied') {
+                            toolOutput =
+                                'The user denied this action. Do not retry it as-is; adjust your plan or ask the user what to do instead.';
+                            toolMetadata = { ...toolMetadata, approval: 'denied' };
+                        }
+                        else if (approvalVerdict === 'expired') {
+                            toolOutput =
+                                'This action was not executed: the approval request timed out with no decision from the user.';
+                            toolMetadata = { ...toolMetadata, approval: 'expired' };
+                        }
+                        else {
+                            const result = await this.executeTool(task, call, {
+                                signal: controller.signal,
+                                computer: computerContext,
+                                runId,
+                                delegated: runDelegation !== undefined,
+                                external: externalTools,
+                            });
+                            toolOutput = result.content;
+                            toolImages = result.images;
+                            toolMetadata = { ...toolMetadata, ...result.metadata };
+                        }
                     }
                     catch (error) {
                         toolOutput =
@@ -970,6 +1085,12 @@ export class WorkAgentService {
                     // text observation, and only the most recent screenshots stay in
                     // model context so a long computer session cannot flood tokens.
                     retainRecentWorkImages(messages);
+                    // An unanswered approval hands the run off instead of burning the
+                    // remaining budget on decisions no one is there to make.
+                    if (toolMetadata.approval === 'expired') {
+                        budgetReason = 'approval-timeout';
+                        break roundLoop;
+                    }
                     if ((call.function.name === 'computer_act' ||
                         call.function.name === 'computer_observe') &&
                         typeof toolMetadata.screenshotSha256 === 'string') {
@@ -1045,7 +1166,9 @@ export class WorkAgentService {
                                     role: 'user',
                                     content: `${buildWorkBudgetExhaustionPrompt()}\n${budgetReason === 'computer-stall'
                                         ? 'The run was stopped because repeated computer actions kept producing an unchanged screen even after a recovery notice.'
-                                        : `The ${budgetReason} budget was reached.`}`,
+                                        : budgetReason === 'approval-timeout'
+                                            ? 'The run was stopped because an action was still waiting for user approval when the request timed out.'
+                                            : `The ${budgetReason} budget was reached.`}`,
                                 },
                             ],
                             tools: [],
@@ -1127,6 +1250,7 @@ export class WorkAgentService {
                     sourceKey: `work-run:${runId}:needs_input`,
                 });
             }
+            await this.reportDelegationOutcome(task, runDelegation, 'needs_input', handoffContent);
         }
         catch (error) {
             const currentRun = await workTaskService.getRun(runId);
@@ -1146,6 +1270,7 @@ export class WorkAgentService {
                                 status: 'cancelled',
                                 error: 'Cancelled by user.',
                             }, 'terminal:cancelled');
+                            await this.reportDelegationOutcome(task, runDelegation, 'cancelled');
                         }
                     }
                     catch (cleanupError) {
@@ -1171,6 +1296,9 @@ export class WorkAgentService {
                         status: 'cancelled',
                         error: 'Cancelled by user.',
                     }, 'terminal:cancelled');
+                    if (task) {
+                        await this.reportDelegationOutcome(task, runDelegation, 'cancelled');
+                    }
                 }
                 return;
             }
@@ -1199,6 +1327,9 @@ export class WorkAgentService {
                     sourceKey: `work-run:${runId}:failed`,
                 });
             }
+            if (task) {
+                await this.reportDelegationOutcome(task, runDelegation, 'failed', message);
+            }
         }
         finally {
             this.controllers.delete(runId);
@@ -1247,7 +1378,7 @@ export class WorkAgentService {
             throw new WorkAgentHttpError('The provider routing changed while this Work run was active. Start a new run with the updated provider configuration.', 409, 'WORK_PROVIDER_ROUTING_CHANGED');
         }
     }
-    async contextMessages(task, roundLimit, computerAvailable, taughtSkills, providerStateScope, provider = task, persona) {
+    async contextMessages(task, roundLimit, computerAvailable, taughtSkills, providerStateScope, provider = task, persona, approvalsActive, peerAgents = [], delegatedBy, connectedTools = []) {
         const persisted = restorePersistedWorkContext(await workTaskService.getRecentModelContextMessages(task.id, 30), provider, providerStateScope);
         return [
             {
@@ -1257,6 +1388,10 @@ export class WorkAgentService {
                     computerAvailable,
                     ...(taughtSkills.length > 0 ? { taughtSkills } : {}),
                     ...(persona ? { persona } : {}),
+                    ...(approvalsActive ? { approvalsActive } : {}),
+                    ...(peerAgents.length > 0 ? { peerAgents } : {}),
+                    ...(delegatedBy ? { delegatedBy: delegatedBy.fromAgent } : {}),
+                    ...(connectedTools.length > 0 ? { connectedTools } : {}),
                     previewPort: workRuntimeService.previewPort,
                     roundBudget: roundLimit,
                     commandTimeoutMs: workRuntimeService.limits.commandTimeoutMs,
@@ -1268,6 +1403,32 @@ export class WorkAgentService {
     }
     async executeTool(task, call, context = {}) {
         const args = call.function.arguments;
+        // Connected tool servers: dynamic names resolved through the run's
+        // catalog before the built-in switch. Every guard the chat surface has
+        // is re-applied inside executeToolCall (visibility, enablement,
+        // credentials, SSRF-hardened egress).
+        const external = context.external?.byName.get(call.function.name);
+        if (external && context.external) {
+            if (!task.networkEnabled) {
+                throw new WorkAgentHttpError('Connected tools are not available for this task.', 403, 'WORK_TOOLS_UNAVAILABLE');
+            }
+            const result = await executeToolCall({
+                actor: context.external.actor,
+                tool: external,
+                argumentsJson: JSON.stringify(args ?? {}),
+                selection: context.external.selection,
+                ...(context.signal ? { signal: context.signal } : {}),
+            });
+            return {
+                content: result.text.slice(0, workRuntimeService.limits.maxOutputChars),
+                metadata: {
+                    external: true,
+                    ...(external.serverName ? { server: external.serverName } : {}),
+                    ...(result.isError ? { error: true } : {}),
+                    ...(result.truncated ? { outputTruncated: true } : {}),
+                },
+            };
+        }
         switch (call.function.name) {
             case 'list_files': {
                 const result = await workRuntimeService.listFiles(task, optionalString(args.path) || '.');
@@ -1368,6 +1529,61 @@ export class WorkAgentService {
                 }
                 return result;
             }
+            case 'message_agent': {
+                if (context.delegated === true) {
+                    return {
+                        content: 'This run was itself delegated by another agent, and delegated runs cannot delegate further. Complete the request yourself and include any blocker in your report.',
+                        metadata: { outcome: 'depth-limited' },
+                    };
+                }
+                const agentName = requiredString(args.agent, 'agent')
+                    .trim()
+                    .slice(0, 200);
+                const message = requiredString(args.message, 'message').slice(0, WORK_DELEGATION_MESSAGE_MAX_CHARS);
+                const peers = (await workTaskService.listTaskRecords(task.userId)).filter(record => record.isAgent && record.id !== task.id);
+                const target = peers.find(record => record.title.trim().toLowerCase() === agentName.toLowerCase());
+                if (!target) {
+                    const roster = peers
+                        .slice(0, WORK_DELEGATION_MAX_PEERS)
+                        .map(record => record.title)
+                        .join(', ');
+                    return {
+                        content: roster
+                            ? `No hired agent is named "${agentName}". The user's agents are: ${roster}. Use the exact name, or handle the request yourself.`
+                            : 'The user has no other hired agents, so there is no one to delegate to. Handle the request yourself.',
+                        metadata: { outcome: 'unknown-agent' },
+                    };
+                }
+                try {
+                    const detail = await workTaskService.createRun(target.id, task.userId, message, undefined, undefined, {
+                        delegation: {
+                            fromTaskId: task.id,
+                            fromRunId: context.runId ?? '',
+                            fromAgent: task.title,
+                        },
+                    });
+                    return {
+                        content: `Delegated to ${target.title}. It works in its own separate workspace and cannot see this conversation; its report will arrive here as a message when it finishes. Continue with other work or wrap up your response.`,
+                        metadata: {
+                            outcome: 'delegated',
+                            delegatedTaskId: target.id,
+                            ...(detail.activeRun?.id
+                                ? { delegatedRunId: detail.activeRun.id }
+                                : {}),
+                            delegatedAgent: target.title,
+                        },
+                    };
+                }
+                catch (error) {
+                    if (error instanceof WorkConflictError) {
+                        return {
+                            content: `${target.title} is busy with another run right now. Try again later, do the work yourself, or tell the user.`,
+                            metadata: { outcome: 'busy' },
+                        };
+                    }
+                    throw error;
+                }
+            }
             case 'request_takeover': {
                 await this.assertComputerToolsAvailable(task);
                 if ((await workPolicyService.resolve(task.policyId)).takeoverEnabled ===
@@ -1390,10 +1606,44 @@ export class WorkAgentService {
                         ? `work-takeover:${context.runId}`
                         : `work-takeover:${task.id}:${Date.now()}`,
                 });
-                const outcome = await workScreenControlService.waitForAssist(task.id, reason, {
-                    timeoutMs: WORK_SCREEN_ASSIST_TIMEOUT_MS,
-                    signal: context.signal,
-                });
+                // Hold the screen session for the whole wait — and, when nobody
+                // answers in time, through a grace window after it. Without the
+                // hold, a run_command settle or run-end cleanup stops the sandbox,
+                // and a user who arrives from the notification a few minutes late
+                // takes over a fresh start page instead of the screen the agent
+                // was blocked on.
+                let releaseTakeoverHold;
+                try {
+                    releaseTakeoverHold =
+                        await workRuntimeService.beginScreenSession(task);
+                }
+                catch (error) {
+                    // Best effort: a hold failure must never block the request.
+                    logger.warn(`Could not hold the screen for a takeover request on ${task.id}:`, error);
+                }
+                let holdThroughGrace = false;
+                let outcome;
+                try {
+                    outcome = await workScreenControlService.waitForAssist(task.id, reason, {
+                        timeoutMs: WORK_SCREEN_ASSIST_TIMEOUT_MS,
+                        signal: context.signal,
+                    });
+                    holdThroughGrace = outcome === 'timeout';
+                }
+                finally {
+                    if (releaseTakeoverHold) {
+                        const release = releaseTakeoverHold;
+                        if (holdThroughGrace) {
+                            const timer = setTimeout(() => void release(), WORK_TAKEOVER_GRACE_MS);
+                            timer.unref?.();
+                        }
+                        else {
+                            // An active takeover (or a cancelled run) carries its own
+                            // viewer holds — or none should remain at all.
+                            void release();
+                        }
+                    }
+                }
                 if (outcome === 'released') {
                     return {
                         content: 'The user took control of the computer and has handed it back. Use computer_observe to see the current screen before continuing.',
@@ -1442,6 +1692,167 @@ export class WorkAgentService {
      * never fails the run. The source key is run-scoped because dedupe is
      * permanent per user until the inbox cap prunes it.
      */
+    /**
+     * The user's configured tool servers, resolved once per run. Backend
+     * egress, so an offline task offers none — the web_search rationale.
+     * Servers whose per-user credential is missing are filtered at offer
+     * time, because an autonomous run cannot prompt for one; persona
+     * bindings narrow the servers exactly as they do in chat.
+     */
+    async externalToolsForRun(task) {
+        if (!task.networkEnabled)
+            return undefined;
+        try {
+            const user = await userModel.getUserById(task.userId);
+            const actor = {
+                userId: task.userId,
+                ...(user?.role ? { role: user.role } : {}),
+            };
+            if (!(await actorCanUseTools(actor)))
+                return undefined;
+            let serverIds;
+            if (task.personaId) {
+                try {
+                    const { personaService } = await import('./personaService.js');
+                    const bindings = (await personaService.getPersonaById(task.personaId, task.userId))?.bindings;
+                    if (bindings?.tool_server_ids)
+                        serverIds = bindings.tool_server_ids;
+                }
+                catch {
+                    // A vanished persona leaves the selection unrestricted, matching
+                    // how the run already degrades to no persona identity.
+                }
+            }
+            const catalog = await buildToolCatalog(actor, {}, {
+                builtinTools: [],
+                ...(serverIds ? { serverIds } : {}),
+            });
+            const builtinNames = new Set([
+                ...WORK_TOOL_SCHEMAS,
+                WORK_WEB_SEARCH_TOOL_SCHEMA,
+                WORK_MESSAGE_AGENT_TOOL_SCHEMA,
+                ...WORK_COMPUTER_TOOL_SCHEMAS,
+            ].map(schema => schema.function?.name ?? ''));
+            const credentialed = new Map();
+            const byName = new Map();
+            const schemas = [];
+            for (const tool of catalog.tools) {
+                if (tool.source === 'builtin' || !tool.serverId)
+                    continue;
+                if (builtinNames.has(tool.name))
+                    continue;
+                let usable = credentialed.get(tool.serverId);
+                if (usable === undefined) {
+                    const server = await getToolServer(tool.serverId);
+                    usable =
+                        server !== undefined &&
+                            server !== null &&
+                            (server.authMode === 'none' ||
+                                (await hasToolServerCredential(task.userId, tool.serverId)));
+                    credentialed.set(tool.serverId, usable);
+                }
+                if (!usable)
+                    continue;
+                byName.set(tool.name, tool);
+                schemas.push(externalToolSchema(tool));
+            }
+            if (byName.size === 0)
+                return undefined;
+            return { actor, byName, schemas, selection: catalog.selection };
+        }
+        catch (error) {
+            logger.warn(`Connected tools are unavailable for task ${task.id}:`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Deliver a delegated run's outcome back into the delegating agent's
+     * conversation. Mid-run when the delegator is still working (picked up at
+     * its next round boundary), an ordinary conversation message otherwise —
+     * never an auto-started run, so two agents cannot ping-pong each other.
+     * Best effort: the delegated run's own rows are the source of truth.
+     */
+    async reportDelegationOutcome(task, delegation, status, summary) {
+        if (!delegation)
+            return;
+        try {
+            const delegator = await workTaskService.getTaskRecord(delegation.fromTaskId, task.userId);
+            if (!delegator)
+                return;
+            const statusLine = status === 'completed'
+                ? 'finished'
+                : status === 'needs_input'
+                    ? 'stopped and needs input'
+                    : status === 'failed'
+                        ? 'failed'
+                        : 'was cancelled';
+            const bounded = (summary ?? '')
+                .trim()
+                .slice(0, WORK_DELEGATION_REPORT_MAX_CHARS);
+            const content = `Report from ${task.title} — the delegated request ${statusLine}.\n\n${bounded || '(no summary was produced)'}`;
+            const activeRun = await workTaskService.getActiveRun(delegation.fromTaskId);
+            const deliverMidRun = activeRun !== undefined && isActiveRunStatus(activeRun.status);
+            await workTaskService.addMessage(delegation.fromTaskId, deliverMidRun ? activeRun.id : undefined, 'user', 'message', content, {
+                ...(deliverMidRun ? { midRun: true } : {}),
+                delegationReport: {
+                    fromTaskId: task.id,
+                    fromAgent: task.title,
+                    status,
+                },
+            });
+        }
+        catch (error) {
+            logger.warn(`Delegation report from task ${task.id} failed:`, error);
+        }
+    }
+    /**
+     * The approval gate. Rules are re-read per call so an Always-allow
+     * decision covers the very next matching call; a pending approval rides
+     * the event stream (and the snapshot) so any open view can decide, and
+     * notifies because the user may not be watching. Denial and timeout come
+     * back as verdicts the dispatch loop turns into ordinary tool results —
+     * never silent execution.
+     */
+    async awaitToolApproval(task, call, summary, runId, userId, signal, durableAttemptIdentity) {
+        if (await workApprovalService.callIsPreapproved(task.id, call.function.name, summary)) {
+            return 'approved';
+        }
+        const pending = await workApprovalService.createPending({
+            taskId: task.id,
+            runId,
+            userId,
+            toolCallId: call.id,
+            toolName: call.function.name,
+            summary,
+        });
+        await workEventService.publish(task.id, runId, 'approval', {
+            approvalId: pending.approvalId,
+            toolCallId: call.id,
+            name: call.function.name,
+            summary: pending.summary,
+            status: 'pending',
+            expiresAt: pending.expiresAt,
+        }, `approval:${pending.approvalId}:pending`, durableAttemptIdentity);
+        await this.notifyAgentLifecycle(task, {
+            type: 'work-approval',
+            title: `${task.title} is waiting for your approval`,
+            body: summarizeApprovalBody(call.function.name, summary),
+            sourceKey: `work-approval:${pending.approvalId}`,
+        });
+        const verdict = await workApprovalService.waitForDecision(task.id, pending.approvalId, signal);
+        const status = verdict.status === 'approved'
+            ? 'approved'
+            : verdict.status === 'denied'
+                ? 'denied'
+                : 'expired';
+        await workEventService.publish(task.id, runId, 'approval', {
+            approvalId: pending.approvalId,
+            toolCallId: call.id,
+            name: call.function.name,
+            status,
+        }, `approval:${pending.approvalId}:resolved`, durableAttemptIdentity);
+        return status;
+    }
     async notifyAgentLifecycle(task, input) {
         try {
             const { notificationService } = await import('./notificationService.js');
@@ -2012,6 +2423,8 @@ function validateToolCallArguments(call) {
             return invalidRequiredString('reason');
         case 'run_command':
             return invalidRequiredString('command');
+        case 'message_agent':
+            return invalidRequiredString('agent') || invalidRequiredString('message');
         default:
             return `The model requested an unknown tool: ${call.function.name}.`;
     }
@@ -2019,6 +2432,39 @@ function validateToolCallArguments(call) {
 function isActiveRunStatus(status) {
     return status === 'queued' || status === 'preparing' || status === 'running';
 }
+/** One-line human description of a gated call for the approval notification. */
+function summarizeApprovalBody(toolName, summary) {
+    switch (toolName) {
+        case 'run_command':
+            return typeof summary.command === 'string'
+                ? `Run: ${summary.command.slice(0, 200)}`
+                : 'Run a command';
+        case 'delete_file':
+            return typeof summary.path === 'string'
+                ? `Delete ${summary.path}`
+                : 'Delete a file';
+        case 'move_file':
+            return typeof summary.from === 'string' && typeof summary.to === 'string'
+                ? `Move ${summary.from} to ${summary.to}`
+                : 'Move a file';
+        case 'message_agent':
+            return typeof summary.agent === 'string'
+                ? `Delegate to ${summary.agent}`
+                : 'Delegate to another agent';
+        case 'computer_act': {
+            const count = typeof summary.actionCount === 'number' ? summary.actionCount : null;
+            return count === 1
+                ? '1 computer action on the screen'
+                : count !== null
+                    ? `${count} computer actions on the screen`
+                    : 'Computer actions on the screen';
+        }
+        default:
+            return summary.external === true && typeof summary.server === 'string'
+                ? `Call ${toolName} on ${summary.server}`
+                : toolName;
+    }
+}
 function summarizeToolCall(call) {
     const args = call.function.arguments;
     const metadata = {
@@ -2065,6 +2511,10 @@ function summarizeToolCall(call) {
                 metadata.timeoutMs = args.timeout_ms;
             }
             break;
+        case 'message_agent':
+            includeString('agent', args.agent, 200);
+            includeString('message', args.message, 500);
+            break;
         case 'start_preview':
             includeString('command', args.command, 2000);
             break;