@theia/ai-chat 1.76.0-next.7 → 1.76.0

package/src/browser/agent-delegation-tool.ts

@@ -24,8 +24,11 @@ import {
     ChatChangeEvent,
     ChatRequest,
     ChatResponseContent,
+    ChatContextManager,
     ChatService,
     ChatServiceFactory,
+    ChatSession,
+    ChatSessionStatus,
     ChatToolContext,
     MutableChatModel,
     MutableChatRequestModel,
@@ -57,9 +60,12 @@ export class AgentDelegationTool implements ToolProvider {
             name: AgentDelegationTool.ID,
             description:
                 'Delegate a task or question to a specific AI agent. IMPORTANT: When you delegate a task or question to a specific AI agent using this tool, ' +
-                'remember that each sub-agent operates solely within its specialized capabilities and tools and does not have access to previous conversation context ' +
-                ' or external systems. Therefore, it is crucial to provide all necessary context and detailed information directly within your request to ensure accurate ' +
-                'and effective task completion. ' +
+                'remember that each sub-agent operates solely within its specialized capabilities and tools and, unless you resume a previous delegation via sessionId, ' +
+                'does not have access to previous conversation context or external systems. Therefore, it is crucial to provide all necessary context and detailed ' +
+                'information directly within your request to ensure accurate and effective task completion. ' +
+                'Each result ends with a "[delegation sessionId: <id>]" line. To send a follow-up request to the same agent with its previous conversation retained ' +
+                '(e.g. to request fixes after reviewing its result), pass that id as sessionId. Prefer resuming for follow-ups on the same task; ' +
+                'start a fresh session (omit sessionId) for unrelated tasks, as a resumed session grows with every round. ' +
                 'You may optionally pass a taskContextId to make a specific task context (e.g. a plan) available to the delegated agent via its system prompt.',
             parameters: {
                 type: 'object',
@@ -78,6 +84,12 @@ export class AgentDelegationTool implements ToolProvider {
                         type: 'string',
                         description: 'Optional task context ID to make available to the delegated agent. The agent will see the task context in its system prompt.',
                     },
+                    sessionId: {
+                        type: 'string',
+                        description: 'Optional ID of a previous delegation session to continue, as reported in the "[delegation sessionId: <id>]" line of an earlier result. ' +
+                            'The delegated agent keeps its previous conversation context, so you do not need to repeat context you already sent it. ' +
+                            'Only a session that you delegated yourself can be resumed, and the agentId must match the original delegation.',
+                    },
                 },
                 required: ['agentId', 'prompt'],
             },
@@ -102,7 +114,7 @@ export class AgentDelegationTool implements ToolProvider {
 
         try {
             const args = JSON.parse(arg_string);
-            const { agentId, prompt, taskContextId } = args;
+            const { agentId, prompt, taskContextId, sessionId } = args;
 
             if (!agentId || !prompt) {
                 const errorMsg = 'Both agentId and prompt parameters are required.';
@@ -121,131 +133,183 @@ export class AgentDelegationTool implements ToolProvider {
                 return errorMsg;
             }
 
-            let newSession;
+            let session: ChatSession;
             let childModelDisposable: Disposable | undefined;
-            try {
+            if (sessionId) {
                 const chatService = this.getChatService();
+                // Restore from storage if necessary: delegated sessions are auto-saved, so after a reload the
+                // delegating session's history still carries the id while the session itself is no longer in memory.
+                const existingSession = await chatService.getOrRestoreSession(sessionId);
+                if (!existingSession) {
+                    const errorMsg = `Delegation session '${sessionId}' not found. It may have been deleted. ` +
+                        'Send the request again without sessionId to start a fresh session — the agent will not have any prior context.';
+                    // warn, not error: a stale session id is expected in a normal agentic loop (e.g. the user deleted the session)
+                    this.logger.warn(errorMsg);
+                    return errorMsg;
+                }
+                if (existingSession.parentSessionId !== ctx.request.session.id) {
+                    // Without this, any session id would be accepted, including an unrelated top-level user chat,
+                    // and the delegated request would be injected into it.
+                    const errorMsg = `Delegation session '${sessionId}' was not delegated by this session and cannot be resumed here. ` +
+                        'Only pass a sessionId reported by one of your own earlier delegations, or omit it to start a fresh session.';
+                    this.logger.error(errorMsg);
+                    return errorMsg;
+                }
+                if (ChatSessionStatus.isInProgress(existingSession.model.status)) {
+                    const errorMsg = `Delegation session '${sessionId}' is still processing a previous request. ` +
+                        'Wait for its result before sending a follow-up, or omit sessionId to start a fresh session.';
+                    // warn, not error: expected when the caller issues parallel requests against the same session
+                    this.logger.warn(errorMsg);
+                    return errorMsg;
+                }
+                if (existingSession.pinnedAgent && existingSession.pinnedAgent.id !== agentId) {
+                    const errorMsg = `Delegation session '${sessionId}' belongs to agent '${existingSession.pinnedAgent.id}', not '${agentId}'. ` +
+                        'Pass the matching agentId, or omit sessionId to start a fresh session.';
+                    this.logger.error(errorMsg);
+                    return errorMsg;
+                }
 
-                // Store the current active session to restore it after delegation
-                const currentActiveSession = chatService.getActiveSession();
+                // Deliberately keep rootSessionId/parentSessionId as set at creation time; a resumed
+                // session stays attached to its original delegation hierarchy.
+                if (taskContextId) {
+                    this.setTaskContext(existingSession.model.context, taskContextId);
+                }
+
+                session = existingSession;
+                // Re-establish bubbling for this request; the previous disposable was disposed when the
+                // original delegation completed, and the parent request/response are new objects now.
+                childModelDisposable = this.setupChildSessionBubbling(existingSession.model as MutableChatModel, ctx.request.session, ctx.response);
+            } else {
+                try {
+                    const chatService = this.getChatService();
 
-                newSession = chatService.createSession(
-                    undefined,
-                    { focus: false },
-                    agent
-                );
+                    // Store the current active session to restore it after delegation
+                    const currentActiveSession = chatService.getActiveSession();
 
-                // Set root session ID to enable task context sharing across delegation chains
-                // Root is either the current root (for nested delegation) or current session (for first-level delegation)
-                const rootId = ctx.rootSessionId || ctx.request.session.id;
-                newSession.rootSessionId = rootId;
-                newSession.model.rootSessionId = rootId;
+                    const newSession = chatService.createSession(
+                        undefined,
+                        { focus: false },
+                        agent
+                    );
 
-                // Track the immediate parent (the delegating session) so the UI can render the full
-                // delegation hierarchy, not just a flat list under the root.
-                const parentId = ctx.request.session.id;
-                newSession.parentSessionId = parentId;
-                newSession.model.parentSessionId = parentId;
+                    // Set root session ID to enable task context sharing across delegation chains
+                    // Root is either the current root (for nested delegation) or current session (for first-level delegation)
+                    const rootId = ctx.rootSessionId || ctx.request.session.id;
+                    newSession.rootSessionId = rootId;
+                    newSession.model.rootSessionId = rootId;
+
+                    // Track the immediate parent (the delegating session) so the UI can render the full
+                    // delegation hierarchy, not just a flat list under the root.
+                    const parentId = ctx.request.session.id;
+                    newSession.parentSessionId = parentId;
+                    newSession.model.parentSessionId = parentId;
+
+                    if (taskContextId) {
+                        newSession.model.context.addVariables({
+                            variable: TASK_CONTEXT_VARIABLE,
+                            arg: taskContextId
+                        });
+                    }
 
-                if (taskContextId) {
-                    newSession.model.context.addVariables({
-                        variable: TASK_CONTEXT_VARIABLE,
-                        arg: taskContextId
-                    });
-                }
+                    // Immediately restore the original active session to avoid confusing the user
+                    if (currentActiveSession) {
+                        chatService.setActiveSession(currentActiveSession.id, { focus: false });
+                    }
 
-                // Immediately restore the original active session to avoid confusing the user
-                if (currentActiveSession) {
-                    chatService.setActiveSession(currentActiveSession.id, { focus: false });
+                    // Setup bubbling of child session events to parent session
+                    childModelDisposable = this.setupChildSessionBubbling(newSession.model as MutableChatModel, ctx.request.session, ctx.response);
+                    session = newSession;
+                } catch (sessionError) {
+                    const errorMsg = `Failed to create chat session for agent '${agentId}': ${sessionError instanceof Error ? sessionError.message : sessionError}`;
+                    this.logger.error(errorMsg, sessionError);
+                    return errorMsg;
                 }
-
-                // Setup bubbling of child session events to parent session
-                childModelDisposable = this.setupChildSessionBubbling(newSession.model as MutableChatModel, ctx.request.session, ctx.response);
-            } catch (sessionError) {
-                const errorMsg = `Failed to create chat session for agent '${agentId}': ${sessionError instanceof Error ? sessionError.message : sessionError}`;
-                this.logger.error(errorMsg, sessionError);
-                return errorMsg;
             }
 
-            // Send the request
-            const chatRequest: ChatRequest = {
-                text: `@${agentId} ${prompt}`,
-            };
-
-            let response: ChatRequestInvocation | undefined;
+            // Send the request. The `finally` releases the event bubbling on every outcome: a resumed
+            // session is long-lived, so leaking a listener per failed round would forward its events
+            // into stale parent responses.
             try {
-                if (ctx.cancellationToken?.isCancellationRequested) {
-                    return 'Operation cancelled by user';
-                }
+                const chatRequest: ChatRequest = {
+                    text: `@${agentId} ${prompt}`,
+                };
 
-                const chatService = this.getChatService();
-                response = await chatService.sendRequest(
-                    newSession.id,
-                    chatRequest
-                );
-
-                if (ctx.cancellationToken) {
-                    ctx.cancellationToken.onCancellationRequested(
-                        async () => {
-                            if (response) {
-                                ((await response?.requestCompleted) as MutableChatRequestModel).cancel();
-                            }
-                        }
-                    );
-                }
-            } catch (sendError) {
-                const errorMsg = `Failed to send request to agent '${agentId}': ${sendError instanceof Error ? sendError.message : sendError}`;
-                this.logger.error(errorMsg, sendError);
-                return errorMsg;
-            }
+                let response: ChatRequestInvocation | undefined;
+                try {
+                    if (ctx.cancellationToken?.isCancellationRequested) {
+                        return 'Operation cancelled by user';
+                    }
 
-            if (response) {
-                // Store the invocation in the registry so the renderer can access it
-                if (ctx.toolCallId) {
-                    this.pendingDelegations.set(ctx.toolCallId, {
-                        prompt,
-                        invocation: response
-                    });
-                    // Clean up when the delegated session is deleted
                     const chatService = this.getChatService();
-                    const toolCallId = ctx.toolCallId;
-                    const sessionEventListener = chatService.onSessionEvent(event => {
-                        if (event.type === 'deleted' && event.sessionId === newSession.id) {
-                            this.pendingDelegations.delete(toolCallId);
-                            sessionEventListener.dispose();
-                        }
-                    });
+                    response = await chatService.sendRequest(
+                        session.id,
+                        chatRequest
+                    );
+
+                    if (ctx.cancellationToken) {
+                        ctx.cancellationToken.onCancellationRequested(
+                            async () => {
+                                if (response) {
+                                    ((await response?.requestCompleted) as MutableChatRequestModel).cancel();
+                                }
+                            }
+                        );
+                    }
+                } catch (sendError) {
+                    const errorMsg = `Failed to send request to agent '${agentId}': ${sendError instanceof Error ? sendError.message : sendError}`;
+                    this.logger.error(errorMsg, sendError);
+                    return errorMsg;
                 }
 
-                try {
-                    // Wait for completion to return the final result as tool output
-                    const result = await response.responseCompleted;
-                    const filteredContent = result.response.content.filter(c => !ThinkingChatResponseContent.is(c) && !ToolCallChatResponseContent.is(c));
-                    const stringResult = filteredContent
-                        .map(c => ChatResponseContent.hasAsString(c) ? c.asString() : undefined)
-                        .filter((text): text is string => text !== undefined && text !== '')
-                        .join('\n\n');
-
-                    // Clean up the parent-child link after completion (event bubbling is no longer needed)
-                    childModelDisposable?.dispose();
-
-                    // Return the raw text to the top-level Agent, as a tool result
-                    return stringResult;
-                } catch (completionError) {
-                    if (
-                        completionError instanceof Error &&
-                        completionError.message.includes('cancelled')
-                    ) {
-                        return 'Operation cancelled by user';
+                if (response) {
+                    // Store the invocation in the registry so the renderer can access it
+                    if (ctx.toolCallId) {
+                        this.pendingDelegations.set(ctx.toolCallId, {
+                            prompt,
+                            invocation: response
+                        });
+                        // Clean up when the delegated session is deleted
+                        const chatService = this.getChatService();
+                        const toolCallId = ctx.toolCallId;
+                        const sessionEventListener = chatService.onSessionEvent(event => {
+                            if (event.type === 'deleted' && event.sessionId === session.id) {
+                                this.pendingDelegations.delete(toolCallId);
+                                sessionEventListener.dispose();
+                            }
+                        });
+                    }
+
+                    try {
+                        // Wait for completion to return the final result as tool output
+                        const result = await response.responseCompleted;
+                        const filteredContent = result.response.content.filter(c => !ThinkingChatResponseContent.is(c) && !ToolCallChatResponseContent.is(c));
+                        const stringResult = filteredContent
+                            .map(c => ChatResponseContent.hasAsString(c) ? c.asString() : undefined)
+                            .filter((text): text is string => text !== undefined && text !== '')
+                            .join('\n\n');
+
+                        // Return the raw text to the top-level Agent, as a tool result. The session id
+                        // allows the caller to send follow-up requests into the same session.
+                        const sessionIdSuffix = `[delegation sessionId: ${session.id}]`;
+                        return stringResult ? `${stringResult}\n\n${sessionIdSuffix}` : sessionIdSuffix;
+                    } catch (completionError) {
+                        if (
+                            completionError instanceof Error &&
+                            completionError.message.includes('cancelled')
+                        ) {
+                            return 'Operation cancelled by user';
+                        }
+                        const errorMsg = `Failed to complete response from agent '${agentId}': ${completionError instanceof Error ? completionError.message : completionError}`;
+                        this.logger.error(errorMsg, completionError);
+                        return errorMsg;
                     }
-                    const errorMsg = `Failed to complete response from agent '${agentId}': ${completionError instanceof Error ? completionError.message : completionError}`;
-                    this.logger.error(errorMsg, completionError);
+                } else {
+                    const errorMsg = `Delegation to agent '${agentId}' has failed: no response returned.`;
+                    this.logger.error(errorMsg);
                     return errorMsg;
                 }
-            } else {
-                const errorMsg = `Delegation to agent '${agentId}' has failed: no response returned.`;
-                this.logger.error(errorMsg);
-                return errorMsg;
+            } finally {
+                childModelDisposable?.dispose();
             }
         } catch (error) {
             this.logger.error('Failed to delegate to agent', error);
@@ -255,6 +319,24 @@ export class AgentDelegationTool implements ToolProvider {
         }
     }
 
+    /**
+     * Makes the given task context the session's task context, replacing a previously set one.
+     * `addVariables` deduplicates on variable id *and* argument, so adding a different task context
+     * id would otherwise leave the session with both in its system prompt.
+     */
+    private setTaskContext(context: ChatContextManager, taskContextId: string): void {
+        const staleIndices = context.getVariables().reduce<number[]>((indices, variable, index) => {
+            if (variable.variable.id === TASK_CONTEXT_VARIABLE.id && variable.arg !== taskContextId) {
+                indices.push(index);
+            }
+            return indices;
+        }, []);
+        if (staleIndices.length > 0) {
+            context.deleteVariables(...staleIndices);
+        }
+        context.addVariables({ variable: TASK_CONTEXT_VARIABLE, arg: taskContextId });
+    }
+
     /**
      * Sets up all event bubbling from a delegated child session to the parent session:
      * - Interaction forwarding: child interactionNeeded events are forwarded to the parent response
@@ -273,6 +355,15 @@ export class AgentDelegationTool implements ToolProvider {
             if (ChatChangeEvent.isInteractionNeededEvent(event)) {
                 parentResponse.fireInteractionNeeded(event.contentPart);
                 event.contentPart.whenResolved.then(() => parentResponse.notifyChanged());
+                // A tool call's confirmation settles long before the call resolves (the
+                // tool may run for minutes after being confirmed); notify the parent at
+                // settle time so its UI re-derives pending interactions immediately.
+                if (ToolCallChatResponseContent.is(event.contentPart)) {
+                    event.contentPart.confirmed.then(
+                        () => parentResponse.notifyChanged(),
+                        () => parentResponse.notifyChanged()
+                    );
+                }
             }
         });
 

package/src/common/chat-model.ts

@@ -286,6 +286,19 @@ export type ChatSessionStatus =
     | 'failed';
 
 export namespace ChatSessionStatus {
+    /**
+     * All {@link ChatSessionStatus} values, e.g. for schema declarations. Derived from an
+     * exhaustive record so that adding a status without listing it here fails to compile.
+     */
+    export const VALUES: readonly ChatSessionStatus[] = Object.keys({
+        idle: true,
+        running: true,
+        awaitingApproval: true,
+        awaitingToolCall: true,
+        awaitingInput: true,
+        failed: true
+    } satisfies Record<ChatSessionStatus, true>) as ChatSessionStatus[];
+
     /**
      * Whether a request is in progress in this status, including the states waiting on the user or a tool.
      */
@@ -502,6 +515,13 @@ export interface InteractiveContent {
     readonly isResolved: boolean;
     /** Resolves when the interaction is resolved. Used for cleanup in delegation chains. */
     readonly whenResolved: Promise<void>;
+    /**
+     * Whether the interaction currently requires user action. Unlike {@link isResolved},
+     * this reflects the momentary state: e.g. a tool call whose confirmation was granted
+     * is not yet resolved (the tool is still executing) but no longer awaits interaction.
+     * When `undefined`, consumers should fall back to `!isResolved`.
+     */
+    readonly isAwaitingInteraction?: boolean;
 }
 
 export namespace InteractiveContent {
@@ -706,6 +726,16 @@ export interface ToolCallChatResponseContent extends Required<ChatResponseConten
     cancelConfirmation(reason?: unknown): void;
     /** Signal that this tool call needs user confirmation. Resolves the needsUserConfirmation promise. */
     requestUserConfirmation(): void;
+    /**
+     * Whether the tool execution is currently blocked waiting for user input provided
+     * through the tool's own UI (e.g. an interactive wizard). Cleared when the tool
+     * call finishes or {@link userInputHandled} is called.
+     */
+    readonly isAwaitingUserInput: boolean;
+    /** Signal that the tool execution is blocked waiting for user input. */
+    requestUserInput(): void;
+    /** Signal that the tool execution is no longer waiting for user input. */
+    userInputHandled(): void;
     /**
      * Update the tool call's result without marking it finished. Use this to persist
      * intermediate state for long-running tools (e.g. the user-interaction wizard) so
@@ -1073,6 +1103,13 @@ export interface ChatResponseModel {
      * The content part that needs interaction is provided as the event payload.
      */
     readonly onInteractionNeeded: Event<InteractiveContent & ChatResponseContent>;
+    /**
+     * Content parts announced via {@link onInteractionNeeded} that currently await user
+     * interaction (see {@link InteractiveContent.isAwaitingInteraction}). Lets late
+     * subscribers (e.g. a remounted delegation renderer) rebuild pending interaction
+     * state instead of relying solely on the push event.
+     */
+    readonly pendingInteractions: ReadonlyArray<InteractiveContent & ChatResponseContent>;
     /**
      * The unique identifier of the response model
      */
@@ -2578,6 +2615,7 @@ export class ToolCallChatResponseContentImpl implements ToolCallChatResponseCont
     protected _needsUserConfirmation: Promise<void>;
     protected _needsUserConfirmationResolver?: () => void;
     protected _isAwaitingUserConfirmation = false;
+    protected _isAwaitingUserInput = false;
     protected _confirmed: Promise<boolean>;
     protected _confirmationResolver?: (value: boolean) => void;
     protected _confirmationRejecter?: (reason?: unknown) => void;
@@ -2659,6 +2697,14 @@ export class ToolCallChatResponseContentImpl implements ToolCallChatResponseCont
         return this._isAwaitingUserConfirmation && !this.finished;
     }
 
+    get isAwaitingUserInput(): boolean {
+        return this._isAwaitingUserInput && !this.finished;
+    }
+
+    get isAwaitingInteraction(): boolean {
+        return this.isAwaitingUserConfirmation || this.isAwaitingUserInput;
+    }
+
     get whenFinished(): Promise<void> {
         return this._whenFinished;
     }
@@ -2717,6 +2763,14 @@ export class ToolCallChatResponseContentImpl implements ToolCallChatResponseCont
         }
     }
 
+    requestUserInput(): void {
+        this._isAwaitingUserInput = true;
+    }
+
+    userInputHandled(): void {
+        this._isAwaitingUserInput = false;
+    }
+
     updateResult(result: ToolCallResult): void {
         this._result = result;
         this._onDidChangeEmitter.fire();
@@ -3104,6 +3158,12 @@ export class QuestionResponseContentImpl implements QuestionResponseContent, Int
         return this.selectedOption !== undefined;
     }
 
+    get isAwaitingInteraction(): boolean {
+        // A skipped question resolves with an empty selection: isResolved stays false,
+        // but the question no longer awaits interaction.
+        return !this.isReadOnly && this._selectedOptions === undefined;
+    }
+
     set selectedOption(option: { text: string; value?: string } | undefined) {
         this._selectedOptions = option ? [option] : undefined;
         this._resolvedResolver?.();
@@ -3292,6 +3352,8 @@ export class MutableChatResponseModel implements ChatResponseModel {
     protected readonly _onInteractionNeededEmitter = new Emitter<InteractiveContent & ChatResponseContent>();
     readonly onInteractionNeeded: Event<InteractiveContent & ChatResponseContent> = this._onInteractionNeededEmitter.event;
 
+    protected _pendingInteractions: (InteractiveContent & ChatResponseContent)[] = [];
+
     data = {};
 
     protected _id: string;
@@ -3474,16 +3536,22 @@ export class MutableChatResponseModel implements ChatResponseModel {
         this._agentId = agentId;
     }
 
+    /** Reset all pending-input state; the response no longer accepts user interaction. */
+    protected resetPendingInput(): void {
+        this._waitingForInputCount = 0;
+        this._pendingInteractions = [];
+    }
+
     complete(): void {
         this._isComplete = true;
-        this._waitingForInputCount = 0;
+        this.resetPendingInput();
         this._onDidChangeEmitter.fire();
     }
 
     cancel(): void {
         this._cancellationToken.cancel();
         this._isComplete = true;
-        this._waitingForInputCount = 0;
+        this.resetPendingInput();
 
         // Ensure any pending tool confirmations are canceled when the chat is canceled
         try {
@@ -3516,7 +3584,23 @@ export class MutableChatResponseModel implements ChatResponseModel {
         this._onDidChangeEmitter.fire();
     }
 
+    get pendingInteractions(): ReadonlyArray<InteractiveContent & ChatResponseContent> {
+        // Filter by the momentary awaiting state so consumers never see interactions
+        // whose actionable phase has passed (e.g. a confirmed tool call that is still
+        // executing and therefore not yet resolved).
+        return this._pendingInteractions.filter(part => part.isAwaitingInteraction ?? !part.isResolved);
+    }
+
     fireInteractionNeeded(contentPart: InteractiveContent & ChatResponseContent): void {
+        if (!this._isComplete && !contentPart.isResolved && !this._pendingInteractions.includes(contentPart)) {
+            this._pendingInteractions = [...this._pendingInteractions, contentPart];
+            // Stop tracking on settlement either way: custom InteractiveContent implementations
+            // may reject whenResolved, and the rejection must not escape the model unhandled.
+            const stopTracking = (): void => {
+                this._pendingInteractions = this._pendingInteractions.filter(part => part !== contentPart);
+            };
+            contentPart.whenResolved.then(stopTracking, stopTracking);
+        }
         this._onInteractionNeededEmitter.fire(contentPart);
     }
 
@@ -3526,7 +3610,7 @@ export class MutableChatResponseModel implements ChatResponseModel {
 
     error(error: Error): void {
         this._isComplete = true;
-        this._waitingForInputCount = 0;
+        this.resetPendingInput();
         this._isError = true;
         this._errorObject = error;
         this._onDidChangeEmitter.fire();