SamCDay/rune
1
1 Fork 0
forked from conductor/rune
Code Pull Requests Activity
Files
master
rune/PRD.md
T

9.2 KiB
Raw Permalink Blame History

Rune TUI — Product Requirements Document (PRD)

Last Updated: 2026-09-07 Version: v0.45.1 Status: Active Development

What Rune Is

Rune is a stateful coding assistant with a Textual-based TUI. It connects to local LLM models (Ollama) and provides a chat interface with memory, personality, tool calling, and autonomous capabilities. Rune remembers, learns, and grows.

Version: v0.54.0 · HEAD: 3e0b748 · Regenerated: 2026-09-07

Governed TUI surfaces (docs/tui-registry.md)

| rune_tui.py | The main Textual application — chat pane, work pane, status bar (version label + refresh), footer, dialogs | The known giant (file-size debt tracked in henxels); composition root for all UI | | tui_validator.py | Import-allowlist validation for TUI code | Drift defect tracked in #139 (allowlist vs __future__/relative imports) |

rune_tui.py is 4075 lines — the known giant, file-size debt tracked in henxels; decomposition target #125.

TUI-adjacent subsystems (impact map)

  • orchestration umbrella: 38 modules (operator, TUI presentation, task lifecycle)
  • perception umbrella: 9 modules (context assembly, capsule)
  • capability umbrella: 7 modules (tool authority)

Architecture

Core Stack

  • TUI: Textual (Python terminal UI framework)
  • Models: Ollama (local inference), cloud providers via API
  • Memory: SQLite + sqlite-vec + FTS5 hybrid store
  • Personality: Identity anchors, voice injection, persona gate
  • Tools: File read/write/list/search/command via tool_executor.py

Key Files

  • rune_tui.py — Main TUI application (2400+ lines)
  • rune_operator.py — Model interaction, prompt construction, response processing
  • tool_executor.py — File operation tools for LLM agents
  • safety_override.py — Adaptive safety override (escalation + learning)
  • model_profiles.py — Intelligent model profile system
  • work_manager.py — Task batching and model routing
  • contracts.py — Function contract testing
  • tui_validator.py — CSS and widget validation
  • skills/llm-craft/ — LLM engineering knowledge base
  • skills/textual-craft/ — Textual TUI engineering knowledge base

Features (v0.45.1)

Chat System

  • Two channels: Task (focused work) and Chat (free conversation)
  • Chat bubbles with role-specific styling (user, assistant, system, confirm, thinking)
  • Right-click copy menu on any chat bubble
  • Input history with up/down arrow persistence (200 entries per channel)
  • Auto-complete for commands

Model Integration

  • Ollama local models (3B to 27B)
  • Cloud providers via API (OpenAI-compatible)
  • Model selector with expandable categories (Local/Cloud)
  • Model profiles: family, size, strengths, weaknesses, prompting tips
  • Adaptive timeouts: 3B=90s, 7B=120s, 14B=180s, 27B=300s
  • Model preload on startup (background thread)

Personality System

  • Native personality in system prompt (not instructional)
  • Examples of how Rune speaks, not descriptions
  • Memory recall for personality context (always present)
  • Empathy, genuineness, material reality, originality
  • Voice influences absorbed into unified voice

Memory System

  • SQLite + sqlite-vec + FTS5 hybrid store
  • Memory recall on every request (budget=3)
  • Personality context always in system prompt
  • Task-specific context from memory recall
  • Memory indicator in status bar (🧠 N)

Safety Override

  • Adaptive escalation: normal → higher temp → affirmative prefix
  • Pattern learning: records which topics need override
  • Blanket override for uncensored models (tier 3)
  • Safety noise filter for thinking blocks (22 patterns)
  • Permissive mode: gate never refuses

Tool Calling

  • Native Ollama /api/chat tool calls with ordered multi-turn results
  • Validated JSON fallback for local models without native tool capability
  • File operations: read, write, list, directory, search, command
  • Sandbox: paths validated against allowed directories
  • Mutations prepare a diff and require explicit approval before execution
  • Approval revalidates operation, path, and content digest and executes once
  • Atomic writes with backup (.bak files)
  • Undo stack (last 50 writes)

TUI Features

  • Status bar: channel indicator, model summary, memory indicator, refresh icon
  • Thinking indicator: animated spinning purple diamond (pixel art via rich-pixels)
  • ThinkingBubble: collapsible thinking blocks (click to expand/collapse)
  • Tool calls/results: dedicated stable-ID objects between chat messages
  • Tool states update in place; protocol data never renders as assistant prose
  • Model selector: expandable categories, checkboxes, tooltips
  • Right-click copy menu on chat bubbles
  • /audit command: full codebase audit against llm-craft
  • /pull command: download models with progress bar
  • /work command: task batching and model routing

