@geckom/opencode-queue 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geckom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# opencode-queue
+
+[![Buy Me A Coffee](https://img.shields.io/badge/Support-Buy%20Me%20A%20Coffee-yellow?logo=buymeacoffee)](https://buymeacoffee.com/geckom)
+
+An [OpenCode](https://opencode.ai) plugin that maintains a global task queue and processes queued work when OpenCode is idle.
+
+## Architecture
+
+The source is split into focused modules under `src/`, while the runtime deploy still ends up as a single bundled plugin file for OpenCode.
+
+- `src/plugin.ts` wires hooks and tools
+- `src/queue-manager.ts` owns `queue.json` persistence and serialized state transitions
+- `src/queue-processor.ts` runs the queue/session state machine
+- `src/schedule-manager.ts` owns cron jobs and delegates persisted mutations back to `QueueManager`
+- `src/testing.ts` exposes a test-only surface used by compiled-output tests
+
+## How it works
+
+The plugin stores a shared queue in `~/.config/opencode/queue.json`. When OpenCode is idle, one process-wide queue processor picks the next pending item, creates or resumes a session for it, and monitors progress. Blocked items (permission requests, questions) hold the queue until resolved. Completed work enters a review state before final close-out.
+
+### Features
+
+- **Queue management tools** — add, list, confirm, follow up, remove, and retry items
+- **Idle processing** — automatically starts the next queued task when OpenCode is idle
+- **Permission and question handling** — detects blocked sessions and auto-resumes when you respond through any opencode interface
+- **Review gate** — finished work enters `review_pending` state for human sign-off before marking complete
+- **Task dependencies** — parent-child relationships with configurable dependency modes
+- **Retry with backoff** — transient processing errors requeue items as pending with increasing retry delays
+- **Blocked reminders** — time-based reminder toasts for blocked queue items
+- **Scheduled tasks** — one-off (run once at a specific time) or recurring (cron-based) scheduled items that automatically prepend to the front of the queue
+- **Schedule management** — pause, resume, and remove scheduled tasks; automatic auto-disable after a configurable number of occurrences
+- **Corruption-safe queue store handling** — preserves broken `queue.json` contents for recovery instead of silently resetting state
+- **Hot-reload config** — change queue settings without restarting OpenCode
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `queue-add` | Add a task to the queue |
+| `queue-list` | List queue items, with optional status filter and view modes |
+| `queue-confirm` | Mark a `review_pending` item as complete |
+| `queue-followup` | Send a follow-up message on a `review_pending` item |
+| `queue-remove` | Remove a queue item |
+| `queue-retry` | Retry a failed item |
+| `queue-schedule-add` | Schedule a one-off or recurring task |
+| `queue-schedule-list` | List, pause, resume, or remove scheduled tasks |
+
+## Installation
+
+Add to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "@geckom/opencode-queue"
+  ]
+}
+```
+
+Alternatively, install directly from GitHub:
+
+```json
+{
+  "plugin": [
+    "@geckom/opencode-queue@git+https://github.com/geckom/opencode-queue.git"
+  ]
+}
+```
+
+## Configuration
+
+The queue reads its settings from `~/.config/opencode/queue.json`. Edit the `config` object there — changes apply immediately without restarting OpenCode.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `idleTimeoutSeconds` | `3600` | Seconds of inactivity before the next item is processed |
+| `blockedReminderMinutes` | `30` | Minutes between reminders for blocked items |
+| `maxRetries` | `3` | Maximum retry attempts for failed items |
+| `retryDelaysMinutes` | `[5, 10, 15]` | Delay in minutes before each retry attempt |
+| `reminderIntervalMessages` | `30` | Messages between blocked-item reminders |
+| `sessionTimeoutMinutes` | `60` | Maximum minutes to wait for a running session before marking it failed |
+
+## Development
+
+Local tests use compiled output from `dist/`, including an internal test surface for the repo test suite. That test-only surface is not exported or published as part of the package contract.
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+To deploy into your local OpenCode config:
+
+```bash
+npm run build:runtime
+```
+
+Smoke test the deployed plugin with:
+
+```bash
+opencode --print-logs debug config
+```
+
+## License
+
+MIT

package/dist/block-watcher.js

@@ -0,0 +1,137 @@
+import { QueueManager } from "./queue-manager.js";
+export class BlockWatcher {
+    queueManager;
+    client;
+    constructor(queueManager, client) {
+        this.queueManager = queueManager;
+        this.client = client;
+    }
+    async handleEvent(event) {
+        if (event.type === "permission.asked") {
+            const permission = event.properties;
+            if (!permission?.sessionID)
+                return;
+            const item = this.queueManager.listItems("running").find((candidate) => candidate.sessionId === permission.sessionID);
+            if (!item)
+                return;
+            const patterns = Array.isArray(permission.patterns) ? permission.patterns : [];
+            const details = [permission.permission, patterns.length > 0 ? `Patterns: ${patterns.join(", ")}` : null]
+                .filter(Boolean)
+                .join(" | ");
+            await this.queueManager.updateItem(item.id, {
+                status: "blocked",
+                blockedReason: {
+                    type: "permission",
+                    permissionId: typeof permission.id === "string" ? permission.id : null,
+                    requestId: typeof permission.id === "string" ? permission.id : null,
+                    details: details || "Permission request pending",
+                    options: ["once", "always", "reject"],
+                    userResponse: null,
+                },
+            });
+            return;
+        }
+        if (event.type === "question.asked") {
+            const question = event.properties;
+            if (!question?.sessionID)
+                return;
+            const item = this.queueManager.listItems("running").find((candidate) => candidate.sessionId === question.sessionID);
+            if (!item)
+                return;
+            const questions = Array.isArray(question.questions) ? question.questions : [];
+            const details = questions
+                .map((entry) => entry.question)
+                .filter((entry) => Boolean(entry))
+                .join(" | ");
+            const options = questions.flatMap((entry) => Array.isArray(entry.options)
+                ? entry.options.map((option) => option.label).filter((label) => Boolean(label))
+                : []);
+            await this.queueManager.updateItem(item.id, {
+                status: "blocked",
+                blockedReason: {
+                    type: "question",
+                    permissionId: null,
+                    requestId: typeof question.id === "string" ? question.id : null,
+                    details: details || "Question pending",
+                    options: options.length > 0 ? options : null,
+                    userResponse: null,
+                },
+            });
+        }
+    }
+    async checkForBlocks(item) {
+        if (!item.sessionId)
+            return false;
+        if (item.status === "blocked")
+            return true;
+        const q = { directory: item.workspace };
+        try {
+            const { data: messages } = await this.client.session.messages({
+                path: { id: item.sessionId },
+                query: q,
+            });
+            if (!messages)
+                return false;
+            for (const msg of messages) {
+                for (const part of msg.parts) {
+                    if (part.type === "tool" && part.tool === "question" && part.state.status === "pending") {
+                        const input = part.state.input;
+                        await this.queueManager.updateItem(item.id, {
+                            status: "blocked",
+                            blockedReason: {
+                                type: "question",
+                                permissionId: null,
+                                requestId: null,
+                                details: String(input.text || input.message || input.question || JSON.stringify(input)),
+                                options: Array.isArray(input.options) ? input.options.map(String) : null,
+                                userResponse: null,
+                            },
+                        });
+                        return true;
+                    }
+                }
+            }
+            const { data: statusMap } = await this.client.session.status({ query: q });
+            if (statusMap) {
+                for (const [, sessionStatus] of Object.entries(statusMap)) {
+                    if (sessionStatus?.type === "idle") {
+                        return false;
+                    }
+                }
+            }
+        }
+        catch { }
+        return false;
+    }
+    async respondToBlock(item, response) {
+        if (!item.blockedReason || !item.sessionId)
+            return false;
+        const q = { directory: item.workspace };
+        try {
+            if (item.blockedReason.type === "permission" && item.blockedReason.permissionId) {
+                const normalized = response.toLowerCase();
+                const allowAlways = normalized === "always";
+                const allowOnce = normalized === "yes" || normalized === "allow" || normalized === "once";
+                const reject = normalized === "no" || normalized === "reject";
+                await this.client.postSessionIdPermissionsPermissionId({
+                    path: { id: item.sessionId, permissionID: item.blockedReason.permissionId },
+                    body: { response: reject ? "reject" : allowAlways ? "always" : allowOnce ? "once" : "once" },
+                    query: q,
+                });
+            }
+            else {
+                await this.client.session.prompt({
+                    path: { id: item.sessionId },
+                    query: q,
+                    body: {
+                        parts: [{ type: "text", text: response }],
+                    },
+                });
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/constants.js

@@ -0,0 +1,25 @@
+import { join } from "path";
+export const CONFIG_DIR = process.env.XDG_CONFIG_HOME || join(process.env.HOME, ".config");
+export const OPENCODE_DIR = join(CONFIG_DIR, "opencode");
+export const QUEUE_FILE = join(OPENCODE_DIR, "queue.json");
+export const QUEUE_CORRUPTION_MARKER_FILE = join(OPENCODE_DIR, "queue.json.corrupt");
+export const LAST_ACTIVITY_FILE = join(OPENCODE_DIR, "queue.last-activity");
+export const LOCK_FILE = join(OPENCODE_DIR, "queue.lock");
+export const STORE_LOCK_FILE = join(OPENCODE_DIR, "queue.store.lock");
+export const PROCESSING_LOCK_STALE_MS = 120_000;
+export const PROCESSING_LOCK_REFRESH_MS = 30_000;
+export const STORE_LOCK_STALE_MS = 15_000;
+export const STORE_LOCK_RETRY_MS = 50;
+export const STORE_LOCK_WAIT_MS = 5_000;
+export const SIGNAL_EXIT_CODE = {
+    SIGINT: 130,
+    SIGTERM: 143,
+};
+export const DEFAULT_CONFIG = {
+    idleTimeoutSeconds: 3600,
+    blockedReminderMinutes: 30,
+    maxRetries: 3,
+    retryDelaysMinutes: [5, 10, 15],
+    reminderIntervalMessages: 30,
+    sessionTimeoutMinutes: 60,
+};

package/dist/file-lock.js

@@ -0,0 +1,106 @@
+/**
+ * File-based locking is the only concurrency primitive used by this plugin.
+ * All persisted queue state mutations must flow through this helper.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { randomUUID } from "crypto";
+import { CONFIG_DIR, LOCK_FILE, OPENCODE_DIR, PROCESSING_LOCK_REFRESH_MS, PROCESSING_LOCK_STALE_MS, } from "./constants.js";
+import { sleep } from "./utils.js";
+void CONFIG_DIR;
+const LOCK_OWNERS = new Map();
+export class FileLock {
+    static isFresh(lockFile = LOCK_FILE, staleMs = PROCESSING_LOCK_STALE_MS) {
+        try {
+            if (!existsSync(lockFile))
+                return false;
+            const stat = statSync(lockFile);
+            return Date.now() - stat.mtimeMs <= staleMs;
+        }
+        catch {
+            return false;
+        }
+    }
+    static async acquire(lockFile = LOCK_FILE, staleMs = PROCESSING_LOCK_STALE_MS) {
+        try {
+            if (!existsSync(OPENCODE_DIR)) {
+                mkdirSync(OPENCODE_DIR, { recursive: true });
+            }
+            if (existsSync(lockFile)) {
+                const stat = statSync(lockFile);
+                if (Date.now() - stat.mtimeMs > staleMs) {
+                    unlinkSync(lockFile);
+                }
+                else {
+                    return false;
+                }
+            }
+            const owner = `${process.pid}:${randomUUID()}`;
+            const fd = openSync(lockFile, "wx");
+            try {
+                writeFileSync(fd, `${owner}\n${Date.now()}`, "utf-8");
+            }
+            finally {
+                closeSync(fd);
+            }
+            LOCK_OWNERS.set(lockFile, owner);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    static refresh(lockFile = LOCK_FILE) {
+        try {
+            const owner = LOCK_OWNERS.get(lockFile);
+            if (!owner)
+                return;
+            if (!existsSync(OPENCODE_DIR)) {
+                mkdirSync(OPENCODE_DIR, { recursive: true });
+            }
+            writeFileSync(lockFile, `${owner}\n${Date.now()}`, "utf-8");
+        }
+        catch { }
+    }
+    static startHeartbeat(lockFile = LOCK_FILE, refreshMs = PROCESSING_LOCK_REFRESH_MS) {
+        const timer = setInterval(() => {
+            this.refresh(lockFile);
+        }, refreshMs);
+        timer.unref?.();
+        return timer;
+    }
+    static stopHeartbeat(timer) {
+        if (timer) {
+            clearInterval(timer);
+        }
+    }
+    static release(lockFile = LOCK_FILE) {
+        try {
+            const owner = LOCK_OWNERS.get(lockFile);
+            if (!owner)
+                return;
+            if (existsSync(lockFile)) {
+                const currentOwner = readFileSync(lockFile, "utf-8").split("\n", 1)[0];
+                if (currentOwner === owner) {
+                    unlinkSync(lockFile);
+                }
+            }
+        }
+        catch { }
+        LOCK_OWNERS.delete(lockFile);
+    }
+    static async withLock(lockFile, staleMs, retryMs, timeoutMs, work) {
+        const deadline = Date.now() + timeoutMs;
+        while (!(await this.acquire(lockFile, staleMs))) {
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out acquiring lock: ${lockFile}`);
+            }
+            await sleep(retryMs);
+        }
+        try {
+            return await work();
+        }
+        finally {
+            this.release(lockFile);
+        }
+    }
+}

