@wundam/orchex 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,65 @@
+Business Source License 1.1
+
+Licensor: Wundam LLC
+Licensed Work: orchex
+Additional Use Grant: You may use the Licensed Work for any purpose,
+  including production use, EXCEPT hosting, offering, or making available
+  the Licensed Work (or any substantial portion thereof) as a commercial
+  service that provides orchestration, parallel agent execution, or
+  substantially similar functionality (whether as a standalone product,
+  embedded in another product, or as part of a managed service platform).
+Change Date: 2030-01-29
+Change License: Apache License, Version 2.0
+
+Notice
+
+The Business Source License (this document, or the "License") is not an
+Open Source license. However, the Licensed Work will eventually be made
+available under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights
+Reserved. "Business Source License" is a trademark of MariaDB Corporation
+Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create
+derivative works, redistribute, and make non-production use of the
+Licensed Work. The Licensor may make an Additional Use Grant, above,
+permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first
+publicly available distribution of a specific version of the Licensed
+Work under this License, whichever comes first, the Licensor hereby
+grants you rights under the terms of the Change License, and the rights
+granted in the paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or
+authorized resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative
+works of the Licensed Work, are subject to this License. This License
+applies separately for each version of the Licensed Work and the Change
+Date may vary for each version of the Licensed Work released by
+Licensor.
+
+You must conspicuously display this License on each original or modified
+copy of the Licensed Work. If you receive the Licensed Work in original
+or modified form from a third party, the terms and conditions set forth
+in this License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will
+automatically terminate your rights under this License for the current
+and all other versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or
+logo of Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS
+PROVIDED ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES
+AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION)
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+NON-INFRINGEMENT, AND TITLE.

package/README.md

