@theia/ai-ide 1.71.0-next.8 → 1.71.0

package/src/browser/workspace-task-provider.ts

@@ -113,7 +113,10 @@ export class TaskRunnerProvider implements ToolProvider {
                 return `Did not find a task for the label: '${args.taskName}'`;
             }
             cancellationToken?.onCancellationRequested(() => {
-                this.taskService.terminateTask(taskInfo);
+                // Only terminate if the task is still running
+                if (this.taskService.isTaskRunning(taskInfo.taskId)) {
+                    this.taskService.terminateTask(taskInfo);
+                }
             });
             if (cancellationToken?.isCancellationRequested) {
                 return JSON.stringify({ error: 'Operation cancelled by user' });

package/src/common/ai-ide-preferences.ts

@@ -15,12 +15,12 @@
 // *****************************************************************************
 
 import { AI_CORE_PREFERENCES_TITLE } from '@theia/ai-core/lib/common';
-import { nls, PreferenceSchema } from '@theia/core';
+import { nls, PreferenceSchema, PreferenceScope } from '@theia/core';
 
 // We reuse the context key for the preference name
 export const PREFERENCE_NAME_ENABLE_AI = 'ai-features.AiEnable.enableAI';
 export const PREFERENCE_NAME_ORCHESTRATOR_EXCLUSION_LIST = 'ai-features.orchestrator.excludedAgents';
-export const PREFERENCE_NAME_AGENT_MODE_CONFIRMED = 'ai-features.agentMode.confirmed';
+export const PREFERENCE_NAME_AGENT_MODE_ENABLED = 'ai-features.agentMode.enabled';
 export const aiIdePreferenceSchema: PreferenceSchema = {
     properties: {
         [PREFERENCE_NAME_ENABLE_AI]: {
@@ -49,14 +49,14 @@ export const aiIdePreferenceSchema: PreferenceSchema = {
             },
             default: ['ClaudeCode', 'Codex'],
         },
-        [PREFERENCE_NAME_AGENT_MODE_CONFIRMED]: {
+        [PREFERENCE_NAME_AGENT_MODE_ENABLED]: {
             title: AI_CORE_PREFERENCES_TITLE,
-            markdownDescription: nls.localize('theia/ai/ide/agentMode/confirmed/mdDescription',
-                'Whether the user has confirmed the agent mode warning. '
-                + 'Agent mode allows autonomous file modifications without further confirmation. '
-                + 'Set to `false` to see the confirmation again on the next agent mode request.'),
+            description: nls.localize('theia/ai/ide/agentMode/enabled/mdDescription',
+                'Enable agent mode for the Coder agent. Agent mode allows autonomous file modifications without further confirmation.\
+                 A first-use confirmation dialog is shown when using agent mode until this is set to `true`.'),
             type: 'boolean',
             default: false,
+            scope: PreferenceScope.User
         }
     }
 };

package/src/common/coder-replace-prompt-template.ts

@@ -49,7 +49,7 @@ https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-
 
 # Identity
 
-You are an **autonomous AI agent** embedded in the Theia IDE. Your purpose is to assist developers with implementing features, fixing bugs, \
+You are an **autonomous AI agent** embedded in {{productName}}. Your purpose is to assist developers with implementing features, fixing bugs, \
 refactoring code, and improving code quality.
 You must independently analyze, implement, validate, and finalize all changes — only yield control when all relevant tasks are completed.
 
@@ -276,9 +276,11 @@ https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-
 
 # Identity
 
-You are an **autonomous AI agent** embedded in the Theia IDE. Your purpose is to assist developers with implementing features, fixing bugs, \
+You are an **autonomous AI agent** embedded in {{productName}}. Your purpose is to assist developers with implementing features, fixing bugs, \
 refactoring code, and improving code quality.
 You must independently analyze, implement, validate, and finalize all changes — only yield control when all relevant tasks are completed.
+You operate within the boundaries of the current workspace. You cannot access external networks, install system-level packages, or modify files \
+outside the project root unless explicitly enabled via capabilities.
 
 # Core Principles
 
@@ -305,10 +307,14 @@ When multiple independent operations are needed, execute them **all in a single
 - Searching for different patterns → search in parallel
 - Running independent validations → run together
 **Never run independent operations one at a time.** Only run sequentially when there are true dependencies.
+**Do NOT write to the same file in parallel.** Parallel reads are always safe; parallel writes to the same file will conflict.
 
 ## Planning and Reflection
 For complex decisions, think step-by-step and explain your reasoning.
-After tool calls, reflect on results and adjust your plan if needed.
+After tool calls, reflect before continuing:
+1. **What did I learn?** — Did the results match expectations?
+2. **Does this change my plan?** — If assumptions were invalidated, adjust your approach rather than continuing with the original plan
+3. **What's next and why?** — Base your next step on evidence, not the initial plan
 
 # Code Quality Guidelines
 
@@ -321,6 +327,13 @@ Only make changes that are directly requested or clearly necessary. Keep solutio
 - Three similar lines of code is better than a premature abstraction
 - Delete unused code completely — no backwards-compatibility hacks, no \`// removed\` comments
 
+## Minimize Your Diff
+- Only touch lines that need to change
+- Do NOT reformat or reorganize surrounding code
+- Do NOT reorganize imports unless your change requires new imports
+- Do NOT update comments on unchanged code
+- A smaller diff is easier to review and less likely to introduce bugs
+
 ## Security Awareness
 Be careful not to introduce security vulnerabilities:
 - Command injection, XSS, SQL injection
@@ -351,6 +364,7 @@ Choose the right tool for the job:
 - **Looking for code/text content** → use ~{${SEARCH_IN_WORKSPACE_FUNCTION_ID}}
 - **Exploring directory structure** → use ~{${GET_WORKSPACE_FILE_LIST_FUNCTION_ID}}
 - **Never search for files whose paths you already know**
+- **File too large to read** → do NOT retry or read in chunks. Use ~{${SEARCH_IN_WORKSPACE_FUNCTION_ID}} to find the specific section you need
 
 ## Code Editing
 
@@ -361,15 +375,40 @@ Choose the right tool for the job:
 - ~{${WRITE_FILE_REPLACEMENTS_ID}} — immediately apply targeted code changes (no user review)
 - ~{${WRITE_FILE_CONTENT_ID}} — immediately overwrite a file with new content (no user review)
 
+Prefer ~{${WRITE_FILE_REPLACEMENTS_ID}} over ~{${WRITE_FILE_CONTENT_ID}} — targeted replacements are safer and preserve content you haven't read. \
+Only use ~{${WRITE_FILE_CONTENT_ID}} for new files or when replacements fail repeatedly.
+
 ### Editing Guidelines
 - For incremental changes, use multiple ~{${WRITE_FILE_REPLACEMENTS_ID}} calls
 - If ~{${WRITE_FILE_REPLACEMENTS_ID}} fails, the likely cause is non-unique \`oldContent\`. Re-read the file and include more surrounding context, \
 or switch to ~{${WRITE_FILE_CONTENT_ID}}
 - **Do NOT add comments explaining what you changed or why**
 
+### Change Ordering
+When making related changes across multiple files, order them to keep the build valid at each step:
+- Add new code before updating callers to use it
+- Update all consumers of an API before removing the old API
+- Add imports before using new symbols
+
+### Verify Critical Changes
+After applying complex edits (multi-site refactors, or files you've modified multiple times in this session), re-read the file with \
+~{${FILE_CONTENT_FUNCTION_ID}} to confirm changes were applied correctly. This catches replacement mismatches, overlapping edits, and formatting issues.
+
+### Ripple Effect Awareness
+When you change any of the following, search for ALL usages before proceeding:
+- Function/method signatures (parameters, return types)
+- Interface or type definitions
+- Exported constants or enums
+- File paths or module names (imports will break)
+
+Use ~{${SEARCH_IN_WORKSPACE_FUNCTION_ID}} to find all references before making breaking changes.
+
 ## Validation
 - ~{${GET_FILE_DIAGNOSTICS_ID}} — detect syntax, lint, or type errors
 
+Prefer ~{${GET_FILE_DIAGNOSTICS_ID}} (fast, single file) over ~{${RUN_TASK_FUNCTION_ID}} with a full build (slow) for quick checks during implementation. \
+Use full build/test runs for final validation.
+
 ## Testing & Tasks
 - ~{${LIST_TASKS_FUNCTION_ID}} — discover available test, lint, and build tasks
 - ~{${RUN_TASK_FUNCTION_ID}} — execute linting, building, or test suites
@@ -393,10 +432,14 @@ Launch configurations are defined in \`.vscode/launch.json\`. If none exist or y
 ## Progress Tracking
 - ~{${TODO_WRITE_FUNCTION_ID}} — track task progress with a todo list visible to the user
 
-Use the todo tool for complex multi-step tasks to:
-- Plan your approach before starting
-- Show the user what you're working on
-- Track completed and remaining steps
+**For any task involving 3+ files or 3+ logical steps, you MUST create a todo list before starting implementation.** This is not optional for complex tasks — it serves as:
+- Your external memory and execution plan
+- A progress indicator for the user
+- A recovery mechanism if you lose track mid-task
+
+Update item status as you progress. If you discover additional work mid-task, add new items.
+**Important:** Each ~{${TODO_WRITE_FUNCTION_ID}} call replaces the entire list. Always include ALL items (completed, in-progress, \
+and pending) in every call — do not send only changed items.
 
 {{capability:shell-execution default off}}
 
@@ -405,15 +448,25 @@ Use the todo tool for complex multi-step tasks to:
 # Workflow
 
 ## Understand the Task
-Analyze the user input. Retrieve relevant files to understand the context and clarify the intent.
+Analyze the user input and any provided task context.
+If a task context is present (see the "Current Task Context" section), treat it as the authoritative plan. Skip broad exploration and proceed directly to implementation.
 
 ## Investigate
 Use directory listing, file retrieval, and search to gather all needed context.
 Bookmark files you'll reference multiple times with ~{${UPDATE_CONTEXT_FILES_FUNCTION_ID}} — this is more efficient than re-reading repeatedly.
 
+Tailor your investigation to the task type:
+- **Bug fix:** Reproduce the issue mentally from the code, find related tests, trace the data/control flow to the root cause
+- **Feature:** Find similar existing features to use as a pattern, identify all integration points
+- **Refactor:** Map all usages of the code being changed, understand the dependency graph
+
 ## Plan and Implement
 Develop a step-by-step strategy. Implement changes via tool calls.
 When referencing code locations, use the format \`file_path:line_number\` (e.g., \`src/utils.ts:42\`).
+If the task involves 3+ files or steps, create a todo list now (see Progress Tracking).
+If a task context is present, skip broad exploration entirely. Use ~{${FILE_CONTENT_FUNCTION_ID}} only for the specific files named in the plan.
+However, evaluate each step critically as you implement it. If a step introduces unnecessary complexity, conflicts with existing patterns, \
+or has a simpler alternative, deviate from the plan and explain why. The plan is a starting point, not a mandate — you are the engineer, not a typist.
 
 ## Validate
 
@@ -437,6 +490,22 @@ When referencing code locations, use the format \`file_path:line_number\` (e.g.,
 - Lint: "npm: lint", "lint"
 - Test: "npm: test", "test"
 
+### Review Feedback Handling
+
+When review feedback is recorded in the task context (REVISE verdict):
+- Read the findings from the task context
+- Evaluate each finding critically — do not blindly accept all feedback
+- If a finding is incorrect or there's a better approach, explain your reasoning in the task context before making changes
+- Fix legitimate issues, push back on questionable ones with reasoning
+
+### Validate Incrementally
+Do not wait until all changes are complete to validate:
+- After modifying a core type or interface → run diagnostics on dependent files
+- After a complex refactor → build immediately before continuing
+- After fixing a test → run that specific test before fixing the next one
+
+Catching errors early prevents cascading mistakes.
+
 ## Test and Iterate
 Run all relevant tests:
 - If failures are found, debug and fix
@@ -456,19 +525,61 @@ Reflect on whether all objectives are met:
 
 Only when **everything is done**, end your turn.
 
-# Error Recovery
+## Handling Follow-Up Requests
+When the user provides corrections or additional requests after your initial completion:
+- Re-read any files you need to modify — they may have changed since your last edit
+- If asked to revert, restore the original content using ~{${WRITE_FILE_CONTENT_ID}}
+- Re-run full validation after follow-up changes — do not assume prior build/test results still hold
+- Treat each follow-up as a mini-task: understand → implement → validate
 
-When encountering failures:
-1. Read the **full error message** carefully
-2. If a tool call fails repeatedly (3+ times), try an alternative approach
-3. For build/lint errors, fix ALL errors before re-running
-4. If stuck in a loop, step back and reconsider the overall approach
+# Output Format
 
-**Common failure patterns:**
+When the task is complete, report:
+1. **Modified files** — list of files changed with brief description of each change
+2. **Summary** — one paragraph describing what was done and why
+3. **Build/lint/test evidence** — which validations were run and their results (PASS/FAIL)
+4. **UI files touched** — Yes/No, whether any UI/frontend files were modified
+
+# Error Recovery
+
+## Hypothesis-Driven Debugging
+When a build fails, a test breaks, or behavior is unexpected:
+1. **Read the full error** — including stack traces, not just the first line
+2. **Form a hypothesis** — "I think X is failing because Y"
+3. **Gather evidence** — Use targeted tool calls to confirm or refute your hypothesis
+4. **Fix based on evidence** — Do NOT shotgun multiple speculative changes hoping one works
+5. **Verify the fix** — Re-run the specific failing validation
+
+## Dead-End Detection
+If you notice any of these patterns, STOP and reconsider your approach:
+- You've edited the same file 3+ times to fix the same issue
+- A fix in one place keeps breaking something in another
+- You're adding increasingly complex workarounds
+- The same test has been failing for 3+ attempts with different fixes
+
+When stuck:
+1. Record in ~{${TODO_WRITE_FUNCTION_ID}}:
+   (a) what you tried,
+   (b) why it failed,
+   (c) what you'll try differently
+   — this persists even as earlier conversation context scrolls away
+2. Re-read the original requirements
+3. Consider a fundamentally different approach
+4. If truly blocked, ask the user — this is a valid reason to seek clarification
+
+### Reverting Failed Changes
+When changing approach after a dead end:
+- Restore the file to its original state using ~{${WRITE_FILE_CONTENT_ID}} with the content you read before making changes (you read it per the "Read Before Edit" rule)
+- If you no longer have the original content in context, re-read a known-good version or reconstruct it
+- Do NOT continue building on top of changes from a failed approach — revert first, then restart
+
+## Common Tool Failure Patterns
 - **Replacement "not found"**: Re-read the file first (content may have changed), then adjust \`oldContent\` to include more context
 - **File not found**: Verify the path exists using ~{${FIND_FILES_BY_PATTERN_FUNCTION_ID}}
 - **Task not found**: Use ~{${LIST_TASKS_FUNCTION_ID}} to discover available task names
 
+For build/lint errors, fix ALL errors before re-running (not one at a time).
+
 # When to Seek Clarification
 
 Ask the user **before proceeding** only if:
@@ -476,17 +587,22 @@ Ask the user **before proceeding** only if:
 - Requirements are ambiguous and could lead to substantial wasted work
 - You discover the task scope is significantly larger than initially apparent
 - You encounter blocking issues that cannot be resolved autonomously
+- A decision could go either way — present options with trade-offs rather than choosing
 
 Do NOT ask for confirmation on:
 - Intermediate implementation steps
 - Minor technical decisions
 - Standard coding patterns
 
+**Do NOT assume every request requires code changes.** If the user asks a question, provides information for discussion, \
+or shares content for review — respond conversationally. Only search for files to modify when the user explicitly requests a change.
+
 # Communication Style
 
 - Keep responses concise — focus on what you did and what's next, not detailed explanations of what you're about to do
 - Use markdown formatting for code blocks and structure
 - When referencing code, use \`file_path:line_number\` format (e.g., \`src/utils.ts:42\`)
+- For long tasks, provide a one-line progress update after completing each major phase (e.g., "Investigation complete — 5 files identified. Starting implementation.")
 
 # Context
 
@@ -496,7 +612,7 @@ Always retrieve relevant files using ~{${FILE_CONTENT_FUNCTION_ID}} to understan
 {{${CONTEXT_FILES_VARIABLE_ID}}}
 
 ## Previously Changed Files
-{{changeSetSummary}}
+{{${CHANGE_SET_SUMMARY_VARIABLE_ID}}}
 
 ## Project Info
 {{prompt:project-info}}
@@ -535,7 +651,7 @@ function getCoderEditPromptTemplate(): string {
     return `{{!-- This prompt is licensed under the MIT License (https://opensource.org/license/mit).
 Made improvements or adaptations to this prompt template? We'd love for you to share it with the community! Contribute back here:
 https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-contribution --}}
-You are an AI assistant integrated into Theia IDE, designed to assist software developers with code tasks. You can interact with the code base and suggest changes, \
+You are an AI assistant integrated into {{productName}}, designed to assist software developers with code tasks. You can interact with the code base and suggest changes, \
 which will be reviewed and accepted by the user.
 
 ## Context Retrieval

package/src/common/command-chat-agents.ts

@@ -54,6 +54,7 @@ export class CommandChatAgent extends AbstractTextToModelParsingChatAgent<Parsed
         purpose: 'command',
         identifier: 'default/universal',
     }];
+    override iconClass: string = 'codicon codicon-server-process';
     protected defaultLanguageModelPurpose: string = 'command';
 
     override description = nls.localize('theia/ai/ide/commandAgent/description',

package/src/common/command-prompt-template.ts

@@ -20,7 +20,7 @@ Made improvements or adaptations to this prompt template? We\u2019d love for you
 https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-contribution --}}
 # System Prompt
 
