@wundam/orchex 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/mcp-instructions.d.ts

@@ -0,0 +1 @@
+export declare const ORCHEX_INSTRUCTIONS = "Orchex is a multi-LLM orchestration tool that coordinates parallel AI agents to implement features across multiple files with zero merge conflicts.\n\n## Core Concepts\n\n\u2022 **Streams**: File ownership units \u2014 each stream owns 1-3 files exclusively\n\u2022 **Waves**: Parallel execution groups \u2014 streams in same wave run simultaneously  \n\u2022 **Ownership**: Strict isolation \u2014 no two streams can modify the same file\n\u2022 **Self-Healing**: Auto-recovery from failures (max 3 attempts per stream)\n\u2022 **Learning**: System improves with every run, adapting to your codebase\n\u2022 **Model Registry**: Dynamic model discovery \u2014 available models auto-updated from providers daily\n\n## How to Start\n\nAlways use `auto`. It handles everything:\n- Short intent: \"Add user auth with JWT\"\n- Full PRD or spec document: paste the content as the intent\n- Bug report: \"Fix the login timeout on mobile\"\n- Refactoring request: \"Extract payment logic into service layer\"\n\nDo NOT use `learn` directly \u2014 it expects a structured implementation plan with code deliverables, not a PRD or spec.\nDo NOT parse user documents into sections yourself \u2014 `auto` does this automatically.\n\n## Available Tools\n\n### Getting Started:\n\u2022 `auto` \u2014 **Start here.** Takes any input (intent, PRD, spec, bug report) \u2192 generates implementation plan \u2192 previews \u2192 executes.\n\u2022 `init-plan` \u2014 Generate plan template for manual editing (advanced \u2014 use `auto` for most cases)\n\u2022 `init` + `add_stream` \u2014 Manual stream-by-stream control (advanced)\n\n### During Execution:\n\u2022 `status` \u2014 Check current state and progress\n\u2022 `execute` \u2014 Run all pending streams\n\u2022 `recover` \u2014 Auto-heal failed streams\n\u2022 `rollback-stream` \u2014 Undo changes from a specific stream\n\u2022 `reload` \u2014 Refresh state from disk\n\n### After Execution:\n\u2022 `complete` \u2014 Mark orchestration as done and cleanup\n\u2022 `reset-learning` \u2014 Clear learned patterns\n\n### Internal (rarely called directly):\n\u2022 `learn` \u2014 Parse a structured implementation plan into stream definitions. Prefer `auto`.\n\n## Error Recovery\n\nIf execute fails, call status to check stream states, then recover to self-heal failed streams automatically.\n\n## Available Resources\n\n\u2022 orchex://quickstart \u2014 Getting started guide and setup\n\u2022 orchex://concepts/streams \u2014 Stream ownership model\n\u2022 orchex://concepts/waves \u2014 Parallel execution system\n\u2022 orchex://concepts/ownership \u2014 File isolation rules\n\u2022 orchex://concepts/self-healing \u2014 Auto-recovery mechanics\n\u2022 orchex://concepts/providers \u2014 LLM provider configuration\n\u2022 orchex://examples \u2014 Real-world orchestration examples\n\u2022 orchex://api-reference \u2014 Stream definition schema\n\n## API Keys\n\nANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (for Bedrock)\n\n## Supported Providers\n\nClaude (Anthropic), OpenAI, Gemini, DeepSeek, Ollama (local), AWS Bedrock \u2014 models auto-discovered via registry\n\n**Note:** Cloud mode (`mode: \"cloud\"`) currently uses Anthropic as the execution provider. All 6 providers are available in local mode.\n\n## Cloud Trial\n\nGet 10 free cloud runs (no expiry, no credit card required) \u2014 run `npx @wundam/orchex login`\n\n## Tiers\n\n\u2022 **Free**: 5 streams, 2 waves, all 6 providers (BYOK)\n\u2022 **Pro** ($19/mo): 15 streams, 10 waves\n\u2022 **Team** ($49/user/mo): 25 streams, 25 waves";

package/dist/mcp-instructions.js

