Skip to content

AGENTS.md

Latest commit

 

History

History
184 lines (146 loc) · 7.04 KB

AGENTS.md

File metadata and controls

184 lines (146 loc) · 7.04 KB
Raw

Intelligent Terminal

Intelligent Terminal is a Windows Terminal fork that adds first-class AI agent workflows. The inherited Windows Terminal build, architecture, and C++ conventions are documented in .github/copilot-instructions.md; this file contains only the fork-specific context.

Architecture

WindowsTerminal.exe
  |-- TerminalProtocolComServer (COM, discovered through WT_COM_CLSID)
  |-- SharedWta --> wta-master --> agent CLI pool (ACP over stdio)
  +-- one wta-helper pane per tab
                       |
                       +-- helper/master ACP over a named pipe
                       +-- session-scoped MCP tools

Agent or human CLI --> wta/wtcli --> COM IProtocolServer --> Windows Terminal
  • WTA (tools/wta/) is the Rust orchestrator.
  • ACP means Agent Client Protocol. wta-master lazily owns a pool of agent CLI processes keyed by agent identity, execution source, and command; helpers using the same key share one process and multiplex sessions through it.
  • WT Protocol is the terminal-control boundary. wtcli.exe activates IProtocolServer through the package COM registration.
  • Session MCP exposes run_command_in_current_shell, create_workspace, delegate_task_in_new_workspace, and request_user_input. It routes requests to the owning helper and never executes terminal actions itself.
  • Agent panes are ordinary ConptyConnection panes hosting wta-helper; C++ does not speak ACP.

See doc/specs/Multi-window-agent-pane.md for the detailed lifecycle and tools/wta/AGENTS.md for WTA-specific implementation rules.

Supported agents and settings

Built-in ACP and delegation providers are Copilot, Claude, Codex, Gemini, and OpenCode. Custom providers use a custom:<name> ID plus the matching custom command setting.

{
    "acpAgent": "copilot",
    "acpModel": "",
    "acpCustomCommand": "",
    "delegateAgent": "copilot",
    "delegateModel": "",
    "delegateCustomCommand": "",
    "agentPanePosition": "bottom",
    "autoErrorDetectionEnabled": true,
    "autoFixEnabled": false,
    "aiIntegration.coordinator.enabled": false,
    "aiIntegration.coordinator.commandline": "wta",
    "aiIntegration.coordinator.profile": "{fd19208a-412b-4857-8a2d-9ca592b4b16e}",
    "aiIntegration.confirmation.readOperations": "auto",
    "aiIntegration.confirmation.createOperations": "auto",
    "aiIntegration.confirmation.inputOperations": "auto"
}

The settings model is authoritative; check src/cascadia/TerminalSettingsModel/MTSMSettings.h and src/cascadia/inc/AgentRegistry.h before documenting defaults or providers.

User-facing behavior

Trigger Behavior
>Toggle AI assistant Stash or restore the current tab's agent pane
?<prompt> Delegate a prompt through WTA
? No-op
&<prompt> Reserved background-task entry point; currently a no-op

Important invariants:

  • Each eligible tab pre-warms one stashed helper. Skip pre-warm when WTA is unavailable, policy blocks all agents, the tab has no active terminal, or a dragged-in agent pane already exists.
  • Toggling an agent pane stashes/restores it; it does not destroy the helper, ACP session, or chat history.
  • Per-tab events carry tab and window identity. Route responses to the owning tab instead of broadcasting across panes or windows.
  • Autofix requires a connected helper session. Failures received before the session connects are not replayed later.
  • Terminal mutation requested by an agent goes through the confirmation-gated session MCP action path. Agent-owned shell tools are a separate execution path.

Key files

Area Path
Terminal integration src/cascadia/TerminalApp/TerminalPage.cpp
Protocol bridge src/cascadia/TerminalApp/TerminalPage.Protocol.cpp
Tab lifecycle and pre-warm src/cascadia/TerminalApp/TabManagement.cpp
Agent pane chrome src/cascadia/TerminalApp/AgentPaneContent.cpp
Stash/restore src/cascadia/TerminalApp/Tab.cpp
Shared WTA process src/cascadia/TerminalApp/SharedWta.cpp
COM server src/cascadia/WindowsTerminal/TerminalProtocolComServer.cpp
Protocol IDL src/cascadia/TerminalProtocol/TerminalProtocol.idl
Agent registry src/cascadia/inc/AgentRegistry.h
Settings src/cascadia/TerminalSettingsModel/MTSMSettings.h
WTA master/helper tools/wta/src/master/mod.rs, tools/wta/src/helper/mod.rs
Runtime agent prompt tools/wta/prompts/terminal-agent.md

Build and validation

WTA and Terminal use separate build systems. Build WTA before packaging changes that need a refreshed wta.exe.

WTA

Always use the explicit Windows target. CascadiaPackage.wapproj prefers this output over the host-target fallback, so mixing target layouts can silently deploy a stale binary.

cargo build --target x86_64-pc-windows-msvc --manifest-path tools/wta/Cargo.toml
cargo test --target x86_64-pc-windows-msvc --manifest-path tools/wta/Cargo.toml

Output: tools/wta/target/x86_64-pc-windows-msvc/debug/wta.exe.

A live WTA process may lock the output. Stop only processes whose executable path exactly matches the binary being rebuilt; never terminate every wta.exe or WindowsTerminal.exe by name.

Terminal

cmd.exe /c "tools\razzle.cmd && bcz no_clean"

For Release use bcz rel no_clean. For a project-local incremental build, enter the project directory in the same razzle CMD session and use bx.

After C++, XAML, IDL, packaging, resource, or mixed Debug changes, deploy with:

.\build\scripts\Invoke-IntelligentTerminalDebugDeployment.ps1 `
    -AppxRecipePath src\cascadia\CascadiaPackage\bin\x64\Debug\CascadiaPackage.build.appxrecipe

Do not perform a full package deployment for a wta.exe-only change. Static assets such as wt-agent-hooks do require packaging.

Runtime data and diagnostics

Packaged state and cache data are package-private:

  • State: Packages\<PFN>\LocalState\IntelligentTerminal
  • Cache/logs: Packages\<PFN>\LocalCache\Local\IntelligentTerminal
  • Logs: logs\<package-version>\

Unpackaged development falls back to %LOCALAPPDATA%\IntelligentTerminal. Resolve paths through the shared runtime path helpers; do not hard-code %TEMP% or a bare LocalAppData path.

Primary logs are:

  • wta-main_master.log
  • wta-main_helper-{pid}.log
  • wta-cli.log
  • wta-delegate.log
  • wta-probe.log
  • wta-install-hooks.log
  • wta-ensure-host.log
  • wta-acp-debug.log
  • terminal-agent-pane.log

Use WTA_LOG=debug or WTA_LOG=trace for additional Rust tracing. See tools/wta/README.md for current diagnostics and CLI usage.

Focused design references

  • Multi-window helper/master lifecycle: doc/specs/Multi-window-agent-pane.md
  • Session tracking: doc/specs/hybrid-agent-session-tracking.md
  • Security boundaries: doc/security-model.md
  • Installer: doc/building-installer.md
  • WTA customization: tools/wta/CUSTOMIZATION.md