feat: confucius-aligned agent stack

.github/workflows/ci.yml

@@ -8,11 +8,19 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
-
+    runs-on: ${{ matrix.runner }}
     strategy:
+      fail-fast: false
       matrix:
-        node-version: [18.x, 20.x, 22.x]
+        include:
+          - runner: ubuntu-latest
+            node-version: 18.x
+          - runner: ubuntu-latest
+            node-version: 20.x
+          - runner: ubuntu-latest
+            node-version: 22.x
+          - runner: ubuntu-24.04-arm
+            node-version: 20.x
 
     steps:
       - name: Checkout repository
@@ -39,6 +47,9 @@ jobs:
         run: pnpm test
         continue-on-error: true
 
+      - name: Security audit
+        run: pnpm audit --audit-level=high
+
   lint:
     runs-on: ubuntu-latest
 

DOCS.md

@@ -21,7 +21,8 @@ Version: **0.6.1**
 7. [Memory System](#memory-system)
 8. [Provider Recipes](#provider-recipes)
 9. [Sandbox / CI Usage](#sandbox--ci-usage)
-10. [Tips & Tricks](#tips--tricks)
+10. [Platforms and devices](#platforms-and-devices)
+11. [Tips & Tricks](#tips--tricks)
 
 ---
 
@@ -92,6 +93,18 @@ Verify config:
 xibecode config --show
 ```
 
+### Cost-saving (economy) mode
+
+Reduce API cost by using a cheaper/smaller model and lower iteration and token caps:
+
+```bash
+xibecode config --set-cost-mode economy
+xibecode config --set-economy-model claude-haiku-4-5-20251015
+```
+
+- **Economy mode**: When enabled, `run`, `run-pr`, and `chat` use the economy model (if set) and cap max iterations at the economy limit (default 50). Use for high-volume or non-critical runs.
+- **Per-command override**: `xibecode run --cost-mode economy "task"` or `xibecode run-pr --cost-mode normal "task"` to override config for one run.
+
 ---
 
 ## Commands Reference
@@ -119,6 +132,9 @@ xibecode run "Preview only" --dry-run
 | `--provider <provider>` | `anthropic` or `openai` |
 | `-d, --max-iterations <n>` | Max agent iterations (default: `150`, `0` = unlimited) |
 | `-v, --verbose` | Show detailed tool call logs |
+| `--cost-mode <mode>` | `normal` or `economy` (cheaper model, lower iteration cap) |
+| `--plan-first` | Force a strategic plan (one-shot, no tools) before execution (AX-lite) |
+| `--mindset-adaptive` | Enable CoM-style reasoning mindsets (convergent/divergent/algorithmic) |
 | `--dry-run` | Preview changes without writing |
 | `--changed-only` | Focus only on git-changed files |
 | `--non-interactive` | Suppress auto-exit (for programmatic embedding) |
@@ -169,6 +185,9 @@ prompt
 | `--provider <provider>` | `anthropic` or `openai` |
 | `-d, --max-iterations <n>` | Max iterations (default: `150`) |
 | `-v, --verbose` | Show detailed logs including git operations |
+| `--cost-mode <mode>` | `normal` or `economy` (cheaper model, lower caps) |
+| `--plan-first` | Force a strategic plan before execution (AX-lite) |
+| `--mindset-adaptive` | Enable CoM-style reasoning mindsets |
 | `--branch <name>` | Override auto-generated branch name |
 | `--title <title>` | Override PR title |
 | `--draft` | Open PR as draft |
@@ -389,6 +408,22 @@ Or add directly to `.xibecode/memory.md`:
 - Run `pnpm test` to execute the test suite
 ```
 
+### Session memory (this run)
+
+Within a single `run` or `run-pr`, the agent keeps **session memory**: tool attempts, failures, and learnings. A compact summary is injected into the system prompt so the agent avoids repeating the same mistakes. Session data is persisted under `.xibecode/sessions/` and recent learnings can be loaded into the next run.
+
+### Context pruning
+
+Before each run, the CLI scores project files by relevance to the task (keyword match). The top N file paths are suggested to the agent so it can prioritize `get_context` and `read_file`. This reduces noise and token use on large repos.
+
+- **Config**: `maxContextFiles` (default `40`). Set to `0` to disable (edit config file or use `config.set('maxContextFiles', 0)`).
+
+### Multi-model routing
+
+You can use a different model for strategic (planning) vs tactical/operational (execution) steps. Set `planningModel` and/or `executionModel` in config. When `--plan-first` is used, the strategic plan uses `planningModel` if set; the rest of the run uses `executionModel` if set, otherwise the default `model`.
+- **Behavior**: Keyword-based scoring; extensions include `.ts`, `.tsx`, `.js`, `.py`, `.go`, `.md`, etc. `node_modules`, `.git`, `dist` are ignored.
+- **PKG-style (optional)**: Set `usePkgStyleContext: true` in config to augment with AST/code-graph relevance (TypeScript/JavaScript). Helps on large codebases.
+
 ---
 
 ## Provider Recipes
@@ -488,6 +523,28 @@ xibecode run "your task"
     xibecode run-pr "Fix all TypeScript type errors" --skip-tests
 ```
 
+### Agent-triggered execution and safety
+
+Agent-triggered shell commands (`run_command`) run with the **same user and privileges** as the XibeCode process. There is no sudo or elevation. For untrusted code or third-party repos, run XibeCode inside a **container or sandbox** (e.g. Docker, E2B, or a disposable VM).
+
+- **Path and URL validation**: File paths used by tools are resolved under the working directory; paths that escape it (e.g. `../etc/passwd`) are rejected. The `fetch_url` tool only allows `http`/`https` URLs and blocks local/private addresses by default to reduce SSRF risk.
+- **Blocked commands**: The built-in safety layer blocks obviously dangerous commands (e.g. `rm -rf /`, fork bombs). See `SECURITY.md` and `src/utils/safety.ts` for details.
+
+---
+
+## Platforms and devices
+
+XibeCode is built to run across common platforms and device types.
+
+| Surface | Platforms | Notes |
+|--------|------------|--------|
+| **CLI** | Linux (x64, ARM64), macOS (Intel, Apple Silicon), Windows (x64, ARM64) | Node.js 18+. ARM64 includes Raspberry Pi and ARM servers. |
+| **WebUI** | Any browser | Responsive, mobile-friendly layout; touch-friendly. Optional PWA/installable. |
+| **Desktop (Electron)** | Windows (x64/ARM64), macOS (Intel/Apple Silicon), Linux (x64/ARM64) | Download from [Releases](https://github.com/iotserver24/xibecode/releases). AppImage/deb for arm64 on Linux. |
+| **Headless / embedded** | Servers, Docker, Raspberry Pi | Use `xibecode run` or `xibecode run-pr` with env-based config (e.g. `ANTHROPIC_API_KEY`, `xibecode config`). No TUI required; suitable for CI, cron, or an agent daemon. |
+
+CI runs on Linux x64 and ARM64 (where available) to validate the CLI. For headless usage, set your API key and endpoint via environment or config, then run tasks non-interactively.
+
 ---
 
 ## Tips & Tricks

README.md

@@ -146,6 +146,8 @@ npm link
 - Node.js 18+
 - API key from Anthropic or OpenAI
 
+**Platforms:** CLI and WebUI run on Linux (x64, ARM64), macOS (Intel, Apple Silicon), and Windows. For servers, Docker, or Raspberry Pi, use headless runs: `xibecode run` / `xibecode run-pr` with env-based config (no TUI). See [DOCS.md](DOCS.md#platforms-and-devices) for the full device matrix.
+
 ## Quick Start
 
 ```bash
@@ -211,6 +213,7 @@ Options:
 - `--provider <provider>` `anthropic` or `openai`
 - `-d, --max-iterations <number>` default `150` (`0` = unlimited)
 - `-v, --verbose`
+- `--cost-mode <mode>` `normal` or `economy` (use cheaper model and lower iteration caps to save API cost)
 - `--dry-run`
 - `--changed-only`
 
@@ -251,6 +254,7 @@ Options:
 - `--provider <provider>` `anthropic` or `openai`
 - `-d, --max-iterations <number>` default `150` (`0` = unlimited)
 - `-v, --verbose`
+- `--cost-mode <mode>` `normal` or `economy` (save API cost)
 - `--branch <name>` override generated branch name
 - `--title <title>` override PR title
 - `--draft` open PR as draft
@@ -274,14 +278,17 @@ Options:
 - `-b, --base-url <url>`
 - `-k, --api-key <key>`
 - `--provider <provider>`
+- `--cost-mode <mode>` `normal` or `economy`
 - `--theme <theme>`
 - `--session <id>`
 
 ### `xibecode config`
 
 Manage saved config:
 
-- `--set-key`, `--set-url`, `--set-model`
+- `--set-key`, `--set-url`, `--set-model`, `--set-provider`
+- `--set-cost-mode <mode>` set default cost mode: `normal` or `economy`
+- `--set-economy-model <model>` model to use when cost mode is `economy`
 - `--show`, `--reset`
 - MCP helpers: `--list-mcp-servers`, `--add-mcp-server`, `--remove-mcp-server`
 
@@ -379,7 +386,7 @@ Click the ⚙️ Settings button to configure:
 - **Markdown Rendering** - Code blocks, bold, italic, lists, links
 - **Tool Execution** - Shows each tool call with status (running/done/failed)
 - **Thinking Indicator** - Spinner while AI is processing
-- **Responsive Design** - Works on mobile and desktop
+- **Responsive Design** - Mobile-friendly layout and touch-friendly controls; works on phones, tablets, and desktop
 - **Real-time Streaming** - See responses as they're generated
 
 ## AI Test Generation

SECURITY.md

@@ -0,0 +1,28 @@
+# Security
+
+## Secrets
+
+- API keys and env-based secrets are never logged or included in error messages. Display config uses masked values (e.g. `sk-ant-...`).
+- Store keys in environment variables or the local config file; avoid passing them on the command line in shared environments.
+
+## Agent-triggered execution (sandbox)
+
+- Commands executed via the agent’s `run_command` tool run with the **same user and privileges** as the XibeCode process. There is no sandboxing of shell commands by default.
+- **Recommendation**: For untrusted code or third-party repositories, run XibeCode inside a container (e.g. Docker) or a dedicated sandbox (e.g. E2B) so that agent-triggered commands cannot affect the host.
+- The `SafetyChecker` in `src/utils/safety.ts` blocks obviously dangerous commands (e.g. `rm -rf /`, fork bombs). This is a best-effort filter, not a full sandbox.
+
+## Input validation
+
+- **File paths**: All file tools resolve paths under the working directory. Paths that escape the workspace (path traversal) are rejected via `sanitizePath()` in `src/utils/safety.ts`.
+- **URLs**: The `fetch_url` tool only allows `http:` and `https:` URLs. Local and private addresses (localhost, 127.0.0.1, 192.168.x.x, 10.x.x.x, .local) are rejected by default to reduce SSRF risk. See `sanitizeUrl()` in `src/utils/safety.ts`.
+
+## Dependencies
+
+- CI runs `pnpm audit --audit-level=high`. High and critical vulnerabilities are treated as blocking. Fix or mitigate before merging.
+
+## New stack (Confucius-aligned features)
+
+- **Meta-agent / synthesized tools**: Session-scoped tools registered via `synthesize_tool` run the same sandbox as `run_command`; `SafetyChecker` and blocked-command rules apply. Scripts are not elevated.
+- **Session memory**: Stored under `.xibecode/sessions/`; no API keys or secrets are written. Failure/learning summaries are plain text only.
+- **PKG-style context**: Uses the local CodeGraph (AST) only; no external network or knowledge APIs.
+- **Economy and multi-model routing**: When cost mode is economy, planning and execution model selection still use the economy model when configured. Self-correction retries in `run-pr` use the same config, so token/iteration caps apply to each attempt.

src/commands/chat.ts

@@ -24,6 +24,7 @@ interface ChatOptions {
   baseUrl?: string;
   apiKey?: string;
   provider?: string;
+  costMode?: string;
   theme?: string;
   session?: string;
   noWebui?: boolean;
@@ -72,7 +73,8 @@ export async function chatCommand(options: ChatOptions) {
     process.exit(1);
   }
 
-  const model = options.model || config.getModel();
+  const useEconomy = (options.costMode || config.getCostMode()) === 'economy';
+  const model = options.model || config.getModel(useEconomy);
   const baseUrl = options.baseUrl || config.getBaseUrl();
   let currentProvider: ProviderType | undefined =
     (options.provider as ProviderType | undefined) || config.get('provider');

src/commands/config.ts

@@ -9,6 +9,8 @@ interface ConfigOptions {
   setUrl?: string;
   setModel?: string;
   setProvider?: string;
+  setCostMode?: string;
+  setEconomyModel?: string;
   show?: boolean;
   reset?: boolean;
   listMcpServers?: boolean;
@@ -66,6 +68,23 @@ export async function configCommand(options: ConfigOptions) {
     return;
   }
 
+  if (options.setCostMode) {
+    const mode = options.setCostMode.toLowerCase();
+    if (mode !== 'normal' && mode !== 'economy') {
+      ui.error(`Invalid cost mode "${options.setCostMode}". Use: normal or economy`);
+      process.exit(1);
+    }
+    config.set('costMode', mode as 'normal' | 'economy');
+    ui.success(`Cost mode set to: ${mode}`);
+    return;
+  }
+
+  if (options.setEconomyModel) {
+    config.set('economyModel', options.setEconomyModel);
+    ui.success(`Economy model set to: ${options.setEconomyModel}`);
+    return;
+  }
+
   if (options.listMcpServers) {
     const servers = await config.getMCPServers();
     const serverNames = Object.keys(servers);