Interaction Surfaces

Nous is a single system accessed through multiple surfaces.

Each surface is optimized for a different context of use. All surfaces share the same underlying runtime — Cortex, memory, projects, routing, governance. The surface changes. The intelligence does not.

Surface 1 — Secure Messaging and Voice

The mobile-first channel.

Purpose

Interaction with Nous when away from a workstation. Quick decisions, approvals, overrides, and escalation responses.

Characteristics

Nous reaches the user here for escalations and notifications
User can give quick natural language instructions
Supports text through the Phase 11.1 communication-gateway baseline
Phase 11.3 adds the canonical voice-control runtime for safe turn handling, interruption, degraded-mode visibility, and confirmation posture
Phase 14.6 moves connector registration and session lifecycle ownership fully into the canonical communication-gateway runtime; the bridge app remains adapter-local transport scaffolding only
Always scoped to a project context (Nous states which project it is referencing)
Minimal UI — the conversation is the interface
High-risk voice actions can require text or dual-channel confirmation instead of voice-only execution
Barge-in stops assistant output immediately and requires explicit continuation

Channel

Current production connector: Telegram through the Phase 11.1 communication gateway and bridge runtime.

Future preferred secure-messaging posture remains Signal or an equivalent end-to-end encrypted messenger once that later phase work is ratified and implemented.

Requirements:

Authorized identity binding before privileged actions
Manual pairing and endpoint trust approval before any privileged device capability becomes active
Message integrity and authenticated connector context
Channel routing through the canonical communication-gateway runtime
Voice turn evaluation through the canonical voice-control runtime when a surface supplies normalized voice signals
Signed endpoint transport validated by the canonical endpoint-trust runtime
No connector-owned routing, acknowledgement, suppression, trust, or project state
No dependency on a specific vendor over the long term (channel remains replaceable)

Runtime Boundary

This surface is not a second control plane. The bridge app normalizes connector-native messages into canonical communication-gateway envelopes and normalized voice-turn signals, then hands them to ICommunicationGatewayService and IVoiceControlService inside the same app-hosted runtime graph. Device identity, manual pairing, immutable endpoint direction, capability grants, signed transport validation, and incident containment flow through IEndpointTrustService; turn completion, degraded mode, interruption state, and text-first recovery flow through the voice-control runtime. The bridge adapter stays thin and does not own trust, route, or voice-policy state. Phase 14.6 extends that boundary by making connector registration and last-seen session projection part of the canonical communication-gateway service rather than bridge-local runtime state.

Interaction Examples

Nous sends: "Persona Engine — identity validation failed at 78%. Recommend adjusting LoRA training rate and re-running. Approve retry or review in Projects UI?"
User responds: "Approve retry"
Nous sends: "Inbox Manager — flagged an email from [sender] marked urgent. Subject: [subject]. Forward, reply, or ignore?"
User responds via voice call for complex decisions
Nous responds to a risky voice request with: "I understood a project-control action, but this requires text confirmation in your active session."

Surface 2 — Chat Interface

The conversational workspace.

Purpose

Thinking through problems, giving multi-step instructions, reviewing project state, and interacting with Nous conversationally. This is the desk-level interaction surface.

Characteristics

ChatGPT-style conversational UI
Project groups in the sidebar
Active Nous projects auto-populate as chat groups — no manual creation required
Conversations within a project group are automatically scoped to that project's memory and context
Supports rich content display (images, tables, code, workflow previews)
Full conversation history with search

Project Group Behavior

Each Nous project appears as a group in the chat sidebar
Opening a project group loads that project's context into the conversation
Nous responses within a project group draw from that project's STM, LTM, and artifact history
General conversations (not scoped to a project) are also supported — these are scratch threads and remain non-executable until explicitly bound to a project
Users can create ad-hoc chat groups for exploratory conversations that may later become projects
Project scope is mandatory for executable or control actions; Nous asks for clarification when scope is ambiguous

Interaction Examples

User opens the Persona Engine group: "What was the reject rate on the last video batch?"
Nous responds with data from the project's memory and artifact history
User: "I want to try a different pose preset for the next identity grid. Show me what we have."
Nous retrieves the Persona Pack's pose presets and presents options

