PRD / Proposal: Spacechat — A Spacebot-Native Team Communication & Operations Client

[sookochoff]

TLDR

I’d like to propose Spacechat: a first-party, Spacebot-native chat app (desktop + mobile) built for org/team collaboration, agent workflows, and runtime operations.

This is not intended to replace Slack/Discord connectors. It’s a primary UX/control plane for teams that run Spacebot seriously (self-hosted or hosted).

────────────────────────────────────────────────────────

Why this is worth doing

Spacebot’s Slack/Discord adapters are already strong, but those platforms still cap what we can do:

• limited control over UX and interaction model,
• weak in-app diagnostics and runtime visibility,
• constrained operational controls (retry/recover/restart workflows),
• inconsistent feature mapping across connectors,
• less structured data flowing into Spacebot memory pipelines.

A first-party client would unlock:

• thread-first collaboration by default,
• native task cards, approvals, polls, forms, rich interaction blocks,
• real-time token usage + model/provider/runtime status,
• role-gated diagnostics and remediation actions,
• richer structured human interaction signals for memory/personalization,
• performance and responsiveness optimized for Spacebot workflows.

────────────────────────────────────────────────────────

Strategic fit (hosted + self-hosted)

Spacechat aligns with current Spacebot distribution:

• Self-hosted: fully compatible with OSS deployments.
• Hosted: stronger premium surface for managed plans (ops, governance, diagnostics, supportability).

This creates clear product differentiation without abandoning open self-hosted users.

────────────────────────────────────────────────────────

Ecosystem fit (future state)

As Spacedrive ↔ Spacebot integration deepens, Spacechat can serve as the shared collaboration/control surface:

• discuss and act on Spacedrive artifacts in agent threads,
• trigger Spacebot tasks with file/data context,
• track provenance of decisions/actions across systems.

PRD

1) Executive Summary

This proposal recommends building Spacechat, a first-party, Spacebot-native team chat platform (desktop + mobile) designed for SMBs and other small-to-mid-sized orgs:

• requiring multi-human and multi-team collaboration to get work done,
• structured agent workflows (tasks, approvals, forms, cards),
• high-fidelity runtime observability (token usage, status, diagnostics),
• and deeper bidirectional data flow between humans and Spacebot.

Spacechat is not “another connector.” It is a primary product surface and control plane for organizations running Spacebot in production.

The current Slack/Discord adapters are robust and should remain supported. However, third-party chat platforms impose unavoidable limits in UX control, operations tooling, data model alignment, and performance. Spacechat unlocks capabilities that are difficult or impossible to deliver inside Slack/Discord constraints.

---

2) Problem Statement

Spacebot today can integrate with Slack/Discord effectively, but serious organizational deployments need:

1. Thread-first operational clarity across teams/agents/departments.
2. Native structured workflows (task cards, action buttons, approvals, polls, diagnostics interactions).
3. Deep runtime transparency (token burn, queue depth, model/provider status, worker lifecycle, failures).
4. Control-plane actions (retry/restart/recover flows) with role-based controls and auditability.
5. High-performance UX optimized for AI collaboration, not general-purpose chat.
6. Richer memory ingestion pipelines from human interactions and app telemetry (with policy controls).
7. Future ecosystem cohesion with Spacedrive + Spacebot.

Slack/Discord can support subsets of these needs, but not as a coherent Spacebot-native product.

---

3) Goals

Product Goals

• Deliver a communication UX purpose-built for Spacebot organizations.
• Make Spacebot behavior legible and controllable in real-time.
• Improve collaboration quality across humans and agents.
• Provide a premium, differentiated surface for both hosted and self-hosted deployments.

Technical Goals

• Define a stable first-party API + realtime event contract for Spacebot-native clients.
• Maintain low-latency streaming interactions and resilient offline/reconnect behavior.
• Ensure strong tenancy, RBAC, auditing, and operational safety.
• Keep Slack/Discord connectors as compatibility channels while enabling richer first-party features.

