byterover-cli 1.5.0 → 1.7.0

package/dist/server/core/domain/transport/schemas.js

@@ -0,0 +1,617 @@
+/**
+ * Transport Schemas - Types and validation for Socket.IO transport layer.
+ *
+ * Architecture (Clean Architecture compliance):
+ * - Domain types from agent-events/types.ts are the Single Source of Truth (SSOT)
+ * - Transport layer IMPORTS from domain, does NOT redefine
+ * - Transport events EXTEND domain types with `taskId` for routing
+ * - Zod schemas provide runtime validation for transport messages
+ */
+import { z } from 'zod';
+// ============================================================================
+// Zod Schemas for Runtime Validation (mirrors domain types)
+// ============================================================================
+export const TokenUsageSchema = z.object({
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    totalTokens: z.number(),
+});
+export const LogLevelSchema = z.enum(['debug', 'error', 'info', 'warn']);
+export const UIEventTypeSchema = z.enum(['banner', 'help', 'prompt', 'response', 'separator', 'shutdown']);
+export const ToolErrorTypeSchema = z.enum([
+    'CANCELLED',
+    'CONFIRMATION_REJECTED',
+    'EXECUTION_FAILED',
+    'INTERNAL_ERROR',
+    'INVALID_PARAM_TYPE',
+    'INVALID_PARAMS',
+    'MISSING_REQUIRED_PARAM',
+    'PARAM_VALIDATION_FAILED',
+    'PERMISSION_DENIED',
+    'PROVIDER_ERROR',
+    'TIMEOUT',
+    'TOOL_DISABLED',
+    'TOOL_NOT_FOUND',
+]);
+export const AgentTerminationReasonSchema = z.enum([
+    'ABORTED',
+    'ERROR',
+    'GOAL',
+    'MAX_TURNS',
+    'PROTOCOL_VIOLATION',
+    'TIMEOUT',
+]);
+export const TodoStatusSchema = z.enum(['cancelled', 'completed', 'in_progress', 'pending']);
+export const TodoItemSchema = z.object({
+    activeForm: z.string(),
+    content: z.string(),
+    status: TodoStatusSchema,
+});
+// ============================================================================
+// Agent Events (cipher:*)
+// ============================================================================
+export const ConversationResetPayloadSchema = z.object({
+    sessionId: z.string(),
+});
+export const ExecutionStartedPayloadSchema = z.object({
+    maxIterations: z.number(),
+    maxTimeMs: z.number().optional(),
+    sessionId: z.string(),
+    startTime: z.coerce.date(),
+});
+export const ExecutionTerminatedPayloadSchema = z.object({
+    durationMs: z.number().optional(),
+    endTime: z.coerce.date(),
+    error: z.any().optional(), // Error objects don't serialize well
+    reason: AgentTerminationReasonSchema,
+    sessionId: z.string(),
+    toolCallsExecuted: z.number(),
+    turnCount: z.number(),
+});
+export const LogPayloadSchema = z.object({
+    context: z.record(z.unknown()).optional(),
+    level: LogLevelSchema,
+    message: z.string(),
+    sessionId: z.string().optional(),
+    source: z.string().optional(),
+});
+export const StateChangedPayloadSchema = z.object({
+    field: z.string(),
+    newValue: z.unknown(),
+    oldValue: z.unknown().optional(),
+    sessionId: z.string().optional(),
+});
+export const StateResetPayloadSchema = z.object({
+    sessionId: z.string().optional(),
+});
+export const UIPayloadSchema = z.object({
+    context: z.record(z.unknown()).optional(),
+    message: z.string().optional(),
+    sessionId: z.string().optional(),
+    type: UIEventTypeSchema,
+});
+// ============================================================================
+// LLM Service Events (llmservice:*)
+// ============================================================================
+export const ChunkPayloadSchema = z.object({
+    content: z.string(),
+    isComplete: z.boolean().optional(),
+    sessionId: z.string(),
+    type: z.enum(['reasoning', 'text']),
+});
+export const ErrorPayloadSchema = z.object({
+    code: z.string().optional(),
+    error: z.string(),
+    sessionId: z.string(),
+});
+export const OutputTruncatedPayloadSchema = z.object({
+    originalLength: z.number(),
+    savedToFile: z.string(),
+    sessionId: z.string(),
+    toolName: z.string(),
+});
+export const ResponsePayloadSchema = z.object({
+    content: z.string(),
+    model: z.string().optional(),
+    partial: z.boolean().optional(),
+    provider: z.string().optional(),
+    reasoning: z.string().optional(),
+    sessionId: z.string(),
+    tokenUsage: TokenUsageSchema.optional(),
+});
+export const ThinkingPayloadSchema = z.object({
+    sessionId: z.string(),
+});
+export const ThoughtPayloadSchema = z.object({
+    description: z.string(),
+    sessionId: z.string(),
+    subject: z.string(),
+});
+export const TodoUpdatedPayloadSchema = z.object({
+    sessionId: z.string(),
+    todos: z.array(TodoItemSchema),
+});
+export const ToolCallPayloadSchema = z.object({
+    args: z.record(z.unknown()),
+    callId: z.string().optional(),
+    sessionId: z.string(),
+    toolName: z.string(),
+});
+export const ToolResultPayloadSchema = z.object({
+    callId: z.string().optional(),
+    error: z.string().optional(),
+    errorType: ToolErrorTypeSchema.optional(),
+    metadata: z.record(z.unknown()).optional(),
+    result: z.unknown().optional(),
+    sessionId: z.string(),
+    success: z.boolean(),
+    toolName: z.string(),
+});
+export const UnsupportedInputPayloadSchema = z.object({
+    reason: z.string(),
+    sessionId: z.string(),
+});
+export const WarningPayloadSchema = z.object({
+    message: z.string(),
+    model: z.string().optional(),
+    provider: z.string().optional(),
+    sessionId: z.string(),
+});
+// ============================================================================
+// Transport Event Names (matches AgentEventMap keys)
+// ============================================================================
+export const TransportEventNames = {
+    // Sorted alphabetically (lint requirement)
+    CHUNK: 'llmservice:chunk',
+    CONVERSATION_RESET: 'cipher:conversationReset',
+    ERROR: 'llmservice:error',
+    EXECUTION_STARTED: 'cipher:executionStarted',
+    EXECUTION_TERMINATED: 'cipher:executionTerminated',
+    LOG: 'cipher:log',
+    OUTPUT_TRUNCATED: 'llmservice:outputTruncated',
+    RESPONSE: 'llmservice:response',
+    STATE_CHANGED: 'cipher:stateChanged',
+    STATE_RESET: 'cipher:stateReset',
+    THINKING: 'llmservice:thinking',
+    THOUGHT: 'llmservice:thought',
+    TODO_UPDATED: 'llmservice:todoUpdated',
+    TOOL_CALL: 'llmservice:toolCall',
+    TOOL_RESULT: 'llmservice:toolResult',
+    UI: 'cipher:ui',
+    UNSUPPORTED_INPUT: 'llmservice:unsupportedInput',
+    WARNING: 'llmservice:warning',
+};
+// ============================================================================
+// Transport Event Schemas (Transport → Client)
+// ============================================================================
+/**
+ * Transport Events - Sent to Clients (TUI, external CLIs)
+ *
+ * Event naming convention:
+ * - task:* events are Transport-generated (lifecycle events)
+ * - llmservice:* events are forwarded from Agent with ORIGINAL names
+ *
+ * This means FE receives the SAME event names that Agent emits internally.
+ * No mapping needed - what you see is what Agent does.
+ *
+ * Event Flow:
+ * 1. Client sends task:create → Transport generates taskId → task:ack
+ * 2. Transport forwards to Agent → Agent starts → task:started
+ * 3. Agent processes:
+ *    - LLM generates text → llmservice:response (streaming chunks)
+ *    - LLM calls a tool → llmservice:toolCall
+ *    - Tool returns result → llmservice:toolResult
+ * 4. Agent finishes → task:completed OR task:error
+ */
+export const TransportTaskEventNames = {
+    // Task lifecycle (Transport-generated)
+    ACK: 'task:ack',
+    // Client requests
+    CANCEL: 'task:cancel',
+    // Task terminal states
+    CANCELLED: 'task:cancelled',
+    COMPLETED: 'task:completed',
+    CREATE: 'task:create',
+    CREATED: 'task:created',
+    ERROR: 'task:error',
+    // Internal (Transport → Agent)
+    EXECUTE: 'task:execute',
+    STARTED: 'task:started',
+};
+export const LlmEventNames = {
+    // LLM events (forwarded with original Agent names)
+    CHUNK: 'llmservice:chunk',
+    ERROR: 'llmservice:error',
+    RESPONSE: 'llmservice:response',
+    THINKING: 'llmservice:thinking',
+    TOOL_CALL: 'llmservice:toolCall',
+    TOOL_RESULT: 'llmservice:toolResult',
+    UNSUPPORTED_INPUT: 'llmservice:unsupportedInput',
+};
+/**
+ * Explicit list of LLM event names for iteration.
+ *
+ * Avoids `Object.values(LlmEventNames)` so call sites remain readable and
+ * type-safe (the list is visible and ordered intentionally).
+ */
+export const TransportLlmEventList = [
+    LlmEventNames.THINKING,
+    LlmEventNames.CHUNK,
+    LlmEventNames.RESPONSE,
+    LlmEventNames.TOOL_CALL,
+    LlmEventNames.TOOL_RESULT,
+    LlmEventNames.ERROR,
+    LlmEventNames.UNSUPPORTED_INPUT,
+];
+/**
+ * Transport-generated Agent lifecycle/control events (internal).
+ */
+export const TransportAgentEventNames = {
+    CONNECTED: 'agent:connected',
+    DISCONNECTED: 'agent:disconnected',
+    NEW_SESSION: 'agent:newSession',
+    NEW_SESSION_CREATED: 'agent:newSessionCreated',
+    REGISTER: 'agent:register',
+    RESTART: 'agent:restart',
+    RESTARTED: 'agent:restarted',
+    RESTARTING: 'agent:restarting',
+};
+/**
+ * Transport-generated session events (internal).
+ */
+export const TransportSessionEventNames = {
+    CREATE: 'session:create',
+    INFO: 'session:info',
+    LIST: 'session:list',
+    SWITCH: 'session:switch',
+    SWITCHED: 'session:switched',
+};
+// ============================================================================
+// Internal Transport ↔ Agent Messages
+// ============================================================================
+/**
+ * task:execute - Transport sends task to Agent for processing
+ * Internal message, not exposed to external clients
+ */
+export const TaskExecuteSchema = z.object({
+    /** Client's working directory for file validation */
+    clientCwd: z.string().optional(),
+    /** Client ID that created the task (for response routing) */
+    clientId: z.string(),
+    /** Task content/prompt */
+    content: z.string(),
+    /** Optional file paths for curate --files */
+    files: z.array(z.string()).optional(),
+    /** Folder path for curate-folder task type */
+    folderPath: z.string().optional(),
+    /** Unique task identifier */
+    taskId: z.string(),
+    /** Task type */
+    type: z.enum(['curate', 'curate-folder', 'query']),
+});
+/**
+ * task:cancel - Transport tells Agent to cancel a task
+ */
+export const TaskCancelSchema = z.object({
+    taskId: z.string(),
+});
+// Zod schemas for runtime validation (if needed)
+export const LlmThinkingEventSchema = z.object({
+    sessionId: z.string(),
+    taskId: z.string(),
+});
+export const LlmChunkEventSchema = z.object({
+    content: z.string(),
+    isComplete: z.boolean().optional(),
+    sessionId: z.string(),
+    taskId: z.string(),
+    type: z.enum(['reasoning', 'text']),
+});
+export const LlmErrorEventSchema = z.object({
+    code: z.string().optional(),
+    error: z.string(),
+    sessionId: z.string(),
+    taskId: z.string(),
+});
+export const LlmUnsupportedInputEventSchema = z.object({
+    reason: z.string(),
+    sessionId: z.string(),
+    taskId: z.string(),
+});
+// ============================================================================
+// Transport Events (Transport → Client)
+// ============================================================================
+/**
+ * task:ack - Transport acknowledges task creation
+ */
+export const TaskAckSchema = z.object({
+    taskId: z.string(),
+});
+/**
+ * task:created - Broadcasted when a new task is created
+ * Sent to broadcast-room for TUI monitoring
+ */
+export const TaskCreatedSchema = z.object({
+    /** Client's working directory for file validation */
+    clientCwd: z.string().optional(),
+    /** Task content/prompt */
+    content: z.string(),
+    /** Optional file paths for curate --files */
+    files: z.array(z.string()).optional(),
+    /** Folder path for curate-folder task type */
+    folderPath: z.string().optional(),
+    /** Unique task identifier */
+    taskId: z.string(),
+    /** Task type */
+    type: z.enum(['curate', 'curate-folder', 'query']),
+});
+/**
+ * task:started - Agent begins processing the task
+ * Direct send: {taskId} only
+ * Broadcast: {taskId, content, type, files?, clientCwd?}
+ */
+export const TaskStartedEventSchema = z.object({
+    /** Client's working directory for file validation */
+    clientCwd: z.string().optional(),
+    /** Task content/prompt */
+    content: z.string().optional(),
+    /** Optional file paths for curate --files */
+    files: z.array(z.string()).optional(),
+    /** Unique task identifier */
+    taskId: z.string(),
+    /** Task type (curate or query) */
+    type: z.string().optional(),
+});
+/**
+ * task:cancelled - Task was cancelled before completion
+ * Terminal state: no more events should follow for this taskId
+ */
+export const TaskCancelledEventSchema = z.object({
+    taskId: z.string(),
+});
+/**
+ * task:completed - Task finished successfully
+ */
+export const TaskCompletedEventSchema = z.object({
+    result: z.string(),
+    taskId: z.string(),
+});
+/**
+ * Structured error object
+ * Matches TaskErrorData interface in task-error.ts
+ */
+export const TaskErrorDataSchema = z.object({
+    code: z.string().optional(),
+    details: z.record(z.unknown()).optional(),
+    message: z.string(),
+    name: z.string(),
+});
+/**
+ * task:error - Task failed with error
+ */
+export const TaskErrorEventSchema = z.object({
+    error: TaskErrorDataSchema,
+    taskId: z.string(),
+});
+/**
+ * llmservice:response - LLM text output
+ * Matches: AgentEventMap['llmservice:response'] + taskId
+ */
+export const LlmResponseEventSchema = z.object({
+    content: z.string(),
+    model: z.string().optional(),
+    partial: z.boolean().optional(),
+    provider: z.string().optional(),
+    reasoning: z.string().optional(),
+    sessionId: z.string(),
+    taskId: z.string(),
+    tokenUsage: TokenUsageSchema.optional(),
+});
+/**
+ * llmservice:toolCall - Agent invokes a tool
+ * Matches: AgentEventMap['llmservice:toolCall'] + taskId
+ */
+export const LlmToolCallEventSchema = z.object({
+    args: z.record(z.unknown()),
+    callId: z.string().optional(),
+    sessionId: z.string(),
+    taskId: z.string(),
+    toolName: z.string(),
+});
+/**
+ * llmservice:toolResult - Tool returns result
+ * Matches: AgentEventMap['llmservice:toolResult'] + taskId
+ */
+export const LlmToolResultEventSchema = z.object({
+    callId: z.string().optional(),
+    error: z.string().optional(),
+    errorType: ToolErrorTypeSchema.optional(),
+    metadata: z.record(z.unknown()).optional(),
+    result: z.unknown().optional(),
+    sessionId: z.string(),
+    success: z.boolean(),
+    taskId: z.string(),
+    toolName: z.string(),
+});
+// Note: LlmResponseEvent, LlmToolCallEvent, LlmToolResultEvent are defined above
+// as type aliases extending AgentEventMap (lines 335-347)
+// ============================================================================
+// Request/Response Schemas (for client → server commands)
+// ============================================================================
+export const TaskTypeSchema = z.enum(['curate', 'curate-folder', 'query']);
+/**
+ * Request to create a new task
+ */
+export const TaskCreateRequestSchema = z.object({
+    /** Client's working directory for file validation */
+    clientCwd: z.string().optional(),
+    /** Task content/prompt (optional for folder/file-only curate) */
+    content: z.string(),
+    /** Optional file paths for curate --files (max 5) */
+    files: z.array(z.string()).optional(),
+    /** Folder path for curate-folder task type */
+    folderPath: z.string().optional(),
+    /** Task ID - generated by Client UseCase (UUID v4) */
+    taskId: z.string().uuid('Invalid taskId format - must be UUID'),
+    /** Task type */
+    type: TaskTypeSchema,
+});
+/**
+ * Response after task creation
+ */
+export const TaskCreateResponseSchema = z.object({
+    /** Created task ID */
+    taskId: z.string(),
+});
+/**
+ * Request to cancel a task
+ */
+export const TaskCancelRequestSchema = z.object({
+    taskId: z.string(),
+});
+/**
+ * Response after task cancellation
+ */
+export const TaskCancelResponseSchema = z.object({
+    /** Error message if cancellation failed */
+    error: z.string().optional(),
+    success: z.boolean(),
+});
+// ============================================================================
+// Session Schemas (client → server commands)
+// ============================================================================
+/**
+ * Session info returned by queries
+ */
+export const SessionInfoSchema = z.object({
+    createdAt: z.number(),
+    id: z.string(),
+    lastActiveAt: z.number(),
+    name: z.string().optional(),
+});
+/**
+ * Session statistics
+ */
+export const SessionStatsSchema = z.object({
+    completedTasks: z.number().int().nonnegative(),
+    failedTasks: z.number().int().nonnegative(),
+    totalTasks: z.number().int().nonnegative(),
+});
+/**
+ * Request for session:info (empty - get current session)
+ */
+export const SessionInfoRequestSchema = z.object({});
+/**
+ * Response for session:info
+ */
+export const SessionInfoResponseSchema = z.object({
+    session: SessionInfoSchema,
+    stats: SessionStatsSchema,
+});
+/**
+ * Request for session:list (empty - list all)
+ */
+export const SessionListRequestSchema = z.object({});
+/**
+ * Response for session:list
+ */
+export const SessionListResponseSchema = z.object({
+    sessions: z.array(SessionInfoSchema),
+});
+/**
+ * Request for session:create
+ */
+export const SessionCreateRequestSchema = z.object({
+    name: z.string().optional(),
+});
+/**
+ * Response for session:create
+ */
+export const SessionCreateResponseSchema = z.object({
+    sessionId: z.string(),
+});
+/**
+ * Request for session:switch
+ */
+export const SessionSwitchRequestSchema = z.object({
+    sessionId: z.string(),
+});
+/**
+ * Response for session:switch
+ */
+export const SessionSwitchResponseSchema = z.object({
+    success: z.boolean(),
+});
+/**
+ * Broadcast when session switches (server → all clients)
+ */
+export const SessionSwitchedBroadcastSchema = z.object({
+    sessionId: z.string(),
+});
+// ============================================================================
+// Agent Control (agent:*)
+// ============================================================================
+/**
+ * Request to restart/reinitialize the Agent.
+ * Used when config changes (e.g., after /init) require Agent to reload.
+ */
+export const AgentRestartRequestSchema = z.object({
+    /** Optional reason for restart (for logging) */
+    reason: z.string().optional(),
+});
+/**
+ * Response after agent restart request.
+ */
+export const AgentRestartResponseSchema = z.object({
+    /** Error message if restart failed */
+    error: z.string().optional(),
+    /** Whether the restart was initiated successfully */
+    success: z.boolean(),
+});
+/**
+ * Request to create a new session (end current, start fresh).
+ * Used by /new command to start a fresh conversation.
+ */
+export const AgentNewSessionRequestSchema = z.object({
+    /** Optional reason for new session (for logging) */
+    reason: z.string().optional(),
+});
+/**
+ * Response after new session is created.
+ */
+export const AgentNewSessionResponseSchema = z.object({
+    /** Error message if session creation failed */
+    error: z.string().optional(),
+    /** The new session ID */
+    sessionId: z.string().optional(),
+    /** Whether the new session was created successfully */
+    success: z.boolean(),
+});
+// ============================================================================
+// Agent Status (health check)
+// ============================================================================
+/**
+ * Agent status event names.
+ */
+export const AgentStatusEventNames = {
+    /** Status changed broadcast */
+    STATUS_CHANGED: 'agent:status:changed',
+};
+/**
+ * Agent health status for monitoring.
+ * Used by Transport to check if CipherAgent is ready before forwarding tasks.
+ */
+export const AgentStatusSchema = z.object({
+    /** Number of tasks currently processing */
+    activeTasks: z.number().int().nonnegative(),
+    /** Whether auth token is loaded and valid */
+    hasAuth: z.boolean(),
+    /** Whether BrvConfig is loaded */
+    hasConfig: z.boolean(),
+    /** Whether CipherAgent is initialized and ready */
+    isInitialized: z.boolean(),
+    /** Last initialization error message */
+    lastError: z.string().optional(),
+    /** Number of tasks waiting in queue */
+    queuedTasks: z.number().int().nonnegative(),
+});

