PRD: Runtime v1 (Channel/Branch/Worker) for Spacebot-Core

1. Document Status

• Version: 1.0
• Date: 2026-03-03
• Status: Draft for implementation and alignment
• Owners: Core, AgentRuntime, Dashboard

2. Product Context

Runtime v1 is a control-plane protocol and orchestration layer for multi-agent execution with token-efficient context handling.

MVP scope stays a vertical slice:

• Backend: Core
• Frontend: Dashboard

Runtime model for v1 includes five entities:

• Channel
• Branch
• Worker
• Compactor
• Visor

3. Goals

1. Provide deterministic, rule-based routing for channel messages.
2. Support branch-based context fork for focused work and concise return to channel.
3. Support worker execution in two modes: fire_and_forget and interactive.
4. Keep context/token costs stable via typed short payloads and artifact/memory references.
5. Provide event-level observability and replay-friendly persistence for runtime operations.
6. Provide operator visibility in Dashboard: chat, tasks, workers, artifacts, activity feed.

4. Non-goals (MVP)

1. Full autonomous LLM router (policy remains rule-based).
2. Full branch transcript persistence.
3. Distributed multi-node scheduling.
4. External vector DB integration.
5. Production-grade RBAC and hardened sandbox profiles.

5. Success Metrics

1. Functional:

• 100% support for defined v1 message envelope and message types.
• Interactive routing to worker is accepted and reflected in worker status transitions.

2. Reliability:

• No channel crash on compaction threshold handling (80/85/95).
• Runtime restart retains persisted events, artifacts, bulletins, and task/project state.

3. Token economy:

• Average payload size for runtime events remains under target limit (target set by team per environment).

6. Functional Requirements

FR-1: Protocol Envelope v1

All runtime events must use one JSON envelope:

• protocolVersion
• messageId
• messageType
• ts
• traceId
• channelId
• taskId?
• branchId?
• workerId?
• payload
• extensions

Compatibility rule:

• Backward-compatible additive changes only.
• Unknown fields are ignored by consumers.

FR-2: Message Types v1

Required message types:

• channel.message.received
• channel.route.decided
• branch.spawned
• branch.conclusion
• worker.spawned
• worker.progress
• worker.completed
• worker.failed
• compactor.threshold.hit
• compactor.summary.applied
• visor.bulletin.generated

FR-3: Channel Runtime

1. Accept user message as entry point.
2. Build routing context with system/policy context.
3. Decide route by rule-based policy:

• respond
• spawn_branch
• spawn_worker

4. Route message into interactive worker when requested.

FR-4: Branch Runtime

1. Fork channel context with unique branchId.
2. Provide memory tools:

• memory_recall
• memory_save

3. Allow worker spawn from branch context.
4. Return only:

• conclusion
• artifactRefs
• memoryRefs
• tokenUsage

5. Do not persist full branch transcript in v1.

FR-5: Worker Runtime

1. Accept WorkerTaskSpec with declared toolset.
2. Support two modes:

• fire_and_forget
• interactive

3. In interactive mode accept route messages from Channel.
4. Return short structured report and artifact references.
5. Emit lifecycle events (spawned/progress/completed/failed).

FR-6: Compactor

1. Evaluate channel context utilization thresholds:

• >80%: soft
• >85%: aggressive
• >95%: emergency

2. Compactor is orchestration-only (non-LLM).
3. Summaries are generated by background workers.
4. Publish threshold and summary-applied events.

FR-7: Visor

1. Consume runtime event stream (broadcast).
2. Build periodic memory bulletin.
3. Persist bulletin in memory store.
4. Deliver digest into active channels.

FR-8: Public API

Required endpoints:

• POST /v1/channels/{id}/messages
• POST /v1/channels/{id}/route/{workerId}
• GET /v1/channels/{id}/state
• GET /v1/bulletins
• POST /v1/workers
• GET /v1/artifacts/{id}/content

FR-9: Persistence

SQLite schema for MVP must include:

• channels
• tasks
• events
• artifacts
• memory_bulletins
• token_usage

FR-10: Dashboard (MVP)

1. Chat interaction with channel.
2. Runtime task visibility.
3. Artifact content viewer.
4. Worker/branch activity feed.

7. Acceptance Scenarios

1. Channel receives task, spawns Branch, Branch spawns Worker, Channel receives conclusion-only output.
2. Interactive worker receives routed message and updates behavior/status.
3. Compactor schedules expected summarize level at 80/85/95 thresholds without channel failure.
4. Visor bulletin is generated by schedule, stored in memory, and delivered as channel digest.
5. Token regression test validates event payload budget.
6. Recovery test validates restore after Core restart for channels/tasks/events/artifacts.

8. Technical Constraints

1. Protocol format in v1 is JSON (not Protobuf).
2. Dashboard remains in /Dashboard.
3. Desktop app (/Sources/App) is out of MVP critical path.
4. Branch full transcript persistence is out of v1.
5. Additive schema evolution only.

9. Delivery Plan

MVP

1. Finalize protocol-v1.md with schema examples.
2. Event bus + broadcast wiring in Core.
3. Channel state machine + route policy.
4. Branch lifecycle + memory adapter.
5. Worker lifecycle + interactive route bridge.
6. Compactor threshold orchestration.
7. Visor bulletin pipeline.
8. Dashboard runtime views.
9. SQLite schema and persistence integration.
10. Docker Compose for core + dashboard.

Post-MVP

1. Proxy layer (global + plugin mode).
2. ACP/Telegram/additional providers.
3. GUI parity in /Sources/App.
4. External vector backend and multi-node scheduling.
5. Security hardening (sandbox profiles, RBAC, quotas, audit export).