Non-Goals

• Replacing Slack/Discord globally for all company communication.
• Rebuilding every enterprise messaging feature at launch.
• Tight coupling that breaks self-hosted simplicity.

---

4) Why This Is Beneficial (Developer-Facing Case)

4.1 Unlocks Product Surface Area Slack/Discord Cannot

• Spacebot-native cards and interactions tied directly to internal task/runtime state.
• Per-turn observability overlays (token usage, tool calls, model/provider metadata).
• Native diagnostics and remediation actions inside the same conversation surface.
• Consistent interaction semantics across desktop/mobile instead of connector-specific behavior.

4.2 Increases Reliability and Operability

• Fewer layers than MCP-through-chat-platform patterns.
• Direct protocol control for streaming, retries, ordering, dedupe, and session recovery.
• First-class health and incident surfaces tied to Spacebot internal state.

4.3 Improves Data Quality for Memory and Personalization

• Canonical identities and team context from first-party auth.
• Structured interaction events (button clicks, poll votes, task transitions) rather than only plain text.
• Better memory candidate extraction and review workflows with explicit policies.

4.4 Fits Existing Business Model (Hosted + Self-Hosted)

Spacebot already supports free self-hosted and paid hosted modes. Spacechat aligns naturally:

• Self-hosted: organizations run full stack on-prem/VPC.
• Hosted: managed Spacechat + Spacebot cloud offering with premium ops UX and administration.

This strengthens differentiation for paid plans while preserving open self-hosted viability.

4.5 Ecosystem Fit: Spacedrive + Spacebot + Spacechat

As Spacedrive and Spacebot move toward seamless interoperability, Spacechat can become the collaboration/control surface across both:

• discuss files/assets from Spacedrive in agent threads,
• trigger Spacebot tasks over repository/media/data context,
• display provenance links to files/objects/workflows,
• keep audit trail of AI-assisted decisions tied to data artifacts.

Spacechat becomes a unifying interaction layer in the broader ecosystem.

---

5) Users and Primary Use Cases

Core Personas

• Team operators/admins running Spacebot in production
• Departmental users collaborating with specialized agents
• Engineering/support teams triaging incidents and automation flows

Key Use Cases

1. Team channels with default threaded conversations for clean context.
2. Agent-specific channels per department/domain.
3. Structured task workflows (create/assign/approve/complete) in-chat.
4. Live token/runtime visibility during long-running interactions.
5. Incident diagnostics and controlled recovery actions from chat.
6. Voice memo send/receive with transcript + audio playback.
7. Cross-team collaboration with agent participation and role-aware controls.

---

6) Product Requirements

6.1 Client Platforms

Desktop

• Tauri + Rust + TypeScript UI (recommended)
• Rationale: performance, memory footprint, native integration, deployment efficiency.

Mobile

• Flutter (recommended) for high-performance cross-platform UI and predictable rendering.
• Native audio pipeline support for voice memo capture/playback.
• Shared API/event contracts with desktop.

6.2 Information Architecture

• Organizations → Teams → Channels → Threads
• Channel categories (agents/departments/ops/incidents/projects)
• Thread-first default behavior
• Message types: text, markdown/code, media, rich cards, interactions, polls, task artifacts

6.3 Core Messaging

• Low-latency realtime message transport
• Streaming response deltas
• Message state transitions (created/streaming/completed/failed)
• Idempotent send/retry semantics
• Attachment and code block support

6.4 Rich Interaction System

• Task cards with action buttons
• Poll components
• Forms/select menus
• Inline status chips and tool-run summaries
• Structured interaction callback events to Spacebot

6.5 Observability Surface (In-App)

Per thread/channel/agent, expose:

• token counts and rolling usage,
• model/provider currently serving,
• response latency and queue state,
• worker/task statuses,
• last errors and remediation hints,
• connector/provider health.

6.6 Operational Controls (RBAC-Gated)

