cyrus-simple-agent-runner 0.0.2

package/README.md

@@ -0,0 +1,322 @@
+# cyrus-simple-agent-runner
+
+A simple, type-safe abstraction for agent interactions that return enumerated responses.
+
+## Overview
+
+`simple-agent-runner` provides a clean API for running agent queries where you need the agent to select from a predefined set of responses (e.g., "yes"/"no", "approve"/"reject"/"abstain"). It handles:
+
+- **Type-safe response validation** - Generic types ensure compile-time checking
+- **Comprehensive error handling** - Structured errors with codes and context
+- **Progress tracking** - Optional callbacks for observability
+- **Multiple backends** - Extensible architecture supports different agent SDKs
+
+## Installation
+
+```bash
+pnpm add cyrus-simple-agent-runner
+```
+
+## Quick Start
+
+```typescript
+import { SimpleClaudeRunner } from "cyrus-simple-agent-runner";
+
+// Define valid responses as a const array for type safety
+const VALID_RESPONSES = ["yes", "no"] as const;
+type YesNoResponse = typeof VALID_RESPONSES[number]; // "yes" | "no"
+
+// Create runner
+const runner = new SimpleClaudeRunner<YesNoResponse>({
+  validResponses: VALID_RESPONSES,
+  cyrusHome: "/Users/me/.cyrus",
+  maxTurns: 3,
+  timeoutMs: 30000, // 30 seconds
+});
+
+// Execute query
+const result = await runner.query(
+  "Is TypeScript better than JavaScript for large projects?"
+);
+
+console.log(result.response); // "yes" or "no" (type-safe!)
+console.log(result.durationMs); // Execution time
+console.log(result.costUSD); // Cost (if available)
+```
+
+## API Reference
+
+### `SimpleClaudeRunner<T>`
+
+The concrete implementation using Claude Agent SDK.
+
+#### Constructor Options
+
+```typescript
+interface SimpleAgentRunnerConfig<T extends string> {
+  // Required
+  validResponses: readonly T[];  // Valid response options
+  cyrusHome: string;              // Cyrus home directory
+
+  // Optional
+  systemPrompt?: string;          // Custom system prompt
+  maxTurns?: number;              // Max turns before timeout
+  timeoutMs?: number;             // Overall timeout in ms
+  model?: string;                 // Model to use
+  fallbackModel?: string;         // Fallback model
+  workingDirectory?: string;      // Working directory
+  onProgress?: (event) => void;   // Progress callback
+}
+```
+
+#### Methods
+
+##### `query(prompt: string, options?: SimpleAgentQueryOptions): Promise<SimpleAgentResult<T>>`
+
+Execute a query and return a validated response.
+
+**Options:**
+```typescript
+interface SimpleAgentQueryOptions {
+  context?: string;                  // Additional context
+  allowFileReading?: boolean;        // Allow file operations
+  allowedDirectories?: string[];     // Allowed file paths
+}
+```
+
+**Returns:**
+```typescript
+interface SimpleAgentResult<T extends string> {
+  response: T;                    // Validated response
+  messages: SDKMessage[];         // All SDK messages
+  sessionId: string | null;       // Session ID
+  durationMs: number;             // Execution time
+  costUSD?: number;               // Cost (if available)
+}
+```
+
+## Error Handling
+
+All errors extend `SimpleAgentError` and include error codes:
+
+```typescript
+import {
+  InvalidResponseError,
+  TimeoutError,
+  NoResponseError,
+  MaxTurnsExceededError,
+  SessionError,
+  SimpleAgentErrorCode,
+} from "cyrus-simple-agent-runner";
+
+try {
+  const result = await runner.query("Should we deploy to production?");
+} catch (error) {
+  if (error instanceof InvalidResponseError) {
+    console.error("Agent returned:", error.receivedResponse);
+    console.error("Valid options:", error.validResponses);
+  } else if (error instanceof TimeoutError) {
+    console.error("Timeout after:", error.timeoutMs);
+  } else if (error instanceof NoResponseError) {
+    console.error("No response produced");
+  } else if (error instanceof MaxTurnsExceededError) {
+    console.error("Max turns exceeded:", error.maxTurns);
+  } else if (error instanceof SessionError) {
+    console.error("Session error:", error.cause);
+  }
+}
+```
+
+### Error Codes
+
+```typescript
+enum SimpleAgentErrorCode {
+  INVALID_RESPONSE = "INVALID_RESPONSE",
+  TIMEOUT = "TIMEOUT",
+  NO_RESPONSE = "NO_RESPONSE",
+  SESSION_ERROR = "SESSION_ERROR",
+  INVALID_CONFIG = "INVALID_CONFIG",
+  ABORTED = "ABORTED",
+  MAX_TURNS_EXCEEDED = "MAX_TURNS_EXCEEDED",
+}
+```
+
+## Examples
+
+### Yes/No Questions
+
+```typescript
+const VALID_RESPONSES = ["yes", "no"] as const;
+type YesNo = typeof VALID_RESPONSES[number];
+
+const runner = new SimpleClaudeRunner<YesNo>({
+  validResponses: VALID_RESPONSES,
+  cyrusHome: process.env.CYRUS_HOME!,
+  systemPrompt: "You are a helpful assistant. Answer questions concisely.",
+});
+
+const result = await runner.query(
+  "Does this code follow best practices?"
+);
+
+if (result.response === "yes") {
+  console.log("✅ Code looks good!");
+} else {
+  console.log("❌ Code needs improvements");
+}
+```
+
+### Approval Workflow
+
+```typescript
+const APPROVAL_OPTIONS = ["approve", "reject", "abstain"] as const;
+type ApprovalDecision = typeof APPROVAL_OPTIONS[number];
+
+const approvalRunner = new SimpleClaudeRunner<ApprovalDecision>({
+  validResponses: APPROVAL_OPTIONS,
+  cyrusHome: process.env.CYRUS_HOME!,
+  systemPrompt: "You are a code reviewer. Review PRs carefully.",
+  maxTurns: 5,
+});
+
+const result = await approvalRunner.query(
+  "Review this pull request and decide: approve, reject, or abstain",
+  { context: prDiff, allowFileReading: true }
+);
+
+switch (result.response) {
+  case "approve":
+    await mergePR();
+    break;
+  case "reject":
+    await requestChanges();
+    break;
+  case "abstain":
+    await requestHumanReview();
+    break;
+}
+```
+
+### With Progress Tracking
+
+```typescript
+const runner = new SimpleClaudeRunner({
+  validResponses: ["high", "medium", "low"] as const,
+  cyrusHome: process.env.CYRUS_HOME!,
+  onProgress: (event) => {
+    switch (event.type) {
+      case "started":
+        console.log("Session started:", event.sessionId);
+        break;
+      case "thinking":
+        console.log("Agent:", event.text);
+        break;
+      case "tool-use":
+        console.log("Using tool:", event.toolName);
+        break;
+      case "response-detected":
+        console.log("Candidate response:", event.candidateResponse);
+        break;
+      case "validating":
+        console.log("Validating response...");
+        break;
+    }
+  },
+});
+
+const result = await runner.query(
+  "Rate the priority of this bug: high, medium, or low"
+);
+```
+
+### Custom System Prompt
+
+```typescript
+const runner = new SimpleClaudeRunner({
+  validResponses: ["safe", "unsafe"] as const,
+  cyrusHome: process.env.CYRUS_HOME!,
+  systemPrompt: `You are a security analyzer.
+  Analyze code for security vulnerabilities.
+  Consider: injection attacks, authentication issues, data exposure.
+  Be conservative - mark as "unsafe" if you have any concerns.`,
+});
+
+const result = await runner.query(
+  "Analyze this function for security issues",
+  { context: functionCode, allowFileReading: false }
+);
+```
+
+## Extending for Other Agent SDKs
+
+To create implementations for other agent SDKs (e.g., OpenAI, Anthropic Direct API):
+
+```typescript
+import { SimpleAgentRunner } from "cyrus-simple-agent-runner";
+
+export class SimpleGPTRunner<T extends string> extends SimpleAgentRunner<T> {
+  protected async executeAgent(
+    prompt: string,
+    options?: SimpleAgentQueryOptions
+  ): Promise<SDKMessage[]> {
+    // Your GPT implementation here
+  }
+
+  protected extractResponse(messages: SDKMessage[]): string {
+    // Your response extraction logic
+  }
+}
+```
+
+## Architecture
+
+The package has two layers:
+
+1. **`SimpleAgentRunner`** (abstract base class)
+   - Handles configuration validation
+   - Manages response validation
+   - Provides timeout handling
+   - Emits progress events
+   - Defines the contract for implementations
+
+2. **`SimpleClaudeRunner`** (concrete implementation)
+   - Uses `cyrus-claude-runner` for execution
+   - Handles message parsing
+   - Cleans and normalizes responses
+   - Manages tool restrictions
+
+## Best Practices
+
+1. **Use const arrays for valid responses:**
+   ```typescript
+   const VALID = ["a", "b"] as const;
+   type Response = typeof VALID[number];
+   ```
+
+2. **Set reasonable timeouts:**
+   ```typescript
+   { timeoutMs: 30000, maxTurns: 5 }
+   ```
+
+3. **Handle all error types:**
+   ```typescript
+   catch (error) {
+     if (error instanceof InvalidResponseError) { /* ... */ }
+     else if (error instanceof TimeoutError) { /* ... */ }
+     // ... handle all types
+   }
+   ```
+
+4. **Use progress callbacks for observability:**
+   ```typescript
+   { onProgress: (e) => logger.info(e) }
+   ```
+
+5. **Restrict tools for simple queries:**
+   ```typescript
+   { allowFileReading: false } // Default behavior
+   ```
+
+## License
+
+MIT

