omoclaw 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onpe5679
+
+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,77 @@
+# omoclaw
+Native event-driven monitoring for OpenCode sessions
+
+[![npm version](https://img.shields.io/npm/v/omoclaw)](https://www.npmjs.com/package/omoclaw)
+
+OpenCode plugin that monitors session state changes and sends webhook notifications. Replaces tmux-based scraping daemons with native event-driven monitoring.
+
+## Installation
+
+Add the plugin to your `~/.config/opencode/opencode.json` file:
+
+```json
+{
+  "plugin": ["omoclaw@latest"]
+}
+```
+
+OpenCode will automatically install the plugin on the next restart.
+
+## Configuration
+
+Create a configuration file at `~/.config/opencode/opencode-monitor.json`:
+
+```json
+{
+  "webhook": {
+    "url": "http://your-webhook-endpoint/hooks/wake",
+    "token": "your-bearer-token"
+  },
+  "staleTimeoutMs": 900000,
+  "permissionReminderMs": 120000,
+  "dedupTtlMs": 30000,
+  "idleConfirmDelayMs": 1500,
+  "debug": false,
+  "enabled": true
+}
+```
+
+### Configuration Fields
+
+- **webhook.url**: The endpoint where notifications will be sent.
+- **webhook.token**: Bearer token for authentication.
+- **staleTimeoutMs**: Timeout for busy sessions (default: 15 minutes).
+- **permissionReminderMs**: Interval to re-notify when waiting for permissions (default: 2 minutes).
+- **dedupTtlMs**: Time window for deduplicating similar notifications (default: 30 seconds).
+- **idleConfirmDelayMs**: Delay before confirming an idle state.
+- **debug**: Enable file logging to `/tmp/opencode-monitor-debug.log`.
+- **enabled**: Toggle the plugin on or off.
+
+## Features
+
+- Session state monitoring (idle/busy/error/retry transitions)
+- Permission wait detection with reminders
+- Agent tracking (Prometheus -> Atlas -> Hephaestus chain)
+- Stale session detection (default: 15 minutes)
+- Deduplication to prevent webhook spam
+- Completion notification with full agent chain
+
+## Webhook Payload Format
+
+The plugin sends a POST request to the configured URL.
+
+### Headers
+- **Authorization**: Bearer <token>
+- **Content-Type**: application/json
+
+### Body
+```json
+{
+  "text": "[OpenCode] ...",
+  "mode": "now"
+}
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export interface MonitorConfig {
+    webhook: {
+        url: string;
+        token: string;
+    };
+    staleTimeoutMs: number;
+    permissionReminderMs: number;
+    dedupTtlMs: number;
+    idleConfirmDelayMs: number;
+    debug: boolean;
+    enabled: boolean;
+}
+export declare function loadConfig(): MonitorConfig;

package/dist/dedup.d.ts

@@ -0,0 +1,6 @@
+export declare class DedupEngine {
+    private readonly ttlMs;
+    private readonly seen;
+    constructor(ttlMs: number);
+    shouldSend(key: string): boolean;
+}

package/dist/handlers/agent.d.ts

@@ -0,0 +1,3 @@
+import type { Event } from "@opencode-ai/sdk";
+import type { SessionStateTracker } from "../state";
+export declare function handleAgentEvent(event: Event, state: SessionStateTracker): void;

package/dist/handlers/permission.d.ts

@@ -0,0 +1,5 @@
+import type { Event } from "@opencode-ai/sdk";
+import type { MonitorConfig } from "../config";
+import type { DedupEngine } from "../dedup";
+import type { TimerManager } from "../timers";
+export declare function handlePermissionEvent(event: Event, _config: MonitorConfig, dedup: DedupEngine, timers: TimerManager, webhookFn: (text: string) => void): void;

package/dist/handlers/session-status.d.ts

@@ -0,0 +1,5 @@
+import type { Event } from "@opencode-ai/sdk";
+import type { DedupEngine } from "../dedup";
+import type { SessionStateTracker } from "../state";
+import type { TimerManager } from "../timers";
+export declare function handleSessionStatusEvent(event: Event, dedup: DedupEngine, state: SessionStateTracker, timers: TimerManager, webhookFn: (text: string) => void, debugLog?: (msg: string) => void): void;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const SessionMonitorPlugin: Plugin;
+export default SessionMonitorPlugin;

package/dist/index.js

@@ -0,0 +1,381 @@
+// @bun
+// src/index.ts
+import fs2 from "fs";
+
+// src/config.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var DEFAULT_CONFIG = {
+  webhook: {
+    url: "",
+    token: ""
+  },
+  staleTimeoutMs: 900000,
+  permissionReminderMs: 120000,
+  dedupTtlMs: 30000,
+  idleConfirmDelayMs: 1500,
+  debug: false,
+  enabled: true
+};
+function stripJsonComments(input) {
+  const noBlock = input.replace(/\/\*[\s\S]*?\*\//g, "");
+  return noBlock.replace(/^\s*\/\/.*$/gm, "");
+}
+function asObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return;
+  }
+  return value;
+}
+function loadConfig() {
+  const filePath = path.join(os.homedir(), ".config", "opencode", "opencode-monitor.json");
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(stripJsonComments(raw));
+    const root = asObject(parsed);
+    if (!root) {
+      return DEFAULT_CONFIG;
+    }
+    const webhook = asObject(root.webhook);
+    return {
+      webhook: {
+        url: typeof webhook?.url === "string" ? webhook.url : DEFAULT_CONFIG.webhook.url,
+        token: typeof webhook?.token === "string" ? webhook.token : DEFAULT_CONFIG.webhook.token
+      },
+      staleTimeoutMs: typeof root.staleTimeoutMs === "number" ? root.staleTimeoutMs : DEFAULT_CONFIG.staleTimeoutMs,
+      permissionReminderMs: typeof root.permissionReminderMs === "number" ? root.permissionReminderMs : DEFAULT_CONFIG.permissionReminderMs,
+      dedupTtlMs: typeof root.dedupTtlMs === "number" ? root.dedupTtlMs : DEFAULT_CONFIG.dedupTtlMs,
+      idleConfirmDelayMs: typeof root.idleConfirmDelayMs === "number" ? root.idleConfirmDelayMs : DEFAULT_CONFIG.idleConfirmDelayMs,
+      debug: typeof root.debug === "boolean" ? root.debug : DEFAULT_CONFIG.debug,
+      enabled: typeof root.enabled === "boolean" ? root.enabled : DEFAULT_CONFIG.enabled
+    };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+// src/dedup.ts
+class DedupEngine {
+  ttlMs;
+  seen = new Map;
+  constructor(ttlMs) {
+    this.ttlMs = ttlMs;
+  }
+  shouldSend(key) {
+    const now = Date.now();
+    const prev = this.seen.get(key);
+    if (this.seen.size > 100) {
+      for (const [existingKey, timestamp] of this.seen.entries()) {
+        if (now - timestamp > this.ttlMs) {
+          this.seen.delete(existingKey);
+        }
+      }
+    }
+    if (prev !== undefined && now - prev <= this.ttlMs) {
+      return false;
+    }
+    this.seen.set(key, now);
+    return true;
+  }
+}
+
+// src/handlers/agent.ts
+function handleAgentEvent(event, state) {
+  if (event.type === "message.updated") {
+    const info = event.properties?.info;
+    const agent = info?.agent;
+    const sessionID = info?.sessionID;
+    if (typeof agent === "string" && typeof sessionID === "string") {
+      state.setAgent(sessionID, agent);
+    }
+    return;
+  }
+  if (event.type === "message.part.updated") {
+    const { part } = event.properties;
+    if (part.type === "agent" && part.name) {
+      state.setAgent(part.sessionID, part.name);
+    }
+  }
+}
+
+// src/handlers/permission.ts
+function handlePermissionEvent(event, _config, dedup, timers, webhookFn) {
+  if (event.type === "permission.updated") {
+    const permission = event.properties;
+    const dedupKey = `perm:${permission.id}`;
+    if (dedup.shouldSend(dedupKey)) {
+      webhookFn(`[OpenCode] Permission wait: ${permission.title} (${permission.sessionID})`);
+    }
+    timers.startPermissionReminder(permission.id, permission.title, permission.sessionID);
+    return;
+  }
+  if (event.type === "permission.replied") {
+    timers.clearPermissionReminder(event.properties.permissionID);
+  }
+}
+
+// src/handlers/session-status.ts
+function shortSessionID(sessionID) {
+  return sessionID.slice(0, 12);
+}
+function buildAgentChain(state, sessionID) {
+  const history = state.getAgentHistory(sessionID);
+  if (history.length === 0) {
+    return "unknown-agent";
+  }
+  return history.join(" -> ");
+}
+function toSessionStatus(statusType) {
+  if (statusType === "idle" || statusType === "busy" || statusType === "retry" || statusType === "error" || statusType === "unknown") {
+    return statusType;
+  }
+  return "unknown";
+}
+function handleSessionStatusEvent(event, dedup, state, timers, webhookFn, debugLog) {
+  const log = debugLog ?? (() => {});
+  if (event.type === "session.status") {
+    const sessionID = event.properties.sessionID;
+    const status = event.properties.status;
+    const statusType = toSessionStatus(status.type);
+    const transition = state.transition(sessionID, statusType);
+    if (transition.changed && transition.current === "busy") {
+      state.setBusySince(sessionID, Date.now());
+      timers.startStaleTimer(sessionID);
+      return;
+    }
+    if (transition.changed && transition.current === "idle" && transition.prev === "busy") {
+      log(`busy\u2192idle transition detected for ${shortSessionID(sessionID)}`);
+      const dedupKey = `idle:${sessionID}`;
+      if (dedup.shouldSend(dedupKey)) {
+        const agentChain = buildAgentChain(state, sessionID);
+        log(`Sending webhook: agentChain=${agentChain}`);
+        webhookFn(`[OpenCode] Session completed (${shortSessionID(sessionID)}) \u2014 ${agentChain}`);
+      }
+      timers.clearStaleTimer(sessionID);
+      state.clearSession(sessionID);
+      return;
+    }
+    if (transition.current === "retry" && status.type === "retry") {
+      const dedupKey = `retry:${sessionID}:${status.attempt}`;
+      if (dedup.shouldSend(dedupKey)) {
+        webhookFn(`[OpenCode] Retry #${status.attempt}: ${status.message} (${shortSessionID(sessionID)})`);
+      }
+    }
+    return;
+  }
+  if (event.type === "session.error") {
+    const sessionID = event.properties.sessionID;
+    if (!sessionID) {
+      return;
+    }
+    state.transition(sessionID, "error");
+    timers.clearStaleTimer(sessionID);
+    const errorName = event.properties.error?.name ?? "UnknownError";
+    const dedupKey = `error:${sessionID}:${errorName}`;
+    if (dedup.shouldSend(dedupKey)) {
+      webhookFn(`[OpenCode] Error: ${errorName} (${shortSessionID(sessionID)})`);
+    }
+  }
+}
+
+// src/state.ts
+class SessionStateTracker {
+  states = new Map;
+  agentHistory = new Map;
+  transition(sessionID, newStatus) {
+    const now = Date.now();
+    const existing = this.states.get(sessionID);
+    if (!existing) {
+      this.states.set(sessionID, {
+        status: newStatus,
+        agent: undefined,
+        busySince: newStatus === "busy" ? now : undefined,
+        lastTransition: now
+      });
+      return {
+        changed: true,
+        prev: "unknown",
+        current: newStatus
+      };
+    }
+    if (existing.status === newStatus) {
+      return {
+        changed: false,
+        prev: existing.status,
+        current: existing.status
+      };
+    }
+    const prev = existing.status;
+    existing.status = newStatus;
+    existing.lastTransition = now;
+    if (newStatus === "busy") {
+      existing.busySince = now;
+    }
+    if (newStatus === "idle") {
+      existing.busySince = undefined;
+    }
+    return {
+      changed: true,
+      prev,
+      current: newStatus
+    };
+  }
+  setAgent(sessionID, agentName) {
+    const existing = this.states.get(sessionID);
+    if (existing) {
+      existing.agent = agentName;
+    } else {
+      this.states.set(sessionID, {
+        status: "unknown",
+        agent: agentName,
+        busySince: undefined,
+        lastTransition: Date.now()
+      });
+    }
+    const history = this.agentHistory.get(sessionID) ?? [];
+    if (history[history.length - 1] !== agentName) {
+      history.push(agentName);
+    }
+    this.agentHistory.set(sessionID, history);
+  }
+  getAgent(sessionID) {
+    return this.states.get(sessionID)?.agent;
+  }
+  getState(sessionID) {
+    return this.states.get(sessionID);
+  }
+  getAgentHistory(sessionID) {
+    return [...this.agentHistory.get(sessionID) ?? []];
+  }
+  setBusySince(sessionID, time) {
+    const existing = this.states.get(sessionID);
+    if (existing) {
+      existing.busySince = time;
+      return;
+    }
+    this.states.set(sessionID, {
+      status: "busy",
+      agent: undefined,
+      busySince: time,
+      lastTransition: Date.now()
+    });
+  }
+  clearSession(sessionID) {
+    this.states.delete(sessionID);
+    this.agentHistory.delete(sessionID);
+  }
+}
+
+// src/timers.ts
+class TimerManager {
+  config;
+  webhookFn;
+  staleTimers = new Map;
+  permissionTimers = new Map;
+  constructor(config, webhookFn) {
+    this.config = config;
+    this.webhookFn = webhookFn;
+  }
+  startStaleTimer(sessionID) {
+    this.clearStaleTimer(sessionID);
+    const timer = setTimeout(() => {
+      this.webhookFn(`[OpenCode] Session stale: ${sessionID.slice(0, 12)} (${sessionID})`);
+      this.staleTimers.delete(sessionID);
+    }, this.config.staleTimeoutMs);
+    this.staleTimers.set(sessionID, timer);
+  }
+  clearStaleTimer(sessionID) {
+    const timer = this.staleTimers.get(sessionID);
+    if (!timer) {
+      return;
+    }
+    clearTimeout(timer);
+    this.staleTimers.delete(sessionID);
+  }
+  startPermissionReminder(permissionID, title, sessionID) {
+    this.clearPermissionReminder(permissionID);
+    const timer = setTimeout(() => {
+      this.webhookFn(`[OpenCode] Permission still waiting: ${title} (${sessionID})`);
+      this.permissionTimers.delete(permissionID);
+    }, this.config.permissionReminderMs);
+    this.permissionTimers.set(permissionID, { sessionID, timer });
+  }
+  clearPermissionReminder(permissionID) {
+    const existing = this.permissionTimers.get(permissionID);
+    if (!existing) {
+      return;
+    }
+    clearTimeout(existing.timer);
+    this.permissionTimers.delete(permissionID);
+  }
+  clearSession(sessionID) {
+    this.clearStaleTimer(sessionID);
+    for (const [permissionID, entry] of this.permissionTimers.entries()) {
+      if (entry.sessionID === sessionID) {
+        clearTimeout(entry.timer);
+        this.permissionTimers.delete(permissionID);
+      }
+    }
+  }
+}
+
+// src/webhook.ts
+function sendWebhook(config, text) {
+  fetch(config.webhook.url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.webhook.token}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ text, mode: "now" })
+  }).then(() => {
+    console.log("[monitor] webhook sent:", text);
+  }).catch((error) => {
+    console.error("[monitor] webhook error:", error);
+  });
+}
+
+// src/index.ts
+var DEBUG_LOG_PATH = "/tmp/opencode-monitor-debug.log";
+var SessionMonitorPlugin = async (_ctx) => {
+  const config = loadConfig();
+  const debugLog = config.debug ? (msg) => {
+    const line = `[${new Date().toISOString()}] ${msg}
+`;
+    try {
+      fs2.appendFileSync(DEBUG_LOG_PATH, line);
+    } catch {}
+  } : undefined;
+  debugLog?.("Plugin initializing...");
+  debugLog?.(`Config loaded: enabled=${config.enabled}, url=${config.webhook.url}`);
+  if (!config.enabled) {
+    debugLog?.("Plugin disabled, exiting.");
+    return {};
+  }
+  if (!config.webhook.url || !config.webhook.token) {
+    console.log("[monitor] Webhook not configured. Set webhook.url and webhook.token in ~/.config/opencode/opencode-monitor.json");
+    return {};
+  }
+  const dedup = new DedupEngine(config.dedupTtlMs);
+  const state = new SessionStateTracker;
+  const webhookFn = (text) => {
+    debugLog?.(`WEBHOOK: ${text}`);
+    sendWebhook(config, text);
+  };
+  const timers = new TimerManager(config, webhookFn);
+  debugLog?.("Plugin loaded successfully. Waiting for events...");
+  console.log("[monitor] Session monitor plugin loaded");
+  return {
+    event: async ({ event }) => {
+      debugLog?.(`EVENT: ${event.type} props=${JSON.stringify(event.properties).slice(0, 200)}`);
+      handleAgentEvent(event, state);
+      handlePermissionEvent(event, config, dedup, timers, webhookFn);
+      handleSessionStatusEvent(event, dedup, state, timers, webhookFn, debugLog);
+    }
+  };
+};
+var src_default = SessionMonitorPlugin;
+export {
+  src_default as default
+};

