agentclick 0.1.1 → 0.2.0

package/README.md

@@ -1,154 +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.
-
-CLI options:
+Then test it with a mock session:
 
 ```bash
-agentclick --help
-PORT=3002 agentclick
+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"}}'
 ```
 
-By default, `agentclick` starts on port `3001`. If that port is in use, it automatically tries `3002`, `3003`, and so on.
+A browser tab opens automatically. Review, approve or reject, and close the tab.
 
-Optional server config (defaults shown in `.env.example`):
-
-```bash
-PORT=3001
-OPENCLAW_WEBHOOK=http://localhost:18789/hooks/agent
-```
-
-Create a local `.env` in the project root to override these values during development (server auto-loads it via `dotenv`).
+---
 
-Production-style local run (single port after build):
+## How It Works
 
-```bash
-npm run build
-npm start          # serves API + built web UI on localhost:3001
-```
+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.
 
-Deployment notes (reverse proxy, Docker/OpenClaw host mapping, env vars):
+No WebSockets. No framework plugins. One HTTP endpoint in, one HTTP endpoint out.
 
-- See `docs/deployment.md`
+---
 
-Copy the skill to your OpenClaw workspace:
+## Comparison
 
-```bash
-cp -r skills/clawui-email ~/.openclaw/skills/
-```
-
-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?
-
-[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.
+## Development
 
----
+```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/package.json

@@ -1,6 +1,25 @@
 {
   "name": "agentclick",
-  "version": "0.1.1",
+  "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

@@ -183,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

@@ -206,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')
 }