@soederpop/luca 0.1.1 → 0.1.3

package/dist/agi/features/claude-code.d.ts

@@ -0,0 +1,824 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+declare module '@soederpop/luca/feature' {
+    interface AvailableFeatures {
+        claudeCode: typeof ClaudeCode;
+    }
+}
+export interface ClaudeInitEvent {
+    type: 'system';
+    subtype: 'init';
+    session_id: string;
+    cwd: string;
+    model: string;
+    tools: string[];
+    mcp_servers: string[];
+    permissionMode: string;
+    claude_code_version: string;
+}
+export interface ClaudeAssistantMessage {
+    type: 'assistant';
+    message: {
+        id: string;
+        model: string;
+        role: 'assistant';
+        content: Array<{
+            type: 'text';
+            text: string;
+        } | {
+            type: 'tool_use';
+            id: string;
+            name: string;
+            input: any;
+        }>;
+        stop_reason: string | null;
+        usage: {
+            input_tokens: number;
+            output_tokens: number;
+            cache_read_input_tokens?: number;
+            cache_creation_input_tokens?: number;
+        };
+    };
+    session_id: string;
+    parent_tool_use_id: string | null;
+}
+export interface ClaudeToolResult {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    session_id: string;
+}
+export interface ClaudeStreamEvent {
+    type: 'stream_event';
+    event: {
+        type: 'message_start' | 'content_block_start' | 'content_block_delta' | 'content_block_stop' | 'message_delta' | 'message_stop';
+        index?: number;
+        delta?: {
+            type: string;
+            text?: string;
+        };
+        content_block?: {
+            type: string;
+            text?: string;
+        };
+        message?: any;
+        usage?: any;
+    };
+    session_id: string;
+    parent_tool_use_id: string | null;
+}
+export interface ClaudeResultEvent {
+    type: 'result';
+    subtype: 'success' | 'error';
+    is_error: boolean;
+    result: string;
+    session_id: string;
+    duration_ms: number;
+    num_turns: number;
+    total_cost_usd: number;
+    usage: Record<string, any>;
+}
+export type ClaudeEvent = ClaudeInitEvent | ClaudeAssistantMessage | ClaudeToolResult | ClaudeStreamEvent | ClaudeResultEvent | {
+    type: string;
+    [key: string]: any;
+};
+export interface ClaudeSession {
+    id: string;
+    sessionId?: string;
+    status: 'idle' | 'running' | 'completed' | 'error';
+    prompt: string;
+    result?: string;
+    error?: string;
+    costUsd: number;
+    turns: number;
+    messages: ClaudeAssistantMessage[];
+    process?: any;
+}
+export interface McpStdioServer {
+    type: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export interface McpHttpServer {
+    type: 'http';
+    url: string;
+    headers?: Record<string, string>;
+}
+export interface McpSseServer {
+    type: 'sse';
+    url: string;
+    headers?: Record<string, string>;
+}
+export type McpServerConfig = McpStdioServer | McpHttpServer | McpSseServer;
+export declare const ClaudeCodeStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    sessions: z.ZodRecord<z.ZodString, z.ZodAny>;
+    activeSessions: z.ZodArray<z.ZodString>;
+    claudeAvailable: z.ZodBoolean;
+    claudeVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const FileLogLevelSchema: z.ZodEnum<{
+    minimal: "minimal";
+    verbose: "verbose";
+    normal: "normal";
+}>;
+export type FileLogLevel = z.infer<typeof FileLogLevelSchema>;
+export declare const ClaudeCodeOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    session: z.ZodOptional<z.ZodString>;
+    claudePath: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    appendSystemPrompt: z.ZodOptional<z.ZodString>;
+    permissionMode: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        acceptEdits: "acceptEdits";
+        bypassPermissions: "bypassPermissions";
+        plan: "plan";
+        dontAsk: "dontAsk";
+    }>>;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    streaming: z.ZodOptional<z.ZodBoolean>;
+    mcpConfig: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    fileLogPath: z.ZodOptional<z.ZodString>;
+    fileLogLevel: z.ZodOptional<z.ZodEnum<{
+        minimal: "minimal";
+        verbose: "verbose";
+        normal: "normal";
+    }>>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
+    fallbackModel: z.ZodOptional<z.ZodString>;
+    agent: z.ZodOptional<z.ZodString>;
+    noSessionPersistence: z.ZodOptional<z.ZodBoolean>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    strictMcpConfig: z.ZodOptional<z.ZodBoolean>;
+    settingsFile: z.ZodOptional<z.ZodString>;
+    skillsFolders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    chrome: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const ClaudeCodeEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    'session:start': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        prompt: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:init': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        init: z.ZodAny;
+    }, z.core.$strip>], null>;
+    'session:event': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        event: z.ZodAny;
+    }, z.core.$strip>], null>;
+    'session:stream': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        streamEvent: z.ZodAny;
+    }, z.core.$strip>], null>;
+    'session:delta': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        text: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:message': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        message: z.ZodAny;
+    }, z.core.$strip>], null>;
+    'session:result': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        result: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:error': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        error: z.ZodAny;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], null>;
+    'session:abort': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:warning': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:log-error': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        error: z.ZodAny;
+    }, z.core.$strip>], null>;
+    'session:parse-error': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        line: z.ZodString;
+    }, z.core.$strip>], null>;
+}, z.core.$strip>;
+export type ClaudeCodeState = z.infer<typeof ClaudeCodeStateSchema>;
+export type ClaudeCodeOptions = z.infer<typeof ClaudeCodeOptionsSchema>;
+export interface RunOptions {
+    /** Override model for this session. */
+    model?: string;
+    /** Override working directory. */
+    cwd?: string;
+    /** System prompt for this session. */
+    systemPrompt?: string;
+    /** Append system prompt for this session. */
+    appendSystemPrompt?: string;
+    /** Permission mode override. */
+    permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk';
+    /** Allowed tools override. */
+    allowedTools?: string[];
+    /** Disallowed tools override. */
+    disallowedTools?: string[];
+    /** Whether to stream partial messages. */
+    streaming?: boolean;
+    /** Resume a previous session by ID. */
+    resumeSessionId?: string;
+    /** Continue the most recent conversation. */
+    continue?: boolean;
+    /** Additional directories to allow tool access to. */
+    addDirs?: string[];
+    /** Directories containing Claude Code skills (SKILL.md files) to load into sessions. Merged with addDirs as --add-dir. */
+    skillsFolders?: string[];
+    /** MCP config file paths. */
+    mcpConfig?: string[];
+    /** MCP servers to inject, keyed by server name. */
+    mcpServers?: Record<string, McpServerConfig>;
+    /** Skip all permission checks (only for sandboxed environments). */
+    dangerouslySkipPermissions?: boolean;
+    /** Additional arbitrary CLI flags. */
+    extraArgs?: string[];
+    /** Path to write a parseable NDJSON session log file. Overrides feature-level fileLogPath. */
+    fileLogPath?: string;
+    /** Verbosity level for file logging. Overrides feature-level fileLogLevel. */
+    fileLogLevel?: FileLogLevel;
+    /** Effort level for Claude reasoning. */
+    effort?: 'low' | 'medium' | 'high';
+    /** Maximum cost budget in USD. */
+    maxBudgetUsd?: number;
+    /** Fallback model when the primary is unavailable. */
+    fallbackModel?: string;
+    /** JSON schema for structured output validation. */
+    jsonSchema?: string | object;
+    /** Agent to use for this session. */
+    agent?: string;
+    /** Resume or fork a specific Claude session by ID. */
+    sessionId?: string;
+    /** Disable session persistence for this run. */
+    noSessionPersistence?: boolean;
+    /** Fork from an existing session instead of resuming. */
+    forkSession?: boolean;
+    /** Tools to make available. */
+    tools?: string[];
+    /** Require strict MCP config validation. */
+    strictMcpConfig?: boolean;
+    /** Enable debug output. Pass a string for specific debug channels, or true for all. */
+    debug?: string | boolean;
+    /** Path to write debug output to a file. */
+    debugFile?: string;
+    /** Path to a custom settings file. */
+    settingsFile?: string;
+    /** Launch Claude Code with a Chrome browser tool. */
+    chrome?: boolean;
+}
+/**
+ * Claude Code CLI wrapper feature. Spawns and manages Claude Code sessions
+ * as subprocesses, streaming structured JSON events back through the
+ * container's event system.
+ *
+ * Sessions are long-lived: each call to `run()` spawns a `claude -p` process
+ * with `--output-format stream-json`, parses NDJSON from stdout line-by-line,
+ * and emits typed events on the feature's event bus.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const cc = container.feature('claudeCode')
+ *
+ * // Listen for events
+ * cc.on('session:delta', ({ sessionId, text }) => process.stdout.write(text))
+ * cc.on('session:result', ({ sessionId, result }) => console.log('Done:', result))
+ *
+ * // Run a prompt
+ * const session = await cc.run('Explain the architecture of this project')
+ * console.log(session.result)
+ * ```
+ */
+export declare class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        sessions: z.ZodRecord<z.ZodString, z.ZodAny>;
+        activeSessions: z.ZodArray<z.ZodString>;
+        claudeAvailable: z.ZodBoolean;
+        claudeVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        session: z.ZodOptional<z.ZodString>;
+        claudePath: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        appendSystemPrompt: z.ZodOptional<z.ZodString>;
+        permissionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            acceptEdits: "acceptEdits";
+            bypassPermissions: "bypassPermissions";
+            plan: "plan";
+            dontAsk: "dontAsk";
+        }>>;
+        allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        streaming: z.ZodOptional<z.ZodBoolean>;
+        mcpConfig: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        fileLogPath: z.ZodOptional<z.ZodString>;
+        fileLogLevel: z.ZodOptional<z.ZodEnum<{
+            minimal: "minimal";
+            verbose: "verbose";
+            normal: "normal";
+        }>>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
+        maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
+        fallbackModel: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        noSessionPersistence: z.ZodOptional<z.ZodBoolean>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        strictMcpConfig: z.ZodOptional<z.ZodBoolean>;
+        settingsFile: z.ZodOptional<z.ZodString>;
+        skillsFolders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        chrome: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        'session:start': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            prompt: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:init': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            init: z.ZodAny;
+        }, z.core.$strip>], null>;
+        'session:event': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            event: z.ZodAny;
+        }, z.core.$strip>], null>;
+        'session:stream': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            streamEvent: z.ZodAny;
+        }, z.core.$strip>], null>;
+        'session:delta': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            text: z.ZodString;
+            role: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:message': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            message: z.ZodAny;
+        }, z.core.$strip>], null>;
+        'session:result': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            result: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:error': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            error: z.ZodAny;
+            exitCode: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>], null>;
+        'session:abort': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:warning': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:log-error': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            error: z.ZodAny;
+        }, z.core.$strip>], null>;
+        'session:parse-error': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            line: z.ZodString;
+        }, z.core.$strip>], null>;
+    }, z.core.$strip>;
+    static shortcut: "features.claudeCode";
+    static envVars: string[];
+    get initialState(): ClaudeCodeState;
+    /**
+     * Resolve the path to the claude CLI binary.
+     *
+     * @returns {string} The path to the claude binary
+     */
+    private _resolvedClaudePath;
+    get claudePath(): string;
+    /**
+     * Parsed semver components from the detected CLI version, or undefined if not yet checked.
+     *
+     * @returns {{ major: number; minor: number; patch: number } | undefined} Parsed version
+     */
+    get parsedVersion(): {
+        major: number;
+        minor: number;
+        patch: number;
+    } | undefined;
+    /**
+     * Assert that the detected CLI version meets a minimum major.minor requirement.
+     * Throws if the CLI version is below the specified minimum.
+     *
+     * @param {number} major - Minimum major version
+     * @param {number} minor - Minimum minor version
+     */
+    assertMinVersion(major: number, minor: number): void;
+    /**
+     * Check if the Claude CLI is available and capture its version.
+     *
+     * @returns {Promise<boolean>} Whether the CLI is available
+     *
+     * @example
+     * ```typescript
+     * const available = await cc.checkAvailability()
+     * if (!available) throw new Error('Claude CLI not found')
+     * ```
+     */
+    checkAvailability(): Promise<boolean>;
+    /** Tracks temp MCP config files created for cleanup */
+    private mcpTempFiles;
+    /** Tracks active file log paths per session */
+    private sessionLogPaths;
+    /**
+     * Resolve the file log path for a session, checking per-session options then feature-level defaults.
+     *
+     * @param {RunOptions} options - Per-session options
+     * @returns {{ path: string; level: FileLogLevel } | undefined} Log config if logging is enabled
+     */
+    private resolveFileLog;
+    /**
+     * Write a log entry to the session's NDJSON log file.
+     * Each line is a self-contained JSON object with timestamp, sessionId, event type, and data.
+     *
+     * @param {string} sessionId - The local session ID
+     * @param {string} type - Event type label (e.g. 'session:init', 'session:message')
+     * @param {any} data - Event payload
+     */
+    private writeLogEntry;
+    /**
+     * Determine if an event should be logged based on the configured log level.
+     *
+     * - verbose: all events (stream deltas, partial messages, everything)
+     * - normal: assistant messages, tool results, init, result, errors (no stream_event)
+     * - minimal: init and result/error only
+     *
+     * @param {string} eventType - The Claude event type
+     * @param {FileLogLevel} level - The configured log level
+     * @returns {boolean} Whether to log this event
+     */
+    private shouldLog;
+    /**
+     * Write an MCP server config map to a temp file suitable for `--mcp-config`.
+     *
+     * @param {Record<string, McpServerConfig>} servers - Server configs keyed by name
+     * @returns {Promise<string>} Path to the generated temp config file
+     *
+     * @example
+     * ```typescript
+     * const configPath = await cc.writeMcpConfig({
+     *   'my-api': { type: 'http', url: 'https://api.example.com/mcp' },
+     *   'local-tool': { type: 'stdio', command: 'bun', args: ['run', 'server.ts'] }
+     * })
+     * ```
+     */
+    writeMcpConfig(servers: Record<string, McpServerConfig>): Promise<string>;
+    /**
+     * Build the argument array for a claude CLI invocation.
+     *
+     * @param {string} prompt - The prompt text
+     * @param {RunOptions} options - Session options
+     * @returns {Promise<string[]>} CLI arguments
+     */
+    private buildArgs;
+    /**
+     * Create a unique session ID.
+     *
+     * @returns {string} A UUID-based session ID
+     */
+    private createSessionId;
+    /**
+     * Update a session in state.
+     *
+     * @param {string} id - The local session ID
+     * @param {Partial<ClaudeSession>} update - Fields to merge
+     */
+    private updateSession;
+    /**
+     * Process a parsed JSON event from the Claude CLI stream.
+     *
+     * @param {string} sessionId - The local session ID
+     * @param {ClaudeEvent} event - The parsed event
+     */
+    private handleEvent;
+    /**
+     * Run a prompt in a new Claude Code session. Spawns a subprocess,
+     * streams NDJSON events, and resolves when the session completes.
+     *
+     * @param {string} prompt - The instruction/prompt to send
+     * @param {RunOptions} [options] - Session configuration overrides
+     * @returns {Promise<ClaudeSession>} The completed session with result
+     *
+     * @example
+     * ```typescript
+     * // Simple one-shot
+     * const session = await cc.run('What files are in this project?')
+     * console.log(session.result)
+     *
+     * // With options
+     * const session = await cc.run('Refactor the auth module', {
+     *   model: 'opus',
+     *   cwd: '/path/to/project',
+     *   permissionMode: 'acceptEdits',
+     *   streaming: true
+     * })
+     *
+     * // With injected MCP servers
+     * const session = await cc.run('Use the database tools to list tables', {
+     *   mcpServers: {
+     *     'db-tools': { type: 'stdio', command: 'bun', args: ['run', 'db-mcp.ts'] },
+     *     'api': { type: 'http', url: 'https://api.example.com/mcp' }
+     *   }
+     * })
+     *
+     * // Resume a previous session
+     * const session = await cc.run('Now add tests for that', {
+     *   resumeSessionId: previousSession.sessionId
+     * })
+     * ```
+     */
+    run(prompt: string, options?: RunOptions): Promise<ClaudeSession>;
+    /**
+     * Run a prompt without waiting for completion. Returns the session ID
+     * immediately so you can subscribe to events.
+     *
+     * @param {string} prompt - The instruction/prompt to send
+     * @param {RunOptions} [options] - Session configuration overrides
+     * @returns {string} The session ID to track via events
+     *
+     * @example
+     * ```typescript
+     * const sessionId = cc.start('Build a REST API for users')
+     *
+     * cc.on('session:delta', ({ sessionId: sid, text }) => {
+     *   if (sid === sessionId) process.stdout.write(text)
+     * })
+     *
+     * cc.on('session:result', ({ sessionId: sid, result }) => {
+     *   if (sid === sessionId) console.log('\nDone:', result)
+     * })
+     * ```
+     */
+    start(prompt: string, options?: RunOptions): Promise<string>;
+    /**
+     * Consume the stdout stream of a running process in the background.
+     *
+     * @param {string} sessionId - The local session ID
+     * @param {any} proc - The process handle returned by features.proc.spawn()
+     */
+    private consumeStream;
+    /**
+     * Kill a running session's subprocess.
+     *
+     * @param {string} sessionId - The local session ID to abort
+     *
+     * @example
+     * ```typescript
+     * const sessionId = cc.start('Do something long')
+     * // ... later
+     * cc.abort(sessionId)
+     * ```
+     */
+    abort(sessionId: string): void;
+    /**
+     * Get a session by its local ID.
+     *
+     * @param {string} sessionId - The local session ID
+     * @returns {ClaudeSession | undefined} The session if it exists
+     *
+     * @example
+     * ```typescript
+     * const session = cc.getSession(sessionId)
+     * if (session?.status === 'completed') {
+     *   console.log(session.result)
+     * }
+     * ```
+     */
+    getSession(sessionId: string): ClaudeSession | undefined;
+    /**
+     * Wait for a running session to complete.
+     *
+     * @param {string} sessionId - The local session ID
+     * @returns {Promise<ClaudeSession>} The completed session
+     *
+     * @example
+     * ```typescript
+     * const id = cc.start('Build something cool')
+     * const session = await cc.waitForSession(id)
+     * console.log(session.result)
+     * ```
+     */
+    waitForSession(sessionId: string): Promise<ClaudeSession>;
+    /**
+     * Get aggregated usage statistics across all sessions, or for a specific session.
+     *
+     * @param {string} [sessionId] - Optional session ID to get usage for a single session
+     * @returns {{ totalCostUsd: number; totalInputTokens: number; totalOutputTokens: number; totalCacheReadTokens: number; totalCacheCreationTokens: number; totalTurns: number; sessionCount: number; sessions: Array<{ id: string; costUsd: number; turns: number; inputTokens: number; outputTokens: number; status: string }> }} Usage statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = cc.usage()
+     * console.log(`Total cost: $${stats.totalCostUsd.toFixed(4)}`)
+     * console.log(`Tokens: ${stats.totalInputTokens} in / ${stats.totalOutputTokens} out`)
+     *
+     * // Single session
+     * const sessionStats = cc.usage(sessionId)
+     * ```
+     */
+    usage(sessionId?: string): {
+        totalCostUsd: number;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalCacheReadTokens: number;
+        totalCacheCreationTokens: number;
+        totalTurns: number;
+        sessionCount: number;
+        maxBudgetUsd: number | null;
+        budgetRemainingUsd: number | null;
+        budgetUsedPercent: number | null;
+        sessions: {
+            id: string;
+            costUsd: number;
+            turns: number;
+            inputTokens: number;
+            outputTokens: number;
+            status: string;
+        }[];
+    };
+    /**
+     * The Claude CLI session ID of the most recently initialized session,
+     * or the session set via the `session` option. Useful for resuming later.
+     *
+     * @returns {string | undefined} The Claude CLI session ID
+     *
+     * @example
+     * ```typescript
+     * const cc = container.feature('claudeCode')
+     * await cc.run('Do something')
+     * console.log(cc.sessionId) // the Claude CLI session ID
+     * ```
+     */
+    get sessionId(): string | undefined;
+    /**
+     * Export session history as a readable markdown document.
+     * Reads from a raw JSONL file (Claude CLI session log or this feature's NDJSON log)
+     * so it works independently of in-memory state.
+     *
+     * Can also accept a local session ID to export from in-memory state as a fallback.
+     *
+     * @param {string} [source] - Path to a JSONL file, a local session ID, or omit for the most recent session
+     * @returns {Promise<string>} Markdown-formatted session history
+     *
+     * @example
+     * ```typescript
+     * // From a JSONL file (works without any prior state)
+     * const md = await cc.sessionHistoryToMarkdown('/path/to/session.jsonl')
+     *
+     * // From the most recent in-memory session
+     * const md = await cc.sessionHistoryToMarkdown()
+     *
+     * // From a specific local session ID
+     * const md = await cc.sessionHistoryToMarkdown(localSessionId)
+     * ```
+     */
+    sessionHistoryToMarkdown(source?: string): Promise<string>;
+    /**
+     * Find the local ID of the most recent session.
+     */
+    private findLastSessionId;
+    /**
+     * Parse a JSONL file and convert its events to markdown.
+     */
+    private jsonlToMarkdown;
+    /**
+     * Convert a ClaudeSession (from state) to markdown.
+     */
+    private sessionToMarkdown;
+    /**
+     * Convert raw Claude events to markdown.
+     */
+    private eventsToMarkdown;
+    /**
+     * Render a single assistant message to markdown lines.
+     */
+    private renderAssistantMessage;
+    /**
+     * List all Claude Code processes currently registered in ~/.claude/sessions/.
+     * Returns each session's metadata along with whether the process is still alive.
+     *
+     * @returns {Promise<Array<{ pid: number; sessionId: string; cwd: string; startedAt: number; kind: string; entrypoint: string; alive: boolean }>>}
+     *
+     * @example
+     * const sessions = await cc.listProcessSessions()
+     * for (const s of sessions) {
+     *   console.log(`[${s.alive ? 'LIVE' : 'dead'}] PID ${s.pid} in ${s.cwd}`)
+     * }
+     */
+    listProcessSessions(): Promise<Array<{
+        pid: number;
+        sessionId: string;
+        cwd: string;
+        startedAt: number;
+        kind: string;
+        entrypoint: string;
+        alive: boolean;
+    }>>;
+    /**
+     * Read a single process session by PID from ~/.claude/sessions/<pid>.json.
+     *
+     * @param {number} pid - The process ID
+     * @returns {Promise<{ pid: number; sessionId: string; cwd: string; startedAt: number; kind: string; entrypoint: string } | null>}
+     *
+     * @example
+     * const session = await cc.getProcessSession(12345)
+     * console.log(session?.cwd)
+     */
+    getProcessSession(pid: number): Promise<{
+        pid: number;
+        sessionId: string;
+        cwd: string;
+        startedAt: number;
+        kind: string;
+        entrypoint: string;
+    } | null>;
+    /**
+     * Read the conversation history for a Claude Code session from its JSONL file in
+     * ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl.
+     *
+     * Returns an array of parsed message objects (user, assistant, tool_use, tool_result).
+     *
+     * @param {string} sessionId - The Claude CLI session ID (from listProcessSessions or getProcessSession)
+     * @param {string} cwd - The working directory of the session (used to locate the project folder)
+     * @returns {Promise<any[]>} Array of parsed JSONL records
+     *
+     * @example
+     * const sessions = await cc.listProcessSessions()
+     * const s = sessions[0]
+     * const history = await cc.getConversationHistory(s.sessionId, s.cwd)
+     * console.log(history.length, 'turns')
+     */
+    getConversationHistory(sessionId: string, cwd?: string): Promise<any[]>;
+    /**
+     * List all conversation sessions stored for a given working directory.
+     * Reads ~/.claude/projects/<encoded-cwd>/ and returns metadata for each .jsonl file.
+     *
+     * @param {string} cwd - The working directory path to look up
+     * @returns {Promise<Array<{ sessionId: string; filePath: string; messageCount: number }>>}
+     *
+     * @example
+     * const sessions = await cc.listSessionsForCwd('/Users/me/my-project')
+     * for (const s of sessions) {
+     *   console.log(s.sessionId, s.messageCount, 'messages')
+     * }
+     */
+    listSessionsForCwd(cwd?: string): Promise<Array<{
+        sessionId: string;
+        filePath: string;
+        messageCount: number;
+    }>>;
+    /**
+     * Clean up any temp MCP config files created during sessions.
+     */
+    cleanupMcpTempFiles(): Promise<void>;
+    /**
+     * Initialize the feature.
+     *
+     * @param {any} [options] - Enable options
+     * @returns {Promise<this>} The enabled feature
+     */
+    enable(options?: any): Promise<this>;
+}
+export default ClaudeCode;
+//# sourceMappingURL=claude-code.d.ts.map