@sylphx/flow 1.0.1 → 1.0.3

package/src/types/session.types.ts

@@ -0,0 +1,214 @@
+/**
+ * Session Types
+ * Unified session and message types used across TUI and headless modes
+ */
+
+import type { ProviderId } from '../config/ai-config.js';
+import type { Todo } from './todo.types.js';
+
+/**
+ * Message Part - unified type for all content parts
+ *
+ * ALL parts have status field to track their lifecycle state:
+ * - 'active': Being generated/processed
+ * - 'completed': Successfully finished
+ * - 'error': Failed with error
+ * - 'abort': User cancelled
+ *
+ * Design: No separate "StreamingPart" type needed
+ * - Streaming parts ARE message parts
+ * - Status field tracks state during and after streaming
+ * - No conversion required between streaming/stored formats
+ *
+ * Multiple parts can be active simultaneously (parallel tool calls).
+ */
+export type MessagePart =
+  | {
+      type: 'text';
+      content: string;
+      status: 'active' | 'completed' | 'error' | 'abort';
+    }
+  | {
+      type: 'reasoning';
+      content: string;
+      status: 'active' | 'completed' | 'error' | 'abort';
+      duration?: number;
+      startTime?: number;
+    }
+  | {
+      type: 'tool';
+      toolId: string;
+      name: string;
+      status: 'active' | 'completed' | 'error' | 'abort';
+      args?: unknown;
+      result?: unknown;
+      error?: string;
+      duration?: number;
+      startTime?: number;
+    }
+  | {
+      type: 'error';
+      error: string;
+      status: 'completed';  // Errors are immediately completed
+    };
+
+/**
+ * Legacy type alias for backwards compatibility
+ * @deprecated Use MessagePart directly
+ */
+export type StreamingPart = MessagePart;
+
+/**
+ * File attachment
+ */
+export interface FileAttachment {
+  path: string;
+  relativePath: string;
+  size?: number;
+}
+
+/**
+ * Token usage statistics
+ */
+export interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+/**
+ * Message metadata - system information at message creation time
+ *
+ * IMPORTANT: This metadata is captured ONCE when the message is created and NEVER changes.
+ * This is critical for prompt cache effectiveness - historical messages must remain immutable.
+ *
+ * Design decisions:
+ * 1. Stored separately from content - not shown in UI, only sent to LLM
+ * 2. Captured at creation time - never updated to preserve prompt cache
+ * 3. Used to build system status context when constructing ModelMessage for LLM
+ *
+ * What goes in metadata vs top-level fields:
+ * - metadata: Info for LLM but NOT shown in UI (cpu, memory, future: sessionId, requestId)
+ * - usage/finishReason: Info for UI/monitoring but NOT sent to LLM
+ * - timestamp: Shown in UI AND used to construct metadata for LLM
+ * - content: Shown in UI AND sent to LLM
+ */
+export interface MessageMetadata {
+  cpu?: string;         // CPU usage at creation time (e.g., "45.3% (8 cores)")
+  memory?: string;      // Memory usage at creation time (e.g., "4.2GB/16.0GB")
+  // Future: add more fields as needed (sessionId, requestId, modelVersion, etc.)
+}
+
+/**
+ * Session message - Unified message type for both UI display and LLM consumption
+ *
+ * Design: Separation of UI display vs LLM context
+ * ================================================
+ *
+ * UI Display (what user sees):
+ * - content: MessagePart[] - Text, tool calls, reasoning, errors
+ * - timestamp: Display time
+ * - usage: Token counts for monitoring
+ * - attachments: Show file paths
+ *
+ * LLM Context (what AI sees):
+ * - content: Converted to ModelMessage format
+ * - metadata: Injected as system status (cpu, memory) - NOT shown in UI
+ * - timestamp: Used to construct system status time
+ * - attachments: File contents read and injected
+ * - todoSnapshot: Todo state at message creation, injected as context
+ *
+ * Why content doesn't include system status:
+ * - System status is contextual info, not part of user's actual message
+ * - Including it in content would display "<system_status>..." in chat UI
+ * - metadata allows us to store it separately and inject only when building ModelMessage
+ *
+ * Why usage/finishReason are NOT in metadata:
+ * - They're for monitoring/debugging, not for LLM consumption
+ * - finishReason controls multi-step flow (stop vs tool-calls vs length)
+ * - usage helps track API costs and quota
+ *
+ * Why todoSnapshot at top-level (not in metadata):
+ * - Structured data (Todo[]), not string context like cpu/memory
+ * - Enables rewind feature - can restore todo state at any point in conversation
+ * - May be used by UI for historical view
+ * - Clearer separation: metadata = simple context, todoSnapshot = structured state
+ */
+export interface SessionMessage {
+  role: 'user' | 'assistant';
+  content: MessagePart[];  // UI display (without system status)
+  timestamp: number;
+  status?: 'active' | 'completed' | 'error' | 'abort';  // Message lifecycle state (default: 'completed')
+  metadata?: MessageMetadata;  // System info for LLM context (not shown in UI)
+  todoSnapshot?: Todo[];   // Full todo state at message creation time (for rewind + LLM context)
+  attachments?: FileAttachment[];
+  usage?: TokenUsage;          // For UI/monitoring, not sent to LLM
+  finishReason?: string;       // For flow control (stop/tool-calls/length/error), not sent to LLM
+}
+
+/**
+ * Chat session
+ *
+ * Design: Per-session todo lists
+ * ================================
+ *
+ * Why todos are scoped to sessions (not global):
+ * 1. Context isolation - Each conversation has its own task context
+ * 2. Prevents cross-contamination - New session won't see old todos
+ * 3. LLM clarity - AI only sees tasks relevant to current conversation
+ *
+ * Before (global todos):
+ * - Session A creates todos ["Build feature X", "Test feature X"]
+ * - Session B starts, user says "hi"
+ * - LLM sees Session A's todos and tries to complete them ❌
+ *
+ * After (per-session todos):
+ * - Session A has its own todos
+ * - Session B starts with empty todos ✅
+ * - Each session manages independent task lists
+ *
+ * Implementation notes:
+ * - nextTodoId is also per-session to avoid ID conflicts
+ * - Todos are persisted with session to disk
+ * - updateTodos tool requires sessionId parameter
+ *
+ * Design: Message status-based state
+ * ===================================
+ *
+ * Streaming state is derived from message status, not stored separately:
+ * - message.status: 'active' | 'completed' | 'error' | 'abort'
+ * - part.status: 'active' | 'completed' | 'error' | 'abort'
+ *
+ * Session recovery:
+ * 1. Find messages with status === 'active'
+ * 2. Display their parts directly
+ * 3. No separate streaming state needed
+ *
+ * Streaming lifecycle:
+ * 1. User sends message → Create message with status='active'
+ * 2. Parts arrive → Add/update parts in message
+ * 3. User switches session → Message stays in DB with status='active'
+ * 4. Streaming completes → Update message status='completed'
+ * 5. User aborts (ESC) → Update message status='abort'
+ *
+ * Benefits:
+ * - Single source of truth (message data)
+ * - No conversion between streaming/persistent formats
+ * - Recovery is just "display active messages"
+ * - Archives naturally (status='archived')
+ */
+export interface Session {
+  id: string;
+  title?: string; // Auto-generated from first user message
+  provider: ProviderId;
+  model: string;
+  messages: SessionMessage[];
+  todos: Todo[];         // Per-session todo list (not global!)
+  nextTodoId: number;    // Next todo ID for this session (starts at 1)
+
+  // Note: Streaming state derived from message.status, not stored here
+  // To check if streaming: messages.some(m => m.status === 'active')
+
+  created: number;
+  updated: number;
+}

