heartbeat-opencode-plugin 0.1.0

package/README.md

@@ -0,0 +1,198 @@
+# Heartbeat OpenCode Plugin
+
+Heartbeat is a plugin stack for OpenCode with three modules:
+
+- `scheduler`: human-managed cron jobs (including `opencode run`)
+- `task-manager`: structured task state (`[program][taskId]`)
+- `memory`: shared append-only log + grep/search retrieval
+
+The design model is:
+
+- LLM = compute cycle
+- Scheduler = clock/launcher
+- Task manager + memory = state across cycles
+
+## Architecture
+
+### Components
+
+1. Scheduler (`/Users/pragneshbarik/Projects/heartbeat/scheduler/index.ts`)
+- Stores job definitions as JSON files.
+- Runs jobs manually or on schedule (launchd on macOS).
+- Streams all emitted stdout/stderr lines to one shared log file.
+
+2. Task Manager (`/Users/pragneshbarik/Projects/heartbeat/task-manager/index.ts`)
+- Stores tasks in a JSON file.
+- Task key is `[program][taskId]`.
+- Supports `parentTaskId` for task hierarchies.
+- Tracks status, priority, timestamps, and optional references.
+
+3. Memory (`/Users/pragneshbarik/Projects/heartbeat/memory/index.ts`)
+- Appends timestamped entries to one shared file.
+- Supports:
+  - tag lookup by `[program]`
+  - exact lookup by `[program][taskId]`
+  - regex grep across all entries
+- Preserves multiline entries as a single memory record.
+
+4. Unified Plugin Entry (`/Users/pragneshbarik/Projects/heartbeat/index.ts`)
+- Merges tools from scheduler + task-manager + memory.
+- Adds `heartbeat_boot_context` helper:
+  - current task snapshot
+  - recent task memory
+  - queue slices (pending/running/blocked/raised)
+
+### Data Flow
+
+1. Human creates a scheduler job.
+2. Scheduler executes command or `opencode run <prompt>`.
+3. Runtime output is streamed into the shared log.
+4. Next cycle can query memory and task state, then continue.
+
+## Config Model
+
+`launchd` prefix and Bun path are fixed in code (not configurable):
+
+- launchd label prefix: `com.heartbeat.job`
+- bun path: `/opt/homebrew/bin/bun`
+
+Configurable settings:
+
+- logs directory/file
+- jobs directory
+- default job workdir
+- task store file
+
+### Config precedence (lowest -> highest)
+
+1. Built-in defaults (in code)
+2. Global plugin config:
+   - `~/.config/opencode/heartbeat.jsonc`
+3. Legacy fallback files:
+   - `heartbeat.config.json`
+   - `.opencode/heartbeat.config.json`
+4. Workspace plugin config:
+   - `.opencode/heartbeat.jsonc`
+5. Environment override:
+   - `HEARTBEAT_CONFIG_PATH`
+   - legacy alias: `HEARTBEAT_CONFIG`
+
+## Setup
+
+### 1. Install package in workspace
+
+```bash
+npm install heartbeat-opencode-plugin
+```
+
+### 2. Register plugin in OpenCode config
+
+Create or edit `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["heartbeat-opencode-plugin"]
+}
+```
+
+### 3. Add Heartbeat workspace config
+
+Create `.opencode/heartbeat.jsonc`:
+
+```jsonc
+{
+  "logs": {
+    "dir": "./.opencode/heartbeat/logs",
+    "file": "memory.log"
+  },
+  "scheduler": {
+    "jobsDir": "./.opencode/heartbeat/jobs",
+    "defaultWorkdir": "."
+  },
+  "taskManager": {
+    "file": "./.opencode/heartbeat/tasks.json"
+  }
+}
+```
+
+## Quick Start
+
+1. Create a task:
+- `task_create(program, taskId, description, parentTaskId?, priority?, status?, references?)`
+
+2. Create a job:
+- `scheduler_create_opencode_job(...)` or `scheduler_create_command_job(...)`
+
+3. Test run once:
+- `scheduler_run_job(jobId)`
+
+4. Read memory:
+- `search_memory(program, taskId?)`
+- `memory_grep(pattern)`
+
+5. Mark done:
+- `task_mark_done(program, taskId)`
+
+## Tool Surface
+
+Scheduler tools:
+
+- `scheduler_create_opencode_job`
+- `scheduler_create_command_job`
+- `scheduler_list_jobs`
+- `scheduler_get_job`
+- `scheduler_update_job`
+- `scheduler_run_job`
+- `scheduler_install_job` (macOS)
+- `scheduler_uninstall_job` (macOS)
+- `scheduler_delete_job`
+- `scheduler_info`
+
+Task tools:
+
+- `task_create`
+- `task_list`
+- `task_get`
+- `task_update`
+- `task_mark_done`
+- `task_delete`
+- `task_store_info`
+
+Memory tools:
+
+- `memory_write` / `write_log`
+- `search_memory`
+- `read_program`
+- `read_program_task`
+- `memory_grep` / `grep_logs`
+- `tail_logs`
+- `log_info`
+
+Helper:
+
+- `heartbeat_boot_context`
+
+## Local Development
+
+```bash
+bun install
+bun run typecheck
+```
+
+## Publish To npm
+
+```bash
+bun run typecheck
+NPM_CONFIG_CACHE=/tmp/heartbeat-npm-cache npm pack --dry-run
+npm login
+npm publish --access public
+```
+
+## Example Files
+
+- `/Users/pragneshbarik/Projects/heartbeat/examples/opencode.json`
+- `/Users/pragneshbarik/Projects/heartbeat/examples/.opencode/heartbeat.jsonc`
+- `/Users/pragneshbarik/Projects/heartbeat/examples/scheduler/jobs/daily-standup.json`
+- `/Users/pragneshbarik/Projects/heartbeat/examples/scheduler/jobs/research-cycle.json`
+- `/Users/pragneshbarik/Projects/heartbeat/examples/task-manager/tasks.json`