package/dist/SimpleAgentRunner.d.ts

@@ -0,0 +1,52 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentProgressEvent, SimpleAgentQueryOptions, SimpleAgentResult, SimpleAgentRunnerConfig } from "./types.js";
+/**
+ * Abstract base class for simple agent runners that return enumerated responses.
+ *
+ * This class provides the core validation and flow control logic, while
+ * concrete implementations provide the actual agent execution.
+ */
+export declare abstract class SimpleAgentRunner<T extends string> {
+    protected readonly config: SimpleAgentRunnerConfig<T>;
+    protected readonly validResponseSet: Set<T>;
+    constructor(config: SimpleAgentRunnerConfig<T>);
+    /**
+     * Execute the agent with the given prompt and return a validated response.
+     *
+     * @param prompt - The question or instruction for the agent
+     * @param options - Optional query configuration
+     * @returns A validated response from the enumerated set
+     * @throws {InvalidResponseError} If agent returns invalid response
+     * @throws {TimeoutError} If execution times out
+     * @throws {NoResponseError} If agent produces no response
+     * @throws {SessionError} If underlying session fails
+     */
+    query(prompt: string, options?: SimpleAgentQueryOptions): Promise<SimpleAgentResult<T>>;
+    /**
+     * Validate the configuration
+     */
+    private validateConfig;
+    /**
+     * Check if a response is valid
+     */
+    protected isValidResponse(response: string): response is T;
+    /**
+     * Build the complete system prompt
+     */
+    protected buildSystemPrompt(): string;
+    /**
+     * Emit a progress event if callback is configured
+     */
+    protected emitProgress(event: AgentProgressEvent): void;
+    /**
+     * Abstract method: Execute the agent and return messages.
+     * Concrete implementations must provide this.
+     */
+    protected abstract executeAgent(prompt: string, options?: SimpleAgentQueryOptions): Promise<SDKMessage[]>;
+    /**
+     * Abstract method: Extract the final response from messages.
+     * Concrete implementations must provide this.
+     */
+    protected abstract extractResponse(messages: SDKMessage[]): string;
+}
+//# sourceMappingURL=SimpleAgentRunner.d.ts.map