@@ -0,0 +1,332 @@
+# orchex
+
+**Turn a plan into parallel AI agents that can't break each other's code.**
+
+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.
+
+## Why Orchex
+
+Your AI assistant does tasks one at a time. Orchex makes it do 10 at once — safely.
+
+- **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** — 10 error categories with targeted fix streams. Not blind retry — categorized analysis with augmented instructions.
+- **Multi-LLM** — OpenAI, Gemini, Claude, DeepSeek, Ollama. Route different orchestrations to different providers — use DeepSeek ($0.001/1K) for docs, Claude ($0.015/1K) for core logic.
+- **BYOK** — Bring your own API key from any supported provider. You control costs.
+- **Context Budget Intelligence** — Provider-aware limits with soft/hard enforcement and adaptive learning per stream category.
+- **Team Collaboration** — Organization members see each other's orchestration runs. Shared dashboard with org switcher and access controls.
+- **Observability** — Real-time stats: speedup multiplier, success rate, self-heal recoveries, time saved. Per-user dashboard with 30-day rolling metrics.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) >= 18
+- LLM API key (one of the following):
+  - `ANTHROPIC_API_KEY` for Anthropic Claude
+  - `OPENAI_API_KEY` for OpenAI (GPT-4, GPT-4.1)
+  - `GEMINI_API_KEY` for Google Gemini
+  - `DEEPSEEK_API_KEY` for DeepSeek (V3, Coder, Reasoner)
+  - Or configure Ollama for local models
+
+## Install
+
+```bash
+npm install -g @wundam/orchex
+```
+
+Or use directly:
+
+```bash
+npx @wundam/orchex
+```
+
+## MCP Configuration
+
+Add to your MCP config (e.g. project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "orchex": {
+      "command": "npx",
+      "args": ["@wundam/orchex"]
+    }
+  }
+}
+```
+
+## Usage
+
+### 1. Initialize an orchestration
+
+```
+orchex.init({
+  feature: "user-authentication",
+  streams: {
+    types: {
+      name: "Define types",
+      deps: [],
+      owns: ["src/types.ts"],
+      reads: ["src/config.ts"],
+      plan: "Define TypeScript interfaces for auth",
+      setup: ["npm install"],
+      verify: ["npm test"]
+    },
+    api: {
+      name: "Build API",
+      deps: ["types"],
+      owns: ["src/api.ts"],
+      reads: ["src/types.ts"]
+    },
+    tests: {
+      name: "Write tests",
+      deps: ["types", "api"],
+      owns: ["tests/"],
+      verify: ["npm test"]
+    }
+  }
+})
+```
+
+### 2. Execute
+
+```
+orchex.execute({ mode: "auto" })
+```
+
+Calculates waves from dependencies (topological sort), then for each wave:
+1. Runs **setup** commands for each stream
+2. Builds a **4-layer context prompt** (project, stream files, dependency artifacts, instructions)
+3. Calls the **LLM API** in parallel (one call per stream in the wave)
+4. Parses and **validates artifacts** from responses
+5. **Applies** file operations to the codebase
+6. Runs **verify** commands
+
+Wave plan for the example above:
+- **Wave 1:** `types` (no deps)
+- **Wave 2:** `api` (depends on types)
+- **Wave 3:** `tests` (depends on types + api)
+
+Modes:
+- `wave` (default) — execute one wave and return. Call repeatedly to step through.
+- `auto` — execute all waves sequentially until done.
+- `dry_run: true` — generate prompts without calling the LLM API.
+
+### 3. Check status
+
+```
+orchex.status()
+```
+
+### 4. Complete
+
+```
+orchex.complete({ archive: true })
+```
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `init` | Initialize orchestration with feature name and streams |
+| `add_stream` | Add a stream to the active orchestration |
+| `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) |
+
+## Architecture
+
+```
+orchex.execute()
+  │
+  For each wave (parallel streams within wave):
+  │
+  ├── 1. Resolve   — load manifest, calculate waves, find target
+  ├── 2. Setup     — run pre-execution commands
+  ├── 3. Context   — build 4-layer prompt
+  │     ├── Project context (file tree, deps, config)
+  │     ├── Stream context (owned + read-only file contents)
+  │     ├── Dependency context (completed artifact summaries)
+  │     └── Instructions (artifact format, ownership rules)
+  ├── 4. Execute   — call LLM API in parallel (Claude/OpenAI/Gemini/DeepSeek/Ollama)
+  ├── 5. Validate  — parse orchex-artifact from response
+  ├── 6. Apply     — write files to codebase (with ownership enforcement)
+  └── 7. Verify    — run post-execution commands
+```
+
+Streams can only modify files listed in their `owns` array. A file-based lock prevents concurrent `execute` calls.
+
+## Stream Definition
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Human-readable stream name |
+| `deps` | `string[]` | Stream IDs this depends on (determines wave order) |
+| `owns` | `string[]` | Files this stream can create/modify (ownership enforcement) |
+| `reads` | `string[]` | Files this stream needs to read (included in context, not writable) |
+| `plan` | `string` | Implementation instructions for the agent |
+| `setup` | `string[]` | Shell commands to run before execution |
+| `verify` | `string[]` | Shell commands to run after execution |
+| `timeoutMs` | `number` | Per-stream timeout override in milliseconds (optional) |
+
+## Stream Slicing Best Practices
+
+**One stream = one atomic deliverable.** If your stream description uses "and" between distinct concepts, split it.
+
+| Pattern | Success | Why |
+|---------|---------|-----|
+| `docs-installation` (one installation guide) | ✅ | Single focused topic |
+| `integration-claude-code` (one integration guide) | ✅ | Predictable structure |
+| `unified-layout` (implementation + tests) | ✅ | Code + tests are one unit |
+| `docs-structure` (5 different docs) | ❌ | Multiple distinct outputs |
+| `tutorials-first` (setup + walkthrough + summary) | ❌ | Multiple conceptual sections |
+
+**Slicing heuristics:**
+- **`owns` > 4 distinct files** → Split (each file requiring different content should be separate)
+- **`reads` > 4 files** → Split (high synthesis complexity = timeout risk)
+- **Expected output > 6,000 tokens** → Split
+- **Tutorials** → Section into intro/walkthrough/conclusion streams
+- **Code implementation + its tests** → Keep together (they must match)
+- **Templated repetition** → Can bundle (structurally identical outputs)
+
+## Context Budget Intelligence
+
+Orchex Learn tracks context budget usage and adapts thresholds based on execution history.
+
+### Provider-Aware Limits
+
+| Provider | Context Limit | Default Soft | Default Hard |
+|----------|---------------|--------------|--------------|
+| Anthropic | 200,000 | 140,000 | 180,000 |
+| OpenAI | 128,000 | 89,600 | 115,200 |
+| Gemini | 1,000,000 | 700,000 | 900,000 |
+| DeepSeek | 128,000 | 89,600 | 115,200 |
+| Ollama | 128,000 | 89,600 | 115,200 |
+
+### Budget Warnings
+
+When a stream's estimated context exceeds limits, warnings appear in execution output:
+
+```json
+{
+  "event": "budget_warning",
+  "streamId": "large-docs",
+  "violationType": "soft",
+  "estimatedTokens": 156000,
+  "budgetLimit": 140000
+}
+```
+
+### Adaptive Learning
+
+Thresholds improve as execution history accumulates:
+- **Per-category limits** — Code streams vs. documentation vs. tutorials
+- **Confidence levels** — Low (0-49 samples) → Medium (50-99) → High (100+)
+- **Persisted learning** — Saved in `.orchex/learn/thresholds.json`
+
+### Stream Category Recommendations
+
+| Category | Max Owns | Max Reads | Notes |
+|----------|----------|-----------|-------|
+| code | 4 | 4 | Implementation files |
+| docs | 6 | 3 | Documentation pages |
+| tutorial | 3 | 4 | Sectioned tutorials |
+| test | 4 | 5 | Test files with fixtures |
+| migration | 3 | 4 | Schema migrations |
+
+## Stream Validation
+
+Orchex validates stream definitions during `init` and `add_stream`, detecting anti-patterns and suggesting improvements.
+
+### Quality Analysis
+
+```json
+{
+  "qualityAnalysis": {
+    "overallScore": 85,
+    "issues": { "errors": 0, "warnings": 2, "info": 1 },
+    "problematicStreams": ["large-docs"],
+    "splitSuggestions": [{
+      "streamId": "large-docs",
+      "templateName": "Documentation Set",
+      "suggestedStreams": ["docs-overview", "docs-installation", "docs-quickstart"]
+    }]
+  }
+}
+```
+
+### Anti-Patterns Detected
+
+| Pattern | Severity | Description |
+|---------|----------|-------------|
+| High owns count | warning | Stream owns >4 files across multiple directories |
+| High reads count | warning | Stream reads >4 files (synthesis complexity) |
+| Compound plan | warning | Plan contains multiple "and" conjunctions |
+| Empty plan | error | Stream has no plan description |
+| No verification | info | Stream has no verify commands |
+
+### Template-Based Split Suggestions
+
+When anti-patterns are detected, Orchex suggests splits based on known templates:
+- **Documentation Set** — Split into overview, installation, quickstart, etc.
+- **Code Feature** — Split into types, core, tests, docs
+- **Migration** — Split into new implementation, migrate components, deprecate old
+- **Tutorial** — Split into intro, steps, conclusion
+- **API Reference** — Split by module
+
+### Automatic Splitting in `learn`
+
+When `orchex learn` parses a markdown plan, it automatically splits deliverables with mixed concerns into focused sub-streams following `types → migrations → core → tests → docs` ordering. Each sub-stream gets relevant plan content and files for its concern. Dependencies chain sequentially: the first sub-stream inherits the parent's deps, and each subsequent sub-stream depends on the previous one. Cross-deliverable dependencies resolve to the `-core` sibling (the implementation stream) rather than scaffolding streams like `-types` or `-migrations`. Plan authors can use `- Read:` / `- Import:` markers alongside `- Create:` / `- Modify:` to declare read-only file dependencies.
+
+### Learn Pipeline Intelligence
+
+The `learn` pipeline includes several quality improvements:
+
+- **Import-based reads inference** — Parses `import`/`require()` from code blocks in plan documents and auto-adds referenced files to `reads`. Resolves relative imports when filename context is available.
+- **Path validation** — Validates `owns`/`reads` paths against the filesystem when `projectDir` is available. Auto-corrects unambiguous mismatches (e.g., `tools.ts` → `src/tools.ts`) with visible warnings.
+- **Cycle auto-resolution** — When two streams mutually read each other's owned files (context reads, not sequencing requirements), the false dependency cycle is automatically resolved. N-node file-ownership-only cycles are broken by removing the weakest edge. Cycles involving explicit or content-pattern dependencies are preserved and reported as errors.
+- **Structured description extraction** — Complex sections (>3000 chars, >=3 children) get numbered task lists instead of truncated prose, ensuring all sub-sections are visible to the LLM.
+- **Complexity warnings** — Flags deliverables with many sub-sections, suggesting YAML definitions or `deliverable_level: 3` for manual decomposition.
+
+## Development
+
+```bash
+npm install
+npm run build    # TypeScript compilation
+npm test         # Run tests
+npm run dev      # Run with tsx (development)
+```
+
+For local development, point `.mcp.json` to your local build:
+
+```json
+{
+  "mcpServers": {
+    "orchex": {
+      "command": "node",
+      "args": ["./bin/orchex.js"],
+      "cwd": "/path/to/orchex"
+    }
+  }
+}
+```
+
+## Pricing
+
+| Tier | Price | What you get |
+|---|---|---|
+| **Local** | Free | Core MCP tools: 5 streams, 2 waves, single provider, BYOK. |
+| **Cloud Trial** | $0 ($5 credit) | Full cloud features. 30-day credit, no credit card required. |
+| **Pro** | $19/mo | 100 cloud runs/mo, 15 agents, 10 waves, 2 providers, `orchex learn`, full self-healing. |
+| **Team** | $49/user/mo | 500 cloud runs/mo, 25 agents, 25 waves, 3 providers, shared orchestrations, team management. |
+| **Enterprise** | Custom | Unlimited runs + waves, 50+ agents, all providers, self-hosted, SLA + dedicated support. |
+
+1 run = 1 orchestration. BYOK on all plans — you pay your own LLM API costs.
+
+## License
+
+[BSL 1.1](LICENSE) — free to use for any purpose except hosting as a competing commercial orchestration service. Converts to Apache 2.0 on 2030-01-29.

