Cloud Executor Reference

// Cloud-only — not available in the npm package
import { CloudExecutor } from './cloud-executor.js';

const executor = new CloudExecutor(
  apiUrl: string,
  apiKey: string,
  config?: Partial<CloudExecutorConfig>
);

interface CloudExecutorConfig {
  pollIntervalMs: number;      // Base polling interval (default: 1000)
  maxPollIntervalMs: number;   // Max polling interval after backoff (default: 10000)
  timeoutMs: number;           // Total job timeout (default: 660000 = 11 minutes)
  maxRetries: number;          // Max retries for transient errors (default: 5)
  retryBaseDelayMs: number;    // Base delay for exponential backoff (default: 1000)
  retryMaxDelayMs: number;     // Max delay for exponential backoff (default: 30000)
  jitterFactor: number;        // Jitter to prevent thundering herd (default: 0.1)
}

async execute(request: ExecutionRequest): Promise<ExecutionResult>

interface ExecutionRequest {
  prompt: string;           // Full prompt for the AI
  model: string;            // Model to use (e.g., 'claude-sonnet-4-20250514')
  maxTokens: number;        // Maximum output tokens
  streamId: string;         // Stream identifier for tracking
  timeoutMs?: number;       // Per-request timeout override
  structuredPrompt?: StructuredPrompt;  // Optional: caching hints
}

interface ExecutionResult {
  success: boolean;         // Whether execution succeeded
  rawResponse: string;      // Raw AI response text
  artifact?: StreamArtifact; // Parsed artifact (file operations)
  tokensUsed: {
    input: number;          // Input tokens consumed
    output: number;         // Output tokens consumed
  };
  error?: string;           // Error message if failed
}

// Cloud-only — not available in the npm package
import { CloudExecutor } from './cloud-executor.js';

const executor = new CloudExecutor(
  'https://api.orchex.dev',
  process.env.ORCHEX_API_KEY!
);

const result = await executor.execute({
  prompt: 'Create a hello world function in src/hello.ts',
  model: 'claude-sonnet-4-20250514',
  maxTokens: 16384,
  streamId: 'hello-world'
});

if (result.success) {
  console.log('Files changed:', result.artifact?.filesChanged);
  console.log('Tokens used:', result.tokensUsed);
} else {
  console.error('Execution failed:', result.error);
}

const executor = new CloudExecutor(
  'https://api.orchex.dev',
  process.env.ORCHEX_API_KEY!,
  {
    timeoutMs: 300000,        // 5 minute timeout
    maxRetries: 3,            // Fewer retries
    pollIntervalMs: 2000,     // Start polling at 2s
    maxPollIntervalMs: 5000,  // Cap polling at 5s
  }
);

// Long-running task needs longer timeout
const result = await executor.execute({
  prompt: longComplexPrompt,
  model: 'claude-sonnet-4-20250514',
  maxTokens: 16384,
  streamId: 'complex-refactor',
  timeoutMs: 900000  // 15 minutes for this specific request
});

┌─────────────────┐
│   Submit Job    │
│  POST /execute  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Poll Status   │◄──────────────┐
│  GET /job/:id   │               │
└────────┬────────┘               │
         │                        │
    ┌────┴────┐                   │
    │ Status? │                   │
    └────┬────┘                   │
         │                        │
    ┌────┼────┬────────┐          │
    │    │    │        │          │
    ▼    ▼    ▼        ▼          │
 pending running completed failed │
    │    │       │        │       │
    └────┴───────┼────────┘       │
         │       │                │
         │       ▼                │
         │  Return Result         │
         │                        │
         └──────(wait)────────────┘

delay = min(baseDelay * 2^attempt, maxDelay) ± jitter

// Timeout result structure
{
  success: false,
  rawResponse: '',
  tokensUsed: { input: 1234, output: 567 },  // Tokens used before timeout
  error: 'Cloud execution timed out after 660000ms (job cancelled)'
}

\`\`\`orchex-artifact
{
  "streamId": "hello-world",
  "status": "complete",
  "operations": [...],
  "filesChanged": ["src/hello.ts"],
  "summary": "Created hello world function"
}
\`\`\`

{
  "streamId": "hello-world",
  "prompt": "Create a hello world function...",
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 16384,
  "timeoutMs": 660000
}

{
  "jobId": "job_abc123def456"
}

{
  "status": "running"
}

{
  "status": "completed",
  "output": "...",
  "artifact": {...},
  "tokensUsed": { "input": 1000, "output": 500 }
}

{
  "status": "failed",
  "error": "Error message"
}

{
  "cancelled": true
}

// Quick tasks: shorter timeout
{ timeoutMs: 120000 }  // 2 minutes

// Complex refactoring: longer timeout
{ timeoutMs: 600000 }  // 10 minutes

// Batch processing: start with longer intervals
{
  pollIntervalMs: 5000,
  maxPollIntervalMs: 15000
}

const result = await executor.execute(request);
if (!result.success) {
  // Handle failure
  console.error(result.error);
  // Check tokensUsed for cost tracking even on failure
}

if (result.error?.includes('timed out')) {
  // Consider retrying with longer timeout
} else if (result.error?.includes('rate limit')) {
  // Back off and retry later
} else if (result.error?.includes('401')) {
  // Check API key
}

let totalTokens = { input: 0, output: 0 };

for (const stream of streams) {
  const result = await executor.execute(stream);
  totalTokens.input += result.tokensUsed.input;
  totalTokens.output += result.tokensUsed.output;
}

console.log(`Total tokens: ${totalTokens.input} in, ${totalTokens.output} out`);

const result = await executor.execute({
  ...request,
  structuredPrompt: {
    systemContent: '...',      // Highly cacheable
    projectContext: '...',     // Cacheable within orchestration
    streamContext: '...',      // Cacheable per stream
    taskContent: '...',        // Not cached
    fullPrompt: '...',
    cachingHints: [...]
  }
});