package/dist/server/core/interfaces/auth/i-auth-service.d.ts

@@ -0,0 +1,35 @@
+import { OAuthTokenData } from '../../domain/entities/oauth-token-data.js';
+/**
+ * Authorization context containing the URL and state for OAuth flow.
+ * The code_verifier is managed internally by the auth service.
+ */
+export type AuthorizationContext = {
+    authUrl: string;
+    state: string;
+};
+/**
+ * Interface for authentication services.
+ */
+export interface IAuthService {
+    /**
+     * Exchanges an authorization code for OAuth token data.
+     * @param code The authorization code to exchange.
+     * @param context The authorization context from initiateAuthorization (contains state for verifier lookup).
+     * @param redirectUri The redirect URI used in the authorization request (must match for OAuth 2.0 compliance).
+     * @returns The OAuth token data (without user information).
+     */
+    exchangeCodeForToken: (code: string, context: AuthorizationContext, redirectUri: string) => Promise<OAuthTokenData>;
+    /**
+     * Initiates the authorization flow by generating PKCE parameters and building the authorization URL.
+     * The code_verifier is generated and stored internally by the service.
+     * @param redirectUri The redirect URI where authorization codes will be received.
+     * @returns Authorization context containing the URL and state for CSRF protection.
+     */
+    initiateAuthorization: (redirectUri: string) => AuthorizationContext;
+    /**
+     * Refreshes an access token using a refresh token.
+     * @param refreshToken The refresh token to use.
+     * @returns The new OAuth token data (without user information).
+     */
+    refreshToken: (refreshToken: string) => Promise<OAuthTokenData>;
+}

package/dist/server/core/interfaces/auth/i-token-store.d.ts

@@ -0,0 +1,22 @@
+import { AuthToken } from '../../domain/entities/auth-token.js';
+/**
+ * Interface for token storage mechanisms.
+ */
+export interface ITokenStore {
+    /**
+     * Clears the stored token.
+     * @returns A promise that resolves when the token is cleared.
+     */
+    clear: () => Promise<void>;
+    /**
+     * Loads the stored token.
+     * @returns A promise that resolves with the loaded token or undefined if not found.
+     */
+    load: () => Promise<AuthToken | undefined>;
+    /**
+     * Saves the token to storage.
+     * @param token The token to save.
+     * @returns A promise that resolves when the token is saved.
+     */
+    save: (token: AuthToken) => Promise<void>;
+}