package/dist/formatters.js

@@ -0,0 +1,108 @@
+export function formatScheduledTask(schedule) {
+    const kind = schedule.scheduledFor ? "one-off" : "recurring";
+    const status = schedule.enabled ? "enabled" : "disabled";
+    let line = `[${status.toUpperCase()}] ${schedule.id.substring(0, 8)} (${kind}) ${schedule.goal.substring(0, 80)}`;
+    if (schedule.scheduledFor)
+        line += `\nScheduled: ${schedule.scheduledFor}`;
+    if (schedule.cronExpression)
+        line += `\nCron: ${schedule.cronExpression}`;
+    line += `\nTimezone: ${schedule.timezone}`;
+    if (schedule.nextTriggerAt)
+        line += `\nNext: ${schedule.nextTriggerAt}`;
+    if (schedule.lastTriggeredAt)
+        line += `\nLast: ${schedule.lastTriggeredAt}`;
+    line += `\nOccurrences: ${schedule.occurrenceCount}`;
+    if (schedule.maxOccurrences !== null)
+        line += ` / ${schedule.maxOccurrences}`;
+    if (schedule.parentItemId)
+        line += `\nDepends: ${schedule.parentItemId.substring(0, 8)} @ ${schedule.dependencyMode}`;
+    return line;
+}
+export function formatQueueItemSummary(item) {
+    let line = `[${item.status.toUpperCase()}] ${item.id.substring(0, 8)} ${item.goal.substring(0, 80)}`;
+    if (item.parentItemId)
+        line += `\nDepends: ${item.parentItemId.substring(0, 8)} @ ${item.dependencyMode}`;
+    if (item.dependencyBlockedReason && item.status === "pending") {
+        line += `\nWaiting: ${item.dependencyBlockedReason.substring(0, 160)}`;
+    }
+    if (item.staleDependency)
+        line += `\nStale: Parent changed after this item became eligible`;
+    if (item.status === "blocked" && item.blockedReason) {
+        line += `\nBlocked: ${item.blockedReason.details.substring(0, 160)}`;
+    }
+    if (item.status === "review_pending" && item.result) {
+        line += `\nReview: ${item.result.substring(0, 160)}`;
+    }
+    if (item.status === "completed" && item.result) {
+        line += `\nResult: ${item.result.substring(0, 160)}`;
+    }
+    if (item.status === "failed" && item.error) {
+        line += `\nError: ${item.error.substring(0, 160)}`;
+    }
+    return line;
+}
+export function formatQueueItemFull(item) {
+    let output = `ID: ${item.id}\nStatus: ${item.status}\nGoal: ${item.goal}\nWorkspace: ${item.workspace}`;
+    if (item.parentItemId)
+        output += `\nParent: ${item.parentItemId}`;
+    output += `\nDependency Mode: ${item.dependencyMode}`;
+    if (item.dependencySatisfiedAt)
+        output += `\nDependency Satisfied: ${item.dependencySatisfiedAt}`;
+    if (item.dependencySourceStatus)
+        output += `\nDependency Source: ${item.dependencySourceStatus}`;
+    if (item.dependencyBlockedReason)
+        output += `\nDependency Waiting: ${item.dependencyBlockedReason}`;
+    if (item.staleDependency)
+        output += `\nStale Dependency: true`;
+    output += `\nCreated: ${item.createdAt}`;
+    if (item.startedAt)
+        output += `\nStarted: ${item.startedAt}`;
+    if (item.completedAt)
+        output += `\nCompleted: ${item.completedAt}`;
+    if (item.reviewedAt)
+        output += `\nReviewed: ${item.reviewedAt}`;
+    if (item.sessionId)
+        output += `\nSession: ${item.sessionId}`;
+    if (item.sessionUrl)
+        output += `\nURL: ${item.sessionUrl}`;
+    if (item.retryCount > 0)
+        output += `\nRetries: ${item.retryCount}`;
+    if (item.nextRetryAt)
+        output += `\nNext Retry: ${item.nextRetryAt}`;
+    if (item.blockedReason)
+        output += `\nBlocked (${item.blockedReason.type}): ${item.blockedReason.details}`;
+    if (item.status === "review_pending" && item.result)
+        output += `\nReview Result: ${item.result}`;
+    else if (item.result)
+        output += `\nResult: ${item.result}`;
+    if (item.error)
+        output += `\nError: ${item.error}`;
+    return output;
+}
+export async function formatQueueItemLog(client, item) {
+    if (!item.sessionId)
+        return `No session for item ${item.id}.`;
+    const output = `Session: ${item.sessionId}\nURL: ${item.sessionUrl || "N/A"}`;
+    try {
+        const { data: messages } = await client.session.messages({
+            path: { id: item.sessionId },
+            query: { directory: item.workspace },
+        });
+        if (!messages || messages.length === 0) {
+            return `${output}\n\n(No messages)`;
+        }
+        const lines = [];
+        for (const msg of messages.slice(-4)) {
+            const role = msg.info.role;
+            const textParts = msg.parts.filter((part) => part.type === "text");
+            for (const part of textParts) {
+                const text = part.text;
+                lines.push(`[${role}] ${text.substring(0, 300)}`);
+            }
+        }
+        return lines.length > 0 ? `${output}\n\n${lines.join("\n\n")}` : `${output}\n\n(No text messages)`;
+    }
+    catch {
+        return `${output}\n\n(Could not fetch messages)`;
+    }
+}