Surface 3 — Projects UI

The visual workflow editor and project management surface.

Purpose

Designing, building, monitoring, and tuning project workflows. This is the engineering surface for structured project work.

Characteristics

Node-based visual workflow editor (ComfyUI / n8n paradigm)
Supports project creation, configuration, and lifecycle management
Workflow design for protocol projects
Live monitoring for intent and hybrid projects
Phase 11.4 adds a staged visual-debug canvas, checkpoint and scheduler summaries, parity diagnostics, and richer node inspection over canonical runtime truth
Workflow lifecycle state is projected from canonical runtime truth, while lifecycle mutations remain governed Internal MCP actions rather than browser-owned controls
Node-level governance configuration (MUST / SHOULD / MAY)
Model assignment per node
Artifact browsing and versioning
Execution trace inspection
Project-level dashboards and metrics

Complexity Range

The Projects UI supports the full spectrum:

Low complexity — a handful of nodes, simple linear flow
Medium complexity — branching paths, quality gates, conditional logic
High complexity — multi-phase workflows with nested sub-workflows, batch operations, and scheduled triggers
Ultra-high complexity — full operational protocols with dozens of nodes, multiple model types, artifact pipelines, and continuous monitoring loops

All complexity levels use the same editor. The interface scales with the project, not the other way around.

Visual-Debug Boundary

The advanced Projects surface is still a projection and control surface, not a second workflow runtime.

Stage grouping is derived from canonical topology, not saved as workflow semantics
Node and edge states project canonical run, checkpoint, branch, artifact, scheduler, and MAO truth
Degraded parity is surfaced explicitly when the selected workflow graph and MAO graph cannot align
Deep links into Chat, Traces, and MAO preserve project, run, node, and evidence continuity
Save and validation still flow through the canonical workflow-definition seam
Workflow start, pause, resume, and cancel remain authority-bound runtime operations routed through the canonical Internal MCP seam instead of a Projects-local control plane

Project Type Support

Protocol projects — full workflow graph design and monitoring
Intent projects — objective and constraint configuration, live activity monitoring, protocol emergence proposals
Hybrid projects — both views coexist within a single project

Installable App Panels

Installable app panels remain trusted-host extensions inside the web shell rather than a separate interaction surface.

Panels mount as sandboxed iframe projections inside the existing trusted host surfaces
preserveState keeps an inactive panel hidden for the current session when the manifest requests it, instead of treating hidden browser state as durable storage
Cross-session panel continuity flows through the trusted host bridge and runtime-owned persisted state rather than host-local or browser-local storage
Panel-facing activation and deactivation helpers remain wrappers over the canonical panel_mount / panel_unmount lifecycle seam, not a separate panel-local lifecycle model

Surface 4 — MAO Operator Surface

The dense observability and project-control surface.

Purpose

Monitoring multi-agent workflow posture at a glance, inspecting blocked or failed agents, tracing corrective arcs, and applying governed project-scope controls from canonical runtime truth.

Characteristics

Density-aware D0-D4 agent projections
Inspect-first behavior at higher densities
Canonical run-graph lineage and corrective-arc visibility
Urgent and blocked overlays derived from runtime/control truth
Evidence-derived reasoning-log previews with redaction posture
Governed project-scope Pause Project, Resume Project, and Hard Stop Project controls
Additive voice_projection visibility for current turn state, degraded mode, pending confirmation, and continuation-required posture

Cross-Surface Role

MAO is not a separate control plane. It is a projection and control surface over:

Workflow runtime truth
Operator-control truth
Escalation truth
Evidence and reasoning-preview truth

It can deep-link into Projects, Chat, and Traces while preserving project, run, node, and evidence continuity.

Surface 5 — Marketplace Governance Surface

The governed package-discovery and moderation surface.

Purpose

Browsing registry packages, inspecting provenance and moderation posture, reviewing advisory discovery suggestions, initiating governed app installs from project-scoped package detail views, and following trust-preserving handoffs into Projects and MAO.

Characteristics

