Chat

The chat interface is the primary way to interact with Nous. Messages are project-scoped — each project has its own conversation history.

Sending Messages

1. Select a project in the sidebar (or create one)
2. Type your message in the input field
3. Press Enter or click Send

Nous processes your message through the full execution cycle: Cortex evaluation, model invocation, memory candidate generation, and response. The response appears when the turn completes.

Phase 1: Responses are displayed in full after the turn completes. Streaming (token-by-token) is deferred to Phase 2+.

CLI Provider Sessions

Chat-bound provider sessions apply only when the selected agent-cli provider satisfies the role's required execution profile. Cortex Chat and Cortex System require persistent_process semantics; only CLI providers that declare a compatible profile can back those roles. Selection-time compatibility validation prevents incompatible providers from being assigned.

Codex CLI declares session_bound_command and is not compatible with Cortex Chat/System persistent-process roles. Codex is available through compatible command-bound roles instead; transient and batch Codex work uses one-shot codex exec.

When a compatible CLI provider is used in a chat-bound context, Nous routes the turn through the runtime CLI session manager. The session manager keys provider lifecycle state to the chat fixture, not to conversation memory. Project chat sessions include the provider id, fixture role, project id, and chat session id in the provider-session key. System-wide chat sessions include the provider id, fixture role, and chat session id, without a synthetic project id. STM remains the source of conversation history; provider sessions only track lifecycle state such as active, busy, dead, or teardown.

If a chat-bound CLI provider session is lost, the next turn creates a fresh session for the same key. If restart fails, chat surfaces the provider-session error instead of silently switching to one-shot execution.

Welcome Message (First Open)

The first time you open the principal chat panel after finishing the first-run wizard, the agent emits a single greeting message. The welcome appears in the chat UI on first chat open regardless of which chat surface you use, is durable across re-mount (closing the chat and reopening it shows the same single welcome, not a duplicate), and is not re-issued once the welcome flag has already been set. The welcome is part of the first-run experience — the wizard configures the agent's identity, then the chat introduces it.

When the welcome fires

The welcome fires the first time the principal chat panel mounts after first-run completion. This is also true if you close Nous between finishing the wizard and opening chat — the welcome lives at the chat panel mount, not at the wizard exit, so a restart still produces the welcome.

What the welcome looks like

It looks like every other agent message — same row component, same persistence, no badge, no highlight, no special "welcome" label. The wording is whatever the model produced from a short, preset-neutral instruction; the personality preset you chose on the Identity step shapes the tone (a professional preset produces a more formal greeting; the default balanced produces a friendlier one).

One-shot semantic

A persistent flag (agent.welcomeMessageSent in nous-config.json5) tracks whether the welcome has already fired. Once it lands successfully, the flag flips to true and subsequent chat panel mounts skip the trigger. The welcome is single-fire by design — there is no per-project welcome, no second welcome after a major update, and no welcome re-fire when you switch projects within the same chat surface.

Personality and identity inheritance

Your chosen agent name, the personality preset (or any individual trait overrides), and the user profile context you optionally shared on the Identity step shape every reply on the principal chat from the first chat turn onward — not only the welcome. The agent introduces itself under the name you chose, adapts its register to the expertise level you set, addresses you by your chosen display name, and reflects the personality preset's behavioural axes in its reply prose. The welcome composes through the same prompt path as every chat turn, so anything that flows into a normal agent reply also flows into the welcome; there is no separate "welcome template" and no separate every-reply template — the agent simply produces every turn under the same composition contract.

Graceful degradation

If the model provider is unreachable when chat first opens (Ollama daemon stopped, cloud provider timing out), the chat still mounts cleanly. No welcome appears, the flag stays false, and the next time you mount the chat panel the welcome retries. The chat is never blocked or stalled by a welcome composition failure. See Troubleshooting § No Welcome Appears on First Chat Open for recovery steps.

Reset reissue

Calling firstRun.resetWizard (see tRPC Procedures § firstRun) clears the entire agent block — including welcomeMessageSent. After a reset, re-completing the wizard and reopening chat fires a fresh welcome composed against whatever new identity you configure. This is the supported way to re-experience the welcome with a different personality or name.

Privacy

The welcome composition is the same model call as any other agent turn. There is no separate telemetry, no engagement tracking, no external probe — the welcome is observable only to you and your local STM store. The seed instruction itself is a short fixed string that lives in the composition input at welcome-init time only and is never persisted to the agent's identity, personality, or any other long-lived shape.

Thread Types and Project Scope

Chat uses thread topology to enforce control-plane integrity:

