| 1 | # Workroom Architecture |
| 2 | |
| 3 | > 阅读简体中文版：[zh_hans/WORKROOM_ARCHITECTURE.md](zh_hans/WORKROOM_ARCHITECTURE.md)。 |
| 4 | |
| 5 | ## Purpose |
| 6 | |
| 7 | Workrooms are Codewhale's chat-native abstraction for durable, addressable |
| 8 | threads of agent work. They sit between the Runtime API's transient thread |
| 9 | model and the user-facing surfaces (TUI, mobile, chat bridges). |
| 10 | |
| 11 | This is a draft v0.9 architecture note. In v0.8.62, only the protocol data |
| 12 | types and link parser are present. Runtime endpoints, persistent state, mobile |
| 13 | rendering, and model-visible link resolution are planned follow-ups. |
| 14 | |
| 15 | ## Component map |
| 16 | |
| 17 | ``` |
| 18 | ┌─────────────────────────────────────────────────────┐ |
| 19 | │ User surfaces │ |
| 20 | │ ┌──────┐ ┌─────────┐ ┌──────────┐ │ |
| 21 | │ │ TUI │ │ Mobile │ │ Bridges │ │ |
| 22 | │ └──┬───┘ └────┬────┘ └────┬─────┘ │ |
| 23 | │ │ │ │ │ |
| 24 | │ └───────────┼────────────┘ │ |
| 25 | │ │ future HTTP + workroom links │ |
| 26 | ├─────────────────┼───────────────────────────────────┤ |
| 27 | │ Runtime API │ │ |
| 28 | │ ┌──────────────┴──────────────┐ │ |
| 29 | │ │ Planned workroom endpoints │ │ |
| 30 | │ │ GET /workrooms │ │ |
| 31 | │ │ GET /workroom/:id/threads │ │ |
| 32 | │ │ GET /workroom/resolve │ │ |
| 33 | │ └──────────────┬─────────────┘ │ |
| 34 | │ │ │ |
| 35 | │ ┌──────────────┴─────────────┐ │ |
| 36 | │ │ Existing endpoints │ │ |
| 37 | │ │ /thread /app /prompt ... │ │ |
| 38 | │ └────────────────────────────┘ │ |
| 39 | └─────────────────────────────────────────────────────┘ |
| 40 | ``` |
| 41 | |
| 42 | ## Data flow |
| 43 | |
| 44 | 1. **Creation.** A future workroom is created when a thread is started with a |
| 45 | workroom context (title, workspace, external refs). The workroom id |
| 46 | is stable and can be shared as a `codewhale://workroom/...` link. |
| 47 | |
| 48 | 2. **Event publication.** Each agent action (tool call, approval, failure) |
| 49 | is recorded as a `WorkroomEvent` in the workroom's event log. Events |
| 50 | carry `AgentAttribution` metadata tracing which provider, model, and |
| 51 | agent produced them. |
| 52 | |
| 53 | 3. **Link resolution.** When a `codewhale://workroom/...` link appears in |
| 54 | a chat surface, a future `resolve_workroom_link` tool (or API endpoint) |
| 55 | parses it and returns scoped context: thread metadata, external refs, |
| 56 | and recent event summaries. The calling model can then decide whether |
| 57 | to read the full thread transcript. |
| 58 | |
| 59 | 4. **Listing.** A future `/workrooms` endpoint returns a summary of all visible |
| 60 | workrooms (id, title, updated_at, active thread count). Surfaces |
| 61 | consume this for inbox/recent-activity views. |
| 62 | |
| 63 | ## State store |
| 64 | |
| 65 | Persisted workroom state should live alongside existing Codewhale state: |
| 66 | |
| 67 | ``` |
| 68 | ~/.codewhale/ |
| 69 | ├── workrooms/ |
| 70 | │ ├── wr_abc123.json # Workroom metadata + event log |
| 71 | │ └── wr_def456.json |
| 72 | ├── threads/ # Existing thread state (unchanged) |
| 73 | ├── checkpoints/ |
| 74 | ├── config.toml |
| 75 | └── ... |
| 76 | ``` |
| 77 | |
| 78 | Each `.json` file would contain the workroom metadata (`Workroom` struct), |
| 79 | a list of `WorkroomThread` descriptors, and a bounded set of recent |
| 80 | `WorkroomEvent` records. This state store is not implemented yet. |
| 81 | |
| 82 | ## Crate responsibilities |
| 83 | |
| 84 | | Crate | Responsibility | |
| 85 | |---|---| |
| 86 | | `codewhale-protocol` | Types: `Workroom`, `WorkroomId`, `WorkroomThread`, `WorkroomEvent`, `WorkroomLink`, `ExternalThreadRef`, `AgentAttribution` | |
| 87 | | `codewhale-app-server` | Future endpoints: `GET /workrooms`, `GET /workroom/:id/threads`, `GET /workroom/resolve` | |
| 88 | | `codewhale-tui` | Future model-facing link resolution and optional workbar inbox | |
| 89 | | `codewhale-state` | Future: persistent workroom store (Phase 2) | |
| 90 | |
| 91 | ## Phase status |
| 92 | |
| 93 | | Phase | Feature | Status | |
| 94 | |---|---|---| |
| 95 | | 1 | RFC design doc | ✅ Complete | |
| 96 | | 1 | Protocol data types | ✅ Complete (with tests) | |
| 97 | | 1 | App-server workroom endpoints | ⏳ Not started | |
| 98 | | 1 | `resolve_workroom_link` tool | ⏳ Not started | |
| 99 | | 1 | Security model docs | ✅ Complete | |
| 100 | | 1 | Architecture docs | ✅ Complete | |
| 101 | | 2 | Persistent workroom state store | ⏳ Not started | |
| 102 | | 2 | Mobile page workroom inbox | ⏳ Not started | |
| 103 | | 2 | Chat bridge event integration | ⏳ Not started | |
| 104 | | 2 | TUI workbar inbox | ⏳ Not started | |
| 105 |