Canonical projection over registry governance truth and discovery runtime truth
Trust tier, distribution status, compatibility posture, provenance, and release history surfaced directly from registry state
Project-scoped package detail views can launch the canonical app install wizard for installable app packages
Project-scoped package detail views can reopen installed app packages into the canonical shared settings surface
The install wizard uses the same host-owned three-stage sequence on touched hosts: permission review, configuration, then validation/activation
The settings surface shows runtime/config-version posture, vault-backed secret state, and explicit save outcomes on the same host-owned contract family
Moderation dashboard for holds, delistings, appeals, and escalation continuity
Advisory-only discovery feed with mandatory suppression controls
Deep links into Projects and MAO preserve project, package, release, candidate, and evidence continuity
No surface-owned governance, moderation, suppression, or config-authority state

Install and Settings Boundary

Marketplace can initiate app installation, but it does not become a second lifecycle engine or a second configuration authority.

The web host prepares install metadata from canonical registry and project context before the wizard renders
The shared wizard requires explicit permission approval, renders manifest-defined configuration groups, and reports success, partial, or failed validation / activation outcomes
Installed apps reopen through the same package detail surface as the shared settings surface, using canonical prepareAppSettings / saveAppSettings transport rather than a package-local UI
Desktop host tooling reuses the same preparation and execution contract plus the same visible stage model
Secrets and OAuth artifacts go directly to the credential vault, while non-secret config persists through the project-scoped install service
Successful settings saves refetch canonical settings truth and push additive config.changed panel updates without iframe remounts or panel-local config stores
Rollback remains service-owned when validation or activation fails

Companion CLI Seam

nous pkg discover is the terminal projection of this same surface family.

It consumes the same marketplace router outputs as the web surface
It remains advisory-only
It displays trust eligibility and available suppression actions
It writes feedback and suppression choices back through canonical runtime services

Cross-Surface Role

Marketplace is not a separate policy engine. It is a governed projection over:

Registry trust and compatibility truth
Governance action and appeal truth
Advisory discovery feed truth
App-install preparation and execution truth
Escalation continuity truth

Surface 6 — Mobile Operations Surface

The quick-review mobile web surface.

Purpose

Reviewing project posture, recording escalation awareness, and checking cross-surface follow-up context from a phone-sized interface without opening the full desktop workspace.

Characteristics

Web-hosted mobile route inside self/apps/web/, not a separate native runtime
Aggregated project snapshot composed from canonical project, escalation, voice, and endpoint-trust projections
Read-optimized layout for status review, escalation acknowledgement, and follow-up prompts
Shared acknowledgement continuity with Chat and Projects
Shared voice continuation and degraded-mode posture with MAO and other web surfaces
Shared device-trust summary posture without exposing pairing or grant authority
No surface-owned project control, trust, or recovery state

Runtime Boundary

The mobile operations surface is not a second dashboard or a second control plane. It consumes a server-side aggregation seam so mobile clients do not stitch together their own authority model. If upstream runtime inputs disagree or are incomplete, the surface shows degraded or partial posture instead of inventing reconciled truth.

Surface 7 — Public MCP Edge

The machine-to-machine integration surface.

Purpose

Allowing approved external clients to discover and call the ratified public MCP surface without exposing internal-only tools, namespaces, or authority classes.

Characteristics

Streamable HTTP at /mcp with JSON-RPC framing
Discovery metadata at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server/mcp
OAuth bearer, audience, origin, and scope checks before tool mapping, bootstrap, or handler execution
Boundary-local ExternalClient subject posture; internal Worker, Orchestrator, Cortex:System, and Cortex:Principal classes remain unchanged
Public ortho.* tool names mapped once onto the canonical flat internal catalog
External-only namespace bootstrap and witness-linked audit evidence for durable admits and security-sensitive rejects
Same public contract across development, local_tunnel, and hosted backends
Public-safe system info can expose deployment mode, phase, and server name without revealing internal-only topology
Backend selection is internal to the edge and does not create a second public API surface
Internal workflow lifecycle tools (workflow_*) remain out of scope for the public edge, so external clients do not inherit internal workflow visibility or mutation authority