package/src/types/target-config.types.ts

@@ -0,0 +1,295 @@
+import { z } from 'zod';
+
+// ============================================================================
+// TARGET CONFIGURATION INTERFACES
+// ============================================================================
+
+/**
+ * Generic metadata structure for agents and configurations
+ */
+export interface AgentMetadata {
+  /** Agent name or identifier */
+  name?: string;
+  /** Agent description */
+  description?: string;
+  /** Agent version */
+  version?: string;
+  /** Agent author */
+  author?: string;
+  /** Tags for categorization */
+  tags?: string[];
+  /** Agent category or type */
+  category?: string;
+  /** Whether the agent is enabled */
+  enabled?: boolean;
+  /** Custom properties */
+  properties?: Record<string, unknown>;
+  /** Creation timestamp */
+  createdAt?: string;
+  /** Last updated timestamp */
+  updatedAt?: string;
+  /** Source file path */
+  sourcePath?: string;
+}
+
+/**
+ * Target-specific configuration data structure
+ */
+export interface TargetConfigurationData {
+  /** Core configuration settings */
+  settings: Record<string, unknown>;
+  /** MCP server configurations */
+  mcpServers?: Record<string, unknown>;
+  /** Agent-specific configurations */
+  agents?: Record<string, AgentMetadata>;
+  /** Extension-specific settings */
+  extensions?: Record<string, unknown>;
+  /** Custom user preferences */
+  preferences?: Record<string, unknown>;
+}
+
+/**
+ * Front matter metadata for markdown files
+ */
+export interface FrontMatterMetadata {
+  /** Title of the document */
+  title?: string;
+  /** Description of the document */
+  description?: string;
+  /** Tags for categorization */
+  tags?: string[];
+  /** Author information */
+  author?: string;
+  /** Creation date */
+  date?: string;
+  /** Last modified date */
+  modified?: string;
+  /** Document status (draft, published, etc.) */
+  status?: 'draft' | 'published' | 'archived';
+  /** Document category */
+  category?: string;
+  /** Custom metadata fields */
+  [key: string]: unknown;
+}
+
+/**
+ * OpenCode specific metadata structure
+ */
+export interface OpenCodeMetadata {
+  /** Project name */
+  name?: string;
+  /** Project description */
+  description?: string;
+  /** Project version */
+  version?: string;
+  /** Author information */
+  author?: string;
+  /** Repository URL */
+  repository?: string;
+  /** License information */
+  license?: string;
+  /** Main entry point */
+  main?: string;
+  /** Scripts configuration */
+  scripts?: Record<string, string>;
+  /** Dependencies */
+  dependencies?: Record<string, string>;
+  /** Development dependencies */
+  devDependencies?: Record<string, string>;
+  /** Project keywords */
+  keywords?: string[];
+  /** Custom configuration */
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Claude Code specific metadata structure
+ */
+export interface ClaudeCodeMetadata {
+  /** Agent name */
+  name?: string;
+  /** Agent description */
+  description?: string;
+  /** Agent instructions */
+  instructions?: string;
+  /** Agent capabilities */
+  capabilities?: string[];
+  /** Agent tools */
+  tools?: string[];
+  /** Agent model configuration */
+  model?: {
+    name?: string;
+    temperature?: number;
+    maxTokens?: number;
+  };
+  /** Agent constraints */
+  constraints?: string[];
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+}
+
+// ============================================================================
+// ZOD SCHEMAS FOR RUNTIME VALIDATION
+// ============================================================================
+
+/**
+ * Zod schema for AgentMetadata
+ */
+export const AgentMetadataSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().optional(),
+  version: z.string().optional(),
+  author: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  category: z.string().optional(),
+  enabled: z.boolean().optional(),
+  properties: z.record(z.unknown()).optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
+  sourcePath: z.string().optional(),
+});
+
+/**
+ * Zod schema for TargetConfigurationData
+ */
+export const TargetConfigurationDataSchema = z.object({
+  settings: z.record(z.unknown()),
+  mcpServers: z.record(z.unknown()).optional(),
+  agents: z.record(AgentMetadataSchema).optional(),
+  extensions: z.record(z.unknown()).optional(),
+  preferences: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Zod schema for FrontMatterMetadata
+ */
+export const FrontMatterMetadataSchema = z
+  .object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    author: z.string().optional(),
+    date: z.string().optional(),
+    modified: z.string().optional(),
+    status: z.enum(['draft', 'published', 'archived']).optional(),
+    category: z.string().optional(),
+  })
+  .catchall(z.unknown());
+
+/**
+ * Zod schema for OpenCodeMetadata
+ */
+export const OpenCodeMetadataSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().optional(),
+  version: z.string().optional(),
+  author: z.string().optional(),
+  repository: z.string().optional(),
+  license: z.string().optional(),
+  main: z.string().optional(),
+  scripts: z.record(z.string()).optional(),
+  dependencies: z.record(z.string()).optional(),
+  devDependencies: z.record(z.string()).optional(),
+  keywords: z.array(z.string()).optional(),
+  config: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Zod schema for ClaudeCodeMetadata
+ */
+export const ClaudeCodeMetadataSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().optional(),
+  instructions: z.string().optional(),
+  capabilities: z.array(z.string()).optional(),
+  tools: z.array(z.string()).optional(),
+  model: z
+    .object({
+      name: z.string().optional(),
+      temperature: z.number().optional(),
+      maxTokens: z.number().optional(),
+    })
+    .optional(),
+  constraints: z.array(z.string()).optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+// ============================================================================
+// TYPE GUARDS FOR RUNTIME TYPE CHECKING
+// ============================================================================
+
+/**
+ * Type guard to check if value is AgentMetadata
+ */
+export function isAgentMetadata(value: unknown): value is AgentMetadata {
+  return AgentMetadataSchema.safeParse(value).success;
+}
+
+/**
+ * Type guard to check if value is TargetConfigurationData
+ */
+export function isTargetConfigurationData(value: unknown): value is TargetConfigurationData {
+  return TargetConfigurationDataSchema.safeParse(value).success;
+}
+
+/**
+ * Type guard to check if value is FrontMatterMetadata
+ */
+export function isFrontMatterMetadata(value: unknown): value is FrontMatterMetadata {
+  return FrontMatterMetadataSchema.safeParse(value).success;
+}
+
+/**
+ * Type guard to check if value is OpenCodeMetadata
+ */
+export function isOpenCodeMetadata(value: unknown): value is OpenCodeMetadata {
+  return OpenCodeMetadataSchema.safeParse(value).success;
+}
+
+/**
+ * Type guard to check if value is ClaudeCodeMetadata
+ */
+export function isClaudeCodeMetadata(value: unknown): value is ClaudeCodeMetadata {
+  return ClaudeCodeMetadataSchema.safeParse(value).success;
+}
+
+// ============================================================================
+// UTILITY TYPES
+// ============================================================================
+
+/**
+ * Generic configuration object with dynamic properties
+ */
+export type DynamicConfig<T = Record<string, unknown>> = T & {
+  [key: string]: unknown;
+};
+
+/**
+ * Generic transformation result
+ */
+export interface TransformationResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  warnings?: string[];
+}
+
+/**
+ * Generic validation result
+ */
+export interface ValidationResult<T = unknown> {
+  isValid: boolean;
+  data?: T;
+  errors: string[];
+}
+
+/**
+ * Generic operation result with metadata
+ */
+export interface OperationResult<T = unknown, M = Record<string, unknown>> {
+  success: boolean;
+  data?: T;
+  metadata?: M;
+  error?: string;
+  timestamp: string;
+}