package/config/index.ts

@@ -0,0 +1,409 @@
+/**
+ * Heartbeat Configuration
+ *
+ * Central configuration for the heartbeat LLM OS.
+ * Supports plugin-style overrides from:
+ * - ~/.config/opencode/heartbeat.jsonc
+ * - .opencode/heartbeat.jsonc (workspace OpenCode folder)
+ * - heartbeat.config.json (legacy project-local file)
+ * - env override: HEARTBEAT_CONFIG_PATH (or legacy HEARTBEAT_CONFIG)
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { homedir } from "os";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface HeartbeatConfig {
+  /** Logging configuration */
+  logs: {
+    /** Directory for log files (relative to project root) */
+    dir: string;
+    /** Log file name */
+    file: string;
+  };
+
+  /** Scheduler configuration */
+  scheduler: {
+    /** Directory for job JSON files (relative to project root) */
+    jobsDir: string;
+    /** Default working directory for jobs (absolute or relative to project root) */
+    defaultWorkdir: string;
+  };
+
+  /** Task manager configuration */
+  taskManager: {
+    /** Task JSON store file (absolute or relative to project root) */
+    file: string;
+  };
+}
+
+// ============================================================================
+// Defaults
+// ============================================================================
+
+const DEFAULT_CONFIG: HeartbeatConfig = {
+  logs: {
+    dir: "./logs",
+    file: "heartbeat.log",
+  },
+  scheduler: {
+    jobsDir: "./scheduler/jobs",
+    defaultWorkdir: ".",
+  },
+  taskManager: {
+    file: "./task-manager/tasks.json",
+  },
+};
+
+const LAUNCHD_LABEL_PREFIX = "com.heartbeat.job";
+const FIXED_BUN_PATH = "/opt/homebrew/bin/bun";
+
+// ============================================================================
+// Config Loading
+// ============================================================================
+
+const CONFIG_FILENAME = "heartbeat.config.json";
+const HEARTBEAT_JSONC = "heartbeat.jsonc";
+const OPENCODE_DIR = ".opencode";
+const HEARTBEAT_ENV_CONFIG_PATH = "HEARTBEAT_CONFIG_PATH";
+const HEARTBEAT_ENV_CONFIG_LEGACY = "HEARTBEAT_CONFIG";
+const OPENCODE_GLOBAL_DIR = path.join(homedir(), ".config", "opencode");
+
+let loadedConfig: HeartbeatConfig | null = null;
+let configDir: string = process.cwd();
+
+function cloneDefaultConfig(): HeartbeatConfig {
+  return {
+    logs: { ...DEFAULT_CONFIG.logs },
+    scheduler: { ...DEFAULT_CONFIG.scheduler },
+    taskManager: { ...DEFAULT_CONFIG.taskManager },
+  };
+}
+
+/**
+ * Deep merge two objects
+ */
+function deepMerge(
+  target: HeartbeatConfig,
+  source: Partial<HeartbeatConfig>
+): HeartbeatConfig {
+  return {
+    logs: {
+      ...target.logs,
+      ...source.logs,
+    },
+    scheduler: {
+      ...target.scheduler,
+      ...source.scheduler,
+    },
+    taskManager: {
+      ...target.taskManager,
+      ...source.taskManager,
+    },
+  };
+}
+
+function stripJsonComments(raw: string): string {
+  let result = "";
+  let inString = false;
+  let stringQuote: '"' | "'" | null = null;
+  let escaped = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+
+  for (let i = 0; i < raw.length; i += 1) {
+    const char = raw[i];
+    const next = raw[i + 1];
+
+    if (inLineComment) {
+      if (char === "\n") {
+        inLineComment = false;
+        result += "\n";
+      } else {
+        result += " ";
+      }
+      continue;
+    }
+
+    if (inBlockComment) {
+      if (char === "*" && next === "/") {
+        inBlockComment = false;
+        result += "  ";
+        i += 1;
+      } else {
+        result += char === "\n" ? "\n" : " ";
+      }
+      continue;
+    }
+
+    if (inString) {
+      result += char;
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+
+      if (stringQuote && char === stringQuote) {
+        inString = false;
+        stringQuote = null;
+      }
+
+      continue;
+    }
+
+    if ((char === '"' || char === "'") && !inString) {
+      inString = true;
+      stringQuote = char;
+      result += char;
+      continue;
+    }
+
+    if (char === "/" && next === "/") {
+      inLineComment = true;
+      result += "  ";
+      i += 1;
+      continue;
+    }
+
+    if (char === "/" && next === "*") {
+      inBlockComment = true;
+      result += "  ";
+      i += 1;
+      continue;
+    }
+
+    result += char;
+  }
+
+  return result;
+}
+
+function parseJsonMaybeJsonc(raw: string, filePath: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    try {
+      return JSON.parse(stripJsonComments(raw));
+    } catch (error) {
+      throw new Error(
+        `Failed to parse JSON/JSONC at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+}
+
+function readJsonFile(filePath: string): unknown {
+  const content = fs.readFileSync(filePath, "utf-8");
+  return parseJsonMaybeJsonc(content, filePath);
+}
+
+function readHeartbeatConfigFile(filePath: string): Partial<HeartbeatConfig> | null {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const parsed = readJsonFile(filePath);
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`Config file must be an object: ${filePath}`);
+  }
+
+  return parsed as Partial<HeartbeatConfig>;
+}
+
+function resolveOptionalPath(input: string): string {
+  if (path.isAbsolute(input)) {
+    return input;
+  }
+  return path.resolve(configDir, input);
+}
+
+function mergeHeartbeatConfig(
+  base: HeartbeatConfig,
+  override: Partial<HeartbeatConfig> | null,
+): HeartbeatConfig {
+  if (!override) {
+    return base;
+  }
+  return deepMerge(base, override);
+}
+
+/**
+ * Load configuration using plugin-style config files.
+ * Falls back to defaults when no overrides are found.
+ */
+export function loadConfig(projectDir?: string): HeartbeatConfig {
+  if (projectDir) {
+    configDir = projectDir;
+  }
+
+  let config = cloneDefaultConfig();
+  const warnings: string[] = [];
+
+  const mergeHeartbeatFile = (filePath: string): void => {
+    try {
+      config = mergeHeartbeatConfig(config, readHeartbeatConfigFile(filePath));
+    } catch (error) {
+      warnings.push(error instanceof Error ? error.message : String(error));
+    }
+  };
+
+  // Global plugin config (shared defaults across workspaces).
+  mergeHeartbeatFile(path.join(OPENCODE_GLOBAL_DIR, HEARTBEAT_JSONC));
+
+  // Legacy files kept for backward compatibility.
+  mergeHeartbeatFile(path.join(configDir, CONFIG_FILENAME));
+  mergeHeartbeatFile(path.join(configDir, OPENCODE_DIR, CONFIG_FILENAME));
+
+  // Preferred workspace-local plugin config.
+  mergeHeartbeatFile(path.join(configDir, OPENCODE_DIR, HEARTBEAT_JSONC));
+
+  // Explicit Heartbeat override file (highest precedence).
+  const explicitHeartbeatConfig =
+    process.env[HEARTBEAT_ENV_CONFIG_PATH]?.trim() ??
+    process.env[HEARTBEAT_ENV_CONFIG_LEGACY]?.trim();
+  if (explicitHeartbeatConfig) {
+    mergeHeartbeatFile(resolveOptionalPath(explicitHeartbeatConfig));
+  }
+
+  loadedConfig = config;
+
+  for (const warning of warnings) {
+    console.warn(`Warning: ${warning}`);
+  }
+
+  return config;
+}
+
+/**
+ * Get the current configuration
+ * Loads from file if not already loaded
+ */
+export function getConfig(): HeartbeatConfig {
+  if (loadedConfig === null) {
+    loadedConfig = loadConfig();
+  }
+  return loadedConfig;
+}
+
+/**
+ * Reset configuration (useful for testing)
+ */
+export function resetConfig(): void {
+  loadedConfig = null;
+  configDir = process.cwd();
+}
+
+/**
+ * Get the project directory
+ */
+export function getProjectDir(): string {
+  return configDir;
+}
+
+// ============================================================================
+// Path Resolvers
+// ============================================================================
+
+/**
+ * Resolve a path relative to project directory
+ */
+export function resolvePath(relativePath: string): string {
+  if (path.isAbsolute(relativePath)) {
+    return relativePath;
+  }
+  return path.resolve(configDir, relativePath);
+}
+
+/**
+ * Get the full log file path
+ */
+export function getLogFilePath(): string {
+  const config = getConfig();
+  return path.join(resolvePath(config.logs.dir), config.logs.file);
+}
+
+/**
+ * Get the full logs directory path
+ */
+export function getLogsDir(): string {
+  const config = getConfig();
+  return resolvePath(config.logs.dir);
+}
+
+/**
+ * Get the full jobs directory path
+ */
+export function getJobsDir(): string {
+  const config = getConfig();
+  return resolvePath(config.scheduler.jobsDir);
+}
+
+/**
+ * Get the default working directory for jobs
+ */
+export function getDefaultWorkdir(): string {
+  const config = getConfig();
+  return resolvePath(config.scheduler.defaultWorkdir);
+}
+
+/**
+ * Get the full task store file path
+ */
+export function getTasksFilePath(): string {
+  const config = getConfig();
+  return resolvePath(config.taskManager.file);
+}
+
+/**
+ * Get launchd label for a job
+ */
+export function getLaunchdLabel(jobId: string): string {
+  return `${LAUNCHD_LABEL_PREFIX}.${jobId}`;
+}
+
+/**
+ * Get bun executable path
+ */
+export function getBunPath(): string {
+  return FIXED_BUN_PATH;
+}
+
+// ============================================================================
+// Config File Generator
+// ============================================================================
+
+/**
+ * Generate a default config file
+ */
+export function generateConfigFile(projectDir?: string): string {
+  const dir = projectDir || configDir;
+  const configPath = path.join(dir, CONFIG_FILENAME);
+
+  const configContent = JSON.stringify(cloneDefaultConfig(), null, 2);
+  fs.writeFileSync(configPath, configContent);
+
+  return configPath;
+}
+
+/**
+ * Check if config file exists
+ */
+export function configFileExists(projectDir?: string): boolean {
+  const dir = projectDir || configDir;
+  return fs.existsSync(path.join(dir, CONFIG_FILENAME));
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { DEFAULT_CONFIG, CONFIG_FILENAME };

package/heartbeat.config.json

@@ -0,0 +1,13 @@
+{
+  "logs": {
+    "dir": "./logs",
+    "file": "heartbeat.log"
+  },
+  "scheduler": {
+    "jobsDir": "./scheduler/jobs",
+    "defaultWorkdir": "."
+  },
+  "taskManager": {
+    "file": "./task-manager/tasks.json"
+  }
+}

package/index.ts

@@ -0,0 +1,71 @@
+import { type Plugin, tool } from "@opencode-ai/plugin";
+import { MemoryPlugin, searchMemory } from "./memory";
+import { SchedulerPlugin } from "./scheduler";
+import { TaskManagerPlugin, getTask, listTasks } from "./task-manager";
+
+type PluginOutput = Awaited<ReturnType<Plugin>>;
+
+function mergeTools(outputs: PluginOutput[]): Record<string, unknown> {
+  const toolMap: Record<string, unknown> = {};
+  for (const output of outputs) {
+    if (output?.tool) {
+      Object.assign(toolMap, output.tool);
+    }
+  }
+  return toolMap;
+}
+
+export const HeartbeatPlugin: Plugin = async (ctx) => {
+  const [memory, scheduler, taskManager] = await Promise.all([
+    MemoryPlugin(ctx),
+    SchedulerPlugin(ctx),
+    TaskManagerPlugin(ctx),
+  ]);
+
+  const mergedTools = mergeTools([memory, scheduler, taskManager]);
+
+  return {
+    tool: {
+      ...mergedTools,
+
+      heartbeat_boot_context: tool({
+        description:
+          "Boot helper for a CPU cycle. Returns task state + prior memory for [program][taskId].",
+        args: {
+          program: tool.schema.string().describe("Program name"),
+          taskId: tool.schema.string().describe("Task identifier"),
+          memoryLimit: tool.schema
+            .number()
+            .optional()
+            .describe("How many recent memory lines to include (default 30)"),
+        },
+        async execute(args) {
+          const memoryLimit =
+            typeof args.memoryLimit === "number" && Number.isFinite(args.memoryLimit)
+              ? args.memoryLimit
+              : 30;
+
+          const snapshot = {
+            task: getTask(args.program, args.taskId) ?? null,
+            memory: searchMemory({
+              program: args.program,
+              taskId: args.taskId,
+              limit: memoryLimit,
+            }),
+            queue: {
+              pending: listTasks({ program: args.program, status: "pending" }),
+              running: listTasks({ program: args.program, status: "running" }),
+              blocked: listTasks({ program: args.program, status: "blocked" }),
+              raised: listTasks({ program: args.program, status: "raised" }),
+            },
+            tagFormat: `[${args.program}][${args.taskId}]`,
+          };
+
+          return JSON.stringify(snapshot, null, 2);
+        },
+      }),
+    },
+  };
+};
+
+export default HeartbeatPlugin;