byterover-cli 1.5.0 → 1.7.0

package/dist/agent/core/domain/sandbox/constants.js

@@ -0,0 +1,134 @@
+/**
+ * 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 const ALLOWED_GLOBALS = [
+    // Console (custom safe version that captures output)
+    'console',
+    // Core constructors
+    '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 and JSON
+    'Math',
+    'JSON',
+    'Intl',
+    // Typed Arrays
+    'ArrayBuffer',
+    'SharedArrayBuffer',
+    'DataView',
+    'Int8Array',
+    'Uint8Array',
+    'Uint8ClampedArray',
+    'Int16Array',
+    'Uint16Array',
+    'Int32Array',
+    'Uint32Array',
+    'Float32Array',
+    'Float64Array',
+    'BigInt64Array',
+    'BigUint64Array',
+    // Utilities
+    'parseInt',
+    'parseFloat',
+    'isNaN',
+    'isFinite',
+    'encodeURI',
+    'decodeURI',
+    'encodeURIComponent',
+    'decodeURIComponent',
+    'atob',
+    'btoa',
+    // Timing (will use safe wrapped versions)
+    'setTimeout',
+    'setInterval',
+    'clearTimeout',
+    'clearInterval',
+    // Other safe globals
+    'NaN',
+    'Infinity',
+    'undefined',
+];
+/**
+ * Explicitly blocked globals for security.
+ * These are NOT available in the sandbox.
+ */
+export const BLOCKED_GLOBALS = [
+    'eval', // Dynamic code execution
+    'Function', // Can be used like eval
+    'require', // Module loading
+    'import', // Module loading
+    'process', // Node.js process object
+    'global', // Global object access
+    'globalThis', // Global object access
+    '__dirname', // File system info
+    '__filename', // File system info
+    'Buffer', // Can be used for exploits
+    'fetch', // Network access
+    'XMLHttpRequest', // Network access
+    'WebSocket', // Network access
+];
+/**
+ * Default timeout for sandbox execution (30 seconds).
+ */
+export const DEFAULT_SANDBOX_TIMEOUT = 30_000;
+/**
+ * Maximum timeout for sandbox execution (5 minutes).
+ */
+export const MAX_SANDBOX_TIMEOUT = 300_000;
+/**
+ * Whitelisted packages available in sandbox.
+ * Focused on data processing and computation (no file system access).
+ */
+export const ALLOWED_PACKAGES = [
+    // Data manipulation & utilities
+    'lodash', // General utilities (map, filter, groupBy, etc.)
+    'ramda', // Functional programming utilities
+    // String & regex processing
+    'change-case', // Case conversion (camelCase, snakeCase, etc.)
+    'pluralize', // Pluralization
+    'escape-string-regexp', // Escape regex special characters
+    'slugify', // URL slug generation
+    // Pattern matching (in-memory, not file-based)
+    'minimatch', // Glob pattern matching for strings
+    'micromatch', // Advanced glob matching
+    // Data validation & transformation
+    'zod', // Schema validation
+    'validator', // String validation (isEmail, isURL, etc.)
+    'json5', // JSON with comments support
+    'yaml', // YAML parsing
+    // Date/time
+    'date-fns', // Date manipulation
+    'dayjs', // Lightweight date library
+    // Math & computation
+    'mathjs', // Advanced math operations
+    'decimal.js', // Arbitrary precision decimals
+    // ID generation
+    'uuid', // UUID generation
+    'nanoid', // Compact ID generation
+];

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

@@ -0,0 +1,2 @@
+export * from './constants.js';
+export * from './types.js';

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

@@ -0,0 +1,2 @@
+export * from './constants.js';
+export * from './types.js';

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

