@staticduo/opencode-scheduler 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Different AI
+
+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,266 @@
+# opencode-scheduler
+
+Run AI agents on a schedule. Set up recurring tasks that execute autonomously—even when you're away.
+
+```
+Schedule a daily job at 9am to search Facebook Marketplace for posters under $100 and send the top 5 deals to my Telegram
+```
+
+This is an [OpenCode](https://opencode.ai) plugin that uses your OS's native scheduler (launchd on macOS, systemd on Linux, Task Scheduler on Windows), with cron fallback where native backends are unavailable.
+
+As of `v1.2.0`, jobs are scoped by `workdir` (so different projects don't collide), and scheduled runs are supervised (no overlap + optional timeout).
+
+## Fork changes (jibanez-staticduo, published as `@staticduo/opencode-scheduler`)
+
+This fork contains three Linux/systemd fixes over upstream `v1.3.0`:
+
+1. **`cronToSystemdCalendars` emitted invalid `OnCalendar` values.** The
+   weekday component was always prefixed, even when the cron day-of-week field
+   is a wildcard, producing expressions like `* *-09-06 10:00:00`. systemd
+   does not accept `*` as a day-of-week, so every timer generated from such
+   schedules failed to parse. The fork omits the weekday prefix for wildcards
+   (e.g. `*-*-* 09:00:00`, `*-09-06 10:00:00`) and keeps generating both
+   valid variants when day-of-month and day-of-week are both fixed.
+2. **Failed systemd installs orphaned unit files.** `installSystemdJob` wrote
+   the `.service`/`.timer` units and then ran
+   `daemon-reload`/`enable`/`start`; if any of those systemctl calls failed,
+   the tool-level error handler removed the job JSON but left the unit files
+   behind (units without jobs). The fork rolls back freshly written units
+   before propagating the error, so neither units nor job JSON are orphaned.
+3. **`systemctl --user` calls inherited an incomplete environment.** When the
+   parent `opencode` process is started without `XDG_RUNTIME_DIR` (and
+   `DBUS_SESSION_BUS_ADDRESS`), every systemctl call failed with
+   `Failed to connect to bus` even though the user manager was running. All
+   systemctl invocations now go through a helper that derives
+   `XDG_RUNTIME_DIR=/run/user/<uid>` (and the bus address) when they exist.
+   Unit files are additionally written with mode `0644`, because hosts with a
+   lax umask (e.g. UGREEN NAS) generated permissions systemd complains about.
+
+Unit tests for these fixes live in `test/` (`bun test`).
+
+## Install
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["@staticduo/opencode-scheduler"]
+}
+```
+
+## Examples
+
+**Daily deal hunting:**
+```
+Schedule a daily job at 9am to search for standing desks under $300
+```
+
+**Weekly reports:**
+```
+Schedule a job every Monday at 8am to summarize my GitHub notifications
+```
+
+**Recurring reminders:**
+```
+Schedule a job every 6 hours to check if my website is up and alert me on Slack if it's down
+```
+
+## Commands
+
+| Command | Example |
+|---------|---------|
+| Schedule a job | `Schedule a daily job at 9am to...` |
+| List jobs | `Show my scheduled jobs` |
+| Get version | `Show scheduler version` |
+| Install skill template | `Install the scheduled job best practices skill` |
+| Get job | `Show details for standing-desk` |
+| Update job | `Update standing-desk to run at 10am` |
+| Run immediately | `Run the standing-desk job now` |
+| View logs | `Show logs for standing-desk` |
+| Delete | `Delete the standing-desk job` |
+| Global cleanup (dry run) | `Run scheduler global cleanup` |
+
+## How It Works
+
+1. You describe what you want scheduled in natural language
+2. The plugin writes a job file (scoped by `workdir`) and installs a timer in your OS scheduler
+3. At the scheduled time, the OS scheduler calls a small supervisor script
+4. The supervisor runs the job, appends logs, and updates job metadata
+
+You can also trigger a job immediately via `run_job`—it runs fire-and-forget and appends to the same log file.
+
+Jobs run from the working directory where you created them, picking up your `opencode.json` and MCP configurations.
+
+### Reliability Guarantees (Scheduled Runs)
+
+- **No overlap**: if the previous run is still active, the next scheduled tick is skipped.
+- **Non-interactive by default**: scheduled runs force `OPENCODE_PERMISSION` to deny "question" prompts, so jobs don't hang waiting for approvals.
+- **Optional timeout**: set `timeoutSeconds` to hard-stop long runs (SIGTERM, then SIGKILL).
+
+### Platform Support
+
+| Platform | Scheduler backend | Notes |
+|------|------|------|
+| macOS | `launchd` | Full support (supervised scheduled runs) |
+| Linux (systemd available) | `systemd --user` | Full support (supervised scheduled runs) |
+| Linux / POSIX (no systemd) | `cron` (`crontab`) | Fallback backend (no missed-run catch-up) |
+| Windows | `schtasks` (Task Scheduler) | Supported with cron subset mapping (see limits below) |
+
+Windows Task Scheduler limits:
+
+- Cron expressions that use unsupported combinations (for example, month + weekday constraints, or month-only without explicit day-of-month) return a clear error with guidance.
+- Complex cron schedules may be expanded into multiple Windows tasks under `\\OpenCode\\opencode-job-...`.
+- Windows scheduled runs currently do **not** use the supervisor pipeline used on macOS/Linux, so no-overlap and timeout enforcement are not guaranteed by the OS integration itself.
+
+---
+
+## Reference
+
+### Cron Syntax
+
+Jobs use standard 5-field cron expressions:
+
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
+│ │ │ │ │
+* * * * *
+```
+
+| Expression | Meaning |
+|------------|---------|
+| `0 9 * * *` | Daily at 9:00 AM |
+| `0 */6 * * *` | Every 6 hours |
+| `30 8 * * 1` | Mondays at 8:30 AM |
+| `0 9,17 * * *` | At 9 AM and 5 PM daily |
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `schedule_job` | Create a new scheduled job |
+| `list_jobs` | List all scheduled jobs |
+| `get_version` | Show scheduler and opencode versions |
+| `get_skill` | Get built-in skill templates (best practices) |
+| `install_skill` | Install a built-in skill into your repo |
+| `get_job` | Fetch job details and metadata |
+| `update_job` | Update an existing job |
+| `delete_job` | Remove a scheduled job |
+| `cleanup_global` | Remove scheduler artifacts across all scopes (dry-run by default) |
+| `run_job` | Execute a job immediately (fire-and-forget) |
+| `job_logs` | View the latest logs from a job |
+
+`schedule_job` and `update_job` accept an optional `timeoutSeconds` (integer seconds). Use `0` (or omit) to disable.
+
+Tools accept an optional `format: "json"` argument to return structured output with `success`, `output`, `shouldContinue`, and `data`.
+
+### Global Cleanup
+
+Use `cleanup_global` to clean scheduler artifacts across all scopes. It always starts in dry-run mode unless you pass `confirm: true`.
+
+- Dry run (safe default):
+
+```json
+{ "confirm": false }
+```
+
+- Execute global cleanup of job definitions + lock files + scheduler units:
+
+```json
+{ "confirm": true }
+```
+
+- Also delete logs and run history:
+
+```json
+{ "confirm": true, "includeHistory": true }
+```
+
+The tool reports exactly how many artifacts were removed, grouped by location (jobs, locks, logs, runs, launchd/systemd units).
+
+### Storage
+
+| What | Where |
+|------|-------|
+| Job configs (scoped) | `~/.config/opencode/scheduler/scopes/<scopeId>/jobs/*.json` |
+| Run records (scoped) | `~/.config/opencode/scheduler/scopes/<scopeId>/runs/*.jsonl` |
+| Locks (scoped) | `~/.config/opencode/scheduler/scopes/<scopeId>/locks/*.json` |
+| Logs (scoped) | `~/.config/opencode/logs/scheduler/<scopeId>/*.log` |
+| Supervisor script | `~/.config/opencode/scheduler/supervisor.pl` |
+| launchd plists (Mac) | `~/Library/LaunchAgents/com.opencode.job.<scopeId>.*.plist` |
+| systemd units (Linux) | `~/.config/systemd/user/opencode-job-<scopeId>-*.{service,timer}` |
+| Task Scheduler entries (Windows) | `\\OpenCode\\opencode-job-<scopeId>-*` |
+
+Legacy note: older versions stored jobs in `~/.config/opencode/jobs/*.json` and used unscoped unit names. `delete_job` removes both scoped and legacy artifacts.
+
+### Working Directory
+
+Jobs run from a specific directory to pick up MCP configs:
+
+```
+Schedule a daily job at 9am from /path/to/project to run my-task
+```
+
+By default, jobs use the directory where you created them.
+
+### Scopes
+
+Scopes are derived from the job's `workdir` (normalized absolute path). This isolates job storage, logs, and OS scheduler unit names per project.
+
+- `list_jobs` defaults to the **current scope** (your current working directory).
+- Use `allScopes: true` to list jobs across all scopes.
+- Use `includeLegacy: true` to include pre-`v1.2.0` jobs stored in `~/.config/opencode/jobs`.
+
+### Attach URL (optional)
+
+If you have an OpenCode backend running via `opencode serve` or `opencode web`, you can set `attachUrl` on a job so runs use that backend:
+
+```
+Update the standing-desk job to use attachUrl http://localhost:4096
+```
+
+## Project Philosophy
+
+- This plugin is intentionally a thin wrapper: it schedules `opencode run` via launchd/systemd/schtasks, with cron fallback when native backends are unavailable.
+- Logs are the source of truth for scheduled runs: `~/.config/opencode/logs/*.log`.
+- Resiliency/reporting roadmap (not implemented): `PRD-resilient-execution.md`.
+
+### Built-in Skill Templates
+
+To install the built-in skill into your project (no copy/paste), open OpenCode in your repo and run:
+
+```
+Install the scheduled job best practices skill
+```
+
+This calls the plugin’s `install_skill` tool and writes `.opencode/skill/scheduled-job-best-practices/SKILL.md`.
+
+(If you prefer, you can also say: `Get skill from opencode-scheduler and add it to my skills`.)
+
+Then add `@scheduled-job-best-practices` at the top of scheduled job prompts.
+
+(Manual option: use `get_skill` to fetch `scheduled-job-best-practices` and copy it into `.opencode/skill/scheduled-job-best-practices/SKILL.md`.)
+
+## Troubleshooting
+
+**Jobs not running?**
+
+1. Check if installed:
+   - Mac: `launchctl list | grep opencode`
+   - Linux: `systemctl --user list-timers | grep opencode`
+   - Windows: `schtasks /Query /TN "\\OpenCode\\opencode-job-*"`
+
+2. Check logs: `Show logs for my-job`
+
+3. Verify the working directory has the right `opencode.json` with MCP configs
+
+**MCP tools not available?**
+
+Make sure the job's working directory contains an `opencode.json` with your MCP server configurations.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * OpenCode Scheduler Plugin
+ *
+ * Schedule recurring jobs using launchd (Mac), systemd (Linux), schtasks (Windows), or cron fallback.
+ * Jobs are stored under ~/.config/opencode/scheduler/ (scoped by workdir).
+ *
+ * Features:
+ * - Survives reboots
+ * - Catches up on missed runs (if computer was asleep)
+ * - Cross-platform (Mac + Linux + Windows)
+ * - Working directory support for MCP configs
+ * - Environment variable injection (PATH for node/npx)
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+import { execSync } from "child_process";
+declare function jobFilePath(scopeId: string, slug: string): string;
+type OpencodeRunFormat = "default" | "json";
+interface JobRunSpec {
+    prompt?: string;
+    command?: string;
+    arguments?: string;
+    files?: string[];
+    agent?: string;
+    model?: string;
+    variant?: string;
+    title?: string;
+    share?: boolean;
+    continue?: boolean;
+    session?: string;
+    runFormat?: OpencodeRunFormat;
+    attachUrl?: string;
+    port?: number;
+}
+type JobInvocation = {
+    command: string;
+    args: string[];
+};
+interface Job {
+    scopeId?: string;
+    slug: string;
+    name: string;
+    schedule: string;
+    prompt?: string;
+    attachUrl?: string;
+    run?: JobRunSpec;
+    invocation?: JobInvocation;
+    timeoutSeconds?: number;
+    source?: string;
+    workdir?: string;
+    createdAt: string;
+    updatedAt?: string;
+    lastRunAt?: string;
+    lastRunExitCode?: number;
+    lastRunError?: string;
+    lastRunSource?: "manual" | "scheduled";
+    lastRunStatus?: "running" | "success" | "failed";
+}
+declare function cronToSystemdCalendars(cron: string): string[];
+declare function withSystemdRuntimeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+declare function systemdRunEnv(): NodeJS.ProcessEnv;
+type SystemdCommandRunner = (command: string, options?: Parameters<typeof execSync>[1]) => ReturnType<typeof execSync>;
+declare function createSystemdTimer(job: Job): string;
+declare function installSystemdJob(job: Job): void;
+declare function uninstallSystemdJob(job: Job): void;
+declare function saveJob(job: Job): void;
+declare function deleteJobFile(job: Job): void;
+export declare const SchedulerPlugin: Plugin;
+export default SchedulerPlugin;
+export type { SystemdCommandRunner };
+export declare const __test__: {
+    cronToSystemdCalendars: typeof cronToSystemdCalendars;
+    createSystemdTimer: typeof createSystemdTimer;
+    withSystemdRuntimeEnv: typeof withSystemdRuntimeEnv;
+    systemdRunEnv: typeof systemdRunEnv;
+    installSystemdJob: typeof installSystemdJob;
+    uninstallSystemdJob: typeof uninstallSystemdJob;
+    saveJob: typeof saveJob;
+    deleteJobFile: typeof deleteJobFile;
+    jobFilePath: typeof jobFilePath;
+    SYSTEMD_USER_DIR: string;
+    SCOPES_DIR: string;
+    setSystemdCommandRunner(runner: SystemdCommandRunner | null): void;
+};