mirror of
https://github.com/Hmbown/DeepSeek-TUI.git
synced 2026-09-03 06:50:13 +08:00
92547e460f
* chore: use the public name Codewhale in prose Replace the word CodeWhale with the ratified public name Codewhale in public prose only: docs/**, all 15 TUI locale packs, and user-facing Rust string literals in crates/tui/src (update/help/status/error copy plus the tests that assert on that copy). Compatibility identifiers are untouched: the Hmbown/CodeWhale GitHub slug and every URL containing it, Hmbown.CodeWhale (winget), Windows install paths (%LOCALAPPDATA%\Programs\CodeWhale\bin), clone directories (cd CodeWhale), user-agent and header strings, gherkin step names, test fixtures, doc comments, CHANGELOG history, README URLs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014aDEyM2a4pPZ9qqMDrP5YX Signed-off-by: CodeWhale Bot <bot@codewhale.net> * chore: bundled plan skill prose uses the public name Codewhale Signed-off-by: CodeWhale Bot <bot@codewhale.net> --------- Signed-off-by: CodeWhale Bot <bot@codewhale.net> Co-authored-by: CodeWhale Bot <bot@codewhale.net> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
103 lines
5.1 KiB
Markdown
103 lines
5.1 KiB
Markdown
# Workroom Architecture
|
|
|
|
## Purpose
|
|
|
|
Workrooms are Codewhale's chat-native abstraction for durable, addressable
|
|
threads of agent work. They sit between the Runtime API's transient thread
|
|
model and the user-facing surfaces (TUI, mobile, chat bridges).
|
|
|
|
This is a draft v0.9 architecture note. In v0.8.62, only the protocol data
|
|
types and link parser are present. Runtime endpoints, persistent state, mobile
|
|
rendering, and model-visible link resolution are planned follow-ups.
|
|
|
|
## Component map
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ User surfaces │
|
|
│ ┌──────┐ ┌─────────┐ ┌──────────┐ │
|
|
│ │ TUI │ │ Mobile │ │ Bridges │ │
|
|
│ └──┬───┘ └────┬────┘ └────┬─────┘ │
|
|
│ │ │ │ │
|
|
│ └───────────┼────────────┘ │
|
|
│ │ future HTTP + workroom links │
|
|
├─────────────────┼───────────────────────────────────┤
|
|
│ Runtime API │ │
|
|
│ ┌──────────────┴──────────────┐ │
|
|
│ │ Planned workroom endpoints │ │
|
|
│ │ GET /workrooms │ │
|
|
│ │ GET /workroom/:id/threads │ │
|
|
│ │ GET /workroom/resolve │ │
|
|
│ └──────────────┬─────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────┴─────────────┐ │
|
|
│ │ Existing endpoints │ │
|
|
│ │ /thread /app /prompt ... │ │
|
|
│ └────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Data flow
|
|
|
|
1. **Creation.** A future workroom is created when a thread is started with a
|
|
workroom context (title, workspace, external refs). The workroom id
|
|
is stable and can be shared as a `codewhale://workroom/...` link.
|
|
|
|
2. **Event publication.** Each agent action (tool call, approval, failure)
|
|
is recorded as a `WorkroomEvent` in the workroom's event log. Events
|
|
carry `AgentAttribution` metadata tracing which provider, model, and
|
|
agent produced them.
|
|
|
|
3. **Link resolution.** When a `codewhale://workroom/...` link appears in
|
|
a chat surface, a future `resolve_workroom_link` tool (or API endpoint)
|
|
parses it and returns scoped context: thread metadata, external refs,
|
|
and recent event summaries. The calling model can then decide whether
|
|
to read the full thread transcript.
|
|
|
|
4. **Listing.** A future `/workrooms` endpoint returns a summary of all visible
|
|
workrooms (id, title, updated_at, active thread count). Surfaces
|
|
consume this for inbox/recent-activity views.
|
|
|
|
## State store
|
|
|
|
Persisted workroom state should live alongside existing Codewhale state:
|
|
|
|
```
|
|
~/.codewhale/
|
|
├── workrooms/
|
|
│ ├── wr_abc123.json # Workroom metadata + event log
|
|
│ └── wr_def456.json
|
|
├── threads/ # Existing thread state (unchanged)
|
|
├── checkpoints/
|
|
├── config.toml
|
|
└── ...
|
|
```
|
|
|
|
Each `.json` file would contain the workroom metadata (`Workroom` struct),
|
|
a list of `WorkroomThread` descriptors, and a bounded set of recent
|
|
`WorkroomEvent` records. This state store is not implemented yet.
|
|
|
|
## Crate responsibilities
|
|
|
|
| Crate | Responsibility |
|
|
|---|---|
|
|
| `codewhale-protocol` | Types: `Workroom`, `WorkroomId`, `WorkroomThread`, `WorkroomEvent`, `WorkroomLink`, `ExternalThreadRef`, `AgentAttribution` |
|
|
| `codewhale-app-server` | Future endpoints: `GET /workrooms`, `GET /workroom/:id/threads`, `GET /workroom/resolve` |
|
|
| `codewhale-tui` | Future model-facing link resolution and optional sidebar inbox |
|
|
| `codewhale-state` | Future: persistent workroom store (Phase 2) |
|
|
|
|
## Phase status
|
|
|
|
| Phase | Feature | Status |
|
|
|---|---|---|
|
|
| 1 | RFC design doc | ✅ Complete |
|
|
| 1 | Protocol data types | ✅ Complete (with tests) |
|
|
| 1 | App-server workroom endpoints | ⏳ Not started |
|
|
| 1 | `resolve_workroom_link` tool | ⏳ Not started |
|
|
| 1 | Security model docs | ✅ Complete |
|
|
| 1 | Architecture docs | ✅ Complete |
|
|
| 2 | Persistent workroom state store | ⏳ Not started |
|
|
| 2 | Mobile page workroom inbox | ⏳ Not started |
|
|
| 2 | Chat bridge event integration | ⏳ Not started |
|
|
| 2 | TUI sidebar inbox | ⏳ Not started |
|