@oxgeneral/orch 1.0.5 → 1.0.6

package/readme.md

@@ -15,7 +15,7 @@
   <a href="https://www.orch.one/"><img src="https://img.shields.io/badge/website-orch.one-f59e0b?style=for-the-badge&labelColor=0a0a0a" alt="Website" /></a>&nbsp;
   <a href="https://www.npmjs.com/package/@oxgeneral/orch"><img src="https://img.shields.io/npm/v/@oxgeneral/orch?style=for-the-badge&color=f59e0b&labelColor=0a0a0a" alt="npm" /></a>&nbsp;
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-f59e0b?style=for-the-badge&labelColor=0a0a0a" alt="MIT License" /></a>&nbsp;
-  <a href="#development"><img src="https://img.shields.io/badge/tests-1493%20passing-f59e0b?style=for-the-badge&labelColor=0a0a0a" alt="Tests" /></a>
+  <a href="#development"><img src="https://img.shields.io/badge/tests-1647%20passing-f59e0b?style=for-the-badge&labelColor=0a0a0a" alt="Tests" /></a>
 </p>
 
 <br/>
@@ -25,6 +25,7 @@
   <a href="#start-coordinating-agents-in-30-seconds">Install</a> &bull;
   <a href="#how-your-ai-team-works">How It Works</a> &bull;
   <a href="#why-founders-choose-orch">Features</a> &bull;
+  <a href="#headless-daemon--cicd">Serve</a> &bull;
   <a href="#pre-built-teams--start-with-a-proven-setup">Templates</a> &bull;
   <a href="#full-cli-reference">CLI</a> &bull;
   <a href="#architecture">Architecture</a> &bull;
@@ -373,6 +374,92 @@ orch org export my-team                          # Save your setup as template
 
 <br/>
 
+## Headless daemon & CI/CD
+
+Run ORCH on a server 24/7 — no terminal, no TUI. Structured JSON logs for Datadog, Grafana Loki, or `jq`.
+
+```bash
+# Daemon mode — runs forever, picks up new tasks automatically
+orch serve
+
+# CI/CD mode — process current tasks and exit
+orch serve --once        # exit 0 = all done, exit 1 = has failures
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--once` | Process all todo tasks and exit | watch mode |
+| `--tick-interval <ms>` | Override polling interval | 10000 |
+| `--log-file <path>` | Tee logs to a file (append) | stdout only |
+| `--log-format json\|text` | Output format | json |
+| `--verbose` | Include `agent:output` events | off |
+
+### Structured logs
+
+Every event is a single JSON line — pipe to any log aggregator:
+
+```json
+{"ts":"2026-03-17T03:00:10.000Z","level":"info","event":"agent:started","agentId":"agt_abc","taskId":"tsk_123","runId":"run_xyz"}
+{"ts":"2026-03-17T03:12:45.000Z","level":"info","event":"task:status_changed","taskId":"tsk_123","from":"in_progress","to":"review"}
+{"ts":"2026-03-17T03:12:46.000Z","level":"info","event":"orchestrator:tick","running":0,"queued":2,"heap_mb":142}
+```
+
+### Deploy with pm2 or systemd
+
+<details>
+<summary><strong>pm2</strong></summary>
+
+```bash
+pm2 start "orch serve" --name orch-daemon --cwd ~/my-project
+pm2 logs orch-daemon     # structured JSON logs
+pm2 stop orch-daemon     # SIGINT → graceful shutdown
+```
+
+</details>
+
+<details>
+<summary><strong>systemd</strong></summary>
+
+```ini
+[Unit]
+Description=ORCH AI Agent Daemon
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/home/user/my-project
+ExecStart=/usr/local/bin/orch serve
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+</details>
+
+### How it works
+
+- **Watch mode** (default): tick loop runs indefinitely. Add tasks from another terminal (`orch task add`) — daemon picks them up on the next tick.
+- **Once mode** (`--once`): processes all existing todo tasks, skips autonomous task seeding, exits when everything reaches a terminal status.
+- **Lock protection**: only one orchestrator per project (reuses `.orchestry/orchestry.lock`). Second `orch serve` exits with a clear error.
+- **Graceful shutdown**: SIGINT/SIGTERM → stops accepting new tasks → waits for running agents → saves state → releases lock.
+- **Heap monitoring**: every tick logs `heap_mb` — catch memory leaks before OOM.
+- **Idle throttling**: logs every 6th idle tick (~60s) to avoid flooding logs when nothing is happening.
+
+<br/>
+
+<!-- Divider -->
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./assets/divider-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="./assets/divider-light.svg">
+  <img alt="" src="./assets/divider-dark.svg" width="100%">
+</picture>
+
+<br/>
+
 ## Full CLI reference
 
 <details>
@@ -461,6 +548,8 @@ orch context set <key> <value>                  # Shared context
 ```bash
 orch run --all --watch             # Launch all agents
 orch run <task-id>                 # Run single task
