agentclick 0.1.0 → 0.2.0

package/README.md

@@ -1,145 +1,98 @@
 # AgentClick
 
-**Rich web UI for AI agent interactions — click to edit, human-in-the-loop, preference learning.**
+AI agents fail silently and take irreversible actions. AgentClick puts a human review step between your agent and the world.
 
-[![GitHub stars](https://img.shields.io/github/stars/agentlayer-io/AgentClick?style=flat-square)](https://github.com/agentlayer-io/AgentClick/stargazers)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/agentlayer-io/AgentClick/pulls)
+[![npm version](https://img.shields.io/npm/v/agentclick)](https://www.npmjs.com/package/agentclick)
+[![license](https://img.shields.io/npm/l/agentclick)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/agentclick)](https://www.npmjs.com/package/agentclick)
 
 ---
 
-## The Problem
+## Why AgentClick
 
-Every OpenClaw user interacts with their agent through text chat (WhatsApp / Telegram). Text is a degraded interface:
-
-- You can't click a paragraph and say "rewrite this"
-- You can't drag steps to reorder them
-- Every correction requires typing out instructions again
-- The agent never remembers your preferences
-
-## The Solution
-
-When your agent finishes a task that needs your input, it opens a browser page — a purpose-built interaction UI. You click, choose, drag. No typing.
-
-```
-Agent finishes email draft
-  → Browser opens automatically
-  → You click paragraph → choose: Delete / Rewrite / Keep
-  → You confirm
-  → Agent continues, remembers your choices for next time
-```
-
-Every interaction teaches the agent your preferences. The more you use it, the less you need to explain.
-
----
-
-## Current Status
-
-This project is already in a working prototype stage and supports multiple review flows end-to-end.
-
-Implemented:
-
-- Email review UI (legacy single-column + v2 inbox + draft layout)
-- Action approval UI (approve/reject + note)
-- Code/shell command review UI
-- Session history homepage with recent sessions
-- SQLite session persistence (`~/.openclaw/clawui-sessions.db`)
-- Long-poll wait endpoint for agent integration (`/api/sessions/:id/wait`)
-- Preference learning from paragraph deletions (writes rules to `MEMORY.md`)
-- Keyboard shortcuts (`Cmd/Ctrl+Enter` submit, `Escape` handling)
-- Browser auto-open on session creation
+- **Not just approve/deny** -- edit the email subject, change the command, modify the payload before it sends.
+- **Preference learning** -- delete a paragraph and tell AgentClick why. It writes the rule to disk so your agent never makes the same mistake again.
+- **Framework-agnostic** -- works with OpenAI, Anthropic, LangChain, or any HTTP-capable agent. Just POST and long-poll.
 
 ---
 
 ## Quick Start
 
-```bash
-git clone https://github.com/agentlayer-io/AgentClick.git
-cd AgentClick
-npm install
-npm run dev        # dev mode: API on 3001, Vite UI on 5173
-```
-
-## Install (Global CLI)
-
 ```bash
 npm install -g agentclick
 agentclick
 ```
 
-This starts the AgentClick server on `http://localhost:3001` and serves the built web UI on the same port.
-
-Optional server config (defaults shown in `.env.example`):
+Then test it with a mock session:
 
 ```bash
-PORT=3001
-OPENCLAW_WEBHOOK=http://localhost:18789/hooks/agent
+curl -X POST http://localhost:3001/api/review \
+  -H "Content-Type: application/json" \
+  -d '{"type":"code_review","sessionKey":"test","payload":{"command":"rm -rf /tmp/old-cache","cwd":"/home/user","explanation":"Clean up stale cache directory","risk":"medium"}}'
 ```
 
-Create a local `.env` in the project root to override these values during development (server auto-loads it via `dotenv`).
+A browser tab opens automatically. Review, approve or reject, and close the tab.
 
-Production-style local run (single port after build):
+---
 
-```bash
-npm run build
-npm start          # serves API + built web UI on localhost:3001
-```
+## How It Works
 
-Deployment notes (reverse proxy, Docker/OpenClaw host mapping, env vars):
+1. **Agent POSTs structured data** to `http://localhost:3001/api/review` with a session key.
+2. **User reviews, edits, and approves** in the browser -- paragraph-level delete/rewrite for emails, approve/reject for commands and actions.
+3. **Agent receives the result** via long-poll (`GET /api/sessions/:id/wait`) and continues execution.
 
-- See `docs/deployment.md`
+No WebSockets. No framework plugins. One HTTP endpoint in, one HTTP endpoint out.
 
-Copy the skill to your OpenClaw workspace:
+---
 
-```bash
-cp -r skills/clawui-email ~/.openclaw/skills/
-```
+## Comparison
 
-Restart OpenClaw. Ask it to write an email — the review page will open automatically.
+| Feature | AgentClick | AgentGate | LangGraph interrupt() | Vercel AI SDK |
+|---|---|---|---|---|
+| Pre-built review UI | Yes | No | No | No |
+| Edit before approve | Yes | No | No | No |
+| Preference learning | Yes | No | No | No |
+| Framework-agnostic | Yes | Yes | LangGraph only | Vercel only |
+| Self-hosted | Yes | Yes | Yes | Cloud |
 
 ---
 
-## Project Structure
+## Session Types
 
-```
-AgentClick/
-├── packages/
-│   ├── server/          # Node.js + Express — receives agent data, handles callbacks
-│   └── web/             # React + Vite + Tailwind — the interaction UI
-├── skills/
-│   └── clawui-email/
-│       └── SKILL.md     # OpenClaw skill definition
-└── docs/
-    └── research.md      # Market & technical research notes
-```
+- **email_review** -- two-column inbox and draft editor. Users can delete paragraphs with reasons, request rewrites, toggle intent suggestions, and confirm or regenerate.
+- **code_review** -- displays the shell command, working directory, affected files as a collapsible tree, and risk level. Approve or reject with an optional note.
+- **action_approval** -- generic high-risk action gate. Shows action description, detail, and risk badge. Approve or reject with an optional note.
 
 ---
 
-## Roadmap
+## API
 
-- [x] **M0** — Email draft review (click to delete/rewrite paragraphs)
-- [x] **M1** — Preference learning (auto-save rules to MEMORY.md)
-- [x] **M2 (partial)** — Agent integration loop (`/review` create session + `/wait` long-poll + callback)
-- [x] **Next** — Unified serving (single port; no separate Vite port in production)
-- [x] **Next** — Production serve polish (deployment docs / environment examples)
-- [ ] **Next** — npm global package (`agentclick`)
-- [ ] **Next** — Remote mode UX + link delivery polish
-- [ ] **Later** — Agent task visualization (Mission Control view)
-- [ ] **Later** — Multi-framework support (beyond OpenClaw)
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/api/review` | Agent creates a review session. Returns `{ sessionId, url }`. Browser opens automatically. |
+| GET | `/api/sessions/:id` | Fetch session data (payload, status, result). |
+| GET | `/api/sessions/:id/wait` | Long-poll. Blocks up to 5 minutes until the user completes the review. |
+| POST | `/api/sessions/:id/complete` | UI submits the user's decision. Triggers preference learning and agent callback. |
 
 ---
 
-## Why Not ClawX?
+## Development
 
-[ClawX](https://github.com/ValueCell-ai/ClawX) is a desktop app for *managing* OpenClaw (installing skills, configuring channels, running the gateway). AgentClick is for *working with* your agent — reviewing its output, making decisions, teaching it your preferences. They're complementary.
-
----
+```bash
+git clone https://github.com/agentlayer-io/AgentClick.git
+cd AgentClick
+npm install
+npm run dev
+```
 
-## Contributing
+Server runs on `http://localhost:3001`, UI on `http://localhost:5173`.
 
-This is an early-stage open source project. All contributions welcome — UI components, new interaction patterns, OpenClaw integration improvements, documentation.
+For production-style single-port serving:
 
-Open an issue to discuss before submitting large PRs.
+```bash
+npm run build
+npm start
+```
 
 ---
 

package/bin/agentclick.mjs

@@ -4,11 +4,39 @@ import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { spawnSync } from 'node:child_process'
+import net from 'node:net'
 
 const __filename = fileURLToPath(import.meta.url)
 const rootDir = dirname(dirname(__filename))
 const webDistIndex = join(rootDir, 'packages', 'web', 'dist', 'index.html')
 const serverDistEntry = join(rootDir, 'packages', 'server', 'dist', 'index.js')
+const args = process.argv.slice(2)
+
+function printHelp() {
+  console.log(`AgentClick CLI
+
+Usage:
+  agentclick
+  agentclick --help
+
+Options:
+  --help, -h   Show this help message
+`)
+}
+
+function parseArgs(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--help' || arg === '-h') {
+      printHelp()
+      process.exit(0)
+    }
+    console.error(`[agentclick] Unknown argument: ${arg}`)
+    console.error('[agentclick] Run "agentclick --help" for usage.')
+    process.exit(1)
+  }
+  return {}
+}
 
 function run(command, args) {
   const result = spawnSync(command, args, {
@@ -25,6 +53,8 @@ function run(command, args) {
   }
 }
 
+parseArgs(args)
+
 if (!existsSync(webDistIndex) || !existsSync(serverDistEntry)) {
   console.log('[agentclick] Build artifacts not found, running npm run build...')
   const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm'
@@ -36,4 +66,48 @@ if (!existsSync(serverDistEntry)) {
   process.exit(1)
 }
 
-run(process.execPath, [serverDistEntry])
+async function canListen(port) {
+  return await new Promise(resolve => {
+    const server = net.createServer()
+    server.once('error', err => {
+      if ((err).code === 'EADDRINUSE') {
+        resolve(false)
+        return
+      }
+      console.error(`[agentclick] Port check failed for ${port}: ${err.message}`)
+      process.exit(1)
+    })
+    server.once('listening', () => {
+      server.close(() => resolve(true))
+    })
+    server.listen(port)
+  })
+}
+
+async function resolvePort() {
+  if (process.env.PORT) return process.env.PORT
+
+  let port = 3001
+  while (true) {
+    const available = await canListen(port)
+    if (available) return String(port)
+    console.log(`[agentclick] Port ${port} in use, trying ${port + 1}...`)
+    port += 1
+  }
+}
+
+const childEnv = { ...process.env }
+childEnv.PORT = await resolvePort()
+
+const result = spawnSync(process.execPath, [serverDistEntry], {
+  cwd: rootDir,
+  stdio: 'inherit',
+  env: childEnv,
+})
+if (result.error) {
+  console.error('[agentclick] Failed to start server:', result.error.message)
+  process.exit(1)
+}
+if (typeof result.status === 'number' && result.status !== 0) {
+  process.exit(result.status)
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "agentclick",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "description": "Human-in-the-loop approval UI for AI agents. Review, edit, and approve agent actions in your browser before they execute.",
+  "keywords": [
+    "ai-agent",
+    "human-in-the-loop",
+    "approval",
+    "hitl",
+    "llm",
+    "langchain",
+    "openai",
+    "agent-ui",
+    "agentic",
+    "ai-safety",
+    "human-oversight"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentlayer-io/AgentClick.git"
+  },
+  "homepage": "https://github.com/agentlayer-io/AgentClick",
   "bin": {
     "agentclick": "./bin/agentclick.mjs"
   },
@@ -11,8 +30,7 @@
     "packages/server/package.json",
     "packages/web/dist/",
     "packages/web/package.json",
-    "README.md",
-    "AGENTS.md"
+    "README.md"
   ],
   "workspaces": [
     "packages/*"

package/packages/server/dist/index.js

@@ -74,6 +74,35 @@ app.get('/api/sessions/:id', (req, res) => {
         return res.status(404).json({ error: 'Session not found' });
     res.json(session);
 });
+// Mock summary endpoint for inbox items (UI integration first)
+app.get('/api/sessions/:id/summary', (req, res) => {
+    const session = getSession(req.params.id);
+    if (!session)
+        return res.status(404).json({ error: 'Session not found' });
+    const payload = session.payload;
+    const inbox = payload?.inbox ?? [];
+    const emailId = req.query.emailId;
+    const email = inbox.find(item => item.id === emailId);
+    if (!email) {
+        return res.status(404).json({ error: 'Email not found in session' });
+    }
+    const preview = String(email.preview ?? '');
+    const summaryText = preview.length > 0
+        ? `This email appears to be about: ${preview}`
+        : 'No preview text is available for this email yet.';
+    const from = String(email.from ?? 'Unknown sender');
+    const category = String(email.category ?? 'Unknown');
+    res.json({
+        emailId,
+        summary: summaryText,
+        bullets: [
+            `From: ${from}`,
+            `Category: ${category}`,
+            'Source: mock summary endpoint (replace with agent summary later)',
+        ],
+        confidence: 'mock',
+    });
+});
 // Long-poll: agent calls this and blocks until user completes review (up to 5 min)
 app.get('/api/sessions/:id/wait', async (req, res) => {
     const TIMEOUT_MS = 5 * 60 * 1000;
@@ -154,6 +183,10 @@ function buildActionSummary(result) {
     if (result.regenerate) {
         lines.push('- User requested full regeneration.');
     }
+    const intents = (result.selectedIntents ?? []);
+    if (intents.length > 0) {
+        lines.push(`- Intent decisions: ${intents.map(i => `${i.id} → ${i.accepted ? 'accepted' : 'rejected'}`).join(', ')}`);
+    }
     return lines.join('\n');
 }
 if (SHOULD_SERVE_BUILT_WEB) {

package/packages/server/src/index.ts

@@ -83,6 +83,40 @@ app.get('/api/sessions/:id', (req, res) => {
   res.json(session)
 })
 
+// Mock summary endpoint for inbox items (UI integration first)
+app.get('/api/sessions/:id/summary', (req, res) => {
+  const session = getSession(req.params.id)
+  if (!session) return res.status(404).json({ error: 'Session not found' })
+
+  const payload = session.payload as Record<string, unknown> | undefined
+  const inbox = (payload?.inbox as Array<Record<string, unknown>> | undefined) ?? []
+  const emailId = req.query.emailId as string | undefined
+  const email = inbox.find(item => item.id === emailId)
+
+  if (!email) {
+    return res.status(404).json({ error: 'Email not found in session' })
+  }
+
+  const preview = String(email.preview ?? '')
+  const summaryText = preview.length > 0
+    ? `This email appears to be about: ${preview}`
+    : 'No preview text is available for this email yet.'
+
+  const from = String(email.from ?? 'Unknown sender')
+  const category = String(email.category ?? 'Unknown')
+
+  res.json({
+    emailId,
+    summary: summaryText,
+    bullets: [
+      `From: ${from}`,
+      `Category: ${category}`,
+      'Source: mock summary endpoint (replace with agent summary later)',
+    ],
+    confidence: 'mock',
+  })
+})
+
 // Long-poll: agent calls this and blocks until user completes review (up to 5 min)
 app.get('/api/sessions/:id/wait', async (req, res) => {
   const TIMEOUT_MS = 5 * 60 * 1000
@@ -172,6 +206,11 @@ function buildActionSummary(result: Record<string, unknown>): string {
     lines.push('- User requested full regeneration.')
   }
 
+  const intents = (result.selectedIntents ?? []) as Array<{ id: string; accepted: boolean }>
+  if (intents.length > 0) {
+    lines.push(`- Intent decisions: ${intents.map(i => `${i.id} → ${i.accepted ? 'accepted' : 'rejected'}`).join(', ')}`)
+  }
+
   return lines.join('\n')
 }