@orgloop/agentctl 1.0.0 → 1.1.0

package/README.md

@@ -28,7 +28,7 @@ Over time, agentctl can extend to handle more concerns of headless coding — au
 ## Installation
 
 ```bash
-npm install -g agentctl
+npm install -g @orgloop/agentctl
 ```
 
 Requires Node.js >= 20.
@@ -90,6 +90,11 @@ agentctl stop <id> [options]
 agentctl resume <id> <message> [options]
   --adapter <name>     Adapter to use
 
+# <message> is a continuation prompt sent to the agent.
+# The agent receives it as new user input and resumes work.
+# Example: resume a stopped session with a follow-up instruction
+agentctl resume abc123 "fix the failing tests and re-run the suite"
+
 agentctl events [options]
   --json               Output as NDJSON (default)
 ```
@@ -109,15 +114,68 @@ agentctl locks [options]
   --json               Output as JSON
 ```
 
+### Lifecycle Hooks
+
+Hooks are shell commands that run at specific points in a session's lifecycle. Pass them as flags to `launch` or `merge`:
+
+```bash
+agentctl launch -p "implement feature X" \
+  --on-create "echo 'Session $AGENTCTL_SESSION_ID started'" \
+  --on-complete "npm test"
+
+agentctl merge <id> \
+  --pre-merge "npm run lint && npm test" \
+  --post-merge "curl -X POST https://slack.example.com/webhook -d '{\"text\": \"PR merged\"}'"
+```
+
+Available hooks:
+
+| Hook | Trigger | Typical use |
+|------|---------|-------------|
+| `--on-create <script>` | After a session is created | Notify, set up environment |
+| `--on-complete <script>` | After a session completes | Run tests, send alerts |
+| `--pre-merge <script>` | Before `agentctl merge` commits | Lint, test, validate |
+| `--post-merge <script>` | After `agentctl merge` pushes/opens PR | Notify, trigger CI |
+
+Hook scripts receive context via environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `AGENTCTL_SESSION_ID` | Session UUID |
+| `AGENTCTL_CWD` | Working directory of the session |
+| `AGENTCTL_ADAPTER` | Adapter name (e.g. `claude-code`) |
+| `AGENTCTL_BRANCH` | Git branch (when using `--worktree`) |
+| `AGENTCTL_EXIT_CODE` | Process exit code (in `--on-complete`) |
+
+Hooks run with a 60-second timeout. If a hook fails, its stderr is printed but execution continues.
+
 ### Fuse Timers
 