@@ -0,0 +1,30 @@
+/**
+ * Sandbox types for code execution in isolated environment.
+ * Following design patterns from rlm/rlm/environments/local_repl.py
+ */
+/**
+ * Result of code execution in the sandbox.
+ */
+export interface REPLResult {
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Current context state (variable names to values) */
+    locals: Record<string, unknown>;
+    /** Return value of the last expression (if any) */
+    returnValue?: unknown;
+    /** Error output (console.error, console.warn, exceptions) */
+    stderr: string;
+    /** Console output (console.log, console.info) */
+    stdout: string;
+}
+/**
+ * Configuration for sandbox execution.
+ */
+export interface SandboxConfig {
+    /** Context data to preload as "context" variable */
+    contextPayload?: Record<string, unknown> | string | unknown[];
+    /** Language: 'javascript' or 'typescript' (default: auto-detect) */
+    language?: 'javascript' | 'typescript';
+    /** Timeout in ms (default: 30000, max: 300000) */
+    timeout?: number;
+}

package/dist/agent/core/domain/sandbox/types.js

@@ -0,0 +1,5 @@
+/**
+ * Sandbox types for code execution in isolated environment.
+ * Following design patterns from rlm/rlm/environments/local_repl.py
+ */
+export {};

package/dist/agent/core/domain/storage/history-types.d.ts

@@ -0,0 +1,38 @@
+import type { InternalMessage } from '../../interfaces/message-types.js';
+/**
+ * Persisted session history data structure.
+ *
+ * This structure is serialized to JSON and stored in blob storage.
+ * Contains the complete conversation history plus metadata for the session.
+ */
+export interface SessionHistoryData {
+    /** Unix timestamp when session was created */
+    createdAt: number;
+    /** Number of messages in the conversation */
+    messageCount: number;
+    /** All messages in chronological order */
+    messages: InternalMessage[];
+    /** Optional metadata for extensibility */
+    metadata?: Record<string, unknown>;
+    /** Unique session identifier */
+    sessionId: string;
+    /** Unix timestamp of last update */
+    updatedAt: number;
+}
+/**
+ * Lightweight session metadata (stored separately from full history).
+ *
+ * Used for listing sessions without loading full message history.
+ */
+export interface SessionMetadata {
+    /** Unix timestamp when session was created */
+    createdAt: number;
+    /** Unix timestamp of last activity */
+    lastActivity: number;
+    /** Number of messages in the session */
+    messageCount: number;
+    /** Unique session identifier */
+    sessionId: string;
+    /** Optional user-provided or auto-generated title */
+    title?: string;
+}

