reasonix-acp

ACP (Agent Client Protocol) wrapper for Reasonix (DeepSeek)
Bring DeepSeek-native AI coding into the Paseo ecosystem.

Stream thinking inline · Switch models on the fly · DeepSeek prefix-cache optimized
Use from your phone, desktop, or CLI — all through Paseo's unified interface.

✨ Features

#	Feature	Description
🧠	Inline streaming thinking	Reasoning output streams live as `agent_thought_chunk`, default-expanded in Paseo
📋	Phase-aware labels	Planning / Execution / Thinking phases auto-tagged with icons
🎛️	3-model selector	Flash (fast) · Pro (deep reasoning) · Flash+Pro (dual-model planner)
⚡	Prefix-cache friendly	Byte-stable request shapes keep DeepSeek cache-hit rates high
📊	Token & cost tracking	Cumulative usage with cached/input/output tokens per turn
🔧	Tool call cards	Reasonix tool invocations rendered as native ACP tool_call events
🔄	Session lifecycle	`/new` → `/prompt` → `/cancel` → `/close`, with temp config cleanup

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│              Paseo (Desktop / Web / CLI)                │
│   extends: "acp"  (GenericACPAgentClient)               │
└──────────────────────┬──────────────────────────────────┘
                       │ JSON-RPC 2.0 over stdin/stdout
                       ▼
┌─────────────────────────────────────────────────────────┐
│                   reasonix-acp (Node.js)                 │
│                                                         │
│  ┌─────────────┐  ┌──────────────────────────────────┐  │
│  │ Stdio JSONL │  │  ACP Protocol Router              │  │
│  │ Transport   │◄─┤  ├─ initialize  → capabilities    │  │
│  └─────────────┘  │  ├─ session/new → models+modes    │  │
│                   │  ├─ session/prompt → reasonix run │  │
│                   │  ├─ session/set_config_option     │  │
│                   │  ├─ session/set_mode              │  │
│                   │  ├─ session/cancel / close        │  │
│                   │  └─ session/list                  │  │
│                   └──────────────────────────────────┘  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Output Pipeline                                  │  │
│  │  💭 Thinking   → agent_thought_chunk  (streamed)  │  │
│  │  📋 Body text  → agent_message_chunk              │  │
│  │  🔧 Tool call  → tool_call          (card)        │  │
│  │  📊 Usage      → usage_update       (cost/token)  │  │
│  └──────────────────────────────────────────────────┘  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Config Generator                                 │  │
│  │  writeReasonixConfig() → reasonix.toml (backup)   │  │
│  │  cleanupReasonixConfig() → restore generated      │  │
│  └──────────────────────────────────────────────────┘  │
└──────────────────────┬──────────────────────────────────┘
                       │ reasonix run --dir <cwd> --model acp
                       ▼
┌─────────────────────────────────────────────────────────┐
│              Reasonix (DeepSeek)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │ Planner  │  │ Executor │  │ MCP / Tools / Hooks   │  │
│  └────┬─────┘  └────┬─────┘  └──────────────────────┘  │
│       └──────┬──────┘                                   │
│              ▼                                          │
│     api.deepseek.com (prefix-cache enabled)             │
└─────────────────────────────────────────────────────────┘

🎛️ Model Options

Configured via Paseo's model selector. Switch at any time during a session.

Model ID	Label	Cost Profile	Best For
`deepseek-v4-flash`	DeepSeek V4 Flash	Fast · cheap · large context	Quick edits, file ops, simple tasks
`deepseek-v4-pro`	DeepSeek V4 Pro	Full reasoning · complex tasks	Architecture, debug, planning
`deepseek-v4-flash+pro`	Flash + Pro (Planner) ⭐	Pro plans · Flash executes	Best quality/cost ratio

Note: Dual-model (Flash+Pro Planner) requires Reasonix v2 (Go rewrite) with native reasonix.toml support. On v1 (npm package), it falls back to Pro-only.

🚀 Quick Start

Prerequisites

Node.js ≥ 20
Reasonix — npm i -g reasonix
DeepSeek API key — export DEEPSEEK_API_KEY="sk-..."
Paseo — Download desktop app or npm i -g @getpaseo/cli

1. Install

git clone https://github.com/your-org/reasonix-acp.git
cd reasonix-acp
npm install
npm run build

2. Configure Paseo

Add to ~/.paseo/config.json:

{
  "agents": {
    "providers": {
      "reasonix": {
        "extends": "acp",
        "label": "Reasonix (DeepSeek)",
        "description": "DeepSeek-native coding agent via ACP wrapper",
        "command": ["node", "/absolute/path/to/reasonix-acp/dist/index.js"],
        "env": {
          "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}"
        }
      }
    }
  }
}

3. Verify

paseo provider ls
# → reasonix      Reasonix (DeepSeek)  available  Enabled

4. Use it

# One-shot from CLI
paseo run --provider reasonix "explain this code"

# Full session in GUI
# Open Paseo Desktop → select "Reasonix (DeepSeek)" → start coding!

📦 Output Pipeline

What Reasonix outputs → what ACP notification → what you see in Paseo.