Knowledge Base

  • llm-craft: LLM engineering guide (checklist, patterns, deep dives)
  • textual-craft: Textual TUI engineering guide
  • Contract testing: 42 function contracts
  • TUI validator: CSS and widget validation
  • Full audit: 75 files, 302 findings (all fixed)

Configuration

Model Selection

  • Default: auto (routes by task complexity)
  • Local: qwen3:14b (coding), qwen2.5:3b (quick), qwen3.6-27B-uncensored (complex)
  • Cloud: mimo-v2.5-pro (via API)
  • Switch: /model or model selector

Ollama Environment

OLLAMA_FLASH_ATTENTION=1
OLLAMA_KV_CACHE_TYPE=q8_0
OLLAMA_KEEP_ALIVE=-1
OLLAMA_MAX_LOADED_MODELS=1
OLLAMA_NUM_PARALLEL=1
OLLAMA_CONTEXT_LENGTH=8192

WezTerm Config

  • Font: JetBrains Mono 11pt
  • Theme: Dracula
  • Shell: bash
  • Kitty graphics: enabled
  • Keybindings: Ctrl+Shift+D split, Ctrl+Tab switch tabs

Development Workflow

1. LEDGER/WORKTREE → Durable checkpoint and isolated branch
2. RESEARCH        → Deep research with pinned, sourced findings
3. FEASIBILITY     → Feasibility and measured complexity gates
4. CONSULT/PLAN    → Knowledge/failure patterns and dependency batches
5. CANARIES        → Failure-sensitive contracts written before build
6. CONSENT         → Approve the plan and finalized canaries
7. BUILD           → Foundation → Implementation → Integration
8. VERIFY          → Inline canaries, contracts, scope guardian, full suite
9. DOCUMENT        → README, PRD, and learning record
10. GITEA          → Commit, push branch, PR, Actions, protected required checks

Explicit fix/build requests enter this pipeline automatically. Placeholder phase output is not evidence; completion requires observed local verification and passing Gitea required checks.

Rune v1 authority admission

The Rune v1 course correction is governed by:

  • config/v1_authority_map.json — machine-readable ownership and disposition;
  • docs/v1/AUTHORITY_MAP.md — current-versus-target authority decision record;
  • Gitea epic #16 and P0-01 issue #17.

New cognitive/runtime mechanisms must identify one owner, a precise trigger, dormant cost, ContextBroker contribution, authority relationship, observable failure, verification, learning, removal, and benchmark. P0-01 maps these relationships but does not implement the migrations.

Test Suite (all must pass before commit)

  1. Canary: 92 imports + 42 contracts + CSS validation
  2. Ruff: fast Python linter
  3. Pyright: static type checker
  4. Contract tests: function return shape verification
  5. TUI validator: CSS property validation

Cron System

Timed Tasks

  • Claim audit sweep: every 4 hours
  • Persona check: every 4 hours
  • LLM craft update: Sunday 03:00 UTC

Task-Completion Triggers

  • /cron on-complete <name> <cmd> — fires after each model response
  • Used for: PRD updates, memory consolidation, pattern learning

Pending Work

High Priority

  • Streaming responses (show tokens as they arrive)
  • Expand explicit tool approval controls and typed permission states
  • Model selector scroll refinement

Medium Priority

  • Expand contract coverage (42 → 100+ functions)
  • Implement work manager batch processing
  • Add more linter rules to llm-craft

Low Priority

  • Graphic thinking animation (blocked on terminal choice)
  • MCP integration for research tools
  • Plugin system for extensibility

Research Findings

LLM Engineering (llm-craft)

  • CoT only works at 100B+ params
  • Self-consistency is highest-ROI reasoning technique
  • Structured output collapses diversity (-0.22 bits)
  • Memory retrieval = recency × importance × relevance
  • Active memory management beats passive RAG 58.6% to 0%

Inference Optimization

  • FlashAttention: 2-3x speedup
  • KV cache quantization: halves memory
  • CPU thread oversaturation is #1 local inference killer
  • Speculative decoding: 2-2.5x at low QPS, 1.8x slowdown at high QPS

Safety Engineering

  • Constitutional AI: self-critique + revision without human labels
  • Llama Guard: small classifier as safety layer
  • NeMo Guardrails: 5 types of programmable rails
  • OWASP Top 10: prompt injection, insecure output, excessive agency

Research Methodology

  • Source quality: papers > practitioner blogs > newsletters > forums
  • LLM hallucination baseline: 5-10%
  • Benchmarks saturate quickly and are gamed
  • arXiv + Semantic Scholar + OpenAlex + Crossref = free research stack
View Git Blame Copy Permalink