aryx/IMPLEMENTATION_PLAN.md

Kopaya Implementation Plan

This file mirrors the working plan in the Copilot session workspace so the repository also carries the current implementation direction.

Problem statement

Build kopaya into an Electron desktop application for orchestrating AI agents across multiple local projects. The desktop app should use TypeScript on the frontend, use the .NET version of Microsoft Agent Framework (MAF) with Copilot SDK for orchestration/runtime work, support all MAF orchestration modes, and also support a simple Copilot-CLI-style 1-on-1 human/agent chat mode.

Users should be able to:

• open and manage multiple project folders
• define reusable orchestration patterns
• create sessions inside a selected project by choosing a pattern
• view and continue active/past sessions from a chat-first UI

The target UX is a left-side tree navigator for projects/sessions/patterns and a right-side main chat pane.

Current repository state

• The repository now contains a working Electron desktop shell with a React + Tailwind renderer, shared TypeScript domain/contracts, persistence, IPC wiring, and a bundled .NET sidecar.
• The chat-first workspace UX is implemented with projects, sessions, pattern management, session launch, and streaming transcript updates.
• The .NET sidecar implements single-agent chat plus sequential, concurrent, handoff, and group-chat orchestration modes.
• Magentic remains intentionally unavailable because Microsoft still documents it as unsupported in C#/.NET today.
• Copilot integration now uses the system-installed copilot command instead of the SDK's bundled native CLI path.
• On Windows, the app sanitizes Bun/Copilot/Electron/Node/npm runtime variables and shell-launches copilot through cmd.exe /d /s /c copilot to avoid the --no-warnings startup failure under Bun/Electron.
• Validation workflows are established and verified in this repository: bun run test, .NET sidecar tests/builds, and packaging for the Windows desktop app.

Product scope captured so far

