byterover-cli 0.2.1 → 0.3.0

package/dist/core/domain/cipher/memory/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Core memory types and interfaces for the cipher agent
+ */
+/**
+ * Supported memory sources
+ */
+export type MemorySource = 'agent' | 'system' | 'user';
+/**
+ * Blob attachment metadata for a memory
+ * References a blob stored in BlobStorage
+ */
+export interface Attachment {
+    /** Reference key to the blob in BlobStorage */
+    blobKey: string;
+    /** Timestamp when the attachment was added (Unix timestamp in milliseconds) */
+    createdAt: number;
+    /** Original filename (if applicable) */
+    name?: string;
+    /** Size of the attachment in bytes */
+    size: number;
+    /** MIME type of the attachment */
+    type: string;
+}
+/**
+ * Memory item stored in the cipher agent system
+ */
+export interface Memory {
+    /** The actual memory content */
+    content: string;
+    /** When the memory was created (Unix timestamp in milliseconds) */
+    createdAt: number;
+    /** Unique identifier for the memory */
+    id: string;
+    /** Additional metadata */
+    metadata?: undefined | {
+        /** Any additional custom metadata */
+        [key: string]: unknown;
+        /** Whether this memory is pinned (for future hybrid approach) */
+        pinned?: boolean | undefined;
+        /** Source of the memory */
+        source?: MemorySource | undefined;
+    };
+    /** Optional tags for categorization */
+    tags?: string[] | undefined;
+    /** When the memory was last updated (Unix timestamp in milliseconds) */
+    updatedAt: number;
+}
+/**
+ * Input for creating a new memory
+ */
+export interface CreateMemoryInput {
+    /** The memory content */
+    content: string;
+    /** Optional metadata */
+    metadata?: {
+        [key: string]: unknown;
+        source?: MemorySource;
+    };
+    /** Optional tags */
+    tags?: string[];
+}
+/**
+ * Input for updating an existing memory
+ */
+export interface UpdateMemoryInput {
+    /** Updated content (optional) */
+    content?: string;
+    /** Updated metadata (optional, merges with existing) */
+    metadata?: {
+        [key: string]: unknown;
+        pinned?: boolean;
+        source?: MemorySource;
+    };
+    /** Updated tags (optional, replaces existing) */
+    tags?: string[];
+}
+/**
+ * Options for listing memories
+ */
+export interface ListMemoriesOptions {
+    /** Limit number of results */
+    limit?: number;
+    /** Skip first N results */
+    offset?: number;
+    /** Filter by pinned status */
+    pinned?: boolean;
+    /** Filter by source */
+    source?: MemorySource;
+    /** Filter by tags (OR logic - matches any of the provided tags) */
+    tags?: string[];
+}
+/**
+ * Configuration for the cipher agent memory service
+ */
+export interface MemoryConfig {
+    /** Default tags to apply to all memories created by the agent */
+    defaultTags?: string[];
+    /** Maximum number of memories to keep (optional limit) */
+    maxMemories?: number;
+    /** Directory where memories are stored (default: .byterover/cipher/memories) */
+    storageDir?: string;
+}

package/dist/core/domain/cipher/memory/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core memory types and interfaces for the cipher agent
+ */
+export {};

package/dist/core/domain/cipher/parsed-interaction.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Represents a parsed interaction between a user and a coding agent.
+ * This entity captures valuable interaction data from coding agent logs
+ * (Claude Code, GitHub Copilot, Cursor, Codex, etc.).
+ *
+ * @deprecated Use CleanSession from '../entities/parser.js' instead.
+ * ParsedInteraction is a lossy format that only captures single Q&A pairs.
+ * CleanSession preserves full conversation history, tool calls, thinking blocks, and workspace context.
+ */
+export type ParsedInteraction = {
+    /** Agent's response  */
+    readonly agentResponse: string;
+    /** Type of coding agent (e.g., 'claude-code', 'copilot', 'cursor') */
+    readonly agentType: string;
+    /** Additional metadata about the interaction */
+    readonly metadata?: Record<string, unknown>;
+    /** Timestamp of the interaction */
+    readonly timestamp: number;
+    /** Tool calls made by the agent, if any */
+    readonly toolCalls?: ToolCall[];
+    /** User's message or prompt */
+    readonly userMessage: string;
+};
+/**
+ * Represents a tool call made by a coding agent.
+ */
+type ToolCall = {
+    /** Tool input/parameters */
+    readonly input: Record<string, unknown>;
+    /** Name of the tool */
+    readonly name: string;
+    /** Tool output/result, if available */
+    readonly output?: unknown;
+};
+type CreateParsedInteractionParams = {
+    agentResponse: string;
+    agentType: string;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+    toolCalls?: ToolCall[];
+    userMessage: string;
+};
+/**
+ * Factory function to create a ParsedInteraction with validation.
+ */
+export declare const createParsedInteraction: (params: CreateParsedInteractionParams) => ParsedInteraction;
+export {};

