@orgloop/agentctl 1.0.0

package/dist/client/daemon-client.d.ts

@@ -0,0 +1,6 @@
+export declare class DaemonClient {
+    private sockPath;
+    constructor(sockPath?: string);
+    call<T>(method: string, params?: unknown): Promise<T>;
+    isRunning(): Promise<boolean>;
+}

package/dist/client/daemon-client.js

@@ -0,0 +1,81 @@
+import crypto from "node:crypto";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_SOCK_PATH = path.join(os.homedir(), ".agentctl", "agentctl.sock");
+export class DaemonClient {
+    sockPath;
+    constructor(sockPath) {
+        this.sockPath = sockPath || DEFAULT_SOCK_PATH;
+    }
+    async call(method, params) {
+        return new Promise((resolve, reject) => {
+            const socket = net.createConnection(this.sockPath);
+            const id = crypto.randomUUID();
+            let buffer = "";
+            let settled = false;
+            const timeout = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    socket.destroy();
+                    reject(new Error("Daemon request timed out"));
+                }
+            }, 30_000);
+            socket.on("connect", () => {
+                socket.write(`${JSON.stringify({ id, method, params })}\n`);
+            });
+            socket.on("data", (chunk) => {
+                buffer += chunk.toString();
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                for (const line of lines) {
+                    if (!line)
+                        continue;
+                    try {
+                        const msg = JSON.parse(line);
+                        if (msg.id === id && !msg.stream) {
+                            settled = true;
+                            clearTimeout(timeout);
+                            if (msg.error)
+                                reject(new Error(msg.error.message));
+                            else
+                                resolve(msg.result);
+                            socket.end();
+                        }
+                    }
+                    catch {
+                        // Malformed response
+                    }
+                }
+            });
+            socket.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                if (err.code === "ENOENT" || err.code === "ECONNREFUSED") {
+                    reject(new Error("Daemon not running. Start with: agentctl daemon start"));
+                }
+                else {
+                    reject(err);
+                }
+            });
+            socket.on("close", () => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timeout);
+                    reject(new Error("Connection closed before response received"));
+                }
+            });
+        });
+    }
+    async isRunning() {
+        try {
+            await this.call("daemon.status");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/compat-shim.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/compat-shim.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+console.error("\u26a0\ufe0f  agent-ctl is renamed to agentctl. Please update your scripts.");
+const __filename = fileURLToPath(import.meta.url);
+const agentctlBin = path.join(path.dirname(__filename), "cli.js");
+try {
+    execFileSync(process.execPath, [agentctlBin, ...process.argv.slice(2)], {
+        stdio: "inherit",
+    });
+}
+catch (err) {
+    process.exit(err.status ?? 1);
+}

package/dist/core/types.d.ts

@@ -0,0 +1,68 @@
+export interface AgentAdapter {
+    id: string;
+    list(opts?: ListOpts): Promise<AgentSession[]>;
+    peek(sessionId: string, opts?: PeekOpts): Promise<string>;
+    status(sessionId: string): Promise<AgentSession>;
+    launch(opts: LaunchOpts): Promise<AgentSession>;
+    stop(sessionId: string, opts?: StopOpts): Promise<void>;
+    resume(sessionId: string, message: string): Promise<void>;
+    events(): AsyncIterable<LifecycleEvent>;
+}
+export interface AgentSession {
+    id: string;
+    adapter: string;
+    status: "running" | "idle" | "stopped" | "error";
+    startedAt: Date;
+    stoppedAt?: Date;
+    cwd?: string;
+    spec?: string;
+    model?: string;
+    prompt?: string;
+    tokens?: {
+        in: number;
+        out: number;
+    };
+    cost?: number;
+    pid?: number;
+    meta: Record<string, unknown>;
+}
+export interface LifecycleEvent {
+    type: "session.started" | "session.stopped" | "session.idle" | "session.error";
+    adapter: string;
+    sessionId: string;
+    session: AgentSession;
+    timestamp: Date;
+    meta?: Record<string, unknown>;
+}
+export interface ListOpts {
+    status?: "running" | "idle" | "stopped" | "error";
+    all?: boolean;
+}
+export interface PeekOpts {
+    lines?: number;
+}
+export interface StopOpts {
+    force?: boolean;
+}
+export interface LaunchOpts {
+    adapter: string;
+    prompt: string;
+    spec?: string;
+    cwd?: string;
+    model?: string;
+    env?: Record<string, string>;
+    adapterOpts?: Record<string, unknown>;
+    /** Git worktree options — auto-create worktree before launch */
+    worktree?: {
+        repo: string;
+        branch: string;
+    };
+    /** Lifecycle hooks — shell commands to run at various points */
+    hooks?: LifecycleHooks;
+}
+export interface LifecycleHooks {
+    onCreate?: string;
+    onComplete?: string;
+    preMerge?: string;
+    postMerge?: string;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+// agentctl core types — Universal Agent Supervision Interface
+export {};

package/dist/daemon/fuse-engine.d.ts

@@ -0,0 +1,30 @@
+import type { EventEmitter } from "node:events";
+import type { FuseTimer, SessionRecord, StateManager } from "./state.js";
+export interface FuseEngineOpts {
+    defaultDurationMs: number;
+    emitter?: EventEmitter;
+}
+export declare class FuseEngine {
+    private timers;
+    private state;
+    private defaultDurationMs;
+    private emitter?;
+    constructor(state: StateManager, opts: FuseEngineOpts);
+    /** Derive cluster name from worktree directory. Returns null if not a mono worktree. */
+    static deriveClusterName(directory: string): {
+        clusterName: string;
+        branch: string;
+    } | null;
+    /** Called when a session exits. Starts fuse if applicable. */
+    onSessionExit(session: SessionRecord): void;
+    private startFuse;
+    /** Cancel fuse for a directory. */
+    cancelFuse(directory: string, persist?: boolean): boolean;
+    /** Resume fuses from persisted state after daemon restart. */
+    resumeTimers(): void;
+    /** Fire a fuse — delete the Kind cluster. */
+    private fireFuse;
+    listActive(): FuseTimer[];
+    /** Clear all timers (for clean shutdown) */
+    shutdown(): void;
+}

package/dist/daemon/fuse-engine.js

@@ -0,0 +1,118 @@
+import { exec } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+export class FuseEngine {
+    timers = new Map();
+    state;
+    defaultDurationMs;
+    emitter;
+    constructor(state, opts) {
+        this.state = state;
+        this.defaultDurationMs = opts.defaultDurationMs;
+        this.emitter = opts.emitter;
+    }
+    /** Derive cluster name from worktree directory. Returns null if not a mono worktree. */
+    static deriveClusterName(directory) {
+        const home = os.homedir();
+        const monoPrefix = path.join(home, "code", "mono-");
+        if (!directory.startsWith(monoPrefix))
+            return null;
+        const branch = directory.slice(monoPrefix.length);
+        if (!branch)
+            return null;
+        return {
+            clusterName: `kindo-charlie-${branch}`,
+            branch,
+        };
+    }
+    /** Called when a session exits. Starts fuse if applicable. */
+    onSessionExit(session) {
+        if (!session.cwd)
+            return;
+        const derived = FuseEngine.deriveClusterName(session.cwd);
+        if (!derived)
+            return;
+        this.startFuse(session.cwd, derived.clusterName, derived.branch, session.id);
+    }
+    startFuse(directory, clusterName, branch, sessionId) {
+        // Cancel existing fuse for same directory
+        this.cancelFuse(directory, false);
+        const expiresAt = new Date(Date.now() + this.defaultDurationMs);
+        const fuse = {
+            directory,
+            clusterName,
+            branch,
+            expiresAt: expiresAt.toISOString(),
+            sessionId,
+        };
+        this.state.addFuse(fuse);
+        const timeout = setTimeout(() => this.fireFuse(fuse), this.defaultDurationMs);
+        this.timers.set(directory, timeout);
+    }
+    /** Cancel fuse for a directory. */
+    cancelFuse(directory, persist = true) {
+        const timer = this.timers.get(directory);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(directory);
+        }
+        if (persist) {
+            this.state.removeFuse(directory);
+        }
+        return !!timer;
+    }
+    /** Resume fuses from persisted state after daemon restart. */
+    resumeTimers() {
+        const fuses = this.state.getFuses();
+        const now = Date.now();
+        for (const fuse of fuses) {
+            const remaining = new Date(fuse.expiresAt).getTime() - now;
+            if (remaining <= 0) {
+                // Expired while daemon was down — fire immediately
+                this.fireFuse(fuse);
+            }
+            else {
+                const timeout = setTimeout(() => this.fireFuse(fuse), remaining);
+                this.timers.set(fuse.directory, timeout);
+            }
+        }
+    }
+    /** Fire a fuse — delete the Kind cluster. */
+    async fireFuse(fuse) {
+        this.timers.delete(fuse.directory);
+        this.state.removeFuse(fuse.directory);
+        console.log(`Fuse fired: deleting cluster ${fuse.clusterName}`);
+        try {
+            // Best effort: yarn local:down first
+            try {
+                await execAsync("yarn local:down", {
+                    cwd: fuse.directory,
+                    timeout: 60_000,
+                });
+            }
+            catch {
+                // Ignore
+            }
+            await execAsync(`kind delete cluster --name ${fuse.clusterName}`, {
+                timeout: 120_000,
+            });
+            console.log(`Cluster ${fuse.clusterName} deleted`);
+            this.emitter?.emit("fuse.fired", fuse);
+        }
+        catch (err) {
+            console.error(`Failed to delete cluster ${fuse.clusterName}:`, err);
+        }
+    }
+    listActive() {
+        return this.state.getFuses();
+    }
+    /** Clear all timers (for clean shutdown) */
+    shutdown() {
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+    }
+}

package/dist/daemon/launchagent.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generate a LaunchAgent plist with dynamically resolved paths.
+ */
+export declare function generatePlist(opts?: {
+    nodePath?: string;
+    cliPath?: string;
+}): string;

package/dist/daemon/launchagent.js

@@ -0,0 +1,49 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Generate a LaunchAgent plist with dynamically resolved paths.
+ */
+export function generatePlist(opts) {
+    const home = os.homedir();
+    const nodePath = opts?.nodePath || process.execPath;
+    const cliPath = opts?.cliPath ||
+        path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
+    // Normalize to absolute
+    const resolvedCliPath = path.resolve(cliPath);
+    // Get PATH including node's bin dir
+    const nodeBinDir = path.dirname(nodePath);
+    const envPath = `/usr/local/bin:/usr/bin:/bin:${nodeBinDir}`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.agentctl.daemon</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodePath}</string>
+        <string>${resolvedCliPath}</string>
+        <string>daemon</string>
+        <string>start</string>
+        <string>--foreground</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${home}/.agentctl/daemon.stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>${home}/.agentctl/daemon.stderr.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${envPath}</string>
+        <key>HOME</key>
+        <string>${home}</string>
+    </dict>
+</dict>
+</plist>
+`;
+}

package/dist/daemon/lock-manager.d.ts

@@ -0,0 +1,16 @@
+import type { Lock, StateManager } from "./state.js";
+export declare class LockManager {
+    private state;
+    constructor(state: StateManager);
+    /** Check if directory is locked. Returns the lock if so, null if free. */
+    check(directory: string): Lock | null;
+    /** Auto-lock a directory for a session. Idempotent if same session. */
+    autoLock(directory: string, sessionId: string): Lock;
+    /** Remove auto-lock for a session. */
+    autoUnlock(sessionId: string): void;
+    /** Manual lock. Fails if already manually locked. */
+    manualLock(directory: string, by?: string, reason?: string): Lock;
+    /** Manual unlock. Only removes manual locks. */
+    manualUnlock(directory: string): void;
+    listAll(): Lock[];
+}

package/dist/daemon/lock-manager.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+export class LockManager {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    /** Check if directory is locked. Returns the lock if so, null if free. */
+    check(directory) {
+        const resolved = path.resolve(directory);
+        const locks = this.state.getLocks();
+        // Manual locks take precedence
+        const manual = locks.find((l) => l.directory === resolved && l.type === "manual");
+        if (manual)
+            return manual;
+        const auto = locks.find((l) => l.directory === resolved && l.type === "auto");
+        return auto || null;
+    }
+    /** Auto-lock a directory for a session. Idempotent if same session. */
+    autoLock(directory, sessionId) {
+        const resolved = path.resolve(directory);
+        const existing = this.state
+            .getLocks()
+            .find((l) => l.directory === resolved &&
+            l.type === "auto" &&
+            l.sessionId === sessionId);
+        if (existing)
+            return existing;
+        const lock = {
+            directory: resolved,
+            type: "auto",
+            sessionId,
+            lockedAt: new Date().toISOString(),
+        };
+        this.state.addLock(lock);
+        return lock;
+    }
+    /** Remove auto-lock for a session. */
+    autoUnlock(sessionId) {
+        this.state.removeLocks((l) => l.type === "auto" && l.sessionId === sessionId);
+    }
+    /** Manual lock. Fails if already manually locked. */
+    manualLock(directory, by, reason) {
+        const resolved = path.resolve(directory);
+        const existing = this.check(resolved);
+        if (existing?.type === "manual") {
+            throw new Error(`Already manually locked by ${existing.lockedBy}: ${existing.reason}`);
+        }
+        const lock = {
+            directory: resolved,
+            type: "manual",
+            lockedBy: by,
+            reason,
+            lockedAt: new Date().toISOString(),
+        };
+        this.state.addLock(lock);
+        return lock;
+    }
+    /** Manual unlock. Only removes manual locks. */
+    manualUnlock(directory) {
+        const resolved = path.resolve(directory);
+        const existing = this.state
+            .getLocks()
+            .find((l) => l.directory === resolved && l.type === "manual");
+        if (!existing)
+            throw new Error(`No manual lock on ${resolved}`);
+        this.state.removeLocks((l) => l.directory === resolved && l.type === "manual");
+    }
+    listAll() {
+        return this.state.getLocks();
+    }
+}

package/dist/daemon/metrics.d.ts

@@ -0,0 +1,20 @@
+import type { FuseEngine } from "./fuse-engine.js";
+import type { LockManager } from "./lock-manager.js";
+import type { SessionTracker } from "./session-tracker.js";
+export declare class MetricsRegistry {
+    private sessionTracker;
+    private lockManager;
+    private fuseEngine;
+    sessionsTotalCompleted: number;
+    sessionsTotalFailed: number;
+    sessionsTotalStopped: number;
+    fusesFiredTotal: number;
+    clustersDeletedTotal: number;
+    sessionDurations: number[];
+    constructor(sessionTracker: SessionTracker, lockManager: LockManager, fuseEngine: FuseEngine);
+    recordSessionCompleted(durationSeconds?: number): void;
+    recordSessionFailed(durationSeconds?: number): void;
+    recordSessionStopped(durationSeconds?: number): void;
+    recordFuseFired(): void;
+    generateMetrics(): string;
+}

package/dist/daemon/metrics.js

@@ -0,0 +1,72 @@
+export class MetricsRegistry {
+    sessionTracker;
+    lockManager;
+    fuseEngine;
+    sessionsTotalCompleted = 0;
+    sessionsTotalFailed = 0;
+    sessionsTotalStopped = 0;
+    fusesFiredTotal = 0;
+    clustersDeletedTotal = 0;
+    sessionDurations = []; // seconds
+    constructor(sessionTracker, lockManager, fuseEngine) {
+        this.sessionTracker = sessionTracker;
+        this.lockManager = lockManager;
+        this.fuseEngine = fuseEngine;
+    }
+    recordSessionCompleted(durationSeconds) {
+        this.sessionsTotalCompleted++;
+        if (durationSeconds != null)
+            this.sessionDurations.push(durationSeconds);
+    }
+    recordSessionFailed(durationSeconds) {
+        this.sessionsTotalFailed++;
+        if (durationSeconds != null)
+            this.sessionDurations.push(durationSeconds);
+    }
+    recordSessionStopped(durationSeconds) {
+        this.sessionsTotalStopped++;
+        if (durationSeconds != null)
+            this.sessionDurations.push(durationSeconds);
+    }
+    recordFuseFired() {
+        this.fusesFiredTotal++;
+        this.clustersDeletedTotal++;
+    }
+    generateMetrics() {
+        const lines = [];
+        const g = (name, help, value, labels) => {
+            lines.push(`# HELP ${name} ${help}`);
+            lines.push(`# TYPE ${name} gauge`);
+            lines.push(labels ? `${name}{${labels}} ${value}` : `${name} ${value}`);
+        };
+        const c = (name, help, value, labels) => {
+            lines.push(`# HELP ${name} ${help}`);
+            lines.push(`# TYPE ${name} counter`);
+            lines.push(labels ? `${name}{${labels}} ${value}` : `${name} ${value}`);
+        };
+        // Gauges
+        g("agentctl_sessions_active", "Number of active sessions", this.sessionTracker.activeCount());
+        const locks = this.lockManager.listAll();
+        g("agentctl_locks_active", "Number of active locks", locks.filter((l) => l.type === "auto").length, 'type="auto"');
+        g("agentctl_locks_active", "Number of active locks", locks.filter((l) => l.type === "manual").length, 'type="manual"');
+        g("agentctl_fuses_active", "Number of active fuse timers", this.fuseEngine.listActive().length);
+        // Counters
+        c("agentctl_sessions_total", "Total sessions by status", this.sessionsTotalCompleted, 'status="completed"');
+        c("agentctl_sessions_total", "Total sessions by status", this.sessionsTotalFailed, 'status="failed"');
+        c("agentctl_sessions_total", "Total sessions by status", this.sessionsTotalStopped, 'status="stopped"');
+        c("agentctl_fuses_fired_total", "Total fuses fired", this.fusesFiredTotal);
+        c("agentctl_kind_clusters_deleted_total", "Total Kind clusters deleted", this.clustersDeletedTotal);
+        // Histogram (session duration)
+        lines.push("# HELP agentctl_session_duration_seconds Session duration histogram");
+        lines.push("# TYPE agentctl_session_duration_seconds histogram");
+        const buckets = [60, 300, 600, 1800, 3600, 7200, Number.POSITIVE_INFINITY];
+        for (const b of buckets) {
+            const count = this.sessionDurations.filter((d) => d <= b).length;
+            const label = b === Number.POSITIVE_INFINITY ? "+Inf" : String(b);
+            lines.push(`agentctl_session_duration_seconds_bucket{le="${label}"} ${count}`);
+        }
+        lines.push(`agentctl_session_duration_seconds_sum ${this.sessionDurations.reduce((a, b) => a + b, 0)}`);
+        lines.push(`agentctl_session_duration_seconds_count ${this.sessionDurations.length}`);
+        return `${lines.join("\n")}\n`;
+    }
+}

package/dist/daemon/server.d.ts

@@ -0,0 +1,33 @@
+import http from "node:http";
+import net from "node:net";
+import type { AgentAdapter } from "../core/types.js";
+export interface DaemonRequest {
+    id: string;
+    method: string;
+    params?: unknown;
+}
+export interface DaemonResponse {
+    id: string;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface DaemonStatus {
+    pid: number;
+    uptime: number;
+    sessions: number;
+    locks: number;
+    fuses: number;
+}
+export interface DaemonStartOpts {
+    metricsPort?: number;
+    configDir?: string;
+    adapters?: Record<string, AgentAdapter>;
+}
+export declare function startDaemon(opts?: DaemonStartOpts): Promise<{
+    socketServer: net.Server;
+    httpServer: http.Server;
+    shutdown: () => Promise<void>;
+}>;