package/dist/agent/core/domain/storage/message-storage-types.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Types for granular message and part storage.
+ *
+ * This module defines the storage format for the new granular history system,
+ * where messages and parts are stored separately to enable:
+ * - Streaming message loading (newest to oldest)
+ * - Selective tool output pruning
+ * - Compaction boundary markers
+ *
+ * Storage key structure:
+ * - ["session", sessionId] → SessionRecord
+ * - ["message", sessionId, messageId] → StoredMessage
+ * - ["part", messageId, partId] → StoredPart
+ */
+import type { ToolCall } from '../../interfaces/message-types.js';
+/**
+ * Session-level record stored at ["session", sessionId].
+ * Contains metadata and acts as a marker for granular format detection.
+ */
+export interface SessionRecord {
+    /** Unix timestamp when session was created */
+    createdAt: number;
+    /** ID of the latest compaction boundary message, if any */
+    lastCompactionMessageId?: string;
+    /** Total number of messages in the session */
+    messageCount: number;
+    /** ID of the most recent message for efficient iteration */
+    newestMessageId?: string;
+    /** ID of the oldest message for complete traversal */
+    oldestMessageId?: string;
+    /** Unique session identifier */
+    sessionId: string;
+    /** Optional user-provided or auto-generated title */
+    title?: string;
+    /** Unix timestamp of last update */
+    updatedAt: number;
+}
+/**
+ * Individual message stored at ["message", sessionId, messageId].
+ *
+ * Messages are stored individually to enable:
+ * - Streaming from newest to oldest
+ * - Efficient single-message updates
+ * - Compaction boundary markers
+ */
+export interface StoredMessage {
+    /**
+     * Flag indicating this is a compaction boundary.
+     * When loading history, stop at the first compaction boundary.
+     * Messages before this point are summarized and not needed.
+     */
+    compactionBoundary?: boolean;
+    /**
+     * Summary content if this is a compaction boundary message.
+     * Contains the LLM-generated summary of prior conversation.
+     */
+    compactionSummary?: string;
+    /**
+     * The text content of the message.
+     * - null for assistant messages with only tool calls
+     * - string for most messages
+     */
+    content: null | string;
+    /** Unix timestamp when message was created */
+    createdAt: number;
+    /** Unique message identifier (UUID) */
+    id: string;
+    /**
+     * Name of the tool that produced this result.
+     * Only present for tool messages.
+     */
+    name?: string;
+    /** ID of the next message (toward newest) for linked traversal */
+    nextMessageId?: string;
+    /** IDs of parts associated with this message, in order */
+    partIds: string[];
+    /** ID of the previous message (toward oldest) for linked traversal */
+    prevMessageId?: string;
+    /** Optional reasoning text from the model */
+    reasoning?: string;
+    /** Message role */
+    role: 'assistant' | 'system' | 'tool' | 'user';
+    /** Session this message belongs to */
+    sessionId: string;
+    /** Raw thought text from the model (Gemini) */
+    thought?: string;
+    /** Parsed thought summary (Gemini) */
+    thoughtSummary?: {
+        description: string;
+        subject: string;
+    };
+    /**
+     * ID of the tool call this message is responding to.
+     * Only present for tool messages.
+     */
+    toolCallId?: string;
+    /**
+     * Tool calls made by the assistant.
+     * Only present for assistant messages requesting tool execution.
+     */
+    toolCalls?: ToolCall[];
+    /** Unix timestamp of last update */
+    updatedAt: number;
+}
+/**
+ * Tool state as stored in StoredPart.
+ * Mirrors the ToolState types from message-types.ts but optimized for storage.
+ */
+export interface StoredToolState {
+    /** Attachments produced by the tool (images, files) */
+    attachments?: Array<{
+        /** Base64-encoded data or data URL */
+        data: string;
+        /** Original filename if available */
+        filename?: string;
+        /** MIME type of the attachment */
+        mime: string;
+        /** Attachment type */
+        type: 'file' | 'image';
+    }>;
+    /** Unique identifier for this tool call */
+    callId: string;
+    /** Unix timestamp when execution completed */
+    completedAt?: number;
+    /** Error message (only for 'error' status) */
+    error?: string;
+    /** Parsed input arguments */
+    input?: Record<string, unknown>;
+    /** Tool output content (only for 'completed' status) */
+    output?: string;
+    /** Unix timestamp when execution started */
+    startedAt?: number;
+    /** Current status of the tool call */
+    status: 'completed' | 'error' | 'pending' | 'running';
+    /** Human-readable title for display */
+    title?: string;
+}
+/**
+ * Reasoning summary as stored in StoredPart.
+ */
+export interface StoredReasoningSummary {
+    /** Detailed description of the thought */
+    description: string;
+    /** Brief subject of the thought */
+    subject: string;
+}
+/**
+ * Part-level metadata as stored in StoredPart.
+ */
+export interface StoredPartMetadata {
+    /** Custom metadata fields */
+    [key: string]: unknown;
+    /** Anthropic cache control hint */
+    cacheControl?: {
+        type: 'ephemeral' | 'permanent';
+    };
+    /** Whether this is auto-generated content */
+    synthetic?: boolean;
+}
+/**
+ * Message part stored at ["part", messageId, partId].
+ *
+ * Parts contain content that may be pruned independently:
+ * - Tool outputs (large, can be marked as compacted)
+ * - Tool calls with state machine (pending → running → completed/error)
+ * - File attachments
+ * - Image data
+ * - Reasoning/thinking traces
+ *
+ * Parts are stored separately to enable:
+ * - Selective pruning of old tool outputs
+ * - Lazy loading of large content
+ * - Efficient streaming without loading all content
+ * - Tool state tracking with full lifecycle
+ *
+ * Blob references:
+ * - Large binary content (>5KB) can be stored in blob storage
+ * - When stored as blob, content contains "@blob:{id}" reference
+ * - Blob refs are resolved lazily at format-time via BlobReferenceResolver
+ */
+export interface StoredPart {
+    /**
+     * Blob reference ID (without @ prefix) when content is stored externally.
+     * Present when isBlob is true. The actual data can be retrieved from
+     * blob storage using this ID.
+     */
+    blobRef?: string;
+    /**
+     * Unix timestamp when this part was marked as compacted.
+     * If set, the original content has been cleared to save space,
+     * and a placeholder message should be shown instead.
+     */
+    compactedAt?: number;
+    /**
+     * The actual content of the part.
+     * - Tool output: string (JSON or text)
+     * - File: base64 encoded data, file path, or blob reference (@blob:id)
+     * - Text: raw text content
+     * - Image: base64 encoded data or blob reference (@blob:id)
+     * - Reasoning: thinking text from the model
+     * - Tool: empty (state stored in toolState)
+     *
+     * When compactedAt is set, this will be empty or contain a placeholder.
+     * When isBlob is true, this contains the blob reference string.
+     */
+    content: string;
+    /** Unix timestamp when part was created */
+    createdAt: number;
+    /** Original filename for file parts */
+    filename?: string;
+    /** Unique part identifier (UUID) */
+    id: string;
+    /**
+     * Whether the content field contains a blob reference.
+     * When true, content should be resolved via BlobReferenceResolver
+     * before use (at format-time for LLM requests).
+     */
+    isBlob?: boolean;
+    /** ID of the message this part belongs to */
+    messageId: string;
+    /**
+     * Part-level metadata for cache hints and custom data.
+     * Follows OpenCode's pattern for part metadata.
+     */
+    metadata?: StoredPartMetadata;
+    /** MIME type for file and image parts */
+    mimeType?: string;
+    /**
+     * Reasoning summary for 'reasoning' type parts.
+     * Contains parsed subject and description for display.
+     */
+    reasoningSummary?: StoredReasoningSummary;
+    /**
+     * For tool_output parts, the name of the tool.
+     * Used for display and filtering.
+     */
+    toolName?: string;
+    /**
+     * Tool state for 'tool' type parts.
+     * Tracks the full lifecycle: pending → running → completed/error.
+     * Only present when type is 'tool'.
+     */
+    toolState?: StoredToolState;
+    /**
+     * Type of part content.
+     * Extended with 'tool' for tool calls with state machine and 'reasoning' for thinking traces.
+     */
+    type: 'compaction' | 'file' | 'image' | 'reasoning' | 'text' | 'tool' | 'tool_output';
+}
+/**
+ * Placeholder message shown when tool output has been compacted.
+ */
+export declare const COMPACTED_TOOL_OUTPUT_PLACEHOLDER = "[Old tool result content cleared]";
+/**
+ * Result of loading messages with compaction awareness.
+ */
+export interface LoadMessagesResult {
+    /** Whether a compaction boundary was reached */
+    hitCompactionBoundary: boolean;
+    /** Loaded messages in chronological order (oldest first) */
+    messages: StoredMessageWithParts[];
+}
+/**
+ * StoredMessage combined with its resolved parts.
+ * Used when converting back to InternalMessage format.
+ */
+export interface StoredMessageWithParts extends StoredMessage {
+    /** Resolved part objects (not just IDs) */
+    parts: StoredPart[];
+}
+/**
+ * Configuration for message streaming.
+ */
+export interface StreamMessagesOptions {
+    /**
+     * Maximum number of messages to load.
+     * Useful for preview/summary views.
+     */
+    limit?: number;
+    /**
+     * Session ID to stream messages from.
+     */
+    sessionId: string;
+    /**
+     * Whether to stop at the first compaction boundary.
+     * Default: true
+     */
+    stopAtCompaction?: boolean;
+}
+/**
+ * Configuration for tool output pruning.
+ */
+export interface PruneToolOutputsOptions {
+    /**
+     * Target token count to keep in tool outputs.
+     * Tool outputs beyond this (from oldest) will be marked as compacted.
+     * Default: 40000 (same as OpenCode PRUNE_PROTECT)
+     */
+    keepTokens?: number;
+    /**
+     * Minimum tokens that must be recoverable to perform pruning.
+     * If pruning would save less than this, skip it entirely.
+     * Default: 20000 (same as OpenCode PRUNE_MINIMUM)
+     */
+    minimumTokens?: number;
+    /**
+     * Number of recent user turns to protect from pruning.
+     * Tool outputs in these turns will not be compacted.
+     * Default: 2
+     */
+    protectedTurns?: number;
+    /**
+     * Session ID to prune tool outputs from.
+     */
+    sessionId: string;
+}
+/**
+ * Compaction operation result.
+ */
+export interface CompactionResult {
+    /** Number of parts that were compacted */
+    compactedCount: number;
+    /** New compaction boundary message ID */
+    compactionMessageId?: string;
+    /** Estimated tokens saved */
+    tokensSaved: number;
+}

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

