byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/system-prompt/schemas.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+/**
+ * Schema for prompt configuration loaded from YAML files.
+ *
+ * Either 'prompt' (single template) or 'prompts' (named templates) is required.
+ *
+ * Handles mapping from YAML snake_case (excluded_tools) to TypeScript camelCase (excludedTools).
+ */
+export const PromptConfigSchema = z
+    .preprocess((data) => {
+    if (typeof data === 'object' && data !== null && !Array.isArray(data)) {
+        const processed = { ...data };
+        // Map excluded_tools (YAML) to excludedTools (TypeScript)
+        if ('excluded_tools' in processed && !('excludedTools' in processed)) {
+            processed.excludedTools = processed.excluded_tools;
+            delete processed.excluded_tools;
+        }
+        return processed;
+    }
+    return data;
+}, z
+    .object({
+    description: z.string().optional().describe('Human-readable description of this prompt'),
+    excludedTools: z.array(z.string()).optional().describe('Tools to exclude from this prompt mode'),
+    prompt: z.string().optional().describe('Main prompt template content'),
+    prompts: z.record(z.string()).optional().describe('Named prompt templates (e.g., for reflection types)'),
+})
+    .strict()
+    .refine((data) => data.prompt !== undefined || data.prompts !== undefined, {
+    message: "Either 'prompt' or 'prompts' field is required",
+})
+    .describe('Prompt configuration loaded from YAML'));
+/**
+ * Schema for conversation metadata.
+ */
+export const ConversationMetadataSchema = z
+    .object({
+    conversationId: z.string().optional().describe('Unique identifier for the conversation'),
+    title: z.string().optional().describe('Title or topic of the conversation'),
+})
+    .strict();
+/**
+ * Schema for build context passed to system prompt builder.
+ *
+ * Contains runtime information needed to construct the system prompt.
+ */
+export const BuildContextSchema = z
+    .object({
+    availableMarkers: z.record(z.string()).optional().describe('Available markers and their descriptions'),
+    availableTools: z.array(z.string()).optional().describe('List of available tool names'),
+    commandType: z.enum(['curate', 'query']).optional().describe('Type of command being executed'),
+    conversationMetadata: ConversationMetadataSchema.optional().describe('Metadata about the current conversation'),
+    environmentContext: z.any().optional().describe('Environment context object (validated separately)'),
+    fileReferenceInstructions: z.string().optional().describe('Instructions for file reference handling'),
+    memoryManager: z.any().optional().describe('Memory manager instance (runtime dependency)'),
+})
+    .strict()
+    .describe('Runtime context for building system prompts');
+/**
+ * Schema for environment context builder options.
+ */
+export const EnvironmentContextOptionsSchema = z
+    .object({
+    includeBrvStructure: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Whether to include .brv directory structure explanation'),
+    includeFileTree: z.boolean().optional().default(true).describe('Whether to include project file tree'),
+    maxFileTreeDepth: z.number().int().positive().optional().default(3).describe('Maximum depth for file tree traversal'),
+    maxFileTreeEntries: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(100)
+        .describe('Maximum number of entries in file tree'),
+    workingDirectory: z.string().min(1).describe('Absolute path to the working directory'),
+})
+    .strict()
+    .describe('Options for building environment context');
+/**
+ * Schema for reflection prompt context.
+ */
+export const ReflectionContextSchema = z
+    .object({
+    currentIteration: z.number().int().positive().optional().describe('Current iteration number'),
+    maxIterations: z.number().int().positive().optional().describe('Maximum iterations allowed'),
+    type: z
+        .enum(['completion_check', 'final_iteration', 'mid_point_check', 'near_max_iterations'])
+        .describe('Type of reflection prompt to build'),
+})
+    .strict()
+    .describe('Context for building reflection prompts');

package/dist/infra/cipher/system-prompt/system-prompt-manager.d.ts