package/src/types/target.types.ts

@@ -0,0 +1,140 @@
+/**
+ * Target system type definitions
+ * Types for target platforms (Claude Code, OpenCode, etc.)
+ */
+
+import type { CommonOptions, SetupResult } from './common.types.js';
+import type { MCPServerConfigFlags, MCPServerConfigUnion } from './mcp.types.js';
+
+/**
+ * Target-specific configuration
+ * Defines how agents, configs, and other artifacts are structured for each target
+ */
+export interface TargetConfig {
+  /** Directory where agents are installed */
+  agentDir: string;
+  /** File extension for agent files */
+  agentExtension: string;
+  /** Format of agent files */
+  agentFormat: 'yaml-frontmatter' | 'json' | 'yaml' | 'markdown';
+  /** Whether to strip YAML front matter from content */
+  stripYaml: boolean;
+  /** Whether to flatten directory structure */
+  flatten: boolean;
+  /** Configuration file name */
+  configFile: string;
+  /** Configuration file schema URL (optional) */
+  configSchema: string | null;
+  /** Path to MCP configuration in config file */
+  mcpConfigPath: string;
+  /** Rules file path (optional, relative to project root) */
+  rulesFile?: string;
+  /** Output styles directory (optional, relative to project root) */
+  outputStylesDir?: string;
+  /** Slash commands directory (optional, relative to project root) */
+  slashCommandsDir?: string;
+  /** Installation-specific configuration */
+  installation: {
+    /** Whether to create the agent directory */
+    createAgentDir: boolean;
+    /** Whether to create the config file */
+    createConfigFile: boolean;
+    /** Whether to use secret file references for sensitive environment variables */
+    useSecretFiles?: boolean;
+  };
+}
+
+/**
+ * Target interface - composition-based design
+ * Targets are implemented as plain objects with functions, not classes
+ *
+ * Each target represents a platform that can host AI agents and MCP servers
+ * (e.g., Claude Code CLI, OpenCode, VS Code with Continue, etc.)
+ */
+export interface Target {
+  // Metadata
+  /** Internal identifier used in CLI commands */
+  readonly id: string;
+  /** Display name for the target */
+  readonly name: string;
+  /** Human-readable description */
+  readonly description: string;
+  /** Target category for grouping */
+  readonly category: 'ide' | 'editor' | 'cli';
+  /** Whether this target is the default when no target is specified */
+  readonly isDefault?: boolean;
+  /** Whether this target is fully implemented */
+  readonly isImplemented: boolean;
+
+  // Configuration
+  /** Target-specific configuration */
+  readonly config: TargetConfig;
+  /** MCP server configuration for this target */
+  readonly mcpServerConfig?: MCPServerConfigFlags;
+
+  // Required transformation methods
+  /** Transform agent content for the target */
+  transformAgentContent(
+    content: string,
+    metadata?: Record<string, unknown>,
+    sourcePath?: string
+  ): Promise<string>;
+
+  /** Transform MCP server configuration for the target */
+  transformMCPConfig(config: MCPServerConfigUnion, serverId?: string): Record<string, unknown>;
+
+  // Required configuration methods
+  /** Get the configuration file path for the target */
+  getConfigPath(cwd: string): Promise<string>;
+
+  /** Read the target's configuration file */
+  readConfig(cwd: string): Promise<Record<string, unknown>>;
+
+  /** Write the target's configuration file */
+  writeConfig(cwd: string, config: Record<string, unknown>): Promise<void>;
+
+  /** Validate target-specific requirements */
+  validateRequirements(cwd: string): Promise<void>;
+
+  /** Get target-specific help text */
+  getHelpText(): string;
+
+  // Optional methods
+  /** Execute command with the target (optional - not all targets need to support execution) */
+  executeCommand?(
+    systemPrompt: string,
+    userPrompt: string,
+    options: Record<string, unknown>
+  ): Promise<void>;
+
+  /** Detect if this target is being used in the current environment (optional) */
+  detectFromEnvironment?(): boolean;
+
+  /** Approve MCP servers in target-specific configuration (optional - only for targets that need approval) */
+  approveMCPServers?(cwd: string, serverNames: string[]): Promise<void>;
+
+  /** Transform rules content for the target (optional - defaults to no transformation) */
+  transformRulesContent?(content: string): Promise<string>;
+
+  /** Setup target-specific configuration (optional - for targets that need additional setup) */
+  setup?(cwd: string, options?: Record<string, unknown>): Promise<void>;
+
+  // Setup methods for different components
+  /** Setup agents for this target (optional - implement if target needs agents) */
+  setupAgents?(cwd: string, options: CommonOptions): Promise<SetupResult>;
+
+  /** Setup rules for this target (optional - implement if target needs rules) */
+  setupRules?(cwd: string, options: CommonOptions): Promise<SetupResult>;
+
+  /** Setup output styles for this target (optional - implement if target supports output styles) */
+  setupOutputStyles?(cwd: string, options: CommonOptions): Promise<SetupResult>;
+
+  /** Setup MCP servers for this target (optional - implement if target supports MCP) */
+  setupMCP?(cwd: string, options: CommonOptions): Promise<SetupResult>;
+
+  /** Setup hooks for this target (optional - implement if target needs hooks like Claude Code) */
+  setupHooks?(cwd: string, options: CommonOptions): Promise<SetupResult>;
+
+  /** Setup slash commands for this target (optional - implement if target supports slash commands) */
+  setupSlashCommands?(cwd: string, options: CommonOptions): Promise<SetupResult>;
+}

package/src/types/todo.types.ts

@@ -0,0 +1,25 @@
+/**
+ * Todo Types
+ * Task tracking for LLM work progress
+ */
+
+export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'removed';
+
+export interface Todo {
+  id: number;
+  content: string;
+  status: TodoStatus;
+  activeForm: string; // Present continuous form (e.g., "Building feature X")
+  ordering: number;   // For custom ordering (higher = earlier in list)
+}
+
+export interface TodoUpdate {
+  id?: number;
+  content?: string;
+  activeForm?: string;
+  status?: TodoStatus;
+  reorder?: {
+    type: 'before' | 'after' | 'top' | 'last';
+    id?: number; // Required when type is 'before' or 'after'
+  };
+}