heartbeat-opencode-plugin 0.1.0 → 0.1.1

package/index.ts

@@ -4,6 +4,8 @@ import { SchedulerPlugin } from "./scheduler";
 import { TaskManagerPlugin, getTask, listTasks } from "./task-manager";
 
 type PluginOutput = Awaited<ReturnType<Plugin>>;
+const OUTPUT_TAG_NOTE =
+  "Runtime contract: while running Heartbeat programs, every emitted status/output line must be prefixed with [program][taskId] for grepability.";
 
 function mergeTools(outputs: PluginOutput[]): Record<string, unknown> {
   const toolMap: Record<string, unknown> = {};
@@ -30,7 +32,7 @@ export const HeartbeatPlugin: Plugin = async (ctx) => {
 
       heartbeat_boot_context: tool({
         description:
-          "Boot helper for a CPU cycle. Returns task state + prior memory for [program][taskId].",
+          `Boot helper for a CPU cycle. Returns task state + prior memory for [program][taskId]. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema.string().describe("Task identifier"),

package/memory/index.ts

@@ -35,6 +35,8 @@ export function writeLog(input: {
 
 const LOG_ENTRY_PREFIX =
   /^\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\]\s/;
+const OUTPUT_TAG_NOTE =
+  "Runtime contract: while running Heartbeat programs, every emitted status/output line must be prefixed with [program][taskId] for grepability.";
 
 function readAllEntries(limit?: number): string[] {
   const path = getLogFilePath();
@@ -180,7 +182,8 @@ export const MemoryPlugin: Plugin = async (ctx) => {
   return {
     tool: {
       memory_write: tool({
-        description: "Write a tagged log line as [program][taskId] message.",
+        description:
+          `Write a tagged log line as [program][taskId] message. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema.string().describe("Task identifier"),
@@ -193,7 +196,7 @@ export const MemoryPlugin: Plugin = async (ctx) => {
 
       write_log: tool({
         description:
-          "Alias for memory_write. Writes tagged memory lines into the shared heartbeat log.",
+          `Alias for memory_write. Writes tagged memory lines into the shared heartbeat log. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema.string().describe("Task identifier"),
@@ -206,7 +209,7 @@ export const MemoryPlugin: Plugin = async (ctx) => {
 
       search_memory: tool({
         description:
-          "Search memory by [program] and optional [taskId]. Use this on boot to restore previous cycle context.",
+          `Search memory by [program] and optional [taskId]. Use this on boot to restore previous cycle context. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema
@@ -227,7 +230,7 @@ export const MemoryPlugin: Plugin = async (ctx) => {
       }),
 
       read_program: tool({
-        description: "Read all log lines containing [program].",
+        description: `Read all log lines containing [program]. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           limit: tool.schema.number().optional().describe("Optional max lines"),
@@ -238,7 +241,8 @@ export const MemoryPlugin: Plugin = async (ctx) => {
       }),
 
       read_program_task: tool({
-        description: "Read all log lines containing [program][taskId].",
+        description:
+          `Read all log lines containing [program][taskId]. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema.string().describe("Task identifier"),
@@ -251,7 +255,7 @@ export const MemoryPlugin: Plugin = async (ctx) => {
 
       memory_grep: tool({
         description:
-          "Regex grep across the shared heartbeat log file. Useful for free-form memory queries.",
+          `Regex grep across the shared heartbeat log file. Useful for free-form memory queries. ${OUTPUT_TAG_NOTE}`,
         args: {
           pattern: tool.schema.string().describe("JavaScript regex pattern"),
           limit: tool.schema.number().optional().describe("Optional max lines"),
@@ -266,7 +270,7 @@ export const MemoryPlugin: Plugin = async (ctx) => {
       }),
 
       grep_logs: tool({
-        description: "Alias for memory_grep.",
+        description: `Alias for memory_grep. ${OUTPUT_TAG_NOTE}`,
         args: {
           pattern: tool.schema.string().describe("JavaScript regex pattern"),
           limit: tool.schema.number().optional().describe("Optional max lines"),
@@ -281,7 +285,7 @@ export const MemoryPlugin: Plugin = async (ctx) => {
       }),
 
       tail_logs: tool({
-        description: "Return recent lines from the shared heartbeat log.",
+        description: `Return recent lines from the shared heartbeat log. ${OUTPUT_TAG_NOTE}`,
         args: {
           lines: tool.schema
             .number()
@@ -294,7 +298,7 @@ export const MemoryPlugin: Plugin = async (ctx) => {
       }),
 
       log_info: tool({
-        description: "Get shared log file path and stats.",
+        description: `Get shared log file path and stats. ${OUTPUT_TAG_NOTE}`,
         args: {},
         async execute() {
           return JSON.stringify(getLogInfo(), null, 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heartbeat-opencode-plugin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Heartbeat Runtime",
   "type": "module",
   "main": "./index.ts",

package/scheduler/index.ts

@@ -70,6 +70,13 @@ export interface RunResult {
 const IS_MAC = process.platform === "darwin";
 const LAUNCH_AGENTS_DIR = path.join(homedir(), "Library", "LaunchAgents");
 const SCHEDULER_ENTRY = fileURLToPath(import.meta.url);
+const OPENCODE_COMMAND = "opencode";
+const OPENCODE_FALLBACK_PATHS = [
+  "/opt/homebrew/bin/opencode",
+  "/usr/local/bin/opencode",
+];
+const OUTPUT_TAG_NOTE =
+  "Runtime contract: while running Heartbeat programs, every emitted status/output line must be prefixed with [program][taskId] for grepability.";
 
 function ensureDir(dir: string): void {
   if (!fs.existsSync(dir)) {
@@ -103,6 +110,57 @@ function appendJobLog(job: Pick<Job, "id">, message: string): void {
   appendLog(`[Scheduler][job:${job.id}] ${message}`);
 }
 
+function isExecutable(filePath: string): boolean {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findExecutableInPath(command: string, envPath?: string): string | null {
+  if (!envPath) return null;
+
+  const pathEntries = envPath.split(path.delimiter).filter(Boolean);
+  for (const pathEntry of pathEntries) {
+    const candidate = path.join(pathEntry, command);
+    if (isExecutable(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function resolveOpencodeCommand(command: string): string {
+  if (path.basename(command) !== OPENCODE_COMMAND) {
+    return command;
+  }
+
+  if (isExecutable(command)) {
+    return command;
+  }
+
+  const envOverride = process.env.OPENCODE_BIN?.trim();
+  if (envOverride && isExecutable(envOverride)) {
+    return envOverride;
+  }
+
+  const fromPath = findExecutableInPath(OPENCODE_COMMAND, process.env.PATH);
+  if (fromPath) {
+    return fromPath;
+  }
+
+  for (const fallbackPath of OPENCODE_FALLBACK_PATHS) {
+    if (isExecutable(fallbackPath)) {
+      return fallbackPath;
+    }
+  }
+
+  return command;
+}
+
 function readJob(jobId: string): Job | null {
   const file = jobFilePath(jobId);
   if (!fs.existsSync(file)) return null;
@@ -228,7 +286,7 @@ export function createOpencodeJob(input: CreateOpencodeJobInput): Job {
     kind: "opencode",
     schedule: input.schedule,
     prompt: input.prompt,
-    command: "opencode",
+    command: resolveOpencodeCommand(OPENCODE_COMMAND),
     args: ["run", heartbeatPrompt],
     workdir: input.workdir ?? getDefaultWorkdir(),
     enabled: input.enabled ?? true,
@@ -261,7 +319,7 @@ export function updateJob(
     if (!nextPrompt) {
       throw new Error(`Opencode job ${existing.id} is missing prompt content.`);
     }
-    nextCommand = "opencode";
+    nextCommand = resolveOpencodeCommand(OPENCODE_COMMAND);
     nextArgs = [
       "run",
       buildHeartbeatPrompt({
@@ -364,12 +422,19 @@ export function runJob(jobId: string): Promise<RunResult> {
     writeJob(job);
 
     appendJobLog(job, `Starting job "${job.name}"`);
-    appendJobLog(job, `Command: ${job.command} ${job.args.join(" ")}`);
+    const resolvedCommand = job.kind === "opencode"
+      ? resolveOpencodeCommand(job.command)
+      : job.command;
+    if (resolvedCommand !== job.command) {
+      job.command = resolvedCommand;
+      appendJobLog(job, `Resolved opencode executable: ${resolvedCommand}`);
+    }
+    appendJobLog(job, `Command: ${resolvedCommand} ${job.args.join(" ")}`);
     appendJobLog(job, `Workdir: ${job.workdir}`);
 
     let child: ReturnType<typeof spawn>;
     try {
-      child = spawn(job.command, job.args, {
+      child = spawn(resolvedCommand, job.args, {
         cwd: job.workdir,
         env: process.env,
         shell: false,
@@ -752,7 +817,7 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
     tool: {
       scheduler_create_opencode_job: tool({
         description:
-          "Create a human-managed cron job that runs `opencode run` with the provided prompt.",
+          `Create a human-managed cron job that runs \`opencode run\` with the provided prompt. ${OUTPUT_TAG_NOTE}`,
         args: {
           name: tool.schema.string().describe("Job name"),
           schedule: tool.schema.string().describe("Cron schedule (e.g. */5 * * * *)"),
@@ -803,7 +868,7 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
 
       scheduler_create_command_job: tool({
         description:
-          "Create a human-managed cron job for a generic command. Output streams to the shared heartbeat log.",
+          `Create a human-managed cron job for a generic command. Output streams to the shared heartbeat log. ${OUTPUT_TAG_NOTE}`,
         args: {
           name: tool.schema.string().describe("Job name"),
           schedule: tool.schema.string().describe("Cron schedule"),
@@ -830,7 +895,7 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
       }),
 
       scheduler_list_jobs: tool({
-        description: "List all heartbeat scheduler jobs.",
+        description: `List all heartbeat scheduler jobs. ${OUTPUT_TAG_NOTE}`,
         args: {},
         async execute() {
           const jobs = listJobs();
@@ -842,7 +907,7 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
       }),
 
       scheduler_get_job: tool({
-        description: "Get a scheduler job by id.",
+        description: `Get a scheduler job by id. ${OUTPUT_TAG_NOTE}`,
         args: {
           jobId: tool.schema.string().describe("Job ID"),
         },
@@ -856,7 +921,8 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
       }),
 
       scheduler_update_job: tool({
-        description: "Update schedule, prompt, or metadata of an existing job.",
+        description:
+          `Update schedule, prompt, or metadata of an existing job. ${OUTPUT_TAG_NOTE}`,
         args: {
           jobId: tool.schema.string().describe("Job ID"),
           name: tool.schema.string().optional().describe("Updated name"),
@@ -883,7 +949,8 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
       }),
 
       scheduler_run_job: tool({
-        description: "Run a job immediately. Output is appended to one shared log file.",
+        description:
+          `Run a job immediately. Output is appended to one shared log file. ${OUTPUT_TAG_NOTE}`,
         args: {
           jobId: tool.schema.string().describe("Job ID"),
         },
@@ -898,7 +965,7 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
       }),
 
       scheduler_install_job: tool({
-        description: "Install a job in macOS launchd.",
+        description: `Install a job in macOS launchd. ${OUTPUT_TAG_NOTE}`,
         args: {
           jobId: tool.schema.string().describe("Job ID"),
         },
@@ -916,7 +983,7 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
       }),
 
       scheduler_uninstall_job: tool({
-        description: "Uninstall a job from macOS launchd.",
+        description: `Uninstall a job from macOS launchd. ${OUTPUT_TAG_NOTE}`,
         args: {
           jobId: tool.schema.string().describe("Job ID"),
         },
@@ -934,7 +1001,8 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
       }),
 
       scheduler_delete_job: tool({
-        description: "Delete a scheduler job and uninstall its launchd entry if present.",
+        description:
+          `Delete a scheduler job and uninstall its launchd entry if present. ${OUTPUT_TAG_NOTE}`,
         args: {
           jobId: tool.schema.string().describe("Job ID"),
         },
@@ -945,7 +1013,7 @@ export const SchedulerPlugin: Plugin = async (ctx) => {
       }),
 
       scheduler_info: tool({
-        description: "Show scheduler storage paths and shared log path.",
+        description: `Show scheduler storage paths and shared log path. ${OUTPUT_TAG_NOTE}`,
         args: {},
         async execute() {
           return JSON.stringify(

package/task-manager/index.ts

@@ -40,6 +40,8 @@ const VALID_PRIORITIES = new Set<TaskPriority>([
   "high",
   "critical",
 ]);
+const OUTPUT_TAG_NOTE =
+  "Runtime contract: while running Heartbeat programs, every emitted status/output line must be prefixed with [program][taskId] for grepability.";
 
 function nowIso(): string {
   return new Date().toISOString();
@@ -128,7 +130,8 @@ export function listTasks(filters?: TaskFilters): Task[] {
   const tasks = storeInstance().read();
   return tasks.filter((task) => {
     if (filters?.program && task.program !== filters.program) return false;
-    if (filters?.parentTaskId && task.parentTaskId !== filters.parentTaskId) return false;
+    if (filters?.parentTaskId && task.parentTaskId !== filters.parentTaskId)
+      return false;
     if (filters?.status && task.status !== filters.status) return false;
     if (filters?.priority && task.priority !== filters.priority) return false;
     return true;
@@ -137,7 +140,9 @@ export function listTasks(filters?: TaskFilters): Task[] {
 
 export function getTask(program: string, taskId: string): Task | undefined {
   const tasks = storeInstance().read();
-  return tasks.find((task) => taskKey(task.program, task.taskId) === taskKey(program, taskId));
+  return tasks.find(
+    (task) => taskKey(task.program, task.taskId) === taskKey(program, taskId),
+  );
 }
 
 export function createTask(input: {
@@ -152,7 +157,11 @@ export function createTask(input: {
   const instance = storeInstance();
   const tasks = instance.read();
 
-  const duplicate = tasks.find((task) => taskKey(task.program, task.taskId) === taskKey(input.program, input.taskId));
+  const duplicate = tasks.find(
+    (task) =>
+      taskKey(task.program, task.taskId) ===
+      taskKey(input.program, input.taskId),
+  );
   if (duplicate) {
     throw new Error(`Task already exists: [${input.program}][${input.taskId}]`);
   }
@@ -172,7 +181,9 @@ export function createTask(input: {
 
   tasks.push(task);
   instance.write(tasks);
-  appendLog(`[${task.program}][${task.taskId}] Task created with status=${task.status}`);
+  appendLog(
+    `[${task.program}][${task.taskId}] Task created with status=${task.status}`,
+  );
   return task;
 }
 
@@ -187,7 +198,11 @@ export function updateTask(input: {
 }): Task | null {
   const instance = storeInstance();
   const tasks = instance.read();
-  const index = tasks.findIndex((task) => taskKey(task.program, task.taskId) === taskKey(input.program, input.taskId));
+  const index = tasks.findIndex(
+    (task) =>
+      taskKey(task.program, task.taskId) ===
+      taskKey(input.program, input.taskId),
+  );
 
   if (index === -1) return null;
 
@@ -195,9 +210,13 @@ export function updateTask(input: {
   const updated: Task = {
     ...existing,
     ...("parentTaskId" in input ? { parentTaskId: input.parentTaskId } : {}),
-    ...("description" in input ? { description: input.description ?? existing.description } : {}),
+    ...("description" in input
+      ? { description: input.description ?? existing.description }
+      : {}),
     ...("status" in input ? { status: input.status ?? existing.status } : {}),
-    ...("priority" in input ? { priority: input.priority ?? existing.priority } : {}),
+    ...("priority" in input
+      ? { priority: input.priority ?? existing.priority }
+      : {}),
     ...("references" in input ? { references: input.references } : {}),
     updatedAt: nowIso(),
   };
@@ -211,7 +230,9 @@ export function updateTask(input: {
 
   tasks[index] = updated;
   instance.write(tasks);
-  appendLog(`[${updated.program}][${updated.taskId}] Task updated status=${updated.status}`);
+  appendLog(
+    `[${updated.program}][${updated.taskId}] Task updated status=${updated.status}`,
+  );
   return updated;
 }
 
@@ -226,7 +247,9 @@ export function markTaskDone(program: string, taskId: string): Task | null {
 export function deleteTask(program: string, taskId: string): boolean {
   const instance = storeInstance();
   const tasks = instance.read();
-  const filtered = tasks.filter((task) => taskKey(task.program, task.taskId) !== taskKey(program, taskId));
+  const filtered = tasks.filter(
+    (task) => taskKey(task.program, task.taskId) !== taskKey(program, taskId),
+  );
 
   if (filtered.length === tasks.length) {
     return false;
@@ -247,20 +270,27 @@ export const TaskManagerPlugin: Plugin = async (ctx) => {
   return {
     tool: {
       task_create: tool({
-        description:
-          "Create a task tracked by [program][taskId]. Use this before running a cron cycle.",
+        description: `Create a task tracked by [program][taskId]. `,
         args: {
-          program: tool.schema.string().describe("Program name used for task and memory tags"),
-          taskId: tool.schema.string().describe("Task identifier in kebab-case"),
+          program: tool.schema
+            .string()
+            .describe("Program name used for task and memory tags"),
+          taskId: tool.schema
+            .string()
+            .describe("Task identifier in snake_case"),
           parentTaskId: tool.schema
             .string()
             .optional()
             .describe("Optional parent task ID to create task hierarchies"),
-          description: tool.schema.string().describe("Human description of the task"),
+          description: tool.schema
+            .string()
+            .describe("Human description of the task"),
           status: tool.schema
             .string()
             .optional()
-            .describe("Optional status: pending, running, blocked, raised, done"),
+            .describe(
+              "Optional status: pending, running, blocked, raised, done",
+            ),
           priority: tool.schema
             .string()
             .optional()
@@ -299,12 +329,24 @@ export const TaskManagerPlugin: Plugin = async (ctx) => {
       }),
 
       task_list: tool({
-        description: "List tasks, optionally filtered by program/status/priority.",
+        description: `List tasks, optionally filtered by program/status/priority. ${OUTPUT_TAG_NOTE}`,
         args: {
-          program: tool.schema.string().optional().describe("Optional program filter"),
-          parentTaskId: tool.schema.string().optional().describe("Optional parent task filter"),
-          status: tool.schema.string().optional().describe("Optional status filter"),
-          priority: tool.schema.string().optional().describe("Optional priority filter"),
+          program: tool.schema
+            .string()
+            .optional()
+            .describe("Optional program filter"),
+          parentTaskId: tool.schema
+            .string()
+            .optional()
+            .describe("Optional parent task filter"),
+          status: tool.schema
+            .string()
+            .optional()
+            .describe("Optional status filter"),
+          priority: tool.schema
+            .string()
+            .optional()
+            .describe("Optional priority filter"),
         },
         async execute(args) {
           const status = normalizeStatus(args.status);
@@ -331,7 +373,7 @@ export const TaskManagerPlugin: Plugin = async (ctx) => {
       }),
 
       task_get: tool({
-        description: "Get a single task by [program][taskId].",
+        description: `Get a single task by [program][taskId]. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema.string().describe("Task ID"),
@@ -346,7 +388,7 @@ export const TaskManagerPlugin: Plugin = async (ctx) => {
       }),
 
       task_update: tool({
-        description: "Update task metadata or status.",
+        description: `Update task metadata or status. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema.string().describe("Task ID"),
@@ -354,10 +396,19 @@ export const TaskManagerPlugin: Plugin = async (ctx) => {
             .string()
             .optional()
             .describe("Updated parent task ID"),
-          description: tool.schema.string().optional().describe("Updated description"),
+          description: tool.schema
+            .string()
+            .optional()
+            .describe("Updated description"),
           status: tool.schema.string().optional().describe("Updated status"),
-          priority: tool.schema.string().optional().describe("Updated priority"),
-          references: tool.schema.string().optional().describe("Updated references"),
+          priority: tool.schema
+            .string()
+            .optional()
+            .describe("Updated priority"),
+          references: tool.schema
+            .string()
+            .optional()
+            .describe("Updated references"),
         },
         async execute(args) {
           const status = normalizeStatus(args.status);
@@ -410,7 +461,7 @@ export const TaskManagerPlugin: Plugin = async (ctx) => {
       }),
 
       task_mark_done: tool({
-        description: "Mark a task as done after it is resolved.",
+        description: `Mark a task as done after it is resolved. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema.string().describe("Task ID"),
@@ -425,7 +476,7 @@ export const TaskManagerPlugin: Plugin = async (ctx) => {
       }),
 
       task_delete: tool({
-        description: "Delete a task from the task manager.",
+        description: `Delete a task from the task manager. ${OUTPUT_TAG_NOTE}`,
         args: {
           program: tool.schema.string().describe("Program name"),
           taskId: tool.schema.string().describe("Task ID"),
@@ -440,7 +491,7 @@ export const TaskManagerPlugin: Plugin = async (ctx) => {
       }),
 
       task_store_info: tool({
-        description: "Get task store file path and current task count.",
+        description: `Get task store file path and current task count. ${OUTPUT_TAG_NOTE}`,
         args: {},
         async execute() {
           const tasks = listTasks();