package/dist/core/domain/cipher/parsed-interaction.js

@@ -0,0 +1,25 @@
+/**
+ * Factory function to create a ParsedInteraction with validation.
+ */
+export const createParsedInteraction = (params) => {
+    if (params.agentType.trim() === '') {
+        throw new Error('agentType is required');
+    }
+    if (params.userMessage.trim() === '') {
+        throw new Error('userMessage is required');
+    }
+    if (params.agentResponse.trim() === '') {
+        throw new Error('agentResponse is required');
+    }
+    if (params.timestamp <= 0) {
+        throw new Error('timestamp must be a positive number');
+    }
+    return {
+        agentResponse: params.agentResponse,
+        agentType: params.agentType,
+        metadata: params.metadata,
+        timestamp: params.timestamp,
+        toolCalls: params.toolCalls,
+        userMessage: params.userMessage,
+    };
+};

package/dist/core/domain/cipher/process/types.d.ts

@@ -0,0 +1,286 @@
+import type { ChildProcess } from 'node:child_process';
+/**
+ * Process execution configuration.
+ *
+ * Defines security settings, resource limits, and environment for command execution.
+ */
+export interface ProcessConfig {
+    /**
+     * Allowed commands whitelist (empty = all allowed with approval).
+     */
+    allowedCommands: string[];
+    /**
+     * Blocked commands blacklist.
+     */
+    blockedCommands: string[];
+    /**
+     * Custom environment variables for all commands.
+     */
+    environment: Record<string, string>;
+    /**
+     * Maximum number of concurrent background processes.
+     * @default 5
+     */
+    maxConcurrentProcesses: number;
+    /**
+     * Maximum output buffer size per background process (bytes).
+     * @default 1048576 (1MB)
+     */
+    maxOutputBuffer: number;
+    /**
+     * Maximum timeout for any command (milliseconds).
+     * @default 600000 (10 minutes)
+     */
+    maxTimeout: number;
+    /**
+     * Security level for command validation.
+     *
+     * - `strict`: All commands require approval, blocks multiple commands unless safe
+     * - `moderate`: Write operations require approval, dangerous patterns blocked
+     * - `permissive`: Only dangerous patterns blocked, minimal approval
+     *
+     * @default 'moderate'
+     */
+    securityLevel: 'moderate' | 'permissive' | 'strict';
+    /**
+     * Base working directory for command execution.
+     * All cwd options are confined within this directory.
+     *
+     * @default process.cwd()
+     */
+    workingDirectory?: string;
+}
+/**
+ * Options for executing a command.
+ */
+export interface ExecuteOptions {
+    /**
+     * Working directory for command execution (relative to ProcessConfig.workingDirectory).
+     */
+    cwd?: string;
+    /**
+     * Human-readable description of what the command does (5-10 words).
+     */
+    description?: string;
+    /**
+     * Custom environment variables for this command.
+     */
+    env?: Record<string, string>;
+    /**
+     * Execute command in background (returns immediately with process handle).
+     *
+     * @default false
+     */
+    runInBackground?: boolean;
+    /**
+     * Timeout in milliseconds (max: ProcessConfig.maxTimeout).
+     *
+     * @default 120000 (2 minutes)
+     */
+    timeout?: number;
+}
+/**
+ * Result of a foreground command execution.
+ */
+export interface ProcessResult {
+    /**
+     * Execution duration in milliseconds.
+     */
+    duration: number;
+    /**
+     * Process exit code (0 = success).
+     */
+    exitCode: number;
+    /**
+     * Standard error output.
+     */
+    stderr: string;
+    /**
+     * Standard output.
+     */
+    stdout: string;
+}
+/**
+ * Handle for a background process.
+ *
+ * Returned immediately when executing a command in background.
+ */
+export interface ProcessHandle {
+    /**
+     * Command that was executed.
+     */
+    command: string;
+    /**
+     * Optional description provided in ExecuteOptions.
+     */
+    description?: string;
+    /**
+     * System process ID (may be undefined if process hasn't started).
+     */
+    pid?: number;
+    /**
+     * Unique process identifier for tracking.
+     */
+    processId: string;
+    /**
+     * Timestamp when process was started.
+     */
+    startedAt: Date;
+}
+/**
+ * Output from a background process.
+ *
+ * Returned by getProcessOutput(). Reading output clears the buffer.
+ */
+export interface ProcessOutput {
+    /**
+     * Execution duration in milliseconds (only available when completed).
+     */
+    duration?: number;
+    /**
+     * Process exit code (only available when completed).
+     */
+    exitCode?: number;
+    /**
+     * Process status.
+     */
+    status: 'completed' | 'failed' | 'running';
+    /**
+     * Standard error output (new since last read).
+     */
+    stderr: string;
+    /**
+     * Standard output (new since last read).
+     */
+    stdout: string;
+}
+/**
+ * Information about a background process.
+ *
+ * Returned by listProcesses().
+ */
+export interface ProcessInfo {
+    /**
+     * Command that was executed.
+     */
+    command: string;
+    /**
+     * Timestamp when process completed (if applicable).
+     */
+    completedAt?: Date;
+    /**
+     * Optional description provided in ExecuteOptions.
+     */
+    description?: string;
+    /**
+     * Process exit code (only available when completed).
+     */
+    exitCode?: number;
+    /**
+     * System process ID.
+     */
+    pid?: number;
+    /**
+     * Unique process identifier.
+     */
+    processId: string;
+    /**
+     * Timestamp when process was started.
+     */
+    startedAt: Date;
+    /**
+     * Process status.
+     */
+    status: 'completed' | 'failed' | 'running';
+}
+/**
+ * Result of command validation.
+ * Uses discriminated union for type safety.
+ *
+ * Returned by CommandValidator.validateCommand().
+ */
+export type CommandValidation = {
+    /** Command is valid */
+    isValid: true;
+    /** Normalized command string (trimmed, whitespace collapsed) */
+    normalizedCommand: string;
+} | {
+    /** Error message explaining why validation failed */
+    error: string;
+    /** Command is invalid */
+    isValid: false;
+};
+/**
+ * Output buffer for background process.
+ *
+ * Internal structure for tracking output with size limits.
+ */
+export interface OutputBuffer {
+    /**
+     * Running byte count for O(1) limit checking.
+     */
+    bytesUsed: number;
+    /**
+     * Whether the process has finished execution.
+     */
+    complete: boolean;
+    /**
+     * Timestamp of last read operation.
+     */
+    lastRead: number;
+    /**
+     * Standard error chunks.
+     */
+    stderr: string[];
+    /**
+     * Standard output chunks.
+     */
+    stdout: string[];
+    /**
+     * Whether output was truncated due to buffer limits.
+     */
+    truncated?: boolean;
+}
+/**
+ * Internal tracking structure for background processes.
+ *
+ * Not exported - used internally by ProcessService.
+ */
+export interface BackgroundProcess {
+    /**
+     * Node.js child process instance.
+     */
+    child: ChildProcess;
+    /**
+     * Command that was executed.
+     */
+    command: string;
+    /**
+     * Timestamp when process completed.
+     */
+    completedAt?: Date;
+    /**
+     * Optional description provided in ExecuteOptions.
+     */
+    description?: string;
+    /**
+     * Process exit code (only available when completed).
+     */
+    exitCode?: number;
+    /**
+     * Output buffer for collecting stdout/stderr.
+     */
+    outputBuffer: OutputBuffer;
+    /**
+     * Unique process identifier.
+     */
+    processId: string;
+    /**
+     * Timestamp when process was started.
+     */
+    startedAt: Date;
+    /**
+     * Process status.
+     */
+    status: 'completed' | 'failed' | 'running';
+}