Runtime Boundary

The public MCP edge is not a second API stack. The web host parses HTTP and discovery traffic, then composes IPublicMcpGatewayService with the core public execution bridge.

Admitted traffic still flows through the existing AgentGateway, Internal MCP, and backpressure seams, and rejected traffic records the same witness and audit posture as other authority-sensitive ingress paths.
The public edge remains the only admission authority for auth, quotas, rate limits, and audit posture even when execution is routed to a tunnel or hosted backend.
Tunnel mode does not expose a raw local MCP server publicly; it forwards only already-admitted public calls into the local runtime.
Hosted mode resolves requests into tenant-local runtime state rather than a shared thin proxy over shared mutable storage.

Scheduler, hook, webhook, and system_event trigger types
Single governed ingress path: validate → authenticate → authorize → idempotency → dispatch
Phase 12.3 routes scheduler and other internal ingress through the app-hosted gateway runtime, where the System-owned ingress adapter performs duplicate checks and forwards accepted work through the canonical runtime seam
Duplicate triggers return existing run; no second run created
Replay protection: stale timestamps and duplicate nonces rejected
Control state gating: projects in hard_stopped or paused_review block new dispatch

Requirements

Webhooks: HMAC signature with key_id, timestamp, nonce
All triggers: project_id, workflow_ref, idempotency_key, nonce, payload_ref (sha256:hex)
Credentials: Workflow-bound; no project-wide wildcards

Surface Continuity

The surfaces are not isolated applications. They are windows into the same system.

Shared State

All surfaces read from and write to the same project state:

Same Cortex instance per project
Same memory (STM and LTM)
Same artifact store
Same execution traces
Same governance configuration
Same long-lived Principal/System gateway runtime, booted once by the app host and shared across chat, automation ingress, public MCP ingress, and other server-hosted surfaces, with direct turn execution now satisfied by the gateway-backed compatibility executor rather than the retired CoreExecutor class
Same canonical voice session and confirmation state projected into web, messaging, Projects, and MAO surfaces
Same canonical escalation acknowledgement and mobile operations snapshot posture projected into Chat, Projects, and the mobile surface

Cross-Surface Flows

A typical cross-surface flow:

Nous escalates via Secure Messaging: "Persona Engine — identity grid failed validation"
User taps through to the Chat Interface for that project to ask follow-up questions
User opens the MAO operator surface to identify the blocked agent and inspect its reasoning preview
User opens the Projects UI visual-debug surface to inspect the staged workflow canvas, checkpoint posture, and linked artifacts for the same run
User checks the Mobile Operations Surface to acknowledge the escalation and confirm whether voice or trust follow-up is still pending
User opens the Marketplace Governance Surface to inspect package trust posture, moderation status, or advisory suggestions
User follows into Chat, Traces, Projects, or MAO with preserved continuity context
Nous resumes execution only through the governed control path

The user moves between surfaces fluidly. Nous maintains continuity.

Notifications Across Surfaces

Escalations originate from the Cortex based on governance rules
Delivery channel is configurable per project and per priority level
Communication-gateway acknowledgements resolve the same canonical escalation record used by in-app surfaces
Voice degraded-mode and pending-confirmation posture resolve against the same canonical session projection used by MAO and other in-app surfaces
Mobile operations snapshots are aggregated from canonical server projections rather than client-owned reconciliation
The same escalation can appear across multiple surfaces (e.g., a push notification and a chat message)
Acknowledgment on any surface resolves the escalation on all surfaces

Security Model

All surfaces must meet baseline security requirements:

Authentication — device and user identity verified before interaction
Authorization — project-scoped permissions enforced regardless of surface
Encryption — end-to-end for messaging, TLS minimum for web surfaces
Audit — all interactions logged with surface, timestamp, and project context
Session management — configurable timeout and re-authentication policies

No surface bypasses the Cortex. All tool execution, memory writes, and governance decisions flow through the same control plane regardless of which surface initiated the request.

This document defines the interaction layer of Nous.

The runtime is the brain. These surfaces are how the user and Nous communicate.

Interaction Surfaces

On this page