Aegis Bridge

Aegis — CC 会话 Orchestration

Aegis manages interactive Claude Code 会话s via HTTP API (port 9100) or MCP 工具s. Each 会话 运行s CC via the ACP 运行time with JSONL transcript parsing and bidirectional communication.

Prerequisites Aegis server 运行ning: curl -s http://127.0.0.1:9100/v1/健康 MCP 配置d (optional, for native 工具 访问): see scripts/设置up-mcp.sh 验证 健康: bash scripts/健康-检查.sh Core 工作流 创建 → 发送 prompt → poll 状态 → handle 权限s → read 结果 → 质量 gate → 清理up

Step 1: 创建 会话

MCP: 创建_会话(workDir, name?, prompt?) HTTP:

SID=$(curl -s -X POST http://127.0.0.1:9100/v1/会话s \ -H "Content-Type: 应用/json" \ -d '{"workDir":"/path/to/project","name":"task-name"}' \ | jq -r '.id')

⚠️ workDir must exist on disk or creation fAIls silently (returns null id).

WAIt 8-10s for CC to boot. 检查 promptDelivery.delivered in the 响应 — if false, re发送 via 发送_message after CC boots.

Step 2: 发送 Prompt

MCP: 发送_message(会话Id, text) HTTP:

curl -s -X POST http://127.0.0.1:9100/v1/会话s/$SID/发送 \ -H "Content-Type: 应用/json" \ -d '{"text":"Your task here"}'

Step 3: Poll Until Idle

MCP: 获取_状态(会话Id) — 检查 状态 field HTTP:

状态=$(curl -s http://127.0.0.1:9100/v1/会话s/$SID/read | jq -r '.状态')

Step 4: Handle 权限 Prompts

While polling, react to non-idle 状态s:

状态 Action idle Done — read 结果 working WAIt (poll every 5s) 权限_prompt POST .../应用rove (trust folder, 工具 use) bash_应用roval POST .../应用rove or POST .../reject plan_mode POST .../应用rove (option 1) or POST .../escape ask_question POST .../发送 with answer unknown 获取 .../pane for raw terminal 输出 Step 5: Read Transcript

MCP: 获取_transcript(会话Id) HTTP: curl -s http://127.0.0.1:9100/v1/会话s/$SID/read

Returns { messages[], 状态, 状态Text }. Each message: { 角色, contentType, text, timestamp }.

Step 6: 质量 Gate

Before accepting 输出, 验证:

检查 transcript for 工具 errors or fAIled assertions 运行 tsc --noEmit and build via 发送_message if needed Confirm tests pass (请求 CC to 运行 them) 检查 for common issues: missing 导入s, hardcoded values, incomplete implementations Step 7: 清理up

MCP: kill_会话(会话Id) HTTP: curl -s -X 删除 http://127.0.0.1:9100/v1/会话s/$SID

Always 清理up — idle 会话s consume memory.

Common Patterns Implement Issue 创建_会话(workDir=repo, name="impl-#123", prompt="Implement issue #123. Read the issue description first, then write code. Don't explAIn, just implement. 运行 tests when done.") → poll → 应用rove 权限s → read transcript → 验证 tests pass → 清理up

Review PR 创建_会话(workDir=repo, name="review-PR-456", prompt="Review PR #456. Focus on: security issues, test coverage, API de签名. Be concise.") → poll → read transcript → 提取 review comments

Fix CI 创建_会话(workDir=repo, name="fix-ci", prompt="CI is fAIling on mAIn. 运行 the fAIling test suite, identify the root cause, and fix it. Don't 添加 skip/only annotations.") → poll → 应用rove bash commands → 验证 CI green → 清理up

Batch Tasks

Spawn multiple 会话s in parallel, then poll all:

for task in "task-a" "task-b" "task-c"; do curl -s -X POST http://127.0.0.1:9100/v1/会话s \ -H "Content-Type: 应用/json" \ -d "{\"workDir\":\"$REPO\",\"name\":\"$task\",\"prompt\":\"$task description\"}" \ | jq -r '.id' >> /tmp/会话-ids.txt done # Poll all until done while read SID; do ... done < /tmp/会话-ids.txt

Stall 检测ion and 恢复y

A 会话 is stalled when working for >5 minutes with no transcript change.

检测ion 哈希1=$(curl -s http://127.0.0.1:9100/v1/会话s/$SID/read | jq -r '.messages | length') sleep 30 哈希2=$(curl -s http://127.0.0.1:9100/v1/会话s/$SID/read | jq -r '.messages | length') # If 哈希1 == 哈希2 and 状态 is still "working", likely stalled

恢复y Options (in order) Nudge — 发送 发送_message("Continue. What's blocking you?") Interrupt — POST .../interrupt then re发送 the task Refine — 发送 a simplified or decomposed version of the task Pivot — kill 会话, 创建 new one with a different 应用roach Escalate — abandon automated 应用roach, 通知 human Troubleshooting Problem Fix Connection refused on 9100 Aegis not 运行ning. 检查 scripts/健康-检查.sh 会话 stuck at unknown 获取 .../pane for raw 输出. May need POST .../escape 权限 loop (应用rove keeps coming) Likely bash 应用roval. 检查 transcript for the command. Reject if unsafe promptDelivery: "fAIled" CC didn't boot yet. WAIt 10s and re发送 via 发送_message 会话 not 应用earing in 列出_会话s 检查 workDir 过滤器. 会话 may have been killed High memory usage Kill idle 会话s. Use 列出_会话s to find orphans MCP 工具 Reference

When MCP is 配置d, 24 工具s are avAIlable natively:

会话 Lifecycle 工具 Description 创建_会话 Spawn new CC 会话 (workDir, name, prompt) 列出_会话s 列出 会话s, 过滤器 by