• Retry last agent turn
• Restart channel worker/session
• Reconnect provider/connector
• Controlled instance recovery hooks (where configured)
• Incident acknowledgment/escalation workflows

All privileged actions must be auditable and policy-gated.

6.7 Voice Workflows

• Record and send voice memo to agent/thread
• STT transcription and transcript attachment
• Agent voice response via TTS audio payload
• Transcript + audio kept linked in thread history

6.8 Memory Ingestion Controls

• Policy-driven ingestion (what can become memory, at what granularity)
• Consent and visibility controls
• Memory candidate queue + moderation/review options
• Metadata capture (role/team/channel/context/device signals where permitted)

---

7) Functional Requirements (System)

1. Spacechat client can authenticate and connect to Spacebot-native realtime gateway.
2. Client can send/receive text/media/interaction/task events in near-real-time.
3. Client can render streaming token deltas and status updates without blocking UI.
4. Client can query diagnostics endpoints and render health/status panels.
5. Client can invoke RBAC-protected operational actions with audit trail.
6. Client can publish structured interaction payloads back to Spacebot.
7. Client can ingest voice memo, receive transcript and response audio.
8. System supports org/team/membership isolation and scoped permissions.
9. Slack/Discord connectors remain functional as external channels with feature subset mapping.

---

8) Non-Functional Requirements

• Performance: sub-100ms local interaction response for UI actions; smooth list virtualization at high message volumes.
• Reliability: resumable sessions, at-least-once event delivery with idempotency keys.
• Scalability: support many channels/threads with event fan-out.
• Security: strong auth, RBAC, audit logging, transport encryption, secret isolation.
• Privacy: configurable retention and memory-ingestion policy controls.
• Observability: structured logs, traces, metrics for client/server/event bus.

---

9) Proposed Technical Architecture

9.1 High-Level Components

1. Spacechat Client (Desktop/Mobile)

   • UI, local cache, optimistic state, retry queue.

2. Spacebot Realtime Gateway (new first-party surface)

   • WebSocket/SSE stream for events.
   • Authenticated bidirectional session.

3. Spacebot API Layer

   • REST/gRPC endpoints for commands, tasks, diagnostics, admin controls.

4. Event Bus / Stream Processor

   • Internal event routing for message/task/status/tool/health updates.

5. Persistence Layer

   • Message/thread/task state, audit logs, interaction history, policy configs.

6. Connector Compatibility Layer

   • Slack/Discord continue as adapters to canonical event model (subset).

9.2 Canonical Event Contract (Illustrative)

• message.created
• message.stream.delta
• message.completed
• message.failed
• thread.created
• interaction.submitted
• task.created|updated|assigned|completed
• agent.status.changed
• agent.token.usage
• tool.started|completed|failed
• system.health.changed
• system.recovery.invoked
• memory.candidate.created
• memory.saved|rejected

Each event includes:

• event_id, event_type, org_id, team_id, channel_id, thread_id, actor, timestamp, idempotency_key, payload.

9.3 API Surface (Illustrative)

Messaging

• POST /v1/channels/{id}/messages
• POST /v1/threads/{id}/messages
• GET /v1/threads/{id}/history

Tasks

• POST /v1/tasks
• PATCH /v1/tasks/{id}
• POST /v1/tasks/{id}/actions/{approve|reject|assign|complete}

Diagnostics

• GET /v1/system/health
• GET /v1/agents/{id}/status
• GET /v1/threads/{id}/metrics

Operations (privileged)

• POST /v1/ops/channels/{id}/retry
• POST /v1/ops/agents/{id}/restart
• POST /v1/ops/instance/recover

Voice

• POST /v1/voice/memos
• GET /v1/voice/memos/{id}
• GET /v1/voice/memos/{id}/transcript

Realtime

• GET /v1/realtime/ws

---

10) Data Model (Core)

• Organization
• Team
• User
• Membership (role, scopes)
• Channel
• Thread
• Message
• Interaction
• Task
• TaskAction
• AgentRuntimeSnapshot
• HealthEvent
• AuditEvent
• MemoryCandidate
• VoiceMemo

