@lawrence369/loop-cli 0.1.0

package/dist/bus/message.js

@@ -0,0 +1,129 @@
+import { join } from "node:path";
+import { nextSeq } from "../utils/lock.js";
+import { appendJsonl } from "../utils/fs.js";
+import { QueueManager } from "./queue.js";
+/**
+ * Manages message creation, routing, and delivery.
+ *
+ * Target resolution order:
+ *   1. Exact subscriber ID match (e.g. "claude:abc123")
+ *   2. Nickname match (e.g. "claude-1")
+ *   3. Agent type match (e.g. "claude" -> all active claude agents)
+ *   4. Broadcast ("*" -> all active agents)
+ */
+export class MessageManager {
+    eventsDir;
+    seqFile;
+    seqLockFile;
+    subscriberManager;
+    queueManager;
+    constructor(busDir, subscriberManager) {
+        this.eventsDir = join(busDir, "events");
+        this.seqFile = join(busDir, "seq.counter");
+        this.seqLockFile = join(busDir, "seq.counter.lock");
+        this.subscriberManager = subscriberManager;
+        this.queueManager = new QueueManager(busDir);
+    }
+    /**
+     * Get the next monotonically increasing sequence number.
+     */
+    async nextSeq() {
+        return nextSeq(this.seqFile, this.seqLockFile);
+    }
+    /**
+     * Resolve a target string to a list of subscriber IDs.
+     *
+     * Resolution order:
+     *   1. Exact subscriber ID match
+     *   2. Nickname match
+     *   3. Agent type match (all active agents of that type)
+     *   4. Broadcast "*" (all active agents)
+     */
+    async resolveTarget(target) {
+        const agents = await this.subscriberManager.list();
+        // 1. Exact subscriber ID match
+        if (agents.has(target)) {
+            return [target];
+        }
+        // 2. If contains ":", treat as subscriber ID even if not in registry
+        if (target.includes(":")) {
+            return [target];
+        }
+        // 3. Nickname match
+        for (const [id, meta] of agents) {
+            if (meta.nickname === target && meta.status === "active") {
+                return [id];
+            }
+        }
+        // 4. Agent type match
+        const byType = [];
+        for (const [id, meta] of agents) {
+            if (meta.agent_type === target && meta.status === "active") {
+                byType.push(id);
+            }
+        }
+        if (byType.length > 0) {
+            return byType;
+        }
+        // 5. Broadcast
+        if (target === "*") {
+            const all = [];
+            for (const [id, meta] of agents) {
+                if (meta.status === "active") {
+                    all.push(id);
+                }
+            }
+            return all;
+        }
+        return [];
+    }
+    /**
+     * Route an event to its target subscribers' queues.
+     */
+    async route(event) {
+        const targets = await this.resolveTarget(event.target);
+        for (const subscriberId of targets) {
+            // Check offset to avoid re-delivering already-consumed events
+            const offset = await this.queueManager.getOffset(subscriberId);
+            if (event.seq > offset) {
+                await this.queueManager.enqueue(subscriberId, event);
+            }
+        }
+    }
+    /**
+     * Create and persist a new event, then route it to targets.
+     * Returns the created event.
+     */
+    async createEvent(publisher, target, data, type = "message/targeted") {
+        const seq = await this.nextSeq();
+        const timestamp = new Date().toISOString();
+        const date = timestamp.slice(0, 10);
+        // Resolve to verify target exists
+        const targets = await this.resolveTarget(target);
+        if (targets.length === 0) {
+            throw new Error(`Target "${target}" not found`);
+        }
+        const event = {
+            seq,
+            timestamp,
+            type,
+            event: data.message !== undefined ? "message" : "event",
+            publisher,
+            target,
+            data,
+        };
+        // Write to the event log
+        const eventFile = join(this.eventsDir, `${date}.jsonl`);
+        await appendJsonl(eventFile, event);
+        // Route to target queues
+        await this.route(event);
+        return event;
+    }
+    /**
+     * Get the queue manager (needed by EventBus for consume operations).
+     */
+    getQueueManager() {
+        return this.queueManager;
+    }
+}
+//# sourceMappingURL=message.js.map

package/dist/bus/queue.d.ts

