Files
agent-radar 2ed3415fb7
Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s
源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
2026-09-01 20:17:27 +08:00

58 lines
2.3 KiB
Markdown

# Workspace Terminal
Reusable terminal node contracts and shared frontend surface for Tutti
workspace hosts.
The package owns host-agnostic terminal semantics. Hosts own concrete process
launching, daemon clients, VM routing, Electron bridges, product copy, and
durable terminal storage.
See `docs/architecture/workspace-terminal.md` for the current architecture and
package boundary.
## Internal Layering
The shared terminal surface is intentionally split into narrow layers:
- `src/core/sessionController.ts`
Owns terminal session orchestration. It composes recovery, state storage,
input queueing, and transport lifetime, but should stay thin.
- `src/core/sessionControllerStore.ts`
Owns in-memory terminal session state such as `rawOutput`, `inputReady`, and
`surfaceError`.
- `src/core/sessionControllerRecovery.ts`
Owns `snapshot -> attach -> replay` recovery semantics and transport event
hydration.
- `src/core/sessionDiagnostics.ts`
Owns diagnostic event shaping so core and react layers do not scatter event
names and payload shapes.
- `src/react/terminalSurfaceRuntime.ts`
Owns xterm wiring, buffered terminal writes, screen-cache restore/persist,
resize observation, and host-agnostic terminal view behavior.
- `src/react/TerminalSurface.tsx`
Owns composition only. It should bind hooks, runtime handles, and UI
controls, but should not become the owner of terminal transport recovery.
## Guardrails
- React view remounts must not directly own `snapshot`, `attach`, or `detach`.
- Recovery behavior should be testable in `src/core/*` without mounting React.
- Terminal view sync behavior should be testable in small `src/react/*` helper
tests without constructing full host adapters.
- New diagnostics should be added through `sessionDiagnostics.ts` instead of
scattering raw event strings across the package.
- Host-specific bridges, preload APIs, daemon clients, and absolute-path
policies stay outside this package.
## Maintenance Rule Of Thumb
When adding new behavior, prefer:
1. pure helper in `src/core` or `src/react`
2. narrow composition in `sessionController` or `terminalSurfaceRuntime`
3. minimal wiring in `TerminalSurface` or `TerminalNode`
If a change wants to put transport lifetime, recovery sequencing, or daemon
policy back into a React component, that is usually a sign the boundary is
slipping.