@@ -0,0 +1,136 @@
+import type { ContributorContext, SystemPromptContributor } from '../../../core/domain/cipher/system-prompt/types.js';
+import type { ValidatedContributorConfig } from './contributor-schemas.js';
+/**
+ * Reflection prompt type for iteration-based prompts.
+ */
+export type ReflectionType = 'completion_check' | 'final_iteration' | 'mid_point_check' | 'near_max_iterations';
+/**
+ * Context for building reflection prompts.
+ */
+export interface ReflectionContext {
+    /** Current iteration number (required for near_max_iterations and mid_point_check) */
+    currentIteration?: number;
+    /** Maximum iterations allowed (required for near_max_iterations and mid_point_check) */
+    maxIterations?: number;
+    /** Type of reflection prompt to build */
+    type: ReflectionType;
+}
+/**
+ * Options for SystemPromptManager configuration.
+ */
+export interface SystemPromptManagerOptions {
+    /** Base path for file contributors (defaults to current directory) */
+    basePath?: string;
+    /** Whether to validate contributor configs with Zod (default: true) */
+    validateConfig?: boolean;
+}
+/**
+ * SystemPromptManager orchestrates contributor-based prompt composition.
+ *
+ * Features:
+ * - Registers and manages multiple contributors
+ * - Builds prompts in parallel for performance
+ * - Validates contributor configurations with Zod
+ * - Sorts contributors by priority
+ */
+export declare class SystemPromptManager {
+    private readonly basePath;
+    private contributors;
+    private readonly validateConfig;
+    /**
+     * Creates a new SystemPromptManager.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: SystemPromptManagerOptions);
+    /**
+     * Build the complete system prompt using all contributors in parallel.
+     *
+     * Contributors are executed concurrently and their outputs are
+     * concatenated in priority order.
+     *
+     * @param context - Runtime context with dependencies
+     * @returns Complete system prompt string
+     */
+    build(context: ContributorContext): Promise<string>;
+    /**
+     * Build a system prompt specifically for an agent.
+     *
+     * This method builds the prompt by:
+     * 1. Getting the agent configuration from the registry
+     * 2. Loading the agent's prompt (from promptFile or inline prompt)
+     * 3. Combining it with base contributors (datetime, environment, etc.)
+     *
+     * @param agentName - Name of the agent (e.g., 'plan', 'query', 'curate')
+     * @param context - Runtime context with dependencies
+     * @returns Complete system prompt for the agent
+     */
+    buildForAgent(agentName: string, context: ContributorContext): Promise<string>;
+    /**
+     * Build a reflection prompt for completion checking.
+     *
+     * @param context - Context with iteration information
+     * @returns Formatted reflection prompt
+     */
+    buildReflectionPrompt(context: ReflectionContext): string;
+    /**
+     * Clear all registered contributors.
+     */
+    clearContributors(): void;
+    /**
+     * Get the list of registered contributors.
+     *
+     * @returns Array of contributors (copy)
+     */
+    getContributors(): SystemPromptContributor[];
+    /**
+     * Get tool-specific output guidance for a tool.
+     *
+     * @param toolName - The name of the tool (e.g., 'write_memory')
+     * @returns The guidance text if available, null otherwise
+     */
+    getToolOutputGuidance(toolName: string): null | string;
+    /**
+     * Register a single contributor directly.
+     *
+     * @param contributor - Contributor instance to register
+     */
+    registerContributor(contributor: SystemPromptContributor): void;
+    /**
+     * Register contributors from configuration objects.
+     *
+     * Validates configs with Zod if validateConfig is enabled,
+     * creates contributor instances, and sorts by priority.
+     *
+     * @param configs - Array of contributor configuration objects
+     */
+    registerContributors(configs: ValidatedContributorConfig[]): void;
+    /**
+     * Create a contributor instance from configuration.
+     *
+     * @param config - Validated contributor configuration
+     * @returns Contributor instance
+     */
+    private createContributor;
+    /**
+     * Load and parse a YAML file from the base path.
+     *
+     * @param filename - Relative filename to load
+     * @returns Parsed YAML content
+     */
+    private loadYamlFile;
+    /**
+     * Render a template string with variable substitution.
+     *
+     * Uses simple {{variable}} syntax.
+     *
+     * @param template - Template string with {{variable}} placeholders
+     * @param variables - Variables to substitute
+     * @returns Rendered string
+     */
+    private renderTemplate;
+    /**
+     * Sort contributors by priority (lower = first).
+     */
+    private sortContributors;
+}

package/dist/infra/cipher/system-prompt/system-prompt-manager.js