@@ -0,0 +1,119 @@
+import type { ExecutionContext } from '../../interfaces/i-cipher-agent.js';
+import type { TokenUsage } from '../agent-events/types.js';
+/**
+ * Streaming event names for CipherAgent.stream()
+ * These are the events exposed via the streaming API for real-time chat UIs.
+ */
+export declare const STREAMING_EVENT_NAMES: readonly ["llmservice:thinking", "llmservice:chunk", "llmservice:response", "llmservice:toolCall", "llmservice:toolResult", "llmservice:error", "llmservice:warning", "message:queued", "message:dequeued", "run:complete"];
+export type StreamingEventName = (typeof STREAMING_EVENT_NAMES)[number];
+/**
+ * Union type of all streaming events with their payloads.
+ * Uses 'name' property as discriminant for type narrowing.
+ */
+export type StreamingEvent = {
+    args: Record<string, unknown>;
+    callId?: string;
+    name: 'llmservice:toolCall';
+    sessionId: string;
+    taskId?: string;
+    toolName: string;
+} | {
+    callId?: string;
+    error?: string;
+    name: 'llmservice:toolResult';
+    result?: unknown;
+    sessionId: string;
+    success: boolean;
+    taskId?: string;
+    toolName: string;
+} | {
+    code?: string;
+    error: string;
+    name: 'llmservice:error';
+    recoverable?: boolean;
+    sessionId: string;
+    taskId?: string;
+} | {
+    content: string;
+    isComplete?: boolean;
+    name: 'llmservice:chunk';
+    sessionId: string;
+    taskId?: string;
+    type: 'reasoning' | 'text';
+} | {
+    content: string;
+    model?: string;
+    name: 'llmservice:response';
+    partial?: boolean;
+    provider?: string;
+    reasoning?: string;
+    sessionId: string;
+    taskId?: string;
+    tokenUsage?: TokenUsage;
+} | {
+    count: number;
+    name: 'message:dequeued';
+    sessionId: string;
+    taskId?: string;
+} | {
+    durationMs: number;
+    error?: Error;
+    finishReason: 'cancelled' | 'error' | 'max-iterations' | 'stop' | 'timeout';
+    name: 'run:complete';
+    sessionId: string;
+    stepCount: number;
+    taskId?: string;
+} | {
+    message: string;
+    name: 'llmservice:warning';
+    sessionId: string;
+    taskId?: string;
+} | {
+    message: {
+        content: string;
+        id: string;
+        queuedAt: number;
+    };
+    name: 'message:queued';
+    position: number;
+    sessionId: string;
+    taskId?: string;
+} | {
+    name: 'llmservice:thinking';
+    sessionId: string;
+    taskId?: string;
+};
+/**
+ * Options for stream() method
+ */
+export interface StreamOptions {
+    /** Execution context */
+    executionContext?: ExecutionContext;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Task ID for concurrent task isolation (included in all emitted events) */
+    taskId?: string;
+}
+/**
+ * Complete response from generate() method (wrapper around stream)
+ */
+export interface GenerateResponse {
+    /** The final response content */
+    content: string;
+    /** Internal reasoning (if available) */
+    reasoning?: string;
+    /** Session ID */
+    sessionId: string;
+    /** Tool calls made during execution */
+    toolCalls: Array<{
+        args: Record<string, unknown>;
+        callId: string;
+        result?: {
+            data: unknown;
+            success: boolean;
+        };
+        toolName: string;
+    }>;
+    /** Token usage statistics */
+    usage: TokenUsage;
+}