feat: env-var-first port pipeline for agentclick runtime

Author: zhmzm

SKILL.md

@@ -11,9 +11,19 @@ cd /Users/hm/.openclaw/workspace/AgentClick
 npm start
 ```
 
-Default server: `http://localhost:38173` (legacy deployments may still use `:3001`)
+Default server: `http://localhost:38173`
 
-Containerized clients may use `http://host.docker.internal:38173` (or your overridden `PORT`).
+Containerized clients may use `http://host.docker.internal:38173` (or `AGENTCLICK_PORT` / `AGENTCLICK_URL` overrides).
+
+## Port Pipeline
+
+Use this runtime pipeline before review calls:
+
+1. Read `AGENTCLICK_URL` (if set) and use it directly.
+2. Else read `AGENTCLICK_PORT` (fallback `PORT`, then `38173`) and target `http://localhost:<port>`.
+3. Verify identity with `GET /api/identity`.
+4. If identity check fails, start `agentclick` and set `AGENTCLICK_PORT` for the running process chain.
+5. Then create review sessions and keep an active `/wait` loop.
 
 ## Supported Review Types
 
@@ -32,7 +42,7 @@ Canonical types accepted by `POST /api/review`:
 ### 1) Create session
 
 ```bash
-curl -s -X POST http://localhost:38173/api/review \
+curl -s -X POST "${AGENTCLICK_URL:-http://localhost:${AGENTCLICK_PORT:-38173}}/api/review" \
   -H 'Content-Type: application/json' \
   -d '{
     "type": "action_approval",
@@ -50,7 +60,7 @@ Response:
 ### 2) Wait for human decision (required active polling)
 
 ```bash
-curl -s "http://localhost:38173/api/sessions/<sessionId>/wait"
+curl -s "${AGENTCLICK_URL:-http://localhost:${AGENTCLICK_PORT:-38173}}/api/sessions/<sessionId>/wait"
 ```
 
 `/wait` blocks up to 5 minutes. Returns the session when status becomes `completed` or `rewriting`.
@@ -69,7 +79,7 @@ Important:
 ### 4) Rewrite payload (when requested)
 
 ```bash
-curl -s -X PUT "http://localhost:38173/api/sessions/<sessionId>/payload" \
+curl -s -X PUT "${AGENTCLICK_URL:-http://localhost:${AGENTCLICK_PORT:-38173}}/api/sessions/<sessionId>/payload" \
   -H 'Content-Type: application/json' \
   -d '{ "payload": { "...": "updated" } }'
 ```

bin/agentclick.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url'
 import { spawnSync } from 'node:child_process'
 import net from 'node:net'
 
+const DEFAULT_PORT = 38173
 const __filename = fileURLToPath(import.meta.url)
 const rootDir = dirname(dirname(__filename))
 const webDistIndex = join(rootDir, 'packages', 'web', 'dist', 'index.html')
@@ -35,10 +36,11 @@ Options:
 
 Examples:
   agentclick              Start the server (auto-detects port)
-  PORT=4000 agentclick    Start on a specific port
+  AGENTCLICK_PORT=4000 agentclick    Start on a specific port
 
 Environment:
-  PORT                    Server port (default: 38173, auto-fallback if busy)
+  AGENTCLICK_PORT         Preferred server port (default: 38173)
+  PORT                    Backward-compatible server port override
   OPENCLAW_WEBHOOK        Webhook URL for agent callbacks
 `)
 }
@@ -107,6 +109,28 @@ async function canListen(port) {
   })
 }
 