package/dist/SimpleAgentRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimpleAgentRunner.d.ts","sourceRoot":"","sources":["../src/SimpleAgentRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAMjE,OAAO,KAAK,EACX,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,uBAAuB,EACvB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,8BAAsB,iBAAiB,CAAC,CAAC,SAAS,MAAM;IACvD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;gBAEhC,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC;IAM9C;;;;;;;;;;OAUG;IACG,KAAK,CACV,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAkEhC;;OAEG;IACH,OAAO,CAAC,cAAc;IAyBtB;;OAEG;IACH,SAAS,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,CAAC;IAI1D;;OAEG;IACH,SAAS,CAAC,iBAAiB,IAAI,MAAM;IAkBrC;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAMvD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,UAAU,EAAE,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM;CAClE"}

package/dist/SimpleAgentRunner.js

@@ -0,0 +1,120 @@
+import { InvalidResponseError, SimpleAgentError, SimpleAgentErrorCode, } from "./errors.js";
+/**
+ * Abstract base class for simple agent runners that return enumerated responses.
+ *
+ * This class provides the core validation and flow control logic, while
+ * concrete implementations provide the actual agent execution.
+ */
+export class SimpleAgentRunner {
+    config;
+    validResponseSet;
+    constructor(config) {
+        this.validateConfig(config);
+        this.config = config;
+        this.validResponseSet = new Set(config.validResponses);
+    }
+    /**
+     * Execute the agent with the given prompt and return a validated response.
+     *
+     * @param prompt - The question or instruction for the agent
+     * @param options - Optional query configuration
+     * @returns A validated response from the enumerated set
+     * @throws {InvalidResponseError} If agent returns invalid response
+     * @throws {TimeoutError} If execution times out
+     * @throws {NoResponseError} If agent produces no response
+     * @throws {SessionError} If underlying session fails
+     */
+    async query(prompt, options) {
+        const startTime = Date.now();
+        try {
+            // Set up timeout if configured
+            const timeoutPromise = this.config.timeoutMs
+                ? new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new SimpleAgentError(SimpleAgentErrorCode.TIMEOUT, `Operation timed out after ${this.config.timeoutMs}ms`));
+                    }, this.config.timeoutMs);
+                })
+                : null;
+            // Execute the agent (delegated to concrete implementation)
+            const executionPromise = this.executeAgent(prompt, options);
+            // Race between execution and timeout
+            const messages = timeoutPromise
+                ? await Promise.race([executionPromise, timeoutPromise])
+                : await executionPromise;
+            // Extract and validate response
+            const response = this.extractResponse(messages);
+            if (!this.isValidResponse(response)) {
+                throw new InvalidResponseError(response, Array.from(this.validResponseSet));
+            }
+            const durationMs = Date.now() - startTime;
+            // Extract session metadata
+            const sessionId = messages[0]?.session_id || null;
+            const resultMessage = messages.find((m) => m.type === "result");
+            const costUSD = resultMessage?.type === "result"
+                ? resultMessage.total_cost_usd
+                : undefined;
+            return {
+                response: response,
+                messages,
+                sessionId,
+                durationMs,
+                costUSD,
+            };
+        }
+        catch (error) {
+            if (error instanceof SimpleAgentError) {
+                throw error;
+            }
+            throw new SimpleAgentError(SimpleAgentErrorCode.SESSION_ERROR, error instanceof Error ? error.message : String(error), { originalError: error });
+        }
+    }
+    /**
+     * Validate the configuration
+     */
+    validateConfig(config) {
+        if (!config.validResponses || config.validResponses.length === 0) {
+            throw new SimpleAgentError(SimpleAgentErrorCode.INVALID_CONFIG, "validResponses must be a non-empty array");
+        }
+        // Check for duplicates
+        const uniqueResponses = new Set(config.validResponses);
+        if (uniqueResponses.size !== config.validResponses.length) {
+            throw new SimpleAgentError(SimpleAgentErrorCode.INVALID_CONFIG, "validResponses contains duplicate values");
+        }
+        if (!config.cyrusHome) {
+            throw new SimpleAgentError(SimpleAgentErrorCode.INVALID_CONFIG, "cyrusHome is required");
+        }
+    }
+    /**
+     * Check if a response is valid
+     */
+    isValidResponse(response) {
+        return this.validResponseSet.has(response);
+    }
+    /**
+     * Build the complete system prompt
+     */
+    buildSystemPrompt() {
+        const basePrompt = this.config.systemPrompt || "";
+        const validResponsesStr = Array.from(this.validResponseSet)
+            .map((r) => `"${r}"`)
+            .join(", ");
+        const constraintPrompt = `
+IMPORTANT: You must respond with EXACTLY one of the following values:
+${validResponsesStr}
+
+Your final response MUST be one of these exact strings, with no additional text, explanation, or formatting.
+Do not use markdown, code blocks, or quotes around your response.
+Simply output the chosen value as your final answer.
+`;
+        return `${basePrompt}\n\n${constraintPrompt}`;
+    }
+    /**
+     * Emit a progress event if callback is configured
+     */
+    emitProgress(event) {
+        if (this.config.onProgress) {
+            this.config.onProgress(event);
+        }
+    }
+}
+//# sourceMappingURL=SimpleAgentRunner.js.map

