scalix 0.0.1 → 1.1.0

package/.env.example

@@ -0,0 +1,29 @@
+# Required — your Scalix API key
+SCALIX_API_KEY=sk-...
+
+# Optional — custom API base URL (defaults to Scalix cloud)
+# SCALIX_BASE_URL=https://api.scalix.world/v1
+
+# Optional — override the default model
+# SCALIX_MODEL=
+
+# Optional — permission mode: plan | default | auto | yolo
+# SCALIX_PERMISSION_MODE=default
+
+# Optional — speech-to-text model for voice input
+# SCALIX_STT_MODEL=
+
+# Optional — log level: debug | info | warn | error
+# LOG_LEVEL=info
+
+# Optional — shell override (defaults to $SHELL)
+# SCALIX_SHELL=/bin/zsh
+
+# Optional — web search API keys (enable web_search tool)
+# BRAVE_API_KEY=
+# TAVILY_API_KEY=
+
+# Optional — custom search endpoint overrides
+# BRAVE_SEARCH_URL=
+# TAVILY_SEARCH_URL=
+# DDG_SEARCH_URL=

package/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to Scalix Coder will be documented in this file.
+
+## [3.1.0] - 2026-04-20
+
+### Added
+- Browser automation tools (navigate, screenshot, click, type, eval, get_text, close) via headless browser
+- Vision tools (read_image, screenshot) for image analysis with vision models
+- Voice input tool for speech-to-text
+- IPC server mode for VS Code extension integration (replaces HTTP-only bridge)
+- Auto-verification system — automatic build/lint checks after file modifications
+- File change tracker for monitoring agent modifications
+- Tab completion (inline suggestions) in VS Code extension
+- Inline chat (Cmd+I) in VS Code extension
+- Codebase symbol indexer in VS Code extension with multi-language support
+- Git checkpoint and restore in VS Code extension
+- Session persistence in VS Code extension
+- Slash commands and @-mention system in VS Code extension webview
+- Settings panel in VS Code extension with tabbed UI (General, Models, Tools)
+- Context detail panel showing token usage breakdown
+
+### Changed
+- Redesigned terminal UI with unique Scalix identity (magenta theme, custom indicators)
+- Tool count expanded from 21 to 31 built-in tools
+- Background process auto-cleanup reduced from 1 hour to 5 minutes
+- All unbounded defaults replaced with finite limits for memory stability
+- Background buffer max reduced from 100MB to 10MB
+- Max exec buffer and file read size capped at 10MB
+- Max steps/messages default set to 200 (previously unbounded)
+- Tool result hard cap at 200K characters to prevent context overflow
+- `verifyFailCounts` map capped at 100 entries with LRU eviction
+- Stream connections properly closed on abort via try/finally
+- Event listeners extracted to named references with proper cleanup
+- Model registry changed from hardcoded to dynamic API-fetched
+
+### Fixed
+- JavaScript heap out-of-memory crash (5GB after ~21 minutes idle)
+- Event listener memory leak (verify:pass, verify:fail, file:modified without cleanup)
+- Stream connection leak on abort (for-await loop without stream.controller.abort())
+- Background process buffer overflow with precise slicing
+- Confirmation timeout hanging indefinitely (now 5-minute timeout)
+- VS Code webview null reference crashes (getElementById without guards)
+- React useEffect dependency causing unnecessary re-renders
+
+## [3.0.0] - 2026-04-18
+
+### Added
+- Scalix ecosystem integration with API key formats (`scalix_*`, `sk_live_*`, `scalix_free_*`)
+- Dynamic model fetching from Scalix API (`/api/inference/models`)
+- Model registry with exact context windows
+- Token and context management system with auto-compression
+- Virtual scrolling in terminal UI with keyboard navigation (Shift+Up/Down, PageUp/PageDown)
+- Symlink traversal prevention in path resolution
+- Bracketed paste mode handling for reliable text input
+- API key masking in setup wizard with character count indicator
+- Context bar in VS Code extension showing token usage
+- Security hardening: `execFile` for search, stream error handlers, input sanitization
+
+### Changed
+- Default API endpoint to `https://api.scalix.world/v1`
+- Default model to `scalix-world-ai` (free tier)
+- Package name from `my-agent` to `scalix-coder`
+- CLI command unified to `scalix`
+- User-Agent strings to `ScalixCoder/3.0`
+- License from ISC to EULA under Scalix World Private Limited
+
+### Fixed
+- Terminal UI shrinking instead of scrolling on long conversations
+- Diff capture race condition in VS Code extension
+- Notebook cell move operation with out-of-bounds positions
+- Dynamic imports replaced with static imports for reliability
+
+## [2.1.0] - 2026-03-15
+
+### Added
+- Sub-agent system with delegated task execution
+- Git checkpoint and undo system
+- Scoped rules engine (`.scalix/rules/*.md`)
+- Custom commands (`.scalix/commands/*.md`)
+- Lifecycle hooks (`.scalix/hooks.json`)
+- Plugin system with auto-discovery
+- Model routing with complexity-based selection
+- Cost budget tracking with daily/monthly limits
+- Project memory with auto-detected conventions
+- Session replay timeline
+
+### Changed
+- Upgraded to 21 built-in tools
+- Enhanced project indexing with symbol extraction
+
+## [2.0.0] - 2026-02-01
+
+### Added
+- React/Ink terminal UI with gradient banner
+- Streaming responses with reasoning display
+- 4 permission modes (plan, default, auto, yolo)
+- Session persistence with save/load
+- Context manager with auto-compression
+- MCP (Model Context Protocol) support
+- Web fetch and search tools with SSRF protection
+- File edit tool with LCS diff engine
+- Directory tree visualization
+- Multiline input with `\` continuation
+
+### Changed
+- Migrated from plain REPL to Ink-based UI
+- Complete architecture rewrite
+
+## [1.0.0] - 2026-01-15
+
+### Added
+- Initial release
+- Core agent loop with OpenAI-compatible API
+- Basic tools: shell, read, write, list files
+- Calculator and time tools
+- Simple REPL interface
+- Configuration system
+
+---
+
+(c) 2024-2026 Scalix World Private Limited. All rights reserved.

package/LICENSE

@@ -0,0 +1,100 @@
+SCALIX WORLD PRIVATE LIMITED
+END USER LICENSE AGREEMENT (EULA)
+
+Copyright (c) 2025-2026 Scalix World Pvt Ltd. All rights reserved.
+A subsidiary of Energy FW Ltd (UK Company No. 14600160)
+
+IMPORTANT — READ CAREFULLY BEFORE USING THIS SOFTWARE.
+
+This End User License Agreement ("Agreement") is a legal agreement between you
+("User") and Scalix World Private Limited ("Company", "we", "us"), a company
+incorporated under the laws of India (CIN: U72100KL2026PTC102006), for the use
+of the software, source code, documentation, and associated materials
+(collectively, the "Software") contained in this repository.
+
+By accessing, downloading, copying, installing, or otherwise using the Software,
+you agree to be bound by the terms of this Agreement. If you do not agree to
+these terms, do not use the Software.
+
+
+1. LICENSE GRANT
+
+   Subject to the terms of this Agreement, the Company grants you a limited,
+   non-exclusive, non-transferable, revocable license to use the Software solely
+   for the purposes expressly authorized by the Company.
+
+   You may NOT:
+   a) Copy, modify, adapt, translate, or create derivative works of the Software;
+   b) Distribute, sublicense, lease, rent, loan, or otherwise transfer the
+      Software or any rights therein to any third party;
+   c) Reverse engineer, decompile, disassemble, or attempt to derive the source
+      code of the Software, except to the extent permitted by applicable law;
+   d) Remove, alter, or obscure any proprietary notices, labels, or marks on
+      the Software;
+   e) Use the Software to build a competing product or service;
+   f) Use the Software for any unlawful purpose.
+
+
+2. INTELLECTUAL PROPERTY
+
+   The Software and all copies thereof are proprietary to the Company and title
+   thereto remains in the Company. All rights in the Software not specifically
+   granted in this Agreement are reserved to the Company. The Software is
+   protected by copyright laws and international treaty provisions.
+
+
+3. CONFIDENTIALITY
+
+   The Software contains trade secrets and proprietary information of the
+   Company. You agree to maintain the confidentiality of the Software and not
+   to disclose it to any third party without the prior written consent of
+   the Company.
+
+
+4. NO WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THE COMPANY DOES
+   NOT WARRANT THAT THE SOFTWARE WILL BE ERROR-FREE OR UNINTERRUPTED.
+
+
+5. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL THE COMPANY, ITS DIRECTORS, OFFICERS, EMPLOYEES, OR
+   AGENTS BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR
+   PUNITIVE DAMAGES ARISING OUT OF OR RELATED TO YOUR USE OF OR INABILITY TO
+   USE THE SOFTWARE, EVEN IF THE COMPANY HAS BEEN ADVISED OF THE POSSIBILITY
+   OF SUCH DAMAGES.
+
+
+6. TERMINATION
+
+   This license is effective until terminated. The Company may terminate this
+   Agreement at any time if you fail to comply with any term herein. Upon
+   termination, you must destroy all copies of the Software in your possession
+   and cease all use.
+
+
+7. GOVERNING LAW
+
+   This Agreement shall be governed by and construed in accordance with the
+   laws of India. Any disputes arising under this Agreement shall be subject
+   to the exclusive jurisdiction of the courts in Kerala, India.
+
+
+8. THIRD-PARTY COMPONENTS
+
+   The Software may include third-party open-source components, each subject to
+   its own license terms. Such licenses are found in the respective component
+   directories and are not affected by this Agreement.
+
+
+9. ENTIRE AGREEMENT
+
+   This Agreement constitutes the entire agreement between you and the Company
+   regarding the Software and supersedes all prior agreements, whether written
+   or oral.
+
+
+For licensing inquiries, contact: legal@scalix.world

package/README.md

@@ -1,3 +1,301 @@
-# scalix
+# Scalix Coder
 
-Coming soon. Visit [scalix.world](https://scalix.world)
+AI-powered coding agent for the terminal and VS Code — built by [Scalix World](https://scalix.world).
+
+![Version](https://img.shields.io/badge/version-1.0.0-blue)
+![Node](https://img.shields.io/badge/node-%3E%3D18-green)
+![License](https://img.shields.io/badge/license-EULA-orange)
+
+Scalix Coder is a full-featured AI coding assistant that runs in your terminal or as a VS Code extension. It connects to the Scalix API (or any OpenAI-compatible endpoint) and gives AI direct access to your codebase through 31 built-in tools — file editing, shell execution, search, git, web access, browser automation, vision, voice input, and more.
+
+## Features
+
+- **Terminal UI** — Rich React/Ink interface with magenta-themed prompt, scrollable chat, streaming responses, and keyboard shortcuts
+- **VS Code Extension** — Sidebar chat panel with inline diffs, tab completion, inline chat (Cmd+I), codebase search, model picker, checkpoints, and session history
+- **31 Built-in Tools** — Shell, file read/write/edit, search (ripgrep), git, web fetch/search, directory tree, notebooks, browser automation, vision, voice input, sub-agents
+- **Security Sandbox** — Path traversal prevention, symlink detection, command blocklist, injection detection, SSRF protection
+- **4 Permission Modes** — `plan` (read-only) / `default` (ask) / `auto` (auto-approve) / `yolo` (full autonomy)
+- **Context Management** — Auto-compression, sliding window, per-model context limits
+- **Dynamic Model Registry** — Models fetched from your Scalix account with exact context windows
+- **Session Persistence** — Save, load, and resume conversations
+- **Project Intelligence** — Auto-detects tech stack, conventions, git context
+- **Plugin System** — Custom tools via `.scalix/plugins/`
+- **Custom Commands** — Reusable prompts in `.scalix/commands/*.md`
+- **Model Routing** — Multi-model support with complexity-based routing and fallback
+- **Cost Tracking** — Token usage and budget limits per session/day/month
+- **Sub-agents** — Delegate tasks with isolated tool access
+- **Git Checkpoints** — Create and undo agent-made changes
+- **Auto-Verification** — Automatic build/lint checks after file modifications
+- **Lifecycle Hooks** — Pre/post tool-use hooks via `.scalix/hooks.json`
+- **IPC Server** — Bridge mode for VS Code extension integration
+- **Browser Automation** — Navigate, click, type, screenshot, and evaluate JS in headless browsers
+
+## Quick Start
+
+### Install
+
+```bash
+git clone https://github.com/scalixworld/scalix-coder.git && cd scalix-coder
+npm install
+sudo npm link
+```
+
+### Run
+
+```bash
+scalix
+```
+
+First launch opens a setup wizard to configure your Scalix API key, endpoint, and models.
+
+### Environment Variables
+
+| Variable          | Description                      |
+| ----------------- | -------------------------------- |
+| `SCALIX_API_KEY`  | API key (overrides saved config) |
+| `SCALIX_MODEL`    | Comma-separated model IDs        |
+| `SCALIX_BASE_URL` | API base URL                     |
+| `BRAVE_API_KEY`   | Brave Search API key             |
+| `TAVILY_API_KEY`  | Tavily Search API key            |
+
+### Headless Mode
+
+```bash
+scalix run "explain src/agent.ts"
+
+echo "list all TODO comments" | scalix --pipe
+
+scalix run "generate a migration" --output migration.sql --format patch
+```
+
+## Commands
+
+| Command            | Description                  |
+| ------------------ | ---------------------------- |
+| `/help`            | Show all commands            |
+| `/shortcuts`       | Keyboard shortcuts           |
+| `/clear`           | Reset conversation           |
+| `/models`          | List active models           |
+| `/model`           | Switch model                 |
+| `/mode`            | Set permission mode          |
+| `/compact`         | Compress context             |
+| `/cost`            | Token usage & cost           |
+| `/budget`          | Budget status                |
+| `/save [name]`     | Save session                 |
+| `/load`            | Resume session               |
+| `/index`           | Scan project files           |
+| `/git`             | Git context                  |
+| `/memory`          | Project memory               |
+| `/remember <note>` | Save a project note          |
+| `/replay`          | Session timeline             |
+| `/plugins`         | Loaded plugins               |
+| `/settings`        | Configure limits             |
+| `/setup`           | Reconfigure API key & models |
+| `/delegate <task>` | Run with sub-agent           |
+| `/checkpoint`      | Create git checkpoint        |
+| `/undo`            | Undo last checkpoint         |
+| `!<cmd>`           | Run shell command            |
+
+## Keyboard Shortcuts
+
+| Key                     | Action                                   |
+| ----------------------- | ---------------------------------------- |
+| `Ctrl+C`                | Interrupt / clear / double-press to quit |
+| `Ctrl+D`                | Exit (empty input)                       |
+| `Ctrl+L`                | Clear screen                             |
+| `Ctrl+U`                | Clear input line                         |
+| `Ctrl+W`                | Delete last word                         |
+| `Ctrl+S`                | Stash/restore prompt                     |
+| `Tab`                   | Autocomplete commands                    |
+| `Up/Down`               | Input history                            |
+| `Shift+Up / PageUp`     | Scroll chat up                           |
+| `Shift+Down / PageDown` | Scroll chat down                         |
+| `Esc`                   | Quit                                     |
+
+## Tools
+
+### Core
+
+| Tool               | Description                          |
+| ------------------ | ------------------------------------ |
+| `get_current_time` | Current date/time with timezone      |
+| `calculate`        | Safe math expression evaluator       |
+| `run_command`      | Shell execution with security checks |
+| `read_file`        | File reading with line numbers       |
+| `read_file_lines`  | Read specific line ranges            |
+| `write_file`       | File creation/overwrite              |
+| `list_files`       | Directory listing with glob support  |
+
+### Code
+
+| Tool           | Description                          |
+| -------------- | ------------------------------------ |
+| `edit_file`    | Precise string replacement with diff |
+| `search_files` | Regex search via ripgrep             |
+| `find_files`   | Glob-based file finding              |
+| `tree`         | Directory tree visualization         |
+
+### Git
+
+| Tool         | Description                     |
+| ------------ | ------------------------------- |
+| `git_status` | Branch, changes, recent commits |
+| `git_diff`   | Staged/unstaged diffs           |
+| `git_commit` | Stage and commit                |
+
+### Web
+
+| Tool         | Description                             |
+| ------------ | --------------------------------------- |
+| `web_fetch`  | Fetch URLs with SSRF protection         |
+| `web_search` | Search via Brave, Tavily, or DuckDuckGo |
+
+### Browser
+
+| Tool                 | Description                           |
+| -------------------- | ------------------------------------- |
+| `browser_navigate`   | Navigate to a URL in headless browser |
+| `browser_screenshot` | Capture browser page screenshot       |
+| `browser_click`      | Click elements on page                |
+| `browser_type`       | Type text into page elements          |
+| `browser_eval`       | Execute JavaScript in browser context |
+| `browser_get_text`   | Extract text content from page        |
+| `browser_close`      | Close browser session                 |
+
+### Vision & Voice
+
+| Tool          | Description                       |
+| ------------- | --------------------------------- |
+| `read_image`  | Analyze images with vision models |
+| `screenshot`  | Capture desktop screenshots       |
+| `voice_input` | Voice-to-text input               |
+
+### Advanced
+
+| Tool             | Description                 |
+| ---------------- | --------------------------- |
+| `todo_write`     | Task tracking               |
+| `notebook_edit`  | Jupyter notebook operations |
+| `monitor`        | Background process output   |
+| `agent`          | Spawn sub-agents            |
+| `add_mcp_server` | Register MCP servers        |
+
+## Configuration
+
+Config is stored in `~/.scalix-coder/config.json`.
+
+### Limits
+
+| Setting                | Default   | Description                                   |
+| ---------------------- | --------- | --------------------------------------------- |
+| `maxSteps`             | 200       | Tool-call rounds per request                  |
+| `maxMessages`          | 200       | History size                                  |
+| `maxContextTokens`     | 1,000,000 | Context window (tokens)                       |
+| `compressionThreshold` | 0.75      | Auto-compress when context exceeds this ratio |
+| `maxToolResultTokens`  | 10,000    | Truncate tool results (tokens)                |
+| `commandTimeoutMs`     | 60,000    | Shell command timeout (ms)                    |
+| `bgCleanupMs`          | 300,000   | Background process auto-cleanup (5 min)       |
+| `readFileMaxSize`      | 10 MB     | Max file size for read operations             |
+
+### Project Files
+
+| Path                    | Purpose                       |
+| ----------------------- | ----------------------------- |
+| `AGENT.md`              | Project-specific instructions |
+| `.scalix/memory.json`   | Conventions & notes           |
+| `.scalix/plugins/`      | Custom tool plugins           |
+| `.scalix/commands/*.md` | Custom slash commands         |
+| `.scalix/hooks.json`    | Lifecycle hooks               |
+| `.scalix/rules/*.md`    | Scoped rules                  |
+| `mcp-services.json`     | MCP server config             |
+
+## VS Code Extension
+
+Full-featured sidebar assistant with streaming chat, tab completion, inline chat, inline diffs, codebase search, and checkpoints.
+
+See [vscode-extension/README.md](vscode-extension/README.md) for setup and usage.
+
+```bash
+cd vscode-extension
+npm install
+npm run build
+npm run package    # Creates .vsix file
+```
+
+## Development
+
+```bash
+npm run start        # Run CLI
+npm run dev          # Watch mode
+npm run test         # Vitest
+npm run typecheck    # Type-check
+npm run lint         # ESLint
+npm run check        # All checks
+```
+
+## Architecture
+
+```
+src/
+  cli.tsx              Terminal UI (React/Ink)
+  headless.ts          Headless/REPL mode
+  agent.ts             Core agent loop
+  constants.ts         All defaults and configuration constants
+  settings.ts          Config management and validation
+  sandbox.ts           Security sandbox (path, command, injection)
+  context-manager.ts   Token counting & compression
+  context-builder.ts   System prompt assembly
+  token-counter.ts     Token estimation engine
+  tools.ts             Core tools (shell, file, time, calc)
+  tools-extra.ts       Code tools (edit, search, find, git)
+  tools-web.ts         Web tools (fetch, search, tree, read_file_lines)
+  tools-advanced.ts    Advanced tools (todo, notebook, sub-agent, monitor)
+  tools-browser.ts     Browser automation (navigate, click, type, eval)
+  tools-vision.ts      Vision tools (read_image, screenshot)
+  tools-voice.ts       Voice input tool
+  tool-helper.ts       Tool definition helper
+  tool-selector.ts     Dynamic tool selection
+  model-router.ts      Multi-model complexity routing
+  cost-tracker.ts      Token/cost tracking with budgets
+  sessions.ts          Session persistence
+  project-index.ts     Project file scanning & symbol extraction
+  project-memory.ts    Convention memory system
+  plugins.ts           Plugin auto-discovery and loading
+  sub-agent.ts         Sub-agent spawning
+  auto-verify.ts       Post-edit build/lint verification
+  change-tracker.ts    File modification tracking
+  hooks.ts             Lifecycle hook execution
+  scoped-rules.ts      Scoped rules engine
+  commands.ts          Custom slash commands
+  git-context.ts       Git info collection
+  git-undo.ts          Checkpoint/undo system
+  agent-replay.ts      Session timeline replay
+  diff.ts              LCS diff computation
+  markdown.ts          Markdown rendering
+  safe-math.ts         Safe expression evaluator
+  logger.ts            Structured logging
+  mcp.ts               MCP server integration
+  ipc-server.ts        IPC bridge for VS Code extension
+  config.ts            Config helpers
+
+vscode-extension/
+  src/extension.ts          Extension activation & command registration
+  src/agent-bridge.ts       Agent implementation (HTTP + IPC modes)
+  src/chat-panel.ts         Webview chat UI (HTML/CSS/JS)
+  src/status-bar.ts         Status bar integration
+  src/diff-viewer.ts        Inline diff viewer
+  src/completion-provider.ts  AI-powered tab completion
+  src/inline-chat.ts        Inline chat (Cmd+I)
+  src/indexer.ts            Codebase symbol indexer
+  src/checkpoints.ts        Git checkpoint management
+  src/session-store.ts      Session persistence
+
+bin/
+  scalix.js            CLI entry point
+```
+
+## License
+
+Scalix Coder is proprietary software. See [LICENSE](LICENSE) for the full EULA.
+
+(c) 2024-2026 Scalix World Private Limited. All rights reserved.

package/bin/scalix.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+process.env.NODE_ENV = 'production';
+
+const args = process.argv.slice(2);
+const needsHeadless =
+  args.includes('run') ||
+  args.includes('--pipe') || args.includes('-p') ||
+  args.includes('--ipc') ||
+  args.includes('--help') || args.includes('-h') ||
+  !process.stdin.isTTY;
+
+const entry = resolve(__dirname, '..', 'dist', needsHeadless ? 'headless.js' : 'cli.js');
+await import(pathToFileURL(entry).href);

package/dist/agent-definitions.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { USER_CONFIG_DIR, PROJECT_LOOKUP_DIRS } from './constants.js';
+const VALID_TOOL_LEVELS = new Set(['read-only', 'standard', 'all']);
+const BUILT_IN_TYPES = new Set(['general', 'explore', 'plan']);
+export function parseAgentDefinition(content, filename) {
+    const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+    if (!frontmatterMatch)
+        return null;
+    const [, frontmatter, body] = frontmatterMatch;
+    const instructions = body.trim();
+    if (!instructions)
+        return null;
+    const fields = {};
+    for (const line of frontmatter.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const val = line.slice(colonIdx + 1).trim();
+        fields[key] = val;
+    }
+    const name = fields.name || path.basename(filename, path.extname(filename));
+    if (BUILT_IN_TYPES.has(name))
+        return null;
+    const description = fields.description || `Custom agent: ${name}`;
+    const tools = VALID_TOOL_LEVELS.has(fields.tools) ? fields.tools : 'standard';
+    const maxSteps = fields.maxSteps ? parseInt(fields.maxSteps, 10) : undefined;
+    const model = fields.model && fields.model !== '(optional override)' ? fields.model : undefined;
+    const allowSpawning = fields.allowSpawning === 'true' ? true : fields.allowSpawning === 'false' ? false : undefined;
+    return {
+        name,
+        description,
+        tools,
+        maxSteps: maxSteps && Number.isFinite(maxSteps) && maxSteps > 0 ? maxSteps : undefined,
+        model,
+        allowSpawning,
+        instructions,
+    };
+}
+async function loadDefinitionsFromDir(dir) {
+    const defs = new Map();
+    try {
+        const entries = await fs.readdir(dir);
+        for (const entry of entries) {
+            if (!entry.endsWith('.md'))
+                continue;
+            try {
+                const content = await fs.readFile(path.join(dir, entry), 'utf-8');
+                const def = parseAgentDefinition(content, entry);
+                if (def)
+                    defs.set(def.name, def);
+            }
+            catch {
+                // skip unreadable files
+            }
+        }
+    }
+    catch {
+        // directory doesn't exist — that's fine
+    }
+    return defs;
+}
+export async function loadAgentDefinitions(projectDir) {
+    const globalDir = path.join(os.homedir(), USER_CONFIG_DIR, 'agents');
+    const globalDefs = await loadDefinitionsFromDir(globalDir);
+    const projectDefs = new Map();
+    if (projectDir) {
+        for (const lookupDir of PROJECT_LOOKUP_DIRS) {
+            const dir = path.join(projectDir, lookupDir, 'agents');
+            const defs = await loadDefinitionsFromDir(dir);
+            for (const [name, def] of defs) {
+                projectDefs.set(name, def);
+            }
+        }
+    }
+    // Project definitions override global
+    const merged = new Map(globalDefs);
+    for (const [name, def] of projectDefs) {
+        merged.set(name, def);
+    }
+    return merged;
+}
+let _cachedDefinitions = null;
+let _cacheProjectDir;
+export async function getAgentDefinitions(projectDir) {
+    if (_cachedDefinitions && _cacheProjectDir === projectDir)
+        return _cachedDefinitions;
+    _cachedDefinitions = await loadAgentDefinitions(projectDir);
+    _cacheProjectDir = projectDir;
+    return _cachedDefinitions;
+}
+export function invalidateAgentDefinitionCache() {
+    _cachedDefinitions = null;
+    _cacheProjectDir = undefined;
+}
+export function isBuiltInAgentType(name) {
+    return BUILT_IN_TYPES.has(name);
+}