byterover-cli 0.2.0 → 0.3.0

package/dist/config/environment.js

@@ -15,18 +15,20 @@ export const ENV_CONFIG = {
         clientId: 'byterover-cli-client',
         cogitApiBaseUrl: 'https://dev-beta-cogit.byterover.dev/api/v1',
         issuerUrl: 'https://dev-beta-iam.byterover.dev/api/v1/oidc',
+        llmGrpcEndpoint: 'dev-beta-llm-grpc.byterover.dev',
         memoraApiBaseUrl: 'https://dev-beta-memora-retrieve.byterover.dev/api/v3',
         mixpanelToken: '258e1a2b3d44cc634ef28964771b1da0',
         scopes: ['read', 'write', 'debug'],
         tokenUrl: 'https://dev-beta-iam.byterover.dev/api/v1/oidc/token',
-        webAppUrl: 'https://dev-beta-app.byterover.dev/',
+        webAppUrl: 'https://dev-beta-app.byterover.dev',
     },
     production: {
         apiBaseUrl: 'https://beta-iam.byterover.dev/api/v1',
         authorizationUrl: 'https://beta-iam.byterover.dev/api/v1/oidc/authorize',
         clientId: 'byterover-cli',
-        cogitApiBaseUrl: 'https://beta-cogit.byterover.dev/api/v1',
+        cogitApiBaseUrl: 'https://beta-cgit.byterover.dev/api/v1',
         issuerUrl: 'https://beta-iam.byterover.dev/api/v1/oidc',
+        llmGrpcEndpoint: 'beta-llm-grpc.byterover.dev',
         memoraApiBaseUrl: 'https://beta-memora-retrieve.byterover.dev/api/v3',
         mixpanelToken: '4d1198b346d2d6ac75f2e77905cc65ac',
         scopes: ['read', 'write'],
@@ -39,3 +41,8 @@ export const ENV_CONFIG = {
  * @returns The environment configuration.
  */
 export const getCurrentConfig = () => ENV_CONFIG[ENVIRONMENT];
+/**
+ * Check if the current environment is development.
+ * @returns True if in development mode, false otherwise.
+ */
+export const isDevelopment = () => ENVIRONMENT === 'development';

package/dist/constants.d.ts

@@ -1,11 +1,16 @@
 export declare const BRV_DIR = ".brv";
 export declare const PROJECT_CONFIG_FILE = "config.json";
+export declare const BRV_CONFIG_VERSION = "0.0.1";
 export declare const ACE_DIR = "ace";
 export declare const EXECUTOR_OUTPUTS_DIR = "executor-outputs";
 export declare const REFLECTIONS_DIR = "reflections";
 export declare const DELTAS_DIR = "deltas";
 export declare const BULLETS_DIR = "bullets";
 export declare const PLAYBOOK_FILE = "playbook.json";
+export declare const PROJECT = "byterover";
+export declare const CONTEXT_TREE_DIR = "context-tree";
+export declare const CONTEXT_FILE = "context.md";
+export declare const SNAPSHOT_FILE = ".snapshot.json";
 /**
  * Default ByteRover branch name for memory storage.
  * This is ByteRover's internal branching mechanism, not Git branches.

package/dist/constants.js

@@ -1,5 +1,6 @@
 export const BRV_DIR = '.brv';
 export const PROJECT_CONFIG_FILE = 'config.json';
+export const BRV_CONFIG_VERSION = '0.0.1';
 // ACE directory structure constants
 export const ACE_DIR = 'ace';
 export const EXECUTOR_OUTPUTS_DIR = 'executor-outputs';
@@ -7,6 +8,11 @@ export const REFLECTIONS_DIR = 'reflections';
 export const DELTAS_DIR = 'deltas';
 export const BULLETS_DIR = 'bullets';
 export const PLAYBOOK_FILE = 'playbook.json';
+export const PROJECT = 'byterover';
+// Context Tree directory structure constants
+export const CONTEXT_TREE_DIR = 'context-tree';
+export const CONTEXT_FILE = 'context.md';
+export const SNAPSHOT_FILE = '.snapshot.json';
 /**
  * Default ByteRover branch name for memory storage.
  * This is ByteRover's internal branching mechanism, not Git branches.

package/dist/core/domain/cipher/agent/agent-state-machine.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Agent State Machine
+ *
+ * Implements a finite state machine for agent execution, following gemini-cli patterns.
+ * Manages state transitions, termination checks, and execution metrics.
+ *
+ * State Transitions:
+ * - IDLE → EXECUTING (start execution)
+ * - EXECUTING → TOOL_CALLING (tool calls in response)
+ * - EXECUTING → COMPLETE (no tool calls, task done)
+ * - EXECUTING → ERROR (execution failed)
+ * - EXECUTING → ABORTED (externally cancelled)
+ * - TOOL_CALLING → EXECUTING (tools executed, continue)
+ * - TOOL_CALLING → ERROR (tool execution failed)
+ * - TOOL_CALLING → ABORTED (externally cancelled)
+ */
+import { AgentExecutionContext, AgentState, TerminationReason } from './agent-state.js';
+/**
+ * Agent State Machine.
+ *
+ * Manages the execution state of an agent, including:
+ * - State transitions with validation
+ * - Termination condition checks (timeout, max turns)
+ * - Execution metrics (turn count, tool calls)
+ *
+ * @example
+ * ```typescript
+ * const sm = new AgentStateMachine(50, 600_000) // 50 turns, 10 min timeout
+ * sm.transition(AgentState.EXECUTING)
+ *
+ * while (!sm.isTerminal()) {
+ *   const reason = sm.shouldTerminate()
+ *   if (reason) break
+ *
+ *   // Execute iteration...
+ *   sm.incrementTurn()
+ * }
+ *
+ * sm.complete() // or sm.fail(error) or sm.abort()
+ * ```
+ */
+export declare class AgentStateMachine {
+    private readonly maxTurns;
+    private readonly maxTimeMs;
+    private context;
+    private state;
+    /**
+     * Create a new agent state machine.
+     *
+     * @param maxTurns - Maximum number of turns before MAX_TURNS termination
+     * @param maxTimeMs - Maximum execution time in milliseconds before TIMEOUT
+     */
+    constructor(maxTurns: number, maxTimeMs: number);
+    /**
+     * Abort the execution externally.
+     *
+     * Transitions to ABORTED state and sets termination reason.
+     * Can be called from any non-terminal state.
+     */
+    abort(): void;
+    /**
+     * Complete the execution successfully.
+     *
+     * Transitions to COMPLETE state and sets GOAL as termination reason.
+     * Should be called when the LLM returns a response without tool calls.
+     */
+    complete(): void;
+    /**
+     * Fail the execution with an error.
+     *
+     * Transitions to ERROR state and stores the error.
+     * Should be called when an unrecoverable error occurs.
+     *
+     * @param error - The error that caused the failure
+     */
+    fail(error: Error): void;
+    /**
+     * Get a readonly copy of the current execution context.
+     *
+     * @returns Copy of the execution context
+     */
+    getContext(): Readonly<AgentExecutionContext>;
+    /**
+     * Get the current state.
+     *
+     * @returns Current agent state
+     */
+    getState(): AgentState;
+    /**
+     * Increment the turn counter.
+     *
+     * Should be called after each iteration of the agentic loop.
+     */
+    incrementTurn(): void;
+    /**
+     * Check if the state machine is in a terminal state.
+     *
+     * Terminal states are: COMPLETE, ERROR, ABORTED
+     *
+     * @returns True if in a terminal state
+     */
+    isTerminal(): boolean;
+    /**
+     * Record a tool call execution.
+     *
+     * Should be called after each tool is executed.
+     */
+    recordToolCall(): void;
+    /**
+     * Check if the execution should terminate.
+     *
+     * Checks for:
+     * - MAX_TURNS: Turn count >= maxTurns
+     * - TIMEOUT: Elapsed time > maxTimeMs
+     *
+     * @returns Termination reason if should terminate, null otherwise
+     */
+    shouldTerminate(): null | TerminationReason;
+    /**
+     * Transition to a new state.
+     *
+     * Validates the transition is allowed, then updates the state.
+     *
+     * @param newState - Target state
+     * @throws Error if the transition is not valid
+     */
+    transition(newState: AgentState): void;
+}

package/dist/core/domain/cipher/agent/agent-state-machine.js

@@ -0,0 +1,183 @@
+/**
+ * Agent State Machine
+ *
+ * Implements a finite state machine for agent execution, following gemini-cli patterns.
+ * Manages state transitions, termination checks, and execution metrics.
+ *
+ * State Transitions:
+ * - IDLE → EXECUTING (start execution)
+ * - EXECUTING → TOOL_CALLING (tool calls in response)
+ * - EXECUTING → COMPLETE (no tool calls, task done)
+ * - EXECUTING → ERROR (execution failed)
+ * - EXECUTING → ABORTED (externally cancelled)
+ * - TOOL_CALLING → EXECUTING (tools executed, continue)
+ * - TOOL_CALLING → ERROR (tool execution failed)
+ * - TOOL_CALLING → ABORTED (externally cancelled)
+ */
+import { AgentState, TerminationReason } from './agent-state.js';
+/**
+ * Valid state transitions for the agent FSM.
+ * Each state maps to an array of valid target states.
+ */
+const VALID_TRANSITIONS = {
+    [AgentState.ABORTED]: [],
+    [AgentState.COMPLETE]: [],
+    [AgentState.ERROR]: [],
+    [AgentState.EXECUTING]: [AgentState.TOOL_CALLING, AgentState.COMPLETE, AgentState.ERROR, AgentState.ABORTED],
+    [AgentState.IDLE]: [AgentState.EXECUTING],
+    [AgentState.TOOL_CALLING]: [AgentState.EXECUTING, AgentState.ERROR, AgentState.ABORTED],
+};
+/**
+ * Agent State Machine.
+ *
+ * Manages the execution state of an agent, including:
+ * - State transitions with validation
+ * - Termination condition checks (timeout, max turns)
+ * - Execution metrics (turn count, tool calls)
+ *
+ * @example
+ * ```typescript
+ * const sm = new AgentStateMachine(50, 600_000) // 50 turns, 10 min timeout
+ * sm.transition(AgentState.EXECUTING)
+ *
+ * while (!sm.isTerminal()) {
+ *   const reason = sm.shouldTerminate()
+ *   if (reason) break
+ *
+ *   // Execute iteration...
+ *   sm.incrementTurn()
+ * }
+ *
+ * sm.complete() // or sm.fail(error) or sm.abort()
+ * ```
+ */
+export class AgentStateMachine {
+    maxTurns;
+    maxTimeMs;
+    context;
+    state = AgentState.IDLE;
+    /**
+     * Create a new agent state machine.
+     *
+     * @param maxTurns - Maximum number of turns before MAX_TURNS termination
+     * @param maxTimeMs - Maximum execution time in milliseconds before TIMEOUT
+     */
+    constructor(maxTurns, maxTimeMs) {
+        this.maxTurns = maxTurns;
+        this.maxTimeMs = maxTimeMs;
+        this.context = {
+            startTime: new Date(),
+            state: AgentState.IDLE,
+            toolCallsExecuted: 0,
+            turnCount: 0,
+        };
+    }
+    /**
+     * Abort the execution externally.
+     *
+     * Transitions to ABORTED state and sets termination reason.
+     * Can be called from any non-terminal state.
+     */
+    abort() {
+        this.transition(AgentState.ABORTED);
+        this.context.terminationReason = TerminationReason.ABORTED;
+    }
+    /**
+     * Complete the execution successfully.
+     *
+     * Transitions to COMPLETE state and sets GOAL as termination reason.
+     * Should be called when the LLM returns a response without tool calls.
+     */
+    complete() {
+        this.transition(AgentState.COMPLETE);
+        this.context.terminationReason = TerminationReason.GOAL;
+    }
+    /**
+     * Fail the execution with an error.
+     *
+     * Transitions to ERROR state and stores the error.
+     * Should be called when an unrecoverable error occurs.
+     *
+     * @param error - The error that caused the failure
+     */
+    fail(error) {
+        this.transition(AgentState.ERROR);
+        this.context.terminationReason = TerminationReason.ERROR;
+        this.context.lastError = error;
+    }
+    /**
+     * Get a readonly copy of the current execution context.
+     *
+     * @returns Copy of the execution context
+     */
+    getContext() {
+        return { ...this.context };
+    }
+    /**
+     * Get the current state.
+     *
+     * @returns Current agent state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Increment the turn counter.
+     *
+     * Should be called after each iteration of the agentic loop.
+     */
+    incrementTurn() {
+        this.context.turnCount++;
+    }
+    /**
+     * Check if the state machine is in a terminal state.
+     *
+     * Terminal states are: COMPLETE, ERROR, ABORTED
+     *
+     * @returns True if in a terminal state
+     */
+    isTerminal() {
+        return [AgentState.ABORTED, AgentState.COMPLETE, AgentState.ERROR].includes(this.state);
+    }
+    /**
+     * Record a tool call execution.
+     *
+     * Should be called after each tool is executed.
+     */
+    recordToolCall() {
+        this.context.toolCallsExecuted++;
+    }
+    /**
+     * Check if the execution should terminate.
+     *
+     * Checks for:
+     * - MAX_TURNS: Turn count >= maxTurns
+     * - TIMEOUT: Elapsed time > maxTimeMs
+     *
+     * @returns Termination reason if should terminate, null otherwise
+     */
+    shouldTerminate() {
+        if (this.context.turnCount >= this.maxTurns) {
+            return TerminationReason.MAX_TURNS;
+        }
+        if (Date.now() - this.context.startTime.getTime() > this.maxTimeMs) {
+            return TerminationReason.TIMEOUT;
+        }
+        return null;
+    }
+    /**
+     * Transition to a new state.
+     *
+     * Validates the transition is allowed, then updates the state.
+     *
+     * @param newState - Target state
+     * @throws Error if the transition is not valid
+     */
+    transition(newState) {
+        if (!VALID_TRANSITIONS[this.state].includes(newState)) {
+            throw new Error(`Invalid state transition: ${this.state} → ${newState}`);
+        }
+        this.state = newState;
+        this.context.state = newState;
+    }
+}

package/dist/core/domain/cipher/agent/agent-state.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Agent State Types
+ *
+ * Defines the state machine for agent execution, following gemini-cli patterns.
+ * Provides explicit states and termination reasons for better observability
+ * and control over the agentic loop.
+ */
+/**
+ * Agent execution states.
+ *
+ * These states represent the current phase of agent execution:
+ * - IDLE: Not executing, waiting for input
+ * - EXECUTING: Processing LLM response
+ * - TOOL_CALLING: Executing tool calls
+ * - COMPLETE: Task finished successfully
+ * - ERROR: Terminated with error
+ * - ABORTED: Externally cancelled
+ */
+export declare enum AgentState {
+    /** Externally cancelled */
+    ABORTED = "ABORTED",
+    /** Task finished successfully */
+    COMPLETE = "COMPLETE",
+    /** Terminated with error */
+    ERROR = "ERROR",
+    /** Processing LLM response */
+    EXECUTING = "EXECUTING",
+    /** Not executing, waiting for input */
+    IDLE = "IDLE",
+    /** Executing tool calls */
+    TOOL_CALLING = "TOOL_CALLING"
+}
+/**
+ * Termination reasons for agent execution.
+ *
+ * When an agent stops executing, one of these reasons explains why:
+ * - GOAL: Task completed successfully (no more tool calls)
+ * - TIMEOUT: Max execution time exceeded
+ * - MAX_TURNS: Iteration limit reached
+ * - ERROR: Unexpected failure during execution
+ * - ABORTED: External cancellation (e.g., abort signal)
+ * - PROTOCOL_VIOLATION: Invalid state transition or response
+ */
+export declare enum TerminationReason {
+    /** External cancellation (e.g., abort signal) */
+    ABORTED = "ABORTED",
+    /** Unexpected failure during execution */
+    ERROR = "ERROR",
+    /** Task completed successfully (no tool calls in response) */
+    GOAL = "GOAL",
+    /** Iteration limit reached */
+    MAX_TURNS = "MAX_TURNS",
+    /** Invalid state transition or malformed response */
+    PROTOCOL_VIOLATION = "PROTOCOL_VIOLATION",
+    /** Max execution time exceeded */
+    TIMEOUT = "TIMEOUT"
+}
+/**
+ * Execution context with state tracking.
+ *
+ * Captures the current state and metrics of an agent execution,
+ * including timing, turn count, and tool call statistics.
+ */
+export interface AgentExecutionContext {
+    /** Last error if terminated with ERROR */
+    lastError?: Error;
+    /** When this execution started */
+    startTime: Date;
+    /** Current state of the agent */
+    state: AgentState;
+    /** Why the execution terminated (if complete) */
+    terminationReason?: TerminationReason;
+    /** Number of tool calls executed */
+    toolCallsExecuted: number;
+    /** Number of turns (iterations) completed */
+    turnCount: number;
+}

package/dist/core/domain/cipher/agent/agent-state.js

@@ -0,0 +1,59 @@
+/**
+ * Agent State Types
+ *
+ * Defines the state machine for agent execution, following gemini-cli patterns.
+ * Provides explicit states and termination reasons for better observability
+ * and control over the agentic loop.
+ */
+/**
+ * Agent execution states.
+ *
+ * These states represent the current phase of agent execution:
+ * - IDLE: Not executing, waiting for input
+ * - EXECUTING: Processing LLM response
+ * - TOOL_CALLING: Executing tool calls
+ * - COMPLETE: Task finished successfully
+ * - ERROR: Terminated with error
+ * - ABORTED: Externally cancelled
+ */
+export var AgentState;
+(function (AgentState) {
+    /** Externally cancelled */
+    AgentState["ABORTED"] = "ABORTED";
+    /** Task finished successfully */
+    AgentState["COMPLETE"] = "COMPLETE";
+    /** Terminated with error */
+    AgentState["ERROR"] = "ERROR";
+    /** Processing LLM response */
+    AgentState["EXECUTING"] = "EXECUTING";
+    /** Not executing, waiting for input */
+    AgentState["IDLE"] = "IDLE";
+    /** Executing tool calls */
+    AgentState["TOOL_CALLING"] = "TOOL_CALLING";
+})(AgentState || (AgentState = {}));
+/**
+ * Termination reasons for agent execution.
+ *
+ * When an agent stops executing, one of these reasons explains why:
+ * - GOAL: Task completed successfully (no more tool calls)
+ * - TIMEOUT: Max execution time exceeded
+ * - MAX_TURNS: Iteration limit reached
+ * - ERROR: Unexpected failure during execution
+ * - ABORTED: External cancellation (e.g., abort signal)
+ * - PROTOCOL_VIOLATION: Invalid state transition or response
+ */
+export var TerminationReason;
+(function (TerminationReason) {
+    /** External cancellation (e.g., abort signal) */
+    TerminationReason["ABORTED"] = "ABORTED";
+    /** Unexpected failure during execution */
+    TerminationReason["ERROR"] = "ERROR";
+    /** Task completed successfully (no tool calls in response) */
+    TerminationReason["GOAL"] = "GOAL";
+    /** Iteration limit reached */
+    TerminationReason["MAX_TURNS"] = "MAX_TURNS";
+    /** Invalid state transition or malformed response */
+    TerminationReason["PROTOCOL_VIOLATION"] = "PROTOCOL_VIOLATION";
+    /** Max execution time exceeded */
+    TerminationReason["TIMEOUT"] = "TIMEOUT";
+})(TerminationReason || (TerminationReason = {}));

package/dist/core/domain/cipher/agent/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Agent Module
+ *
+ * Exports agent state management types and classes.
+ */
+export { AgentStateMachine } from './agent-state-machine.js';
+export { AgentExecutionContext, AgentState, TerminationReason } from './agent-state.js';

package/dist/core/domain/cipher/agent/index.js

@@ -0,0 +1,7 @@
+/**
+ * Agent Module
+ *
+ * Exports agent state management types and classes.
+ */
+export { AgentStateMachine } from './agent-state-machine.js';
+export { AgentState, TerminationReason } from './agent-state.js';

package/dist/core/domain/cipher/agent-events/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Event system types and constants.
+ *
+ * This module provides type-safe event definitions for CipherAgent's event-driven architecture.
+ * Follows the pattern from Dexto's event system.
+ */
+export type { AgentEventMap, AgentEventName, EventName, SessionEventMap, SessionEventName, TokenUsage, } from './types.js';
+export { AGENT_EVENT_NAMES, EVENT_NAMES, SESSION_EVENT_NAMES } from './types.js';

package/dist/core/domain/cipher/agent-events/index.js

@@ -0,0 +1,7 @@
+/**
+ * Event system types and constants.
+ *
+ * This module provides type-safe event definitions for CipherAgent's event-driven architecture.
+ * Follows the pattern from Dexto's event system.
+ */
+export { AGENT_EVENT_NAMES, EVENT_NAMES, SESSION_EVENT_NAMES } from './types.js';