@orgloop/agentctl 1.0.0

package/dist/daemon/supervisor.js

@@ -0,0 +1,79 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Daemon supervisor — launches the daemon in foreground mode and
+ * restarts it on crash with exponential backoff (1s, 2s, 4s... cap 5min).
+ * Resets backoff after stable uptime.
+ */
+export async function runSupervisor(opts) {
+    const minBackoff = opts.minBackoffMs ?? 1000;
+    const maxBackoff = opts.maxBackoffMs ?? 300_000;
+    const stableUptime = opts.stableUptimeMs ?? 60_000;
+    let currentBackoff = minBackoff;
+    let running = true;
+    // Write supervisor PID file
+    const supervisorPidPath = path.join(opts.configDir, "supervisor.pid");
+    await fs.writeFile(supervisorPidPath, String(process.pid));
+    const cleanup = async () => {
+        running = false;
+        await fs.rm(supervisorPidPath, { force: true }).catch(() => { });
+    };
+    process.on("SIGTERM", async () => {
+        await cleanup();
+        process.exit(0);
+    });
+    process.on("SIGINT", async () => {
+        await cleanup();
+        process.exit(0);
+    });
+    const logDir = opts.configDir;
+    await fs.mkdir(logDir, { recursive: true });
+    while (running) {
+        const startTime = Date.now();
+        const stdoutFd = await fs.open(path.join(logDir, "daemon.stdout.log"), "a");
+        const stderrFd = await fs.open(path.join(logDir, "daemon.stderr.log"), "a");
+        const child = spawn(opts.nodePath, [
+            opts.cliPath,
+            "daemon",
+            "start",
+            "--foreground",
+            "--metrics-port",
+            String(opts.metricsPort),
+        ], {
+            stdio: ["ignore", stdoutFd.fd, stderrFd.fd],
+        });
+        // Wait for child to exit
+        const exitCode = await new Promise((resolve) => {
+            child.on("exit", (code) => resolve(code));
+            child.on("error", () => resolve(1));
+        });
+        await stdoutFd.close();
+        await stderrFd.close();
+        if (!running)
+            break;
+        const uptime = Date.now() - startTime;
+        // Reset backoff if daemon ran long enough to be considered stable
+        if (uptime >= stableUptime) {
+            currentBackoff = minBackoff;
+        }
+        console.error(`Daemon exited (code ${exitCode}) after ${Math.round(uptime / 1000)}s. Restarting in ${Math.round(currentBackoff / 1000)}s...`);
+        await new Promise((r) => setTimeout(r, currentBackoff));
+        // Exponential backoff (double, capped)
+        currentBackoff = Math.min(currentBackoff * 2, maxBackoff);
+    }
+}
+/** Read the supervisor PID from disk and check if it's alive */
+export async function getSupervisorPid(configDir) {
+    const dir = configDir || path.join(os.homedir(), ".agentctl");
+    try {
+        const raw = await fs.readFile(path.join(dir, "supervisor.pid"), "utf-8");
+        const pid = Number.parseInt(raw.trim(), 10);
+        process.kill(pid, 0); // Check liveness
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/hooks.d.ts

@@ -0,0 +1,19 @@
+import type { LifecycleHooks } from "./core/types.js";
+export type HookPhase = "onCreate" | "onComplete" | "preMerge" | "postMerge";
+export interface HookContext {
+    sessionId: string;
+    cwd: string;
+    adapter: string;
+    branch?: string;
+    exitCode?: number;
+}
+/**
+ * Run a lifecycle hook script if defined.
+ * Hook scripts receive context via environment variables:
+ *   AGENTCTL_SESSION_ID, AGENTCTL_CWD, AGENTCTL_ADAPTER,
+ *   AGENTCTL_BRANCH, AGENTCTL_EXIT_CODE
+ */
+export declare function runHook(hooks: LifecycleHooks | undefined, phase: HookPhase, ctx: HookContext): Promise<{
+    stdout: string;
+    stderr: string;
+} | null>;

package/dist/hooks.js

@@ -0,0 +1,39 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/**
+ * Run a lifecycle hook script if defined.
+ * Hook scripts receive context via environment variables:
+ *   AGENTCTL_SESSION_ID, AGENTCTL_CWD, AGENTCTL_ADAPTER,
+ *   AGENTCTL_BRANCH, AGENTCTL_EXIT_CODE
+ */
+export async function runHook(hooks, phase, ctx) {
+    if (!hooks)
+        return null;
+    const script = hooks[phase];
+    if (!script)
+        return null;
+    const env = {
+        ...process.env,
+        AGENTCTL_SESSION_ID: ctx.sessionId,
+        AGENTCTL_CWD: ctx.cwd,
+        AGENTCTL_ADAPTER: ctx.adapter,
+    };
+    if (ctx.branch)
+        env.AGENTCTL_BRANCH = ctx.branch;
+    if (ctx.exitCode != null)
+        env.AGENTCTL_EXIT_CODE = String(ctx.exitCode);
+    try {
+        const result = await execAsync(script, {
+            cwd: ctx.cwd,
+            env,
+            timeout: 60_000,
+        });
+        return { stdout: result.stdout, stderr: result.stderr };
+    }
+    catch (err) {
+        const e = err;
+        console.error(`Hook ${phase} failed:`, e.message);
+        return { stdout: e.stdout || "", stderr: e.stderr || "" };
+    }
+}

package/dist/merge.d.ts

@@ -0,0 +1,24 @@
+export interface MergeOpts {
+    /** Working directory of the session */
+    cwd: string;
+    /** Commit message (auto-generated if omitted) */
+    message?: string;
+    /** Whether to remove worktree after push */
+    removeWorktree?: boolean;
+    /** The main repo path (needed for worktree removal) */
+    repoPath?: string;
+}
+export interface MergeResult {
+    committed: boolean;
+    pushed: boolean;
+    prUrl?: string;
+    worktreeRemoved: boolean;
+}
+/**
+ * Merge + cleanup workflow:
+ * 1. Commit uncommitted changes
+ * 2. Push to remote
+ * 3. Open PR via `gh`
+ * 4. Optionally remove worktree
+ */
+export declare function mergeSession(opts: MergeOpts): Promise<MergeResult>;

package/dist/merge.js

@@ -0,0 +1,65 @@
+import { exec, execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+/**
+ * Merge + cleanup workflow:
+ * 1. Commit uncommitted changes
+ * 2. Push to remote
+ * 3. Open PR via `gh`
+ * 4. Optionally remove worktree
+ */
+export async function mergeSession(opts) {
+    const { cwd } = opts;
+    const result = {
+        committed: false,
+        pushed: false,
+        worktreeRemoved: false,
+    };
+    // 1. Check for uncommitted changes
+    const { stdout: status } = await execFileAsync("git", ["status", "--porcelain"], { cwd });
+    if (status.trim()) {
+        // Stage all changes and commit
+        await execFileAsync("git", ["add", "-A"], { cwd });
+        const message = opts.message || "chore: commit agent session work (via agentctl merge)";
+        await execFileAsync("git", ["commit", "-m", message], { cwd });
+        result.committed = true;
+    }
+    // 2. Get current branch name
+    const { stdout: branchRaw } = await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
+    const branch = branchRaw.trim();
+    // 3. Push to remote
+    try {
+        await execFileAsync("git", ["push", "-u", "origin", branch], { cwd });
+        result.pushed = true;
+    }
+    catch (err) {
+        console.error("Push failed:", err.message);
+        return result;
+    }
+    // 4. Open PR via gh (best effort)
+    try {
+        const { stdout: prOut } = await execAsync(`gh pr create --fill --head ${branch} 2>&1 || gh pr view --json url -q .url 2>&1`, { cwd });
+        // Extract URL from output
+        const urlMatch = prOut.match(/https:\/\/github\.com\/[^\s]+/);
+        if (urlMatch) {
+            result.prUrl = urlMatch[0];
+        }
+    }
+    catch {
+        // gh not available or PR already exists
+    }
+    // 5. Optionally remove worktree
+    if (opts.removeWorktree && opts.repoPath) {
+        try {
+            await execFileAsync("git", ["worktree", "remove", "--force", cwd], {
+                cwd: opts.repoPath,
+            });
+            result.worktreeRemoved = true;
+        }
+        catch (err) {
+            console.error("Worktree removal failed:", err.message);
+        }
+    }
+    return result;
+}

package/dist/migration/migrate-locks.d.ts

@@ -0,0 +1,5 @@
+/**
+ * One-time migration from ~/.openclaw/locks/locks.json to ~/.agentctl/locks.json.
+ * Idempotent — skips if target already exists or source is missing.
+ */
+export declare function migrateLocks(configDir?: string): Promise<number>;

package/dist/migration/migrate-locks.js

@@ -0,0 +1,41 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/**
+ * One-time migration from ~/.openclaw/locks/locks.json to ~/.agentctl/locks.json.
+ * Idempotent — skips if target already exists or source is missing.
+ */
+export async function migrateLocks(configDir) {
+    const targetDir = configDir || path.join(os.homedir(), ".agentctl");
+    const oldPath = path.join(os.homedir(), ".openclaw", "locks", "locks.json");
+    const newPath = path.join(targetDir, "locks.json");
+    // Skip if already migrated
+    if (await fileExists(newPath))
+        return 0;
+    // Skip if no old file
+    if (!(await fileExists(oldPath)))
+        return 0;
+    const oldData = JSON.parse(await fs.readFile(oldPath, "utf-8"));
+    // Transform old format → new format
+    // Old format: array of { directory, lockedBy, reason, lockedAt }
+    const newLocks = (Array.isArray(oldData) ? oldData : []).map((old) => ({
+        directory: old.directory,
+        type: "manual",
+        lockedBy: (old.lockedBy || old.by || "unknown"),
+        reason: (old.reason || ""),
+        lockedAt: old.lockedAt || new Date().toISOString(),
+    }));
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.writeFile(newPath, JSON.stringify(newLocks, null, 2));
+    console.log(`Migrated ${newLocks.length} locks from ${oldPath}`);
+    return newLocks.length;
+}
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/worktree.d.ts

@@ -0,0 +1,24 @@
+export interface WorktreeCreateOpts {
+    /** Path to the main repo (e.g. ~/code/myproject) */
+    repo: string;
+    /** Branch name (e.g. charlie/feature-name) */
+    branch: string;
+}
+export interface WorktreeInfo {
+    /** Absolute path to the worktree directory */
+    path: string;
+    /** Branch name */
+    branch: string;
+    /** The base repo path */
+    repo: string;
+}
+/**
+ * Create a git worktree for the given repo + branch.
+ * Worktree is placed at `<repo>-<branch-slug>` (sibling directory).
+ * If the worktree already exists, returns its info without creating a new one.
+ */
+export declare function createWorktree(opts: WorktreeCreateOpts): Promise<WorktreeInfo>;
+/**
+ * Remove a git worktree.
+ */
+export declare function removeWorktree(repo: string, worktreePath: string): Promise<void>;

package/dist/worktree.js

@@ -0,0 +1,65 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Create a git worktree for the given repo + branch.
+ * Worktree is placed at `<repo>-<branch-slug>` (sibling directory).
+ * If the worktree already exists, returns its info without creating a new one.
+ */
+export async function createWorktree(opts) {
+    const repoResolved = path.resolve(opts.repo);
+    const slug = opts.branch.replace(/\//g, "-");
+    const worktreePath = `${repoResolved}-${slug}`;
+    // Check if worktree already exists (check filesystem + git)
+    try {
+        // Quick filesystem check — if the .git file exists in the worktree dir, it's a worktree
+        const gitFile = path.join(worktreePath, ".git");
+        try {
+            await fs.access(gitFile);
+            return { path: worktreePath, branch: opts.branch, repo: repoResolved };
+        }
+        catch {
+            // Not on disk yet — check git's worktree list (handles symlink/realpath differences)
+        }
+        // Validate this is actually a git repo
+        await execFileAsync("git", ["rev-parse", "--git-dir"], {
+            cwd: repoResolved,
+        });
+    }
+    catch {
+        throw new Error(`Not a git repository: ${repoResolved}`);
+    }
+    // Check if branch already exists
+    let branchExists = false;
+    try {
+        await execFileAsync("git", ["rev-parse", "--verify", opts.branch], {
+            cwd: repoResolved,
+        });
+        branchExists = true;
+    }
+    catch {
+        // Branch doesn't exist yet
+    }
+    if (branchExists) {
+        // Branch exists — create worktree checking it out
+        await execFileAsync("git", ["worktree", "add", worktreePath, opts.branch], {
+            cwd: repoResolved,
+        });
+    }
+    else {
+        // Branch doesn't exist — create new branch from HEAD
+        await execFileAsync("git", ["worktree", "add", "-b", opts.branch, worktreePath], { cwd: repoResolved });
+    }
+    return { path: worktreePath, branch: opts.branch, repo: repoResolved };
+}
+/**
+ * Remove a git worktree.
+ */
+export async function removeWorktree(repo, worktreePath) {
+    const repoResolved = path.resolve(repo);
+    await execFileAsync("git", ["worktree", "remove", "--force", worktreePath], {
+        cwd: repoResolved,
+    });
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@orgloop/agentctl",
+  "version": "1.0.0",
+  "description": "Universal agent supervision interface — monitor and control AI coding agents from a single CLI",
+  "type": "module",
+  "bin": {
+    "agentctl": "./dist/cli.js",
+    "agent-ctl": "./dist/compat-shim.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/",
+    "prepare": "git config core.hooksPath .githooks"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OrgLoop/agentctl.git"
+  },
+  "homepage": "https://github.com/c-h-/agentctl#readme",
+  "bugs": {
+    "url": "https://github.com/c-h-/agentctl/issues"
+  },
+  "keywords": [
+    "cli",
+    "agent",
+    "ai",
+    "supervisor",
+    "claude",
+    "coding-agent"
+  ],
+  "author": "Charlie Hulcher <charlie.hulcher@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@types/node": "^25.2.3",
+    "commander": "^14.0.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}