byterover-cli 1.5.0 → 1.7.0

package/README.md

@@ -12,6 +12,8 @@ Command-line interface for ByteRover, featuring an interactive REPL with a moder
 * [Quick Start](#quick-start)
 * [Interactive REPL](#interactive-repl)
 * [Keyboard Shortcuts](#keyboard-shortcuts)
+* [CLI Commands](#cli-commands)
+* [Headless Mode](#headless-mode)
 * [What is Context Tree?](#what-is-context-tree)
 * [Supported AI Agents](#supported-ai-agents)
 * [LLM Providers](#llm-providers) (BETA)
@@ -124,7 +126,7 @@ The terminal UI includes:
 - **Streaming Output**: Live responses with markdown rendering (headings, lists, blockquotes, code blocks)
 - **Reasoning Display**: View agent thinking process with streamed reasoning blocks
 - **File References**: Type `@` in curate mode to browse and attach files
-- **PDF Support**: Reference and extract text from PDF files using `@` (up to 100 pages)
+- **PDF Support**: Reference and extract text from PDF files using `@` (100 pages default, 200 max)
 - **Dynamic Domains**: Automatically creates new knowledge domains as your context tree grows
 - **Session Persistence**: Sessions auto-resume after restart
 - **Expandable Views**: Press `Ctrl+O` to expand messages or logs to full-screen with vim-style navigation
@@ -142,17 +144,123 @@ The terminal UI includes:
 | `/` | Show command suggestions |
 | `@` | Browse files (in curate mode) |
 
-### Using Commands
+## CLI Commands
 
-In the REPL, use slash commands (commands prefixed with `/`) to interact with ByteRover:
+In addition to the interactive REPL, ByteRover CLI provides direct command-line commands for automation and scripting.
 
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `brv login -k <key>` | Authenticate with an API key |
+
+**Example:**
+```bash
+brv login --api-key your-api-key
 ```
-/status              # Check your project status
-/curate              # Add context interactively
-/push                # Push changes to cloud
+
+Get your API key at [app.byterover.dev/settings/keys](https://app.byterover.dev/settings/keys).
+
+### Project Commands
+
+| Command | Description |
+|---------|-------------|
+| `brv init` | Initialize a project with ByteRover |
+| `brv status [dir]` | Show CLI status and project information |
+
+**Init flags:**
+- `-f, --force`: Force re-initialization without confirmation
+- `--headless`: Run in headless mode (requires `--team` and `--space`)
+- `--team <id|name>`: Team ID or name
+- `--space <id|name>`: Space ID or name
+- `--format <text|json>`: Output format (default: text)
+
+**Status flags:**
+- `-f, --format <text|json>`: Output format (default: text)
+- `--headless`: Run in headless mode
+
+### Context Operations
+
+| Command | Description |
+|---------|-------------|
+| `brv query <question>` | Query the context tree |
+| `brv curate [context]` | Curate context to the context tree |
+
+**Note:** `query` and `curate` require a running `brv` instance in another terminal.
+
+**Query flags:**
+- `--headless`: Run in headless mode
+- `--format <text|json>`: Output format (default: text)
+
+**Curate flags:**
+- `-f, --files <path>`: Include specific files (max 5, can be repeated)
+- `--headless`: Run in headless mode
+- `--format <text|json>`: Output format (default: text)
+
+### Cloud Sync
+
+| Command | Description |
+|---------|-------------|
+| `brv push` | Push context tree to ByteRover cloud |
+| `brv pull` | Pull context tree from ByteRover cloud |
+
+**Push flags:**
+- `-b, --branch <name>`: ByteRover branch name (default: main, not Git branch)
+- `-y, --yes`: Skip confirmation prompt
+- `--headless`: Run in headless mode (auto-skips confirmation)
+- `--format <text|json>`: Output format (default: text)
+
+**Pull flags:**
+- `-b, --branch <name>`: ByteRover branch name (default: main, not Git branch)
+- `--headless`: Run in headless mode
+- `--format <text|json>`: Output format (default: text)
+
+## Headless Mode
+
+ByteRover CLI supports headless mode for automation, CI/CD pipelines, and scripting. Headless mode disables interactive prompts and supports machine-readable JSON output.
+
+### Supported Commands
+
+The following commands support `--headless` mode:
+- `brv init` (requires `--team` and `--space`)
+- `brv status`
+- `brv query`
+- `brv curate`
+- `brv push` (auto-skips confirmation)
+- `brv pull`
+
+### Output Formats
+
+Use `--format` to control output:
+- `text` (default): Human-readable text output
+- `json`: NDJSON (newline-delimited JSON) for machine parsing
+
+### CI/CD Examples
+
+**Initialize a project in CI:**
+```bash
+brv login --api-key $BRV_API_KEY
+brv init --headless --team "my-team" --space "my-space" --format json
+```
+
+**Push context tree after tests pass:**
+```bash
+brv push --headless --format json -y
 ```
 
-Commands support tab completion for quick navigation.
+**Query context in a script:**
+```bash
+brv query "What are the API endpoints?" --headless --format json
+```
+
+### JSON Output Structure
+
+JSON output uses NDJSON format with message types:
+- `log`: Progress messages
+- `output`: Main output content
+- `error`: Error messages
+- `warning`: Warning messages
+- `result`: Final operation result
 
 ## What is Context Tree?
 
@@ -182,10 +290,10 @@ ByteRover integrates with 19 AI coding agents:
 - Claude Code, Cursor
 
 **MCP Connector (Default):**
-- Amp, Augment Code, Cline, Codex, Gemini CLI, Github Copilot, Junie, Kilo Code, Kiro, Qoder, Qwen Code, Roo Code, Trae.ai, Warp, Windsurf, Zed
+- Amp, Codex, Gemini CLI, Github Copilot, Junie, Kilo Code, Kiro, Roo Code, Zed
 
 **Rules Connector (Default):**
-- Antigravity (rules-only integration)
+- Antigravity, Augment Code, Cline, Qoder, Qwen Code, Trae.ai, Warp, Windsurf
 
 **All agents support rules-based integration as a universal fallback option.**
 
@@ -201,15 +309,15 @@ Use `/connectors` to manage integrations with your AI coding agents:
 
 ByteRover supports four connector types:
 
-1. **Skill integration** (Claude Code, Cursor - default): Modern integration that writes 3 markdown files (SKILL.md, TROUBLESHOOTING.md, WORKFLOWS.md) to your agent's skills directory for easy discovery and guidance
-2. **MCP integration** (16 agents - default): Exposes brv-query and brv-curate as Model Context Protocol tools that AI agents can call directly
+1. **Skill integration** (Claude Code, Codex, Cursor, Github Copilot): Modern integration that writes 3 markdown files (SKILL.md, TROUBLESHOOTING.md, WORKFLOWS.md) to your agent's skills directory for easy discovery and guidance
+2. **MCP integration** (11 agents): Exposes brv-query and brv-curate as Model Context Protocol tools that AI agents can call directly
 3. **Rules-based** (all agents): Generates agent-specific rule files (e.g., CLAUDE.md, .cursorrules) with instructions for using ByteRover
 4. **Hook integration** (Claude Code only - legacy): Direct injection via IDE settings, replaced by skill connector
 
 **Defaults by agent:**
 - Claude Code, Cursor: Skill connector
-- Antigravity: Rules connector (only supported type)
-- All others (16 agents): MCP connector
+- Amp, Codex, Gemini CLI, Github Copilot, Junie, Kilo Code, Kiro, Roo Code, Zed: MCP connector
+- Antigravity, Augment Code, Cline, Qoder, Qwen Code, Trae.ai, Warp, Windsurf: Rules connector
 - Rules: Available for all agents as fallback
 
 ## LLM Providers (BETA)
@@ -324,8 +432,8 @@ The model browser shows:
 
 **Defaults:**
 - Claude Code, Cursor: `skill`
-- Antigravity: `rules` (only supported type)
-- All others: `mcp`
+- Amp, Codex, Gemini CLI, Github Copilot, Junie, Kilo Code, Kiro, Roo Code, Zed: `mcp`
+- Antigravity, Augment Code, Cline, Qoder, Qwen Code, Trae.ai, Warp, Windsurf: `rules`
 
 **Reset options:**
 - `-y, --yes`: Skip confirmation prompt
@@ -348,7 +456,7 @@ The model browser shows:
 **Options:**
 - `-y, --yes`: Skip confirmation prompt
 
-**Note:** Sessions are stateful and auto-resume after restart. Use `/new` to start fresh—this clears conversation history but does NOT affect the context tree.
+**Note:** Sessions are stateful and auto-resume after restart (retained for 30 days). Use `/new` to start fresh—this clears conversation history but does NOT affect the context tree.
 
 ### Project Setup
 
@@ -368,16 +476,29 @@ The model browser shows:
 
 ## Authentication
 
-ByteRover CLI uses **OAuth 2.0 with PKCE** (Proof Key for Code Exchange) for secure authentication.
+ByteRover CLI supports two authentication methods to suit different workflows.
+
+### Authentication Methods
+
+**1. OAuth 2.0 (Interactive)**
+- Use `/login` in the REPL
+- Opens browser for secure OAuth flow with PKCE
+- Best for: Local development, interactive use
+
+**2. API Key (Non-interactive)**
+- Use `brv login --api-key <key>`
+- No browser required
+- Best for: CI/CD, automation, headless environments
+- Get your key at [app.byterover.dev/settings/keys](https://app.byterover.dev/settings/keys)
 
-### How it works
+### How OAuth Works
 
 1. Run `/login` in the REPL to start authentication
 2. Your browser opens to the ByteRover authorization page
 3. After successful login, tokens are securely stored in your system keychain
 4. All subsequent commands automatically use your stored credentials
 
-### Security features
+### Security Features
 
 - **PKCE flow**: Prevents authorization code interception attacks
 - **System keychain**: Tokens stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service
@@ -433,8 +554,8 @@ The context tree is stored in `.brv/context-tree/`:
 
 Connector configurations are stored based on type:
 
-**Skill connectors** (Claude Code, Cursor):
-- **Project-scoped**: `.claude/skills/byterover/`, `.cursor/skills/byterover/`
+**Skill connectors** (Claude Code, Codex, Cursor, Github Copilot):
+- **Project-scoped**: `.claude/skills/byterover/`, `.cursor/skills/byterover/`, `.github/skills/byterover/`
 - **Global-scoped** (Codex): `~/.codex/skills/byterover/`
 - Files: `SKILL.md`, `TROUBLESHOOTING.md`, `WORKFLOWS.md`
 

package/dist/agent/core/domain/agent/agent-registry.d.ts

@@ -0,0 +1,90 @@
+import { AgentInfo } from './agent-info.js';
+/**
+ * Built-in agent names.
+ * These constants ensure type safety and prevent typos.
+ */
+export declare const AgentName: {
+    /** Default primary agent with full capabilities */
+    readonly CIPHER: "cipher";
+};
+export type KnownAgent = (typeof AgentName)[keyof typeof AgentName];
+/**
+ * AgentRegistry - Singleton registry for managing agent definitions.
+ *
+ * Provides methods to:
+ * - Get agent by name
+ * - List all agents
+ * - List agents by mode (primary, subagent)
+ * - Register custom agents
+ */
+export declare class AgentRegistry {
+    private static instance;
+    private agents;
+    private constructor();
+    /**
+     * Get the singleton instance of AgentRegistry.
+     */
+    static getInstance(): AgentRegistry;
+    /**
+     * Reset the singleton instance (for testing).
+     */
+    static reset(): void;
+    /**
+     * Get an agent by name.
+     * @param name - Agent name
+     * @returns Agent info or undefined if not found
+     */
+    get(name: string): AgentInfo | undefined;
+    /**
+     * Get agent names as a formatted list for display.
+     * @returns Formatted string of agent names and descriptions
+     */
+    getSubagentDescriptions(): string;
+    /**
+     * Check if an agent exists.
+     * @param name - Agent name
+     * @returns true if agent exists
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered agents.
+     * @returns Array of agent info objects
+     */
+    list(): AgentInfo[];
+    /**
+     * List agents by mode.
+     * @param mode - Agent mode to filter by
+     * @returns Array of agents matching the mode
+     */
+    listByMode(mode: 'all' | 'primary' | 'subagent'): AgentInfo[];
+    /**
+     * List primary agents available for direct user interaction.
+     * Returns agents that can be used as entry points (mode: 'primary' or 'all').
+     * Excludes hidden agents.
+     * @returns Array of primary agent info objects
+     */
+    listPrimaryAgents(): AgentInfo[];
+    /**
+     * List subagents available for TaskTool.
+     * Returns agents that can be invoked as subagents (mode: 'subagent' or 'all').
+     * Excludes hidden agents.
+     * @returns Array of subagent info objects
+     */
+    listSubagents(): AgentInfo[];
+    /**
+     * Register a custom agent.
+     * @param agent - Agent info to register
+     * @throws Error if agent with same name already exists (unless overwrite is true)
+     */
+    register(agent: AgentInfo, overwrite?: boolean): void;
+    /**
+     * Unregister an agent.
+     * @param name - Agent name to remove
+     * @returns true if agent was removed, false if not found
+     */
+    unregister(name: string): boolean;
+}
+/**
+ * Convenience function to get the AgentRegistry instance.
+ */
+export declare function getAgentRegistry(): AgentRegistry;

package/dist/agent/core/domain/agent/agent-registry.js

@@ -0,0 +1,152 @@
+import { AgentInfoSchema, DEFAULT_AGENT_PERMISSION, } from './agent-info.js';
+/**
+ * Built-in agent names.
+ * These constants ensure type safety and prevent typos.
+ */
+export const AgentName = {
+    /** Default primary agent with full capabilities */
+    CIPHER: 'cipher',
+};
+/**
+ * Built-in agent definitions.
+ * These are the native agents available in the system.
+ */
+const BUILT_IN_AGENTS = {
+    /**
+     * Cipher Agent - Default primary agent with full capabilities.
+     * Handles queries, curation, and all context tree operations directly.
+     */
+    [AgentName.CIPHER]: AgentInfoSchema.parse({
+        description: 'Default agent with full capabilities for context engineering tasks.',
+        hidden: false,
+        mode: 'primary',
+        name: AgentName.CIPHER,
+        native: true,
+        permission: DEFAULT_AGENT_PERMISSION,
+        promptFile: 'system-prompt.yml',
+        tools: {}, // All tools enabled by default
+    }),
+};
+/**
+ * AgentRegistry - Singleton registry for managing agent definitions.
+ *
+ * Provides methods to:
+ * - Get agent by name
+ * - List all agents
+ * - List agents by mode (primary, subagent)
+ * - Register custom agents
+ */
+export class AgentRegistry {
+    static instance = null;
+    agents;
+    constructor() {
+        this.agents = new Map();
+        // Register built-in agents
+        for (const [name, agent] of Object.entries(BUILT_IN_AGENTS)) {
+            this.agents.set(name, agent);
+        }
+    }
+    /**
+     * Get the singleton instance of AgentRegistry.
+     */
+    static getInstance() {
+        if (!AgentRegistry.instance) {
+            AgentRegistry.instance = new AgentRegistry();
+        }
+        return AgentRegistry.instance;
+    }
+    /**
+     * Reset the singleton instance (for testing).
+     */
+    static reset() {
+        AgentRegistry.instance = null;
+    }
+    /**
+     * Get an agent by name.
+     * @param name - Agent name
+     * @returns Agent info or undefined if not found
+     */
+    get(name) {
+        return this.agents.get(name);
+    }
+    /**
+     * Get agent names as a formatted list for display.
+     * @returns Formatted string of agent names and descriptions
+     */
+    getSubagentDescriptions() {
+        return this.listSubagents()
+            .map((agent) => `- ${agent.name}: ${agent.description || 'No description'}`)
+            .join('\n');
+    }
+    /**
+     * Check if an agent exists.
+     * @param name - Agent name
+     * @returns true if agent exists
+     */
+    has(name) {
+        return this.agents.has(name);
+    }
+    /**
+     * List all registered agents.
+     * @returns Array of agent info objects
+     */
+    list() {
+        return [...this.agents.values()];
+    }
+    /**
+     * List agents by mode.
+     * @param mode - Agent mode to filter by
+     * @returns Array of agents matching the mode
+     */
+    listByMode(mode) {
+        return this.list().filter((agent) => {
+            if (mode === 'all')
+                return true;
+            return agent.mode === mode || agent.mode === 'all';
+        });
+    }
+    /**
+     * List primary agents available for direct user interaction.
+     * Returns agents that can be used as entry points (mode: 'primary' or 'all').
+     * Excludes hidden agents.
+     * @returns Array of primary agent info objects
+     */
+    listPrimaryAgents() {
+        return this.list().filter((agent) => !agent.hidden && (agent.mode === 'primary' || agent.mode === 'all'));
+    }
+    /**
+     * List subagents available for TaskTool.
+     * Returns agents that can be invoked as subagents (mode: 'subagent' or 'all').
+     * Excludes hidden agents.
+     * @returns Array of subagent info objects
+     */
+    listSubagents() {
+        return this.list().filter((agent) => !agent.hidden && (agent.mode === 'subagent' || agent.mode === 'all'));
+    }
+    /**
+     * Register a custom agent.
+     * @param agent - Agent info to register
+     * @throws Error if agent with same name already exists (unless overwrite is true)
+     */
+    register(agent, overwrite = false) {
+        const validated = AgentInfoSchema.parse(agent);
+        if (this.agents.has(validated.name) && !overwrite) {
+            throw new Error(`Agent '${validated.name}' already exists. Use overwrite=true to replace.`);
+        }
+        this.agents.set(validated.name, validated);
+    }
+    /**
+     * Unregister an agent.
+     * @param name - Agent name to remove
+     * @returns true if agent was removed, false if not found
+     */
+    unregister(name) {
+        return this.agents.delete(name);
+    }
+}
+/**
+ * Convenience function to get the AgentRegistry instance.
+ */
+export function getAgentRegistry() {
+    return AgentRegistry.getInstance();
+}

package/dist/agent/core/domain/environment/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Environment context information.
+ * Provides awareness of the operating environment for agents and sandbox execution.
+ */
+export interface EnvironmentContext {
+    /** Formatted .brv directory structure explanation */
+    brvStructure: string;
+    /** Formatted project file tree */
+    fileTree: string;
+    /** Whether the working directory is a git repository */
+    isGitRepository: boolean;
+    /** Node.js version */
+    nodeVersion: string;
+    /** Operating system version */
+    osVersion: string;
+    /** Operating system platform (darwin, linux, win32) */
+    platform: string;
+    /** Absolute path to the working directory */
+    workingDirectory: string;
+}

package/dist/agent/core/domain/folder-pack/index.d.ts

@@ -0,0 +1 @@
+export type { FolderPackConfig, FolderPackResult, PackedFile, PackPhase, PackProgress, PackProgressCallback, SkippedFile, SkipReason, } from './types.js';

package/dist/agent/core/domain/folder-pack/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Configuration options for folder packing operations.
+ * Controls which files to include, exclude, and how to process them.
+ */
+export interface FolderPackConfig {
+    /** Whether to extract text from Office documents (docx, xlsx, pptx). Default: false */
+    extractDocuments: boolean;
+    /** Whether to extract text from PDF files. Default: true */
+    extractPdfText: boolean;
+    /** Additional glob patterns to ignore (merged with defaults) */
+    ignore: string[];
+    /** Glob patterns for files to include. Default: all files */
+    include: string[];
+    /** Whether to include directory tree in the output. Default: true */
+    includeTree: boolean;
+    /** Maximum file size in bytes to include. Default: 10MB */
+    maxFileSize: number;
+    /** Maximum number of lines to read per file. Default: 10000 */
+    maxLinesPerFile: number;
+    /** Whether to respect .gitignore rules. Default: true */
+    useGitignore: boolean;
+}
+/**
+ * Reasons why a file might be skipped during packing.
+ */
+export type SkipReason = 'binary' | 'encoding' | 'permission' | 'read-error' | 'size-limit';
+/**
+ * Represents a single packed file with its content and metadata.
+ */
+export interface PackedFile {
+    /** File content as string */
+    content: string;
+    /** Detected file type (e.g., 'pdf', 'code', 'text') */
+    fileType?: string;
+    /** Number of lines in the content */
+    lineCount: number;
+    /** Relative path from the root folder */
+    path: string;
+    /** File size in bytes */
+    size: number;
+    /** Whether the content was truncated */
+    truncated: boolean;
+}
+/**
+ * Represents a file that was skipped during packing.
+ */
+export interface SkippedFile {
+    /** Optional error message with details */
+    message?: string;
+    /** Relative path from the root folder */
+    path: string;
+    /** Reason why the file was skipped */
+    reason: SkipReason;
+}
+/**
+ * Result of a folder packing operation.
+ */
+export interface FolderPackResult {
+    /** Configuration used for this pack operation */
+    config: FolderPackConfig;
+    /** Directory tree representation */
+    directoryTree: string;
+    /** Processing duration in milliseconds */
+    durationMs: number;
+    /** Number of files successfully packed */
+    fileCount: number;
+    /** Array of successfully packed files */
+    files: PackedFile[];
+    /** Absolute path to the root folder that was packed */
+    rootPath: string;
+    /** Number of files skipped */
+    skippedCount: number;
+    /** Array of files that were skipped */
+    skippedFiles: SkippedFile[];
+    /** Total character count across all packed files */
+    totalCharacters: number;
+    /** Total line count across all packed files */
+    totalLines: number;
+}
+/**
+ * Progress phases during folder packing.
+ */
+export type PackPhase = 'collecting' | 'generating' | 'searching';
+/**
+ * Progress information during folder packing.
+ * Used for streaming progress updates to the UI.
+ */
+export interface PackProgress {
+    /** Number of items processed so far */
+    current: number;
+    /** Human-readable progress message */
+    message: string;
+    /** Current phase of the packing operation */
+    phase: PackPhase;
+    /** Total number of items to process (if known) */
+    total?: number;
+}
+/**
+ * Callback function for receiving progress updates.
+ */
+export type PackProgressCallback = (progress: PackProgress) => void;

package/dist/agent/core/domain/sandbox/constants.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sandbox constants for code execution security.
+ * Following design patterns from rlm/rlm/environments/local_repl.py
+ */
+/**
+ * Safe globals allowed in sandbox.
+ * These are standard JavaScript built-ins that are safe for sandboxed execution.
+ */
+export declare const ALLOWED_GLOBALS: readonly ["console", "Object", "Array", "String", "Number", "Boolean", "Symbol", "BigInt", "Map", "Set", "WeakMap", "WeakSet", "Date", "RegExp", "Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError", "EvalError", "URIError", "AggregateError", "Promise", "Proxy", "Reflect", "Math", "JSON", "Intl", "ArrayBuffer", "SharedArrayBuffer", "DataView", "Int8Array", "Uint8Array", "Uint8ClampedArray", "Int16Array", "Uint16Array", "Int32Array", "Uint32Array", "Float32Array", "Float64Array", "BigInt64Array", "BigUint64Array", "parseInt", "parseFloat", "isNaN", "isFinite", "encodeURI", "decodeURI", "encodeURIComponent", "decodeURIComponent", "atob", "btoa", "setTimeout", "setInterval", "clearTimeout", "clearInterval", "NaN", "Infinity", "undefined"];
+/**
+ * Explicitly blocked globals for security.
+ * These are NOT available in the sandbox.
+ */
+export declare const BLOCKED_GLOBALS: readonly ["eval", "Function", "require", "import", "process", "global", "globalThis", "__dirname", "__filename", "Buffer", "fetch", "XMLHttpRequest", "WebSocket"];
+/**
+ * Default timeout for sandbox execution (30 seconds).
+ */
+export declare const DEFAULT_SANDBOX_TIMEOUT = 30000;
+/**
+ * Maximum timeout for sandbox execution (5 minutes).
+ */
+export declare const MAX_SANDBOX_TIMEOUT = 300000;
+/**
+ * Whitelisted packages available in sandbox.
+ * Focused on data processing and computation (no file system access).
+ */
+export declare const ALLOWED_PACKAGES: readonly ["lodash", "ramda", "change-case", "pluralize", "escape-string-regexp", "slugify", "minimatch", "micromatch", "zod", "validator", "json5", "yaml", "date-fns", "dayjs", "mathjs", "decimal.js", "uuid", "nanoid"];