@dmsdc-ai/aigentry-devkit 0.1.0 → 0.1.2

package/README.md

@@ -56,13 +56,15 @@ Pre-configured settings with template substitution:
 All OS (recommended):
 
 ```bash
-npx -y @dmsdc-ai/aigentry-devkit install
+npx --yes --package @dmsdc-ai/aigentry-devkit aigentry-devkit install
 ```
 
+`git clone` is not required for this path. The npm package contains the full installer + runtime files.
+
 Force reinstall:
 
 ```bash
-npx -y @dmsdc-ai/aigentry-devkit install --force
+npx --yes --package @dmsdc-ai/aigentry-devkit aigentry-devkit install --force
 ```
 
 Manual install (local clone) is still available:
@@ -86,9 +88,9 @@ powershell -ExecutionPolicy Bypass -File .\install.ps1
 The installer will:
 
 1. Verify Node.js and optional dependencies (Claude Code CLI, tmux, direnv)
-2. Link skills to `~/.claude/skills/`
+2. Install skills to `~/.claude/skills/`
 3. Install HUD statusline to `~/.claude/hud/`
-4. Set up MCP Deliberation Server at `~/.local/lib/mcp-deliberation/`
+4. Set up full MCP Deliberation runtime at `~/.local/lib/mcp-deliberation/` (server + browser adapters + selectors + monitor)
 5. Register MCP server in `~/.claude/.mcp.json`
 6. Create configuration templates from templates
 7. Attempt Codex CLI integration (if available)
@@ -105,9 +107,10 @@ After installation, restart Claude/Codex for changes to take effect:
 To verify installation:
 
 ```bash
-ls -la ~/.claude/skills/      # Check skills are linked
+ls -la ~/.claude/skills/      # Check skills are installed
 ls -la ~/.claude/hud/         # Check HUD is installed
 ls -la ~/.local/lib/mcp-deliberation/  # Check MCP server
+ls -la ~/.local/lib/mcp-deliberation/selectors/  # Check browser selector assets
 cat ~/.claude/.mcp.json       # Verify MCP registration
 ```
 
@@ -313,7 +316,7 @@ direnv allow
 
 ### Skills not loading
 
-1. Verify skills are linked: `ls -la ~/.claude/skills/`
+1. Verify skills are installed: `ls -la ~/.claude/skills/`
 2. Restart your MCP client process (Claude/Codex/etc.)
 3. Check for keyword matches in skill definitions
 
@@ -321,8 +324,9 @@ direnv allow
 
 1. Verify MCP registration: `cat ~/.claude/.mcp.json`
 2. Check installation: `ls ~/.local/lib/mcp-deliberation/`
-3. Restart your MCP client process (Claude/Codex/etc.)
-4. Review MCP server logs in Claude Code console
+3. Reinstall runtime files: `npx --yes --package @dmsdc-ai/aigentry-devkit aigentry-devkit install --force`
+4. Restart your MCP client process (Claude/Codex/etc.)
+5. Review runtime log: `tail -n 120 ~/.local/lib/mcp-deliberation/runtime.log`
 
 ### MCP `Transport closed` in multi-session use
 
