microsoft / microsoft/foundry-dev-tools

Add Fix with Copilot for failed local agent launches

Open
#731 1 comment 0 reactions 1 assignee View on GitHub

@qinezh is already working on this.

Since Sep 2, 2026.

canvas enhancement
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 provides send_terminal_input and read_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_input confirms only that text was written to the shell; it does not identify or track the resulting process.
  • read_terminal_output returns 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

  1. Keep the terminal visible while the local agent starts.
  2. When the launch command exits unsuccessfully, return to Foundry Canvas with a concise failure state.
  3. Offer Fix with Copilot, Open terminal, and Retry actions.
  4. 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-client command 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.