maestro-agent 0.0.1 → 0.0.2

package/src/ops/index.ts

@@ -0,0 +1,226 @@
+import { Database } from "bun:sqlite";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { generateId, now } from "../core/db";
+
+export function recoverInterruptedSessions(db: Database) {
+  const ts = now();
+  const running = db.query("SELECT * FROM session WHERE status = 'running'").all() as any[];
+  for (const session of running) {
+    db.run("UPDATE session SET status = 'interrupted', ended_at = ? WHERE id = ?", [ts, session.id]);
+    db.run("UPDATE agent SET status = 'idle', last_active_at = ? WHERE id = ?", [ts, session.agent_id]);
+    audit(db, "system", "ops.session_recovered", session.id, { previous_status: "running" });
+  }
+
+  // Recover stale orphaned tasks: tasks stuck in claimed/in_progress with no running session
+  const taskTimeoutMs = 5 * 60 * 1000;
+  const staleTaskCutoff = ts - taskTimeoutMs;
+  const orphanedTasks = db.query(`
+    SELECT t.id, t.status, t.assignee_agent_id FROM task t
+    WHERE t.status IN ('claimed', 'in_progress')
+      AND t.updated_at <= ?
+      AND NOT EXISTS (
+        SELECT 1 FROM session s
+        WHERE s.task_id = t.id AND s.status = 'running'
+      )
+  `).all(staleTaskCutoff) as any[];
+  for (const task of orphanedTasks) {
+    db.run(
+      "UPDATE task SET status = 'open', assignee_agent_id = NULL, claim_token = NULL, updated_at = ? WHERE id = ?",
+      [ts, task.id],
+    );
+    audit(db, "system", "ops.task_recovered", task.id, { previous_status: task.status, task_timeout_ms: taskTimeoutMs });
+  }
+
+  return { recovered: running.length, tasks_reset: orphanedTasks.length };
+}
+
+export function runtimeWaterline(db: Database, runtimeId: string, capacity: number) {
+  const running = (db.query(`
+    SELECT COUNT(*) AS count
+    FROM session
+    JOIN agent ON agent.id = session.agent_id
+    WHERE agent.runtime_id = ? AND session.status = 'running'
+  `).get(runtimeId) as any).count;
+  return {
+    running,
+    capacity,
+    utilization: capacity > 0 ? running / capacity : 0,
+  };
+}
+
+export async function checkRuntimeHealth(db: Database, runtime: any) {
+  let status = "online";
+  let detail = "ok";
+  if (runtime.transport === "local-pty" && runtime.cmd) {
+    const result = await Bun.spawn(["sh", "-c", `command -v ${shellQuote(runtime.cmd)}`]).exited;
+    status = result === 0 ? "online" : "offline";
+    detail = result === 0 ? "command found" : "command not found";
+  } else if ((runtime.transport === "ssh" || runtime.transport === "http-api") && !runtime.target) {
+    status = "offline";
+    detail = "missing target";
+  }
+  db.run("UPDATE agent_runtime SET status = ? WHERE id = ?", [status, runtime.id]);
+  return { id: runtime.id, status, detail, waterline: runtimeWaterline(db, runtime.id, Number(runtime.capacity ?? -1)) };
+}
+
+export function createBackup(hubDir: string) {
+  const backupDir = join(hubDir, "backups");
+  mkdirSync(backupDir, { recursive: true });
+  const source = join(hubDir, "maestro.db");
+  const path = join(backupDir, `maestro-${now()}.db`);
+  const db = new Database(source);
+  db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  db.close();
+  copyFileSync(source, path);
+  return { path };
+}
+
+export function restoreBackup(hubDir: string, path: string) {
+  if (!existsSync(path)) throw new Error(`Backup not found: ${path}`);
+  copyFileSync(path, join(hubDir, "maestro.db"));
+  return { restored: true, path };
+}
+
+export function recordAgentExit(db: Database, input: { agentId: string; sessionId: string; code: number }) {
+  const agent = db.query("SELECT * FROM agent WHERE id = ?").get(input.agentId) as any;
+  if (!agent) return { restart: false, attempts: 0 };
+  const metrics = parseMetrics(agent.metrics_json);
+  const attempts = input.code === 0 ? 0 : Number(metrics.restart_attempts || 0) + 1;
+  metrics.restart_attempts = attempts;
+  db.run("UPDATE agent SET metrics_json = ? WHERE id = ?", [JSON.stringify(metrics), input.agentId]);
+
+  if (input.code !== 0 && attempts >= 3) {
+    createInbox(db, "escalation", "hub", "user", "Agent restart failed", `Agent ${input.agentId} crashed ${attempts} time(s).`, {
+      agent_id: input.agentId,
+      session_id: input.sessionId,
+      code: input.code,
+    });
+    return { restart: false, attempts };
+  }
+
+  return { restart: input.code !== 0, attempts };
+}
+
+export function opsStats(db: Database) {
+  const sessions = db.query("SELECT * FROM session").all() as any[];
+  const runtimes = (db.query("SELECT * FROM agent_runtime ORDER BY created_at DESC").all() as any[])
+    .map((runtime) => ({ ...runtime, waterline: runtimeWaterline(db, runtime.id, Number(runtime.capacity ?? -1)) }));
+
+  // Better cost estimation based on session duration
+  let totalDurationMs = 0;
+  for (const session of sessions) {
+    if (session.started_at && session.ended_at) {
+      totalDurationMs += session.ended_at - session.started_at;
+    }
+  }
+  const estimatedTokens = Math.max(sessions.length * 1000, Math.ceil(totalDurationMs / 60000) * 500);
+  const estimatedUsd = Math.round(estimatedTokens * 0.000015 * 100) / 100; // ~$15/1M tokens avg
+
+  return {
+    cost: {
+      sessions: sessions.length,
+      estimated_tokens: estimatedTokens,
+      estimated_usd: estimatedUsd,
+      total_duration_min: Math.round(totalDurationMs / 60000),
+    },
+    runtimes,
+  };
+}
+
+export async function smokeRuntimes(db: Database, runtimes: any[]) {
+  const ts = now();
+  let sessions = 0;
+  for (const runtime of runtimes) {
+    const runtimeId = generateId("runtime");
+    const agentId = generateId("agent");
+    const sessionId = generateId("sess");
+    db.run(
+      "INSERT INTO agent_runtime (id, type, transport, cmd, target, capacity, status, capabilities_json, created_at) VALUES (?, ?, ?, ?, ?, 1, 'online', '[]', ?)",
+      [runtimeId, runtime.type, runtime.transport, runtime.cmd || null, runtime.target || null, ts],
+    );
+    db.run(
+      "INSERT INTO agent (id, runtime_id, name, status, metrics_json, created_at, last_active_at) VALUES (?, ?, ?, 'idle', '{}', ?, ?)",
+      [agentId, runtimeId, `${runtime.type}-smoke`, ts, ts],
+    );
+    db.run(
+      "INSERT INTO session (id, agent_id, pty_pid, transcript_path, status, started_at, ended_at) VALUES (?, ?, 0, NULL, 'ended', ?, ?)",
+      [sessionId, agentId, ts, ts],
+    );
+    sessions++;
+  }
+  return { status: "passed", runtimes: runtimes.length, sessions };
+}
+
+export async function soakRuntimes(hubDir: string, db: Database, input: { runtimes: any[]; duration_ms?: number; fast_forward?: boolean }) {
+  const startedAt = now();
+  const smoke = await smokeRuntimes(db, input.runtimes || []);
+  const durationMs = Number(input.duration_ms ?? 24 * 60 * 60 * 1000);
+  if (durationMs > 0) await Bun.sleep(input.fast_forward ? Math.min(durationMs, 100) : durationMs);
+  const endedAt = now();
+  const observedDurationMs = endedAt - startedAt;
+  const complete = !input.fast_forward && observedDurationMs >= durationMs;
+  const evidenceDir = join(hubDir, "evidence");
+  mkdirSync(evidenceDir, { recursive: true });
+  const evidence = {
+    status: complete ? smoke.status : "simulated",
+    requested_duration_ms: durationMs,
+    observed_duration_ms: observedDurationMs,
+    fast_forward: Boolean(input.fast_forward),
+    complete,
+    started_at: startedAt,
+    ended_at: endedAt,
+    runtimes: input.runtimes || [],
+    sessions: smoke.sessions,
+  };
+  const evidencePath = join(evidenceDir, `soak-${startedAt}.json`);
+  writeFileSync(evidencePath, JSON.stringify(evidence, null, 2));
+  return {
+    ...smoke,
+    status: evidence.status,
+    duration_ms: durationMs,
+    observed_duration_ms: observedDurationMs,
+    complete,
+    evidence_path: evidencePath,
+  };
+}
+
+export function latestSoakEvidence(hubDir: string) {
+  const evidenceDir = join(hubDir, "evidence");
+  if (!existsSync(evidenceDir)) return null;
+  const files = readdirSync(evidenceDir)
+    .filter((file) => file.startsWith("soak-") && file.endsWith(".json"))
+    .sort();
+  const latest = files.at(-1);
+  if (!latest) return null;
+  const path = join(evidenceDir, latest);
+  return { path, ...JSON.parse(readFileSync(path, "utf-8")) };
+}
+
+function audit(db: Database, actor: string, action: string, target: string, payload: unknown) {
+  db.run(
+    "INSERT INTO audit_log (id, actor, action, target, payload_json, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+    [generateId("audit"), actor, action, target, JSON.stringify(payload), now()],
+  );
+}
+
+function createInbox(db: Database, kind: string, fromActor: string, toActor: string, subject: string, body: string, ref: unknown) {
+  db.run(
+    `INSERT INTO inbox_message (id, kind, from_actor, to_actor, subject, body, ref_json, status, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, 'unread', ?)`,
+    [generateId("msg"), kind, fromActor, toActor, subject, body, JSON.stringify(ref), now()],
+  );
+}
+
+function parseMetrics(raw: string | null | undefined) {
+  try {
+    return JSON.parse(raw || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function shellQuote(value: string) {
+  if (/^[A-Za-z0-9_./:=@+-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/src/ops/project-serial.ts

@@ -0,0 +1,52 @@
+import type { Database } from "bun:sqlite";
+
+export interface ProjectTaskRow {
+	id: string;
+	project_id?: string | null;
+	status?: string | null;
+	assignee_agent_id?: string | null;
+	updated_at?: number | null;
+}
+
+export function projectExecutionStatuses(
+	claimedStatus?: string | null,
+): string[] {
+	const statuses = new Set(["claimed", "in_progress"]);
+	if (claimedStatus) statuses.add(claimedStatus);
+	return [...statuses];
+}
+
+export function findProjectExecutionBlocker(
+	db: Database,
+	input: {
+		projectId?: string | null;
+		excludeTaskId?: string | null;
+		claimedStatus?: string | null;
+	},
+): ProjectTaskRow | null {
+	if (!input.projectId) return null;
+	const statuses = projectExecutionStatuses(input.claimedStatus);
+	const statusPlaceholders = statuses.map(() => "?").join(", ");
+	const excludeClause = input.excludeTaskId ? "AND id != ?" : "";
+	const params = input.excludeTaskId
+		? [input.projectId, input.excludeTaskId, ...statuses]
+		: [input.projectId, ...statuses];
+
+	return db
+		.query(
+			`SELECT * FROM task
+     WHERE project_id = ?
+       ${excludeClause}
+       AND status IN (${statusPlaceholders})
+     ORDER BY updated_at ASC
+     LIMIT 1`,
+		)
+		.get(...params) as ProjectTaskRow | null;
+}
+
+export function isTaskAssignedToAgent(
+	task: ProjectTaskRow,
+	agentId?: string | null,
+): boolean {
+	return !task.assignee_agent_id || task.assignee_agent_id === agentId;
+}

package/src/ops/role-dispatch.ts

@@ -0,0 +1,111 @@
+import type { Database } from "bun:sqlite";
+import { now } from "../core/db";
+import type { HubContext } from "../core/server";
+
+/**
+ * Role-centric agent resolution.
+ *
+ * Principle: Tasks are assigned to Roles. A Role is always "online" (logical entity).
+ * An Agent is merely the execution tool. When a Role receives work, it picks the best
+ * available Agent — or wakes one up if all are offline.
+ */
+
+export interface ResolvedAgent {
+  id: string;
+  woken: boolean; // true if the agent was offline and was reactivated
+}
+
+/**
+ * Find or wake an Agent under the given Role.
+ *
+ * Priority:
+ * 1. idle agent (no active session) — best candidate
+ * 2. idle agent (has running session but can accept more) — if capacity allows
+ * 3. offline agent — wake it up (set status to idle)
+ *
+ * Returns null only if the role has zero agents at all.
+ */
+export function resolveAgentForRole(
+  db: Database,
+  roleId: string,
+): ResolvedAgent | null {
+  // 1. Find idle agent without a running session
+  const idleAgent = db.query(
+    `SELECT a.id FROM agent a
+     LEFT JOIN session s ON s.agent_id = a.id AND s.status = 'running'
+     WHERE a.role_id = ? AND a.status = 'idle' AND s.id IS NULL
+     ORDER BY a.last_active_at DESC
+     LIMIT 1`
+  ).get(roleId) as { id: string } | null;
+
+  if (idleAgent) return { id: idleAgent.id, woken: false };
+
+  // 2. Find idle agent that still has capacity (running sessions < capacity)
+  const idleWithCapacity = db.query(
+    `SELECT a.id FROM agent a
+     JOIN agent_runtime ar ON ar.id = a.runtime_id
+     LEFT JOIN (
+       SELECT agent_id, COUNT(*) as cnt FROM session WHERE status = 'running' GROUP BY agent_id
+     ) sc ON sc.agent_id = a.id
+     WHERE a.role_id = ? AND a.status = 'idle'
+       AND (ar.capacity < 0 OR COALESCE(sc.cnt, 0) < ar.capacity)
+     ORDER BY COALESCE(sc.cnt, 0) ASC, a.last_active_at DESC
+     LIMIT 1`
+  ).get(roleId) as { id: string } | null;
+
+  if (idleWithCapacity) return { id: idleWithCapacity.id, woken: false };
+
+  // 3. Wake an offline agent
+  const offlineAgent = db.query(
+    `SELECT id FROM agent WHERE role_id = ? AND status = 'offline' ORDER BY last_active_at DESC LIMIT 1`
+  ).get(roleId) as { id: string } | null;
+
+  if (offlineAgent) {
+    const ts = now();
+    db.run("UPDATE agent SET status = 'idle', last_active_at = ? WHERE id = ?", [ts, offlineAgent.id]);
+    return { id: offlineAgent.id, woken: true };
+  }
+
+  return null;
+}
+
+/**
+ * Given a task (with optional required_capabilities), find the best Role in the workspace
+ * that can handle it, then resolve an Agent under that Role.
+ */
+export function findRoleAndAgentForTask(
+  ctx: HubContext,
+  task: { project_id: string; required_capabilities_json?: string },
+): { role_id: string; agent: ResolvedAgent } | null {
+  const project = ctx.db.query("SELECT workspace_id FROM project WHERE id = ?").get(task.project_id) as any;
+  if (!project) return null;
+
+  const requiredCaps: string[] = safeJsonParse(task.required_capabilities_json);
+
+  // Find roles in this workspace that have agents
+  const roles = ctx.db.query(
+    `SELECT DISTINCT r.id, r.capabilities_json
+     FROM role r
+     JOIN agent a ON a.role_id = r.id
+     WHERE r.workspace_id = ?`
+  ).all(project.workspace_id) as Array<{ id: string; capabilities_json: string }>;
+
+  for (const role of roles) {
+    // Check capabilities match
+    if (requiredCaps.length > 0) {
+      const roleCaps: string[] = safeJsonParse(role.capabilities_json);
+      const hasAll = requiredCaps.every((cap) => roleCaps.includes(cap));
+      if (!hasAll) continue;
+    }
+
+    const agent = resolveAgentForRole(ctx.db, role.id);
+    if (agent) return { role_id: role.id, agent };
+  }
+
+  return null;
+}
+
+function safeJsonParse(val: string | null | undefined): string[] {
+  if (!val) return [];
+  try { return JSON.parse(val); } catch { return []; }
+}