@colinmollenhour/occtl 1.0.0

package/dist/sse.js

@@ -0,0 +1,128 @@
+import { getBaseUrl } from "./client.js";
+/**
+ * Extract the session ID from an event, checking all known locations.
+ */
+export function getEventSessionId(event) {
+    const props = event.properties;
+    const sid = props.sessionID ??
+        props.info?.sessionID ??
+        props.info?.id ??
+        props.part?.sessionID ??
+        undefined;
+    return sid || undefined; // treat empty string as undefined
+}
+/**
+ * Check if an SSE event belongs to a given session.
+ */
+export function isSessionEvent(event, sessionId) {
+    return getEventSessionId(event) === sessionId;
+}
+/**
+ * Connect to the OpenCode SSE event stream and invoke a callback for each
+ * parsed event that matches the given session.
+ *
+ * Returns "stopped" if the callback returned "stop", or "disconnected" if
+ * the stream ended unexpectedly.
+ */
+export async function streamEvents(sessionId, onEvent) {
+    return streamAllEvents((event) => {
+        if (!isSessionEvent(event, sessionId))
+            return;
+        return onEvent(event);
+    });
+}
+/**
+ * Connect to the SSE stream and return a handle with cancel + connected signal.
+ * This is the low-level version for callers that need to coordinate startup.
+ */
+export function startStream(sessionId, onEvent) {
+    return startAllStream((event) => {
+        if (!isSessionEvent(event, sessionId))
+            return;
+        return onEvent(event);
+    });
+}
+/**
+ * Start an SSE stream (unfiltered) and return a handle with cancel + connected signal.
+ */
+export function startAllStream(onEvent) {
+    let cancelFn = () => { };
+    let resolveConnected;
+    const connected = new Promise((r) => {
+        resolveConnected = r;
+    });
+    const result = (async () => {
+        const url = `${getBaseUrl()}/event`;
+        let response;
+        try {
+            response = await fetch(url, {
+                headers: { Accept: "text/event-stream" },
+            });
+        }
+        catch {
+            resolveConnected();
+            return "disconnected";
+        }
+        if (!response.ok || !response.body) {
+            resolveConnected();
+            return "disconnected";
+        }
+        const reader = response.body.getReader();
+        cancelFn = () => reader.cancel().catch(() => { });
+        // Signal that the connection is established
+        resolveConnected();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let stoppedCleanly = false;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    if (!line.startsWith("data: "))
+                        continue;
+                    const data = line.slice(6);
+                    if (data === "[DONE]")
+                        continue;
+                    let event;
+                    try {
+                        event = JSON.parse(data);
+                    }
+                    catch {
+                        // Skip unparseable SSE data
+                        continue;
+                    }
+                    try {
+                        const cbResult = await onEvent(event);
+                        if (cbResult === "stop") {
+                            stoppedCleanly = true;
+                            reader.cancel().catch(() => { });
+                            return "stopped";
+                        }
+                    }
+                    catch (err) {
+                        // Log callback errors to stderr instead of swallowing
+                        console.error(`[occtl] SSE callback error: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+        }
+        finally {
+            reader.cancel().catch(() => { });
+        }
+        return stoppedCleanly ? "stopped" : "disconnected";
+    })();
+    return { result, cancel: () => cancelFn(), connected };
+}
+/**
+ * Connect to the SSE stream and invoke callback for ALL events (unfiltered).
+ * Returns "stopped" or "disconnected".
+ */
+export async function streamAllEvents(onEvent) {
+    const handle = startAllStream(onEvent);
+    return handle.result;
+}

package/dist/wait-util.d.ts

@@ -0,0 +1,23 @@
+import type { OpencodeClient } from "@opencode-ai/sdk";
+export interface WaitResult {
+    /** Whether the session is confirmed idle. */
+    idle: boolean;
+    /** How it was determined: "api" (status check), "sse" (event), "disconnected" (stream lost). */
+    reason: "api" | "sse" | "disconnected" | "timeout";
+}
+/**
+ * Race-safe wait for a session to go idle. Starts the SSE stream, waits for
+ * the connection to establish, then checks the API. This eliminates the gap
+ * where the session could go idle between the check and the stream starting.
+ */
+export declare function waitForIdle(client: OpencodeClient, sessionId: string, timeoutMs?: number): Promise<WaitResult>;
+export interface WaitAnyResult {
+    /** The session ID that went idle first (empty string if timeout/disconnect). */
+    sessionID: string;
+    /** How it was determined. */
+    reason: "api" | "sse" | "disconnected" | "timeout";
+}
+/**
+ * Race-safe wait for any of multiple sessions to go idle.
+ */
+export declare function waitForAnyIdle(client: OpencodeClient, sessionIds: string[], timeoutMs?: number): Promise<WaitAnyResult>;

package/dist/wait-util.js

@@ -0,0 +1,118 @@
+import { startStream, startAllStream, getEventSessionId } from "./sse.js";
+/**
+ * Race-safe wait for a session to go idle. Starts the SSE stream, waits for
+ * the connection to establish, then checks the API. This eliminates the gap
+ * where the session could go idle between the check and the stream starting.
+ */
+export async function waitForIdle(client, sessionId, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            handle.cancel();
+            resolve(result);
+        };
+        // Timeout
+        let timer;
+        if (timeoutMs && timeoutMs > 0) {
+            timer = setTimeout(() => {
+                settle({ idle: false, reason: "timeout" });
+            }, timeoutMs);
+        }
+        // Start SSE stream
+        const handle = startStream(sessionId, (event) => {
+            if (event.type === "session.idle") {
+                settle({ idle: true, reason: "sse" });
+                return "stop";
+            }
+        });
+        // When stream ends unexpectedly
+        handle.result.then((streamResult) => {
+            if (!settled && streamResult === "disconnected") {
+                settle({ idle: false, reason: "disconnected" });
+            }
+        });
+        // After SSE is connected, check current status via API
+        handle.connected.then(async () => {
+            if (settled)
+                return;
+            try {
+                const statusResult = await client.session.status();
+                const statuses = statusResult.data ?? {};
+                const current = statuses[sessionId];
+                if (!current || current.type === "idle") {
+                    settle({ idle: true, reason: "api" });
+                }
+            }
+            catch {
+                // API check failed; rely on SSE stream
+            }
+        });
+    });
+}
+/**
+ * Race-safe wait for any of multiple sessions to go idle.
+ */
+export async function waitForAnyIdle(client, sessionIds, timeoutMs) {
+    const watchSet = new Set(sessionIds);
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            handle.cancel();
+            resolve(result);
+        };
+        // Timeout
+        let timer;
+        if (timeoutMs && timeoutMs > 0) {
+            timer = setTimeout(() => {
+                settle({ sessionID: "", reason: "timeout" });
+            }, timeoutMs);
+        }
+        // Start SSE stream (unfiltered, watching multiple sessions)
+        const handle = startAllStream((event) => {
+            if (event.type !== "session.idle")
+                return;
+            const sid = getEventSessionId(event);
+            if (!sid || !watchSet.has(sid))
+                return;
+            settle({ sessionID: sid, reason: "sse" });
+            return "stop";
+        });
+        // When stream ends unexpectedly
+        handle.result.then((streamResult) => {
+            if (!settled && streamResult === "disconnected") {
+                settle({ sessionID: "", reason: "disconnected" });
+            }
+        });
+        // After SSE is connected, check current status via API
+        handle.connected.then(async () => {
+            if (settled)
+                return;
+            try {
+                const statusResult = await client.session.status();
+                const statuses = statusResult.data ?? {};
+                for (const sid of sessionIds) {
+                    if (settled)
+                        return;
+                    const current = statuses[sid];
+                    if (!current || current.type === "idle") {
+                        settle({ sessionID: sid, reason: "api" });
+                        return;
+                    }
+                }
+            }
+            catch {
+                // API check failed; rely on SSE stream
+            }
+        });
+    });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@colinmollenhour/occtl",
+  "version": "1.0.0",
+  "description": "Extended CLI for managing OpenCode sessions",
+  "keywords": [
+    "opencode",
+    "cli",
+    "session",
+    "automation",
+    "ralph-loop",
+    "ai-agent",
+    "orchestration"
+  ],
+  "homepage": "https://github.com/colinmollenhour/occtl#readme",
+  "bugs": {
+    "url": "https://github.com/colinmollenhour/occtl/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/colinmollenhour/occtl.git"
+  },
+  "license": "MIT",
+  "author": "Colin Mollenhour",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "occtl": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@opencode-ai/sdk": "^1.3.0",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  }
+}