package/dist/idle-detector.js

@@ -0,0 +1,49 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { LAST_ACTIVITY_FILE, OPENCODE_DIR } from "./constants.js";
+/**
+ * IdleDetector is intentionally filesystem-backed so all plugin instances share
+ * the same notion of activity.
+ */
+export class IdleDetector {
+    timer = null;
+    getConfig;
+    onIdle;
+    constructor(getConfig, onIdle) {
+        this.getConfig = getConfig;
+        this.onIdle = onIdle;
+    }
+    start() {
+        this.writeActivity();
+        this.timer = setInterval(() => void this.checkIdle(), 30_000);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    writeActivity() {
+        try {
+            if (!existsSync(OPENCODE_DIR)) {
+                mkdirSync(OPENCODE_DIR, { recursive: true });
+            }
+            writeFileSync(LAST_ACTIVITY_FILE, Date.now().toString(), "utf-8");
+        }
+        catch { }
+    }
+    async checkIdle() {
+        try {
+            if (!existsSync(LAST_ACTIVITY_FILE)) {
+                await this.onIdle();
+                return;
+            }
+            const lastActivity = Number.parseInt(readFileSync(LAST_ACTIVITY_FILE, "utf-8").trim(), 10);
+            const elapsed = Date.now() - lastActivity;
+            if (elapsed >= this.getConfig().idleTimeoutSeconds * 1000) {
+                await this.onIdle();
+            }
+        }
+        catch { }
+    }
+}

package/dist/index.js

@@ -0,0 +1 @@
+export { OpencodeQueuePlugin as default } from "./plugin.js";

package/dist/opencode-queue.js

@@ -0,0 +1 @@
+export { OpencodeQueuePlugin as default } from "./plugin.js";