microsoft / microsoft/foundry-dev-tools
Add Fix with Copilot for failed local agent launches
@qinezh is already working on this.
Since Sep 2, 2026.
- Dominant language
- JavaScript
- Stars
- 2.1k
- Forks
- 260
- Avg merge
- 42m
- Merged PRs (30d)
- 29
Description
[!IMPORTANT]
This experience is currently blocked by a missing terminal canvas capability. The existing API only providessend_terminal_inputandread_terminal_output; it does not expose command identity, process state, completion, cancellation, or exit codes.
Problem
When a user selects Inspect locally, Microsoft Foundry Canvas starts the agent with azd ai agent run --no-client in the integrated terminal. If startup fails—for example, because the Python version does not satisfy a dependency requirement—the terminal displays the actionable error, but Canvas cannot reliably determine that the launch command has exited.
Skylight PR microsoft/Skylight#5862 improves the immediate experience by keeping the terminal focused until the agent becomes reachable. However, Canvas cannot reliably return with a failure state or offer Fix with Copilot because the required process-level terminal API does not exist today.
Why the current API is insufficient
send_terminal_inputconfirms only that text was written to the shell; it does not identify or track the resulting process.read_terminal_outputreturns rendered terminal text; it does not indicate whether the command is still running or what exit code it produced.- Port readiness distinguishes a successfully started agent from one that is not ready, but it cannot distinguish slow startup from an exited command.
- Shell wrappers and marker parsing would alter the visible command, add noise to troubleshooting context, and require shell-specific behavior.
Proposed experience
- Keep the terminal visible while the local agent starts.
- When the launch command exits unsuccessfully, return to Foundry Canvas with a concise failure state.
- Offer Fix with Copilot, Open terminal, and Retry actions.
- Send a bounded terminal-output tail to Copilot only after the user selects Fix with Copilot.
Required new API capability
Add a terminal canvas API that executes the original visible command and exposes structured lifecycle information, for example:
run_terminal_command -> { commandId }
get_terminal_command_status -> {
state: "running" | "completed" | "failed" | "cancelled",
exitCode?: number,
outputTail?: string
}
An event-driven completion notification would also work. The API must correlate status with the specific command, rather than with the terminal instance alone.
How this API solves the issue
- Reliable failure detection: a nonzero exit code immediately distinguishes failure from slow startup.
- No command pollution: the terminal shows the original
azd ai agent run --no-clientcommand without wrappers or markers. - Accurate Copilot context: Canvas can attach the output associated with the failed command rather than unrelated terminal scrollback.
- Safe user consent: output is sent to Copilot only after the user selects Fix with Copilot.
- Correct state transitions: Canvas can separately handle successful startup, command failure, user cancellation, terminal closure, and timeout.
Acceptance criteria
- Canvas can execute the original command and receive a stable command identifier.
- Canvas can determine whether that command is running, completed, failed, or cancelled and obtain its exit code.
- Failure diagnostics can include a bounded, ANSI-resolved output tail correlated to that command.
- Terminal cancellation and closure are represented distinctly from command failure.
- Foundry Canvas can use the result to present a reliable, user-initiated Fix with Copilot action.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.