[EPIC] [MIND-REASON] Cross-platform Reasoning Engine

[ucguy4u]

Goal

Airo Mind produces structured, intent-driven answers with a user-facing progress summary on every platform. Reasoning is a capability, not an inference-runtime feature and not a Flutter brain.

Same reason(request) API on macOS, Windows, Android, iOS, and iPadOS. Only the GenerationEngine implementor and the loaded model change.

Architectural rule (ADR-0002): Flutter calls reason() and renders ReasoningEvent. Rust owns policy, prompt, GBNF, parse, validate, and the tool loop. Chain-of-thought is an internal last-mile tick — never a stored field, never result.thoughts, never Gallery partialThinkingResult.

Pro boundary

Public crate rust/airo_mind_reasoning, same as airo_mind_meeting. Not an airo-pro overlay.

Critical Agent Gate

Problem: Chat streamed unconstrained tokens. Users need last-mile structured answers, not a raw thinking dump.

User / actor: Airo Mind chat on device.

Framework or application layer: Mixed — Rust capability (framework) + feature_mind presentation (application).

Owning agent: Framework Agent + Product Manager (feature_mind)

Reviewing agents: Chief Architect, Rust Architect, Platform Architect, Chief Performance Officer, Chief Security Officer, Chief QA Officer, Chief UX Officer

Decision: Ready

Contract

Flutter UI  ──FRB──►  airo_mind_reasoning
                         │  policy, context, prompt, parse, validate, tools
                         ▼
                   GenerationEngine  (domain-free)
                         │
          llama.cpp / Apple FM / LiteRT

Persist answer + reasoning_summary + level + tool_calls. Never thoughts / scratchpad / raw_thoughts / partialThinkingResult.

Tool loop cap = 5. none level: at most one tool, then answer, no second LLM call if the tool result is the answer.

Depends on

• [MIND-LLM-1] LlmBackend trait + llama.cpp GGUF backend in Rust core #1628 GBNF + GenerationEngine (landed)
• [MIND-LLM-4] Device-tier gating + local/cloud routing #1631 device tiers (landed)
• [MIND-LLM-5] Flutter plugin seam — thin Dart plugin over Rust FFI (airo-pro package) #1638 Flutter generation seam (landed)

Related, not duplicated

• [EPIC] [MIND-LLM] On-device intelligence — local LLM runtime + offline meeting intelligence #1627 MIND-LLM runtime epic — this epic consumes that runtime; it does not add an 8th primitive
• [COINS-AI-1] Coins LLM consumption seam — shared constrained-extraction contract over Mind runtime #1644 Coins constrained extraction — consumer of the same last-mile contract, not a second engine
• [MIND-LLM-23] Assistant chat over meeting archive (IR + transcripts) #1789 chat over meetings
• Model Routing #497 model routing
• [EPIC] Phase 9 — AI Runtime: extraction, summarization, merge proposals #1202 Phase 9 graph writes — later; V1 has no silent vault write
• [MIND-LLM-6] Apple Foundation Models backend — iOS zero-download path #1640 Apple FM backend — later GenerationEngine impl
• Airo Mind: split the runtime into two cdylibs (whisper and llama vendor incompatible ggml) #1546 iOS ffiPlugin / ggml ODR

Close / reframe

• Add Thinking Mode to Brain AI Chat for supported models #271 Thinking Mode — superseded. Gallery-style raw CoT stream will not ship. Progress UI is StageChanged / Progress / ToolStarted. Keep capability gating (DeviceInferenceProfile + engine-ready), never a "show thinking" toggle that reveals a scratchpad.

Slice status (branch agent/mind/reasoning-engine)

ID	Title	Status
MIND-REASON-0	ADR + epic (this issue)	Landing with ADR-0002
MIND-REASON-1	Policy + levels	Done (9ba00595)
MIND-REASON-2	Prompt + result GBNF (no thoughts)	Done (9ba00595)
MIND-REASON-3	Event stream + parser	Done (9ba00595)
MIND-REASON-4	Wire GenerationEngine + Dart facade	Done (9ba00595)
MIND-REASON-5	Context pack	Done (9ba00595)
MIND-REASON-6	Tool loop cap=5	Done (84741190)
MIND-REASON-7	Thinking progress UI	Done (62efd199)
MIND-REASON-8	Persistence without raw CoT	Done (62efd199)
MIND-REASON-9	Device-tier clamp	Done (62efd199)

Remaining on this epic

• Host GGUF smoke: cargo test -p airo_mind_llama --features llama --test reasoning_offline with AIRO_LLAMA_MODEL or the default tiny Qwen GGUF
• Android chat GGUF uses the FRB llama slot so reason() runs; JNI is fallback only
• iOS/iPad: same API, backend blocked on Airo Mind: split the runtime into two cdylibs (whisper and llama vendor incompatible ggml) #1546 / [MIND-LLM-6] Apple Foundation Models backend — iOS zero-download path #1640

Verification environment

Host-only for crate + Dart tests. Real GGUF smoke is opt-in (AIRO_LLAMA_MODEL). Android emulator not required.

Docs

• docs/architecture/ADR-airo-mind-reasoning-engine.md (ADR-0002)
• docs/features/airo-mind/REASONING_ENGINE_ARCHITECTURE_REPORT.md
• docs/superpowers/plans/2026-08-21-airo-mind-reasoning-engine.md

Feature Packet

Deterministic use cases: calendar lookup stays none; planning clamps by device tier; malformed envelope is InvalidModelOutput; tool loop stops at 5.

Security/privacy: no thought traces in SharedPreferences; no OS cfg in the reasoning crate; lookup-only tools (no create-event / notify) on the reasoning loop.

Rollback: chat send path can disable reason() via useOnDeviceReasoning; history schema v1 is additive.