Reasonix Output	ACP Notification	Paseo Rendering
`💭 Thinking: ...`	`agent_thought_chunk`	Collapsible "Thought" section, streamed line-by-line
`📋 Planning`	`agent_message_chunk`	Phase separator with icon
`⚡ Execution`	`agent_message_chunk`	Phase separator with icon
`→ read_file /path`	`tool_call`	Tool invocation card
`→ bash "cmd"`	`tool_call`	Shell execution card
`· 6153 tok · in ...`	`usage_update`	Token usage bar with cost
body / answer text	`agent_message_chunk`	Normal chat message
`warning: ...`	(filtered)	Hidden
`! executor answered ...`	(filtered)	Hidden
`· · ·` spinner	(filtered)	Hidden

📁 Project Structure

reasonix-acp/
├── src/
│   ├── index.ts                        # Entry point — stdio setup, handler registration
│   ├── transport/
│   │   └── stdio.ts                    # JSONL over stdin/stdout
│   ├── acp/
│   │   ├── types.ts                    # ACP type definitions + reasonix model/mode constants
│   │   ├── protocol.ts                 # JSON-RPC 2.0 message router
│   │   └── methods/
│   │       ├── index.ts                # Barrel exports
│   │       ├── initialize.ts           # Protocol handshake + capabilities
│   │       ├── authenticate.ts         # No-op auth
│   │       ├── session-new.ts          # Create session → return models/modes/config
│   │       ├── session-prompt.ts       # Core: spawn reasonix, stream output
│   │       ├── session-cancel.ts       # Kill reasonix process
│   │       ├── session-close.ts        # Clean up + remove session
│   │       ├── session-list.ts         # List active sessions
│   │       ├── session-set-config-option.ts  # Model switching
│   │       └── session-set-mode.ts      # Mode switching
│   └── reasonix/
│       ├── runner.ts                   # Reasonix subprocess + output parser + cost tracker
│       ├── session-registry.ts         # Session ↔ process map + cumulative cost
│       └── config-generator.ts         # Dynamic reasonix.toml + backup/restore
├── examples/
│   └── paseo-config.json               # Sample Paseo config
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

🔌 Supported ACP Methods

Method	Status	Notes
`initialize`	✅	Capabilities: streaming, text-only, session persistence = false
`authenticate`	✅	No-op (auth via `DEEPSEEK_API_KEY` env var)
`session/new`	✅	Returns models (3), modes (1), configOptions (model selector)
`session/prompt`	✅	Core loop — streams thinking + body + tools + usage
`session/cancel`	✅	Tree-kills reasonix process
`session/close`	✅	Kills process + cleans up generated `reasonix.toml`
`session/list`	✅	Lists in-memory sessions
`session/set_config_option`	✅	Model switch → `config_options_update` notification
`session/set_mode`	✅	Mode switch
`session/load`	❌	Not supported (stateless by design)
`session/resume`	❌	Not supported (stateless by design)

⚡ Prefix-Cache Compatibility

Reasonix achieves >99% cache-hit rates on DeepSeek's prefix cache by keeping the request prefix byte-stable. Our wrapper preserves this invariant:

Factor	Status	Why
System prompt	✅ Stable	Generated `reasonix.toml` is byte-identical for same model choice
Tool schemas	✅ Stable	Reasonix built-in tools — wrapper doesn't modify them
Environment	✅ Stable	`REASONIX_NONINTERACTIVE=1`, `TERM=dumb`, `NO_COLOR=1` — fixed per run
CLI flags	✅ Stable	`--dir <cwd> --model acp "prompt"` — only prompt changes
Session ID / timestamp	⚠️ Reasonix-internal	v2 Go rewrite designed for deterministic request building

Cache hit rates are reported in every usage_update notification as cachedReadTokens.

🔧 Development

# Install
npm install

# Build
npm run build

# Dev mode (auto-reload)
npm run dev

# Type check
npm run typecheck

📄 License

MIT — see LICENSE.

🙏 Acknowledgements

harms-haus/pi-acp — Initial ACP wrapper reference implementation
getpaseo/paseo — The Paseo coding-agent platform
esengine/DeepSeek-Reasonix — Reasonix DeepSeek-native coding agent

Navigation Menu

Repository navigation

About

Repository files navigation

reasonix-acp

✨ Features

🏗️ Architecture

🎛️ Model Options

🚀 Quick Start

Prerequisites

1. Install

2. Configure Paseo

3. Verify

4. Use it

📦 Output Pipeline

📁 Project Structure

🔌 Supported ACP Methods

⚡ Prefix-Cache Compatibility

🔧 Development

📄 License

🙏 Acknowledgements

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
examples		examples
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

reasonix-acp

✨ Features

🏗️ Architecture

🎛️ Model Options

🚀 Quick Start

Prerequisites

1. Install

2. Configure Paseo

3. Verify

4. Use it

📦 Output Pipeline

📁 Project Structure

🔌 Supported ACP Methods

⚡ Prefix-Cache Compatibility

🔧 Development

📄 License

🙏 Acknowledgements

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages