claude-comms 1.0.46 → 2.0.1

package/.agents/tools/workflow/config.example.json

@@ -1,16 +0,0 @@
-{
-  "convexUrl": "https://your-project.convex.cloud",
-  "namespace": "my-project",
-  "timeoutMs": 3600000,
-  "idleTimeoutMs": 600000,
-  "harnessDefaults": {
-    "default": "claude",
-    "plan": "claude",
-    "implement": "claude",
-    "review": "claude",
-    "uat": "claude",
-    "document": "claude",
-    "pm": "claude",
-    "chat": "claude"
-  }
-}

package/.agents/tools/workflow/init.ts

@@ -1,76 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * Workflow Init Script
- *
- * Initializes the namespace in the Convex database based on config.json.
- * This script is idempotent - running it multiple times won't create duplicates.
- *
- * Usage:
- *   npx tsx init.ts
- */
-
-import { ConvexClient } from "convex/browser";
-import { anyApi } from "convex/server";
-import { readFileSync, existsSync } from "fs";
-import { dirname, join } from "path";
-import { fileURLToPath } from "url";
-
-const api = anyApi;
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-interface Config {
-  convexUrl: string;
-  namespace: string;
-  timeoutMs?: number;
-  harnessDefaults?: {
-    default: "claude" | "codex" | "gemini";
-    [jobType: string]: "claude" | "codex" | "gemini";
-  };
-}
-
-function loadConfig(): Config {
-  const configPath = join(__dirname, "config.json");
-  if (!existsSync(configPath)) {
-    console.error("Error: config.json not found at", configPath);
-    console.error("Please copy config.example.json to config.json and configure it.");
-    process.exit(1);
-  }
-  return JSON.parse(readFileSync(configPath, "utf-8"));
-}
-
-async function main() {
-  const config = loadConfig();
-  console.log(`Initializing namespace: ${config.namespace}`);
-  console.log(`Convex URL: ${config.convexUrl}`);
-
-  const client = new ConvexClient(config.convexUrl);
-
-  try {
-    // Check if namespace already exists
-    const existing = await client.query(api.namespaces.getByName, {
-      name: config.namespace,
-    });
-
-    if (existing) {
-      console.log(`Namespace "${config.namespace}" already exists with ID: ${existing._id}`);
-      console.log("No action needed - idempotent check passed.");
-    } else {
-      // Create the namespace
-      const namespaceId = await client.mutation(api.namespaces.create, {
-        name: config.namespace,
-        description: `Namespace for ${config.namespace} repo`,
-      });
-      console.log(`Created namespace "${config.namespace}" with ID: ${namespaceId}`);
-    }
-
-    console.log("\nInit complete!");
-  } catch (error) {
-    console.error("Error during init:", error);
-    process.exit(1);
-  } finally {
-    await client.close();
-  }
-}
-
-main();

package/.agents/tools/workflow/lib/file-tracker.test.ts

@@ -1,81 +0,0 @@
-/**
- * Tests for file-based job tracking module
- *
- * Run with: npx tsx --test lib/file-tracker.test.ts
- */
-
-import { describe, it, before, after } from "node:test";
-import assert from "node:assert";
-import { rmSync, existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { JobTracker } from "./file-tracker.js";
-
-// ============================================================================
-// JobTracker tests - the high-level API that matters
-// ============================================================================
-
-describe("JobTracker", () => {
-  const TEST_ROOT = join(tmpdir(), "agent_jobs_test_" + Date.now());
-
-  before(() => {
-    process.env.AGENT_JOBS_ROOT = TEST_ROOT;
-  });
-
-  after(() => {
-    delete process.env.AGENT_JOBS_ROOT;
-    if (existsSync(TEST_ROOT)) {
-      rmSync(TEST_ROOT, { recursive: true, force: true });
-    }
-  });
-
-  it("creates status.json with correct initial state", () => {
-    const tracker = new JobTracker("init-test", "claude", 12345);
-    const status = tracker.getStatus();
-
-    assert.strictEqual(status.job_id, "init-test");
-    assert.strictEqual(status.harness, "claude");
-    assert.strictEqual(status.pid, 12345);
-    assert.strictEqual(status.status, "running");
-    assert.ok(status.logs?.endsWith("agent.log"));
-  });
-
-  it("records events with operations count and status reason", () => {
-    const tracker = new JobTracker("events-test", "codex", 99999);
-
-    tracker.recordEvent("assistant");
-    tracker.recordEvent("tool_use");
-    tracker.recordEvent();
-
-    const status = tracker.getStatus();
-    assert.strictEqual(status.operations, 3);
-    assert.strictEqual(status.status_reason, "tool_use"); // last explicit
-  });
-
-  it("logs lines to agent.log", () => {
-    const tracker = new JobTracker("log-test", "gemini", 11111);
-
-    tracker.logLine('{"type":"init"}');
-    tracker.logLine('{"type":"result"}');
-
-    const content = readFileSync(tracker.getLogPath(), "utf-8");
-    assert.ok(content.includes("init"));
-    assert.ok(content.includes("result"));
-  });
-
-  it("marks complete/fail/timeout with end_time", () => {
-    const t1 = new JobTracker("complete-test", "claude", 1);
-    t1.complete("Done");
-    assert.strictEqual(t1.getStatus().status, "complete");
-    assert.ok(t1.getStatus().end_time);
-
-    const t2 = new JobTracker("fail-test", "claude", 2);
-    t2.fail("exit_1");
-    assert.strictEqual(t2.getStatus().status, "error");
-    assert.strictEqual(t2.getStatus().status_reason, "exit_1");
-
-    const t3 = new JobTracker("timeout-test", "claude", 3);
-    t3.timeout();
-    assert.strictEqual(t3.getStatus().status, "timeout");
-  });
-});

package/.agents/tools/workflow/lib/file-tracker.ts

@@ -1,387 +0,0 @@
-/**
- * File-based Job Tracking
- *
- * Compatible with agent_monitor.py TUI. Writes status.json and agent.log
- * files in the same format as agent_job.py for process-level monitoring.
- *
- * This is separate from Convex tracking - used for debugging/monitoring
- * when you need to see verbose JSON streams and process-level telemetry.
- *
- * Enhanced to support:
- * - read_position tracking for recovery after runner restart
- * - Orphan detection and reconciliation
- * - Reading status from disk
- */
-
-import {
-  writeFileSync,
-  mkdirSync,
-  appendFileSync,
-  renameSync,
-  existsSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-} from "fs";
-import { join } from "path";
-import { tmpdir } from "os";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface FileJobStatus {
-  job_id: string;
-  harness: string;
-  agent_id: string | null;
-  pid: number | null;
-  logs: string | null;
-  status: "running" | "complete" | "error" | "timeout";
-  status_reason: string | null;
-  start_time: string | null;
-  last_event_time: string | null;
-  end_time: string | null;
-  operations: number;
-  /** Byte position in log file that has been processed (for recovery) */
-  read_position?: number;
-  completion: {
-    messages: string[];
-    final_message: string | null;
-    tokens: {
-      input: number | null;
-      output: number | null;
-      total: number | null;
-    };
-    duration_ms: number | null;
-  };
-}
-
-export interface JobPaths {
-  statusPath: string;
-  logPath: string;
-}
-
-// ============================================================================
-// Utilities
-// ============================================================================
-
-/**
- * Get the root directory for job files.
- * Respects AGENT_JOBS_ROOT env var, defaults to /tmp/agent_jobs/$USER
- */
-export function getJobsRoot(): string {
-  if (process.env.AGENT_JOBS_ROOT) {
-    return process.env.AGENT_JOBS_ROOT;
-  }
-  const user = process.env.USER || "unknown";
-  return join(tmpdir(), "agent_jobs", user);
-}
-
-/**
- * Get UTC timestamp in ISO format (matches agent_job.py format)
- */
-export function utcNowIso(): string {
-  return new Date().toISOString().replace(/\.\d{3}Z$/, ".000Z");
-}
-
-/**
- * Get the directory path for a specific job
- */
-export function getJobDir(jobId: string): string {
-  return join(getJobsRoot(), jobId);
-}
-
-/**
- * Check if a process is alive by PID
- */
-export function isPidAlive(pid: number | null): boolean {
-  if (!pid) return false;
-  try {
-    process.kill(pid, 0); // Signal 0 = check existence
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * List all job directories in the jobs root
- */
-export function listJobDirs(): string[] {
-  const root = getJobsRoot();
-  if (!existsSync(root)) return [];
-
-  return readdirSync(root).filter((name) => {
-    const dir = join(root, name);
-    try {
-      return statSync(dir).isDirectory();
-    } catch {
-      return false;
-    }
-  });
-}
-
-/**
- * Read status.json for a job, returns null if not found or invalid
- */
-export function readJobStatus(jobId: string): FileJobStatus | null {
-  const statusPath = join(getJobDir(jobId), "status.json");
-  if (!existsSync(statusPath)) return null;
-
-  try {
-    const content = readFileSync(statusPath, "utf-8");
-    return JSON.parse(content) as FileJobStatus;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Get paths for a job (without creating the directory)
- */
-export function getJobPaths(jobId: string): JobPaths {
-  const jobDir = getJobDir(jobId);
-  return {
-    statusPath: join(jobDir, "status.json"),
-    logPath: join(jobDir, "agent.log"),
-  };
-}
-
-/**
- * Find orphaned jobs: status="running" but process is dead
- */
-export function findOrphanedJobs(): Array<{
-  jobId: string;
-  status: FileJobStatus;
-  paths: JobPaths;
-}> {
-  const orphans: Array<{ jobId: string; status: FileJobStatus; paths: JobPaths }> = [];
-
-  for (const jobId of listJobDirs()) {
-    const status = readJobStatus(jobId);
-    if (!status) continue;
-
-    // Only care about "running" jobs
-    if (status.status !== "running") continue;
-
-    // Check if process is still alive
-    if (!isPidAlive(status.pid)) {
-      orphans.push({
-        jobId,
-        status,
-        paths: getJobPaths(jobId),
-      });
-    }
-  }
-
-  return orphans;
-}
-
-// ============================================================================
-// Job Status Management
-// ============================================================================
-
-/**
- * Create initial job status object
- */
-export function createFileJobStatus(
-  jobId: string,
-  harness: string,
-  pid: number
-): FileJobStatus {
-  return {
-    job_id: jobId,
-    harness,
-    agent_id: jobId,
-    pid,
-    logs: null, // Set after dir creation
-    status: "running",
-    status_reason: "initializing",
-    start_time: utcNowIso(),
-    last_event_time: utcNowIso(),
-    end_time: null,
-    operations: 0,
-    read_position: 0,
-    completion: {
-      messages: [],
-      final_message: null,
-      tokens: { input: null, output: null, total: null },
-      duration_ms: null,
-    },
-  };
-}
-
-/**
- * Create job directory and return paths to status.json and agent.log
- */
-export function ensureJobDir(jobId: string): JobPaths {
-  const jobDir = getJobDir(jobId);
-  mkdirSync(jobDir, { recursive: true });
-  return {
-    statusPath: join(jobDir, "status.json"),
-    logPath: join(jobDir, "agent.log"),
-  };
-}
-
-/**
- * Write status.json atomically (via temp file + rename)
- */
-export function writeJobStatus(statusPath: string, status: FileJobStatus): void {
-  const tmpPath = statusPath + ".tmp";
-  writeFileSync(tmpPath, JSON.stringify(status, null, 2));
-  renameSync(tmpPath, statusPath);
-}
-
-/**
- * Append a line to the agent.log file
- */
-export function appendToLog(logPath: string, line: string): void {
-  appendFileSync(logPath, line + "\n");
-}
-
-// ============================================================================
-// High-level Job Tracker
-// ============================================================================
-
-/**
- * JobTracker manages file-based status for a single job.
- * Use this to track process-level telemetry alongside Convex.
- */
-export class JobTracker {
-  private status: FileJobStatus;
-  private paths: JobPaths;
-
-  constructor(jobId: string, harness: string, pid: number) {
-    this.paths = ensureJobDir(jobId);
-    this.status = createFileJobStatus(jobId, harness, pid);
-    this.status.logs = this.paths.logPath;
-    this.writeStatus();
-  }
-
-  /**
-   * Create a JobTracker from an existing status on disk.
-   * Used for recovery/reconciliation of orphaned jobs.
-   */
-  static fromExisting(
-    jobId: string,
-    status: FileJobStatus,
-    paths: JobPaths
-  ): JobTracker {
-    const tracker = Object.create(JobTracker.prototype) as JobTracker;
-    tracker.status = { ...status };
-    tracker.paths = paths;
-    return tracker;
-  }
-
-  /** Update status reason (current activity) */
-  updateStatusReason(reason: string): void {
-    this.status.status_reason = reason;
-    this.status.last_event_time = utcNowIso();
-    this.writeStatus();
-  }
-
-  /** Increment operation count */
-  incrementOperations(): void {
-    this.status.operations++;
-    this.status.last_event_time = utcNowIso();
-    this.writeStatus();
-  }
-
-  /** Record an event (increments ops, updates timestamp, optionally updates reason) */
-  recordEvent(statusReason?: string): void {
-    this.status.operations++;
-    this.status.last_event_time = utcNowIso();
-    if (statusReason) {
-      this.status.status_reason = statusReason;
-    }
-    this.writeStatus();
-  }
-
-  /** Append raw JSON line to log file */
-  logLine(line: string): void {
-    appendToLog(this.paths.logPath, line);
-  }
-
-  /** Mark job as complete */
-  complete(finalMessage?: string): void {
-    this.status.status = "complete";
-    this.status.status_reason = "completed";
-    this.status.end_time = utcNowIso();
-    if (finalMessage) {
-      this.status.completion.final_message = finalMessage;
-      this.status.completion.messages.push(finalMessage);
-    }
-    this.writeStatus();
-  }
-
-  /** Mark job as failed */
-  fail(reason: string): void {
-    this.status.status = "error";
-    this.status.status_reason = reason;
-    this.status.end_time = utcNowIso();
-    this.writeStatus();
-  }
-
-  /** Mark job as timed out */
-  timeout(): void {
-    this.status.status = "timeout";
-    this.status.status_reason = "idle_timeout";
-    this.status.end_time = utcNowIso();
-    this.writeStatus();
-  }
-
-  /** Update token stats */
-  updateTokens(input: number | null, output: number | null): void {
-    this.status.completion.tokens.input = input;
-    this.status.completion.tokens.output = output;
-    if (input != null && output != null) {
-      this.status.completion.tokens.total = input + output;
-    }
-    this.writeStatus();
-  }
-
-  /** Get current status */
-  getStatus(): FileJobStatus {
-    return { ...this.status };
-  }
-
-  /** Get log path */
-  getLogPath(): string {
-    return this.paths.logPath;
-  }
-
-  /** Get status path */
-  getStatusPath(): string {
-    return this.paths.statusPath;
-  }
-
-  /** Get current read position in log file */
-  getReadPosition(): number {
-    return this.status.read_position ?? 0;
-  }
-
-  /** Update read position (bytes processed in log file) */
-  setReadPosition(position: number): void {
-    this.status.read_position = position;
-    this.writeStatus();
-  }
-
-  /** Get job ID */
-  getJobId(): string {
-    return this.status.job_id;
-  }
-
-  /** Get harness type */
-  getHarness(): string {
-    return this.status.harness;
-  }
-
-  /** Check if job is in a terminal state */
-  isTerminal(): boolean {
-    return this.status.status !== "running";
-  }
-
-  private writeStatus(): void {
-    writeJobStatus(this.paths.statusPath, this.status);
-  }
-}