+orch serve                         # Headless daemon (JSON logs)
+orch serve --once                  # CI/CD: process and exit
 orch status                        # Quick overview
 orch logs <run-id>                 # View run logs
 orch tui                           # Command center (TUI)
@@ -521,7 +610,7 @@ src/
 ```bash
 npm run dev            # Run via tsx
 npm run build          # Build ESM + DTS
-npm test               # 1493 tests via Vitest
+npm test               # 1647 tests via Vitest
 npm run typecheck      # Strict TypeScript
 ```
 
@@ -609,6 +698,15 @@ Five adapters: **Claude Code**, **OpenCode** (Gemini, DeepSeek, any OpenRouter m
 
 </details>
 
+<details>
+<summary><strong>Can I run agents 24/7 on a server?</strong></summary>
+
+<br/>
+
+Yes. `orch serve` runs the orchestrator as a headless daemon — no TUI, structured JSON logs to stdout. Deploy with pm2, systemd, or any process manager. Add tasks from another terminal or machine — the daemon picks them up automatically. Graceful shutdown on SIGINT/SIGTERM.
+
+</details>
+
 <details>
 <summary><strong>Is there a cloud component?</strong></summary>
 

package/scripts/demo.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# ============================================================
+#  ORCH Demo — asciinema-ready terminal workflow
+#
+#  Record:   asciinema rec demo.cast -c ./scripts/demo.sh \
+#              --title "ORCH — AI Agent Runtime Demo"
+#
+#  Preview:  asciinema play demo.cast
+#  To GIF:   agg demo.cast demo.gif --font-size 14 --theme monokai
+#
+#  Duration: ~75 seconds
+#  Shows:    setup → add agents → add tasks → run --all →
+#            parallel execution → state transitions → status
+# ============================================================
+set -euo pipefail
+
+# ── visual config ────────────────────────────────────────────
+TYPE_SPEED=0.035   # seconds per character (adjust for recording speed)
+CMD_PAUSE=0.7      # pause after showing command before running
+SECTION_PAUSE=1.0  # pause between sections
+OUTPUT_PAUSE=0.4   # pause after output before next step
+
+# ── color helpers ────────────────────────────────────────────
+RESET="\033[0m"
+BOLD="\033[1m"
+GREEN="\033[1;32m"
+YELLOW="\033[1;33m"
+CYAN="\033[1;36m"
+BLUE="\033[0;34m"
+MAGENTA="\033[0;35m"
+DIM="\033[90m"
+RED="\033[0;31m"
+
+# ── utility functions ────────────────────────────────────────
+type_cmd() {
+  printf "${GREEN}\$${RESET} "
+  local text="$1"
+  for (( i=0; i<${#text}; i++ )); do
+    printf "%s" "${text:$i:1}"
+    sleep "$TYPE_SPEED"
+  done
+  sleep "$CMD_PAUSE"
+  printf "\n"
+}
+
+run_cmd() {
+  eval "$1" 2>/dev/null || true
+  sleep "$OUTPUT_PAUSE"
+}
+
+pause() { sleep "${1:-$SECTION_PAUSE}"; }
+
+section() {
+  printf "\n${YELLOW}# ── %s ──${RESET}\n\n" "$1"
+  sleep 0.5
+}
+
+divider() {
+  printf "${DIM}────────────────────────────────────────────────────${RESET}\n"
+}
+
+# ── demo environment setup ───────────────────────────────────
+DEMO_DIR="/tmp/orch-demo-$$"
+mkdir -p "$DEMO_DIR"
+cd "$DEMO_DIR"
+
+# pre-create .orchestry structure silently so init is instant
+export NO_COLOR=""
+
+# ── SCENE 0: Clear + intro ───────────────────────────────────
+clear
+sleep 0.5
+
+printf "${YELLOW}${BOLD}"
+printf "  ┌─────────────────────────────────────────────────┐\n"
+printf "  │  ORCH — AI Agent Runtime                        │\n"
+printf "  │  3 agents. Parallel execution. Zero babysitting │\n"
+printf "  └─────────────────────────────────────────────────┘\n"
+printf "${RESET}\n"
+sleep 1.5
+
+# ── SCENE 1: Install (show only — not actually installing) ───
+section "Install"
+
+type_cmd "npm install -g @oxgeneral/orch"
+printf "${DIM}  added 1 package in 2.1s${RESET}\n"
+printf "${GREEN}  ✓ orch v1.0.5 installed${RESET}\n"
+sleep "$OUTPUT_PAUSE"
+pause 0.5
+
+# ── SCENE 2: Init ────────────────────────────────────────────
+section "Initialize project"
+
+type_cmd "mkdir my-project && cd my-project"
+printf ""  # no output
+
+type_cmd "orch init"
+run_cmd "orch init"
+pause 0.5
+
+# ── SCENE 3: Add agents ──────────────────────────────────────
+section "Add your AI team (3 agents)"
+
+type_cmd 'orch agent add "Backend" --adapter claude --model claude-sonnet-4-6 --role "Senior TypeScript developer. Implements features end-to-end." --approval-policy auto'
+run_cmd 'orch agent add "Backend" --adapter claude --model claude-sonnet-4-6 --role "Senior TypeScript developer. Implements features end-to-end." --approval-policy auto'
+
+type_cmd 'orch agent add "QA" --adapter claude --model claude-sonnet-4-6 --role "QA engineer. Writes integration tests, verifies correctness." --approval-policy auto'
+run_cmd 'orch agent add "QA" --adapter claude --model claude-sonnet-4-6 --role "QA engineer. Writes integration tests, verifies correctness." --approval-policy auto'
+
+type_cmd 'orch agent add "Reviewer" --adapter claude --model claude-sonnet-4-6 --role "Code reviewer. Checks quality, security, and edge cases." --approval-policy auto'
+run_cmd 'orch agent add "Reviewer" --adapter claude --model claude-sonnet-4-6 --role "Code reviewer. Checks quality, security, and edge cases." --approval-policy auto'
+
+pause 0.3
+type_cmd "orch agent list"
+run_cmd "orch agent list"
+pause
+
+# ── SCENE 4: Add tasks ───────────────────────────────────────
+section "Queue tasks"
+
+type_cmd 'orch task add "Implement REST API: GET /users endpoint" -p 2'
+run_cmd 'orch task add "Implement REST API: GET /users endpoint" -p 2'
+
+type_cmd 'orch task add "Write integration tests for /users endpoint" -p 2'
+run_cmd 'orch task add "Write integration tests for /users endpoint" -p 2'
+
+type_cmd 'orch task add "Review: API implementation + test coverage" -p 3'
+run_cmd 'orch task add "Review: API implementation + test coverage" -p 3'
+
+pause 0.3
+type_cmd "orch task list"
+run_cmd "orch task list"
+pause
+
+# ── SCENE 5: Run — simulated parallel execution ──────────────
+section "orch run --all  (parallel execution)"
+
+printf "${GREEN}\$${RESET} orch run --all\n"
+sleep 0.4
+
+printf "${DIM}[orchestrator] tick #1 — dispatching idle agents...${RESET}\n"; sleep 0.3
+divider
+
+# Backend and QA claim tasks simultaneously
+printf "${BLUE}[Backend  ]${RESET}  ${YELLOW}▶${RESET}  Claiming  \"Implement REST API: GET /users endpoint\"\n"; sleep 0.15
+printf "${MAGENTA}[QA       ]${RESET}  ${YELLOW}▶${RESET}  Claiming  \"Write integration tests for /users endpoint\"\n"; sleep 0.3
+
+printf "${BLUE}[Backend  ]${RESET}  ${YELLOW}●${RESET}  Running   ${DIM}todo${RESET} → ${YELLOW}in_progress${RESET}\n"; sleep 0.15
+printf "${MAGENTA}[QA       ]${RESET}  ${YELLOW}●${RESET}  Running   ${DIM}todo${RESET} → ${YELLOW}in_progress${RESET}\n"; sleep 0.4
+
+printf "${DIM}[orchestrator] 2 agents running in parallel...${RESET}\n"; sleep 1.2
+
+# Backend finishes first
+printf "${BLUE}[Backend  ]${RESET}  ${CYAN}⏸${RESET}  Awaiting  ${YELLOW}in_progress${RESET} → ${CYAN}review${RESET}\n"; sleep 0.5
+
+# QA finishes
+printf "${MAGENTA}[QA       ]${RESET}  ${CYAN}⏸${RESET}  Awaiting  ${YELLOW}in_progress${RESET} → ${CYAN}review${RESET}\n"; sleep 0.4
+
+printf "${DIM}[orchestrator] tick #2 — dispatching Reviewer...${RESET}\n"; sleep 0.3
+divider
+
+printf "${YELLOW}[Reviewer ]${RESET}  ${YELLOW}▶${RESET}  Claiming  \"Review: API implementation + test coverage\"\n"; sleep 0.2
+printf "${YELLOW}[Reviewer ]${RESET}  ${YELLOW}●${RESET}  Running   ${DIM}todo${RESET} → ${YELLOW}in_progress${RESET}\n"; sleep 1.0
+
+# Reviewer approves both
+printf "${BLUE}[Backend  ]${RESET}  ${GREEN}✓${RESET}  Approved  ${CYAN}review${RESET} → ${GREEN}done${RESET}\n"; sleep 0.3
+printf "${MAGENTA}[QA       ]${RESET}  ${GREEN}✓${RESET}  Approved  ${CYAN}review${RESET} → ${GREEN}done${RESET}\n"; sleep 0.4
+printf "${YELLOW}[Reviewer ]${RESET}  ${GREEN}✓${RESET}  Done      ${YELLOW}in_progress${RESET} → ${GREEN}done${RESET}\n"; sleep 0.3
+
+divider
+printf "\n${GREEN}${BOLD}✓  All 3 tasks completed.  2 agents ran in parallel.  0 failures.${RESET}\n"
+printf "${DIM}   Total: ~47s · Backend: 31s · QA: 38s · Reviewer: 22s${RESET}\n"
+pause
+
+# ── SCENE 6: Final status check ─────────────────────────────
+section "Results"
+
+type_cmd "orch task list"
+run_cmd "orch task list"
+pause 0.5
+
+type_cmd "orch status"
+run_cmd "orch status"
+pause
+
+# ── OUTRO ────────────────────────────────────────────────────
+printf "\n"
+printf "${YELLOW}${BOLD}"
+printf "╔══════════════════════════════════════════════════════╗\n"
+printf "║  ORCH — AI Agent Runtime                             ║\n"
+printf "║                                                      ║\n"
+printf "║  npm install -g @oxgeneral/orch                      ║\n"
+printf "║  github.com/oxgeneral/ORCH                           ║\n"
+printf "║                                                      ║\n"
+printf "║  ⭐ Star us if this saved you time                   ║\n"
+printf "╚══════════════════════════════════════════════════════╝\n"
+printf "${RESET}\n"
+sleep 3
+
+# ── cleanup ──────────────────────────────────────────────────
+cd /tmp
+rm -rf "$DEMO_DIR"

package/scripts/postinstall.js

@@ -61,4 +61,6 @@ process.stderr.write(`
   Get started:
     $ ${bold('orch')}
 
+  ${dim('⭐ Like it? Star us on GitHub: https://github.com/oxgeneral/ORCH')}
+
 `);