• Desktop application built with Electron
• Standalone self-contained desktop app that bundles its local .NET backend
• Frontend implemented with React + Tailwind CSS in TypeScript
• Backend orchestration engine implemented with .NET + Microsoft Agent Framework
• Only Copilot SDK-backed agents are in scope for v1
• Users authenticate with their Copilot account
• Support for all MAF orchestration modes currently documented for workflows:
  • sequential
  • concurrent
  • handoff
  • group chat
  • magentic (represented as unavailable in the current .NET implementation because Microsoft documents it as unsupported in C# today)
• Additional first-class single-agent chat mode for direct human-agent conversation
• Multiple projects/folders open in the app at the same time
• Reusable user-defined orchestration patterns stored in a global app-wide pattern library
• Session creation flow where the user selects both project and pattern

Recommended architecture

1. Hybrid desktop structure

• Electron main process
  • application lifecycle
  • native dialogs and folder selection
  • spawning and supervising the .NET agent host
  • IPC boundary to the renderer
  • secure access to persisted local configuration
• Electron renderer
  • chat-first application shell
  • tree navigation for projects, sessions, and patterns
  • pattern management screens
  • session creation and session transcript views
• .NET agent host
  • wraps Microsoft Agent Framework orchestration capabilities
  • hosts Copilot SDK integrations
  • creates/runs sessions
  • validates and executes user-defined orchestration patterns
  • streams structured events back to Electron

2. Domain model

• Workspace: top-level local app state
• Project: a user-selected folder with metadata and project-specific sessions
• Pattern: reusable orchestration definition with mode, participating agents, instructions, and execution options
• Agent definition: provider/model/instructions/tools metadata used inside a pattern
• Session: a concrete run bound to one project and one pattern
• Turn/Event: chat messages, orchestration state changes, tool events, handoffs, completion states

3. Runtime boundary

• Confirmed v1 approach: Electron main launches a bundled local .NET sidecar process as part of a standalone self-contained app.
• Use a versioned structured contract for commands/events between Electron and the .NET host.
• The contract must support:
  • session creation
  • send message / user input
  • streaming assistant and orchestration events
  • session pause/abort/resume
  • pattern CRUD and validation
  • project/workspace metadata sync

4. UX slices

• Left tree navigator
  • workspace
  • projects
  • sessions under each project
  • shared global pattern library
• Right main pane
  • chat transcript
  • composer
  • session header/status
  • selected pattern summary
  • orchestration timeline or event rail for multi-agent runs
• Create session flow
  • choose project
  • choose pattern
  • optionally override models/instructions
  • launch and stream activity into the chat pane

5. Persistence

• Persist workspace metadata, known projects, patterns, sessions, transcripts, and resumable orchestration metadata in app data.
• Keep project source code in place; only store references to folders, not copies.
• Separate durable user configuration from transient runtime state.
• Store secrets and credentials in the OS keychain only.

6. Testing strategy

• TypeScript tests for desktop domain logic and renderer state
• .NET tests for pattern validation and orchestration execution
• Contract/integration tests for Electron-to-.NET messaging
• End-to-end smoke coverage for launching a project, starting a session, and streaming chat output

Current implementation status

• Phases 1 through 6 are substantially complete for the currently supported scope.
• Desktop shell, persistence, pattern management, session launch, streaming chat UX, sidecar protocol, packaging, and validation coverage are implemented.
• The Copilot runtime path is now productionized around the system-installed CLI, including protocol compatibility upgrades and Windows/Bun launch hardening.
• The only explicitly blocked roadmap item is Magentic orchestration support, which depends on upstream C#/.NET support in Microsoft Agent Framework.
• Future planning should treat the current work as a functioning baseline that mainly needs iterative polish and any new product features, not initial scaffolding.

Proposed implementation phases

Phase 1 - Bootstrap the hybrid repository

• Add Electron application structure
• Add renderer application structure in TypeScript
• Add a .NET solution for the agent host
• Add unified local development scripts
• Establish repository layout for TS app and .NET backend

Phase 2 - Define contracts and persistence

• Define workspace/project/pattern/session models
• Define command/event contracts between Electron and .NET
• Implement local persistence for workspace metadata and transcripts
• Implement durable session state/checkpoint persistence for resume after restart
• Integrate secure credential access through the OS keychain
• Add validation rules for pattern definitions

Phase 3 - Implement the .NET agent host

• Integrate Microsoft Agent Framework and Copilot SDK-backed agents
• Build single-agent chat mode
• Build orchestration execution adapters for each supported MAF mode
• Implement streaming lifecycle events and error propagation

Phase 4 - Build the desktop shell

• Build the chat-first application shell
• Implement the left-side tree navigator
• Implement session list/detail routing and selection state
• Implement project add/remove flows

Phase 5 - Pattern authoring and session launch

• Build pattern list/editor UX
• Support agent configuration inside a pattern
• Allow session creation from a selected project and pattern
• Surface validation errors before launch

Phase 6 - Reliability and polish

• Resume/reload session state after app restart
• Improve long-running orchestration visibility
• Add packaging, logging, and diagnostics
• Expand test coverage and development ergonomics

Initial todo inventory

1. bootstrap-electron-hybrid-repo
   Create the Electron + TypeScript renderer scaffold and add the .NET solution layout for the MAF host.

2. define-domain-and-contracts
   Define workspace, project, pattern, agent, session, and event models plus the Electron/.NET command-event contract.

3. implement-persistence-layer
   Persist workspace metadata, project references, patterns, session summaries, transcripts, and resumable state.

4. build-dotnet-agent-host
   Create the .NET host process and integrate Microsoft Agent Framework plus Copilot SDK-backed agent support.

5. implement-single-agent-chat-mode
   Deliver simple Copilot-CLI-style 1-on-1 chat as a first-class session type.

6. wire-maf-orchestration-modes
   Add sequential, concurrent, handoff, group chat, and magentic pattern execution support.

7. build-electron-shell-and-navigation
   Implement the left tree navigator and the chat-first main pane.

8. build-pattern-management-ui
   Add CRUD workflows for reusable orchestration patterns and agent definitions.

9. build-session-launch-and-streaming-ui
   Allow users to choose a project and pattern, start a session, and watch streaming events in chat.

10. add-tests-and-packaging
    Add TypeScript/.NET/contract coverage and prepare desktop packaging and local developer workflows.

Confirmed product decisions

• The app is packaged as a standalone self-contained Electron product with a bundled local .NET sidecar.
• The renderer uses React + Tailwind CSS.
• User-defined patterns are editable, reusable, and managed as a global library shared across projects.
• Sessions must resume after app restart and recover orchestration/chat state.
• Only Copilot SDK-backed agents are in scope for v1, using the user's Copilot account.
• The app always uses the system-installed copilot CLI; on Windows it launches that CLI through the shell and sanitizes runtime environment variables for Bun/Electron compatibility.
• Secrets and provider credentials are stored through the OS keychain.
• The current .NET implementation supports sequential, concurrent, handoff, and group chat; Magentic is surfaced as unavailable until C# support exists upstream.

Remaining assumptions

• One desktop window is sufficient for v1.
• The right pane is primarily a chat experience, not a details-first inspector.
• Multi-agent orchestration should surface its event stream in a chat-adjacent way rather than in a separate heavy workflow designer first.