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.
Files changed (127) hide show
  1. package/AGENTS.md +16 -0
  2. package/CHANGELOG.md +82 -0
  3. package/EXECUTION-PLAN.md +135 -0
  4. package/FEATURE_MATRIX.md +173 -0
  5. package/LICENSE +21 -0
  6. package/PLAN.md +619 -0
  7. package/README.md +133 -2
  8. package/SECURITY.md +34 -0
  9. package/assets/logo.svg +26 -0
  10. package/dist/bridges/telegram.js +192 -0
  11. package/dist/bridges/telegram.js.map +1 -0
  12. package/dist/cli/args.js +156 -0
  13. package/dist/cli/args.js.map +1 -0
  14. package/dist/cli/audit.js +38 -0
  15. package/dist/cli/audit.js.map +1 -0
  16. package/dist/cli/callbacks.js +14 -0
  17. package/dist/cli/callbacks.js.map +1 -0
  18. package/dist/cli/commands.js +534 -0
  19. package/dist/cli/commands.js.map +1 -0
  20. package/dist/cli/render.js +142 -0
  21. package/dist/cli/render.js.map +1 -0
  22. package/dist/cli/repl.js +161 -0
  23. package/dist/cli/repl.js.map +1 -0
  24. package/dist/config/config.js +244 -0
  25. package/dist/config/config.js.map +1 -0
  26. package/dist/config/default-models.js +264 -0
  27. package/dist/config/default-models.js.map +1 -0
  28. package/dist/config/doctor.js +100 -0
  29. package/dist/config/doctor.js.map +1 -0
  30. package/dist/config/paths.js +52 -0
  31. package/dist/config/paths.js.map +1 -0
  32. package/dist/config/provider-defaults.js +50 -0
  33. package/dist/config/provider-defaults.js.map +1 -0
  34. package/dist/config/types.js +3 -0
  35. package/dist/config/types.js.map +1 -0
  36. package/dist/core/agent.js +394 -0
  37. package/dist/core/agent.js.map +1 -0
  38. package/dist/core/cost.js +40 -0
  39. package/dist/core/cost.js.map +1 -0
  40. package/dist/core/permissions.js +218 -0
  41. package/dist/core/permissions.js.map +1 -0
  42. package/dist/core/session.js +248 -0
  43. package/dist/core/session.js.map +1 -0
  44. package/dist/core/tool-usage.js +92 -0
  45. package/dist/core/tool-usage.js.map +1 -0
  46. package/dist/index.js +496 -0
  47. package/dist/index.js.map +1 -0
  48. package/dist/mcp/client.js +177 -0
  49. package/dist/mcp/client.js.map +1 -0
  50. package/dist/mcp/server.js +112 -0
  51. package/dist/mcp/server.js.map +1 -0
  52. package/dist/memory/store.js +140 -0
  53. package/dist/memory/store.js.map +1 -0
  54. package/dist/orchestration/ralph.js +42 -0
  55. package/dist/orchestration/ralph.js.map +1 -0
  56. package/dist/providers/anthropic.js +192 -0
  57. package/dist/providers/anthropic.js.map +1 -0
  58. package/dist/providers/gemini.js +162 -0
  59. package/dist/providers/gemini.js.map +1 -0
  60. package/dist/providers/openai.js +140 -0
  61. package/dist/providers/openai.js.map +1 -0
  62. package/dist/providers/router.js +100 -0
  63. package/dist/providers/router.js.map +1 -0
  64. package/dist/providers/sse.js +61 -0
  65. package/dist/providers/sse.js.map +1 -0
  66. package/dist/providers/types.js +15 -0
  67. package/dist/providers/types.js.map +1 -0
  68. package/dist/runtime.js +89 -0
  69. package/dist/runtime.js.map +1 -0
  70. package/dist/server/http.js +263 -0
  71. package/dist/server/http.js.map +1 -0
  72. package/dist/server/web.js +117 -0
  73. package/dist/server/web.js.map +1 -0
  74. package/dist/skills/install.js +50 -0
  75. package/dist/skills/install.js.map +1 -0
  76. package/dist/skills/loader.js +145 -0
  77. package/dist/skills/loader.js.map +1 -0
  78. package/dist/tools/agent-tools.js +59 -0
  79. package/dist/tools/agent-tools.js.map +1 -0
  80. package/dist/tools/bash-tool.js +145 -0
  81. package/dist/tools/bash-tool.js.map +1 -0
  82. package/dist/tools/checkpoint-tool.js +49 -0
  83. package/dist/tools/checkpoint-tool.js.map +1 -0
  84. package/dist/tools/diagnostics-tool.js +56 -0
  85. package/dist/tools/diagnostics-tool.js.map +1 -0
  86. package/dist/tools/fs-tools.js +339 -0
  87. package/dist/tools/fs-tools.js.map +1 -0
  88. package/dist/tools/git-tool.js +99 -0
  89. package/dist/tools/git-tool.js.map +1 -0
  90. package/dist/tools/index.js +34 -0
  91. package/dist/tools/index.js.map +1 -0
  92. package/dist/tools/mcp-tool.js +91 -0
  93. package/dist/tools/mcp-tool.js.map +1 -0
  94. package/dist/tools/memory-tool.js +54 -0
  95. package/dist/tools/memory-tool.js.map +1 -0
  96. package/dist/tools/registry.js +47 -0
  97. package/dist/tools/registry.js.map +1 -0
  98. package/dist/tools/skill-tool.js +36 -0
  99. package/dist/tools/skill-tool.js.map +1 -0
  100. package/dist/tools/todo-tool.js +104 -0
  101. package/dist/tools/todo-tool.js.map +1 -0
  102. package/dist/tools/types.js +40 -0
  103. package/dist/tools/types.js.map +1 -0
  104. package/dist/tools/verify-tool.js +74 -0
  105. package/dist/tools/verify-tool.js.map +1 -0
  106. package/dist/tools/web-tool.js +113 -0
  107. package/dist/tools/web-tool.js.map +1 -0
  108. package/dist/tools/worktree-tool.js +83 -0
  109. package/dist/tools/worktree-tool.js.map +1 -0
  110. package/dist/util/ansi.js +78 -0
  111. package/dist/util/ansi.js.map +1 -0
  112. package/dist/util/diff.js +50 -0
  113. package/dist/util/diff.js.map +1 -0
  114. package/dist/util/fs.js +132 -0
  115. package/dist/util/fs.js.map +1 -0
  116. package/dist/util/glob.js +47 -0
  117. package/dist/util/glob.js.map +1 -0
  118. package/dist/util/log.js +32 -0
  119. package/dist/util/log.js.map +1 -0
  120. package/dist/util/redact.js +34 -0
  121. package/dist/util/redact.js.map +1 -0
  122. package/dist/version.js +8 -0
  123. package/dist/version.js.map +1 -0
  124. package/package.json +59 -4
  125. package/scripts/install.sh +33 -0
  126. package/scripts/prepare.cjs +23 -0
  127. 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.