@wundam/orchex 1.0.0-rc.3 → 1.0.0-rc.30

package/README.md

@@ -1,8 +1,8 @@
 # orchex
 
-**Turn a plan into parallel AI agents that can't break each other's code.**
+**Describe what you want. Orchex plans, parallelizes, and executes — safely.**
 
-The orchestration engine inside your AI coding assistant. Paste a plan doc, orchex splits it into parallel streams with file ownership enforcement, self-healing failures, and multi-LLM routing. Your AI assistant is the driver. Orchex is the engine.
+The orchestration engine inside your AI coding assistant. Describe your intent, orchex auto-generates a plan, splits it into parallel streams with file ownership enforcement, self-healing failures, and multi-LLM routing. Your AI assistant is the driver. Orchex is the engine.
 
 ## Why Orchex
 
@@ -10,20 +10,23 @@ Your AI assistant does tasks one at a time. Orchex makes it do 10 at once — sa
 
 - **Parallel Execution** — Multiple streams run simultaneously in dependency-aware waves. 5-10x faster than serial prompting.
 - **Ownership Enforcement** — Each stream can only modify files in its `owns` array. No two agents touch the same file. Zero conflicts.
-- **`orchex learn`** — The magic command. Paste a markdown plan, get executable parallel streams with dependency inference and anti-pattern detection. No other tool does this.
-- **Self-Healing** — Categorized error analysis with targeted fix streams. Not blind retry.
-- **Multi-LLM** — OpenAI, Gemini, Claude, DeepSeek, Ollama. Route different orchestrations to different providers.
+- **`orchex run`** — Describe what you want, get parallel execution. Auto-generates plans, previews waves, executes with ownership enforcement.
+- **`orchex learn`** — The advanced path. Paste a markdown plan, get executable parallel streams with dependency inference and anti-pattern detection.
+- **Self-Healing** — Categorized error analysis with targeted fix streams. Not blind retry. Model validation before execution prevents wasted API calls.
+- **Multi-LLM** — OpenAI, Gemini, Claude, DeepSeek, Kimi (Moonshot AI), Ollama, AWS Bedrock. Dynamic model registry auto-discovers available models. Key-aware routing prevents "model not found" errors.
 - **BYOK** — Bring your own API key from any supported provider. You control costs.
 
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) >= 18
-- LLM API key (one of the following):
+- LLM API key — set via environment variable **or** store on the [dashboard](https://orchex.dev/dashboard/keys) and sync with `orchex login`:
   - `ANTHROPIC_API_KEY` for Anthropic Claude
-  - `OPENAI_API_KEY` for OpenAI (GPT-4.1, GPT-4.5)
+  - `OPENAI_API_KEY` for OpenAI (GPT-4.1, o1, o3)
   - `GEMINI_API_KEY` for Google Gemini
-  - `DEEPSEEK_API_KEY` for DeepSeek (V3, Coder, Reasoner)
-  - Or configure Ollama for local models
+  - `DEEPSEEK_API_KEY` for DeepSeek (V3, Coder, R1)
+  - `KIMI_API_KEY` for Kimi / Moonshot AI (K2, moonshot-v1; `MOONSHOT_API_KEY` alias accepted)
+  - Configure Ollama for local models
+  - `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` for AWS Bedrock
 
 ## Install
 
@@ -45,11 +48,11 @@ Connect to orchex cloud for managed execution:
 orchex login
 ```
 
-Your browser opens — log in or create a free account, click **Allow**. Token saved automatically.
+Your browser opens — log in or create a free account, click **Allow**. Token saved automatically. API keys stored on the dashboard are synced to your local machine so `orchex run` works without environment variables.
 
 ```bash
 orchex status          # Check tier and trial runs
-orchex logout          # Clear credentials
+orchex logout          # Clear credentials and cached keys
 orchex --help          # All commands
 ```
 
@@ -57,19 +60,35 @@ See the [cloud setup guide](docs/user-guide/cloud-setup.md) for full details.
 
 ## MCP Configuration
 
-Add to your MCP config (e.g. project `.mcp.json`):
+Auto-configure for your IDE (Cursor, Windsurf, Claude Code):
+
+```bash
+npx @wundam/orchex setup
+```
+
+Or manually add to your MCP config (e.g. project `.mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "orchex": {
       "command": "npx",
-      "args": ["@wundam/orchex"]
+      "args": ["-y", "@wundam/orchex"]
     }
   }
 }
 ```
 
+### Zero-Config LLM Discovery
+
+Once connected, your AI assistant automatically receives:
+
+- **Instructions** — Core concepts, all 12 tools, provider setup, and tier info. No prompt engineering needed.
+- **8 on-demand resources** via `orchex://` URIs — deep guides on streams, waves, ownership, self-healing, providers, examples, and API reference. The LLM reads these when it needs them.
+- **IDE auto-detection** — `orchex setup` detects Cursor, Windsurf, and other MCP clients, writes the correct config, and merges with existing MCP servers.
+
+Your AI assistant knows how to use Orchex the moment it connects.
+
 ## Usage
 
 ### 1. Initialize an orchestration