package/dist/core/domain/cipher/session/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Message role in a conversation.
+ */
+export type MessageRole = 'assistant' | 'system' | 'tool' | 'user';
+/**
+ * Tool call structure.
+ * Represents a request from the LLM to execute a tool.
+ */
+export interface ToolCall {
+    /** Arguments to pass to the tool */
+    arguments: Record<string, unknown>;
+    /** Unique identifier for this tool call */
+    id: string;
+    /** Name of the tool to execute */
+    name: string;
+}
+/**
+ * Message in a conversation.
+ * Represents a single message in the conversation history.
+ */
+export interface Message {
+    /** Message content */
+    content: string;
+    /** Message role (who sent the message) */
+    role: MessageRole;
+    /** Optional timestamp (milliseconds since epoch) */
+    timestamp?: number;
+    /** Tool call ID (for tool result messages) */
+    toolCallId?: string;
+    /** Tool calls requested by the assistant */
+    toolCalls?: ToolCall[];
+    /** Tool name (for tool result messages) */
+    toolName?: string;
+}
+/**
+ * Session configuration.
+ * Options for customizing session behavior.
+ */
+export interface SessionConfig {
+    /** Maximum number of tool execution iterations (default: 10) */
+    maxToolIterations?: number;
+    /** Optional system prompt to prepend to conversation */
+    systemPrompt?: string;
+}
+/**
+ * LLM response structure.
+ * Response from the LLM service.
+ */
+export interface LLMResponse {
+    /** Response content */
+    content: string;
+    /** Optional tool calls requested by the LLM */
+    toolCalls?: ToolCall[];
+}

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

