starred/aryx
1
0
Fork 0
mirror of https://github.com/davidkaya/aryx.git synced 2026-07-24 13:38:43 +02:00
Code Issues 3 Packages Projects Releases 10 Wiki Activity

docs: remove plans

Browse Source
This commit is contained in:
David Kaya
2026-03-22 15:13:29 +01:00
parent bf5aa7ce57
commit af3a60501c
2 changed files with 0 additions and 332 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BACKEND_UI_CHANGES.md
-107
View File
@@ -1,107 +0,0 @@
# Backend UI Changes
This document describes the implemented .NET sidecar / backend protocol changes that enable richer agent-activity reporting in the chat UI.
The repository now emits and consumes `agent-activity` events end to end. Because the current MAF workflow stream does not expose every lifecycle detail uniformly, activity events are emitted only when they can be detected reliably from the available workflow events.
## Context
The chat UI now shows a "Thinking…" indicator while the agent processes a request (before streaming starts) and a blinking cursor while the response streams in. These states are inferred from the existing `status` and `message-delta` session events.
To display more granular activity (e.g. "Using tool X…", "Agent Y is thinking…", "Handing off to Agent Z…"), the sidecar protocol uses a new event kind.
## Protocol addition
### New event kind: `agent-activity`
Add a new value `'agent-activity'` to `SessionEventKind` in `src/shared/domain/event.ts`:
```typescript
export type SessionEventKind =
| 'status'
| 'message-delta'
| 'message-complete'
| 'agent-activity' // ← new
| 'error';
```
### New fields on `SessionEventRecord`
```typescript
export interface SessionEventRecord {
sessionId: string;
kind: SessionEventKind;
occurredAt: string;
// Existing fields…
status?: 'idle' | 'running' | 'error';
messageId?: string;
authorName?: string;
contentDelta?: string;
error?: string;
// New fields for 'agent-activity' events
activityType?: 'thinking' | 'tool-calling' | 'handoff' | 'completed';
agentId?: string;
agentName?: string;
toolName?: string;
}
```
### Sidecar event mapping
The .NET sidecar emits `agent-activity` events when the workflow stream exposes these points reliably:
| MAF lifecycle point | `activityType` | `agentName` | `toolName` |
|---|---|---|---|
| Agent begins processing a turn | `thinking` | agent name | — |
| Agent invokes a tool | `tool-calling` | agent name | tool name |
| Handoff orchestration transfers control | `handoff` | target agent name | — |
| Agent finishes its contribution | `completed` | agent name | — |
In practice, `thinking` and `completed` are driven by executor lifecycle events, while `tool-calling` and `handoff` are emitted when request-info payloads expose recognizable tool-call or handoff targets.
One important runtime nuance is that MAF / Copilot executor identifiers are not always the raw configured agent IDs. Real streams can emit composite values such as `Architect_agent_concurrent_architect` or generic names such as `assistant`. The sidecar therefore normalizes these runtime identifiers back to the configured pattern agents before emitting `agent-activity` events or choosing the visible author name. This is especially important in handoff flows, where the target agent can continue emitting generic `assistant` updates after control transfer; the sidecar now carries the handed-off identity forward so those updates and final messages still belong to the real target agent.
### .NET sidecar changes
In the sidecar's turn-execution pipeline, emit a new JSON event type alongside the existing `turn-delta` and `turn-complete` events:
```json
{
"type": "agent-activity",
"requestId": "…",
"sessionId": "…",
"activityType": "tool-calling",
"agentId": "agent-reviewer",
"agentName": "Code Reviewer",
"toolName": "read_file"
}
```
The Electron main process maps this to a `SessionEventRecord` with `kind: 'agent-activity'` and forwards it to the renderer via the existing `sessions:event` channel.
### Renderer consumption
`App.tsx` now subscribes to `onSessionEvent`, applies message-delta / message-complete updates into renderer workspace state so assistant responses can stream live, and tracks live activity per agent for the selected session. `ChatPane.tsx` uses that state to show a status row for each agent while the run is active.
- "Code Reviewer is thinking…"
- "Code Reviewer is using read_file…"
- "Handing off to Summarizer…"
The activity panel in `ChatPane.tsx` is now wired to this data, showing every agent in the pattern with observed activity such as thinking, tool usage, handoff, or completed. If no event has been observed for an agent yet, the UI states that no status has been reported instead of inventing a synthetic state. The panel also keeps the last observed statuses visible after a run completes, and resets them when the next run begins. Completed activity is emitted when final messages are applied, so the status no longer jumps to `Completed` before the corresponding response becomes visible.
## Files involved
| Layer | File | Change |
|---|---|---|
| Shared | `src/shared/domain/event.ts` | Add `'agent-activity'` to `SessionEventKind`, add optional `activityType` / `agentId` / `agentName` / `toolName` fields |
| Shared | `src/shared/contracts/sidecar.ts` | Add `AgentActivityEvent` to the sidecar event union, including a stable optional `agentId` |
| Main | `src/main/sidecar/sidecarProcess.ts` | Parse `agent-activity` events from sidecar JSON output |
| Main | `src/main/KopayaAppService.ts` | Map parsed activity events to `SessionEventRecord` and emit via `session-event` |
| Renderer | `src/renderer/App.tsx` | Subscribe to `onSessionEvent` and track live per-agent activity state per session |
| Renderer | `src/renderer/components/ChatPane.tsx` | Render an activity row for each agent while a session is running |
| Renderer | `src/renderer/lib/sessionActivity.ts` | Provide pure helpers for per-agent activity-state updates and display text |
| Sidecar | `sidecar/src/Kopaya.AgentHost/Contracts/ProtocolModels.cs` | Define `AgentActivityEventDto`, including `agentId` |
| Sidecar | `sidecar/src/Kopaya.AgentHost/Services/CopilotWorkflowRunner.cs` | Emit `agent-activity` events during MAF turn execution when observable |
| Sidecar | `sidecar/src/Kopaya.AgentHost/Services/SidecarProtocolHost.cs` | Forward activity events over the stdio protocol |
IMPLEMENTATION_PLAN.md
-225
View File
@@ -1,225 +0,0 @@
# 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.