-For Kind cluster management — automatically shuts down clusters when sessions end.
+Fuse timers provide automatic cleanup of [Kind](https://kind.sigs.k8s.io/) Kubernetes clusters tied to coding sessions. When a session exits, agentctl starts a countdown timer. If no new session starts in the same worktree directory before the timer expires, the associated Kind cluster is deleted to free resources.
+
+This is useful when running agents in worktree-per-branch workflows where each branch has its own Kind cluster (e.g. `kindo-charlie-<branch>`). Without fuse timers, forgotten clusters accumulate and waste resources.
+
+**How it works:**
+
+1. Agent session exits in a worktree directory (e.g. `~/code/mono-my-feature`)
+2. agentctl derives the cluster name (`kindo-charlie-my-feature`) and starts a fuse timer
+3. If the timer expires (default: configured at daemon startup), the cluster is deleted via `kind delete cluster`
+4. If a new session starts in the same directory before expiry, the fuse is cancelled
 
 ```bash
+# List active fuse timers
 agentctl fuses [options]
   --json               Output as JSON
 ```
 
+Example output:
+
+```
+Directory             Cluster                     Expires In
+~/code/mono-feat-x    kindo-charlie-feat-x        12m
+~/code/mono-hotfix    kindo-charlie-hotfix        45m
+```
+
 ### Daemon
 
 The daemon provides session tracking, directory locks, fuse timers, and Prometheus metrics. It auto-starts on first `agentctl` command.
@@ -135,7 +193,76 @@ agentctl daemon install    # Install macOS LaunchAgent (auto-start on login)
 agentctl daemon uninstall  # Remove LaunchAgent
 ```
 
-Metrics are exposed at `http://localhost:9200/metrics` in Prometheus text format.
+Metrics are exposed at `http://localhost:9200/metrics` in Prometheus text format. See [Prometheus Metrics](#prometheus-metrics) for the full list.
+
+### Events
+
+`agentctl events` streams session lifecycle events as NDJSON (newline-delimited JSON). Each line is a self-contained JSON object:
+
+```json
+{"type":"session.started","adapter":"claude-code","sessionId":"abc123...","timestamp":"2025-06-15T10:30:00.000Z","session":{...}}
+{"type":"session.stopped","adapter":"claude-code","sessionId":"abc123...","timestamp":"2025-06-15T11:00:00.000Z","session":{...}}
+{"type":"session.idle","adapter":"claude-code","sessionId":"def456...","timestamp":"2025-06-15T11:05:00.000Z","session":{...}}
+```
+
+Event types: `session.started`, `session.stopped`, `session.idle`, `session.error`.
+
+The `session` field contains the full session object (id, adapter, status, cwd, model, prompt, tokens, etc.).
+
+**Piping events into OrgLoop (or similar event routers):**
+
+```bash
+# Pipe lifecycle events to OrgLoop's webhook endpoint
+agentctl events | while IFS= read -r event; do
+  curl -s -X POST https://orgloop.example.com/hooks/agentctl \
+    -H "Content-Type: application/json" \
+    -d "$event"
+done
+
+# Or use a persistent pipe with jq filtering
+agentctl events | jq -c 'select(.type == "session.stopped")' | while IFS= read -r event; do
+  curl -s -X POST https://orgloop.example.com/hooks/session-ended \
+    -H "Content-Type: application/json" \
+    -d "$event"
+done
+```
+
+This pattern works with any webhook-based system — OrgLoop, Zapier, n8n, or a custom event router. The NDJSON format is compatible with standard Unix tools (`jq`, `grep`, `awk`) for filtering and transformation.
+
+## Prometheus Metrics
+
+The daemon exposes metrics at `http://localhost:9200/metrics` in Prometheus text format. Default port is 9200, configurable via `--metrics-port`.
+
+### Gauges
+
+| Metric | Labels | Description |
+|--------|--------|-------------|
+| `agentctl_sessions_active` | — | Number of currently active sessions |
+| `agentctl_locks_active` | `type="auto"\|"manual"` | Number of active directory locks by type |
+| `agentctl_fuses_active` | — | Number of active fuse timers |
+
+### Counters
+
+| Metric | Labels | Description |
+|--------|--------|-------------|
+| `agentctl_sessions_total` | `status="completed"\|"failed"\|"stopped"` | Total sessions by final status |
+| `agentctl_fuses_fired_total` | — | Total fuse timers that fired (clusters deleted) |
+| `agentctl_kind_clusters_deleted_total` | — | Total Kind clusters deleted by fuse timers |
+
+### Histogram
+
+| Metric | Buckets (seconds) | Description |
+|--------|-------------------|-------------|
+| `agentctl_session_duration_seconds` | 60, 300, 600, 1800, 3600, 7200, +Inf | Session duration distribution |
+
+Example scrape config for Prometheus:
+
+```yaml
+scrape_configs:
+  - job_name: agentctl
+    static_configs:
+      - targets: ["localhost:9200"]
+```
 
 ## Architecture
 
@@ -155,6 +282,8 @@ Reads session data from `~/.claude/projects/` and cross-references with running
 
 Connects to the OpenClaw gateway via WebSocket RPC. Read-only — sessions are managed through the gateway.
 
+Requires the `OPENCLAW_WEBHOOK_TOKEN` environment variable. The adapter warns clearly if the token is missing or authentication fails.
+
 ### Writing an Adapter
 
 Implement the `AgentAdapter` interface:

package/dist/adapters/claude-code.js

@@ -148,7 +148,7 @@ export class ClaudeCodeAdapter {
         if (pid) {
             resolvedSessionId = await this.pollForSessionId(logPath, pid, 5000);
         }
-        const sessionId = resolvedSessionId || crypto.randomUUID();
+        const sessionId = resolvedSessionId || (pid ? `pending-${pid}` : crypto.randomUUID());
         // Persist session metadata so status checks work after wrapper exits
         if (pid) {
             await this.writeSessionMeta({

package/dist/adapters/openclaw.js

@@ -17,6 +17,11 @@ export class OpenClawAdapter {
         this.rpcCall = opts?.rpcCall || this.defaultRpcCall.bind(this);
     }
     async list(opts) {
+        if (!this.authToken) {
+            console.warn("Warning: OPENCLAW_WEBHOOK_TOKEN is not set — OpenClaw adapter cannot authenticate. " +
+                "Set this environment variable to connect to the gateway.");
+            return [];
+        }
         let result;
         try {
             result = (await this.rpcCall("sessions.list", {
@@ -24,8 +29,16 @@ export class OpenClawAdapter {
                 includeLastMessage: true,
             }));
         }
-        catch {
-            // Gateway unreachable — return empty
+        catch (err) {
+            const msg = err?.message || "unknown error";
+            if (msg.includes("auth") || msg.includes("Auth")) {
+                console.warn(`Warning: OpenClaw gateway authentication failed: ${msg}. ` +
+                    "Check that OPENCLAW_WEBHOOK_TOKEN is valid.");
+            }
+            else {
+                console.warn(`Warning: OpenClaw gateway unreachable (${msg}). ` +
+                    `Is the gateway running at ${this.baseUrl}?`);
+            }
             return [];
         }
         let sessions = result.sessions.map((row) => this.mapRowToSession(row, result.defaults));
@@ -67,6 +80,9 @@ export class OpenClawAdapter {
         return assistantMessages.slice(-limit).join("\n---\n");
     }
     async status(sessionId) {
+        if (!this.authToken) {
+            throw new Error("OPENCLAW_WEBHOOK_TOKEN is not set — cannot connect to OpenClaw gateway");
+        }
         let result;
         try {
             result = (await this.rpcCall("sessions.list", {
@@ -184,14 +200,17 @@ export class OpenClawAdapter {
      * Resolve a sessionId (or prefix) to a gateway session key.
      */
     async resolveKey(sessionId) {
+        if (!this.authToken) {
+            throw new Error("OPENCLAW_WEBHOOK_TOKEN is not set — cannot connect to OpenClaw gateway");
+        }
         let result;
         try {
             result = (await this.rpcCall("sessions.list", {
                 search: sessionId,
             }));
         }
-        catch {
-            return null;
+        catch (err) {
+            throw new Error(`Failed to resolve session ${sessionId}: ${err.message}`);
         }
         const row = result.sessions.find((s) => s.sessionId === sessionId ||
             s.key === sessionId ||

package/dist/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
+import { createRequire } from "node:module";
 import os from "node:os";
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require("../package.json");
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
@@ -158,7 +161,7 @@ const program = new Command();
 program
     .name("agentctl")
     .description("Universal agent supervision interface")
-    .version("0.3.0");
+    .version(PKG_VERSION);
 // list
 program
     .command("list")

package/dist/daemon/session-tracker.d.ts

@@ -3,16 +3,25 @@ import type { SessionRecord, StateManager } from "./state.js";
 export interface SessionTrackerOpts {
     adapters: Record<string, AgentAdapter>;
     pollIntervalMs?: number;
+    /** Override PID liveness check for testing (default: process.kill(pid, 0)) */
+    isProcessAlive?: (pid: number) => boolean;
 }
 export declare class SessionTracker {
     private state;
     private adapters;
     private pollIntervalMs;
     private pollHandle;
+    private readonly isProcessAlive;
     constructor(state: StateManager, opts: SessionTrackerOpts);
     startPolling(): void;
     stopPolling(): void;
     private poll;
+    /**
+     * Clean up ghost sessions in the daemon state:
+     * - pending-* entries whose PID matches a resolved session → remove pending
+     * - Any "running"/"idle" session in state whose PID is dead → mark stopped
+     */
+    private reapStaleEntries;
     /** Track a newly launched session */
     track(session: AgentSession, adapterName: string): SessionRecord;
     /** Get session record by id (exact or prefix) */

package/dist/daemon/session-tracker.js

@@ -3,10 +3,12 @@ export class SessionTracker {
     adapters;
     pollIntervalMs;
     pollHandle = null;
+    isProcessAlive;
     constructor(state, opts) {
         this.state = state;
         this.adapters = opts.adapters;
         this.pollIntervalMs = opts.pollIntervalMs ?? 5000;
+        this.isProcessAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
     }
     startPolling() {
         if (this.pollHandle)
@@ -24,10 +26,15 @@ export class SessionTracker {
         }
     }
     async poll() {
+        // Collect PIDs from all adapter-returned sessions (the source of truth)
+        const adapterPidToId = new Map();
         for (const [adapterName, adapter] of Object.entries(this.adapters)) {
             try {
                 const sessions = await adapter.list({ all: true });
                 for (const session of sessions) {
+                    if (session.pid) {
+                        adapterPidToId.set(session.pid, session.id);
+                    }
                     const existing = this.state.getSession(session.id);
                     const record = sessionToRecord(session, adapterName);
                     if (!existing) {
@@ -49,6 +56,43 @@ export class SessionTracker {
                 // Adapter unavailable — skip
             }
         }
+        // Reap stale entries from daemon state
+        this.reapStaleEntries(adapterPidToId);
+    }
+    /**
+     * Clean up ghost sessions in the daemon state:
+     * - pending-* entries whose PID matches a resolved session → remove pending
+     * - Any "running"/"idle" session in state whose PID is dead → mark stopped
+     */
+    reapStaleEntries(adapterPidToId) {
+        const sessions = this.state.getSessions();
+        for (const [id, record] of Object.entries(sessions)) {
+            // Bug 2: If this is a pending-* entry and a real session has the same PID,
+            // the pending entry is stale — remove it
+            if (id.startsWith("pending-") && record.pid) {
+                const resolvedId = adapterPidToId.get(record.pid);
+                if (resolvedId && resolvedId !== id) {
+                    this.state.removeSession(id);
+                    continue;
+                }
+            }
+            // Bug 1: If session is "running"/"idle" but PID is dead, mark stopped
+            if ((record.status === "running" || record.status === "idle") &&
+                record.pid) {
+                // Only reap if the adapter didn't return this session as running
+                // (adapter is the source of truth for sessions it knows about)
+                const adapterId = adapterPidToId.get(record.pid);
+                if (adapterId === id)
+                    continue; // Adapter confirmed this PID is active
+                if (!this.isProcessAlive(record.pid)) {
+                    this.state.setSession(id, {
+                        ...record,
+                        status: "stopped",
+                        stoppedAt: new Date().toISOString(),
+                    });
+                }
+            }
+        }
     }
     /** Track a newly launched session */
     track(session, adapterName) {
@@ -79,6 +123,8 @@ export class SessionTracker {
         else if (!opts?.all) {
             filtered = filtered.filter((s) => s.status === "running" || s.status === "idle");
         }
+        // Dedup: if a pending-* entry shares a PID with a resolved entry, show only the resolved one
+        filtered = deduplicatePendingSessions(filtered);
         return filtered.sort((a, b) => {
             // Running first, then by recency
             if (a.status === "running" && b.status !== "running")
@@ -102,6 +148,34 @@ export class SessionTracker {
         return session;
     }
 }
+/** Check if a process is alive via kill(pid, 0) signal check */
+function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove pending-* entries that share a PID with a resolved (non-pending) session.
+ * This is a safety net for list output — the poll() reaper handles cleanup in state.
+ */
+function deduplicatePendingSessions(sessions) {
+    const realPids = new Set();
+    for (const s of sessions) {
+        if (!s.id.startsWith("pending-") && s.pid) {
+            realPids.add(s.pid);
+        }
+    }
+    return sessions.filter((s) => {
+        if (s.id.startsWith("pending-") && s.pid && realPids.has(s.pid)) {
+            return false;
+        }
+        return true;
+    });
+}
 function sessionToRecord(session, adapterName) {
     return {
         id: session.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orgloop/agentctl",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Universal agent supervision interface — monitor and control AI coding agents from a single CLI",
   "type": "module",
   "bin": {