@@ -0,0 +1,307 @@
+import { load as loadYaml } from 'js-yaml';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getAgentRegistry } from '../../../core/domain/cipher/agent/agent-registry.js';
+import { SystemPromptError } from '../../../core/domain/cipher/errors/system-prompt-error.js';
+import { ContributorConfigSchema } from './contributor-schemas.js';
+import { AgentPromptContributor, DateTimeContributor, EnvironmentContributor, FileContributor, MemoryContributor, StaticContributor, } from './contributors/index.js';
+/**
+ * SystemPromptManager orchestrates contributor-based prompt composition.
+ *
+ * Features:
+ * - Registers and manages multiple contributors
+ * - Builds prompts in parallel for performance
+ * - Validates contributor configurations with Zod
+ * - Sorts contributors by priority
+ */
+export class SystemPromptManager {
+    basePath;
+    contributors = [];
+    validateConfig;
+    /**
+     * Creates a new SystemPromptManager.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options = {}) {
+        this.basePath = options.basePath ?? '';
+        this.validateConfig = options.validateConfig ?? true;
+    }
+    /**
+     * Build the complete system prompt using all contributors in parallel.
+     *
+     * Contributors are executed concurrently and their outputs are
+     * concatenated in priority order.
+     *
+     * @param context - Runtime context with dependencies
+     * @returns Complete system prompt string
+     */
+    async build(context) {
+        if (this.contributors.length === 0) {
+            return '';
+        }
+        // Execute all contributors in parallel
+        const results = await Promise.all(this.contributors.map(async (contributor) => {
+            try {
+                const content = await contributor.getContent(context);
+                return { content, error: null, id: contributor.id };
+            }
+            catch (error) {
+                return {
+                    content: '',
+                    error: error instanceof Error ? error.message : String(error),
+                    id: contributor.id,
+                };
+            }
+        }));
+        // Check for errors
+        const errors = results.filter((r) => r.error !== null);
+        if (errors.length > 0) {
+            const firstError = errors[0];
+            throw SystemPromptError.contributorExecutionFailed(firstError.id, firstError.error);
+        }
+        // Combine content from all contributors
+        return results
+            .map((r) => r.content)
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    /**
+     * Build a system prompt specifically for an agent.
+     *
+     * This method builds the prompt by:
+     * 1. Getting the agent configuration from the registry
+     * 2. Loading the agent's prompt (from promptFile or inline prompt)
+     * 3. Combining it with base contributors (datetime, environment, etc.)
+     *
+     * @param agentName - Name of the agent (e.g., 'plan', 'query', 'curate')
+     * @param context - Runtime context with dependencies
+     * @returns Complete system prompt for the agent
+     */
+    async buildForAgent(agentName, context) {
+        const registry = getAgentRegistry();
+        const agent = registry.get(agentName);
+        if (!agent) {
+            // Unknown agent - fall back to default build
+            return this.build(context);
+        }
+        // Create agent prompt contributor
+        const agentContributor = new AgentPromptContributor('agent', 5, {
+            basePath: this.basePath,
+            cache: true,
+        });
+        // Build context with agent name for the contributor
+        const agentContext = {
+            ...context,
+            agentName,
+        };
+        // Get agent-specific prompt
+        const agentPrompt = await agentContributor.getContent(agentContext);
+        // If agent has no custom prompt, use default build
+        if (!agentPrompt) {
+            return this.build(context);
+        }
+        // Build base prompt from existing contributors
+        const basePrompt = await this.build(context);
+        // Combine: agent prompt takes precedence, then base prompt
+        // Agent prompt comes first as it defines the agent's role
+        if (basePrompt) {
+            return `${agentPrompt}\n\n${basePrompt}`;
+        }
+        return agentPrompt;
+    }
+    /**
+     * Build a reflection prompt for completion checking.
+     *
+     * @param context - Context with iteration information
+     * @returns Formatted reflection prompt
+     */
+    buildReflectionPrompt(context) {
+        const reflectionConfig = this.loadYamlFile('reflection.yml');
+        if (!reflectionConfig.prompts) {
+            throw SystemPromptError.configMissingField('prompts', 'reflection.yml');
+        }
+        const template = reflectionConfig.prompts[context.type];
+        if (!template) {
+            throw SystemPromptError.configMissingField(`prompts.${context.type}`, 'reflection.yml');
+        }
+        if (context.type === 'near_max_iterations' && context.currentIteration && context.maxIterations) {
+            /* eslint-disable camelcase */
+            return this.renderTemplate(template, {
+                current_iteration: context.currentIteration.toString(),
+                max_iterations: context.maxIterations.toString(),
+            });
+            /* eslint-enable camelcase */
+        }
+        if (context.type === 'mid_point_check' && context.currentIteration && context.maxIterations) {
+            const remaining = context.maxIterations - context.currentIteration;
+            /* eslint-disable camelcase */
+            return this.renderTemplate(template, {
+                current_iteration: context.currentIteration.toString(),
+                remaining_iterations: remaining.toString(),
+            });
+            /* eslint-enable camelcase */
+        }
+        return template;
+    }
+    /**
+     * Clear all registered contributors.
+     */
+    clearContributors() {
+        this.contributors = [];
+    }
+    /**
+     * Get the list of registered contributors.
+     *
+     * @returns Array of contributors (copy)
+     */
+    getContributors() {
+        return [...this.contributors];
+    }
+    /**
+     * Get tool-specific output guidance for a tool.
+     *
+     * @param toolName - The name of the tool (e.g., 'write_memory')
+     * @returns The guidance text if available, null otherwise
+     */
+    getToolOutputGuidance(toolName) {
+        try {
+            const toolOutputsConfig = this.loadYamlFile('tool-outputs.yml');
+            if (toolOutputsConfig.prompts) {
+                const promptKey = `${toolName}_output`;
+                const guidance = toolOutputsConfig.prompts[promptKey];
+                if (guidance) {
+                    return guidance;
+                }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Register a single contributor directly.
+     *
+     * @param contributor - Contributor instance to register
+     */
+    registerContributor(contributor) {
+        this.contributors.push(contributor);
+        this.sortContributors();
+    }
+    /**
+     * Register contributors from configuration objects.
+     *
+     * Validates configs with Zod if validateConfig is enabled,
+     * creates contributor instances, and sorts by priority.
+     *
+     * @param configs - Array of contributor configuration objects
+     */
+    registerContributors(configs) {
+        for (const config of configs) {
+            // Validate config if enabled
+            if (this.validateConfig) {
+                const parseResult = ContributorConfigSchema.safeParse(config);
+                if (!parseResult.success) {
+                    const errorMessages = parseResult.error.errors
+                        .map((err) => `${err.path.join('.')}: ${err.message}`)
+                        .join('; ');
+                    throw SystemPromptError.configInvalid(errorMessages, parseResult.error.errors);
+                }
+            }
+            // Skip disabled contributors
+            if (config.enabled === false) {
+                continue;
+            }
+            const contributor = this.createContributor(config);
+            this.contributors.push(contributor);
+        }
+        this.sortContributors();
+    }
+    /**
+     * Create a contributor instance from configuration.
+     *
+     * @param config - Validated contributor configuration
+     * @returns Contributor instance
+     */
+    createContributor(config) {
+        switch (config.type) {
+            case 'dateTime': {
+                return new DateTimeContributor(config.id, config.priority);
+            }
+            case 'environment': {
+                return new EnvironmentContributor(config.id, config.priority);
+            }
+            case 'file': {
+                return new FileContributor(config.id, config.priority, config.filepath, {
+                    basePath: this.basePath,
+                    cache: config.options?.cache,
+                    validateMtime: config.options?.validateMtime,
+                });
+            }
+            case 'memory': {
+                return new MemoryContributor(config.id, config.priority, {
+                    includeTags: config.options?.includeTags,
+                    limit: config.options?.limit,
+                    pinnedOnly: config.options?.pinnedOnly,
+                });
+            }
+            case 'static': {
+                return new StaticContributor(config.id, config.priority, config.content);
+            }
+            default: {
+                // Exhaustive check - TypeScript will error if we miss a case
+                const _exhaustive = config;
+                throw SystemPromptError.contributorInvalidConfig(_exhaustive);
+            }
+        }
+    }
+    /**
+     * Load and parse a YAML file from the base path.
+     *
+     * @param filename - Relative filename to load
+     * @returns Parsed YAML content
+     */
+    loadYamlFile(filename) {
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        const defaultBasePath = path.join(currentDir, '../../../resources/prompts');
+        const basePath = this.basePath || defaultBasePath;
+        const fullPath = path.join(basePath, filename);
+        if (!fs.existsSync(fullPath)) {
+            throw SystemPromptError.fileNotFound(fullPath);
+        }
+        let yamlContent;
+        try {
+            yamlContent = fs.readFileSync(fullPath, 'utf8');
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw SystemPromptError.fileReadFailed(fullPath, reason);
+        }
+        return loadYaml(yamlContent);
+    }
+    /**
+     * Render a template string with variable substitution.
+     *
+     * Uses simple {{variable}} syntax.
+     *
+     * @param template - Template string with {{variable}} placeholders
+     * @param variables - Variables to substitute
+     * @returns Rendered string
+     */
+    renderTemplate(template, variables) {
+        let result = template;
+        for (const [key, value] of Object.entries(variables)) {
+            const regex = new RegExp(`{{\\s*${key}\\s*}}`, 'g');
+            result = result.replaceAll(regex, value ?? '');
+        }
+        return result;
+    }
+    /**
+     * Sort contributors by priority (lower = first).
+     */
+    sortContributors() {
+        this.contributors.sort((a, b) => a.priority - b.priority);
+    }
+}

package/dist/infra/cipher/todos/todo-storage-service.d.ts

@@ -0,0 +1,26 @@
+import type { Todo } from '../../../core/domain/cipher/todos/types.js';
+import type { ITodoStorage } from '../../../core/interfaces/cipher/i-todo-storage.js';
+/**
+ * In-memory implementation of todo storage.
+ *
+ * Stores todos per session in a Map. Data is lost when process restarts.
+ * Use a persistent implementation if you need todos to survive restarts.
+ */
+export declare class TodoStorageService implements ITodoStorage {
+    private storage;
+    /**
+     * Get todos for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Promise that resolves to array of todos, empty array if not found
+     */
+    get(sessionId: string): Promise<Todo[]>;
+    /**
+     * Update (replace) todos for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @param todos - Array of todos to store
+     * @returns Promise that resolves when todos are saved
+     */
+    update(sessionId: string, todos: Todo[]): Promise<void>;
+}

package/dist/infra/cipher/todos/todo-storage-service.js

@@ -0,0 +1,28 @@
+/**
+ * In-memory implementation of todo storage.
+ *
+ * Stores todos per session in a Map. Data is lost when process restarts.
+ * Use a persistent implementation if you need todos to survive restarts.
+ */
+export class TodoStorageService {
+    storage = new Map();
+    /**
+     * Get todos for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Promise that resolves to array of todos, empty array if not found
+     */
+    async get(sessionId) {
+        return this.storage.get(sessionId) ?? [];
+    }
+    /**
+     * Update (replace) todos for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @param todos - Array of todos to store
+     * @returns Promise that resolves when todos are saved
+     */
+    async update(sessionId, todos) {
+        this.storage.set(sessionId, todos);
+    }
+}

package/dist/infra/cipher/tools/core-tool-scheduler.js

@@ -91,7 +91,11 @@ export class CoreToolScheduler {
         this.updateStatus(execution, 'executing');
         execution.startedAt = new Date();
         try {
-            const result = await this.toolProvider.executeTool(toolName, args, context.sessionId);
+            // Pass full context (including taskId) to toolProvider for subagent billing
+            const result = await this.toolProvider.executeTool(toolName, args, context.sessionId, {
+                sessionId: context.sessionId,
+                taskId: context.taskId,
+            });
             this.updateStatus(execution, 'completed');
             execution.result = result;
             execution.completedAt = new Date();

package/dist/infra/cipher/tools/default-policy-rules.js

@@ -71,7 +71,7 @@ export const DEFAULT_POLICY_RULES = [
         decision: 'ALLOW',
         name: 'allow-read-tools',
         reason: 'Read operations are safe',
-        toolPattern: /^(read_file|glob_files|grep_content|list_memories|read_memory|search_history|find_knowledge_topics)$/,
+        toolPattern: /^(read_file|glob_files|grep_content|list_memories|read_memory|search_history)$/,
     },
     /**
      * Allow all write operations (autonomous mode).

package/dist/infra/cipher/tools/implementations/bash-exec-tool.d.ts

@@ -5,6 +5,7 @@ import type { IProcessService } from '../../../../core/interfaces/cipher/i-proce
  *
  * Executes shell commands with security validation and approval for dangerous commands.
  * Supports both foreground (wait for completion) and background (return immediately) execution.
+ * When a metadata callback is provided, streams output updates in real-time.
  *
  * @param processService - Process service for command execution
  * @returns bash_exec tool instance