EchoKernel Product Brief V2

Document Goal

This brief is a direct handoff baseline for the next implementation cycle. It locks current behavior and gives one source of truth for architecture, API contracts, config keys, and immediate P0 work.

• Freeze the current implementation snapshot
• Clarify web architecture and interface contracts
• Enable immediate execution of the V2 priority backlog

Product Surfaces (Web Perspective)

EchoKernel web is not a secondary dashboard. It provides two production surfaces: a local control center on the PC and a mobile remote audio gateway.

Operating Principle

The two web layers are intentionally separated. Runtime handles core audio and model processing, while web handles control, visibility, and remote I/O handoff.

• Local Web owns local control and settings operations
• Remote Gateway owns remote audio and session relay
• Runtime remains the single processing authority

Runtime Bootstrap and DI

Program bootstrap includes elevation checks, workspace provisioning, HybridAudioSource registration, STT routing, Agent and TTS tooling, and RemoteGatewayTtsPublisher wiring.

Default Configuration Baseline

The following defaults define expected behavior. Any changes require compatibility review and migration notes.

{
  "EchoKernel:Ui:WebControlEnabled": true,
  "EchoKernel:Ui:WebControlPort": 61523,
  "EchoKernel:RemoteGateway:Enabled": false,
  "EchoKernel:RemoteGateway:Port": 43601,
  "EchoKernel:RemoteGateway:AllowLocalNetworkOnly": true,
  "EchoKernel:RemoteGateway:MicrophoneMode": "local_and_remote",
  "EchoKernel:RemoteGateway:OutputMode": "local_and_remote"
}

Managed Model Endpoint Strategy

Additional model presets must carry provider metadata and a built-in default endpoint. Endpoint values are resolved automatically per selected model/company, with manual override support when operators need a custom gateway.

• Each preset stores company, runtime provider key, model ID, and default endpoint
• Model selection auto-fills endpoint when endpoint input is empty
• Manual endpoint input always takes precedence over catalog defaults

Preloaded Company + Endpoint Catalog

The table below is the baseline catalog that should ship preloaded to avoid per-model endpoint guesswork in UI and settings flows.

Workspace and Security Provisioning

Runtime boot provisions C:\Users\{User}\EchoKernel\workspace with security lists, base config, and persona documents.

• allowlist.txt / blacklist.txt / hard_blacklist.txt
• workspace/config.json
• SOUL.md, IDENTITY.md, USER.md, MEMORY.md

Hosting Split

The local control center runs in the GUI process via Kestrel, while the remote gateway runs as a Python FastAPI sidecar.

Layer Separation

Local Web is loopback-only control and configuration. Remote Gateway is an externalized relay for mobile mic input, TTS output, runtime state, and chat forwarding.

Remote Voice Input Flow

Mobile client sends PCM16 frames to /ws/mic. Gateway broadcasts to runtime subscribers at /ws/runtime-mic. Runtime ingests via FastApiRemoteAudioSource, applies mode policy in HybridAudioSource, then pipelines STT to Agent to TTS.

Remote TTS Output Flow

Runtime publishes WAV payloads to POST /api/runtime/tts. Gateway pushes binary frames to /ws/tts, and mobile playback consumes a local queue.

Runtime State Broadcast

Runtime posts thinking and phase events to POST /api/runtime/state. Gateway broadcasts state updates over /ws/state for immediate UI reaction.

Local Web Control Center API

Status, runtime control, settings, catalog discovery, logs, and chat endpoints.

Remote Gateway API

Gateway handles health and page checks, runtime uplink, mode controls, chat proxying, and websocket channels.

Auth and Network Policy

When PIN is enabled, clients must provide ?pin= or X-EchoKernel-Pin. When local-network-only is enabled, only loopback and private ranges are accepted.

Critical Configuration Domains

These keys are mandatory context for any web delivery, testing, or rollout workflow.

EchoKernel:Ui:WebControlEnabled
EchoKernel:Ui:WebControlPort
EchoKernel:RemoteGateway:Enabled
EchoKernel:RemoteGateway:AllowLocalNetworkOnly
EchoKernel:RemoteGateway:Host
EchoKernel:RemoteGateway:Port
EchoKernel:RemoteGateway:Pin
EchoKernel:RemoteGateway:MicrophoneMode
EchoKernel:RemoteGateway:OutputMode
EchoKernel:Agent:JsonActionExecPermissionMode
EchoKernel:Agent:JsonActionExecAllowlistPath
EchoKernel:Agent:JsonActionExecBlacklistPath
EchoKernel:Agent:JsonActionExecHardBlacklistPath

Model Endpoint Resolution Policy

Settings and runtime should resolve endpoints in a deterministic order so all model providers behave consistently.

{
  "step_1": "If user configured endpoint exists, use it",
  "step_2": "Else load default endpoint from model/company catalog",
  "step_3": "Else fallback to provider-level hard default",
  "step_4": "Persist resolved endpoint back to settings for transparency"
}

Provider Onboarding Rule

When adding a new model company, teams should update one centralized catalog entry instead of scattering endpoint constants across UI and runtime.

• Add company alias, runtime provider mapping, and default endpoint in one catalog source
• Register at least one preset model ID for discovery and testing
• Keep API-key ownership explicit per company to prevent cross-provider leakage

Command Execution Permission Modes

Execution is controlled by three permission modes. Hard blacklist is non-bypassable in every mode.

Security Guardrails

These controls should remain intact during UI and gateway iterations.

• workspace_jail_only execution context
• Prefix, boundary, segment, and token blacklist matching
• PIN and rate-limit hardening for any external exposure
• Prevent deployment paths that weaken local-only assumptions

Local Web V2 Priorities

Raise visual parity with the desktop GUI, stabilize settings interaction, and improve live chat rendering behavior.

• Close spacing, typography, and card hierarchy parity gaps
• Fix category scrolling and custom select conflicts
• Render session switches and command blocks consistently

Remote Gateway V2 Priorities

Prioritize mobile layout stability, real-time updates, audio reliability, and iOS autoplay-safe interaction flow.

• Apply complete safe-area support and remove clipping
• Improve chat update latency without tab re-entry
• Reduce mic frame drops and strengthen reconnect recovery
• Align remote playback completion with overlay timing

Remote Session State Machine

Session lifecycle and transitions should remain explicit to reduce edge-case drift across clients.

V2 Performance Targets

Business-facing quality targets for release readiness.

Priority Backlog

Sequence work by operational impact first, then experience polish, then platform expansion.

Regression Checklist

All items should pass before packaging or release candidate handoff.

• No lingering gateway process after app shutdown
• No runtime-stop hangs or loops
• Settings defaults and selects load correctly
• PIN and local-network policy regression passes
• Hard blacklist remains non-bypassable

Build and Packaging Commands

Baseline commands for local run and Windows packaging.

dotnet run --project src/EchoKernel.Gui

dotnet run --project src/EchoKernel.Runtime

powershell -ExecutionPolicy Bypass -File .\scripts\package-windows.ps1

Definition of Done (V2 Phase 1)

Phase 1 is complete only when every item below is verifiably true.

• Local Web and GUI parity is documented and validated
• Remote mic uplink, TTS, state, and chat are stable
• PIN and local-network policy tests pass
• Settings roundtrip persists and survives restart
• Packaged dist behavior matches local behavior
• Failure logs are actionable for root-cause isolation