xminal 0.0.0-stage → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +16 -0
- package/CHANGELOG.md +82 -0
- package/EXECUTION-PLAN.md +135 -0
- package/FEATURE_MATRIX.md +173 -0
- package/LICENSE +21 -0
- package/PLAN.md +619 -0
- package/README.md +133 -2
- package/SECURITY.md +34 -0
- package/assets/logo.svg +26 -0
- package/dist/bridges/telegram.js +192 -0
- package/dist/bridges/telegram.js.map +1 -0
- package/dist/cli/args.js +156 -0
- package/dist/cli/args.js.map +1 -0
- package/dist/cli/audit.js +38 -0
- package/dist/cli/audit.js.map +1 -0
- package/dist/cli/callbacks.js +14 -0
- package/dist/cli/callbacks.js.map +1 -0
- package/dist/cli/commands.js +534 -0
- package/dist/cli/commands.js.map +1 -0
- package/dist/cli/render.js +142 -0
- package/dist/cli/render.js.map +1 -0
- package/dist/cli/repl.js +161 -0
- package/dist/cli/repl.js.map +1 -0
- package/dist/config/config.js +244 -0
- package/dist/config/config.js.map +1 -0
- package/dist/config/default-models.js +264 -0
- package/dist/config/default-models.js.map +1 -0
- package/dist/config/doctor.js +100 -0
- package/dist/config/doctor.js.map +1 -0
- package/dist/config/paths.js +52 -0
- package/dist/config/paths.js.map +1 -0
- package/dist/config/provider-defaults.js +50 -0
- package/dist/config/provider-defaults.js.map +1 -0
- package/dist/config/types.js +3 -0
- package/dist/config/types.js.map +1 -0
- package/dist/core/agent.js +394 -0
- package/dist/core/agent.js.map +1 -0
- package/dist/core/cost.js +40 -0
- package/dist/core/cost.js.map +1 -0
- package/dist/core/permissions.js +218 -0
- package/dist/core/permissions.js.map +1 -0
- package/dist/core/session.js +248 -0
- package/dist/core/session.js.map +1 -0
- package/dist/core/tool-usage.js +92 -0
- package/dist/core/tool-usage.js.map +1 -0
- package/dist/index.js +496 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp/client.js +177 -0
- package/dist/mcp/client.js.map +1 -0
- package/dist/mcp/server.js +112 -0
- package/dist/mcp/server.js.map +1 -0
- package/dist/memory/store.js +140 -0
- package/dist/memory/store.js.map +1 -0
- package/dist/orchestration/ralph.js +42 -0
- package/dist/orchestration/ralph.js.map +1 -0
- package/dist/providers/anthropic.js +192 -0
- package/dist/providers/anthropic.js.map +1 -0
- package/dist/providers/gemini.js +162 -0
- package/dist/providers/gemini.js.map +1 -0
- package/dist/providers/openai.js +140 -0
- package/dist/providers/openai.js.map +1 -0
- package/dist/providers/router.js +100 -0
- package/dist/providers/router.js.map +1 -0
- package/dist/providers/sse.js +61 -0
- package/dist/providers/sse.js.map +1 -0
- package/dist/providers/types.js +15 -0
- package/dist/providers/types.js.map +1 -0
- package/dist/runtime.js +89 -0
- package/dist/runtime.js.map +1 -0
- package/dist/server/http.js +263 -0
- package/dist/server/http.js.map +1 -0
- package/dist/server/web.js +117 -0
- package/dist/server/web.js.map +1 -0
- package/dist/skills/install.js +50 -0
- package/dist/skills/install.js.map +1 -0
- package/dist/skills/loader.js +145 -0
- package/dist/skills/loader.js.map +1 -0
- package/dist/tools/agent-tools.js +59 -0
- package/dist/tools/agent-tools.js.map +1 -0
- package/dist/tools/bash-tool.js +145 -0
- package/dist/tools/bash-tool.js.map +1 -0
- package/dist/tools/checkpoint-tool.js +49 -0
- package/dist/tools/checkpoint-tool.js.map +1 -0
- package/dist/tools/diagnostics-tool.js +56 -0
- package/dist/tools/diagnostics-tool.js.map +1 -0
- package/dist/tools/fs-tools.js +339 -0
- package/dist/tools/fs-tools.js.map +1 -0
- package/dist/tools/git-tool.js +99 -0
- package/dist/tools/git-tool.js.map +1 -0
- package/dist/tools/index.js +34 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/mcp-tool.js +91 -0
- package/dist/tools/mcp-tool.js.map +1 -0
- package/dist/tools/memory-tool.js +54 -0
- package/dist/tools/memory-tool.js.map +1 -0
- package/dist/tools/registry.js +47 -0
- package/dist/tools/registry.js.map +1 -0
- package/dist/tools/skill-tool.js +36 -0
- package/dist/tools/skill-tool.js.map +1 -0
- package/dist/tools/todo-tool.js +104 -0
- package/dist/tools/todo-tool.js.map +1 -0
- package/dist/tools/types.js +40 -0
- package/dist/tools/types.js.map +1 -0
- package/dist/tools/verify-tool.js +74 -0
- package/dist/tools/verify-tool.js.map +1 -0
- package/dist/tools/web-tool.js +113 -0
- package/dist/tools/web-tool.js.map +1 -0
- package/dist/tools/worktree-tool.js +83 -0
- package/dist/tools/worktree-tool.js.map +1 -0
- package/dist/util/ansi.js +78 -0
- package/dist/util/ansi.js.map +1 -0
- package/dist/util/diff.js +50 -0
- package/dist/util/diff.js.map +1 -0
- package/dist/util/fs.js +132 -0
- package/dist/util/fs.js.map +1 -0
- package/dist/util/glob.js +47 -0
- package/dist/util/glob.js.map +1 -0
- package/dist/util/log.js +32 -0
- package/dist/util/log.js.map +1 -0
- package/dist/util/redact.js +34 -0
- package/dist/util/redact.js.map +1 -0
- package/dist/version.js +8 -0
- package/dist/version.js.map +1 -0
- package/package.json +59 -4
- package/scripts/install.sh +33 -0
- package/scripts/prepare.cjs +23 -0
- package/site/index.html +561 -0
package/PLAN.md
ADDED
|
@@ -0,0 +1,619 @@
|
|
|
1
|
+
# XMINAL — Master Plan
|
|
2
|
+
|
|
3
|
+
**Status:** v0.1.0 built · brand assets landed · see `EXECUTION-PLAN.md` for the phase-by-phase build order
|
|
4
|
+
**Source inventory:** `FEATURE_MATRIX.md` (125 projects, 125/125 mapped)
|
|
5
|
+
**Providers:** Default = OpenCode (`opencode/inkling-2-small-free`, keyless). 47 providers + 258 model aliases (models.dev snapshot 2026-11-08). User will adjust later. Bedrock/Vertex/Azure need native adapters (not built).
|
|
6
|
+
**License target:** MIT
|
|
7
|
+
**Working dir:** `/workspace/projects/ff`
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. Executive summary
|
|
12
|
+
|
|
13
|
+
**xminal** ek provider-agnostic terminal coding agent + orchestration platform hai jo 125 MIT projects ke best features ko ek hi product me laata hai.
|
|
14
|
+
|
|
15
|
+
Core idea:
|
|
16
|
+
|
|
17
|
+
> **Core small rakho, baaki sab adapters/skills/plugins se jodo.**
|
|
18
|
+
|
|
19
|
+
Hum 125 projects ko reimplement nahi karenge. Strategy:
|
|
20
|
+
|
|
21
|
+
- **Native** — jo core differentiator hai (agent loop, modes, sessions, memory, orchestration, security)
|
|
22
|
+
- **Borrow** — MIT code/algorithms/skills (TUI patterns, eval harness, skill packs)
|
|
23
|
+
- **Integrate** — external agents/tools via MCP, ACP, PTY, HTTP (Claude Code, Codex, OpenCode, browsers, Telegram)
|
|
24
|
+
- **Reference** — design inspiration only
|
|
25
|
+
|
|
26
|
+
Isse v1 jaldi ship hota hai aur baaki features plugin ecosystem me grow karte hain.
|
|
27
|
+
|
|
28
|
+
### Product pillars
|
|
29
|
+
|
|
30
|
+
1. **Any provider** — 40+ APIs, local models, failover, quota routing
|
|
31
|
+
2. **Any workflow** — Plan/Build/Compose/Yolo, spec-driven, Ralph loops
|
|
32
|
+
3. **Any scale** — single agent → subagents → worktree fleets → swarms
|
|
33
|
+
4. **Anywhere** — TUI, headless, HTTP/ACP server, Telegram, mobile
|
|
34
|
+
5. **Safe by default** — sandbox, secrets broker, audit receipts, provenance
|
|
35
|
+
6. **Remembers** — sessions, memory, codebase wiki, beads graph
|
|
36
|
+
7. **Cheap** — output compression, context pruning, token budgets, cost logs
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 2. Guiding principles
|
|
41
|
+
|
|
42
|
+
| Principle | Matlab | Source inspiration |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| Provider-agnostic | Koi bhi OpenAI/Anthropic/Gemini-compatible API + local | OpenCode, OpenCodex, Pi-ai |
|
|
45
|
+
| Local-first | Data/project local; cloud optional | OpenClaw, Atomic, Moltis |
|
|
46
|
+
| Composable | Core + adapters + skills + plugins | Pi, rpi, Open-Harness |
|
|
47
|
+
| Observable | Har tool call, cost, token, diff track ho | AgentSight, Trae, AgentDiff |
|
|
48
|
+
| Reversible | Undo, rewind, checkpoints, branch | Reasonix, Codewhale, Plandex |
|
|
49
|
+
| Safe | Sandbox default-on, secrets never to model | Codewhale, authsome, DvalinCode |
|
|
50
|
+
| Fast | ms startup, low RAM | jcode, NullClaw, 3code |
|
|
51
|
+
| Interoperable | MCP, ACP, LSP, DAP, Git | OpenCode, OpenHands, Martty |
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 3. High-level architecture
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
┌──────────────────────────────────────────────────────────────────────┐
|
|
59
|
+
│ INTERFACES │
|
|
60
|
+
│ TUI │ Headless CLI │ HTTP/WS Server │ ACP Server │ MCP │
|
|
61
|
+
│ Telegram/Slack/Discord │ Mobile companion │ GitHub Actions │
|
|
62
|
+
└───────────────────────────────┬──────────────────────────────────────┘
|
|
63
|
+
│
|
|
64
|
+
┌───────────────────────────────▼──────────────────────────────────────┐
|
|
65
|
+
│ AGENT RUNTIME │
|
|
66
|
+
│ Session Manager (branch/resume/rewind/checkpoint) │
|
|
67
|
+
│ Agent Loop (plan → act → observe → verify) │
|
|
68
|
+
│ Modes: Plan | Build | Compose | Review | Yolo │
|
|
69
|
+
│ Permission Engine: Ask | Auto-Review | Full Access │
|
|
70
|
+
│ Subagents | Swarm | Ralph Loops | Council | Worktree Fleet │
|
|
71
|
+
│ Context Engine: pruning, compression, retrieval, TurnMemory │
|
|
72
|
+
└───────────────────────────────┬──────────────────────────────────────┘
|
|
73
|
+
│
|
|
74
|
+
┌───────────────────────────────▼──────────────────────────────────────┐
|
|
75
|
+
│ CAPABILITY LAYER │
|
|
76
|
+
│ Providers/Router │ Tools │ Memory │ Skills │ Plugins │
|
|
77
|
+
│ MCP Client/Server │ ACP │ LSP/DAP │ Browser │ Search/RAG │
|
|
78
|
+
└───────────────────────────────┬──────────────────────────────────────┘
|
|
79
|
+
│
|
|
80
|
+
┌───────────────────────────────▼──────────────────────────────────────┐
|
|
81
|
+
│ PLATFORM LAYER │
|
|
82
|
+
│ Sandbox (bubblewrap/seatbelt/docker) │ Secrets Broker │
|
|
83
|
+
│ Audit/Provenance (hash chain, Git notes) │ Cost/Telemetry │
|
|
84
|
+
│ Config (xminal.toml) │ Storage (SQLite/JSONL/Blobs) │ Updates │
|
|
85
|
+
└──────────────────────────────────────────────────────────────────────┘
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 4. Repository layout (monorepo)
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
xminal/
|
|
94
|
+
├── apps/
|
|
95
|
+
│ ├── cli/ # xminal binary: TUI + headless
|
|
96
|
+
│ ├── server/ # HTTP/WS + ACP server
|
|
97
|
+
│ └── desktop/ # optional Tauri shell (later)
|
|
98
|
+
├── packages/
|
|
99
|
+
│ ├── core/ # agent loop, modes, permissions, sessions
|
|
100
|
+
│ ├── config/ # xminal.toml schema, profiles, doctor
|
|
101
|
+
│ ├── providers/ # adapter interface + implementations
|
|
102
|
+
│ ├── router/ # failover, cost, quota, capability routing
|
|
103
|
+
│ ├── tools/ # fs, bash, search, edit, lsp, dap, browser
|
|
104
|
+
│ ├── memory/ # session store, FTS5, markdown, wiki, beads
|
|
105
|
+
│ ├── context/ # pruning, compression, TurnMemory, retrieval
|
|
106
|
+
│ ├── orchestrator/ # subagents, worktrees, ralph, council, swarm
|
|
107
|
+
│ ├── sandbox/ # backends + secrets + policy engine
|
|
108
|
+
│ ├── skills/ # SKILL.md loader, registry, packs
|
|
109
|
+
│ ├── plugins/ # plugin host (Lua first, TS later)
|
|
110
|
+
│ ├── mcp/ # MCP client pool + server
|
|
111
|
+
│ ├── acp/ # ACP client/server
|
|
112
|
+
│ ├── bridge/ # telegram/slack/discord/webhooks
|
|
113
|
+
│ ├── telemetry/ # cost, traces, audit, provenance
|
|
114
|
+
│ └── sdk/ # embeddable TypeScript/Python SDK
|
|
115
|
+
├── skills/ # bundled skill packs (spec, TDD, review...)
|
|
116
|
+
├── templates/ # project templates / AGENTS.md presets
|
|
117
|
+
├── evals/ # SWE-bench harness, skill benchmarks
|
|
118
|
+
├── docs/
|
|
119
|
+
└── scripts/ # release, packaging, Termux
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## 5. Tech stack — options & recommendation
|
|
125
|
+
|
|
126
|
+
| Option | Pros | Cons | Verdict |
|
|
127
|
+
|---|---|---|---|
|
|
128
|
+
| **A. TypeScript + Bun monorepo** | Fastest dev; best MCP/SDK ecosystem; React/Ink TUI; Bun compiles to ARM64 binary; easy plugin loading | Higher RAM than Rust/Zig; startup ~50–100ms | **Recommended for v1** |
|
|
129
|
+
| B. Rust core + TS TUI | jcode-level perf; single binary; memory safe | 3–5x dev time; provider churn painful | v2 option |
|
|
130
|
+
| C. Go core + TS TUI | Single static binary; simple concurrency | TUI ecosystem weaker; plugins harder | Alternative |
|
|
131
|
+
| D. Hybrid: TS core + Rust native addons (ripgrep, tree-sitter, PTY) | Near-Rust speed where it matters | Build complexity | Incremental path |
|
|
132
|
+
|
|
133
|
+
**Recommendation:** Start with **A**, keep performance-critical pieces behind native interfaces (ripgrep/tree-sitter/PTY), and keep core logic UI-independent so a Rust core swap is possible later. Target **Linux ARM64 / Termux** from day 1 (source: 3code, Reasonix, NullClaw packaging lessons).
|
|
134
|
+
|
|
135
|
+
**Runtime requirements:** Node/Bun 20+, SQLite (bundled), optional Docker, optional bubblewrap.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 6. Provider layer (default = OpenCode; user to adjust later)
|
|
140
|
+
|
|
141
|
+
Built-in providers (all OpenAI-compatible unless noted):
|
|
142
|
+
|
|
143
|
+
| Provider | Type | Auth | Notes |
|
|
144
|
+
|---|---|---|---|
|
|
145
|
+
| opencode | openai | **keyless** | default; free models; endpoint may rate-limit (429 FreeUsageLimitError) |
|
|
146
|
+
| openai / anthropic (native) / gemini (native) | adapter | env key | |
|
|
147
|
+
| openrouter, groq, deepseek, mistral, xai, cerebras, cohere, togetherai, fireworks, perplexity, moonshotai(+cn), huggingface, github (GitHub Models), nvidia, deepinfra, sambanova, novita, friendli, nebius, poe, ollama_cloud, zai, zhipuai, minimax (anthropic-compatible), stepfun(+cn), siliconflow, volcengine, 302ai, venice, vercel | openai | env key | |
|
|
148
|
+
| alibaba (DashScope) | openai | env key | qwen |
|
|
149
|
+
| ollama, ollama_cn, lmstudio, vllm, llama_cpp, koboldcpp, textgen, gpt4all, openwebui | local | dummy key | OpenAI-compatible |
|
|
150
|
+
|
|
151
|
+
Model aliases ship as `provider/model` (e.g. `opencode/inkling-2-small-free`, `anthropic/claude-sonnet-5-5`) with real context/output limits and $/Mtok pricing from models.dev. 258 aliases in `src/config/default-models.ts` (generated). Users override via `models` in global/project config. Router tries primary → all credentialed providers on retryable errors (429/5xx/network); non-retryable 4xx fails fast.
|
|
152
|
+
|
|
153
|
+
### 6.1 Adapter interface
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
interface ProviderAdapter {
|
|
157
|
+
id: string;
|
|
158
|
+
capabilities: {
|
|
159
|
+
tools: boolean;
|
|
160
|
+
streaming: boolean;
|
|
161
|
+
vision: boolean;
|
|
162
|
+
audio: boolean;
|
|
163
|
+
video: boolean;
|
|
164
|
+
pdf: boolean;
|
|
165
|
+
reasoning: boolean;
|
|
166
|
+
promptCache: boolean;
|
|
167
|
+
embeddings: boolean;
|
|
168
|
+
};
|
|
169
|
+
chat(req: ChatRequest): AsyncIterable<ChatEvent>;
|
|
170
|
+
countTokens?(req: ChatRequest): Promise<number>;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
type WireProtocol =
|
|
174
|
+
| "openai-chat" // /v1/chat/completions
|
|
175
|
+
| "openai-responses" // /v1/responses
|
|
176
|
+
| "anthropic-messages"
|
|
177
|
+
| "gemini"
|
|
178
|
+
| "local"; // ollama / llama.cpp / lm studio
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### 6.2 Router policies
|
|
182
|
+
|
|
183
|
+
- **failover** — primary → secondary on 429/5xx/timeout
|
|
184
|
+
- **cost** — cheapest model meeting capability floor
|
|
185
|
+
- **latency** — fastest recent P50
|
|
186
|
+
- **quota** — route to account with remaining 5h/7d quota
|
|
187
|
+
- **capability** — vision/audio/long-context routing
|
|
188
|
+
- **task** — planner model vs executor model split (Reasonix pattern)
|
|
189
|
+
- **budget** — hard token/cost cap per session (`/autonomous` pattern from Prime Agent)
|
|
190
|
+
|
|
191
|
+
### 6.3 Security
|
|
192
|
+
|
|
193
|
+
- API keys never enter model context
|
|
194
|
+
- Credential broker with OAuth2/PKCE + encrypted vault (authsome pattern)
|
|
195
|
+
- Key redaction in logs and tool output (ThinkWatch pattern)
|
|
196
|
+
- Per-provider data-use flags (training allowed or not)
|
|
197
|
+
|
|
198
|
+
### 6.4 Config sketch (`xminal.toml`)
|
|
199
|
+
|
|
200
|
+
```toml
|
|
201
|
+
[provider]
|
|
202
|
+
default = "provider-a/fast-model"
|
|
203
|
+
planner = "provider-b/reasoning-model"
|
|
204
|
+
executor = "provider-a/fast-model"
|
|
205
|
+
fallback = ["provider-c/backup-model"]
|
|
206
|
+
|
|
207
|
+
[router]
|
|
208
|
+
policy = ["quota", "cost", "capability", "latency"]
|
|
209
|
+
|
|
210
|
+
[limits]
|
|
211
|
+
max_tokens_per_turn = 32000
|
|
212
|
+
max_cost_per_session = 2.00
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Default `defaultModel = "opencode/inkling-2-small-free"`; `fallbackModels = []`; resolution order = primary → fallbacks → credentialed providers.
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## 7. Agent runtime
|
|
220
|
+
|
|
221
|
+
### 7.1 Modes
|
|
222
|
+
|
|
223
|
+
| Mode | Access | Use |
|
|
224
|
+
|---|---|---|
|
|
225
|
+
| **Plan** | Read-only + analysis | Design, review, spec |
|
|
226
|
+
| **Build** | Full tools | Implementation |
|
|
227
|
+
| **Compose** | Multi-step workflow + hooks | Feature delivery |
|
|
228
|
+
| **Review** | Read-only + diff tools | Code review, verification |
|
|
229
|
+
| **Yolo** | Full access, no prompts | Sandbox/CI only |
|
|
230
|
+
|
|
231
|
+
Sources: OpenCode, Codewhale (Plan/Work/Operate), MiMo (Plan/Build/Compose), Smelt (Normal/Plan/Apply/Yolo).
|
|
232
|
+
|
|
233
|
+
### 7.2 Permission engine
|
|
234
|
+
|
|
235
|
+
- **Ask** — har destructive action pe prompt
|
|
236
|
+
- **Auto-Review** — risk score + rule engine; low-risk auto, high-risk prompt
|
|
237
|
+
- **Full Access** — no prompts (never default)
|
|
238
|
+
- Path/command allowlists; protected paths (`~/.ssh`, `.env`, secrets)
|
|
239
|
+
- Per-tool, per-session, per-project overrides
|
|
240
|
+
- Approval inbox for parallel agents (Calyx pattern)
|
|
241
|
+
|
|
242
|
+
### 7.3 Session model
|
|
243
|
+
|
|
244
|
+
- Append-only JSONL events
|
|
245
|
+
- Branching + resume + attach (Tau, rpi, Prime Agent)
|
|
246
|
+
- Per-turn snapshots for rewind (Reasonix, Codewhale `/undo`)
|
|
247
|
+
- Content-addressed blobs for file state
|
|
248
|
+
- CRDT-free merge for parallel worktrees (diff-based)
|
|
249
|
+
- Session browser + fuzzy search (showagent)
|
|
250
|
+
- Cross-agent transcript import (OpenWork, showagent)
|
|
251
|
+
|
|
252
|
+
### 7.4 Context engine
|
|
253
|
+
|
|
254
|
+
- Token budget per model
|
|
255
|
+
- Priority: system > current task > recent turns > retrieved memory > old history
|
|
256
|
+
- Pruning with cache-aware boundaries (Reasonix)
|
|
257
|
+
- Summaries: TurnMemory-style (Keen Code)
|
|
258
|
+
- File skeletons via tree-sitter (Maki)
|
|
259
|
+
- Output compression for shell/build/test (rtk)
|
|
260
|
+
- Content-hash-anchored edits (Hashline/OH-MY-PI)
|
|
261
|
+
- Retrieval: FTS5 + optional embeddings (Hermes, ContextStream)
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## 8. Tools catalog
|
|
266
|
+
|
|
267
|
+
### 8.1 Built-in tools
|
|
268
|
+
|
|
269
|
+
| Tool | Description | Source |
|
|
270
|
+
|---|---|---|
|
|
271
|
+
| `read` | File read with range + image/PDF | Pi, codehamr |
|
|
272
|
+
| `write` | Create/overwrite with diff preview | codehamr |
|
|
273
|
+
| `edit` | Hash-anchored patch/line edit | OH-MY-PI, Pi |
|
|
274
|
+
| `multi_edit` | Multiple edits atomically | Plandex |
|
|
275
|
+
| `bash` | Shell exec with safety checks + timeout | OpenCode, VT Code |
|
|
276
|
+
| `bash_builtin` | In-process rg/find/sed/jq/head/tail | OH-MY-PI |
|
|
277
|
+
| `search` | ripgrep + glob + fuzzy | OpenCode, Maki |
|
|
278
|
+
| `code_index` | Tree-sitter symbols/skeletons | Maki, Moltis |
|
|
279
|
+
| `lsp` | 14 LSP ops (diagnostics, hover, refs, rename) | OH-MY-PI, OpenCode |
|
|
280
|
+
| `dap` | 28 debug ops (breakpoints, step, eval) | OH-MY-PI, Grinta |
|
|
281
|
+
| `browser` | Real logged-in browser via extension/MCP | Browse, BrowserSkill |
|
|
282
|
+
| `web_search` | Search + fetch + cite | Agent Code, gptme |
|
|
283
|
+
| `todo` | Task list with dependencies | Task Master, ralph-tui |
|
|
284
|
+
| `subagent` | Spawn isolated agent | OpenCode, Deep Agents |
|
|
285
|
+
| `worktree` | Create/merge isolated worktree | Orca, Rove |
|
|
286
|
+
| `memory` | Read/write long-term memory | Hermes, pi-mem |
|
|
287
|
+
| `beads` | Issue graph claim/update | Beads |
|
|
288
|
+
| `git` | status/diff/log/commit/branch | GitClaw, AgentPlane |
|
|
289
|
+
| `verify` | Run tests/lint/typecheck gates | Grinta, SWE-agent |
|
|
290
|
+
|
|
291
|
+
### 8.2 Tool safety
|
|
292
|
+
|
|
293
|
+
- Command allow/deny lists
|
|
294
|
+
- Destructive command detection (`rm -rf`, `git reset --hard`, force push)
|
|
295
|
+
- Network egress policy
|
|
296
|
+
- Sandbox required for Yolo/autonomous modes
|
|
297
|
+
- Output size caps + truncation with full log reference (rtk)
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
## 9. Memory & knowledge
|
|
302
|
+
|
|
303
|
+
| Layer | Storage | Purpose | Source |
|
|
304
|
+
|---|---|---|---|
|
|
305
|
+
| Session | JSONL + SQLite index | Resume/branch/search | Tau, rpi |
|
|
306
|
+
| Working memory | In-context | Current task | — |
|
|
307
|
+
| Long-term memory | Markdown files + FTS5 | Preferences, lessons, decisions | pi-mem, Hermes |
|
|
308
|
+
| Codebase wiki | Markdown generated | Architecture docs | OpenWiki |
|
|
309
|
+
| Code index | SQLite + tree-sitter | Symbol search, skeletons | Maki, Moltis |
|
|
310
|
+
| Issue graph | SQLite (optional Dolt) | Long-horizon task tracking | Beads |
|
|
311
|
+
| Cross-session | MCP server | Shared decisions/lessons | ContextStream |
|
|
312
|
+
| Provenance | Git notes/refs | Who wrote which line | AgentDiff |
|
|
313
|
+
|
|
314
|
+
Memory lifecycle:
|
|
315
|
+
|
|
316
|
+
- **Write**: after task completion, reflection pass extracts lessons (pi-reflect)
|
|
317
|
+
- **Update**: `/refine` evidence-backed updates (Prime Agent)
|
|
318
|
+
- **Forget**: TTL + relevance decay + manual prune
|
|
319
|
+
- **Export/import**: Markdown + JSON for portability
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## 10. Orchestration
|
|
324
|
+
|
|
325
|
+
### 10.1 Levels
|
|
326
|
+
|
|
327
|
+
| Level | Mechanism | Source |
|
|
328
|
+
|---|---|---|
|
|
329
|
+
| L0 | Single agent | codehamr, Pi |
|
|
330
|
+
| L1 | Subagents (planner/coder/explorer/reviewer) | OpenCode, Kimi, Deep Agents |
|
|
331
|
+
| L2 | Parallel worktrees | Orca, wmux, Rove, amux |
|
|
332
|
+
| L3 | Ralph loops (fresh context, verify, retry) | ralph family, LoopTroop |
|
|
333
|
+
| L4 | LLM Council (multi-model planning) | LoopTroop |
|
|
334
|
+
| L5 | Swarm with conflict detection | jcode, Ruflo, DeerFlow |
|
|
335
|
+
|
|
336
|
+
### 10.2 Ralph loop contract
|
|
337
|
+
|
|
338
|
+
```
|
|
339
|
+
spec → plan → implement → verify → (pass? done : fresh context retry)
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
- Hard iteration cap
|
|
343
|
+
- Time cap
|
|
344
|
+
- Budget cap
|
|
345
|
+
- Independent verifier (different model optional)
|
|
346
|
+
- Artifacts: plan.md, task list, test report, diff
|
|
347
|
+
|
|
348
|
+
### 10.3 Worktree orchestrator
|
|
349
|
+
|
|
350
|
+
- One task = one worktree + branch
|
|
351
|
+
- Auto-merge only with confirmation or clean fast-forward
|
|
352
|
+
- Hunk-level diff adoption (wmux)
|
|
353
|
+
- Conflict detection: alert peers when a file changes (jcode, Concord)
|
|
354
|
+
- SSH-resilient session (Rove)
|
|
355
|
+
- Kanban view (Nimbalyst, amux)
|
|
356
|
+
|
|
357
|
+
### 10.4 External agent integration
|
|
358
|
+
|
|
359
|
+
Run existing agents as workers, not competitors:
|
|
360
|
+
|
|
361
|
+
- Claude Code, Codex, Gemini CLI, OpenCode, Pi, Aider via PTY/ACP
|
|
362
|
+
- ACP is the preferred structured channel
|
|
363
|
+
- MCP is the preferred tool/data channel
|
|
364
|
+
- Per-session MCP toggles (agent-deck)
|
|
365
|
+
|
|
366
|
+
---
|
|
367
|
+
|
|
368
|
+
## 11. Security, sandbox, audit
|
|
369
|
+
|
|
370
|
+
| Control | Implementation | Source |
|
|
371
|
+
|---|---|---|
|
|
372
|
+
| Sandbox | bubblewrap (Linux), seatbelt (macOS), Docker/Podman, micro-VM optional | Codewhale, Pi, AgentBox |
|
|
373
|
+
| Secrets | Encrypted vault; inject at request time; no raw keys in prompts | authsome, ThinkWatch |
|
|
374
|
+
| Egress | Domain allowlist/denylist; block metadata endpoints | DvalinCode |
|
|
375
|
+
| Filesystem | Project-scoped; block `~/.ssh`, `.aws`, `.env`, keychains | Codewhale |
|
|
376
|
+
| Audit | Hash-chained JSONL of every action | DvalinCode, GitClaw |
|
|
377
|
+
| Provenance | Git notes per line/commit with agent + prompt hash | AgentDiff |
|
|
378
|
+
| Observability | eBPF trace (optional), token/cost/tool metrics | AgentSight, Trae |
|
|
379
|
+
| Approvals | Risk-scored; inbox for parallel agents | Calyx, Codewhale |
|
|
380
|
+
| Prompt injection | Tool output sanitization; untrusted-content taint tracking | — |
|
|
381
|
+
|
|
382
|
+
**Default posture:** sandbox ON for autonomous modes; Ask permissions for manual mode; Full Access only with explicit flag + warning.
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
## 12. TUI / UX
|
|
387
|
+
|
|
388
|
+
### Layout
|
|
389
|
+
|
|
390
|
+
```
|
|
391
|
+
┌─ xminal ────────────────────────────────────────────── model · mode · $cost ─┐
|
|
392
|
+
│ Session: feature-auth-oauth Branch: main · WT: task-42 │
|
|
393
|
+
├───────────────────────────────────────────────┬──────────────────────────┤
|
|
394
|
+
│ Chat / agent transcript │ Context / files │
|
|
395
|
+
│ │ ▸ src/auth.ts │
|
|
396
|
+
│ ❯ add OAuth PKCE flow │ ▸ tests/auth.spec.ts │
|
|
397
|
+
│ ● plan ... │ │
|
|
398
|
+
│ ● read src/auth.ts │ Tasks │
|
|
399
|
+
│ ● edit src/auth.ts (+42 −7) │ ☐ schema │
|
|
400
|
+
│ ● test → pass │ ☐ provider │
|
|
401
|
+
│ │ ☑ callback │
|
|
402
|
+
├───────────────────────────────────────────────┴──────────────────────────┤
|
|
403
|
+
│ Diff preview / approval prompt / command palette │
|
|
404
|
+
├───────────────────────────────────────────────────────────────────────────┤
|
|
405
|
+
│ ↑↓ scroll · Tab pane · Ctrl+K commands · Ctrl+P plan · Ctrl+D diff │
|
|
406
|
+
└───────────────────────────────────────────────────────────────────────────┘
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
### UX features
|
|
410
|
+
|
|
411
|
+
- Command palette + slash commands (`/plan`, `/build`, `/undo`, `/rewind`, `/diff`, `/receipts`, `/mcp`, `/skills`, `/beads`, `/mode`, `/model`, `/cost`)
|
|
412
|
+
- Inline diff review with accept/reject per hunk (Calyx, Plandex)
|
|
413
|
+
- Streaming tool traces with collapsible detail (Keen Code style summaries)
|
|
414
|
+
- Image/LaTeX inline rendering (jcode)
|
|
415
|
+
- Session browser + fuzzy search (showagent)
|
|
416
|
+
- Kanban dashboard (Nimbalyst, CliDeck)
|
|
417
|
+
- Onboarding wizard (OpenClaw)
|
|
418
|
+
- `xminal doctor` diagnostics (Claw Code, Grinta)
|
|
419
|
+
- Vim keys optional (Smelt)
|
|
420
|
+
- Themes + accessibility
|
|
421
|
+
|
|
422
|
+
---
|
|
423
|
+
|
|
424
|
+
## 13. Interop & bridges
|
|
425
|
+
|
|
426
|
+
| Protocol/Channel | Direction | Source |
|
|
427
|
+
|---|---|---|
|
|
428
|
+
| MCP client | xminal → external tools | OpenCode, openHarness |
|
|
429
|
+
| MCP server | external agents → xminal memory/tools | ContextStream, Beads |
|
|
430
|
+
| ACP client | xminal → external agents | Martty, OpenHands |
|
|
431
|
+
| ACP server | editors → xminal | Hermes, Codewhale, Kimi |
|
|
432
|
+
| LSP | xminal → language servers | OpenCode, OH-MY-PI |
|
|
433
|
+
| DAP | xminal → debuggers | OH-MY-PI, Grinta |
|
|
434
|
+
| HTTP/WS | xminal server API | OpenHands SDK, AgenC |
|
|
435
|
+
| Telegram | remote control + approvals | Untether, 5dive |
|
|
436
|
+
| Slack/Discord/WhatsApp | notifications + triggers | OpenClaw, NullClaw |
|
|
437
|
+
| GitHub Actions | CI agent workflows | gh-aw |
|
|
438
|
+
| Webhooks | Slack/Linear/GitHub triggers | Open SWE, OpenHands |
|
|
439
|
+
|
|
440
|
+
---
|
|
441
|
+
|
|
442
|
+
## 14. Config, state, storage
|
|
443
|
+
|
|
444
|
+
```
|
|
445
|
+
~/.xminal/ # global
|
|
446
|
+
├── config.toml # providers, router, limits, UI
|
|
447
|
+
├── profiles/ # named provider/account profiles
|
|
448
|
+
├── skills/ # user skills
|
|
449
|
+
├── plugins/ # user plugins
|
|
450
|
+
├── memory/ # global markdown memory
|
|
451
|
+
├── cache/ # models, indexes, downloads
|
|
452
|
+
└── logs/ # audit, receipts, cost
|
|
453
|
+
|
|
454
|
+
<project>/.xminal/ # project-local
|
|
455
|
+
├── config.toml # overrides
|
|
456
|
+
├── AGENTS.md # project rules (synced)
|
|
457
|
+
├── sessions/ # JSONL + index
|
|
458
|
+
├── memory/ # project memory
|
|
459
|
+
├── wiki/ # generated codebase docs
|
|
460
|
+
├── beads.db # issue graph
|
|
461
|
+
├── snapshots/ # content-addressed file states
|
|
462
|
+
└── receipts/ # audit trails
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
- Config precedence: CLI flags > env > project > global > defaults
|
|
466
|
+
- `xminal init` scaffolds `.xminal/` and `AGENTS.md`
|
|
467
|
+
- Import from Claude Code/OpenCode/Codex sessions
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## 15. Roadmap (milestones + acceptance criteria)
|
|
472
|
+
|
|
473
|
+
### v0.1 — Walking skeleton (2–3 weeks)
|
|
474
|
+
- [x] Scaffold + build (tsc) + npm pack
|
|
475
|
+
- [x] REPL shell + slash commands (TUI-lite; Ink TUI deferred)
|
|
476
|
+
- [x] 3 native-capable adapters + OpenAI-compatible adapter (47 providers)
|
|
477
|
+
- [x] Tools: read/write/edit/bash/glob/grep/list/todo/memory/skills/checkpoint/git/worktree/verify/web/diagnostics/mcp/subagent
|
|
478
|
+
- [x] Session JSONL + resume + branch + checkpoints
|
|
479
|
+
- [x] Permission engine (Ask/Auto/Full) + protected paths + hash-chained audit
|
|
480
|
+
- **AC:** `xminal` starts, reads a repo, makes a file edit, tests pass, session resumes.
|
|
481
|
+
|
|
482
|
+
### v0.2 — Daily driver (3–4 weeks)
|
|
483
|
+
- [x] Provider router + failover + cost tracking
|
|
484
|
+
- [x] Plan/Build/Compose/Review/YOLO modes
|
|
485
|
+
- [x] MCP client (stdio; server side deferred)
|
|
486
|
+
- [ ] LSP diagnostics (diagnostics tool added; language servers not wired)
|
|
487
|
+
- [ ] Diff preview + approval
|
|
488
|
+
- [ ] `xminal doctor`, onboarding wizard
|
|
489
|
+
- [ ] Global/project config + profiles
|
|
490
|
+
- **AC:** works on a real repo; plan mode never writes; MCP server connects.
|
|
491
|
+
|
|
492
|
+
### v0.3 — Memory + safety (3–4 weeks)
|
|
493
|
+
- [ ] FTS5 session search
|
|
494
|
+
- [ ] Markdown memory + write/update/forget
|
|
495
|
+
- [ ] Codebase index (tree-sitter) + wiki
|
|
496
|
+
- [ ] Sandbox backends + protected paths
|
|
497
|
+
- [ ] Secrets broker + redaction
|
|
498
|
+
- [ ] Checkpoints/rewind/undo + receipts
|
|
499
|
+
- **AC:** rewind restores exact state; secrets never appear in transcripts; sandbox blocks egress.
|
|
500
|
+
|
|
501
|
+
### v0.4 — Orchestration (4–5 weeks)
|
|
502
|
+
- [ ] Subagents (explore/plan/code/review)
|
|
503
|
+
- [ ] Worktree orchestrator + Kanban
|
|
504
|
+
- [ ] Ralph loop engine + verification gates
|
|
505
|
+
- [ ] Task graph (PRD → tasks → beads)
|
|
506
|
+
- [ ] Parallel fan-out (1 prompt → N tasks)
|
|
507
|
+
- **AC:** 3 tasks run in parallel worktrees; conflicting file alerts; loop stops at cap.
|
|
508
|
+
|
|
509
|
+
### v0.5 — Skills + plugins (3–4 weeks)
|
|
510
|
+
- [ ] SKILL.md loader + registry
|
|
511
|
+
- [ ] Hooks (pre/post tool, session start/end)
|
|
512
|
+
- [ ] Lua plugin host (Smelt pattern)
|
|
513
|
+
- [ ] Bundled packs: spec, TDD, review, security, compliance
|
|
514
|
+
- [ ] Skill benchmark harness
|
|
515
|
+
- **AC:** third-party skill installs and runs; hooks enforce policy.
|
|
516
|
+
|
|
517
|
+
### v0.6 — Interop + remote (3–4 weeks)
|
|
518
|
+
- [ ] ACP client/server
|
|
519
|
+
- [ ] Browser tool (real logged-in browser)
|
|
520
|
+
- [ ] Telegram bridge + approvals
|
|
521
|
+
- [ ] HTTP/WS server + SDK
|
|
522
|
+
- [ ] Session browser + import from other agents
|
|
523
|
+
- **AC:** xminal controlled from Telegram; external Claude Code runs as worker; editor connects via ACP.
|
|
524
|
+
|
|
525
|
+
### v0.7 — Hardening + evals (3–4 weeks)
|
|
526
|
+
- [ ] SWE-bench harness
|
|
527
|
+
- [ ] Tool-safety test suite
|
|
528
|
+
- [ ] Provider contract tests
|
|
529
|
+
- [ ] Performance: startup <150ms, RAM <150MB idle
|
|
530
|
+
- [ ] Audit/provenance reports
|
|
531
|
+
- **AC:** benchmark score recorded; all safety tests pass.
|
|
532
|
+
|
|
533
|
+
### v1.0 — Release
|
|
534
|
+
- [ ] Packaging: npm, standalone binaries (linux-x64/arm64, macOS, Windows), Termux script
|
|
535
|
+
- [ ] Docs + migration guides
|
|
536
|
+
- [ ] Stable plugin/skill API
|
|
537
|
+
- **AC:** install on Android/Termux and desktop; upgrade path works.
|
|
538
|
+
|
|
539
|
+
### v1.x — Beyond
|
|
540
|
+
- Swarms, council planning, self-improvement, cloud sandboxes, mobile app, compliance packs, marketplace.
|
|
541
|
+
|
|
542
|
+
---
|
|
543
|
+
|
|
544
|
+
## 16. Testing & evaluation
|
|
545
|
+
|
|
546
|
+
| Type | Scope | Tool |
|
|
547
|
+
|---|---|---|
|
|
548
|
+
| Unit | core loop, permissions, router | Vitest/Bun test |
|
|
549
|
+
| Integration | provider adapters against mocks + live smoke | contract tests |
|
|
550
|
+
| Golden sessions | replay JSONL, assert diffs | custom harness |
|
|
551
|
+
| Tool safety | destructive commands, path escapes, egress | adversarial suite |
|
|
552
|
+
| TUI | snapshot rendering | custom |
|
|
553
|
+
| Eval | SWE-bench Verified / Lite | mini-swe-agent harness |
|
|
554
|
+
| Skill eval | SKILL.md pass rate across models | skill-optimizer pattern |
|
|
555
|
+
| Performance | startup, RAM, tokens/turn | benchmarks in CI |
|
|
556
|
+
|
|
557
|
+
**CI gates:** lint, typecheck, unit, integration-mock, safety. Live-model tests nightly with budget cap.
|
|
558
|
+
|
|
559
|
+
---
|
|
560
|
+
|
|
561
|
+
## 17. Packaging & distribution
|
|
562
|
+
|
|
563
|
+
- npm: `npm i -g xminal`
|
|
564
|
+
- Standalone: Bun compile or pkg → `xminal-linux-x64`, `xminal-linux-arm64`, `xminal-darwin-*`, `xminal-win-*`
|
|
565
|
+
- Termux: `scripts/install-termux.sh` (Node/Bun + binary)
|
|
566
|
+
- Docker image: `ghcr.io/<org>/xminal`
|
|
567
|
+
- Update channel: signed manifests + checksums
|
|
568
|
+
- Config migration: versioned schema
|
|
569
|
+
|
|
570
|
+
---
|
|
571
|
+
|
|
572
|
+
## 18. Risks & mitigations
|
|
573
|
+
|
|
574
|
+
| Risk | Impact | Mitigation |
|
|
575
|
+
|---|---|---|
|
|
576
|
+
| Scope explosion (125 features) | Never ships | Tiers + plugin architecture; v1 core only |
|
|
577
|
+
| Source list inaccuracies (stars/links/licenses) | Legal/technical | Verify every repo before borrowing; keep attribution file |
|
|
578
|
+
| Provider API drift | Breakage | Adapter contract tests; nightly smoke |
|
|
579
|
+
| Context limits | Bad quality | Pruning + retrieval + compression + planner/executor split |
|
|
580
|
+
| Sandbox escape | Security | Default sandbox; no network in Yolo; audit |
|
|
581
|
+
| Prompt injection via tool output | Data exfiltration | Taint tracking, output sanitization, egress policy |
|
|
582
|
+
| Windows/Termux portability | Adoption | CI matrix; pure-JS fallbacks; ARM64 builds |
|
|
583
|
+
| Performance | UX | Native addons (rg/tree-sitter/PTY); lazy loading |
|
|
584
|
+
| Upstream license changes | Legal | Pin versions; vendor critical MIT code |
|
|
585
|
+
| Ad model / branding confusion | Product | Decide business model separately; MIT core |
|
|
586
|
+
|
|
587
|
+
---
|
|
588
|
+
|
|
589
|
+
## 19. Open decisions (need user input)
|
|
590
|
+
|
|
591
|
+
1. **Providers** — DONE (default opencode; 47 providers + 258 model aliases baked in). User said they'll finalize/update later; Bedrock/Vertex/Azure need native adapters — not built yet.
|
|
592
|
+
2. **Stack** — confirm TypeScript/Bun vs Rust/Go.
|
|
593
|
+
3. **Platform priority** — Termux/Android first, desktop first, or both?
|
|
594
|
+
4. **Base strategy** — greenfield vs fork OpenCode vs fork Pi. Recommendation: greenfield core, borrow Pi TUI/provider design, integrate others.
|
|
595
|
+
5. **Name/brand** — `xminal` internal, final name?
|
|
596
|
+
6. **Business model** — MIT + ads (Freebuff style), open-core, or pure OSS?
|
|
597
|
+
7. **Team/time budget** — solo/team, hours per week; roadmap will rescale.
|
|
598
|
+
8. **Must-have integrations** — Claude Code, Codex, Gemini CLI, OpenCode, Aider?
|
|
599
|
+
|
|
600
|
+
---
|
|
601
|
+
|
|
602
|
+
## 20. Immediate next steps
|
|
603
|
+
|
|
604
|
+
1. User adjusts provider list later (Bedrock/Vertex/Azure native adapters are the likely gaps).
|
|
605
|
+
2. Live smoke against real credentials once user adds a key (opencode free tier currently returns 429 FreeUsageLimitError; local ollama/lmstudio not running).
|
|
606
|
+
3. README + release packaging (npm publish needs user's explicit approval).
|
|
607
|
+
4. v0.2: LSP diagnostics, Ink TUI, MCP server, Telegram live test.
|
|
608
|
+
|
|
609
|
+
---
|
|
610
|
+
|
|
611
|
+
## Appendix A — Feature coverage
|
|
612
|
+
|
|
613
|
+
- **125/125 projects** mapped in `FEATURE_MATRIX.md`
|
|
614
|
+
- 4 ecosystem layers covered
|
|
615
|
+
- 11 flagship deep-dives incorporated (Hermes, OpenCode, Claw Code, Pi, Orca, OpenHands, Codewhale, OH-MY-PI, Reasonix, Prime Agent, jcode)
|
|
616
|
+
|
|
617
|
+
## Appendix B — Attribution
|
|
618
|
+
|
|
619
|
+
All borrowed code/skills must retain original MIT copyright notices. Maintain `THIRD_PARTY_NOTICES.md` with repo URL, commit, license, and files used.
|