package/dist/SimpleAgentRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimpleAgentRunner.js","sourceRoot":"","sources":["../src/SimpleAgentRunner.ts"],"names":[],"mappings":"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"}

package/dist/SimpleClaudeRunner.d.ts

@@ -0,0 +1,28 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { SimpleAgentRunner } from "./SimpleAgentRunner.js";
+import type { SimpleAgentQueryOptions } from "./types.js";
+/**
+ * Concrete implementation using ClaudeRunner from cyrus-claude-runner package.
+ *
+ * This implementation uses the Claude Agent SDK to execute queries and
+ * constrains the responses to an enumerated set.
+ */
+export declare class SimpleClaudeRunner<T extends string> extends SimpleAgentRunner<T> {
+    /**
+     * Execute the agent using ClaudeRunner
+     */
+    protected executeAgent(prompt: string, options?: SimpleAgentQueryOptions): Promise<SDKMessage[]>;
+    /**
+     * Extract the final response from the last assistant message
+     */
+    protected extractResponse(messages: SDKMessage[]): string;
+    /**
+     * Clean the response text to extract the actual value
+     */
+    private cleanResponse;
+    /**
+     * Handle incoming messages for progress events
+     */
+    private handleMessage;
+}
+//# sourceMappingURL=SimpleClaudeRunner.d.ts.map