@@ -0,0 +1,84 @@
+export const ORCHEX_INSTRUCTIONS = `\
+Orchex is a multi-LLM orchestration tool that coordinates parallel AI agents to \
+implement features across multiple files with zero merge conflicts.
+
+## Core Concepts
+
+• **Streams**: File ownership units — each stream owns 1-3 files exclusively
+• **Waves**: Parallel execution groups — streams in same wave run simultaneously  
+• **Ownership**: Strict isolation — no two streams can modify the same file
+• **Self-Healing**: Auto-recovery from failures (max 3 attempts per stream)
+• **Learning**: System improves with every run, adapting to your codebase
+• **Model Registry**: Dynamic model discovery — available models auto-updated from providers daily
+
+## How to Start
+
+Always use \`auto\`. It handles everything:
+- Short intent: "Add user auth with JWT"
+- Full PRD or spec document: paste the content as the intent
+- Bug report: "Fix the login timeout on mobile"
+- Refactoring request: "Extract payment logic into service layer"
+
+Do NOT use \`learn\` directly — it expects a structured implementation plan with code deliverables, not a PRD or spec.
+Do NOT parse user documents into sections yourself — \`auto\` does this automatically.
+
+## Available Tools
+
+### Getting Started:
+• \`auto\` — **Start here.** Takes any input (intent, PRD, spec, bug report) → generates implementation plan → previews → executes.
+• \`init-plan\` — Generate plan template for manual editing (advanced — use \`auto\` for most cases)
+• \`init\` + \`add_stream\` — Manual stream-by-stream control (advanced)
+
+### During Execution:
+• \`status\` — Check current state and progress
+• \`execute\` — Run all pending streams
+• \`recover\` — Auto-heal failed streams
+• \`rollback-stream\` — Undo changes from a specific stream
+• \`reload\` — Refresh state from disk
+
+### After Execution:
+• \`complete\` — Mark orchestration as done and cleanup
+• \`reset-learning\` — Clear learned patterns
+
+### Internal (rarely called directly):
+• \`learn\` — Parse a structured implementation plan into stream definitions. Prefer \`auto\`.
+
+## Error Recovery
+
+If execute fails, call status to check stream states, then recover to self-heal \
+failed streams automatically.
+
+## Available Resources
+
+• orchex://quickstart — Getting started guide and setup
+• orchex://concepts/streams — Stream ownership model
+• orchex://concepts/waves — Parallel execution system
+• orchex://concepts/ownership — File isolation rules
+• orchex://concepts/self-healing — Auto-recovery mechanics
+• orchex://concepts/providers — LLM provider configuration
+• orchex://examples — Real-world orchestration examples
+• orchex://api-reference — Stream definition schema
+
+## API Keys
+
+ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, \
+AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (for Bedrock)
+
+## Supported Providers
+
+Claude (Anthropic), OpenAI, Gemini, DeepSeek, Ollama (local), AWS Bedrock — models auto-discovered via registry
+
+**Note:** Cloud mode (\`mode: "cloud"\`) currently uses Anthropic as the execution \
+provider. All 6 providers are available in local mode.
+
+## Cloud Trial
+
+Get 10 free cloud runs (no expiry, no credit card required) — run \
+\`npx @wundam/orchex login\`
+
+## Tiers
+
+• **Free**: 5 streams, 2 waves, all 6 providers (BYOK)
+• **Pro** ($19/mo): 15 streams, 10 waves
+• **Team** ($49/user/mo): 25 streams, 25 waves\
+`;

package/dist/mcp-resources.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface ResourceEntry {
+    name: string;
+    description: string;
+    content: string;
+}
+export declare const RESOURCE_REGISTRY: Record<string, ResourceEntry>;
+export declare function registerResources(server: McpServer): void;

package/dist/mcp-resources.js

