@wundam/orchex 1.0.0-rc.1

package/dist/ownership.d.ts

@@ -0,0 +1,44 @@
+import type { FileOperation } from './types.js';
+export interface OwnershipCheckOptions {
+    /**
+     * Allow common project files even if not in owns list.
+     * Default: true
+     */
+    allowCommonFiles?: boolean;
+    /**
+     * Include warnings in result for common files not in owns.
+     * Default: false
+     */
+    warnOnCommonFiles?: boolean;
+    /**
+     * Strict mode: disable all allowlists, only explicit owns allowed.
+     * Default: false
+     */
+    strict?: boolean;
+}
+export interface OwnershipCheckResult {
+    /** Files that violate ownership (will cause failure) */
+    violations: string[];
+    /** Files that are allowed but worth noting */
+    warnings: string[];
+    /** Files that passed ownership check */
+    allowed: string[];
+}
+/**
+ * Check whether all file operations fall within the stream's owns patterns.
+ *
+ * Security guarantees:
+ * - Path traversal is ALWAYS blocked (non-negotiable)
+ * - Absolute paths are ALWAYS blocked
+ * - Common files are only allowed in project root or owned directories
+ *
+ * @param operations - File operations to check
+ * @param owns - Ownership patterns from stream definition
+ * @param options - Checking options
+ */
+export declare function checkOwnership(operations: FileOperation[], owns: string[], options?: OwnershipCheckOptions): OwnershipCheckResult;
+/**
+ * Legacy function signature for backward compatibility.
+ * Returns only violations array (old behavior).
+ */
+export declare function checkOwnershipLegacy(operations: FileOperation[], owns: string[]): string[];

package/dist/ownership.js

