@dmsdc-ai/aigentry-deliberation 0.0.39 → 0.0.41

package/examples/browser-automation.md

@@ -0,0 +1,120 @@
+# Browser Automation — Include ChatGPT / Gemini via CDP
+
+Use `deliberation_browser_llm_tabs` and `deliberation_browser_auto_turn` to pull browser-based
+LLMs (ChatGPT, Gemini, Claude.ai) into a deliberation session without manual copy-paste.
+
+---
+
+## Prerequisites
+
+- Chrome / Chromium launched with remote debugging enabled:
+  ```bash
+  google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile
+  ```
+- Target LLM tabs open and logged in (e.g., chatgpt.com, gemini.google.com)
+
+---
+
+## Step 1 — Discover Open Browser Tabs
+
+```json
+// Tool: deliberation_browser_llm_tabs
+{}
+```
+
+**Response:**
+```json
+{
+  "tabs": [
+    { "id": "tab-001", "url": "https://chatgpt.com", "title": "ChatGPT", "provider": "chatgpt" },
+    { "id": "tab-002", "url": "https://gemini.google.com", "title": "Gemini", "provider": "gemini" }
+  ]
+}
+```
+
+---
+
+## Step 2 — Confirm Speakers Including Browser Tabs
+
+```json
+// Tool: deliberation_confirm_speakers
+{
+  "speaker_ids": ["claude-opus", "tab-001", "tab-002"]
+}
+```
+
+---
+
+## Step 3 — Start the Session
+
+```json
+// Tool: deliberation_start
+{
+  "topic": "Best caching strategy for a high-traffic e-commerce product page",
+  "context": "~50k requests/min, product data changes every 15 minutes, personalization per user.",
+  "max_turns": 6
+}
+```
+
+---
+
+## Step 4 — Route a Turn to a Browser Tab
+
+```json
+// Tool: deliberation_browser_auto_turn
+{
+  "deliberation_id": "delib-b7c8d9",
+  "tab_id": "tab-001",
+  "prompt": "Given the context above, what caching strategy would you recommend and why?"
+}
+```
+
+**What happens:** The server injects the prompt into the ChatGPT tab via CDP, waits for the
+response to stream to completion, then captures the text and stores it as a deliberation turn.
+
+**Response:**
+```json
+{
+  "speaker_id": "tab-001",
+  "content": "I recommend a two-layer cache: CDN edge cache (TTL 60s) for the static product shell, plus a Redis read-through cache (TTL 900s) for product data. For personalization, serve a generic cached page and hydrate user-specific sections client-side via a lightweight /api/personalize call.",
+  "transport": "browser_auto"
+}
+```
+
+---
+
+## Step 5 — Run All Remaining Turns Automatically
+
+```json
+// Tool: deliberation_run_until_blocked
+{
+  "deliberation_id": "delib-b7c8d9"
+}
+```
+
+The server routes each pending turn to its assigned transport (`browser_auto` for tabs,
+`cli_respond` for CLI speakers) and blocks only when manual input is required.
+
+---
+
+## Step 6 — Synthesize
+
+```json
+// Tool: deliberation_synthesize
+{
+  "deliberation_id": "delib-b7c8d9"
+}
+```
+
+**Response:**
+```json
+{
+  "verdict": "Two-layer cache: CDN (60s TTL) + Redis (900s TTL) with client-side personalization hydration",
+  "confidence": 0.88,
+  "actionable_tasks": [
+    { "id": 1, "task": "Configure CDN cache rules with 60s TTL and stale-while-revalidate", "priority": "high" },
+    { "id": 2, "task": "Add Redis read-through cache for product data with 15-min TTL", "priority": "high" },
+    { "id": 3, "task": "Build /api/personalize endpoint for client-side hydration", "priority": "medium" }
+  ]
+}
+```

package/examples/code-review.md