@@ -0,0 +1,420 @@
+export const RESOURCE_REGISTRY = {
+    'orchex://quickstart': {
+        name: 'Getting Started',
+        description: 'Quick setup guide for Orchex MCP server',
+        content: `# Getting Started with Orchex
+
+## MCP Configuration
+
+Add Orchex to your IDE's MCP config (e.g. \`.cursor/mcp.json\` or Claude Desktop config):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "orchex": {
+      "command": "npx",
+      "args": ["-y", "@wundam/orchex@latest"]
+    }
+  }
+}
+\`\`\`
+
+Orchex inherits your shell environment automatically — no \`env\` block needed unless overriding specific values.
+
+## API Key Setup
+
+Set provider keys as environment variables in your shell profile (\`~/.zshrc\` or \`~/.bashrc\`):
+
+- \`ANTHROPIC_API_KEY\` — Claude (recommended default)
+- \`OPENAI_API_KEY\` — GPT-4o and variants
+- \`GEMINI_API_KEY\` — Google Gemini
+- \`DEEPSEEK_API_KEY\` — DeepSeek
+- AWS credentials — Bedrock
+
+Orchex auto-detects which providers are available from your environment.
+
+## First Run
+
+Use the \`auto\` tool to plan and execute in one shot:
+
+\`\`\`
+auto intent="Add a /health endpoint to the Express server" projectDir="/path/to/project"
+\`\`\`
+
+Orchex will generate a plan, show you a preview of proposed streams, and ask for confirmation before executing.
+
+## Cloud Trial
+
+Get 10 free cloud-managed runs with:
+
+\`\`\`
+orchex login
+\`\`\`
+
+This fetches an entitlement JWT that unlocks Pro-level limits (up to 10 streams, 10 waves, multiple providers) for your trial runs. No credit card required.
+
+## Key Tools
+
+- \`auto\` — full autopilot: intent → plan → execute
+- \`init\` + \`add_stream\` + \`execute\` — manual workflow for fine-grained control
+- \`status\` — check orchestration progress
+- \`complete\` — finalize and archive after execution
+`,
+    },
+    'orchex://concepts/streams': {
+        name: 'Streams',
+        description: 'Stream ownership model and file isolation',
+        content: `# Streams
+
+Streams are the atomic unit of work in Orchex. Each stream represents a focused, bounded task executed by a single LLM call.
+
+## Core Properties
+
+Every stream definition includes:
+
+- \`name\` — unique identifier (e.g. \`"auth-middleware"\`)
+- \`deps\` — stream IDs this stream depends on (must complete first)
+- \`owns\` — files this stream will create or modify (exclusive ownership)
+- \`reads\` — files needed for context but not modified
+- \`plan\` — YAML instructions passed directly to the executing LLM
+- \`setup\` — shell commands to run before execution (e.g. \`npm install\`)
+- \`verify\` — shell commands to validate output (e.g. \`npm test\`, \`tsc --noEmit\`)
+
+## Ownership Model
+
+Each file in \`owns\` belongs exclusively to one stream. No two streams may own the same file. This prevents merge conflicts when streams run in parallel. Ownership is validated at \`init\` time — conflicts cause an immediate error before any execution begins.
+
+## Parallel Execution
+
+Streams with no shared dependencies run simultaneously within a wave. Orchex automatically groups streams into waves based on the dependency graph. A stream in wave 2 can safely read files owned by wave 1 streams because wave 1 is complete before wave 2 starts.
+
+## Fix Streams
+
+When a stream fails, Orchex generates a fix stream automatically. The fix stream inherits the same \`owns\` list and receives the full error context — stderr, verification output, and file diffs — in its plan. Fix chains are capped at 3 attempts per stream.
+
+## Plan Quality
+
+The \`plan\` field is the LLM's entire instruction set. Markdown prose outside the YAML is not visible to the executing model. Be explicit: specify file paths, function signatures, import statements, and constraints like "do NOT use library X".
+`,
+    },
+    'orchex://concepts/waves': {
+        name: 'Waves',
+        description: 'Parallel execution and dependency management',
+        content: `# Waves
+
+Waves are groups of streams that execute simultaneously. Orchex automatically calculates wave assignments from the dependency graph — you declare dependencies, Orchex figures out parallelism.
+
+## How Wave Assignment Works
+
+1. Streams with no dependencies → wave 1
+2. Streams whose all dependencies are in wave 1 → wave 2
+3. Streams whose all dependencies are in waves 1–2 → wave 3
+4. And so on...
+
+A stream is placed in the earliest wave where all its dependencies have already been assigned.
+
+## Dependency Rules
+
+- \`deps\` references other stream IDs (names), not wave numbers
+- A stream can only depend on streams in earlier waves (no circular deps)
+- Orchex detects and rejects circular dependencies at \`init\` time
+- Cross-wave file access is safe: earlier waves are fully complete before later waves start
+
+## Execution Modes
+
+- \`execute mode=auto\` — runs all waves sequentially, one wave at a time
+- \`execute mode=wave\` — runs the next pending wave (useful for step-by-step control)
+- Within a wave, all streams launch in parallel
+
+## Wave-Level Circuit Breaker
+
+If every stream in a wave fails, Orchex halts execution immediately rather than running dependent waves that are guaranteed to fail. The circuit breaker state is visible in \`status\` output.
+
+## Practical Tips
+
+- Keep waves shallow (3–5 streams per wave) for predictable parallelism
+- Use \`reads\` on shared files rather than deps when you only need context
+- Streams that touch unrelated parts of the codebase can safely be in the same wave even if logically sequential
+`,
+    },
+    'orchex://concepts/ownership': {
+        name: 'Ownership',
+        description: 'File isolation rules preventing merge conflicts',
+        content: `# Ownership
+
+Orchex enforces strict file ownership to prevent parallel streams from corrupting each other's work.
+
+## owns vs reads
+
+- \`owns\` — files this stream will create or modify. Exclusive: no other stream may list these files in its \`owns\`.
+- \`reads\` — files needed for context. Non-exclusive: any number of streams can read the same file.
+
+A stream may freely read files it does not own. It must not write to files it does not own.
+
+## Ownership Validation
+
+At \`init\` time, Orchex validates the full ownership graph before any stream executes:
+
+- Duplicate \`owns\` entries across streams → init fails with a conflict error naming both streams
+- Files in \`reads\` that are also in \`owns\` of the same stream → allowed (owns implies read access)
+- Non-existent files in \`owns\` → allowed (stream may create them)
+
+## Path Rules
+
+- All paths in \`owns\` and \`reads\` must be relative to the project directory
+- Absolute paths are rejected
+- Paths must stay within the project directory — traversal (e.g. \`../../secrets\`) is blocked
+
+## Fix Stream Inheritance
+
+When a fix stream is auto-generated for a failed stream, it inherits the parent's \`owns\` list exactly. This ensures the fix can overwrite broken output without ownership conflicts.
+
+## Common Patterns
+
+- **New file creation**: list only in \`owns\`, no \`reads\` needed
+- **Editing shared config** (e.g. \`tsconfig.json\`): only one stream may own it; others use \`reads\`
+- **Barrel exports** (e.g. \`src/index.ts\`): assign ownership to a dedicated "exports" stream that runs last
+- **Test files**: typically co-located ownership — stream that owns \`auth.ts\` also owns \`auth.test.ts\`
+`,
+    },
+    'orchex://concepts/self-healing': {
+        name: 'Self-Healing',
+        description: 'Automatic error detection and recovery',
+        content: `# Self-Healing
+
+When a stream fails, Orchex automatically analyzes the error, generates a targeted fix stream, and retries — up to 3 attempts per chain.
+
+## Error Categories
+
+Orchex classifies errors into 10+ categories to decide whether to retry:
+
+**Retryable (code errors):**
+- Test failures — unit/integration tests report failures
+- Type errors — TypeScript compilation errors
+- Lint errors — ESLint/style violations
+- Syntax errors — unparseable output
+- Missing imports — module not found at runtime
+- Logic errors — incorrect behavior detected by verify commands
+
+**Not retryable (infrastructure errors):**
+- Model not found (404) — invalid model ID in config
+- Authentication failure — invalid or missing API key
+- Server errors (5xx) — provider outage
+- Rate limit exceeded — quota hit (surfaces as user-facing error)
+- Context length exceeded — plan too large for model
+
+## Fix Stream Generation
+
+On a retryable failure, Orchex:
+
+1. Captures the full error context: stderr, verify output, file diffs, and the original plan
+2. Generates a new stream with the error context injected into its plan
+3. Assigns the same \`owns\` list as the failed stream
+4. Queues it as the next stream to execute
+
+## Chain Limits
+
+Each fix stream is chained to its parent via \`parentStreamId\`. Orchex traverses the full chain to count attempts. At 3 attempts, the stream is marked permanently failed and execution continues with other streams (if possible).
+
+## Circuit Breaker
+
+If all streams in a wave fail with the same error type, the wave-level circuit breaker trips. Subsequent waves are skipped and the orchestration is marked failed. This prevents cascading failures when the root cause affects all streams (e.g. a broken dependency or missing env var).
+
+## selfHealable Flag
+
+Streams can opt out of self-healing by setting \`selfHealable: false\`. Infrastructure streams or one-shot migrations may use this to fail fast rather than retry.
+`,
+    },
+    'orchex://concepts/providers': {
+        name: 'Providers',
+        description: 'LLM provider configuration and API keys',
+        content: `# Providers
+
+Orchex supports 6 LLM providers. Keys are read from environment variables automatically.
+
+## Supported Providers
+
+| Provider | Env Var(s) | Fallback Model |
+|----------|-----------|---------------|
+| Anthropic (Claude) | \`ANTHROPIC_API_KEY\` | claude-sonnet-4-5-20250929 |
+| OpenAI | \`OPENAI_API_KEY\` | gpt-4.1 |
+| Google Gemini | \`GEMINI_API_KEY\` | gemini-2.0-flash |
+| DeepSeek | \`DEEPSEEK_API_KEY\` | deepseek-coder |
+| Ollama | (none — local) | llama3.3:70b |
+| AWS Bedrock | \`AWS_ACCESS_KEY_ID\` + \`AWS_SECRET_ACCESS_KEY\` + \`AWS_REGION\` | claude-3.5-sonnet |
+
+Models are auto-discovered from provider APIs daily. The fallback models above are only used when the registry is unavailable (offline mode). Use \`GET /api/v1/models\` to see all currently available models.
+
+## Override via Env Vars
+
+Set \`ORCHEX_PROVIDER\` and \`ORCHEX_MODEL\` to override the auto-detected default:
+
+\`\`\`
+ORCHEX_PROVIDER=openai ORCHEX_MODEL=gpt-4o-mini
+\`\`\`
+
+## Auto-Detection
+
+Orchex scans available API keys at startup and selects a provider automatically. Priority order: Anthropic → OpenAI → Gemini → DeepSeek → Bedrock → Ollama.
+
+## Cloud Mode
+
+Cloud execution (\`mode: "cloud"\`) currently uses Anthropic as the backend provider. Provider and model settings in your config apply to **local mode only**. If you configure a non-Anthropic provider in cloud mode, Orchex will warn you before execution.
+
+To use non-Anthropic providers, run in local mode with your own API key:
+
+\`\`\`
+orchex config --local --provider openai
+export OPENAI_API_KEY=sk-...
+\`\`\`
+
+## Per-Stream Routing (Pro+)
+
+On Pro and Team tiers, individual streams can specify a different provider or model. This allows using a fast/cheap model for simple streams and a powerful model for complex ones within the same orchestration.
+
+## Model Registry
+
+Orchex maintains a dynamic model registry updated daily from provider APIs. Models are validated before execution — if a model is unavailable, orchex falls back to the next best option and warns you. The registry is cached locally (\`~/.orchex/models.json\`, 24h TTL) and refreshed on \`orchex login\`.
+
+## Providers
+
+All tiers support all 6 providers (BYOK) — no provider restrictions.
+
+## Ollama (Local)
+
+Ollama runs locally — no API key needed. Set \`ORCHEX_PROVIDER=ollama\` and \`ORCHEX_MODEL=<your-model>\`. Requires Ollama running on \`localhost:11434\`. Useful for air-gapped environments or cost-sensitive workloads.
+`,
+    },
+    'orchex://examples': {
+        name: 'Examples',
+        description: 'Real-world orchestration patterns',
+        content: `# Orchestration Examples
+
+## Example 1: Feature Implementation
+
+**Intent:** "Add user authentication with JWT to the Express API"
+
+\`\`\`
+auto intent="Add user authentication with JWT to the Express API" projectDir="/app"
+\`\`\`
+
+Typical output: 5 streams across 2 waves.
+
+- Wave 1: \`jwt-utils\` (owns: \`src/auth/jwt.ts\`), \`user-model\` (owns: \`src/models/user.ts\`)
+- Wave 2: \`auth-middleware\` (owns: \`src/middleware/auth.ts\`, reads: jwt-utils + user-model), \`auth-routes\` (owns: \`src/routes/auth.ts\`), \`auth-tests\` (owns: \`tests/auth.test.ts\`)
+
+## Example 2: Bug Fix
+
+**Intent:** "Fix the login timeout on mobile — users are logged out after 5 minutes"
+
+\`\`\`
+auto intent="Fix the login timeout on mobile — users are logged out after 5 minutes" projectDir="/app"
+\`\`\`
+
+Typical output: 2 streams, 1 wave (no dependencies between them).
+
+- \`session-config\` (owns: \`src/config/session.ts\`) — extend TTL
+- \`session-tests\` (owns: \`tests/session.test.ts\`) — add regression test
+
+## Example 3: Refactoring
+
+**Intent:** "Extract payment logic from the order controller into a dedicated PaymentService"
+
+Typical output: 4 streams, 3 waves.
+
+- Wave 1: \`payment-service\` (owns: \`src/services/payment.ts\`)
+- Wave 2: \`payment-tests\` (owns: \`tests/payment.test.ts\`), \`order-controller-update\` (owns: \`src/controllers/order.ts\`, reads: payment-service)
+- Wave 3: \`barrel-exports\` (owns: \`src/services/index.ts\`)
+
+## Example 4: From a PRD or Spec Document
+
+Orchex handles full documents — not just short intents:
+
+\`\`\`
+auto intent="<paste entire PRD or spec content here>" project_dir="/path/to/project"
+\`\`\`
+
+Orchex extracts implementation deliverables from the document, ignores non-code sections
+(executive summary, problem statement, market analysis), and generates development streams
+with proper file ownership.
+
+## Tips for Better Results
+
+- **Be specific**: "Add JWT auth to Express" beats "improve security"
+- **Mention file paths**: "…in \`src/routes/users.ts\`" guides stream planning
+- **Include constraints**: "do not modify the existing test suite", "use the existing \`db\` helper"
+- **Scope tightly**: one feature per orchestration; break large refactors into phases
+- **Verify commands**: Orchex uses \`npm test\` and \`tsc --noEmit\` by default — ensure they pass before starting
+`,
+    },
+    'orchex://api-reference': {
+        name: 'API Reference',
+        description: 'Stream definition schema and tool parameters',
+        content: `# API Reference
+
+## Stream Definition Schema
+
+\`\`\`
+StreamDefinition {
+  name:    string        // unique ID within orchestration
+  deps:    string[]      // names of streams that must complete first
+  owns:    string[]      // files this stream will create/modify (exclusive)
+  reads:   string[]      // files needed for context (non-exclusive)
+  plan:    string        // YAML instructions — the LLM's entire input
+  setup:   string[]      // shell commands before execution (e.g. "npm install")
+  verify:  string[]      // validation commands after execution (e.g. "npm test")
+}
+\`\`\`
+
+## Key Rules
+
+- \`owns\` paths must be relative to \`projectDir\` (no absolute paths, no \`../\` traversal)
+- \`deps\` references stream \`name\` values, not indices
+- \`plan\` is the LLM's entire instruction set — prose outside YAML blocks is not visible to the executing model
+- \`verify\` commands that exit non-zero trigger self-healing (if the error is retryable)
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`auto\` | Full autopilot: intent → plan → preview → execute |
+| \`init\` | Create orchestration from stream definitions |
+| \`add_stream\` | Add a stream to an existing orchestration |
+| \`execute\` | Run pending streams (mode: auto \| wave) |
+| \`status\` | Get current orchestration state |
+| \`complete\` | Finalize and archive orchestration |
+| \`recover\` | Resume a failed or interrupted orchestration |
+| \`learn\` | Parse implementation plan into stream definitions (internal — prefer auto) |
+| \`rollback-stream\` | Revert a specific stream's file changes |
+| \`reload\` | Reload orchestration state from disk |
+| \`reset-learning\` | Clear learned patterns |
+| \`init-plan\` | Initialize from a pre-written plan document |
+
+## auto Tool Parameters
+
+- \`intent\` (required) — natural language description of what to build
+- \`projectDir\` (required) — absolute path to project root
+- \`provider\` — override default LLM provider
+- \`model\` — override default model
+- \`approve\` — skip confirmation prompt (\`true\` for non-interactive use)
+
+## execute Tool Parameters
+
+- \`orchestrationId\` — ID from \`init\` or \`auto\`
+- \`mode\` — \`"auto"\` (all waves) or \`"wave"\` (next wave only)
+`,
+    },
+};
+export function registerResources(server) {
+    for (const [uriPath, entry] of Object.entries(RESOURCE_REGISTRY)) {
+        server.resource(entry.name, uriPath, { description: entry.description, mimeType: 'text/markdown' }, async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    text: entry.content,
+                    mimeType: 'text/markdown',
+                },
+            ],
+        }));
+    }
+}

