@aithr-ai/mcp-server 1.2.2 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithr-ai/mcp-server",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "MCP server to connect Claude Code to Aether canvas - AI-powered team workspace for software development",
   "main": "index.js",
   "bin": {

package/skills/orchestra/SKILL.md

@@ -2753,10 +2753,183 @@ aether_push_local({
 
 ---
 
+## Reliability Features (Orchestra v8)
+
+Orchestra v8 introduces comprehensive reliability improvements to ensure sessions complete successfully.
+
+### Automatic Artifact Validation
+
+Every artifact is validated before a task is marked complete:
+
+```
+Agent produces artifact
+        ↓
+┌───────────────────────────┐
+│  JSON Structure Check     │  Is it valid JSON?
+└───────────────────────────┘
+        ↓
+   ┌────┴────┐
+  VALID    INVALID
+   │         │
+   │         ▼
+   │    ┌───────────────────────────┐
+   │    │  Auto-Repair Attempt      │  Try to fix malformed JSON
+   │    └───────────────────────────┘
+   │         │
+   │    ┌────┴────┐
+   │  REPAIRED  UNREPAIRABLE
+   │    │         │
+   │    │         ▼
+   │    │    ┌───────────────────────────┐
+   │    │    │  REJECT completion        │  Return error, ask for retry
+   │    │    │  Task stays pending       │
+   │    │    └───────────────────────────┘
+   ▼    ▼
+┌───────────────────────────┐
+│  Mark task complete       │  Artifact stored
+└───────────────────────────┘
+```
+
+**What gets validated:**
+- JSON structure (must be valid JSON, not markdown code blocks)
+- Code artifacts: Must follow `{ "type": "structured_output", "files": [...] }` format
+- File paths in artifacts must be valid
+
+**Auto-repair capabilities:**
+- Strips markdown code fence wrappers (`\`\`\`json ... \`\`\``)
+- Fixes trailing commas
+- Repairs unescaped characters
+- Handles truncated JSON (detects and warns)
+
+### Auto-Retry Failed Tasks
+
+Tasks that fail due to validation errors automatically retry (up to 3 times):
+
+```
+Task fails validation
+        ↓
+┌───────────────────────────┐
+│  Check retry count        │  [retry N/3] in error message
+└───────────────────────────┘
+        │
+   ┌────┴────┐
+  <3 retries  ≥3 retries
+   │            │
+   ▼            ▼
+┌─────────────┐ ┌─────────────────────────┐
+│ Reset task  │ │ Leave as failed         │
+│ to pending  │ │ (requires manual help)  │
+└─────────────┘ └─────────────────────────┘
+```
+
+### Stalled Task Detection
+
+Tasks that get stuck are automatically detected and reset:
+
+| Condition | Threshold | Action |
+|-----------|-----------|--------|
+| `in_progress` with no completion | 10 minutes | Reset to `pending` |
+| `awaiting_report` without artifact | 5 minutes | Reset to `pending` |
+| `awaiting_report` with artifact | Immediate | Mark as `completed` |
+
+This prevents sessions from getting permanently stuck on unresponsive tasks.
+
+### TypeScript Validation Between Phases
+
+When a phase completes, all code artifacts are validated:
+
+```
+All phase tasks complete
+        ↓
+┌───────────────────────────┐
+│  Extract .ts/.tsx files   │  From all phase artifacts
+└───────────────────────────┘
+        ↓
+┌───────────────────────────┐
+│  In-memory TypeScript     │  Validates types, imports, syntax
+│  validation               │
+└───────────────────────────┘
+        │
+   ┌────┴────┐
+  PASS      FAIL
+   │         │
+   ▼         ▼
+┌───────────┐ ┌───────────────────────────┐
+│ Advance   │ │ Create fix tasks          │
+│ to next   │ │ Don't advance phase       │
+│ phase     │ │ Return with errors        │
+└───────────┘ └───────────────────────────┘
+```
+
+**Validation includes:**
+- TypeScript type checking
+- Import resolution verification
+- Syntax error detection
+- Up to 20 errors reported per phase
+
+### Timeout Enforcement
+
+Sessions now actually stop when limits are exceeded:
+
+| Limit | Default | Enforcement |
+|-------|---------|-------------|
+| `timeoutMinutes` | 480 (8h) | Session auto-stops, status set to `completed` |
+| `maxIterations` | 100 | Session auto-stops, status set to `completed` |
+
+Previously, limits were checked but sessions could continue. Now they definitively stop.
+
+### Enhanced Upstream Artifact Context
+
+When tasks receive context from upstream artifacts, they now get:
+
+1. **File list summary**: Which files were created by upstream tasks
+2. **Type file warnings**: Explicit warnings about files that must be imported (not redefined)
+3. **Structured formatting**: Clear separation between artifacts
+
+Example context injection:
+
+```markdown
+## Artifacts from Upstream Tasks
+
+**IMPORTANT:** These artifacts were produced by tasks that completed before you. Use this information to:
+- Maintain consistency with established patterns and decisions
+- Reference types, interfaces, and schemas already defined
+- Build upon completed work rather than duplicating it
+- Follow naming conventions and architecture established in earlier phases
+
+**Available upstream artifacts (2):**
+- Phase 1.2: Database Schema (code)
+- Phase 1.3: Type Definitions (code)
+
+---
+
+### From Phase 1, Task 2: Database Schema
+**Artifact:** Database Schema (code)
+**Files created:** src/lib/db/schema.ts, src/lib/db/index.ts
+**⚠️ IMPORT from these type files, don't redefine:** src/lib/db/schema.ts
+
+\`\`\`
+{ "type": "structured_output", "files": [...] }
+\`\`\`
+
+**Note:** If upstream artifacts define types, schemas, or patterns - IMPORT them, don't redefine them. Type redefinition creates compilation failures in the automated pipeline.
+```
+
+### Best Practices for Reliability
+
+1. **Always use JSON output** - Ensure agents produce valid JSON, not markdown
+2. **Explicit file declarations** - Set `targetFiles` on tasks for better collision prevention
+3. **Monitor session status** - Check `safeguards` in `aether_orchestra_status`
+4. **Use checkpoints** - Run `aether_orchestra_checkpoint` between phases
+5. **Handle validation errors** - When validation fails, fix the issues don't just retry
+
+---
+
 ## Version History
 
 | Version | Date | Changes |
 |---------|------|---------|
+| v8.0 | 2026-01 | Reliability improvements: artifact validation, auto-retry, stalled detection, TypeScript validation |
 | v7.0 | 2025-01 | Workflow enforcement: validate, checkpoint, guide tools |
 | v6.0 | 2025-01 | File collision prevention, file lock manager |
 | v5.0 | 2025-01 | Contract-first development, validation protocol |
@@ -2826,4 +2999,4 @@ aether_edit_orchestra({ sessionId, action: "add_task", ... })
 
 ---
 
-*Orchestra v7 - Autonomous AI Development Orchestration with Workflow Enforcement, Contract-First Development, Dynamic Agent Switching, and File Collision Prevention. The trust of millions of codebases depends on this system working reliably.*
+*Orchestra v8 - Autonomous AI Development Orchestration with Reliability Improvements, Workflow Enforcement, Contract-First Development, Dynamic Agent Switching, and File Collision Prevention. The trust of millions of codebases depends on this system working reliably.*