@@ -133,6 +152,22 @@ orchex.status()
 orchex.complete({ archive: true })
 ```
 
+## CLI Commands
+
+```bash
+orchex run "Add user auth"          # Auto-plan and execute from intent
+orchex run "..." --yes              # Skip approval prompt
+orchex run "..." --dry-run          # Generate plan only, don't execute
+orchex run "..." --provider openai  # Use specific provider
+orchex setup                        # Auto-detect IDE and configure MCP
+orchex setup --ide cursor           # Target a specific IDE
+orchex login                        # Authenticate with orchex cloud
+orchex logout                       # Log out of cloud
+orchex status                       # Show login state, tier, trial runs
+orchex config                       # Show/set configuration
+orchex reset-learning               # Clear learning data
+```
+
 ## MCP Tools
 
 | Tool | Description |
@@ -142,10 +177,13 @@ orchex.complete({ archive: true })
 | `status` | Get orchestration progress and wave info |
 | `execute` | Run the orchestration — calls LLM API, applies artifacts, verifies |
 | `complete` | Mark streams done or archive orchestration |
-| `learn` | Parse a planning document, generate atomic stream definitions, and surface prerequisites |
-| `init-plan` | Generate an annotated plan template optimized for `orchex learn` |
-| `recover` | Detect and recover stuck streams from mid-execution failures |
-| `reload` | Restart the MCP server process (picks up config/code changes) |
+| `recover` | Reset stuck/failed streams for retry or skip |
+| `learn` | Parse a markdown plan into stream definitions |
+| `init-plan` | Generate an annotated plan template |
+| `auto` | One-shot: intent → plan → preview → execute → report |
+| `reset-learning` | Clear learning data (thresholds, patterns, reports) |
+| `rollback-stream` | Revert a stream's file changes via git |
+| `reload` | Restart MCP server to pick up code changes |
 
 ## Stream Definition
 
@@ -196,7 +234,11 @@ For local development, point `.mcp.json` to your local build:
 
 ## Pricing
 
-See [orchex.dev/pricing](https://orchex.dev/pricing) for current plans and limits. Free local tier included.
+Free local tier included — no account required. Cloud tiers unlock more streams, waves, providers, and run history.
+
+**Founding Members** — 50 slots at $49/year with Pro-level limits (200 runs, 30 agents, 20 waves, unlimited providers). Locked-in pricing for life. [Claim a slot](https://orchex.dev/founders) while they last.
+
+See [orchex.dev/pricing](https://orchex.dev/pricing) for all plans and limits.
 
 ## License
 

package/dist/artifacts.js

@@ -420,6 +420,10 @@ export async function writeArtifact(projectDir, streamId, artifact) {
     await fs.writeFile(artifactPath, JSON.stringify(artifact, null, 2), 'utf-8');
     return artifactPath;
 }
+// Artifact-application trust boundary. Plan-level ownership is enforced
+// upstream by validatePlan (src/intelligence/plan-contract.ts); this
+// function guards the different trust boundary where LLM-generated
+// artifacts try to apply their output.
 /**
  * Check whether all file operations fall within the stream's owns patterns.
  *

package/dist/cloud-executor.d.ts

@@ -0,0 +1,71 @@
+import type { ExecutorStrategy, ExecutionRequest, ExecutionResult } from './types.js';
+/**
+ * Configuration for CloudExecutor retry and polling behavior.
+ */
+export interface CloudExecutorConfig {
+    /** Base polling interval in milliseconds. Default: 1000 (1 second) */
+    pollIntervalMs: number;
+    /** Maximum polling interval after backoff. Default: 10000 (10 seconds) */
+    maxPollIntervalMs: number;
+    /** Total timeout for job execution in milliseconds. Default: 660000 (11 minutes) */
+    timeoutMs: number;
+    /** Maximum retries for transient errors (429, 5xx). Default: 5 */
+    maxRetries: number;
+    /** Base delay for exponential backoff in milliseconds. Default: 1000 */
+    retryBaseDelayMs: number;
+    /** Maximum delay for exponential backoff in milliseconds. Default: 30000 */
+    retryMaxDelayMs: number;
+    /** Jitter factor (0-1) to randomize delays and prevent thundering herd. Default: 0.1 */
+    jitterFactor: number;
+}
+/**
+ * CloudExecutor submits jobs to the orchex cloud server and polls for completion.
+ *
+ * Features:
+ * - Exponential backoff with jitter for transient errors (429, 5xx)
+ * - Respects Retry-After header from rate limit responses
+ * - Adaptive polling intervals to reduce server load
+ * - Configurable timeouts and retry limits
+ */
+export declare class CloudExecutor implements ExecutorStrategy {
+    private apiUrl;
+    private apiKey;
+    readonly provider = "orchex-cloud";
+    private config;
+    constructor(apiUrl: string, apiKey: string, config?: Partial<CloudExecutorConfig>);
+    execute(request: ExecutionRequest): Promise<ExecutionResult>;
+    /**
+     * Submit a job to the cloud server with retry logic for transient errors.
+     */
+    private submitJobWithRetry;
+    /**
+     * Poll for job completion with adaptive intervals and retry logic.
+     * @param jobId The job ID to poll
+     * @param timeoutMs Effective timeout in milliseconds
+     */
+    private pollForCompletionWithRetry;
+    /**
+     * Cancel a job on the cloud server to stop token consumption.
+     * Best effort — silently fails if server is unreachable.
+     */
+    private cancelJob;
+    /**
+     * Fetch final token usage from job state on timeout.
+     * Best effort — returns zeros if fetch fails.
+     */
+    private fetchFinalTokenUsage;
+    /**
+     * Calculate retry delay with exponential backoff and jitter.
+     */
+    private calculateRetryDelay;
+    /**
+     * Parse Retry-After header (supports both seconds and HTTP-date formats).
+     */
+    private parseRetryAfter;
+    /**
+     * Add jitter to a delay to prevent thundering herd.
+     * Returns delay ± (jitterFactor * delay).
+     */
+    private addJitter;
+    private sleep;
+}

package/dist/cloud-executor.js

@@ -0,0 +1,364 @@
+import { extractArtifact } from './artifacts.js';
+import { validateOwnership } from './utils/ownership-validator.js';
+function parseProviderErrorBody(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const message = parsed?.error?.message ?? parsed?.message;
+        if (typeof message === 'string')
+            return message;
+    }
+    catch {
+        // Not JSON — return null
+    }
+    return null;
+}
+/**
+ * Returns actionable error messages for cloud API failures.
+ * Status-code-specific guidance tells users exactly how to fix each error.
+ */
+function formatCloudError(status, body) {
+    const detail = body ? ` (${body.slice(0, 120)})` : '';
+    switch (status) {
+        case 401:
+            return `Authentication failed (401)${detail}.\n\nYour API token has expired or been revoked. Run \`orchex login\` to authenticate again.`;
+        case 402:
+            return `Payment required (402)${detail}.\n\nCheck your subscription at https://orchex.dev/dashboard/billing`;
+        case 403:
+            return `Access denied (403)${detail}.\n\nYour account may not have permission for this operation.`;
+        case 404: {
+            const modelMatch = body.match(/model[:\s]+(\S+)/i);
+            const modelHint = modelMatch ? ` "${modelMatch[1]}"` : '';
+            return `Model${modelHint} not found (404)${detail}.\n\nRun \`orchex config --model <model>\` to use a different model.`;
+        }
+        case 400: {
+            const providerMsg = parseProviderErrorBody(body);
+            if (providerMsg && /credit balance|insufficient|billing/i.test(providerMsg)) {
+                return `LLM provider billing error (400): ${providerMsg}\n\nTop up credits at your provider's billing page, or switch providers with \`orchex config --provider <provider>\`.`;
+            }
+            if (providerMsg) {
+                return `LLM provider error (400): ${providerMsg}`;
+            }
+            return `Cloud API error: 400${detail}`;
+        }
+        case 429:
+            return `Quota exceeded (429)${detail}.\n\nYou've used all cloud runs for this period. Upgrade at https://orchex.dev/pricing`;
+        default:
+            return `Cloud API error: ${status}${detail}`;
+    }
+}
+const DEFAULT_CONFIG = {
+    pollIntervalMs: 1000, // Start at 1s for faster initial response
+    maxPollIntervalMs: 10000,
+    timeoutMs: 660_000, // 11 minutes — buffer over server's 10min to allow completion
+    maxRetries: 5,
+    retryBaseDelayMs: 1000,
+    retryMaxDelayMs: 30000,
+    jitterFactor: 0.1, // Reduced jitter for more predictable timing
+};
+/** HTTP status codes that are retryable (transient errors). */
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+/**
+ * CloudExecutor submits jobs to the orchex cloud server and polls for completion.
+ *
+ * Features:
+ * - Exponential backoff with jitter for transient errors (429, 5xx)
+ * - Respects Retry-After header from rate limit responses
+ * - Adaptive polling intervals to reduce server load
+ * - Configurable timeouts and retry limits
+ */
+export class CloudExecutor {
+    apiUrl;
+    apiKey;
+    provider = 'orchex-cloud';
+    config;
+    constructor(apiUrl, apiKey, config = {}) {
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    async execute(request) {
+        // 1. Submit job with retry
+        const submitResult = await this.submitJobWithRetry(request);
+        if (!submitResult.success) {
+            return {
+                success: false,
+                rawResponse: '',
+                tokensUsed: { input: 0, output: 0 },
+                error: submitResult.error,
+            };
+        }
+        const jobId = submitResult.jobId;
+        // 2. Poll for completion with retry and adaptive intervals
+        // Use request-level timeout if provided, otherwise fall back to config
+        const effectiveTimeout = request.timeoutMs ?? this.config.timeoutMs;
+        return this.pollForCompletionWithRetry(jobId, effectiveTimeout, request.ownership);
+    }
+    /**
+     * Submit a job to the cloud server with retry logic for transient errors.
+     */
+    async submitJobWithRetry(request) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+            try {
+                const submitRes = await fetch(`${this.apiUrl}/api/v1/execute`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${this.apiKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        streamId: request.streamId,
+                        prompt: request.prompt,
+                        model: request.model,
+                        maxTokens: request.maxTokens,
+                        timeoutMs: this.config.timeoutMs,
+                        ...(request.fileContext && { fileContext: request.fileContext }),
+                        ...(request.ownership && { ownership: request.ownership }),
+                    }),
+                });
+                if (submitRes.ok) {
+                    const { jobId } = (await submitRes.json());
+                    return { success: true, jobId };
+                }
+                // Check if error is retryable
+                if (RETRYABLE_STATUS_CODES.has(submitRes.status)) {
+                    lastError = `Cloud API error: ${submitRes.status}`;
+                    if (attempt < this.config.maxRetries) {
+                        const delay = this.calculateRetryDelay(attempt, submitRes);
+                        await this.sleep(delay);
+                        continue;
+                    }
+                }
+                else {
+                    // Non-retryable error (400, 401, 403, 404, etc.)
+                    const body = await submitRes.text().catch(() => '');
+                    return {
+                        success: false,
+                        error: formatCloudError(submitRes.status, body),
+                    };
+                }
+            }
+            catch (err) {
+                lastError = `Network error: ${err.message}`;
+                if (attempt < this.config.maxRetries) {
+                    const delay = this.calculateRetryDelay(attempt);
+                    await this.sleep(delay);
+                    continue;
+                }
+            }
+        }
+        return {
+            success: false,
+            error: `Failed after ${this.config.maxRetries + 1} attempts: ${lastError}`,
+        };
+    }
+    /**
+     * Poll for job completion with adaptive intervals and retry logic.
+     * @param jobId The job ID to poll
+     * @param timeoutMs Effective timeout in milliseconds
+     */
+    async pollForCompletionWithRetry(jobId, timeoutMs, ownership) {
+        const deadline = Date.now() + timeoutMs;
+        let pollInterval = this.config.pollIntervalMs;
+        let consecutiveErrors = 0;
+        while (Date.now() < deadline) {
+            try {
+                const pollRes = await fetch(`${this.apiUrl}/api/v1/job/${jobId}`, {
+                    headers: { 'Authorization': `Bearer ${this.apiKey}` },
+                });
+                if (pollRes.ok) {
+                    consecutiveErrors = 0; // Reset error count on success
+                    const job = (await pollRes.json());
+                    if (job.status === 'completed') {
+                        const rawResponse = job.output ?? '';
+                        // Use server-provided artifact if available, otherwise extract client-side
+                        const artifact = job.artifact ?? extractArtifact(rawResponse);
+                        // If artifact extraction fails (both server and client), mark as failure
+                        if (!artifact) {
+                            return {
+                                success: false,
+                                rawResponse,
+                                tokensUsed: job.tokensUsed ?? { input: 0, output: 0 },
+                                error: 'No valid orchex-artifact block found in response',
+                            };
+                        }
+                        // Validate artifact against ownership constraints (defense-in-depth)
+                        if (ownership && artifact) {
+                            const validation = validateOwnership(artifact, ownership);
+                            if (!validation.valid) {
+                                return {
+                                    success: false,
+                                    rawResponse,
+                                    tokensUsed: job.tokensUsed ?? { input: 0, output: 0 },
+                                    error: validation.error,
+                                };
+                            }
+                        }
+                        return {
+                            success: true,
+                            rawResponse,
+                            artifact,
+                            tokensUsed: job.tokensUsed ?? { input: 0, output: 0 },
+                        };
+                    }
+                    if (job.status === 'failed') {
+                        const rawError = job.error ?? 'Cloud execution failed';
+                        const providerMsg = parseProviderErrorBody(rawError);
+                        const formattedError = providerMsg
+                            ? (/credit balance|insufficient|billing/i.test(providerMsg)
+                                ? `LLM provider billing error: ${providerMsg}\n\nTop up credits at your provider's billing page, or switch providers with \`orchex config --provider <provider>\`.`
+                                : `LLM provider error: ${providerMsg}`)
+                            : rawError;
+                        return {
+                            success: false,
+                            rawResponse: job.output ?? '',
+                            tokensUsed: job.tokensUsed ?? { input: 0, output: 0 },
+                            error: formattedError,
+                        };
+                    }
+                    // Job still pending/running - wait with adaptive interval
+                    const delay = this.addJitter(pollInterval);
+                    await this.sleep(delay);
+                    // Gradually increase poll interval to reduce server load (max: maxPollIntervalMs)
+                    pollInterval = Math.min(pollInterval * 1.1, this.config.maxPollIntervalMs);
+                    continue;
+                }
+                // Handle poll error
+                if (RETRYABLE_STATUS_CODES.has(pollRes.status)) {
+                    consecutiveErrors++;
+                    // For rate limiting, back off significantly
+                    if (pollRes.status === 429) {
+                        const retryAfter = this.parseRetryAfter(pollRes);
+                        const backoffDelay = retryAfter ?? this.calculateRetryDelay(consecutiveErrors);
+                        await this.sleep(backoffDelay);
+                        // Increase base poll interval to reduce future rate limiting
+                        pollInterval = Math.min(pollInterval * 2, this.config.maxPollIntervalMs);
+                        continue;
+                    }
+                    // For server errors, use standard retry logic
+                    if (consecutiveErrors <= this.config.maxRetries) {
+                        const delay = this.calculateRetryDelay(consecutiveErrors - 1, pollRes);
+                        await this.sleep(delay);
+                        continue;
+                    }
+                }
+                // Non-retryable error or max retries exceeded — read body for diagnostic context
+                let pollBody = '';
+                try {
+                    pollBody = await pollRes.text();
+                }
+                catch { /* ignore unreadable body */ }
+                return {
+                    success: false,
+                    rawResponse: '',
+                    tokensUsed: { input: 0, output: 0 },
+                    error: formatCloudError(pollRes.status, pollBody) + ` (after ${consecutiveErrors} retries)`,
+                };
+            }
+            catch (err) {
+                consecutiveErrors++;
+                if (consecutiveErrors <= this.config.maxRetries) {
+                    const delay = this.calculateRetryDelay(consecutiveErrors - 1);
+                    await this.sleep(delay);
+                    continue;
+                }
+                return {
+                    success: false,
+                    rawResponse: '',
+                    tokensUsed: { input: 0, output: 0 },
+                    error: `Network error: ${err.message} (after ${consecutiveErrors} retries)`,
+                };
+            }
+        }
+        // On timeout:
+        // 1. Cancel the job to stop further token consumption
+        // 2. Fetch final token usage for cost tracking
+        await this.cancelJob(jobId);
+        const tokensUsed = await this.fetchFinalTokenUsage(jobId);
+        return {
+            success: false,
+            rawResponse: '',
+            tokensUsed,
+            error: `Cloud execution timed out after ${timeoutMs}ms (job cancelled)`,
+        };
+    }
+    /**
+     * Cancel a job on the cloud server to stop token consumption.
+     * Best effort — silently fails if server is unreachable.
+     */
+    async cancelJob(jobId) {
+        try {
+            await fetch(`${this.apiUrl}/api/v1/job/${jobId}/cancel`, {
+                method: 'POST',
+                headers: { 'Authorization': `Bearer ${this.apiKey}` },
+            });
+        }
+        catch {
+            // Best effort — ignore errors
+        }
+    }
+    /**
+     * Fetch final token usage from job state on timeout.
+     * Best effort — returns zeros if fetch fails.
+     */
+    async fetchFinalTokenUsage(jobId) {
+        try {
+            const res = await fetch(`${this.apiUrl}/api/v1/job/${jobId}`, {
+                headers: { 'Authorization': `Bearer ${this.apiKey}` },
+            });
+            if (res.ok) {
+                const job = (await res.json());
+                return job.tokensUsed ?? { input: 0, output: 0 };
+            }
+        }
+        catch {
+            // Best effort — ignore errors
+        }
+        return { input: 0, output: 0 };
+    }
+    /**
+     * Calculate retry delay with exponential backoff and jitter.
+     */
+    calculateRetryDelay(attempt, response) {
+        // Check for Retry-After header
+        if (response) {
+            const retryAfter = this.parseRetryAfter(response);
+            if (retryAfter)
+                return retryAfter;
+        }
+        // Exponential backoff: baseDelay * 2^attempt
+        const exponentialDelay = this.config.retryBaseDelayMs * Math.pow(2, attempt);
+        const cappedDelay = Math.min(exponentialDelay, this.config.retryMaxDelayMs);
+        return this.addJitter(cappedDelay);
+    }
+    /**
+     * Parse Retry-After header (supports both seconds and HTTP-date formats).
+     */
+    parseRetryAfter(response) {
+        const retryAfter = response.headers.get('retry-after');
+        if (!retryAfter)
+            return undefined;
+        // Try parsing as seconds
+        const seconds = parseInt(retryAfter, 10);
+        if (!isNaN(seconds)) {
+            return seconds * 1000;
+        }
+        // Try parsing as HTTP-date
+        const date = Date.parse(retryAfter);
+        if (!isNaN(date)) {
+            return Math.max(0, date - Date.now());
+        }
+        return undefined;
+    }
+    /**
+     * Add jitter to a delay to prevent thundering herd.
+     * Returns delay ± (jitterFactor * delay).
+     */
+    addJitter(delay) {
+        const jitter = delay * this.config.jitterFactor;
+        return delay + (Math.random() * 2 - 1) * jitter;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/cloud-sync.d.ts

@@ -0,0 +1,8 @@
+import type { Config } from './config.js';
+import type { ExecutionReport } from './intelligence/index.js';
+/**
+ * Fire-and-forget sync of an execution report to the cloud dashboard.
+ * Only runs when user is logged in (mode=cloud + apiKey present).
+ * Retries once on transient server errors. Logs warnings on failure.
+ */
+export declare function syncReportToCloud(config: Config, report: ExecutionReport): Promise<void>;

package/dist/cloud-sync.js

@@ -0,0 +1,52 @@
+/** HTTP status codes that are retryable (transient server errors). */
+const RETRYABLE_STATUS = new Set([500, 502, 503, 504]);
+/**
+ * Fire-and-forget sync of an execution report to the cloud dashboard.
+ * Only runs when user is logged in (mode=cloud + apiKey present).
+ * Retries once on transient server errors. Logs warnings on failure.
+ */
+export async function syncReportToCloud(config, report) {
+    if (config.mode !== 'cloud' || !config.apiKey)
+        return;
+    const apiUrl = config.apiUrl;
+    const maxAttempts = 2;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const resp = await fetch(`${apiUrl}/api/v1/history/sync`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${config.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ report }),
+            });
+            if (resp.ok)
+                return;
+            if (resp.status === 401) {
+                console.warn('Cloud sync: token expired. Run `orchex login` to re-authenticate.');
+                return;
+            }
+            if (RETRYABLE_STATUS.has(resp.status) && attempt < maxAttempts) {
+                await new Promise(r => setTimeout(r, 1000));
+                continue;
+            }
+            // Capture error body for diagnostics
+            let detail = '';
+            try {
+                const body = await resp.json();
+                if (body?.error)
+                    detail = `: ${body.error}`;
+            }
+            catch { /* response may not be JSON */ }
+            console.warn(`Cloud sync failed: HTTP ${resp.status}${detail} (run ${report.runId}). History may be incomplete.`);
+            return;
+        }
+        catch {
+            if (attempt < maxAttempts) {
+                await new Promise(r => setTimeout(r, 1000));
+                continue;
+            }
+            console.warn(`Cloud sync failed: network error (run ${report.runId}). History may be incomplete.`);
+        }
+    }
+}