package/dist/model-cache.d.ts

@@ -0,0 +1,18 @@
+export interface CachedModelEntry {
+    modelId: string;
+    displayName: string | null;
+    pricingInputPerM: number | null;
+    pricingOutputPerM: number | null;
+}
+export interface CachedModels {
+    providers: Record<string, CachedModelEntry[]>;
+    fetchedAt: string;
+}
+export declare function writeModelCache(data: CachedModels): Promise<void>;
+export declare function readModelCache(): Promise<CachedModels | null>;
+export declare function clearModelCache(): Promise<void>;
+/**
+ * Fetch models from Orchex server and cache locally.
+ * Returns null if server is unreachable (offline/local mode).
+ */
+export declare function fetchAndCacheModels(apiUrl: string): Promise<CachedModels | null>;

package/dist/model-cache.js

@@ -0,0 +1,62 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+/** TTL for cached models — 24 hours. */
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CACHE_FILENAME = 'models.json';
+function cacheDir() {
+    return process.env.ORCHEX_CONFIG_DIR ?? path.join(os.homedir(), '.orchex');
+}
+function cachePath() {
+    return path.join(cacheDir(), CACHE_FILENAME);
+}
+export async function writeModelCache(data) {
+    const dir = cacheDir();
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(cachePath(), JSON.stringify(data, null, 2), { encoding: 'utf-8', mode: 0o600 });
+}
+export async function readModelCache() {
+    try {
+        const raw = await fs.readFile(cachePath(), 'utf-8');
+        const data = JSON.parse(raw);
+        // TTL check
+        const age = Date.now() - new Date(data.fetchedAt).getTime();
+        if (age > CACHE_TTL_MS)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export async function clearModelCache() {
+    try {
+        await fs.unlink(cachePath());
+    }
+    catch {
+        // Ignore — file may not exist
+    }
+}
+/**
+ * Fetch models from Orchex server and cache locally.
+ * Returns null if server is unreachable (offline/local mode).
+ */
+export async function fetchAndCacheModels(apiUrl) {
+    try {
+        const resp = await fetch(`${apiUrl}/api/v1/models`, {
+            signal: AbortSignal.timeout(5000), // 5s timeout
+        });
+        if (!resp.ok)
+            return null;
+        const data = await resp.json();
+        const cached = {
+            providers: data.providers,
+            fetchedAt: new Date().toISOString(),
+        };
+        await writeModelCache(cached);
+        return cached;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/model-validator.d.ts

@@ -0,0 +1,20 @@
+import { type LLMProvider } from './config.js';
+export interface ModelValidationResult {
+    originalModel: string;
+    resolvedModel: string;
+    wasFallback: boolean;
+    reason?: string;
+}
+/**
+ * Static fallback chains — used only when registry + cache are both unavailable.
+ */
+export declare const MODEL_FALLBACKS: Record<string, string[]>;
+/**
+ * Resolve a model to an available one using the registry/cache.
+ * Resolution chain: cache → server fetch → static fallback
+ */
+export declare function resolveModel(provider: LLMProvider, preferredModel: string, apiUrl?: string): Promise<ModelValidationResult>;
+/**
+ * Check if a provider has a valid API key configured.
+ */
+export declare function isProviderAvailable(provider: LLMProvider): boolean;