+async function getClosestAvailablePort(preferredPort) {
+  const nextPort = preferredPort + 1
+  if (await canListen(nextPort)) return nextPort
+  // Fallback to OS-assigned free port (no range scan).
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer()
+    server.once('error', reject)
+    server.listen(0, () => {
+      const address = server.address()
+      if (!address || typeof address === 'string') {
+        server.close(() => reject(new Error('Failed to resolve ephemeral port')))
+        return
+      }
+      const freePort = address.port
+      server.close(err => {
+        if (err) reject(err)
+        else resolve(freePort)
+      })
+    })
+  })
+}
+
 async function isAgentClickServer(port) {
   const url = `http://localhost:${port}/api/identity`
   const controller = new AbortController()
@@ -124,48 +148,23 @@ async function isAgentClickServer(port) {
 }
 
 async function resolvePort() {
-  const explicitPort = process.env.PORT ? Number(process.env.PORT) : null
-  if (explicitPort && Number.isFinite(explicitPort) && explicitPort > 0) {
-    const free = await canListen(explicitPort)
-    if (free) return String(explicitPort)
-    if (await isAgentClickServer(explicitPort)) {
-      console.log(`[agentclick] AgentClick already running at http://localhost:${explicitPort}; reusing existing server.`)
-      return null
-    }
-    console.log(`[agentclick] Port ${explicitPort} is occupied by another service; searching for fallback port...`)
-    let fallback = explicitPort + 1
-    while (true) {
-      const available = await canListen(fallback)
-      if (available) {
-        console.log(`[agentclick] Using fallback port ${fallback}`)
-        return String(fallback)
-      }
-      if (await isAgentClickServer(fallback)) {
-        console.log(`[agentclick] AgentClick already running at http://localhost:${fallback}; reusing existing server.`)
-        return null
-      }
-      fallback += 1
-    }
+  const configuredPort = Number(process.env.AGENTCLICK_PORT || process.env.PORT || DEFAULT_PORT)
+  if (!Number.isFinite(configuredPort) || configuredPort <= 0) {
+    console.error('[agentclick] Invalid AGENTCLICK_PORT/PORT configuration.')
+    process.exit(1)
   }
 
-  // Backward compatibility: if legacy default is running AgentClick, reuse it.
-  const legacyPort = 3001
-  if (await isAgentClickServer(legacyPort)) {
-    console.log(`[agentclick] AgentClick already running at legacy default http://localhost:${legacyPort}; reusing existing server.`)
+  const free = await canListen(configuredPort)
+  if (free) return String(configuredPort)
+
+  if (await isAgentClickServer(configuredPort)) {
+    console.log(`[agentclick] AgentClick already running at http://localhost:${configuredPort}; reusing existing server.`)
     return null
   }
 
-  let port = 38173
-  while (true) {
-    const available = await canListen(port)
-    if (available) return String(port)
-    if (await isAgentClickServer(port)) {
-      console.log(`[agentclick] AgentClick already running at http://localhost:${port}; reusing existing server.`)
-      return null
-    }
-    console.log(`[agentclick] Port ${port} in use by another service, trying ${port + 1}...`)
-    port += 1
-  }
+  const fallbackPort = await getClosestAvailablePort(configuredPort)
+  console.log(`[agentclick] Port ${configuredPort} is occupied by another service. Starting AgentClick on ${fallbackPort}.`)
+  return String(fallbackPort)
 }
 
 const childEnv = { ...process.env }
@@ -174,6 +173,9 @@ if (!resolvedPort) {
   process.exit(0)
 }
 childEnv.PORT = resolvedPort
+childEnv.AGENTCLICK_PORT = resolvedPort
+process.env.AGENTCLICK_PORT = resolvedPort
+console.log(`[agentclick] Using AGENTCLICK_PORT=${resolvedPort}`)
 
 const result = spawnSync(process.execPath, [serverDistEntry], {
   cwd: rootDir,

lib/agentclick.js

@@ -0,0 +1,40 @@
+const AGENTCLICK_PORT = process.env.AGENTCLICK_PORT || process.env.PORT || '38173';
+const AGENTCLICK_URL = process.env.AGENTCLICK_URL || `http://localhost:${AGENTCLICK_PORT}`;
+
+/**
+ * Send an action for human review and wait for approval.
+ * @param {Object} options
+ * @param {string} options.type - 'code_review' | 'email_review' | 'action_approval' | 'plan_review' | 'trajectory_review'
+ * @param {string} options.sessionKey - OpenClaw session key
+ * @param {Object} options.payload - Review-specific payload
+ * @returns {Promise<Object>} User's decision
+ */
+async function reviewAndWait({ type, sessionKey, payload }) {
+  // Create review session
+  const res = await fetch(`${AGENTCLICK_URL}/api/review`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type, sessionKey, payload })
+  });
+  
+  if (!res.ok) {
+    throw new Error(`AgentClick error: ${res.status} ${res.statusText}`);
+  }
+  
+  const { sessionId } = await res.json();
+  console.log(`[agentclick] Waiting for review: ${sessionId}`);
+  
+  // Long-poll for result (up to 5 min)
+  const waitRes = await fetch(`${AGENTCLICK_URL}/api/sessions/${sessionId}/wait`);
+  
+  if (!waitRes.ok) {
+    throw new Error(`AgentClick wait failed: ${waitRes.status}`);
+  }
+  
+  const session = await waitRes.json();
+  console.log(`[agentclick] Review complete: ${session.status}`);
+  
+  return session.result || session;
+}
+
+module.exports = { reviewAndWait };

packages/server/src/index.ts

@@ -10,7 +10,7 @@ import { createSession, getSession, listSessions, completeSession, setSessionRew
 
 const app = express()
 const DEFAULT_PORT = 38173
-const PORT = Number(process.env.PORT || DEFAULT_PORT)
+const PORT = Number(process.env.AGENTCLICK_PORT || process.env.PORT || DEFAULT_PORT)
 const OPENCLAW_WEBHOOK = process.env.OPENCLAW_WEBHOOK || 'http://localhost:18789/hooks/agent'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)

skills/clawui-plan/SKILL.md

@@ -137,7 +137,7 @@ Submit a multi-step execution plan to AgentClick for human review. The human can
 ## Submitting a Plan
 
 ```bash
-RESPONSE=$(curl -s -X POST http://localhost:38173/api/review \
+RESPONSE=$(curl -s -X POST "${AGENTCLICK_URL:-http://localhost:${AGENTCLICK_PORT:-38173}}/api/review" \
   -H 'Content-Type: application/json' \
   -d '{
     "type": "plan_review",
@@ -160,7 +160,7 @@ echo "Session: $SESSION_ID"
 After creating the session, immediately block on `/wait` for that same session. Do not continue execution before `/wait` returns a decision.
 
 ```bash
-curl -s "http://localhost:38173/api/sessions/${SESSION_ID}/wait"
+curl -s "${AGENTCLICK_URL:-http://localhost:${AGENTCLICK_PORT:-38173}}/api/sessions/${SESSION_ID}/wait"
 ```
 
 Rules: