@preziosiraffaele/agent-watch 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raffaele Preziosi
+
+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/bin/agent-watchd

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import('../dist/agent-watchd.js');

package/bin/aw

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { main } from '../dist/aw.js';
+
+const code = await main(process.argv.slice(2));
+process.exit(code);

package/dist/agent-watchd.js

@@ -0,0 +1,603 @@
+// @bun
+// packages/agent-core/src/types.ts
+var AGENT_FILTER_KEYS = ["nvim_server", "repo"];
+// packages/agent-core/src/protocol.ts
+var DEFAULT_DAEMON_HOST = "127.0.0.1";
+var DEFAULT_DAEMON_PORT = 3847;
+var DEFAULT_DAEMON_URL = `http://${DEFAULT_DAEMON_HOST}:${DEFAULT_DAEMON_PORT}`;
+var ENV = {
+  LAUNCH_ID: "AGENT_WATCH_LAUNCH_ID",
+  DAEMON_URL: "AGENT_WATCH_DAEMON_URL",
+  DAEMON_PORT: "AGENT_WATCH_DAEMON_PORT",
+  DAEMON_HOST: "AGENT_WATCH_DAEMON_HOST"
+};
+var SUPPORTED_AGENTS = ["claude", "codex", "agent"];
+function isSupportedAgent(name) {
+  return SUPPORTED_AGENTS.includes(name);
+}
+// packages/agent-core/src/states.ts
+var STATES = {
+  SESSION_STARTED: "session_started",
+  WORKING: "working",
+  RUNNING_TOOL: "running_tool",
+  RUNNING_SHELL: "running_shell",
+  NEEDS_APPROVAL: "needs_approval",
+  EDITED_FILE: "edited_file",
+  WAITING: "waiting",
+  IDLE: "idle",
+  STALE: "stale",
+  EXITED: "exited",
+  FAILED: "failed"
+};
+var STALE_AFTER_MS = 30 * 60 * 1000;
+// packages/agent-core/src/events.ts
+var CLAUDE_STATE = {
+  SessionStart: STATES.SESSION_STARTED,
+  UserPromptSubmit: STATES.WORKING,
+  UserPromptExpansion: STATES.WORKING,
+  PreToolUse: STATES.RUNNING_TOOL,
+  PermissionRequest: STATES.NEEDS_APPROVAL,
+  PermissionDenied: STATES.WORKING,
+  PostToolUse: STATES.WORKING,
+  PostToolUseFailure: STATES.WORKING,
+  PostToolBatch: STATES.WORKING,
+  Notification: STATES.WAITING,
+  SubagentStart: STATES.RUNNING_TOOL,
+  SubagentStop: STATES.IDLE,
+  TaskCreated: STATES.RUNNING_TOOL,
+  TaskCompleted: STATES.WORKING,
+  Stop: STATES.IDLE,
+  StopFailure: STATES.IDLE,
+  SessionEnd: STATES.IDLE
+};
+var CODEX_STATE = {
+  SessionStart: STATES.SESSION_STARTED,
+  UserPromptSubmit: STATES.WORKING,
+  PreToolUse: STATES.RUNNING_TOOL,
+  PermissionRequest: STATES.NEEDS_APPROVAL,
+  PostToolUse: STATES.WORKING,
+  Stop: STATES.IDLE
+};
+var AGENT_STATE = {
+  sessionStart: STATES.SESSION_STARTED,
+  beforeSubmitPrompt: STATES.WORKING,
+  preToolUse: STATES.RUNNING_TOOL,
+  beforeShellExecution: STATES.RUNNING_SHELL,
+  afterShellExecution: STATES.WORKING,
+  beforeMCPExecution: STATES.RUNNING_TOOL,
+  afterMCPExecution: STATES.WORKING,
+  beforeReadFile: STATES.RUNNING_TOOL,
+  afterFileEdit: STATES.EDITED_FILE,
+  postToolUse: STATES.WORKING,
+  postToolUseFailure: STATES.WORKING,
+  subagentStart: STATES.RUNNING_TOOL,
+  subagentStop: STATES.WORKING,
+  stop: STATES.IDLE,
+  sessionEnd: STATES.IDLE
+};
+var CLAUDE_EVENTS = Object.keys(CLAUDE_STATE);
+var CODEX_EVENTS = Object.keys(CODEX_STATE);
+var AGENT_EVENTS = Object.keys(AGENT_STATE);
+function stateFor(agent, event) {
+  if (agent === "claude")
+    return CLAUDE_STATE[event] ?? STATES.WORKING;
+  if (agent === "codex")
+    return CODEX_STATE[event] ?? STATES.WORKING;
+  if (agent === "agent")
+    return AGENT_STATE[event] ?? STATES.WORKING;
+  return STATES.WORKING;
+}
+// packages/agent-core/src/repo.ts
+import { basename } from "path";
+function inferRepoContext(folder, runGit) {
+  if (!folder)
+    return { repo: null, repo_root: null, branch: null };
+  const root = runGit(folder, ["rev-parse", "--show-toplevel"]);
+  if (!root)
+    return { repo: null, repo_root: null, branch: null };
+  const branch = runGit(folder, ["branch", "--show-current"]) || runGit(folder, ["rev-parse", "--short", "HEAD"]);
+  return {
+    repo: basename(root),
+    repo_root: root,
+    branch: branch || null
+  };
+}
+var realGitRunner = (folder, args) => {
+  try {
+    const proc = Bun.spawnSync(["git", "-C", folder, ...args], {
+      stdout: "pipe",
+      stderr: "ignore"
+    });
+    if (!proc.success)
+      return null;
+    const output = proc.stdout?.toString().trim();
+    return output || null;
+  } catch {
+    return null;
+  }
+};
+// packages/agent-core/src/payload.ts
+function asString(value) {
+  if (typeof value === "string" && value.trim())
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function firstString(payload, keys) {
+  if (!isObject(payload))
+    return null;
+  for (const key of keys) {
+    const found = asString(payload[key]);
+    if (found)
+      return found;
+  }
+  return null;
+}
+function firstStringPath(payload, paths) {
+  for (const parts of paths) {
+    let current = payload;
+    let ok = true;
+    for (const part of parts) {
+      if (!isObject(current)) {
+        ok = false;
+        break;
+      }
+      current = current[part];
+    }
+    if (ok) {
+      const found = asString(current);
+      if (found)
+        return found;
+    }
+  }
+  return null;
+}
+function pickToolName(payload) {
+  const command = firstStringPath(payload, [
+    ["command"],
+    ["shell_command"],
+    ["shellCommand"],
+    ["tool_input", "command"],
+    ["toolInput", "command"],
+    ["input", "command"],
+    ["arguments", "command"],
+    ["args", "command"]
+  ]);
+  if (command)
+    return command;
+  const tool = firstString(payload, ["tool_name", "toolName", "tool", "name"]);
+  if (tool)
+    return tool;
+  return firstStringPath(payload, [
+    ["tool", "name"],
+    ["tool", "type"],
+    ["tool_call", "name"],
+    ["toolCall", "name"]
+  ]) ?? "-";
+}
+function pickSessionId(payload) {
+  return firstString(payload, [
+    "session_id",
+    "sessionId",
+    "session",
+    "conversation_id",
+    "conversationId",
+    "thread_id",
+    "threadId"
+  ]);
+}
+function pickClaudeEventName(payload) {
+  return firstString(payload, ["hook_event_name", "hookEventName"]);
+}
+// packages/agent-core/src/daemon-state.ts
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var DAEMON_RUNTIME_DIR_NAME = ".agent-watch";
+var DAEMON_STATE_FILE_NAME = "daemon.json";
+function daemonRuntimeDir(home = homedir()) {
+  return join(home, DAEMON_RUNTIME_DIR_NAME);
+}
+function daemonStatePath(runtimeDir = daemonRuntimeDir()) {
+  return join(runtimeDir, DAEMON_STATE_FILE_NAME);
+}
+function writeDaemonState(state, path = daemonStatePath()) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}
+`);
+  renameSync(tempPath, path);
+}
+function removeDaemonState(path = daemonStatePath()) {
+  try {
+    rmSync(path, { force: true });
+  } catch {}
+}
+// packages/agent-watchd/src/registry.ts
+function createRegistry(options = {}) {
+  const records = new Map;
+  const subscribers = new Set;
+  const gitRunner = options.gitRunner ?? realGitRunner;
+  const now = options.now ?? (() => new Date);
+  let nextId = 1;
+  let seq = 0;
+  const broadcast = (event) => {
+    for (const fn of subscribers) {
+      try {
+        fn(event);
+      } catch {}
+    }
+  };
+  const register = (reg) => {
+    const id = nextId++;
+    const repo2 = inferRepoContext(reg.folder, gitRunner);
+    const record = {
+      id,
+      agent: reg.agent,
+      state: STATES.SESSION_STARTED,
+      title: reg.title ?? null,
+      session_id: null,
+      recent_events: [],
+      tool: "-",
+      folder: reg.folder,
+      repo: repo2.repo,
+      repo_root: repo2.repo_root,
+      branch: repo2.branch,
+      updated: now().toISOString(),
+      agent_process_pid: null,
+      nvim_server: reg.nvim?.server ?? null,
+      nvim_terminal_bufnr: reg.nvim?.terminalBufnr ?? null
+    };
+    records.set(id, record);
+    broadcast({ type: "created", record });
+    return record;
+  };
+  const update = (id, patch) => {
+    const current = records.get(id);
+    if (!current)
+      return null;
+    const next = {
+      ...current,
+      agent_process_pid: patch.agent_process_pid !== undefined ? patch.agent_process_pid : current.agent_process_pid,
+      state: patch.state ?? current.state,
+      title: patch.title !== undefined ? patch.title : current.title,
+      updated: now().toISOString()
+    };
+    records.set(id, next);
+    broadcast({ type: "updated", record: next });
+    return next;
+  };
+  const applyHook = (id, agent, hook) => {
+    const current = records.get(id);
+    if (!current)
+      return null;
+    const received_at = now().toISOString();
+    seq += 1;
+    const state = agent === "claude" && hook.event === "SubagentStop" && current.state === STATES.IDLE ? current.state : hook.state;
+    const next = {
+      ...current,
+      agent: current.agent || agent,
+      state,
+      tool: hook.tool || current.tool,
+      session_id: hook.session_id ?? current.session_id,
+      recent_events: [...current.recent_events, { event: hook.event, received_at, seq }].slice(-3),
+      updated: received_at
+    };
+    records.set(id, next);
+    broadcast({ type: "updated", record: next });
+    return next;
+  };
+  const remove = (id) => {
+    if (!records.has(id))
+      return false;
+    records.delete(id);
+    broadcast({ type: "removed", id });
+    return true;
+  };
+  const refreshRepoContext = () => {
+    const recordsByFolder = new Map;
+    for (const record of records.values()) {
+      if (!record.folder)
+        continue;
+      const grouped = recordsByFolder.get(record.folder);
+      if (grouped) {
+        grouped.push(record);
+      } else {
+        recordsByFolder.set(record.folder, [record]);
+      }
+    }
+    const changed = [];
+    for (const [folder, folderRecords] of recordsByFolder) {
+      const repo2 = inferRepoContext(folder, gitRunner);
+      for (const current of folderRecords) {
+        if (current.repo === repo2.repo && current.repo_root === repo2.repo_root && current.branch === repo2.branch) {
+          continue;
+        }
+        const next = {
+          ...current,
+          repo: repo2.repo,
+          repo_root: repo2.repo_root,
+          branch: repo2.branch,
+          updated: now().toISOString()
+        };
+        records.set(next.id, next);
+        changed.push(next);
+        broadcast({ type: "updated", record: next });
+      }
+    }
+    return changed;
+  };
+  return {
+    register,
+    update,
+    remove,
+    applyHook,
+    refreshRepoContext,
+    get(id) {
+      return records.get(id);
+    },
+    list() {
+      return Array.from(records.values()).sort((a, b) => a.id - b.id);
+    },
+    subscribe(fn) {
+      subscribers.add(fn);
+      return () => {
+        subscribers.delete(fn);
+      };
+    }
+  };
+}
+
+// packages/agent-watchd/src/queue.ts
+function createPerLaunchQueue() {
+  const tails = new Map;
+  return {
+    enqueue(launchId, task) {
+      const previous = tails.get(launchId) ?? Promise.resolve();
+      const next = previous.then(() => task());
+      const swallowed = next.catch(() => {
+        return;
+      });
+      tails.set(launchId, swallowed);
+      swallowed.finally(() => {
+        if (tails.get(launchId) === swallowed)
+          tails.delete(launchId);
+      });
+      return next;
+    }
+  };
+}
+
+// packages/agent-watchd/src/hooks.ts
+function normalizeHook(agent, fallbackEvent, payload2) {
+  const event = agent === "claude" && pickClaudeEventName(payload2) || fallbackEvent || "unknown";
+  return {
+    event,
+    state: stateFor(agent, event),
+    tool: pickToolName(payload2),
+    session_id: pickSessionId(payload2)
+  };
+}
+function parseJson(input) {
+  if (!input.trim())
+    return {};
+  try {
+    return JSON.parse(input);
+  } catch {
+    return {};
+  }
+}
+
+// packages/agent-watchd/src/server.ts
+var DEFAULT_REPO_CONTEXT_REFRESH_INTERVAL_MS = 1e4;
+var json = (data, init) => new Response(JSON.stringify(data), {
+  ...init,
+  headers: { "content-type": "application/json", ...init?.headers ?? {} }
+});
+var text = (status, body) => new Response(body, { status, headers: { "content-type": "text/plain" } });
+function startDaemon(options = {}) {
+  const registry = options.registry ?? createRegistry(options.registryOptions);
+  const queue = options.queue ?? createPerLaunchQueue();
+  const onShutdown = options.onShutdown;
+  const server = Bun.serve({
+    port: options.port ?? 0,
+    hostname: options.hostname ?? "127.0.0.1",
+    fetch: (request) => handle(request, registry, queue, onShutdown)
+  });
+  const repoContextRefresh = startRepoContextRefresh(registry, options.repoContextRefreshIntervalMs ?? DEFAULT_REPO_CONTEXT_REFRESH_INTERVAL_MS);
+  const port = server.port ?? options.port ?? 0;
+  const url = `http://${server.hostname}:${port}`;
+  const statePath = options.statePath ?? daemonStatePath();
+  writeDaemonState({
+    version: 1,
+    url,
+    pid: process.pid,
+    started_at: new Date().toISOString()
+  }, statePath);
+  return {
+    registry,
+    url,
+    port,
+    async stop() {
+      repoContextRefresh.stop();
+      await server.stop(true);
+      removeDaemonState(statePath);
+    }
+  };
+}
+function startRepoContextRefresh(registry, intervalMs) {
+  let timer = null;
+  const stopTimer = () => {
+    if (!timer)
+      return;
+    clearInterval(timer);
+    timer = null;
+  };
+  const startTimer = () => {
+    if (timer || registry.list().length === 0)
+      return;
+    timer = setInterval(() => {
+      registry.refreshRepoContext();
+    }, intervalMs);
+  };
+  const unsubscribe = registry.subscribe((event) => {
+    if (event.type === "created")
+      startTimer();
+    if (event.type === "removed" && registry.list().length === 0)
+      stopTimer();
+  });
+  startTimer();
+  return {
+    stop() {
+      unsubscribe();
+      stopTimer();
+    }
+  };
+}
+async function handle(request, registry, queue, onShutdown) {
+  const url = new URL(request.url);
+  const method = request.method.toUpperCase();
+  const path = url.pathname;
+  if (method === "GET" && path === "/healthz")
+    return json({ ok: true });
+  if (method === "GET" && path === "/agents") {
+    let agents = registry.list();
+    for (const key of AGENT_FILTER_KEYS) {
+      if (url.searchParams.has(key)) {
+        const value = url.searchParams.get(key);
+        const expected = value === "" ? null : value;
+        agents = agents.filter((a) => a[key] === expected);
+      }
+    }
+    return json({ agents });
+  }
+  if (method === "POST" && path === "/shutdown") {
+    setTimeout(() => onShutdown?.(), 0);
+    return json({ ok: true });
+  }
+  if (method === "POST" && path === "/launches") {
+    const reg = await readLaunchRegistration(request);
+    if (!reg)
+      return text(400, "invalid launch registration");
+    const record = registry.register(reg);
+    return json(record, { status: 201 });
+  }
+  const launchPatch = method === "PATCH" && path.match(/^\/launches\/(\d+)$/);
+  if (launchPatch) {
+    const id = Number(launchPatch[1]);
+    const patch = await readLaunchUpdate(request);
+    if (!patch)
+      return text(400, "invalid launch update");
+    const updated = registry.update(id, patch);
+    if (!updated)
+      return text(404, "launch not found");
+    return json(updated);
+  }
+  const launchDelete = method === "DELETE" && path.match(/^\/launches\/(\d+)$/);
+  if (launchDelete) {
+    const id = Number(launchDelete[1]);
+    const removed = registry.remove(id);
+    if (!removed)
+      return text(404, "launch not found");
+    return json({ ok: true });
+  }
+  const hookMatch = method === "POST" && path.match(/^\/hooks\/(claude|codex|agent)$/);
+  if (hookMatch) {
+    const agent = hookMatch[1];
+    if (!agent || !isSupportedAgent(agent))
+      return text(400, "unsupported agent");
+    const launchId = Number(url.searchParams.get("launch_id"));
+    if (!Number.isInteger(launchId) || launchId <= 0) {
+      return text(400, "missing or invalid launch_id");
+    }
+    if (!registry.get(launchId)) {
+      return text(202, "unknown launch");
+    }
+    const event = url.searchParams.get("event") ?? "unknown";
+    const body = await request.text();
+    const payload2 = parseJson(body);
+    await queue.enqueue(launchId, () => {
+      const normalized = normalizeHook(agent, event, payload2);
+      registry.applyHook(launchId, agent, normalized);
+    });
+    return json({ ok: true });
+  }
+  return text(404, "not found");
+}
+async function readLaunchRegistration(request) {
+  const data = await readJson(request);
+  if (!data)
+    return null;
+  if (typeof data.agent !== "string" || !data.agent)
+    return null;
+  if (typeof data.folder !== "string" || !data.folder)
+    return null;
+  return {
+    agent: data.agent,
+    folder: data.folder,
+    title: typeof data.title === "string" ? data.title : null,
+    nvim: {
+      server: typeof data.nvim_server === "string" ? data.nvim_server : null,
+      terminalBufnr: typeof data.nvim_terminal_bufnr === "string" ? data.nvim_terminal_bufnr : null
+    }
+  };
+}
+async function readLaunchUpdate(request) {
+  const data = await readJson(request);
+  if (!data)
+    return null;
+  const patch = {};
+  if ("agent_process_pid" in data) {
+    const value = data.agent_process_pid;
+    patch.agent_process_pid = typeof value === "number" ? value : null;
+  }
+  if (typeof data.state === "string")
+    patch.state = data.state;
+  if ("title" in data) {
+    patch.title = typeof data.title === "string" ? data.title : null;
+  }
+  return patch;
+}
+async function readJson(request) {
+  try {
+    const data = await request.json();
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      return data;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// packages/agent-watchd/src/index.ts
+function readPort() {
+  const raw = process.env[ENV.DAEMON_PORT];
+  if (!raw)
+    return DEFAULT_DAEMON_PORT;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0)
+    return DEFAULT_DAEMON_PORT;
+  return parsed;
+}
+function main() {
+  let stop = async () => {};
+  const handle2 = startDaemon({
+    port: readPort(),
+    hostname: process.env[ENV.DAEMON_HOST] ?? DEFAULT_DAEMON_HOST,
+    onShutdown: () => stop()
+  });
+  process.stdout.write(`agent-watchd listening on ${handle2.url}
+`);
+  stop = async () => {
+    await handle2.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+}
+main();