package/dist/state.d.ts

@@ -0,0 +1,24 @@
+type SessionStatus = "idle" | "busy" | "retry" | "error" | "unknown";
+interface SessionState {
+    status: SessionStatus;
+    agent: string | undefined;
+    busySince: number | undefined;
+    lastTransition: number;
+}
+interface TransitionResult {
+    changed: boolean;
+    prev: SessionStatus;
+    current: SessionStatus;
+}
+export declare class SessionStateTracker {
+    private readonly states;
+    private readonly agentHistory;
+    transition(sessionID: string, newStatus: SessionStatus): TransitionResult;
+    setAgent(sessionID: string, agentName: string): void;
+    getAgent(sessionID: string): string | undefined;
+    getState(sessionID: string): SessionState | undefined;
+    getAgentHistory(sessionID: string): string[];
+    setBusySince(sessionID: string, time: number): void;
+    clearSession(sessionID: string): void;
+}
+export type { SessionStatus };

package/dist/timers.d.ts

@@ -0,0 +1,13 @@
+import type { MonitorConfig } from "./config";
+export declare class TimerManager {
+    private readonly config;
+    private readonly webhookFn;
+    private readonly staleTimers;
+    private readonly permissionTimers;
+    constructor(config: MonitorConfig, webhookFn: (text: string) => void);
+    startStaleTimer(sessionID: string): void;
+    clearStaleTimer(sessionID: string): void;
+    startPermissionReminder(permissionID: string, title: string, sessionID: string): void;
+    clearPermissionReminder(permissionID: string): void;
+    clearSession(sessionID: string): void;
+}

package/dist/webhook.d.ts

@@ -0,0 +1,2 @@
+import type { MonitorConfig } from "./config";
+export declare function sendWebhook(config: MonitorConfig, text: string): void;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "omoclaw",
+  "version": "1.0.0",
+  "description": "OpenCode session monitor plugin — native event-driven webhook notifications for session state changes",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "monitor",
+    "webhook"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onpe5679/omoclaw.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.1.19",
+    "@opencode-ai/sdk": "^1.1.19"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.6",
+    "typescript": "^5.7.3"
+  }
+}