apps/orchestrator/.env.example

@@ -0,0 +1,19 @@
+# Orchestrator Configuration
+ORCHESTRATOR_PORT=3001
+
+# Valkey
+VALKEY_URL=redis://localhost:6379
+
+# Claude API
+CLAUDE_API_KEY=your-api-key-here
+
+# Docker
+DOCKER_SOCKET=/var/run/docker.sock
+
+# Git
+GIT_USER_NAME="Mosaic Orchestrator"
+GIT_USER_EMAIL="orchestrator@mosaicstack.dev"
+
+# Security
+KILLSWITCH_ENABLED=true
+SANDBOX_ENABLED=true

apps/orchestrator/Dockerfile

@@ -0,0 +1,19 @@
+FROM node:20-alpine AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+
+FROM base AS builder
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY apps/orchestrator ./apps/orchestrator
+COPY packages ./packages
+RUN pnpm install --frozen-lockfile
+RUN pnpm --filter @mosaic/orchestrator build
+
+FROM base AS runtime
+WORKDIR /app
+COPY --from=builder /app/apps/orchestrator/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+EXPOSE 3001
+CMD ["node", "dist/main.js"]

apps/orchestrator/README.md

@@ -0,0 +1,46 @@
+# Mosaic Orchestrator
+
+Agent orchestration service for Mosaic Stack.
+
+## Overview
+
+The Orchestrator is the execution plane of Mosaic Stack, responsible for:
+- Spawning and managing Claude agents
+- Task queue management (Valkey-backed)
+- Agent health monitoring and recovery
+- Git workflow automation
+- Quality gate enforcement callbacks
+- Killswitch emergency stop
+
+## Architecture
+
+Part of the Mosaic Stack monorepo at `apps/orchestrator/`.
+
+Controlled by `apps/coordinator/` (Quality Coordinator).
+Monitored via `apps/web/` (Agent Dashboard).
+
+## Development
+
+```bash
+# Install dependencies (from monorepo root)
+pnpm install
+
+# Run in dev mode
+pnpm --filter @mosaic/orchestrator dev
+
+# Build
+pnpm --filter @mosaic/orchestrator build
+
+# Test
+pnpm --filter @mosaic/orchestrator test
+```
+
+## Configuration
+
+See `.env.example` for required environment variables.
+
+## Documentation
+
+- Architecture: `/docs/ORCHESTRATOR-MONOREPO-SETUP.md`
+- API Contracts: `/docs/M6-ISSUE-AUDIT.md`
+- Milestone: M6-AgentOrchestration (0.0.6)

apps/orchestrator/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mosaic/orchestrator",
+  "version": "0.0.6",
+  "private": true,
+  "type": "module",
+  "main": "dist/main.js",
+  "scripts": {
+    "dev": "tsx watch src/main.ts",
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.31.1",
+    "@mosaic/shared": "workspace:*",
+    "@mosaic/config": "workspace:*",
+    "fastify": "^5.2.0",
+    "ioredis": "^5.4.2",
+    "dockerode": "^4.0.2",
+    "simple-git": "^3.27.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.31",
+    "@types/node": "^22.10.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  }
+}

apps/orchestrator/src/api/routes/health.routes.ts

@@ -0,0 +1,17 @@
+import { FastifyPluginAsync } from 'fastify';
+
+export const healthRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get('/health', async () => {
+    return {
+      status: 'ok',
+      service: 'orchestrator',
+      version: '0.0.6',
+      timestamp: new Date().toISOString()
+    };
+  });
+
+  fastify.get('/health/ready', async () => {
+    // TODO: Check Valkey connection, Docker daemon
+    return { ready: true };
+  });
+};

apps/orchestrator/src/api/server.ts

@@ -0,0 +1,13 @@
+import Fastify from 'fastify';
+import { healthRoutes } from './routes/health.routes.js';
+
+export async function createServer() {
+  const fastify = Fastify({
+    logger: true,
+  });
+
+  // Health check routes
+  await fastify.register(healthRoutes);
+
+  return fastify;
+}

apps/orchestrator/src/main.ts

@@ -0,0 +1,28 @@
+/**
+ * Mosaic Orchestrator - Agent Orchestration Service
+ *
+ * Execution plane for Mosaic Stack agent coordination.
+ * Spawns, monitors, and manages Claude agents for autonomous work.
+ */
+
+import { createServer } from './api/server.js';
+
+const PORT = process.env.ORCHESTRATOR_PORT || 3001;
+
+async function bootstrap() {
+  console.log('🚀 Starting Mosaic Orchestrator...');
+
+  const server = await createServer();
+
+  await server.listen({
+    port: Number(PORT),
+    host: '0.0.0.0'
+  });
+
+  console.log(`✅ Orchestrator running on http://0.0.0.0:${PORT}`);
+}
+
+bootstrap().catch((error) => {
+  console.error('Failed to start orchestrator:', error);
+  process.exit(1);
+});

apps/orchestrator/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

docker-compose.yml

@@ -349,6 +349,53 @@ services:
       # Let's Encrypt (if enabled)
       - "traefik.http.routers.mosaic-api.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
 
+  # ======================
+  # Mosaic Orchestrator
+  # ======================
+  orchestrator:
+    build:
+      context: .
+      dockerfile: ./apps/orchestrator/Dockerfile
+    container_name: mosaic-orchestrator
+    restart: unless-stopped
+    environment:
+      NODE_ENV: production
+      # Orchestrator Configuration
+      ORCHESTRATOR_PORT: 3001
+      # Valkey
+      VALKEY_URL: redis://valkey:6379
+      # Claude API
+      CLAUDE_API_KEY: ${CLAUDE_API_KEY}
+      # Docker
+      DOCKER_SOCKET: /var/run/docker.sock
+      # Git
+      GIT_USER_NAME: "Mosaic Orchestrator"
+      GIT_USER_EMAIL: "orchestrator@mosaicstack.dev"
+      # Security
+      KILLSWITCH_ENABLED: true
+      SANDBOX_ENABLED: true
+    ports:
+      - "3002:3001"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - orchestrator_workspace:/workspace
+    depends_on:
+      valkey:
+        condition: service_healthy
+      api:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    networks:
+      - mosaic-internal
+    labels:
+      - "com.mosaic.service=orchestrator"
+      - "com.mosaic.description=Mosaic Agent Orchestrator"
+
   # ======================
   # Mosaic Web
   # ======================
@@ -425,6 +472,9 @@ volumes:
   traefik_letsencrypt:
     name: mosaic-traefik-letsencrypt
     driver: local
+  orchestrator_workspace:
+    name: mosaic-orchestrator-workspace
+    driver: local
 
 # ======================
 # Networks