package/dist/SimpleClaudeRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimpleClaudeRunner.d.ts","sourceRoot":"","sources":["../src/SimpleClaudeRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;GAKG;AACH,qBAAa,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAE,SAAQ,iBAAiB,CAAC,CAAC,CAAC;IAC7E;;OAEG;cACa,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,UAAU,EAAE,CAAC;IA6DxB;;OAEG;IACH,SAAS,CAAC,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM;IAsCzD;;OAEG;IACH,OAAO,CAAC,aAAa;IAyBrB;;OAEG;IACH,OAAO,CAAC,aAAa;CA0BrB"}

package/dist/SimpleClaudeRunner.js

@@ -0,0 +1,150 @@
+import { ClaudeRunner } from "cyrus-claude-runner";
+import { NoResponseError, SessionError } from "./errors.js";
+import { SimpleAgentRunner } from "./SimpleAgentRunner.js";
+/**
+ * Concrete implementation using ClaudeRunner from cyrus-claude-runner package.
+ *
+ * This implementation uses the Claude Agent SDK to execute queries and
+ * constrains the responses to an enumerated set.
+ */
+export class SimpleClaudeRunner extends SimpleAgentRunner {
+    /**
+     * Execute the agent using ClaudeRunner
+     */
+    async executeAgent(prompt, options) {
+        const messages = [];
+        let sessionError = null;
+        // Build the full prompt with context if provided
+        const fullPrompt = options?.context
+            ? `${options.context}\n\n${prompt}`
+            : prompt;
+        // Create ClaudeRunner with configuration
+        const runner = new ClaudeRunner({
+            workingDirectory: this.config.workingDirectory,
+            cyrusHome: this.config.cyrusHome,
+            model: this.config.model,
+            fallbackModel: this.config.fallbackModel,
+            maxTurns: this.config.maxTurns,
+            systemPrompt: this.buildSystemPrompt(),
+            // Limit tools for simple queries
+            disallowedTools: options?.allowFileReading
+                ? []
+                : ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
+            allowedDirectories: options?.allowedDirectories,
+        });
+        // Set up event handlers
+        runner.on("message", (message) => {
+            messages.push(message);
+            this.handleMessage(message);
+        });
+        runner.on("error", (error) => {
+            sessionError = error;
+        });
+        runner.on("complete", () => {
+            this.emitProgress({ type: "validating", response: "complete" });
+        });
+        try {
+            this.emitProgress({ type: "started", sessionId: null });
+            await runner.start(fullPrompt);
+            // Update session ID in progress events
+            const sessionId = messages[0]?.session_id || null;
+            if (sessionId) {
+                this.emitProgress({ type: "started", sessionId });
+            }
+            if (sessionError) {
+                throw new SessionError(sessionError, messages);
+            }
+            return messages;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw error;
+            }
+            throw new SessionError(new Error(String(error)), messages);
+        }
+    }
+    /**
+     * Extract the final response from the last assistant message
+     */
+    extractResponse(messages) {
+        // Find the last assistant message with text content
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const message = messages[i];
+            if (!message)
+                continue;
+            if (message.type === "assistant" &&
+                "message" in message &&
+                message.message &&
+                message.message.content) {
+                // Extract text from content blocks
+                for (const block of message.message.content) {
+                    if (typeof block === "object" &&
+                        block !== null &&
+                        "type" in block &&
+                        block.type === "text" &&
+                        "text" in block) {
+                        // Clean the response (remove whitespace, markdown, etc.)
+                        const cleaned = this.cleanResponse(block.text);
+                        if (cleaned) {
+                            this.emitProgress({
+                                type: "response-detected",
+                                candidateResponse: cleaned,
+                            });
+                            return cleaned;
+                        }
+                    }
+                }
+            }
+        }
+        throw new NoResponseError(messages);
+    }
+    /**
+     * Clean the response text to extract the actual value
+     */
+    cleanResponse(text) {
+        // Remove markdown code blocks
+        let cleaned = text.replace(/```[\s\S]*?```/g, "");
+        // Remove inline code
+        cleaned = cleaned.replace(/`([^`]+)`/g, "$1");
+        // Remove quotes
+        cleaned = cleaned.replace(/^["']|["']$/g, "");
+        // Trim whitespace
+        cleaned = cleaned.trim();
+        // If the response is multi-line, try to find a valid response on any line
+        const lines = cleaned.split("\n").map((l) => l.trim());
+        for (const line of lines) {
+            if (this.isValidResponse(line)) {
+                return line;
+            }
+        }
+        // Return the cleaned text (will be validated by caller)
+        return cleaned;
+    }
+    /**
+     * Handle incoming messages for progress events
+     */
+    handleMessage(message) {
+        if (message.type === "assistant" &&
+            "message" in message &&
+            message.message &&
+            message.message.content) {
+            for (const block of message.message.content) {
+                if (typeof block === "object" && block !== null && "type" in block) {
+                    if (block.type === "text" && "text" in block) {
+                        this.emitProgress({ type: "thinking", text: block.text });
+                    }
+                    else if (block.type === "tool_use" &&
+                        "name" in block &&
+                        "input" in block) {
+                        this.emitProgress({
+                            type: "tool-use",
+                            toolName: block.name,
+                            input: block.input,
+                        });
+                    }
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=SimpleClaudeRunner.js.map