@@ -415,10 +419,10 @@ Language-specific requirements for skills:
 ### Installation Flow
 
 ```
-npx @dmsdc-ai/aigentry-devkit install
+npx --yes --package @dmsdc-ai/aigentry-devkit aigentry-devkit install
   ├─ dispatches to install.sh (macOS/Linux) or install.ps1 (Windows)
   ├─ Check prerequisites (Node.js, npm, optional tools)
-  ├─ Link skills to ~/.claude/skills/
+  ├─ Install skills to ~/.claude/skills/
   ├─ Install HUD to ~/.claude/hud/
   ├─ Deploy MCP server to ~/.local/lib/mcp-deliberation/
   ├─ Register MCP in ~/.claude/.mcp.json

package/bin/aigentry-devkit.js

@@ -15,8 +15,8 @@ function printHelp() {
     "  aigentry-devkit --help",
     "",
     "Examples:",
-    "  npx -y @dmsdc-ai/aigentry-devkit install",
-    "  npx -y @dmsdc-ai/aigentry-devkit install --force",
+    "  npx --yes --package @dmsdc-ai/aigentry-devkit aigentry-devkit install",
+    "  npx --yes --package @dmsdc-ai/aigentry-devkit aigentry-devkit install --force",
   ].join("\n");
   process.stdout.write(`${text}\n`);
 }

package/install.ps1

@@ -94,14 +94,20 @@ if (-not (Test-Path $hudTarget) -or $Force) {
 
 Write-Header "4. MCP Deliberation Server"
 
+if ($Force -and (Test-Path $McpDest)) {
+  Remove-Item -Path $McpDest -Recurse -Force
+}
 New-Item -ItemType Directory -Path $McpDest -Force | Out-Null
-Copy-Item -Path (Join-Path $DevkitDir "mcp-servers\deliberation\index.js") -Destination (Join-Path $McpDest "index.js") -Force
-Copy-Item -Path (Join-Path $DevkitDir "mcp-servers\deliberation\package.json") -Destination (Join-Path $McpDest "package.json") -Force
-Copy-Item -Path (Join-Path $DevkitDir "mcp-servers\deliberation\session-monitor.sh") -Destination (Join-Path $McpDest "session-monitor.sh") -Force
+$mcpSource = Join-Path $DevkitDir "mcp-servers\deliberation"
+Copy-Item -Path (Join-Path $mcpSource "*") -Destination $McpDest -Recurse -Force
 
 Write-Info "Installing dependencies..."
 Push-Location $McpDest
-npm install --silent | Out-Null
+npm install --omit=dev
+if ($LASTEXITCODE -ne 0) {
+  Pop-Location
+  throw "npm install failed in $McpDest"
+}
 Pop-Location
 Write-Info "MCP deliberation server installed at $McpDest"
 
@@ -132,6 +138,48 @@ $cfg.mcpServers | Add-Member -MemberType NoteProperty -Name deliberation -Value
 $cfg | ConvertTo-Json -Depth 8 | Set-Content -Path $mcpConfig -Encoding utf8
 Write-Info "Registered deliberation MCP in $mcpConfig"
 
+if (Get-Command claude -ErrorAction SilentlyContinue) {
+  $claudeScopeSupported = $false
+  try {
+    $claudeAddHelp = claude mcp add --help 2>$null | Out-String
+    if ($claudeAddHelp -match "--scope") {
+      $claudeScopeSupported = $true
+    }
+  } catch {}
+
+  if ($claudeScopeSupported) {
+    try { claude mcp remove --scope local deliberation 2>$null | Out-Null } catch {}
+    try { claude mcp remove --scope user deliberation 2>$null | Out-Null } catch {}
+
+    try {
+      claude mcp add --scope user deliberation -- node (Join-Path $McpDest "index.js") | Out-Null
+      Write-Info "Registered deliberation MCP in Claude Code user scope (~/.claude.json)"
+    } catch {
+      Write-Warn "Claude Code MCP registration failed. Run manually: claude mcp add --scope user deliberation -- node $McpDest\\index.js"
+    }
+  } else {
+    try {
+      claude mcp add deliberation -- node (Join-Path $McpDest "index.js") | Out-Null
+      Write-Info "Registered deliberation MCP in Claude Code"
+    } catch {
+      Write-Warn "Claude Code MCP registration failed (legacy CLI)."
+    }
+  }
+
+  try {
+    $claudeMcpList = claude mcp list 2>$null | Out-String
+    if ($claudeMcpList -match "(?m)^deliberation:") {
+      Write-Info "Claude Code MCP verification passed (deliberation found)"
+    } else {
+      Write-Warn "Claude Code MCP verification failed. Restart Claude and run: claude mcp list"
+    }
+  } catch {
+    Write-Warn "Claude Code MCP verification failed (claude mcp list unavailable)"
+  }
+} else {
+  Write-Warn "Claude CLI not found. Skipping Claude MCP registration."
+}
+
 Write-Header "6. Config Templates"
 
 $settingsDest = Join-Path $ClaudeDir "settings.json"

package/install.sh

@@ -13,6 +13,15 @@ DEVKIT_DIR="$(cd "$(dirname "$0")" && pwd)"
 CLAUDE_DIR="$HOME/.claude"
 MCP_DEST="$HOME/.local/lib/mcp-deliberation"
 PLATFORM="$(uname -s 2>/dev/null || echo unknown)"
+FORCE=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --force|-f)
+      FORCE=1
+      ;;
+  esac
+done
 
 # 색상
 GREEN='\033[0;32m'
@@ -68,17 +77,22 @@ for skill_dir in "$DEVKIT_DIR"/skills/*/; do
   skill_name=$(basename "$skill_dir")
   target="$SKILLS_DEST/$skill_name"
 
-  if [ -L "$target" ]; then
-    rm "$target"
+  if [ -e "$target" ]; then
+    if [ "$FORCE" -eq 1 ]; then
+      rm -rf "$target"
+    else
+      warn "$skill_name already exists (skipping, use --force to overwrite)"
+      continue
+    fi
   fi
 
-  if [ -d "$target" ]; then
-    warn "$skill_name already exists (skipping, use --force to overwrite)"
+  if [ ! -d "$skill_dir" ]; then
+    warn "Skill source missing: $skill_dir"
     continue
   fi
 
-  ln -s "$skill_dir" "$target"
-  info "Linked skill: $skill_name"
+  cp -R "$skill_dir" "$target"
+  info "Installed skill: $skill_name"
 done
 
 # ── HUD / Statusline ──
@@ -87,7 +101,7 @@ header "3. HUD Statusline"
 HUD_DEST="$CLAUDE_DIR/hud"
 mkdir -p "$HUD_DEST"
 
-if [ ! -f "$HUD_DEST/simple-status.sh" ] || [ "${1:-}" = "--force" ]; then
+if [ ! -f "$HUD_DEST/simple-status.sh" ] || [ "$FORCE" -eq 1 ]; then
   cp "$DEVKIT_DIR/hud/simple-status.sh" "$HUD_DEST/simple-status.sh"
   chmod +x "$HUD_DEST/simple-status.sh"
   info "Installed HUD: simple-status.sh"
@@ -98,14 +112,15 @@ fi
 # ── MCP Deliberation Server ──
 header "4. MCP Deliberation Server"
 
+if [ "$FORCE" -eq 1 ] && [ -d "$MCP_DEST" ]; then
+  rm -rf "$MCP_DEST"
+fi
 mkdir -p "$MCP_DEST"
-cp "$DEVKIT_DIR/mcp-servers/deliberation/index.js" "$MCP_DEST/"
-cp "$DEVKIT_DIR/mcp-servers/deliberation/package.json" "$MCP_DEST/"
-cp "$DEVKIT_DIR/mcp-servers/deliberation/session-monitor.sh" "$MCP_DEST/"
+cp -R "$DEVKIT_DIR/mcp-servers/deliberation/." "$MCP_DEST/"
 chmod +x "$MCP_DEST/session-monitor.sh"
 
 info "Installing dependencies..."
-(cd "$MCP_DEST" && npm install --silent 2>/dev/null)
+(cd "$MCP_DEST" && npm install --omit=dev)
 info "MCP deliberation server installed at $MCP_DEST"
 
 # ── MCP 등록 ──
@@ -115,13 +130,18 @@ MCP_CONFIG="$CLAUDE_DIR/.mcp.json"
 
 if [ -f "$MCP_CONFIG" ]; then
   # deliberation 서버가 이미 등록되어 있는지 확인
-  if node -e "const c=JSON.parse(require('fs').readFileSync('$MCP_CONFIG','utf-8'));process.exit(c.mcpServers?.deliberation?0:1)" 2>/dev/null; then
+  if node -e "const fs=require('fs');let c={};try{c=JSON.parse(fs.readFileSync('$MCP_CONFIG','utf-8'));}catch{}process.exit(c.mcpServers?.deliberation?0:1)" 2>/dev/null; then
     info "Deliberation MCP already registered"
   else
     # 기존 설정에 deliberation 추가
     node -e "
       const fs = require('fs');
-      const c = JSON.parse(fs.readFileSync('$MCP_CONFIG', 'utf-8'));
+      let c = {};
+      try {
+        c = JSON.parse(fs.readFileSync('$MCP_CONFIG', 'utf-8'));
+      } catch {
+        c = {};
+      }
       if (!c.mcpServers) c.mcpServers = {};
       c.mcpServers.deliberation = {
         command: 'node',
@@ -146,6 +166,33 @@ MCPEOF
   info "Created $MCP_CONFIG with deliberation MCP"
 fi
 
+# Claude Code CLI 등록 (최신 런타임 경로)
+if command -v claude >/dev/null 2>&1; then
+  if claude mcp add --help 2>/dev/null | grep -q -- '--scope'; then
+    claude mcp remove --scope local deliberation >/dev/null 2>&1 || true
+    claude mcp remove --scope user deliberation >/dev/null 2>&1 || true
+    if claude mcp add --scope user deliberation -- node "$MCP_DEST/index.js" >/dev/null 2>&1; then
+      info "Registered deliberation MCP in Claude Code user scope (~/.claude.json)"
+    else
+      warn "Claude Code MCP registration failed. Run manually: claude mcp add --scope user deliberation -- node $MCP_DEST/index.js"
+    fi
+  else
+    if claude mcp add deliberation -- node "$MCP_DEST/index.js" >/dev/null 2>&1; then
+      info "Registered deliberation MCP in Claude Code"
+    else
+      warn "Claude Code MCP registration failed (legacy CLI)."
+    fi
+  fi
+
+  if claude mcp list 2>/dev/null | grep -q '^deliberation:'; then
+    info "Claude Code MCP verification passed (deliberation found)"
+  else
+    warn "Claude Code MCP verification failed. Restart Claude and run: claude mcp list"
+  fi
+else
+  warn "Claude CLI not found. Skipping Claude MCP registration."
+fi
+
 # ── Config 템플릿 ──
 header "6. Config Templates"
 

package/mcp-servers/deliberation/browser-control-port.js

@@ -0,0 +1,509 @@
+/**
+ * BrowserControlPort — Abstract interface + Chrome DevTools MCP adapter
+ *
+ * Deliberation 합의 스펙:
+ * - 6 메서드: attach, sendTurn, waitTurnResult, health, recover, detach
+ * - Chrome DevTools MCP 1차 구현
+ * - DegradationStateMachine 위임 복구
+ * - MVP: ChatGPT 단일 지원
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DegradationStateMachine, makeResult, ERROR_CODES } from "./degradation-state-machine.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── Selector Config Loader ───
+
+function loadSelectorConfig(provider) {
+  const configPath = join(__dirname, "selectors", `${provider}.json`);
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    return JSON.parse(raw);
+  } catch (err) {
+    return null;
+  }
+}
+
+// ─── BrowserControlPort Interface ───
+
+class BrowserControlPort {
+  /**
+   * Bind to a browser tab for a deliberation session.
+   * @param {string} sessionId
+   * @param {{ url?: string, provider?: string }} targetHint
+   * @returns {Promise<Result>}
+   */
+  async attach(sessionId, targetHint) {
+    throw new Error("attach() not implemented");
+  }
+
+  /**
+   * Send a turn message to the LLM chat input.
+   * @param {string} sessionId
+   * @param {string} turnId
+   * @param {string} text
+   * @returns {Promise<Result>}
+   */
+  async sendTurn(sessionId, turnId, text) {
+    throw new Error("sendTurn() not implemented");
+  }
+
+  /**
+   * Wait for the LLM to produce a response.
+   * @param {string} sessionId
+   * @param {string} turnId
+   * @param {number} timeoutSec
+   * @returns {Promise<Result>}
+   */
+  async waitTurnResult(sessionId, turnId, timeoutSec) {
+    throw new Error("waitTurnResult() not implemented");
+  }
+
+  /**
+   * Check if the browser binding is healthy.
+   * @param {string} sessionId
+   * @returns {Promise<Result>}
+   */
+  async health(sessionId) {
+    throw new Error("health() not implemented");
+  }
+
+  /**
+   * Recover from failure.
+   * @param {string} sessionId
+   * @param {"rebind"|"reload"|"reopen"} mode
+   * @returns {Promise<Result>}
+   */
+  async recover(sessionId, mode) {
+    throw new Error("recover() not implemented");
+  }
+
+  /**
+   * Detach from the browser tab.
+   * @param {string} sessionId
+   * @returns {Promise<Result>}
+   */
+  async detach(sessionId) {
+    throw new Error("detach() not implemented");
+  }
+}
+
+// ─── Chrome DevTools MCP Adapter ───
+
+class DevToolsMcpAdapter extends BrowserControlPort {
+  constructor({ cdpEndpoints = [], autoResend = true } = {}) {
+    super();
+    /** @type {Map<string, { tabId: string, wsUrl: string, provider: string, selectors: object }>} */
+    this.bindings = new Map();
+    this.cdpEndpoints = cdpEndpoints;
+    this.autoResend = autoResend;
+    this._cmdId = 0;
+    /** @type {Map<string, Set<string>>} dedupe: sessionId → Set<turnId> */
+    this.sentTurns = new Map();
+  }
+
+  async attach(sessionId, targetHint = {}) {
+    const provider = targetHint.provider || "chatgpt";
+    const selectorConfig = loadSelectorConfig(provider);
+    if (!selectorConfig) {
+      return makeResult(false, null, {
+        code: "INVALID_SELECTOR_CONFIG",
+        message: `No selector config found for provider: ${provider}`,
+      });
+    }
+
+    // Find matching tab via CDP /json/list
+    const targetUrl = targetHint.url;
+    const domains = selectorConfig.domains || [];
+
+    let foundTab = null;
+    for (const endpoint of this.cdpEndpoints) {
+      try {
+        const resp = await fetch(endpoint, {
+          signal: AbortSignal.timeout(3000),
+          headers: { accept: "application/json" },
+        });
+        const tabs = await resp.json();
+        for (const tab of tabs) {
+          if (tab.type !== "page") continue;
+          const tabUrl = tab.url || "";
+          if (targetUrl && tabUrl.includes(targetUrl)) {
+            foundTab = { ...tab, endpoint };
+            break;
+          }
+          if (domains.some(d => tabUrl.includes(d))) {
+            foundTab = { ...tab, endpoint };
+            break;
+          }
+        }
+        if (foundTab) break;
+      } catch {
+        // endpoint not reachable
+      }
+    }
+
+    if (!foundTab) {
+      return makeResult(false, null, {
+        code: "BIND_FAILED",
+        message: `No matching browser tab found for provider "${provider}" (checked ${this.cdpEndpoints.length} endpoints)`,
+      });
+    }
+
+    this.bindings.set(sessionId, {
+      tabId: foundTab.id,
+      wsUrl: foundTab.webSocketDebuggerUrl,
+      provider,
+      selectors: selectorConfig.selectors,
+      timing: selectorConfig.timing,
+      pageUrl: foundTab.url,
+      title: foundTab.title,
+    });
+
+    return makeResult(true, {
+      provider,
+      tabId: foundTab.id,
+      title: foundTab.title,
+      url: foundTab.url,
+    });
+  }
+
+  async sendTurn(sessionId, turnId, text) {
+    const binding = this.bindings.get(sessionId);
+    if (!binding) {
+      return makeResult(false, null, {
+        code: "BIND_FAILED",
+        message: `No binding for session ${sessionId}. Call attach() first.`,
+      });
+    }
+
+    // Idempotency check
+    if (!this.sentTurns.has(sessionId)) this.sentTurns.set(sessionId, new Set());
+    const sent = this.sentTurns.get(sessionId);
+    if (sent.has(turnId)) {
+      return makeResult(true, { deduplicated: true, turnId });
+    }
+
+    try {
+      // Execute CDP commands to type and send
+      const result = await this._cdpEvaluate(binding, `
+        (function() {
+          const input = document.querySelector('${binding.selectors.inputSelector}');
+          if (!input) return { ok: false, error: 'INPUT_NOT_FOUND' };
+          input.focus();
+          input.textContent = ${JSON.stringify(text)};
+          input.dispatchEvent(new Event('input', { bubbles: true }));
+          return { ok: true };
+        })()
+      `);
+
+      if (!result.ok) {
+        return makeResult(false, null, {
+          code: "DOM_CHANGED",
+          message: `Input selector not found: ${binding.selectors.inputSelector}`,
+        });
+      }
+
+      // Small delay then click send
+      await new Promise(r => setTimeout(r, binding.timing?.sendDelayMs || 200));
+
+      const sendResult = await this._cdpEvaluate(binding, `
+        (function() {
+          const btn = document.querySelector('${binding.selectors.sendButton}');
+          if (!btn) return { ok: false, error: 'SEND_BUTTON_NOT_FOUND' };
+          btn.click();
+          return { ok: true };
+        })()
+      `);
+
+      if (!sendResult.ok) {
+        return makeResult(false, null, {
+          code: "SEND_FAILED",
+          message: `Send button not found: ${binding.selectors.sendButton}`,
+        });
+      }
+
+      sent.add(turnId);
+      return makeResult(true, { turnId, sent: true });
+    } catch (err) {
+      return this._classifyError(err);
+    }
+  }
+
+  async waitTurnResult(sessionId, turnId, timeoutSec = 45) {
+    const binding = this.bindings.get(sessionId);
+    if (!binding) {
+      return makeResult(false, null, {
+        code: "BIND_FAILED",
+        message: `No binding for session ${sessionId}`,
+      });
+    }
+
+    const timeoutMs = timeoutSec * 1000;
+    const pollInterval = binding.timing?.pollIntervalMs || 500;
+    const startTime = Date.now();
+
+    try {
+      while (Date.now() - startTime < timeoutMs) {
+        // Check if streaming is complete
+        const status = await this._cdpEvaluate(binding, `
+          (function() {
+            const streaming = document.querySelector('${binding.selectors.streamingIndicator}');
+            if (streaming) return { streaming: true };
+            const responses = document.querySelectorAll('${binding.selectors.responseContainer}');
+            if (responses.length === 0) return { streaming: true };
+            const last = responses[responses.length - 1];
+            const content = last.querySelector('${binding.selectors.responseSelector}');
+            return {
+              streaming: false,
+              text: content ? content.textContent : last.textContent,
+            };
+          })()
+        `);
+
+        if (status.data && !status.data.streaming && status.data.text) {
+          return makeResult(true, {
+            turnId,
+            response: status.data.text.trim(),
+            elapsedMs: Date.now() - startTime,
+          });
+        }
+
+        await new Promise(r => setTimeout(r, pollInterval));
+      }
+
+      return makeResult(false, null, {
+        code: "TIMEOUT",
+        message: `Response not received within ${timeoutSec}s`,
+      });
+    } catch (err) {
+      return this._classifyError(err);
+    }
+  }
+
+  async health(sessionId) {
+    const binding = this.bindings.get(sessionId);
+    if (!binding) {
+      return makeResult(true, { bound: false, sessionId });
+    }
+
+    try {
+      const result = await this._cdpEvaluate(binding, "document.readyState");
+      return makeResult(true, {
+        bound: true,
+        sessionId,
+        provider: binding.provider,
+        pageUrl: binding.pageUrl,
+        readyState: result.data,
+      });
+    } catch (err) {
+      return makeResult(false, null, {
+        code: "TAB_CLOSED",
+        message: `Health check failed: ${err.message}`,
+      });
+    }
+  }
+
+  async recover(sessionId, mode = "rebind") {
+    const binding = this.bindings.get(sessionId);
+
+    switch (mode) {
+      case "rebind": {
+        // Re-scan for the tab
+        if (!binding) return makeResult(false, null, { code: "BIND_FAILED", message: "No previous binding to rebind" });
+        return this.attach(sessionId, { provider: binding.provider });
+      }
+      case "reload": {
+        if (!binding) return makeResult(false, null, { code: "TAB_CLOSED", message: "No binding to reload" });
+        try {
+          await this._cdpCommand(binding, "Page.reload", {});
+          await new Promise(r => setTimeout(r, 3000)); // wait for reload
+          return makeResult(true, { mode: "reload", sessionId });
+        } catch (err) {
+          return this._classifyError(err);
+        }
+      }
+      case "reopen": {
+        // Detach old binding, try re-attach
+        this.bindings.delete(sessionId);
+        const provider = binding?.provider || "chatgpt";
+        return this.attach(sessionId, { provider });
+      }
+      default:
+        return makeResult(false, null, { code: "SEND_FAILED", message: `Unknown recover mode: ${mode}` });
+    }
+  }
+
+  async detach(sessionId) {
+    this.bindings.delete(sessionId);
+    this.sentTurns.delete(sessionId);
+    return makeResult(true, { sessionId, detached: true });
+  }
+
+  // ─── CDP Helpers ───
+
+  async _cdpEvaluate(binding, expression) {
+    return this._cdpCommand(binding, "Runtime.evaluate", {
+      expression,
+      returnByValue: true,
+    }).then(result => {
+      const val = result?.result?.value;
+      if (val && typeof val === "object" && val.ok === false) {
+        return makeResult(false, null, { code: "DOM_CHANGED", message: val.error || "DOM evaluation failed" });
+      }
+      return makeResult(true, val);
+    });
+  }
+
+  async _cdpCommand(binding, method, params = {}) {
+    if (!binding.wsUrl) {
+      throw Object.assign(new Error("No WebSocket URL for CDP"), { code: "MCP_CHANNEL_CLOSED" });
+    }
+
+    // Use dynamic import for WebSocket (Node 18+ has it globally, or ws package)
+    const ws = await this._connectWs(binding.wsUrl);
+    const id = ++this._cmdId;
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        ws.close();
+        reject(Object.assign(new Error("CDP command timeout"), { code: "TIMEOUT" }));
+      }, 10000);
+
+      ws.onmessage = (event) => {
+        try {
+          const data = JSON.parse(typeof event === "string" ? event : event.data);
+          if (data.id === id) {
+            clearTimeout(timeout);
+            ws.close();
+            if (data.error) {
+              reject(Object.assign(new Error(data.error.message), { code: "SEND_FAILED" }));
+            } else {
+              resolve(data.result);
+            }
+          }
+        } catch { /* ignore parse errors */ }
+      };
+
+      ws.onerror = (err) => {
+        clearTimeout(timeout);
+        ws.close();
+        reject(Object.assign(new Error(err.message || "WebSocket error"), { code: "NETWORK_DISCONNECTED" }));
+      };
+
+      ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  async _connectWs(url) {
+    // Node.js 22+ has global WebSocket; fallback to ws package
+    if (typeof globalThis.WebSocket !== "undefined") {
+      const ws = new globalThis.WebSocket(url);
+      await new Promise((resolve, reject) => {
+        ws.onopen = resolve;
+        ws.onerror = reject;
+      });
+      return ws;
+    }
+
+    // Try dynamic import of ws
+    try {
+      const { default: WS } = await import("ws");
+      const ws = new WS(url);
+      await new Promise((resolve, reject) => {
+        ws.on("open", resolve);
+        ws.on("error", reject);
+      });
+      return ws;
+    } catch {
+      throw Object.assign(new Error("WebSocket not available. Install 'ws' package or use Node 22+."), { code: "MCP_CHANNEL_CLOSED" });
+    }
+  }
+
+  _classifyError(err) {
+    const code = err.code || "UNKNOWN";
+    if (ERROR_CODES[code]) {
+      return makeResult(false, null, { code, message: err.message });
+    }
+    // Classify by message patterns
+    if (/ECONNREFUSED|ENOTFOUND|fetch failed/i.test(err.message)) {
+      return makeResult(false, null, { code: "NETWORK_DISCONNECTED", message: err.message });
+    }
+    if (/WebSocket|ws:/i.test(err.message)) {
+      return makeResult(false, null, { code: "MCP_CHANNEL_CLOSED", message: err.message });
+    }
+    if (/target.*closed|page.*crashed/i.test(err.message)) {
+      return makeResult(false, null, { code: "BROWSER_CRASHED", message: err.message });
+    }
+    return makeResult(false, null, { code: "UNKNOWN", message: err.message });
+  }
+}
+
+// ─── Orchestrated Port (with DegradationStateMachine) ───
+
+class OrchestratedBrowserPort {
+  constructor({ cdpEndpoints = [], autoResend = true, skipEnabled = false } = {}) {
+    this.adapter = new DevToolsMcpAdapter({ cdpEndpoints, autoResend });
+    this.machines = new Map(); // sessionId → DegradationStateMachine
+  }
+
+  _getOrCreateMachine(sessionId) {
+    if (!this.machines.has(sessionId)) {
+      this.machines.set(sessionId, new DegradationStateMachine({
+        onRetry: () => makeResult(false, null, { code: "SEND_FAILED", message: "retry pass-through" }),
+        onRebind: () => this.adapter.recover(sessionId, "rebind"),
+        onReload: () => this.adapter.recover(sessionId, "reload"),
+        onFallback: (lastResult) => {
+          return makeResult(false, null, {
+            code: "TIMEOUT",
+            message: "All degradation stages exhausted. Falling back to clipboard mode.",
+          });
+        },
+      }));
+    }
+    return this.machines.get(sessionId);
+  }
+
+  async attach(sessionId, targetHint) {
+    return this.adapter.attach(sessionId, targetHint);
+  }
+
+  /**
+   * Send a turn with full degradation pipeline.
+   */
+  async sendTurnWithDegradation(sessionId, turnId, text) {
+    const machine = this._getOrCreateMachine(sessionId);
+    return machine.execute(() => this.adapter.sendTurn(sessionId, turnId, text));
+  }
+
+  async waitTurnResult(sessionId, turnId, timeoutSec) {
+    return this.adapter.waitTurnResult(sessionId, turnId, timeoutSec);
+  }
+
+  async health(sessionId) {
+    return this.adapter.health(sessionId);
+  }
+
+  async recover(sessionId, mode) {
+    return this.adapter.recover(sessionId, mode);
+  }
+
+  async detach(sessionId) {
+    this.machines.delete(sessionId);
+    return this.adapter.detach(sessionId);
+  }
+
+  getDegradationState(sessionId) {
+    const machine = this.machines.get(sessionId);
+    return machine ? machine.toJSON() : null;
+  }
+}
+
+export {
+  BrowserControlPort,
+  DevToolsMcpAdapter,
+  OrchestratedBrowserPort,
+  loadSelectorConfig,
+};

package/mcp-servers/deliberation/degradation-state-machine.js

@@ -0,0 +1,206 @@
+/**
+ * DegradationStateMachine — 4-stage graceful degradation for BrowserControlPort
+ *
+ * States: HEALTHY → RETRYING → REBINDING → RELOADING → FALLBACK → FAILED
+ * Time budget (60s SLO): S1(12s) + S2(8s) + S3(18s) + S4(22s spare)
+ */
+
+const STATES = {
+  HEALTHY: "HEALTHY",
+  RETRYING: "RETRYING",
+  REBINDING: "REBINDING",
+  RELOADING: "RELOADING",
+  FALLBACK: "FALLBACK",
+  FAILED: "FAILED",
+};
+
+const STAGE_BUDGETS = {
+  RETRYING: { maxAttempts: 2, backoffMs: [2000, 4000], budgetMs: 12000 },
+  REBINDING: { maxAttempts: 1, budgetMs: 8000 },
+  RELOADING: { maxAttempts: 1, budgetMs: 18000 },
+  FALLBACK: { budgetMs: 22000 },
+};
+
+const ERROR_CODES = {
+  BIND_FAILED: { category: "transient", domain: "browser", retryable: true },
+  SEND_FAILED: { category: "transient", domain: "transport", retryable: true },
+  TIMEOUT: { category: "transient", domain: "transport", retryable: true },
+  DOM_CHANGED: { category: "transient", domain: "dom", retryable: true },
+  SESSION_EXPIRED: { category: "permanent", domain: "session", retryable: false },
+  TAB_CLOSED: { category: "transient", domain: "browser", retryable: true },
+  NETWORK_DISCONNECTED: { category: "transient", domain: "transport", retryable: true },
+  MCP_CHANNEL_CLOSED: { category: "transient", domain: "transport", retryable: true },
+  BROWSER_CRASHED: { category: "transient", domain: "browser", retryable: true },
+  INVALID_SELECTOR_CONFIG: { category: "permanent", domain: "dom", retryable: false },
+};
+
+function makeResult(ok, data, error) {
+  if (ok) return { ok: true, data: data ?? null };
+  const meta = ERROR_CODES[error?.code] || ERROR_CODES.TIMEOUT;
+  return {
+    ok: false,
+    error: {
+      code: error?.code || "UNKNOWN",
+      category: meta.category,
+      domain: meta.domain,
+      message: error?.message || "Unknown error",
+      retryable: meta.retryable,
+    },
+  };
+}
+
+class DegradationStateMachine {
+  constructor({ onRetry, onRebind, onReload, onFallback, skipEnabled = false } = {}) {
+    this.state = STATES.HEALTHY;
+    this.stageAttempts = { RETRYING: 0, REBINDING: 0, RELOADING: 0 };
+    this.startTime = null;
+    this.lastError = null;
+    this.skipEnabled = skipEnabled;
+
+    // Callbacks for each stage action
+    this._onRetry = onRetry || (() => makeResult(false, null, { code: "SEND_FAILED", message: "retry not implemented" }));
+    this._onRebind = onRebind || (() => makeResult(false, null, { code: "DOM_CHANGED", message: "rebind not implemented" }));
+    this._onReload = onReload || (() => makeResult(false, null, { code: "TAB_CLOSED", message: "reload not implemented" }));
+    this._onFallback = onFallback || (() => makeResult(false, null, { code: "TIMEOUT", message: "fallback not implemented" }));
+  }
+
+  reset() {
+    this.state = STATES.HEALTHY;
+    this.stageAttempts = { RETRYING: 0, REBINDING: 0, RELOADING: 0 };
+    this.startTime = null;
+    this.lastError = null;
+  }
+
+  get elapsedMs() {
+    return this.startTime ? Date.now() - this.startTime : 0;
+  }
+
+  get totalBudgetMs() {
+    return 60000;
+  }
+
+  get isTerminal() {
+    return this.state === STATES.FAILED || this.state === STATES.FALLBACK;
+  }
+
+  /**
+   * Execute a turn with full degradation pipeline.
+   * @param {Function} primaryAction - async () => Result. The main action to attempt.
+   * @returns {Result} Final result after all degradation attempts.
+   */
+  async execute(primaryAction) {
+    this.startTime = Date.now();
+    this.state = STATES.HEALTHY;
+    this.stageAttempts = { RETRYING: 0, REBINDING: 0, RELOADING: 0 };
+
+    // Stage 0: Primary attempt
+    const primaryResult = await this._timed(primaryAction);
+    if (primaryResult.ok) return primaryResult;
+    this.lastError = primaryResult.error;
+
+    // Check if permanent error — skip to FAILED
+    if (primaryResult.error && !primaryResult.error.retryable) {
+      this.state = STATES.FAILED;
+      return primaryResult;
+    }
+
+    // Stage 1: Retry with backoff
+    this.state = STATES.RETRYING;
+    const retryResult = await this._stageRetry(primaryAction);
+    if (retryResult.ok) { this.state = STATES.HEALTHY; return retryResult; }
+    if (this._budgetExceeded()) return this._toFallback(retryResult);
+
+    // Stage 2: Rebind (DOM re-scan)
+    this.state = STATES.REBINDING;
+    const rebindResult = await this._stageRebind();
+    if (rebindResult.ok) {
+      // Rebind succeeded, retry primary once more
+      const afterRebind = await this._timed(primaryAction);
+      if (afterRebind.ok) { this.state = STATES.HEALTHY; return afterRebind; }
+    }
+    if (this._budgetExceeded()) return this._toFallback(rebindResult);
+
+    // Stage 3: Reload/Reopen
+    this.state = STATES.RELOADING;
+    const reloadResult = await this._stageReload();
+    if (reloadResult.ok) {
+      // After reload, retry primary once (auto-resend with turn_id idempotency)
+      const afterReload = await this._timed(primaryAction);
+      if (afterReload.ok) { this.state = STATES.HEALTHY; return afterReload; }
+    }
+    if (this._budgetExceeded()) return this._toFallback(reloadResult);
+
+    // Stage 4: Fallback
+    return this._toFallback(reloadResult);
+  }
+
+  async _stageRetry(action) {
+    const budget = STAGE_BUDGETS.RETRYING;
+    let lastResult = null;
+    for (let i = 0; i < budget.maxAttempts; i++) {
+      if (this._budgetExceeded()) break;
+      const delay = budget.backoffMs[i] || budget.backoffMs[budget.backoffMs.length - 1];
+      await this._sleep(delay);
+      this.stageAttempts.RETRYING++;
+      lastResult = await this._timed(action);
+      if (lastResult.ok) return lastResult;
+      this.lastError = lastResult.error;
+    }
+    return lastResult || makeResult(false, null, { code: "TIMEOUT", message: "retry exhausted" });
+  }
+
+  async _stageRebind() {
+    if (this._budgetExceeded()) return makeResult(false, null, { code: "TIMEOUT", message: "budget exceeded before rebind" });
+    this.stageAttempts.REBINDING++;
+    return this._timed(this._onRebind);
+  }
+
+  async _stageReload() {
+    if (this._budgetExceeded()) return makeResult(false, null, { code: "TIMEOUT", message: "budget exceeded before reload" });
+    this.stageAttempts.RELOADING++;
+    return this._timed(this._onReload);
+  }
+
+  async _toFallback(lastResult) {
+    this.state = STATES.FALLBACK;
+    const fallbackResult = await this._onFallback(lastResult);
+    if (!fallbackResult?.ok && !this.skipEnabled) {
+      this.state = STATES.FAILED;
+    }
+    return fallbackResult || makeResult(false, null, {
+      code: "TIMEOUT",
+      message: `All degradation stages exhausted (elapsed: ${this.elapsedMs}ms)`,
+    });
+  }
+
+  _budgetExceeded() {
+    return this.elapsedMs >= this.totalBudgetMs;
+  }
+
+  async _timed(fn) {
+    try {
+      return await fn();
+    } catch (err) {
+      return makeResult(false, null, {
+        code: err.code || "UNKNOWN",
+        message: err.message || String(err),
+      });
+    }
+  }
+
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  toJSON() {
+    return {
+      state: this.state,
+      elapsedMs: this.elapsedMs,
+      stageAttempts: { ...this.stageAttempts },
+      lastError: this.lastError,
+      skipEnabled: this.skipEnabled,
+    };
+  }
+}
+
+export { DegradationStateMachine, STATES, STAGE_BUDGETS, ERROR_CODES, makeResult };

package/mcp-servers/deliberation/selectors/chatgpt.json

@@ -0,0 +1,20 @@
+{
+  "provider": "chatgpt",
+  "version": "1.0.0",
+  "domains": ["chat.openai.com", "chatgpt.com"],
+  "selectors": {
+    "inputSelector": "#prompt-textarea",
+    "sendButton": "button[data-testid='send-button']",
+    "responseSelector": ".markdown.prose",
+    "responseContainer": "[data-message-author-role='assistant']",
+    "streamingIndicator": ".result-streaming",
+    "conversationList": "nav[aria-label='Chat history']"
+  },
+  "timing": {
+    "inputDelayMs": 100,
+    "sendDelayMs": 200,
+    "pollIntervalMs": 500,
+    "streamingTimeoutMs": 45000
+  },
+  "notes": "ChatGPT DOM selectors - update version when selectors change"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-devkit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Cross-platform installer and tooling bundle for aigentry-devkit",
   "license": "MIT",
   "repository": {
@@ -28,9 +28,7 @@
     "hud/**",
     "install.sh",
     "install.ps1",
-    "mcp-servers/deliberation/index.js",
-    "mcp-servers/deliberation/package.json",
-    "mcp-servers/deliberation/session-monitor.sh",
+    "mcp-servers/deliberation/**",
     "skills/clipboard-image/**",
     "skills/deliberation/**",
     "skills/deliberation-executor/**",