Design principles:

• append-only event log for auditability,
• materialized views for fast UI reads,
• strict tenancy boundaries.

---

11) Security / Auth / Permissions

• Token-based auth with device/session management.
• Org/team scoped RBAC (member, operator, admin, etc.).
• Fine-grained scopes for diagnostics and ops actions.
• Mandatory audit events for all privileged actions.
• Optional SSO integration path for hosted enterprise plans.
• Policy controls for telemetry and memory ingestion.

---

12) Hosted + Self-Hosted Packaging Strategy

Self-Hosted

• Spacechat clients point at self-managed Spacebot API/realtime endpoints.
• Operators control storage, retention, and policy configuration.
• Works with existing open-source distribution model.

Hosted

• Managed Spacechat endpoints integrated with Spacebot-hosted plans.
• Centralized operations console and managed reliability features.
• Premium differentiation through richer diagnostics, governance, and support tooling.

This dual model aligns directly with Spacebot’s existing free self-hosted + paid hosted strategy.

---

13) Compatibility and Migration

• Keep Slack/Discord adapters as supported ingress/egress channels.
• Introduce canonical internal event model and map connector payloads into it.
• Spacechat uses full feature set; connectors consume subset.
• Avoid breaking existing deployments by keeping connector contracts stable.

---

14) Phase Plan

Phase A — Platform Foundations

• Define canonical event and API contracts.
• Implement realtime gateway and auth/rbac scaffolding.
• Establish telemetry + audit baselines.

Phase B — Core Spacechat MVP

• Team/channel/thread UX.
• Streaming messaging + retries + local cache.
• Basic rich cards/interactions.

Phase C — Spacebot-Native Operations

• Token/runtime/health panels.
• Diagnostics workflows and role-gated remediation actions.

Phase D — Tasks + Voice + Memory Policy

• Native tasks lifecycle UI and event flows.
• Voice memo send/receive with transcript.
• Memory candidate policy/review surfaces.

Phase E — Ecosystem Integration

• Spacedrive-linked artifacts in threads/tasks.
• Cross-surface provenance and workflow handoff patterns.

---

15) Risks and Mitigations

1. Scope creep toward full Slack replacement
   Mitigation: keep focus on Spacebot-native collaboration and operations.

2. Client complexity/performance regressions
   Mitigation: strict performance budgets, virtualization, compact event payloads, profiling gates.

3. Security exposure from operational controls
   Mitigation: RBAC scopes, approvals, audit logs, optional policy gates for destructive actions.

4. Fragmented behavior across connectors and first-party client
   Mitigation: canonical event contract + explicit feature subset mapping.

5. Privacy concerns around deeper ingestion
   Mitigation: configurable policies, consent visibility, retention controls.

---

16) Success Criteria (Proposal Acceptance Level)

• Clear technical consensus that Spacechat creates capabilities unavailable in third-party connectors alone.
• Agreement on canonical API/event contract direction.
• Alignment that hosted + self-hosted packaging is strategically consistent with Spacebot.
• Confirmation that Spacechat is the preferred path for deep task/ops/observability UX.
• Agreement that Spacedrive interoperability is a first-class design consideration.

---

17) Decision Request

Requesting maintainer feedback and decision on:

1. Whether to prioritize a Spacechat-first API/event surface in Spacebot core.
2. Whether to adopt the proposed architecture direction (first-party realtime gateway + canonical event model).
3. Whether to treat Spacechat as a dual-distribution product (self-hosted compatible + hosted premium).
4. Whether to align upcoming Tasks and observability work with Spacechat-native interaction patterns from day one.

[luigigalli]

Kudos! That's my primary requirement as well: I'm still not finding it in any agentic platform!

[sookochoff]

Feels like a native integration would give any agent a lot more power than just relying on existing tech! Openclaw hasn't done it yet, which is in a way surprising. But I'm sure someone's working on it.