feat: multi-agent engine on the Claude Agent SDK

.coderabbit.yaml

@@ -0,0 +1,41 @@
+# CodeRabbit configuration — https://docs.coderabbit.ai/getting-started/yaml-configuration
+# Repo-level config for activeloopai/open-repl. Requires the CodeRabbit GitHub
+# App to be installed on the repo/org for reviews to run.
+language: en-US
+reviews:
+  profile: chill # fewer low-value nitpicks; "assertive" is the only alternative
+  request_changes_workflow: false
+  high_level_summary: true
+  auto_review:
+    enabled: true
+    base_branches: ["main"]
+  # Don't spend review on generated / vendored / lock artifacts.
+  path_filters:
+    - "!**/package-lock.json"
+    - "!**/dist/**"
+    - "!**/coverage/**"
+    - "!.test-tmp/**"
+  # Repo-specific context so CodeRabbit stops re-raising known by-design items.
+  path_instructions:
+    - path: "packages/server/src/agent/claude/**"
+      instructions: >
+        This is the Claude Agent SDK engine. A deliberate, e2e-validated design
+        constraint: an in-process createSdkMcpServer is only reachable from the
+        MAIN thread — delegated subagents' MCP calls return "Stream closed", so
+        the ORCHESTRATOR does all file work via the MCP tools and the
+        planner/reviewer subagents use the SDK's built-in read-only tools. Do
+        NOT suggest giving subagents the MCP tools, nor moving run_app off the
+        orchestrator. The read-only loop guard in canUseTool is intentional.
+    - path: "packages/server/src/agent/claude/tools.ts"
+      instructions: >
+        The run_command allowlist is a coarse prefix guard, not a sandbox — this
+        is documented in the file. Don't re-flag that an allowed binary can
+        re-shell; true isolation is OS-level and deliberately deferred.
+    - path: "packages/server/src/agent/{orchestrator,subagents,runtime}.ts"
+      instructions: >
+        This is the legacy Vercel AI SDK path, intentionally kept for the
+        OpenRouter/Codex providers. Do not suggest deleting it as dead code.
+    - path: "packages/**/*.test.ts"
+      instructions: >
+        Prefer asserting on specific values (paths, tool names, model tiers)
+        over generic substrings.

.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What does this PR do and why? -->
+
+## Test plan
+
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes
+- [ ] Relevant new tests added (1:1 with the source they cover)
+- [ ] For agent/engine changes: verified end-to-end (`npx tsx scripts/check-claude-engine.ts`)

.github/workflows/ci.yaml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  # Run on every PR regardless of base branch.
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck-test:
+    name: Typecheck and test
+    runs-on: ubuntu-latest
+    # pull-requests: write lets the coverage-report action post its PR comment.
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Typecheck
+        run: npm run typecheck
+      - name: Test with coverage
+        # Per-file thresholds (statements/branches/functions/lines) live in
+        # vitest.config.ts under coverage.thresholds — vitest exits non-zero if
+        # a listed file regresses below its bar, failing the job.
+        run: npx vitest run --coverage
+      - name: Coverage summary (four categories)
+        if: always()
+        run: |
+          if [ -f coverage/coverage-summary.json ]; then
+            node -e "
+              const t = require('./coverage/coverage-summary.json').total;
+              const f = (m) => m.pct.toFixed(2) + '% (' + m.covered + '/' + m.total + ')';
+              const out = [
+                '### Test coverage',
+                '',
+                '| Category | Coverage |',
+                '|----------|----------|',
+                '| Statements | ' + f(t.statements) + ' |',
+                '| Branches | ' + f(t.branches) + ' |',
+                '| Functions | ' + f(t.functions) + ' |',
+                '| Lines | ' + f(t.lines) + ' |',
+              ].join('\n');
+              require('fs').appendFileSync(process.env.GITHUB_STEP_SUMMARY, out + '\n');
+              console.log(out);
+            "
+          fi
+      - name: Report coverage on the PR
+        if: ${{ always() && github.event_name == 'pull_request' }}
+        uses: davelosert/vitest-coverage-report-action@v2
+        with:
+          json-summary-path: coverage/coverage-summary.json
+          json-final-path: coverage/coverage-final.json
+      - name: Build web
+        run: npm run build:web
+
+  duplication:
+    # Code-duplication regression guard (jscpd). Separate job so the PR checks
+    # table shows a dedicated pass/fail row. Threshold lives in .jscpd.json.
+    name: Duplication check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Run jscpd
+        run: npm run dup
+      - name: Upload jscpd report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: jscpd-report
+          path: jscpd-report/
+          if-no-files-found: ignore

.github/workflows/codeql.yaml

@@ -0,0 +1,51 @@
+name: CodeQL
+
+# Static security analysis (SAST) for the TypeScript sources — surfaces
+# command-injection / path-traversal / unsafe-shell patterns (the bug class the
+# run_command allowlist guards) in the repo's Security tab and as inline PR
+# annotations. Findings do NOT fail the build by default; gate via branch
+# protection later if desired.
+
+on:
+  push:
+    branches: [main]
+  # Every PR regardless of base, so stacked / intermediate PRs don't skip SAST.
+  pull_request:
+  schedule:
+    # Weekly full scan (Mondays 06:00 UTC).
+    - cron: "0 6 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze (javascript-typescript)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write # upload SARIF results to the Security tab
+      actions: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+          queries: security-extended
+          # Scan shipped product source only. Dev/test harnesses (scripts/,
+          # *.test.ts) are not deployed and trip taint queries on values that
+          # come from our own server, not an attacker (e.g. the e2e driver's
+          # provider check). Keep SAST focused on packages/*/src.
+          config: |
+            paths-ignore:
+              - scripts/**
+              - "**/*.test.ts"
+              - "**/dist/**"
+      - name: Analyze
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:javascript-typescript"

.gitignore

@@ -9,3 +9,14 @@ dist/
 coverage/
 packages/web/dist/
 .test-tmp/
+jscpd-report/
+
+# Internal / agent-authored docs — never committed to the public repo (kept local only)
+.internal/
+PRD-*.md
+BACKLOG.md
+IMPLEMENTATION.md
+NIGHT-LOG.md
+PLAN.md
+STATUS.md
+todo_list.md

.jscpd.json

@@ -0,0 +1,19 @@
+{
+  "threshold": 7,
+  "reporters": ["console", "markdown"],
+  "output": "./jscpd-report",
+  "ignore": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/coverage/**",
+    "**/.test-tmp/**",
+    "**/*.test.ts",
+    "**/test/**",
+    "**/scripts/**"
+  ],
+  "absolute": false,
+  "gitignore": true,
+  "format": ["typescript", "tsx"],
+  "minLines": 10,
+  "minTokens": 60
+}