@@ -0,0 +1,78 @@
+# Multi-AI Code Review
+
+Use `deliberation_request_review` to route a code snippet to multiple AI speakers for parallel review.
+
+---
+
+## Scenario
+
+You have a new authentication middleware and want independent review from Claude and Gemini before merging.
+
+---
+
+## Step 1 — Start a Review Session
+
+```json
+// Tool: deliberation_request_review
+{
+  "topic": "Security review: JWT authentication middleware",
+  "code": "function authMiddleware(req, res, next) {\n  const token = req.headers['authorization']?.split(' ')[1];\n  if (!token) return res.status(401).json({ error: 'No token' });\n  try {\n    const payload = jwt.verify(token, process.env.JWT_SECRET);\n    req.user = payload;\n    next();\n  } catch (err) {\n    res.status(403).json({ error: 'Invalid token' });\n  }\n}",
+  "language": "javascript",
+  "focus": ["security", "error handling", "edge cases"]
+}
+```
+
+**Response:**
+```json
+{
+  "deliberation_id": "delib-review-x9z1",
+  "status": "active",
+  "assigned_speakers": ["claude-opus", "gemini-pro"]
+}
+```
+
+---
+
+## Step 2 — Collect Reviews
+
+```json
+// Tool: deliberation_respond  (speaker: claude-opus)
+{
+  "deliberation_id": "delib-review-x9z1",
+  "speaker_id": "claude-opus",
+  "content": "Issues found:\n1. JWT_SECRET missing guard — if env var is undefined, jwt.verify accepts any token signed with 'undefined'.\n2. No token expiry enforcement beyond jwt.verify defaults.\n3. Leaking error type in 403 response could aid attackers.\nRecommend: validate JWT_SECRET at startup, use a dedicated error logger, return generic 403 message."
+}
+```
+
+```json
+// Tool: deliberation_respond  (speaker: gemini-pro)
+{
+  "deliberation_id": "delib-review-x9z1",
+  "speaker_id": "gemini-pro",
+  "content": "Concur on the JWT_SECRET risk. Additional concern: no algorithm pinning — `jwt.verify` without `algorithms` option is vulnerable to algorithm confusion (e.g., HS256 vs RS256 swap). Add `{ algorithms: ['HS256'] }` as third argument."
+}
+```
+
+---
+
+## Step 3 — Synthesize Review Findings
+
+```json
+// Tool: deliberation_synthesize
+{
+  "deliberation_id": "delib-review-x9z1"
+}
+```
+
+**Response:**
+```json
+{
+  "verdict": "Block merge — 2 critical security issues",
+  "confidence": 0.95,
+  "actionable_tasks": [
+    { "id": 1, "task": "Guard JWT_SECRET at startup with process.exit on missing value", "priority": "high" },
+    { "id": 2, "task": "Pin algorithm: jwt.verify(token, secret, { algorithms: ['HS256'] })", "priority": "high" },
+    { "id": 3, "task": "Replace detailed error message in 403 with generic 'Forbidden'", "priority": "medium" }
+  ]
+}
+```

package/examples/structured-synthesis.md

@@ -0,0 +1,96 @@
+# Structured Synthesis & ExecutionContractV2
+
+`deliberation_synthesize` returns an `ExecutionContractV2` — a machine-readable handoff
+that downstream automation (brain inbox, CI pipelines, executor agents) can consume directly.
+
+---
+
+## Triggering Synthesis
+
+```json
+// Tool: deliberation_synthesize
+{
+  "deliberation_id": "delib-a1b2c3"
+}
+```
+
+---
+
+## Full ExecutionContractV2 Schema
+
+```json
+{
+  "schema_version": 2,
+  "source_session_id": "aigentry-orchestrator-claude",
+  "deliberation_id": "delib-a1b2c3",
+  "summary": "GraphQL chosen over REST for the new API due to multi-client flexibility and nested data requirements.",
+  "decisions": [
+    "Use GraphQL with Apollo Server",
+    "Schema-first design with code generation",
+    "Maintain REST shim for legacy mobile clients during 90-day transition"
+  ],
+  "actionable_tasks": [
+    {
+      "id": 1,
+      "task": "Set up Apollo Server with schema-first design",
+      "priority": "high",
+      "files": ["src/server.js", "src/schema/index.graphql"]
+    },
+    {
+      "id": 2,
+      "task": "Define GraphQL types for User, Order, and Product entities",
+      "priority": "high",
+      "files": ["src/schema/types.graphql"]
+    },
+    {
+      "id": 3,
+      "task": "Add REST compatibility shim for /api/v1 routes",
+      "priority": "medium",
+      "files": ["src/routes/v1.js"]
+    }
+  ],
+  "experiment_outcome": {
+    "verdict": "keep",
+    "confidence": 0.82
+  },
+  "generated_from": "deliberation_synthesize"
+}
+```
+
+---
+
+## Brain Inbox Handoff
+
+The contract is automatically written to:
+
+```
+~/.aigentry/inbox/handoff-{deliberation_id}.json
+```
+
+An executor agent (or `inbox-watcher.mjs`) picks it up and starts implementation:
+
+```bash
+node inbox-watcher.mjs
+# => Detected handoff: delib-a1b2c3
+# => Dispatching 3 tasks to executor...
+```
+
+---
+
+## Consuming the Contract in Code
+
+```javascript
+import { readFileSync } from 'fs';
+import { homedir } from 'os';
+import path from 'path';
+
+const contract = JSON.parse(
+  readFileSync(path.join(homedir(), '.aigentry/inbox/handoff-delib-a1b2c3.json'), 'utf8')
+);
+
+for (const task of contract.actionable_tasks) {
+  if (task.priority === 'high') {
+    console.log(`[HIGH] ${task.task} → files: ${task.files.join(', ')}`);
+  }
+}
+```