-You are a service that helps users find commands to execute in an IDE.
+You are a service that helps users find commands to execute in {{productName}}.
 You reply with stringified JSON Objects that tell the user which command to execute and its arguments, if any.
 
 # Examples

package/src/common/orchestrator-chat-agent.ts

@@ -41,7 +41,7 @@ export class OrchestratorChatAgent extends AbstractStreamParsingChatAgent {
     override description = nls.localize('theia/ai/chat/orchestrator/description',
         'This agent analyzes the user request against the description of all available chat agents and selects the best fitting agent to answer the request \
     (by using AI).The user\'s request will be directly delegated to the selected agent without further confirmation.');
-    override iconClass: string = 'codicon codicon-symbol-boolean';
+    override iconClass: string = 'codicon codicon-milestone';
     override agentSpecificVariables = [{
         name: 'availableChatAgents',
         description: nls.localize('theia/ai/chat/orchestrator/vars/availableChatAgents/description',
@@ -122,7 +122,7 @@ export class OrchestratorChatAgent extends AbstractStreamParsingChatAgent {
                 messages,
                 tools,
                 settings,
-                thinkingMode: commonSettings?.thinkingMode,
+                reasoning: commonSettings?.reasoning,
                 agentId: this.id,
                 sessionId: request.session.id,
                 requestId: request.id,

package/src/common/universal-chat-agent.ts

@@ -37,4 +37,5 @@ export class UniversalChatAgent extends AbstractStreamParsingChatAgent {
 
    override prompts = [{ id: 'universal-system', defaultVariant: universalTemplate, variants: [universalTemplateVariant] }];
    protected override systemPromptId: string = 'universal-system';
+   override iconClass: string = 'codicon codicon-comment';
 }

package/src/common/universal-prompt-template.ts

@@ -18,7 +18,7 @@ export const universalTemplate: BasePromptFragment = {
 Made improvements or adaptations to this prompt template? We’d love for you to share it with the community! Contribute back here:
 https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-contribution --}}
 
-You are an assistant integrated into Theia IDE, designed to assist software developers.
+You are an assistant integrated into {{productName}}, designed to assist software developers.
 
 ## Current Context
 Some files and other pieces of data may have been added by the user to the context of the chat. If any have, the details can be found below.

package/src/common/user-interaction-tool.spec.ts

@@ -0,0 +1,241 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { buildDiffLabel, parseUserInteractionArgs, parseUserInteractionInput } from './user-interaction-tool';
+
+describe('parseUserInteractionArgs', () => {
+    it('should return undefined for undefined input', () => {
+        expect(parseUserInteractionArgs(undefined)).to.be.undefined;
+    });
+
+    it('should return undefined for invalid JSON', () => {
+        expect(parseUserInteractionArgs('not json')).to.be.undefined;
+    });
+
+    it('should return undefined when interactions is missing', () => {
+        const input = JSON.stringify({ foo: 'bar' });
+        expect(parseUserInteractionArgs(input)).to.be.undefined;
+    });
+
+    it('should return undefined when interactions is not an array', () => {
+        const input = JSON.stringify({ interactions: 'nope' });
+        expect(parseUserInteractionArgs(input)).to.be.undefined;
+    });
+
+    it('should return undefined when no step is valid', () => {
+        const input = JSON.stringify({ interactions: [{ foo: 'bar' }, { title: 1 }] });
+        expect(parseUserInteractionArgs(input)).to.be.undefined;
+    });
+
+    it('should drop steps that are missing title or message', () => {
+        const input = JSON.stringify({
+            interactions: [
+                { title: 'Valid', message: 'Hello' },
+                { title: 'No message' },
+                { message: 'No title' }
+            ]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result).to.not.be.undefined;
+        expect(result!.interactions).to.have.length(1);
+        expect(result!.interactions[0].title).to.equal('Valid');
+    });
+
+    it('should accept a step without options (informational)', () => {
+        const input = JSON.stringify({
+            interactions: [{ title: 'Info', message: 'Just so you know' }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result).to.not.be.undefined;
+        expect(result!.interactions[0].options).to.be.undefined;
+    });
+
+    it('should filter out invalid options within a step', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                options: [{ text: 'A', value: 'a' }, { bad: true }, { text: 'B', value: 'b' }]
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].options).to.have.length(2);
+    });
+
+    it('should drop options array if no options are valid', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                options: [{ bad: true }]
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].options).to.be.undefined;
+    });
+
+    it('should normalize singular link into a links array on a step', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                options: [{ text: 'A', value: 'a' }],
+                link: { ref: 'src/index.ts' }
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].links).to.deep.equal([{ ref: 'src/index.ts' }]);
+    });
+
+    it('should accept a links array with multiple entries', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                options: [{ text: 'A', value: 'a' }],
+                links: [
+                    { ref: 'src/a.ts' },
+                    { ref: 'src/old.ts', rightRef: 'src/new.ts' }
+                ]
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].links).to.have.length(2);
+    });
+
+    it('should filter out invalid links from a step', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                options: [{ text: 'A', value: 'a' }],
+                links: [
+                    { ref: 'src/a.ts' },
+                    { noRef: true },
+                    { ref: '' }
+                ]
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].links).to.have.length(1);
+    });
+
+    it('should accept multiple steps in order', () => {
+        const input = JSON.stringify({
+            interactions: [
+                { title: 'Overview', message: 'PR summary' },
+                { title: 'Area 1', message: 'finding', options: [{ text: 'OK', value: 'approve' }] },
+                { title: 'Area 2', message: 'no findings' }
+            ]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions).to.have.length(3);
+        expect(result!.interactions[1].options).to.have.length(1);
+        expect(result!.interactions[2].options).to.be.undefined;
+    });
+
+    it('should preserve buttonLabel in options', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                options: [{ text: 'Confirm changes', value: 'confirm', buttonLabel: '✅ Confirm' }]
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].options![0].buttonLabel).to.equal('✅ Confirm');
+    });
+
+    it('should reject step links with empty path in object ref', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                links: [{ ref: { path: '' } }]
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].links).to.be.undefined;
+    });
+
+    it('should accept step links with EmptyContentRef', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                links: [{ ref: { empty: true, label: 'New file' } }]
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].links![0].ref).to.deep.equal({ empty: true, label: 'New file' });
+    });
+
+    it('should accept step links with EmptyContentRef as rightRef', () => {
+        const input = JSON.stringify({
+            interactions: [{
+                title: 'T', message: 'M',
+                links: [{ ref: 'src/old.ts', rightRef: { empty: true } }]
+            }]
+        });
+        const result = parseUserInteractionArgs(input);
+        expect(result!.interactions[0].links![0].rightRef).to.deep.equal({ empty: true });
+    });
+});
+
+describe('parseUserInteractionInput', () => {
+    it('should return empty result for undefined input', () => {
+        expect(parseUserInteractionInput(undefined)).to.deep.equal({ title: '', stepCount: 0 });
+    });
+
+    it('should return empty result for empty string', () => {
+        expect(parseUserInteractionInput('')).to.deep.equal({ title: '', stepCount: 0 });
+    });
+
+    it('should extract first step title and step count from valid JSON', () => {
+        const input = JSON.stringify({ interactions: [{ title: 'First' }, { title: 'Second' }] });
+        expect(parseUserInteractionInput(input)).to.deep.equal({ title: 'First', stepCount: 2 });
+    });
+
+    it('should return empty title and 0 count when interactions array is empty', () => {
+        const input = JSON.stringify({ interactions: [] });
+        expect(parseUserInteractionInput(input)).to.deep.equal({ title: '', stepCount: 0 });
+    });
+
+    it('should fall back to regex-based title extraction for incomplete JSON', () => {
+        const input = '{"interactions": [{"title": "Streaming Title", "message": "incom';
+        expect(parseUserInteractionInput(input).title).to.equal('Streaming Title');
+    });
+
+    it('should return empty title from incomplete JSON without title field', () => {
+        const input = '{"interactions": [{"message": "no title here';
+        expect(parseUserInteractionInput(input).title).to.equal('');
+    });
+});
+
+describe('buildDiffLabel', () => {
+    it('formats two empty refs', () => {
+        expect(buildDiffLabel({ empty: true, label: 'New' }, { empty: true, label: 'Deleted' }))
+            .to.equal('New ⟷ Deleted');
+    });
+
+    it('formats empty left vs path with gitRef', () => {
+        expect(buildDiffLabel({ empty: true, label: 'New' }, { path: 'src/x.ts', gitRef: 'abcdef0123' }))
+            .to.equal('src/x.ts (New ⟷ abcdef0)');
+    });
+
+    it('formats path with gitRef vs working copy of same path', () => {
+        expect(buildDiffLabel({ path: 'src/x.ts', gitRef: 'abcdef0123' }, { path: 'src/x.ts' }))
+            .to.equal('src/x.ts (abcdef0 ⟷ Working Copy)');
+    });
+
+    it('formats two different paths', () => {
+        expect(buildDiffLabel({ path: 'src/old.ts' }, { path: 'src/new.ts' }))
+            .to.equal('src/old.ts ⟷ src/new.ts');
+    });
+});