package/bin/orchex.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/artifacts.d.ts

@@ -0,0 +1,132 @@
+import { type StreamArtifact, type FileOperation } from './types.js';
+import { type OwnershipCheckOptions, type OwnershipCheckResult } from './ownership.js';
+/**
+ * Read and validate a stream's artifact JSON file.
+ * Returns null if artifact doesn't exist.
+ */
+export declare function readArtifact(projectDir: string, streamId: string): Promise<StreamArtifact | null>;
+export interface SanityCheckResult {
+    passed: boolean;
+    violations: string[];
+    warnings: string[];
+}
+/**
+ * Validate artifact for degenerate outputs that are structurally valid
+ * but semantically broken (LLM repetition loops, truncation artifacts, etc.).
+ */
+export declare function validateArtifactSanity(artifact: StreamArtifact): SanityCheckResult;
+export interface ExtractionDiagnostic {
+    strategy: 'exact' | 'relaxed' | 'fence_recovery' | 'failed';
+    jsonRepaired: boolean;
+    rawLength: number;
+    error?: string;
+}
+export interface ExtractionResult {
+    artifact: StreamArtifact | null;
+    diagnostic: ExtractionDiagnostic;
+}
+/**
+ * Extract artifact JSON from an agent's response text with full diagnostics.
+ * Tries cascading strategies: exact → fence recovery.
+ */
+export declare function extractArtifactWithDiagnostics(agentOutput: string): ExtractionResult;
+/**
+ * Extract artifact JSON from an agent's response text.
+ * Backward-compatible wrapper — returns StreamArtifact | null.
+ */
+export declare function extractArtifact(agentOutput: string): StreamArtifact | null;
+/**
+ * Write an artifact JSON file for a stream.
+ * Used by the host session to save agent output.
+ */
+export declare function writeArtifact(projectDir: string, streamId: string, artifact: StreamArtifact): Promise<string>;
+export interface ApplyResult {
+    success: boolean;
+    streamId: string;
+    appliedOps: number;
+    error?: string;
+    errors?: string[];
+    /** Warnings about files that were allowed but notable (e.g., common files) */
+    warnings?: string[];
+}
+/**
+ * Check whether all file operations fall within the stream's owns patterns.
+ *
+ * Enhanced behavior (v3.1+):
+ * - Common project files (.gitignore, README.md, etc.) are allowed by default
+ * - Glob patterns supported in owns list
+ * - Security: path traversal and absolute paths always blocked
+ *
+ * @param operations - File operations to validate
+ * @param owns - Ownership patterns from stream definition
+ * @param options - Optional settings to control strictness
+ * @returns Array of violation messages (empty = all allowed)
+ */
+export declare function checkOwnership(operations: FileOperation[], owns: string[], options?: OwnershipCheckOptions): string[];
+/**
+ * Enhanced ownership check with detailed results.
+ * Returns violations, warnings, and allowed files separately.
+ */
+export declare function checkOwnershipDetailed(operations: FileOperation[], owns: string[], options?: OwnershipCheckOptions): OwnershipCheckResult;
+/**
+ * Apply a stream's artifact to the project codebase.
+ * Creates a backup before applying. Rolls back on error.
+ */
+export declare function applyArtifact(projectDir: string, streamId: string, options?: {
+    dryRun?: boolean;
+    force?: boolean;
+}): Promise<ApplyResult>;
+/**
+ * Apply all artifacts for a set of stream IDs.
+ */
+export declare function applyWaveArtifacts(projectDir: string, streamIds: string[], options?: {
+    dryRun?: boolean;
+    force?: boolean;
+}): Promise<{
+    applied: string[];
+    failed: string[];
+    results: ApplyResult[];
+}>;
+/**
+ * Fuzzy edit replacement: tries line-by-line matching after trimming
+ * trailing whitespace from each line. Handles the most common LLM
+ * deviations: trailing spaces, \r\n vs \n, trailing blank lines.
+ *
+ * Returns the replaced content or null if no match found.
+ */
+export declare function fuzzyReplace(content: string, oldContent: string, newContent: string): string | null;
+interface BackupEntry {
+    path: string;
+    content: string;
+}
+export interface StreamBackup {
+    streamId: string;
+    entries: BackupEntry[];
+    createdFiles: string[];
+}
+/**
+ * Create backup of files that will be modified by operations.
+ * Public API — used by orchestrator for verify isolation.
+ */
+export declare function createStreamBackup(projectDir: string, streamId: string, operations: FileOperation[]): Promise<StreamBackup>;
+/**
+ * Revert a stream's changes using its backup.
+ * Restores modified files and removes created files.
+ */
+export declare function revertStreamBackup(projectDir: string, backup: StreamBackup): Promise<void>;
+/**
+ * Restore a stream's changes from its "modified state" backup.
+ * Used to re-apply changes after a temporary revert during verify isolation.
+ */
+export declare function restoreStreamBackup(projectDir: string, backup: StreamBackup): Promise<void>;
+/**
+ * Isolate which stream(s) caused a verify failure by temporarily
+ * reverting each stream's changes and re-running its verify commands.
+ *
+ * Returns a map of streamId → verdict:
+ * - 'guilty': reverting this stream made verify pass
+ * - 'innocent': reverting this stream didn't fix verify
+ * - 'unknown': couldn't determine (interaction between streams)
+ */
+export declare function isolateVerifyFailure(projectDir: string, backups: StreamBackup[], failedVerifyMap: Map<string, string[]>): Promise<Map<string, 'guilty' | 'innocent' | 'unknown'>>;
+export {};