@@ -0,0 +1,38 @@
+import type { InternalMessage } from '../../../interfaces/cipher/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/core/domain/cipher/system-prompt/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Conversation metadata for execution context
+ */
+export interface ConversationMetadata {
+    /** ID of the conversation */
+    conversationId: string;
+    /** Title of the conversation */
+    title: string;
+}
+/**
+ * Context passed to system prompt contributors at runtime.
+ * This allows contributors to access runtime dependencies and configuration.
+ */
+export interface SystemPromptContext {
+    /** Additional context properties */
+    [key: string]: unknown;
+    /** Set of available tool marker strings */
+    availableMarkers?: Set<string>;
+    /** Array of available tool names */
+    availableTools?: string[];
+    /** Metadata about the conversation (for JSON input mode) */
+    conversationMetadata?: ConversationMetadata;
+    /** Whether running in JSON input mode (headless with conversation history) */
+    isJsonInputMode?: boolean;
+}
+/**
+ * Configuration for a static contributor.
+ * Static contributors return the base system prompt from YAML or custom content.
+ */
+export interface StaticContributorConfig {
+    /** Optional category for YAML file (e.g., 'base', 'contributors') */
+    category?: string;
+    /** Optional custom content to return (overrides YAML) */
+    content?: string;
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Optional filename for YAML file (without .yml extension) */
+    filename?: string;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'static';
+}
+/**
+ * Configuration for a date-time contributor.
+ * Provides current date and time in ISO format.
+ */
+export interface DateTimeContributorConfig {
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'dateTime';
+}
+/**
+ * Options for memory contributor configuration.
+ * Controls how memories are retrieved and formatted in the system prompt.
+ */
+export interface MemoryContributorOptions {
+    /** Whether to include tags in memory display (default: true) */
+    includeTags?: boolean;
+    /** Whether to include timestamps in memory display (default: false) */
+    includeTimestamps?: boolean;
+    /** Maximum number of memories to include */
+    limit?: number;
+    /** Only include pinned memories (for hybrid approach, default: false) */
+    pinnedOnly?: boolean;
+    /** Filter by memory source (agent, system, or user) */
+    source?: 'agent' | 'system' | 'user';
+}
+/**
+ * Configuration for a memory contributor.
+ * Retrieves and formats agent memories for inclusion in the system prompt.
+ */
+export interface MemoryContributorConfig {
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Options for memory retrieval and formatting */
+    options?: MemoryContributorOptions;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'memory';
+}
+/**
+ * Configuration for an execution mode contributor.
+ * Provides context-specific instructions based on execution mode (e.g., JSON input mode).
+ */
+export interface ExecutionModeContributorConfig {
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'executionMode';
+}
+/**
+ * Configuration for a marker-based prompt contributor.
+ * Generates prompt sections based on available tool markers.
+ */
+export interface MarkerPromptContributorConfig {
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'markerPrompt';
+}
+/**
+ * Union type for all contributor configurations.
+ * Uses discriminated union for type-safe contributor creation.
+ */
+export type ContributorConfig = DateTimeContributorConfig | ExecutionModeContributorConfig | MarkerPromptContributorConfig | MemoryContributorConfig | StaticContributorConfig;
+/**
+ * Configuration for the system prompt manager.
+ */
+export interface SystemPromptConfig {
+    /** Array of contributor configurations */
+    contributors: ContributorConfig[];
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Todo types for planning-based execution.
+ */
+export * from './types.js';

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

@@ -0,0 +1,4 @@
+/**
+ * Todo types for planning-based execution.
+ */
+export * from './types.js';