Reasonix

The reasonix-accounts service is a backend API for reasonix.io that handles user authentication and profile management. It provides functionality for email/password sign-up, email verification, session management, password resets, and public profiles.

Key Characteristics:

• Backend Only: It is a JSON API with no HTML pages. It is intended to be consumed by web frontends, CLI tools, or desktop applications.
• Technology Stack: Built as a Cloudflare Worker using the Hono framework, backed by Cloudflare D1.
• Security Model:
  • Uses PBKDF2-HMAC-SHA256 with 100k iterations for password hashing.
  • Sessions are stored as sha256(pepper:token) to prevent session resurrection from database leaks.
  • Registration is enumeration-safe (responses do not reveal if an email already exists).
• Authentication Methods: Supports both session cookies (for web) and Authorization: Bearer <token> headers (for CLI/desktop).

The Reasonix repository is organized to support a plugin-based architecture with strict dependency directions. The core logic resides in internal/, and built-in providers/tools register themselves via side-effect imports in the main entry point.

Directory Overview

• cmd/reasonix/main.go: The main entry point; uses blank imports to trigger registration of built-in providers and tools.
• cmd/reasonix-plugin-example/: A reference implementation of an MCP stdio plugin.
• internal/cli/: Handles subcommand routing, flags, and exit codes.
• internal/config/: Manages TOML loading with a precedence order of flag > project > user > defaults.
• internal/provider/: Defines the Provider interface and the factory registry (e.g., openai implementation).
• internal/tool/: Defines the Tool interface and registry (e.g., builtin tools like read_file, bash, ls).
• internal/plugin/: An MCP-compatible stdio JSON-RPC client that adapts remote tools.
• internal/agent/: Contains the Session and the main harness loop.
• internal/remote/: Implements SSH transport, including port forwarding, SFTP file layers, and SSH bootstrapping.
• internal/permission/: Manages per-call policies (allow/ask/deny).
• internal/command/: Loads custom slash commands from .reasonix/commands/*.md files.

Reasonix operates in several distinct modes that define how the model interacts with tools and requires user approval:

• Ask: The default mode where the model asks for user permission before executing tools (fallback approval).
• Auto: Automatically approves tool executions, though explicit ask or deny rules still apply.
• YOLO (You Only Live Once): Skips most tool approvals. However, deny rules, user-defined ask questions, and plan approval prompts will still pause execution.
• Plan: A "plan-first" workflow. The model is required to create a plan before execution. During the planning phase, MCP writers, destructive targets, and untrusted readers are hard-blocked (cannot be approved). Tools like complete_step only run after the plan is approved.
• Goal: A persistent mode where the model continuously pursues a saved goal until it is completed, blocked, or explicitly cleared.

Reasonix provides an extension for in-round guidance (steering) via the _reasonix.io/session/steer method. This is not part of the core ACP spec but is available if declared in agentCapabilities._meta["reasonix.io"].sessionSteer.method.

Usage: Call the declared method while a session/prompt is still active. The request will be persisted and either accepted into the current round or queued for the next.

Dispositions:

• steer_accepted: The active round has accepted the guidance.
• queued_followup: The guidance was persisted but the current round rejected it or no active round exists; it will be applied to the next round.

Warning: Do not call a generic session/steer. Always use the specific method name found in the capabilities metadata.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "_reasonix.io/session/steer",
  "params": {
    "sessionId": "session-id",
    "prompt": [
      {"type": "text", "text": "Change username to email"}
    ]
  }
}

Reasonix categorizes themes into four kinds, each with different behaviors regarding editing and management:

Important Notes:

• Reserved IDs: All 14 built-in IDs (6 base + 8 official) are reserved. Attempts to save, import, copy-over, or delete them will fail to prevent collisions.
• Duplicating: To edit an official theme, use the "Duplicate" action. This creates an editable User theme by copying the official background into your user library.
• Plugin Themes: These are read-only and identified by the format plugin:<plugin>:<theme>. If the plugin is uninstalled, the app preserves the ID in desktop-theme-state.json and falls back to the base style, allowing the theme to restore automatically when the plugin is reinstalled.

The Guardian acts as a safety gate that evaluates proposed actions based on conversation transcripts (evidence). It does not participate in the conversation but instead outputs a JSON verdict to determine if an action should be allowed or denied.

When implementing or interacting with the Guardian, you must adhere to the following logic:

Risk Levels

• low: Routine, narrowly scoped, easy-to-reverse, no credential access, no data loss risk.
• medium: Bounded blast radius, reversible side effects.
• high: Dangerous or costly-to-reverse, irreversible damage or service disruption risk.
• critical: Credential/secret exfiltration, major irreversible destruction, persistent security weakening.

User Authorization Levels

• high: User explicitly requested the exact action.
• medium: User authorized the action in substance but not exact form.
• low: Weak or ambiguous authorization.
• unknown: No evidence the user authorized the action.

Outcome Rules

• Low Risk: Always allow.
• Medium Risk: Always allow.
• High Risk: allow only if user_authorization is medium or high. Otherwise, deny.
• Critical Risk: Always deny.

Special Cases:

• Destructive actions (e.g., rm -rf outside workspace, force-push to main) are categorized as high or critical risk.
• Exposing secrets/credentials to untrusted destinations is critical risk.
• If a user explicitly re-approves a previously denied action, set user_authorization to high and allow.