heartbeat-opencode-plugin 0.1.0

package/scheduler/index.ts

@@ -0,0 +1,966 @@
+import * as fs from "fs";
+import * as path from "path";
+import {
+  execFileSync,
+  spawn,
+} from "child_process";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+import { type Plugin, tool } from "@opencode-ai/plugin";
+import {
+  getBunPath,
+  getDefaultWorkdir,
+  getJobsDir,
+  getLaunchdLabel as getConfigLaunchdLabel,
+  getLogFilePath,
+  getLogsDir,
+  loadConfig,
+} from "../config";
+import { appendLog } from "../memory";
+
+type JobKind = "opencode" | "command";
+type RunStatus = "running" | "success" | "failed" | "skipped";
+
+export interface Job {
+  id: string;
+  name: string;
+  kind: JobKind;
+  schedule: string;
+  prompt?: string;
+  command: string;
+  args: string[];
+  workdir: string;
+  enabled: boolean;
+  createdAt: string;
+  updatedAt?: string;
+  lastRunAt?: string;
+  lastRunStatus?: RunStatus;
+  lastRunExitCode?: number;
+  lastRunError?: string;
+}
+
+export interface CreateCommandJobInput {
+  name: string;
+  schedule: string;
+  command: string;
+  args?: string[];
+  workdir?: string;
+  enabled?: boolean;
+}
+
+export interface CreateOpencodeJobInput {
+  name: string;
+  schedule: string;
+  prompt: string;
+  workdir?: string;
+  enabled?: boolean;
+}
+
+export interface RunResult {
+  jobId: string;
+  status: RunStatus;
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  exitCode: number | null;
+  signal: string | null;
+  error?: string;
+}
+
+const IS_MAC = process.platform === "darwin";
+const LAUNCH_AGENTS_DIR = path.join(homedir(), "Library", "LaunchAgents");
+const SCHEDULER_ENTRY = fileURLToPath(import.meta.url);
+
+function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function isoNow(): string {
+  return new Date().toISOString();
+}
+
+function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+
+  if (slug) return slug;
+  return `job-${Date.now()}`;
+}
+
+function jobFilePath(jobId: string): string {
+  return path.join(getJobsDir(), `${jobId}.json`);
+}
+
+function sharedLogPath(): string {
+  return getLogFilePath();
+}
+
+function appendJobLog(job: Pick<Job, "id">, message: string): void {
+  appendLog(`[Scheduler][job:${job.id}] ${message}`);
+}
+
+function readJob(jobId: string): Job | null {
+  const file = jobFilePath(jobId);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const raw = fs.readFileSync(file, "utf-8");
+    return JSON.parse(raw) as Job;
+  } catch {
+    return null;
+  }
+}
+
+function writeJob(job: Job): void {
+  ensureDir(getJobsDir());
+  fs.writeFileSync(jobFilePath(job.id), JSON.stringify(job, null, 2));
+}
+
+function deleteJobFile(jobId: string): boolean {
+  const file = jobFilePath(jobId);
+  if (!fs.existsSync(file)) return false;
+  fs.unlinkSync(file);
+  return true;
+}
+
+function splitLines(chunk: string): { lines: string[]; remainder: string } {
+  const normalized = chunk.replace(/\r\n/g, "\n");
+  const parts = normalized.split("\n");
+  const remainder = parts.pop() ?? "";
+  return { lines: parts, remainder };
+}
+
+function buildHeartbeatPrompt(input: {
+  jobId: string;
+  jobName: string;
+  prompt: string;
+}): string {
+  return [
+    "You are running inside Heartbeat scheduler as a human-created cron job.",
+    `Job ID: ${input.jobId}`,
+    `Job Name: ${input.jobName}`,
+    "",
+    "Scheduler intent:",
+    "- Scheduler is only the runner. Do not create or modify scheduler jobs from this run.",
+    "- Emit clear progress lines; all output is streamed into shared memory logs.",
+    "- If needed, read previous logs using memory tools (search_memory / memory_grep).",
+    "",
+    "Run instructions:",
+    input.prompt,
+  ].join("\n");
+}
+
+function validateCron(schedule: string): void {
+  parseCronToLaunchd(schedule);
+}
+
+export function initScheduler(projectDir?: string): void {
+  loadConfig(projectDir);
+  ensureDir(getJobsDir());
+  ensureDir(getLogsDir());
+}
+
+export function listJobs(): Job[] {
+  ensureDir(getJobsDir());
+  const files = fs.readdirSync(getJobsDir()).filter((entry) => entry.endsWith(".json"));
+  return files
+    .map((entry) => {
+      try {
+        const raw = fs.readFileSync(path.join(getJobsDir(), entry), "utf-8");
+        return JSON.parse(raw) as Job;
+      } catch {
+        return null;
+      }
+    })
+    .filter((job): job is Job => Boolean(job))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getJob(jobId: string): Job | null {
+  return readJob(jobId);
+}
+
+export function createCommandJob(input: CreateCommandJobInput): Job {
+  validateCron(input.schedule);
+  const id = slugify(input.name);
+
+  if (readJob(id)) {
+    throw new Error(`Job already exists: ${id}`);
+  }
+
+  const job: Job = {
+    id,
+    name: input.name,
+    kind: "command",
+    schedule: input.schedule,
+    command: input.command,
+    args: input.args ?? [],
+    workdir: input.workdir ?? getDefaultWorkdir(),
+    enabled: input.enabled ?? true,
+    createdAt: isoNow(),
+  };
+
+  writeJob(job);
+  appendJobLog(job, `Created command job "${job.name}" schedule=${job.schedule}`);
+  return job;
+}
+
+export function createOpencodeJob(input: CreateOpencodeJobInput): Job {
+  validateCron(input.schedule);
+  const id = slugify(input.name);
+
+  if (readJob(id)) {
+    throw new Error(`Job already exists: ${id}`);
+  }
+
+  const heartbeatPrompt = buildHeartbeatPrompt({
+    jobId: id,
+    jobName: input.name,
+    prompt: input.prompt,
+  });
+
+  const job: Job = {
+    id,
+    name: input.name,
+    kind: "opencode",
+    schedule: input.schedule,
+    prompt: input.prompt,
+    command: "opencode",
+    args: ["run", heartbeatPrompt],
+    workdir: input.workdir ?? getDefaultWorkdir(),
+    enabled: input.enabled ?? true,
+    createdAt: isoNow(),
+  };
+
+  writeJob(job);
+  appendJobLog(job, `Created opencode job "${job.name}" schedule=${job.schedule}`);
+  return job;
+}
+
+export function updateJob(
+  jobId: string,
+  updates: Partial<
+    Pick<Job, "name" | "schedule" | "prompt" | "workdir" | "enabled" | "command" | "args">
+  >,
+): Job | null {
+  const existing = readJob(jobId);
+  if (!existing) return null;
+
+  if (updates.schedule) {
+    validateCron(updates.schedule);
+  }
+
+  let nextCommand = updates.command ?? existing.command;
+  let nextArgs = updates.args ?? existing.args;
+  const nextPrompt = updates.prompt ?? existing.prompt;
+
+  if (existing.kind === "opencode" && (updates.prompt !== undefined || updates.name !== undefined)) {
+    if (!nextPrompt) {
+      throw new Error(`Opencode job ${existing.id} is missing prompt content.`);
+    }
+    nextCommand = "opencode";
+    nextArgs = [
+      "run",
+      buildHeartbeatPrompt({
+        jobId: existing.id,
+        jobName: updates.name ?? existing.name,
+        prompt: nextPrompt,
+      }),
+    ];
+  }
+
+  const updated: Job = {
+    ...existing,
+    ...updates,
+    prompt: nextPrompt,
+    command: nextCommand,
+    args: nextArgs,
+    updatedAt: isoNow(),
+  };
+
+  writeJob(updated);
+  appendJobLog(updated, `Updated job "${updated.name}"`);
+  return updated;
+}
+
+export function deleteJob(jobId: string): boolean {
+  const job = readJob(jobId);
+  if (!job) return false;
+
+  try {
+    uninstallLaunchdJob(job);
+  } catch {
+    // Ignore launchd teardown errors during delete.
+  }
+
+  const deleted = deleteJobFile(jobId);
+  if (deleted) {
+    appendJobLog(job, `Deleted job "${job.name}"`);
+  }
+  return deleted;
+}
+
+function createLineDrain(
+  onLine: (line: string) => void,
+): {
+  push: (chunk: Buffer) => void;
+  flush: () => void;
+} {
+  let remainder = "";
+
+  return {
+    push(chunk: Buffer) {
+      const next = remainder + chunk.toString("utf-8");
+      const parsed = splitLines(next);
+      remainder = parsed.remainder;
+      for (const line of parsed.lines) {
+        if (line.trim().length > 0) {
+          onLine(line);
+        }
+      }
+    },
+    flush() {
+      if (remainder.trim().length > 0) {
+        onLine(remainder);
+      }
+      remainder = "";
+    },
+  };
+}
+
+export function runJob(jobId: string): Promise<RunResult> {
+  return new Promise((resolve, reject) => {
+    const job = readJob(jobId);
+    if (!job) {
+      reject(new Error(`Job not found: ${jobId}`));
+      return;
+    }
+
+    const startedAt = isoNow();
+    const startedMs = Date.now();
+
+    if (!job.enabled) {
+      const skipped: RunResult = {
+        jobId: job.id,
+        status: "skipped",
+        startedAt,
+        finishedAt: startedAt,
+        durationMs: 0,
+        exitCode: 0,
+        signal: null,
+      };
+      appendJobLog(job, `Skipped disabled job "${job.name}"`);
+      resolve(skipped);
+      return;
+    }
+
+    job.lastRunAt = startedAt;
+    job.lastRunStatus = "running";
+    delete job.lastRunExitCode;
+    delete job.lastRunError;
+    writeJob(job);
+
+    appendJobLog(job, `Starting job "${job.name}"`);
+    appendJobLog(job, `Command: ${job.command} ${job.args.join(" ")}`);
+    appendJobLog(job, `Workdir: ${job.workdir}`);
+
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(job.command, job.args, {
+        cwd: job.workdir,
+        env: process.env,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      const finishedAt = isoNow();
+      const failed: RunResult = {
+        jobId: job.id,
+        status: "failed",
+        startedAt,
+        finishedAt,
+        durationMs: Date.now() - startedMs,
+        exitCode: null,
+        signal: null,
+        error: msg,
+      };
+
+      job.lastRunStatus = "failed";
+      job.lastRunExitCode = undefined;
+      job.lastRunError = msg;
+      job.updatedAt = finishedAt;
+      writeJob(job);
+      appendJobLog(job, `[stderr] Failed to spawn: ${msg}`);
+      resolve(failed);
+      return;
+    }
+
+    const stdoutDrain = createLineDrain((line) => {
+      appendJobLog(job, `[stdout] ${line}`);
+    });
+    const stderrDrain = createLineDrain((line) => {
+      appendJobLog(job, `[stderr] ${line}`);
+    });
+
+    child.stdout?.on("data", (chunk: Buffer) => stdoutDrain.push(chunk));
+    child.stderr?.on("data", (chunk: Buffer) => stderrDrain.push(chunk));
+
+    let settled = false;
+    const finish = (result: RunResult): void => {
+      if (settled) return;
+      settled = true;
+
+      stdoutDrain.flush();
+      stderrDrain.flush();
+
+      job.lastRunStatus = result.status;
+      job.lastRunExitCode = result.exitCode ?? undefined;
+      job.lastRunError = result.error;
+      job.updatedAt = result.finishedAt;
+      writeJob(job);
+
+      appendJobLog(
+        job,
+        `Finished status=${result.status} exit=${result.exitCode ?? "null"} durationMs=${result.durationMs}`,
+      );
+
+      resolve(result);
+    };
+
+    child.on("error", (error) => {
+      const finishedAt = isoNow();
+      finish({
+        jobId: job.id,
+        status: "failed",
+        startedAt,
+        finishedAt,
+        durationMs: Date.now() - startedMs,
+        exitCode: null,
+        signal: null,
+        error: error.message,
+      });
+    });
+
+    child.on("close", (code, signal) => {
+      const finishedAt = isoNow();
+      finish({
+        jobId: job.id,
+        status: code === 0 ? "success" : "failed",
+        startedAt,
+        finishedAt,
+        durationMs: Date.now() - startedMs,
+        exitCode: code,
+        signal,
+        error: code === 0 ? undefined : `Exit code ${code}`,
+      });
+    });
+  });
+}
+
+type CalendarKey = "Minute" | "Hour" | "Day" | "Month" | "Weekday";
+type CalendarEntry = Partial<Record<CalendarKey, number>>;
+
+function parseCronNumber(
+  value: string,
+  min: number,
+  max: number,
+  label: string,
+  allowSundaySeven = false,
+): number {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid cron ${label}: ${value}`);
+  }
+
+  const normalized = allowSundaySeven && parsed === 7 ? 0 : parsed;
+  if (normalized < min || normalized > max) {
+    throw new Error(`Cron ${label} out of range (${min}-${max}): ${value}`);
+  }
+  return normalized;
+}
+
+function parseCronField(
+  field: string,
+  min: number,
+  max: number,
+  label: string,
+  allowSundaySeven = false,
+): number[] | null {
+  if (field === "*") return null;
+
+  const values = new Set<number>();
+  const tokens = field.split(",");
+
+  for (const token of tokens) {
+    const stepMatch = token.match(/^\*\/(\d+)$/);
+    if (stepMatch) {
+      const step = Number.parseInt(stepMatch[1], 10);
+      if (!Number.isFinite(step) || step <= 0) {
+        throw new Error(`Invalid cron ${label} step: ${token}`);
+      }
+      for (let value = min; value <= max; value += step) {
+        values.add(value);
+      }
+      continue;
+    }
+
+    const rangeMatch = token.match(/^(\d+)-(\d+)(?:\/(\d+))?$/);
+    if (rangeMatch) {
+      const start = parseCronNumber(rangeMatch[1], min, max, label, allowSundaySeven);
+      const end = parseCronNumber(rangeMatch[2], min, max, label, allowSundaySeven);
+      const step = rangeMatch[3] ? Number.parseInt(rangeMatch[3], 10) : 1;
+      if (step <= 0) {
+        throw new Error(`Invalid cron ${label} range step: ${token}`);
+      }
+      if (end < start) {
+        throw new Error(`Invalid cron ${label} range: ${token}`);
+      }
+      for (let value = start; value <= end; value += step) {
+        values.add(value);
+      }
+      continue;
+    }
+
+    values.add(parseCronNumber(token, min, max, label, allowSundaySeven));
+  }
+
+  return Array.from(values).sort((a, b) => a - b);
+}
+
+function expandCalendar(
+  base: CalendarEntry[],
+  key: CalendarKey,
+  values: number[] | null,
+): CalendarEntry[] {
+  if (!values) return base;
+
+  const next: CalendarEntry[] = [];
+  for (const row of base) {
+    for (const value of values) {
+      next.push({
+        ...row,
+        [key]: value,
+      });
+    }
+  }
+  return next;
+}
+
+function parseCronToLaunchd(cron: string): { startInterval?: number; calendars?: CalendarEntry[] } {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression: ${cron}`);
+  }
+
+  const [minute, hour, day, month, weekday] = parts;
+
+  if (day !== "*" && weekday !== "*") {
+    throw new Error("Cron with both day-of-month and day-of-week is not supported for launchd.");
+  }
+
+  if (hour === "*" && day === "*" && month === "*" && weekday === "*") {
+    if (minute === "*") {
+      return { startInterval: 60 };
+    }
+    const everyMatch = minute.match(/^\*\/(\d+)$/);
+    if (everyMatch) {
+      const every = Number.parseInt(everyMatch[1], 10);
+      if (every <= 0) {
+        throw new Error(`Invalid minute step in cron: ${minute}`);
+      }
+      return { startInterval: every * 60 };
+    }
+  }
+
+  const minutes = parseCronField(minute, 0, 59, "minute");
+  const hours = parseCronField(hour, 0, 23, "hour");
+  const days = parseCronField(day, 1, 31, "day");
+  const months = parseCronField(month, 1, 12, "month");
+  const weekdays = parseCronField(weekday, 0, 6, "weekday", true);
+
+  let calendars: CalendarEntry[] = [{}];
+  calendars = expandCalendar(calendars, "Minute", minutes);
+  calendars = expandCalendar(calendars, "Hour", hours);
+  calendars = expandCalendar(calendars, "Day", days);
+  calendars = expandCalendar(calendars, "Month", months);
+  calendars = expandCalendar(calendars, "Weekday", weekdays);
+
+  if (calendars.length === 0) {
+    calendars = [{}];
+  }
+
+  if (calendars.length > 256) {
+    throw new Error("Cron expands to too many launchd schedules. Use a simpler schedule.");
+  }
+
+  return { calendars };
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function launchdPlistPath(job: Job): string {
+  return path.join(LAUNCH_AGENTS_DIR, `${getConfigLaunchdLabel(job.id)}.plist`);
+}
+
+function buildCalendarXml(calendars: CalendarEntry[]): string {
+  return calendars
+    .map((entry) => {
+      const rows = Object.entries(entry)
+        .map(([key, value]) => `      <key>${key}</key>\n      <integer>${value}</integer>`)
+        .join("\n");
+      return `    <dict>\n${rows}\n    </dict>`;
+    })
+    .join("\n");
+}
+
+function createLaunchdPlist(job: Job): string {
+  const label = getConfigLaunchdLabel(job.id);
+  const parsed = parseCronToLaunchd(job.schedule);
+
+  const scheduleBlock = parsed.startInterval
+    ? `  <key>StartInterval</key>\n  <integer>${parsed.startInterval}</integer>`
+    : `  <key>StartCalendarInterval</key>\n  <array>\n${buildCalendarXml(parsed.calendars ?? [{}])}\n  </array>`;
+
+  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>${escapeXml(label)}</string>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(job.workdir)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(getBunPath())}</string>
+    <string>run</string>
+    <string>${escapeXml(SCHEDULER_ENTRY)}</string>
+    <string>run</string>
+    <string>${escapeXml(job.id)}</string>
+  </array>
+${scheduleBlock}
+  <key>StandardOutPath</key>
+  <string>${escapeXml(sharedLogPath())}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(sharedLogPath())}</string>
+  <key>RunAtLoad</key>
+  <false/>
+</dict>
+</plist>`;
+}
+
+export function installLaunchdJob(job: Job): void {
+  if (!IS_MAC) {
+    throw new Error("launchd install is only supported on macOS");
+  }
+
+  ensureDir(LAUNCH_AGENTS_DIR);
+  ensureDir(path.dirname(sharedLogPath()));
+
+  const plistPath = launchdPlistPath(job);
+  const plist = createLaunchdPlist(job);
+
+  try {
+    execFileSync("launchctl", ["unload", plistPath], { stdio: "ignore" });
+  } catch {
+    // Ignore unload failures.
+  }
+
+  fs.writeFileSync(plistPath, plist);
+  execFileSync("launchctl", ["load", plistPath], { stdio: "ignore" });
+  appendJobLog(job, `Installed launchd job ${plistPath}`);
+}
+
+export function uninstallLaunchdJob(job: Job): void {
+  if (!IS_MAC) return;
+
+  const plistPath = launchdPlistPath(job);
+  if (!fs.existsSync(plistPath)) return;
+
+  try {
+    execFileSync("launchctl", ["unload", plistPath], { stdio: "ignore" });
+  } catch {
+    // Ignore unload failures.
+  }
+
+  try {
+    fs.unlinkSync(plistPath);
+  } catch {
+    // Ignore remove failures.
+  }
+
+  appendJobLog(job, `Uninstalled launchd job ${plistPath}`);
+}
+
+async function runCli(): Promise<void> {
+  initScheduler();
+  const [cmd, arg] = process.argv.slice(2);
+
+  if (cmd === "run" && arg) {
+    const result = await runJob(arg);
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.status === "success" ? 0 : 1);
+  }
+
+  if (cmd === "list") {
+    console.log(JSON.stringify(listJobs(), null, 2));
+    return;
+  }
+
+  if (cmd === "install" && arg) {
+    const job = getJob(arg);
+    if (!job) throw new Error(`Job not found: ${arg}`);
+    installLaunchdJob(job);
+    console.log(`Installed ${job.id}`);
+    return;
+  }
+
+  if (cmd === "uninstall" && arg) {
+    const job = getJob(arg);
+    if (!job) throw new Error(`Job not found: ${arg}`);
+    uninstallLaunchdJob(job);
+    console.log(`Uninstalled ${job.id}`);
+    return;
+  }
+
+  console.log("Usage:");
+  console.log("  bun run scheduler/index.ts run <jobId>");
+  console.log("  bun run scheduler/index.ts list");
+  console.log("  bun run scheduler/index.ts install <jobId>");
+  console.log("  bun run scheduler/index.ts uninstall <jobId>");
+}
+
+if (import.meta.main) {
+  runCli().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+
+export const SchedulerPlugin: Plugin = async (ctx) => {
+  initScheduler(ctx.directory);
+
+  return {
+    tool: {
+      scheduler_create_opencode_job: tool({
+        description:
+          "Create a human-managed cron job that runs `opencode run` with the provided prompt.",
+        args: {
+          name: tool.schema.string().describe("Job name"),
+          schedule: tool.schema.string().describe("Cron schedule (e.g. */5 * * * *)"),
+          prompt: tool.schema.string().describe("Task prompt for opencode"),
+          workdir: tool.schema
+            .string()
+            .optional()
+            .describe("Working directory for job execution"),
+          enabled: tool.schema
+            .boolean()
+            .optional()
+            .describe("Whether the job is enabled (default true)"),
+          install: tool.schema
+            .boolean()
+            .optional()
+            .describe("Install into launchd immediately (macOS only)"),
+        },
+        async execute(args) {
+          try {
+            const job = createOpencodeJob({
+              name: args.name,
+              schedule: args.schedule,
+              prompt: args.prompt,
+              workdir: args.workdir ?? ctx.directory,
+              enabled: args.enabled,
+            });
+
+            let installMsg = "";
+            if (args.install) {
+              installLaunchdJob(job);
+              installMsg = "\nInstalled to launchd.";
+            }
+
+            return [
+              `Created job "${job.name}" (id: ${job.id})`,
+              `Schedule: ${job.schedule}`,
+              `Workdir: ${job.workdir}`,
+              `Shared log: ${sharedLogPath()}`,
+              installMsg,
+            ]
+              .filter(Boolean)
+              .join("\n");
+          } catch (error) {
+            return `Failed to create opencode job: ${error instanceof Error ? error.message : String(error)}`;
+          }
+        },
+      }),
+
+      scheduler_create_command_job: tool({
+        description:
+          "Create a human-managed cron job for a generic command. Output streams to the shared heartbeat log.",
+        args: {
+          name: tool.schema.string().describe("Job name"),
+          schedule: tool.schema.string().describe("Cron schedule"),
+          command: tool.schema.string().describe("Command executable"),
+          args: tool.schema.array(tool.schema.string()).optional().describe("Command arguments"),
+          workdir: tool.schema.string().optional().describe("Working directory"),
+          enabled: tool.schema.boolean().optional().describe("Whether enabled"),
+        },
+        async execute(args) {
+          try {
+            const job = createCommandJob({
+              name: args.name,
+              schedule: args.schedule,
+              command: args.command,
+              args: args.args,
+              workdir: args.workdir ?? ctx.directory,
+              enabled: args.enabled,
+            });
+            return `Created command job "${job.name}" (id: ${job.id})`;
+          } catch (error) {
+            return `Failed to create command job: ${error instanceof Error ? error.message : String(error)}`;
+          }
+        },
+      }),
+
+      scheduler_list_jobs: tool({
+        description: "List all heartbeat scheduler jobs.",
+        args: {},
+        async execute() {
+          const jobs = listJobs();
+          if (jobs.length === 0) {
+            return "No jobs found.";
+          }
+          return JSON.stringify(jobs, null, 2);
+        },
+      }),
+
+      scheduler_get_job: tool({
+        description: "Get a scheduler job by id.",
+        args: {
+          jobId: tool.schema.string().describe("Job ID"),
+        },
+        async execute(args) {
+          const job = getJob(args.jobId);
+          if (!job) {
+            return `Job not found: ${args.jobId}`;
+          }
+          return JSON.stringify(job, null, 2);
+        },
+      }),
+
+      scheduler_update_job: tool({
+        description: "Update schedule, prompt, or metadata of an existing job.",
+        args: {
+          jobId: tool.schema.string().describe("Job ID"),
+          name: tool.schema.string().optional().describe("Updated name"),
+          schedule: tool.schema.string().optional().describe("Updated cron schedule"),
+          prompt: tool.schema.string().optional().describe("Updated prompt (opencode jobs)"),
+          workdir: tool.schema.string().optional().describe("Updated workdir"),
+          enabled: tool.schema.boolean().optional().describe("Updated enabled status"),
+        },
+        async execute(args) {
+          const job = updateJob(args.jobId, {
+            name: args.name,
+            schedule: args.schedule,
+            prompt: args.prompt,
+            workdir: args.workdir,
+            enabled: args.enabled,
+          });
+
+          if (!job) {
+            return `Job not found: ${args.jobId}`;
+          }
+
+          return `Updated job "${job.name}" (id: ${job.id})`;
+        },
+      }),
+
+      scheduler_run_job: tool({
+        description: "Run a job immediately. Output is appended to one shared log file.",
+        args: {
+          jobId: tool.schema.string().describe("Job ID"),
+        },
+        async execute(args) {
+          try {
+            const result = await runJob(args.jobId);
+            return JSON.stringify(result, null, 2);
+          } catch (error) {
+            return `Failed to run job: ${error instanceof Error ? error.message : String(error)}`;
+          }
+        },
+      }),
+
+      scheduler_install_job: tool({
+        description: "Install a job in macOS launchd.",
+        args: {
+          jobId: tool.schema.string().describe("Job ID"),
+        },
+        async execute(args) {
+          const job = getJob(args.jobId);
+          if (!job) return `Job not found: ${args.jobId}`;
+
+          try {
+            installLaunchdJob(job);
+            return `Installed "${job.name}" to launchd.`;
+          } catch (error) {
+            return `Failed to install launchd job: ${error instanceof Error ? error.message : String(error)}`;
+          }
+        },
+      }),
+
+      scheduler_uninstall_job: tool({
+        description: "Uninstall a job from macOS launchd.",
+        args: {
+          jobId: tool.schema.string().describe("Job ID"),
+        },
+        async execute(args) {
+          const job = getJob(args.jobId);
+          if (!job) return `Job not found: ${args.jobId}`;
+
+          try {
+            uninstallLaunchdJob(job);
+            return `Uninstalled "${job.name}" from launchd.`;
+          } catch (error) {
+            return `Failed to uninstall launchd job: ${error instanceof Error ? error.message : String(error)}`;
+          }
+        },
+      }),
+
+      scheduler_delete_job: tool({
+        description: "Delete a scheduler job and uninstall its launchd entry if present.",
+        args: {
+          jobId: tool.schema.string().describe("Job ID"),
+        },
+        async execute(args) {
+          const deleted = deleteJob(args.jobId);
+          return deleted ? `Deleted job ${args.jobId}` : `Job not found: ${args.jobId}`;
+        },
+      }),
+
+      scheduler_info: tool({
+        description: "Show scheduler storage paths and shared log path.",
+        args: {},
+        async execute() {
+          return JSON.stringify(
+            {
+              jobsDir: getJobsDir(),
+              logFile: sharedLogPath(),
+              launchAgentsDir: LAUNCH_AGENTS_DIR,
+            },
+            null,
+            2,
+          );
+        },
+      }),
+    },
+  };
+};
+
+export default SchedulerPlugin;