@@ -0,0 +1,50 @@
+import type { BusEvent } from "./event-bus.js";
+/**
+ * Manages per-subscriber message queues.
+ *
+ * Each subscriber has a directory under `bus/queues/{safeName}/`
+ * containing a `pending.jsonl` file with queued events.
+ */
+export declare class QueueManager {
+    readonly busDir: string;
+    private readonly queuesDir;
+    private readonly offsetsDir;
+    constructor(busDir: string);
+    /**
+     * Enqueue an event for a subscriber.
+     */
+    enqueue(subscriberId: string, event: BusEvent): Promise<void>;
+    /**
+     * Dequeue all pending events for a subscriber (read and clear).
+     */
+    dequeue(subscriberId: string): Promise<BusEvent[]>;
+    /**
+     * Peek at pending events without removing them.
+     */
+    peek(subscriberId: string): Promise<BusEvent[]>;
+    /**
+     * Clear all pending events for a subscriber.
+     */
+    clear(subscriberId: string): Promise<void>;
+    /**
+     * Ensure the queue directory exists for a subscriber.
+     */
+    ensureQueue(subscriberId: string): Promise<void>;
+    /**
+     * Get the path to a subscriber's pending file.
+     */
+    getPendingPath(subscriberId: string): string;
+    /**
+     * Get the path to a subscriber's queue directory.
+     */
+    getQueueDir(subscriberId: string): string;
+    /**
+     * Get the consumption offset for a subscriber.
+     */
+    getOffset(subscriberId: string): Promise<number>;
+    /**
+     * Set the consumption offset for a subscriber.
+     */
+    setOffset(subscriberId: string, seq: number): Promise<void>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/bus/queue.js

@@ -0,0 +1,100 @@
+import { join } from "node:path";
+import { ensureDir, appendJsonl, readJsonl, truncateFile } from "../utils/fs.js";
+import { subscriberToSafeName } from "./store.js";
+/**
+ * Manages per-subscriber message queues.
+ *
+ * Each subscriber has a directory under `bus/queues/{safeName}/`
+ * containing a `pending.jsonl` file with queued events.
+ */
+export class QueueManager {
+    busDir;
+    queuesDir;
+    offsetsDir;
+    constructor(busDir) {
+        this.busDir = busDir;
+        this.queuesDir = join(busDir, "queues");
+        this.offsetsDir = join(busDir, "offsets");
+    }
+    /**
+     * Enqueue an event for a subscriber.
+     */
+    async enqueue(subscriberId, event) {
+        await this.ensureQueue(subscriberId);
+        const pendingPath = this.getPendingPath(subscriberId);
+        await appendJsonl(pendingPath, event);
+    }
+    /**
+     * Dequeue all pending events for a subscriber (read and clear).
+     */
+    async dequeue(subscriberId) {
+        const pendingPath = this.getPendingPath(subscriberId);
+        const events = await readJsonl(pendingPath);
+        if (events.length > 0) {
+            await truncateFile(pendingPath);
+        }
+        return events;
+    }
+    /**
+     * Peek at pending events without removing them.
+     */
+    async peek(subscriberId) {
+        const pendingPath = this.getPendingPath(subscriberId);
+        return readJsonl(pendingPath);
+    }
+    /**
+     * Clear all pending events for a subscriber.
+     */
+    async clear(subscriberId) {
+        const pendingPath = this.getPendingPath(subscriberId);
+        await truncateFile(pendingPath);
+    }
+    /**
+     * Ensure the queue directory exists for a subscriber.
+     */
+    async ensureQueue(subscriberId) {
+        const safeName = subscriberToSafeName(subscriberId);
+        await ensureDir(join(this.queuesDir, safeName));
+    }
+    /**
+     * Get the path to a subscriber's pending file.
+     */
+    getPendingPath(subscriberId) {
+        const safeName = subscriberToSafeName(subscriberId);
+        return join(this.queuesDir, safeName, "pending.jsonl");
+    }
+    /**
+     * Get the path to a subscriber's queue directory.
+     */
+    getQueueDir(subscriberId) {
+        const safeName = subscriberToSafeName(subscriberId);
+        return join(this.queuesDir, safeName);
+    }
+    /**
+     * Get the consumption offset for a subscriber.
+     */
+    async getOffset(subscriberId) {
+        const safeName = subscriberToSafeName(subscriberId);
+        const offsetPath = join(this.offsetsDir, `${safeName}.offset`);
+        try {
+            const { readFile } = await import("node:fs/promises");
+            const content = await readFile(offsetPath, "utf8");
+            const parsed = parseInt(content.trim(), 10);
+            return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Set the consumption offset for a subscriber.
+     */
+    async setOffset(subscriberId, seq) {
+        const safeName = subscriberToSafeName(subscriberId);
+        const offsetPath = join(this.offsetsDir, `${safeName}.offset`);
+        await ensureDir(this.offsetsDir);
+        const { writeFile } = await import("node:fs/promises");
+        await writeFile(offsetPath, `${seq}\n`, "utf8");
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/bus/store.d.ts

@@ -0,0 +1,88 @@
+import type { BusEvent } from "./event-bus.js";
+import type { AgentMetadata } from "./subscriber.js";
+/**
+ * File-backed store for the event bus.
+ *
+ * Layout under `<project>/.loop/`:
+ *   bus/events/{YYYY-MM-DD}.jsonl   - append-only event log
+ *   bus/queues/{subscriberId}/
+ *     pending.jsonl                 - pending messages per subscriber
+ *     tty                           - agent TTY path
+ *   bus/offsets/{subscriberId}.offset - consumption offset
+ *   bus/seq.counter                 - monotonic sequence number
+ *   bus/seq.counter.lock            - file lock for counter
+ *   agents/all-agents.json          - agent registry
+ */
+export declare class BusStore {
+    readonly busDir: string;
+    readonly eventsDir: string;
+    readonly queuesDir: string;
+    readonly offsetsDir: string;
+    readonly agentsDir: string;
+    readonly agentsFile: string;
+    readonly seqCounterPath: string;
+    readonly seqLockPath: string;
+    readonly runDir: string;
+    private _eventCount;
+    constructor(busDir: string);
+    /**
+     * Ensure all required directories exist.
+     */
+    init(): Promise<void>;
+    /**
+     * Append an event to the daily event log.
+     */
+    appendEvent(event: BusEvent): Promise<void>;
+    /**
+     * Append an event to a subscriber's pending queue.
+     */
+    appendToQueue(subscriberId: string, event: BusEvent): Promise<void>;
+    /**
+     * Read and clear a subscriber's pending queue (atomic drain).
+     */
+    consumeQueue(subscriberId: string): Promise<BusEvent[]>;
+    /**
+     * Read a subscriber's pending queue without clearing it.
+     */
+    peekQueue(subscriberId: string): Promise<BusEvent[]>;
+    /**
+     * Get a subscriber's consumption offset.
+     */
+    getOffset(subscriberId: string): Promise<number>;
+    /**
+     * Set a subscriber's consumption offset.
+     */
+    setOffset(subscriberId: string, seq: number): Promise<void>;
+    /**
+     * Load the agents registry.
+     */
+    loadAgents(): Promise<Map<string, AgentMetadata>>;
+    /**
+     * Save the agents registry.
+     */
+    saveAgents(agents: Map<string, AgentMetadata>): Promise<void>;
+    /**
+     * Count total events across all event log files.
+     * Uses a cached counter when available (warm path).
+     */
+    countEvents(): Promise<number>;
+    /**
+     * Scan all event log files on disk and return the total event count.
+     */
+    private _countEventsFromDisk;
+    /**
+     * Ensure a subscriber's queue directory exists.
+     */
+    ensureQueue(subscriberId: string): Promise<void>;
+}
+/**
+ * Convert a subscriber ID to a safe directory name.
+ * Replaces ":" with "_" so it can be used in file paths.
+ */
+export declare function subscriberToSafeName(subscriberId: string): string;
+/**
+ * Convert a safe directory name back to a subscriber ID.
+ * Replaces the first "_" with ":" to reconstruct the original format.
+ */
+export declare function safeNameToSubscriber(safeName: string): string;
+//# sourceMappingURL=store.d.ts.map

package/dist/bus/store.js

@@ -0,0 +1,212 @@
+import { join } from "node:path";
+import { ensureDir, appendJsonl, readJsonl, safeWriteFile, safeReadFile, fileExists } from "../utils/fs.js";
+/**
+ * File-backed store for the event bus.
+ *
+ * Layout under `<project>/.loop/`:
+ *   bus/events/{YYYY-MM-DD}.jsonl   - append-only event log
+ *   bus/queues/{subscriberId}/
+ *     pending.jsonl                 - pending messages per subscriber
+ *     tty                           - agent TTY path
+ *   bus/offsets/{subscriberId}.offset - consumption offset
+ *   bus/seq.counter                 - monotonic sequence number
+ *   bus/seq.counter.lock            - file lock for counter
+ *   agents/all-agents.json          - agent registry
+ */
+export class BusStore {
+    busDir;
+    eventsDir;
+    queuesDir;
+    offsetsDir;
+    agentsDir;
+    agentsFile;
+    seqCounterPath;
+    seqLockPath;
+    runDir;
+    _eventCount = 0;
+    constructor(busDir) {
+        this.busDir = busDir;
+        // Bus subdirectories live under busDir
+        this.eventsDir = join(busDir, "events");
+        this.queuesDir = join(busDir, "queues");
+        this.offsetsDir = join(busDir, "offsets");
+        this.seqCounterPath = join(busDir, "seq.counter");
+        this.seqLockPath = join(busDir, "seq.counter.lock");
+        // Agents directory is a sibling of bus/ under .loop/
+        const loopDir = join(busDir, "..");
+        this.agentsDir = join(loopDir, "agents");
+        this.agentsFile = join(this.agentsDir, "all-agents.json");
+        this.runDir = join(loopDir, "run");
+    }
+    /**
+     * Ensure all required directories exist.
+     */
+    async init() {
+        await Promise.all([
+            ensureDir(this.eventsDir),
+            ensureDir(this.queuesDir),
+            ensureDir(this.offsetsDir),
+            ensureDir(this.agentsDir),
+            ensureDir(this.runDir),
+        ]);
+        // Create the agents file if it doesn't exist
+        if (!(await fileExists(this.agentsFile))) {
+            const initial = {
+                created_at: new Date().toISOString(),
+                agents: {},
+            };
+            await safeWriteFile(this.agentsFile, JSON.stringify(initial, null, 2) + "\n");
+        }
+        // Initialize event count cache from disk
+        this._eventCount = await this._countEventsFromDisk();
+    }
+    /**
+     * Append an event to the daily event log.
+     */
+    async appendEvent(event) {
+        const date = event.timestamp.slice(0, 10); // YYYY-MM-DD
+        const filePath = join(this.eventsDir, `${date}.jsonl`);
+        await appendJsonl(filePath, event);
+        this._eventCount++;
+    }
+    /**
+     * Append an event to a subscriber's pending queue.
+     */
+    async appendToQueue(subscriberId, event) {
+        const safeName = subscriberToSafeName(subscriberId);
+        const queueDir = join(this.queuesDir, safeName);
+        await ensureDir(queueDir);
+        const pendingPath = join(queueDir, "pending.jsonl");
+        await appendJsonl(pendingPath, event);
+    }
+    /**
+     * Read and clear a subscriber's pending queue (atomic drain).
+     */
+    async consumeQueue(subscriberId) {
+        const safeName = subscriberToSafeName(subscriberId);
+        const pendingPath = join(this.queuesDir, safeName, "pending.jsonl");
+        const events = await readJsonl(pendingPath);
+        if (events.length > 0) {
+            // Truncate the file after reading
+            await safeWriteFile(pendingPath, "");
+        }
+        return events;
+    }
+    /**
+     * Read a subscriber's pending queue without clearing it.
+     */
+    async peekQueue(subscriberId) {
+        const safeName = subscriberToSafeName(subscriberId);
+        const pendingPath = join(this.queuesDir, safeName, "pending.jsonl");
+        return readJsonl(pendingPath);
+    }
+    /**
+     * Get a subscriber's consumption offset.
+     */
+    async getOffset(subscriberId) {
+        const safeName = subscriberToSafeName(subscriberId);
+        const offsetPath = join(this.offsetsDir, `${safeName}.offset`);
+        const content = await safeReadFile(offsetPath);
+        if (content === null)
+            return 0;
+        const parsed = parseInt(content.trim(), 10);
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+    }
+    /**
+     * Set a subscriber's consumption offset.
+     */
+    async setOffset(subscriberId, seq) {
+        const safeName = subscriberToSafeName(subscriberId);
+        const offsetPath = join(this.offsetsDir, `${safeName}.offset`);
+        await ensureDir(this.offsetsDir);
+        await safeWriteFile(offsetPath, `${seq}\n`);
+    }
+    /**
+     * Load the agents registry.
+     */
+    async loadAgents() {
+        const content = await safeReadFile(this.agentsFile);
+        if (content === null)
+            return new Map();
+        try {
+            const data = JSON.parse(content);
+            const agents = data.agents ?? {};
+            return new Map(Object.entries(agents));
+        }
+        catch {
+            return new Map();
+        }
+    }
+    /**
+     * Save the agents registry.
+     */
+    async saveAgents(agents) {
+        const existing = await safeReadFile(this.agentsFile);
+        let data;
+        try {
+            data = existing ? JSON.parse(existing) : { created_at: new Date().toISOString(), agents: {} };
+        }
+        catch {
+            data = { created_at: new Date().toISOString(), agents: {} };
+        }
+        data.agents = Object.fromEntries(agents);
+        await safeWriteFile(this.agentsFile, JSON.stringify(data, null, 2) + "\n");
+    }
+    /**
+     * Count total events across all event log files.
+     * Uses a cached counter when available (warm path).
+     */
+    async countEvents() {
+        if (this._eventCount > 0)
+            return this._eventCount;
+        this._eventCount = await this._countEventsFromDisk();
+        return this._eventCount;
+    }
+    /**
+     * Scan all event log files on disk and return the total event count.
+     */
+    async _countEventsFromDisk() {
+        const { readdir, readFile } = await import("node:fs/promises");
+        let total = 0;
+        try {
+            const files = await readdir(this.eventsDir);
+            for (const file of files) {
+                if (!file.endsWith(".jsonl"))
+                    continue;
+                const content = await readFile(join(this.eventsDir, file), "utf8");
+                const lines = content.trim().split("\n").filter(Boolean);
+                total += lines.length;
+            }
+        }
+        catch {
+            // Events dir may not exist yet
+        }
+        return total;
+    }
+    /**
+     * Ensure a subscriber's queue directory exists.
+     */
+    async ensureQueue(subscriberId) {
+        const safeName = subscriberToSafeName(subscriberId);
+        await ensureDir(join(this.queuesDir, safeName));
+    }
+}
+/**
+ * Convert a subscriber ID to a safe directory name.
+ * Replaces ":" with "_" so it can be used in file paths.
+ */
+export function subscriberToSafeName(subscriberId) {
+    // Strip path separators and traversal sequences to prevent directory escape
+    return subscriberId.replace(/:/g, "_").replace(/[/\\]/g, "").replace(/\.\./g, "");
+}
+/**
+ * Convert a safe directory name back to a subscriber ID.
+ * Replaces the first "_" with ":" to reconstruct the original format.
+ */
+export function safeNameToSubscriber(safeName) {
+    const idx = safeName.indexOf("_");
+    if (idx === -1)
+        return safeName;
+    return safeName.slice(0, idx) + ":" + safeName.slice(idx + 1);
+}
+//# sourceMappingURL=store.js.map

package/dist/bus/subscriber.d.ts

@@ -0,0 +1,76 @@
+import { BusStore } from "./store.js";
+/**
+ * Metadata tracked for each agent on the bus.
+ */
+export interface AgentMetadata {
+    agent_type: string;
+    nickname: string;
+    status: "active" | "inactive";
+    joined_at: string;
+    last_seen: string;
+    pid: number;
+    tty?: string;
+    tmux_pane?: string;
+    launch_mode: string;
+    activity_state: string;
+    last_activity?: string;
+}
+/**
+ * Manages subscriber registration, lifecycle, and metadata.
+ *
+ * Subscriber IDs follow the format `{agentType}:{randomId}`,
+ * e.g. "claude:abc12345".
+ */
+export declare class SubscriberManager {
+    private store;
+    private agents;
+    constructor(store: BusStore);
+    /**
+     * Load agent data from disk into memory.
+     */
+    load(): Promise<void>;
+    /**
+     * Persist agent data to disk.
+     */
+    save(): Promise<void>;
+    /**
+     * Register a new agent on the bus.
+     * Returns the generated subscriber ID.
+     */
+    register(agentType: string, metadata?: Partial<AgentMetadata>): Promise<string>;
+    /**
+     * Unregister an agent, marking it as inactive.
+     */
+    unregister(subscriberId: string): Promise<void>;
+    /**
+     * Rename a subscriber's nickname.
+     */
+    rename(subscriberId: string, nickname: string): Promise<void>;
+    /**
+     * Update specific metadata fields for a subscriber.
+     */
+    updateMetadata(subscriberId: string, updates: Partial<AgentMetadata>): Promise<void>;
+    /**
+     * Clean up subscribers whose processes are no longer alive.
+     * Returns the list of subscriber IDs that were marked inactive.
+     */
+    cleanupInactive(): Promise<string[]>;
+    /**
+     * List all agents (both active and inactive).
+     */
+    list(): Promise<Map<string, AgentMetadata>>;
+    /**
+     * Get metadata for a specific subscriber.
+     */
+    get(subscriberId: string): Promise<AgentMetadata | undefined>;
+    /**
+     * Generate a unique auto-nickname for the given agent type.
+     * Format: {prefix}-{N} where N is the lowest unused integer.
+     */
+    private generateNickname;
+    /**
+     * Get the nickname prefix for a given agent type.
+     */
+    private nicknamePrefix;
+}
+//# sourceMappingURL=subscriber.d.ts.map