Project scope is mandatory for any action that dispatches work or mutates run state. If you ask Nous to run a task, pause execution, or perform a control action without an explicit project context, Nous will ask for clarification before proceeding. No side effects occur until scope is resolved.

Scratch threads remain non-executable until you explicitly bind them to a project or run. This prevents accidental execution from exploratory conversations.

Control Actions via Chat

Lifecycle control actions (pause, resume, stop, recover) requested in chat route through operator-control — the same integrity contracts used by the Projects UI and CLI. Chat does not bypass confirmation requirements or evidence linkage.

When you ask Nous to pause or stop a run, the request is validated, routed to operator-control, and requires confirmation proof per Operator Control. Chat is intent; authority remains with the control plane.

Clarification Behavior

When Nous cannot confidently classify your intent (e.g., ambiguous scope, high-impact action with low confidence), it fails closed — it asks for clarification and performs no side effects. This applies to executable requests, control intents, and project-admin actions.

Message History

Conversation history is stored in short-term memory (STM) and persists across sessions. When you switch projects, you see that project's history.

When a conversation grows beyond the configured STM pressure threshold, Nous compacts older turns into a generated summary and keeps the newest turns verbatim. This keeps long-running project chats usable without dropping project context. The retained turns stay in chronological order, and the current STM state is visible through history and memory export surfaces.

Escalation Inbox (Phase 9.6)

Phase 9.6 adds a chat-side escalation inbox. This inbox reads the same canonical in-app escalation queue used by the Projects surface.

That means:

• The inbox is project-scoped
• Acknowledging an escalation in chat updates the same canonical record that Projects reads
• Chat does not maintain a separate acknowledgement state

Use the inbox when you want to confirm receipt of an escalation without leaving the conversation flow. This is especially useful when the escalation is mirrored into chat for urgent project attention.

Acknowledging an escalation in chat does not:

• Resume a blocked workflow automatically
• Clear project control-state restrictions
• Bypass operator-control or confidence-governance rules

It only records the acknowledgement on the canonical escalation record. If the underlying issue still requires review, reconfiguration, or workflow intervention, handle that through the appropriate governed surface afterward.

Project control state may still block configuration or schedule edits elsewhere, but escalation acknowledgement remains available so operators can record awareness even while the project is paused or hard stopped.

MAO Reasoning Handoff (Phase 9.7)

Phase 9.7 extends chat with MAO-origin continuity instead of a second reasoning transcript model.

When chat is opened from an MAO inspect view, the page now preserves:

• The linked project, run, and node context
• The reasoning-preview reference and primary evidence ref passed from MAO
• A return path back to the originating MAO context

The chat page can show the handoff and the shared escalation queue, but it still does not own private chain-of-thought or a chat-local recovery state.

Reasoning Preview Boundary

MAO reasoning previews are evidence-derived summaries. Chat may receive:

• The preview evidence reference
• The redaction-aware summary context
• Linked workflow scope for the affected run or node

Chat must not receive or display hidden private reasoning beyond that redaction-aware preview contract.

Projects Visual-Debug Handoff (Phase 11.4)

Phase 11.4 adds a second continuity entry path into chat: the advanced Projects visual-debug surface.

When chat is opened from a Projects canvas node or node-inspect panel, the route preserves:

• projectId
• runId
• nodeId
• evidenceRef when available

That means chat can continue the same project-scoped debugging conversation that started in the Projects surface without inventing a separate workflow-state model.

Use this handoff when you want to:

• ask follow-up questions about a specific blocked or failed workflow node
• continue investigation on the same run while keeping project and node scope intact
• move from visual debugging into conversational reasoning without losing canonical evidence references

The chat page still does not own workflow control truth. It receives continuity context and shared escalation state, but the authoritative workflow and debug posture stays in the canonical runtime and the projection surfaces built on top of it.

Mobile Continuity (Phase 11.5)

Phase 11.5 extends that same continuity model to the mobile operations surface.

If you acknowledge a project escalation from the mobile surface, chat reflects the same canonical acknowledgement state. Chat does not reconcile a second inbox, and the mobile surface does not create a chat-local follow-up model.

Use this when you need to:

• acknowledge an escalation on mobile and continue the investigation in chat later
• move from mobile project review into a fuller project-scoped conversation
• preserve shared voice follow-up posture across mobile, chat, MAO, and Projects

The rule remains the same: continuity context can move between surfaces, but authority stays with the canonical escalation, voice, workflow, and project runtimes.

Via CLI

pnpm dev:cli -- send "Your message here"
pnpm dev:cli -- -p <project-id> send "Project-scoped message"

Related

• Secure Messaging (Telegram)