@@ -0,0 +1,250 @@
+import * as path from 'path';
+// ============================================================================
+// Common Allowed Files
+// ============================================================================
+/**
+ * Root-level files that are commonly created by scaffolds and are safe to allow.
+ * These are security-vetted and don't pose path traversal risks.
+ */
+const COMMON_ALLOWED_FILES = new Set([
+    // Git
+    '.gitignore',
+    '.gitattributes',
+    '.gitkeep',
+    // Environment templates (never actual secrets)
+    '.env.example',
+    '.env.local.example',
+    '.env.development.example',
+    '.env.production.example',
+    '.env.test.example',
+    // Code formatting
+    '.prettierrc',
+    '.prettierrc.json',
+    '.prettierrc.js',
+    '.prettierrc.cjs',
+    '.prettierrc.mjs',
+    '.prettierrc.yaml',
+    '.prettierrc.yml',
+    '.prettierignore',
+    // Linting
+    '.eslintrc',
+    '.eslintrc.json',
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.mjs',
+    '.eslintrc.yaml',
+    '.eslintrc.yml',
+    '.eslintignore',
+    // Editor
+    '.editorconfig',
+    // Docker
+    '.dockerignore',
+    // Node version managers
+    '.nvmrc',
+    '.node-version',
+    '.tool-versions',
+    // TypeScript/JavaScript config (if not explicitly owned)
+    'tsconfig.json',
+    'jsconfig.json',
+]);
+/**
+ * Regex patterns for files that are commonly created and safe to allow.
+ */
+const COMMON_ALLOWED_PATTERNS = [
+    // Documentation
+    /^README\.md$/i,
+    /^CHANGELOG\.md$/i,
+    /^LICENSE(\.md|\.txt)?$/i,
+    /^CONTRIBUTING\.md$/i,
+    /^CODE_OF_CONDUCT\.md$/i,
+    /^SECURITY\.md$/i,
+    // GitHub
+    /^\.github\/.+/,
+    // VS Code
+    /^\.vscode\/.+/,
+];
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * Check whether all file operations fall within the stream's owns patterns.
+ *
+ * Security guarantees:
+ * - Path traversal is ALWAYS blocked (non-negotiable)
+ * - Absolute paths are ALWAYS blocked
+ * - Common files are only allowed in project root or owned directories
+ *
+ * @param operations - File operations to check
+ * @param owns - Ownership patterns from stream definition
+ * @param options - Checking options
+ */
+export function checkOwnership(operations, owns, options = {}) {
+    const { allowCommonFiles = true, warnOnCommonFiles = false, strict = false, } = options;
+    // Empty owns = no restriction (backward compatible)
+    if (owns.length === 0) {
+        return {
+            violations: [],
+            warnings: [],
+            allowed: operations.map((o) => o.path),
+        };
+    }
+    const violations = [];
+    const warnings = [];
+    const allowed = [];
+    for (const op of operations) {
+        const checkResult = checkSingleOperation(op, owns, {
+            allowCommonFiles: !strict && allowCommonFiles,
+        });
+        if (checkResult.violation) {
+            violations.push(checkResult.violation);
+        }
+        else {
+            allowed.push(op.path);
+            if (checkResult.warning && warnOnCommonFiles) {
+                warnings.push(checkResult.warning);
+            }
+        }
+    }
+    return { violations, warnings, allowed };
+}
+function checkSingleOperation(op, owns, options) {
+    const filePath = op.path;
+    // SECURITY: Block path traversal (non-negotiable, checked first)
+    if (filePath.includes('..')) {
+        return {
+            violation: `SECURITY: Path traversal blocked in '${filePath}'`,
+        };
+    }
+    // SECURITY: Block absolute paths
+    if (path.isAbsolute(filePath)) {
+        return {
+            violation: `SECURITY: Absolute path blocked: '${filePath}'`,
+        };
+    }
+    // SECURITY: Block hidden directories in parent paths (e.g., .ssh/config)
+    const parts = filePath.split('/');
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (part.startsWith('.') && !isAllowedHiddenDir(part)) {
+            return {
+                violation: `SECURITY: Hidden directory blocked: '${filePath}'`,
+            };
+        }
+    }
+    // Check explicit ownership
+    if (isExplicitlyOwned(filePath, owns)) {
+        return {};
+    }
+    // Check if it's a common allowed file
+    if (options.allowCommonFiles && isCommonAllowedFile(filePath, owns)) {
+        return {
+            warning: `Common file '${filePath}' created (not in owns list)`,
+        };
+    }
+    // Not allowed
+    return {
+        violation: `${op.type} on '${filePath}' is outside owned files`,
+    };
+}
+/**
+ * Check if a path is explicitly covered by an ownership pattern.
+ */
+function isExplicitlyOwned(filePath, owns) {
+    return owns.some((pattern) => {
+        // Directory pattern: "src/" matches "src/foo.ts"
+        if (pattern.endsWith('/')) {
+            return filePath.startsWith(pattern);
+        }
+        // Glob pattern: "src/*.ts" matches "src/foo.ts"
+        if (pattern.includes('*')) {
+            return matchGlobPattern(pattern, filePath);
+        }
+        // Exact match
+        return filePath === pattern;
+    });
+}
+/**
+ * Check if a file is a common allowed file.
+ * Only allows files in:
+ * - Project root (for root-level common files)
+ * - Inside already owned directories
+ */
+function isCommonAllowedFile(filePath, owns) {
+    const fileName = path.basename(filePath);
+    const dirName = path.dirname(filePath);
+    // Root-level common files
+    if (dirName === '.') {
+        if (COMMON_ALLOWED_FILES.has(fileName)) {
+            return true;
+        }
+        for (const pattern of COMMON_ALLOWED_PATTERNS) {
+            if (pattern.test(filePath)) {
+                return true;
+            }
+        }
+    }
+    // Pattern-matched files (like .github/workflows/ci.yml)
+    for (const pattern of COMMON_ALLOWED_PATTERNS) {
+        if (pattern.test(filePath)) {
+            return true;
+        }
+    }
+    // .gitkeep inside owned directories
+    if (fileName === '.gitkeep') {
+        const isInOwnedDir = owns.some((pattern) => {
+            if (pattern.endsWith('/')) {
+                return filePath.startsWith(pattern);
+            }
+            return false;
+        });
+        if (isInOwnedDir) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Hidden directories that are allowed (dev tooling, not system files).
+ */
+function isAllowedHiddenDir(dirName) {
+    const allowed = new Set([
+        '.github',
+        '.vscode',
+        '.idea',
+        '.husky',
+        '.storybook',
+        '.next',
+        '.nuxt',
+        '.svelte-kit',
+        '.turbo',
+        '.vercel',
+        '.netlify',
+    ]);
+    return allowed.has(dirName);
+}
+/**
+ * Match a simple glob pattern against a file path.
+ * Supports: * (any chars except /), ** (any chars including /)
+ */
+function matchGlobPattern(pattern, filePath) {
+    // Escape regex special chars except * and **
+    let regexStr = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '<<<GLOBSTAR>>>')
+        .replace(/\*/g, '[^/]*')
+        .replace(/<<<GLOBSTAR>>>/g, '.*');
+    return new RegExp(`^${regexStr}$`).test(filePath);
+}
+// ============================================================================
+// Legacy Compatibility
+// ============================================================================
+/**
+ * Legacy function signature for backward compatibility.
+ * Returns only violations array (old behavior).
+ */
+export function checkOwnershipLegacy(operations, owns) {
+    const result = checkOwnership(operations, owns, {
+        allowCommonFiles: false, // Old behavior: strict
+    });
+    return result.violations;
+}

package/dist/semaphore.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Promise-based semaphore for limiting concurrent async operations.
+ * Used by ClaudeExecutor to cap parallel API calls.
+ */
+export declare class Semaphore {
+    private readonly maxConcurrency;
+    private queue;
+    private running;
+    constructor(maxConcurrency: number);
+    acquire(): Promise<() => void>;
+    private release;
+}

package/dist/semaphore.js

@@ -0,0 +1,34 @@
+/**
+ * Promise-based semaphore for limiting concurrent async operations.
+ * Used by ClaudeExecutor to cap parallel API calls.
+ */
+export class Semaphore {
+    maxConcurrency;
+    queue = [];
+    running = 0;
+    constructor(maxConcurrency) {
+        this.maxConcurrency = maxConcurrency;
+        if (maxConcurrency < 1) {
+            throw new Error(`Semaphore concurrency must be >= 1, got ${maxConcurrency}`);
+        }
+    }
+    async acquire() {
+        if (this.running < this.maxConcurrency) {
+            this.running++;
+            return () => this.release();
+        }
+        return new Promise((resolve) => {
+            this.queue.push(() => {
+                this.running++;
+                resolve(() => this.release());
+            });
+        });
+    }
+    release() {
+        this.running--;
+        const next = this.queue.shift();
+        if (next) {
+            next();
+        }
+    }
+}

package/dist/telemetry/telemetry-types.d.ts

@@ -0,0 +1,85 @@
+import type { ErrorCategory } from '../intelligence/error-analyzer.js';
+import type { BudgetViolationType } from '../types.js';
+export interface TelemetryEvent {
+    id: string;
+    sessionHash: string;
+    eventType: 'orchestration_start' | 'orchestration_complete' | 'stream_complete' | 'stream_failed' | 'self_heal_triggered';
+    timestamp: string;
+    durationMs?: number;
+    streamCount?: number;
+    waveCount?: number;
+    parallelCount?: number;
+    success?: boolean;
+    errorCategory?: ErrorCategory;
+    retryCount?: number;
+    selfHealCount?: number;
+    complexityScore?: number;
+    tokensInput?: number;
+    tokensOutput?: number;
+    provider?: string;
+    model?: string;
+    tier?: string;
+    /** Estimated context tokens before execution */
+    contextTokensEstimated?: number;
+    /** Actual context tokens from API response */
+    contextTokensActual?: number;
+    /** Budget utilization ratio (0-1) */
+    contextBudgetUtilization?: number;
+    /** Whether budget limits were exceeded */
+    budgetViolationType?: BudgetViolationType;
+    /** Provider's context window limit for this model */
+    providerContextLimit?: number;
+    /** Whether cache was hit */
+    cacheHit?: boolean;
+    /** Tokens read from cache */
+    cacheReadTokens?: number;
+    /** Tokens written to cache */
+    cacheWriteTokens?: number;
+    /** Milliseconds saved by parallel execution */
+    timeSavedMs?: number;
+    /** Hypothetical sequential execution time in ms */
+    sequentialMs?: number;
+    /** Actual parallel execution time in ms */
+    parallelMs?: number;
+    /** Stream name for category-based analysis */
+    streamName?: string;
+}
+export interface TelemetryAggregate {
+    period: string;
+    orchestrationsTotal: number;
+    orchestrationsSuccess: number;
+    orchestrationsFailed: number;
+    streamsTotal: number;
+    streamsSuccess: number;
+    streamsFailed: number;
+    avgDurationMs?: number;
+    p50DurationMs?: number;
+    p95DurationMs?: number;
+    errorsByCategory: Record<ErrorCategory, number>;
+    selfHealTriggered: number;
+    selfHealSuccess: number;
+    tokensInputTotal: number;
+    tokensOutputTotal: number;
+    /** Average context budget utilization (0-1) */
+    avgContextUtilization?: number;
+    /** Count of soft limit violations */
+    softViolationCount: number;
+    /** Count of hard limit violations */
+    hardViolationCount: number;
+    /** Streams that failed due to context exceeded */
+    contextExceededFailures: number;
+    /** Cache hit rate (0-1) */
+    cacheHitRate?: number;
+    /** Total tokens read from cache */
+    cacheReadTokensTotal: number;
+    /** Total tokens written to cache */
+    cacheWriteTokensTotal: number;
+    /** Estimated cost savings from cache */
+    estimatedCacheSavings?: number;
+    /** Total milliseconds saved by parallel execution */
+    timeSavedMsTotal: number;
+    /** Total hypothetical sequential time in ms */
+    sequentialMsTotal: number;
+    /** Total actual parallel time in ms */
+    parallelMsTotal: number;
+}

package/dist/telemetry/telemetry-types.js

@@ -0,0 +1 @@
+export {};

package/dist/tier-gating.d.ts

@@ -0,0 +1,24 @@
+import type { Tier } from './tiers.js';
+import type { StreamDefinition } from './types.js';
+export interface TierLimitCheckOptions {
+    tier: Tier;
+    streams: Record<string, StreamDefinition>;
+    projectDir: string;
+    mode: 'cloud' | 'local';
+}
+export interface TierLimitResult {
+    allowed: boolean;
+    error?: string;
+    code?: string;
+    suggestion?: string;
+}
+/**
+ * Checks tier gating limits for orchestrations: wave count, providers, and more.
+ * Returns { allowed, error, code, suggestion }
+ */
+export declare function checkTierLimits(opts: TierLimitCheckOptions): TierLimitResult;
+/**
+ * Generate a user-facing warning if wave count approaches or exceeds tier limit.
+ * Returns null if within limits. Used by `learn` tool to warn early.
+ */
+export declare function getWaveCountWarning(waveCount: number, tier: Tier): string | null;

package/dist/tier-gating.js

@@ -0,0 +1,88 @@
+/**
+ * Checks tier gating limits for orchestrations: wave count, providers, and more.
+ * Returns { allowed, error, code, suggestion }
+ */
+export function checkTierLimits(opts) {
+    const { tier, streams } = opts;
+    // 1. Wave count restriction
+    const depLevels = getMaxDependencyDepth(streams);
+    if (tier.maxWaves !== -1 && depLevels > tier.maxWaves) {
+        return {
+            allowed: false,
+            error: `Too many dependency waves for tier '${tier.name}'. Max allowed: ${tier.maxWaves}, required: ${depLevels}. Upgrade to increase this limit.`,
+            code: 'MAX_WAVES_EXCEEDED',
+            suggestion: `Split up your orchestration to use fewer dependency layers, or upgrade to Pro/Team for increased depth.`,
+        };
+    }
+    // 2. Maximum parallel agents (total stream count)
+    if (tier.maxParallelAgents !== -1) {
+        const totalStreams = Object.keys(streams).length;
+        if (totalStreams > tier.maxParallelAgents) {
+            return {
+                allowed: false,
+                error: `Too many streams for tier '${tier.name}'. Max allowed: ${tier.maxParallelAgents}, requested: ${totalStreams}. Upgrade to increase this limit.`,
+                code: 'MAX_AGENTS_EXCEEDED',
+                suggestion: `Reduce the number of streams to ${tier.maxParallelAgents} or fewer, or upgrade your tier.`,
+            };
+        }
+    }
+    // 3. maxProviders: Count distinct providers across streams with explicit provider field
+    if (tier.maxProviders !== -1) {
+        const providers = new Set();
+        for (const s of Object.values(streams)) {
+            if (s.provider)
+                providers.add(s.provider);
+        }
+        if (providers.size > tier.maxProviders) {
+            return {
+                allowed: false,
+                error: `Too many LLM providers for tier '${tier.name}'. Max allowed: ${tier.maxProviders}, requested: ${providers.size}. Upgrade to increase this limit.`,
+                code: 'MAX_PROVIDERS_EXCEEDED',
+                suggestion: `Reduce the number of distinct providers to ${tier.maxProviders} or fewer, or upgrade your tier.`,
+            };
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Generate a user-facing warning if wave count approaches or exceeds tier limit.
+ * Returns null if within limits. Used by `learn` tool to warn early.
+ */
+export function getWaveCountWarning(waveCount, tier) {
+    if (tier.maxWaves === -1)
+        return null;
+    if (waveCount > tier.maxWaves) {
+        return `This plan requires ${waveCount} waves but your ${tier.name} tier allows max ${tier.maxWaves}. Reduce dependency depth or upgrade your tier.`;
+    }
+    if (waveCount >= Math.ceil(tier.maxWaves * 0.8)) {
+        return `This plan requires ${waveCount} waves, approaching your ${tier.name} tier limit of ${tier.maxWaves}.`;
+    }
+    return null;
+}
+// Utility: Returns maximum depth of dependencies (waves)
+function getMaxDependencyDepth(streams) {
+    // For each stream, compute its max dependency chain length (DAG longest path)
+    const memo = {};
+    function dfs(id, visited) {
+        if (memo[id] !== undefined)
+            return memo[id];
+        if (visited.has(id))
+            return 0; // break cycles
+        visited.add(id);
+        const deps = streams[id]?.deps ?? [];
+        let max = 0;
+        for (const dep of deps) {
+            if (!streams[dep])
+                continue;
+            max = Math.max(max, dfs(dep, visited));
+        }
+        visited.delete(id);
+        memo[id] = max + 1;
+        return memo[id];
+    }
+    let result = 0;
+    for (const id of Object.keys(streams)) {
+        result = Math.max(result, dfs(id, new Set()));
+    }
+    return result;
+}

package/dist/tiers.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+export declare const TierIdSchema: z.ZodEnum<["free", "pro", "team", "enterprise"]>;
+export type TierId = z.infer<typeof TierIdSchema>;
+export declare const TierSchema: z.ZodObject<{
+    id: z.ZodEnum<["free", "pro", "team", "enterprise"]>;
+    name: z.ZodString;
+    price: z.ZodNumber;
+    cloudOrchestrations: z.ZodNumber;
+    maxParallelAgents: z.ZodNumber;
+    selfHealing: z.ZodEnum<["none", "full"]>;
+    smartPlanning: z.ZodEnum<["none", "full"]>;
+    teamMembers: z.ZodNumber;
+    /** Maximum # of dependency waves (-1 = unlimited) */
+    maxWaves: z.ZodNumber;
+    /** Maximum # of distinct LLM providers per orchestration (-1 = unlimited) */
+    maxProviders: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: "free" | "pro" | "team" | "enterprise";
+    price: number;
+    cloudOrchestrations: number;
+    maxParallelAgents: number;
+    selfHealing: "none" | "full";
+    smartPlanning: "none" | "full";
+    teamMembers: number;
+    maxWaves: number;
+    maxProviders: number;
+}, {
+    name: string;
+    id: "free" | "pro" | "team" | "enterprise";
+    price: number;
+    cloudOrchestrations: number;
+    maxParallelAgents: number;
+    selfHealing: "none" | "full";
+    smartPlanning: "none" | "full";
+    teamMembers: number;
+    maxWaves: number;
+    maxProviders: number;
+}>;
+export type Tier = z.infer<typeof TierSchema>;
+export declare const TIERS: {
+    readonly free: {
+        readonly id: "free";
+        readonly name: "Free";
+        readonly price: 0;
+        readonly cloudOrchestrations: 0;
+        readonly maxParallelAgents: 5;
+        readonly selfHealing: "none";
+        readonly smartPlanning: "none";
+        readonly teamMembers: 1;
+        readonly maxWaves: 2;
+        readonly maxProviders: 1;
+    };
+    readonly pro: {
+        readonly id: "pro";
+        readonly name: "Pro";
+        readonly price: 19;
+        readonly cloudOrchestrations: 100;
+        readonly maxParallelAgents: 15;
+        readonly selfHealing: "full";
+        readonly smartPlanning: "full";
+        readonly teamMembers: 1;
+        readonly maxWaves: 10;
+        readonly maxProviders: 2;
+    };
+    readonly team: {
+        readonly id: "team";
+        readonly name: "Team";
+        readonly price: 49;
+        readonly cloudOrchestrations: 500;
+        readonly maxParallelAgents: 25;
+        readonly selfHealing: "full";
+        readonly smartPlanning: "full";
+        readonly teamMembers: -1;
+        readonly maxWaves: 25;
+        readonly maxProviders: 3;
+    };
+    readonly enterprise: {
+        readonly id: "enterprise";
+        readonly name: "Enterprise";
+        readonly price: -1;
+        readonly cloudOrchestrations: -1;
+        readonly maxParallelAgents: 50;
+        readonly selfHealing: "full";
+        readonly smartPlanning: "full";
+        readonly teamMembers: -1;
+        readonly maxWaves: -1;
+        readonly maxProviders: -1;
+    };
+};
+export declare function getTier(id: TierId): Tier;
+export declare function isCloudTier(id: TierId): boolean;