ai-maestro 1.0.0

package/src/lock.mjs

@@ -0,0 +1,439 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from './config.mjs';
+
+const lockPath = path.join(CONFIG.maestroPath, '.lock.json');
+const taskLocksDir = path.join(CONFIG.maestroPath, 'locks', 'tasks');
+const STALE_MS = 30 * 60 * 1000;
+const READ_RETRY_ATTEMPTS = 30;
+const READ_RETRY_DELAY_MS = 5;
+const RENAME_RETRY_ATTEMPTS = 30;
+const RENAME_RETRY_DELAY_MS = 5;
+const ACQUIRE_RETRY_ATTEMPTS = 3;
+const ownedTaskLockTokens = new Set();
+let globalLockHandle = null;
+
+export function getLockPath() {
+  return lockPath;
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function ownerToken() {
+  return process.pid + ':' + crypto.randomUUID();
+}
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+function isTaskLockHeldByActiveOwner(lock) {
+  if (!lock || !Number.isInteger(lock.pid) || lock.pid <= 0) {
+    return false;
+  }
+  if (lock.pid === process.pid && lock.ownerToken && !ownedTaskLockTokens.has(lock.ownerToken)) {
+    return false;
+  }
+  return isPidAlive(lock.pid);
+}
+
+function safeTaskKey(taskId) {
+  const value = String(taskId);
+  if (value.length === 0) {
+    throw new Error('taskId is required');
+  }
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function getTaskLockPath(taskId) {
+  return path.join(taskLocksDir, 'task-' + safeTaskKey(taskId) + '.lock.json');
+}
+
+export async function inspectTaskLock(taskId) {
+  const taskIdText = String(taskId);
+  const taskLockPath = getTaskLockPath(taskIdText);
+  let raw;
+  try {
+    raw = await fs.readFile(taskLockPath, 'utf-8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {
+        taskId: taskIdText,
+        lockPath: taskLockPath,
+        exists: false,
+        lock: null,
+        lockCorrupted: false,
+        pidAlive: false,
+        heldByActive: false,
+        activeLock: null
+      };
+    }
+    throw error;
+  }
+
+  try {
+    const lock = JSON.parse(raw);
+    const heldByActive = isTaskLockHeldByActiveOwner(lock);
+    return {
+      taskId: taskIdText,
+      lockPath: taskLockPath,
+      exists: true,
+      lock,
+      lockCorrupted: false,
+      pidAlive: isPidAlive(lock && lock.pid),
+      heldByActive,
+      activeLock: heldByActive ? safeActiveLockInfo(lock, taskIdText) : null
+    };
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return {
+        taskId: taskIdText,
+        lockPath: taskLockPath,
+        exists: true,
+        lock: null,
+        lockCorrupted: true,
+        parseError: error.message,
+        rawBytes: Buffer.byteLength(raw, 'utf8'),
+        pidAlive: false,
+        heldByActive: false,
+        activeLock: null
+      };
+    }
+    throw error;
+  }
+}
+
+async function readJsonFile(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf-8'));
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function readLockEventually(filePath) {
+  for (let attempt = 0; attempt < READ_RETRY_ATTEMPTS; attempt += 1) {
+    const lock = await readJsonFile(filePath);
+    if (lock) {
+      return lock;
+    }
+    await delay(READ_RETRY_DELAY_MS);
+  }
+  return readJsonFile(filePath);
+}
+
+async function writeJsonExclusive(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const handle = await fs.open(filePath, 'wx');
+  let completed = false;
+  try {
+    await handle.writeFile(JSON.stringify(value, null, 2));
+    completed = true;
+  } finally {
+    await handle.close();
+    if (!completed) {
+      await fs.rm(filePath, { force: true });
+    }
+  }
+}
+
+async function renameWithTransientRetry(sourcePath, targetPath) {
+  for (let attempt = 0; attempt < RENAME_RETRY_ATTEMPTS; attempt += 1) {
+    try {
+      await fs.rename(sourcePath, targetPath);
+      return { ok: true };
+    } catch (error) {
+      if (error.code !== 'EPERM' && error.code !== 'EACCES') {
+        throw error;
+      }
+      await delay(RENAME_RETRY_DELAY_MS);
+    }
+  }
+  return { ok: false };
+}
+
+function lockAgeMs(lock) {
+  const startedAt = Date.parse(lock && lock.startedAt);
+  return Number.isFinite(startedAt) ? Date.now() - startedAt : null;
+}
+
+function safeActiveLockInfo(lock, taskId = null) {
+  const ageMs = lockAgeMs(lock);
+  const info = {
+    pid: Number.isInteger(lock && lock.pid) ? lock.pid : null,
+    command: typeof (lock && lock.command) === 'string' ? lock.command : null,
+    startedAt: typeof (lock && lock.startedAt) === 'string' ? lock.startedAt : null
+  };
+  if (taskId !== null) {
+    info.taskId = String(taskId);
+  }
+  if (ageMs !== null && ageMs > STALE_MS) {
+    info.warning = 'active_lock_exceeds_stale_threshold';
+  }
+  return info;
+}
+
+function safeRecoveryLockInfo(recovery, taskId = null) {
+  const info = {
+    pid: Number.isInteger(recovery && recovery.pid) ? recovery.pid : null,
+    command: 'lock recovery in progress',
+    startedAt: typeof (recovery && recovery.startedAt) === 'string' ? recovery.startedAt : null,
+    reason: 'recovery_in_progress'
+  };
+  if (taskId !== null) {
+    info.taskId = String(taskId);
+  }
+  return info;
+}
+
+function rememberGlobalLock(lock) {
+  globalLockHandle = {
+    pid: lock.pid,
+    command: lock.command,
+    startedAt: lock.startedAt
+  };
+}
+
+function isSameGlobalLock(left, right) {
+  return Boolean(left && right) &&
+    left.pid === right.pid &&
+    left.command === right.command &&
+    left.startedAt === right.startedAt;
+}
+
+function maestroLockedError(existing) {
+  const pid = existing && existing.pid ? existing.pid : 'unknown';
+  const command = existing && existing.command ? existing.command : 'unknown command';
+  const startedAt = existing && existing.startedAt ? existing.startedAt : 'unknown time';
+  const error = new Error(
+    'Another maestro process (PID ' + pid + ') is running "' + command +
+    '" since ' + startedAt + '. Wait for it to finish or delete .maestro/.lock.json if you are sure it is stale.'
+  );
+  error.code = 'MAESTRO_LOCKED';
+  return error;
+}
+
+async function replaceLockWithRecoveryClaim(lockFilePath, nextLock, confirmOwner) {
+  const token = ownerToken();
+  const recoveryPath = lockFilePath + '.recovery';
+  const recoveryClaim = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    ownerToken: token
+  };
+
+  try {
+    await writeJsonExclusive(recoveryPath, recoveryClaim);
+  } catch (error) {
+    if (error.code !== 'EEXIST') {
+      throw error;
+    }
+    return { acquiredClaim: false };
+  }
+
+  let tempPath = null;
+  try {
+    const current = await readLockEventually(lockFilePath);
+    if (current && isTaskLockHeldByActiveOwner(current)) {
+      return { acquiredClaim: true, replaced: false, activeLock: current };
+    }
+
+    tempPath = lockFilePath + '.tmp-' + process.pid + '-' + token.replace(/[^A-Za-z0-9_-]/g, '');
+    await writeJsonExclusive(tempPath, nextLock);
+    const renamed = await renameWithTransientRetry(tempPath, lockFilePath);
+    if (!renamed.ok) {
+      const activeLock = await readLockEventually(lockFilePath);
+      return { acquiredClaim: true, replaced: false, activeLock };
+    }
+    tempPath = null;
+
+    const finalLock = await readLockEventually(lockFilePath);
+    if (!confirmOwner(finalLock)) {
+      return { acquiredClaim: true, replaced: false, activeLock: finalLock };
+    }
+    return { acquiredClaim: true, replaced: true, finalLock };
+  } finally {
+    if (tempPath) {
+      await fs.rm(tempPath, { force: true });
+    }
+    const currentClaim = await readJsonFile(recoveryPath);
+    if (currentClaim && currentClaim.ownerToken === token && currentClaim.pid === process.pid) {
+      await fs.rm(recoveryPath, { force: true });
+    }
+  }
+}
+
+async function waitForRecovery(lockFilePath, taskId) {
+  const recoveryPath = lockFilePath + '.recovery';
+  for (let attempt = 0; attempt < READ_RETRY_ATTEMPTS; attempt += 1) {
+    const recovery = await readJsonFile(recoveryPath);
+    if (!recovery) {
+      return null;
+    }
+    const current = await readJsonFile(lockFilePath);
+    if (current && isTaskLockHeldByActiveOwner(current)) {
+      return { outcome: 'held_by_active', activeLock: safeActiveLockInfo(current, taskId) };
+    }
+    if (recovery.pid && !isPidAlive(recovery.pid)) {
+      await fs.rm(recoveryPath, { force: true });
+      return null;
+    }
+    await delay(READ_RETRY_DELAY_MS);
+  }
+  const current = await readLockEventually(lockFilePath);
+  if (current && isTaskLockHeldByActiveOwner(current)) {
+    return { outcome: 'held_by_active', activeLock: safeActiveLockInfo(current, taskId) };
+  }
+  const recovery = await readJsonFile(recoveryPath);
+  if (recovery && recovery.pid && isPidAlive(recovery.pid)) {
+    return { outcome: 'held_by_active', activeLock: safeRecoveryLockInfo(recovery, taskId) };
+  }
+  if (recovery && recovery.pid && !isPidAlive(recovery.pid)) {
+    await fs.rm(recoveryPath, { force: true });
+  }
+  return null;
+}
+
+async function acquireGlobalWithRecovery(command) {
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const lock = { pid: process.pid, command, startedAt: new Date().toISOString() };
+
+  try {
+    await writeJsonExclusive(lockPath, lock);
+    rememberGlobalLock(lock);
+    return lock;
+  } catch (error) {
+    if (error.code !== 'EEXIST') {
+      throw error;
+    }
+  }
+
+  const existing = await readLockEventually(lockPath);
+  if (existing && isPidAlive(existing.pid)) {
+    throw maestroLockedError(existing);
+  }
+
+  for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt += 1) {
+    const recovery = await replaceLockWithRecoveryClaim(
+      lockPath,
+      lock,
+      finalLock => finalLock && finalLock.pid === process.pid && finalLock.startedAt === lock.startedAt && finalLock.command === command
+    );
+    if (recovery.replaced) {
+      rememberGlobalLock(lock);
+      return lock;
+    }
+    if (recovery.activeLock && isPidAlive(recovery.activeLock.pid)) {
+      throw maestroLockedError(recovery.activeLock);
+    }
+    const waited = await waitForRecovery(lockPath, null);
+    if (waited && waited.activeLock) {
+      throw maestroLockedError(waited.activeLock);
+    }
+  }
+  throw maestroLockedError(await readLockEventually(lockPath));
+}
+
+export async function acquireLock(command) {
+  return acquireGlobalWithRecovery(command);
+}
+
+export async function releaseLock() {
+  if (!globalLockHandle) {
+    return;
+  }
+  const existing = await readJsonFile(lockPath);
+  if (isSameGlobalLock(existing, globalLockHandle)) {
+    await fs.rm(lockPath, { force: true });
+    globalLockHandle = null;
+  }
+}
+
+export async function acquireOrRecover(taskId, options = {}) {
+  const taskIdText = String(taskId);
+  const taskLockPath = getTaskLockPath(taskIdText);
+  const token = ownerToken();
+  const command = options.command ?? ('task ' + taskIdText);
+  const lock = {
+    taskId: taskIdText,
+    pid: process.pid,
+    command,
+    startedAt: new Date().toISOString(),
+    ownerToken: token
+  };
+
+  try {
+    await writeJsonExclusive(taskLockPath, lock);
+    ownedTaskLockTokens.add(token);
+    return {
+      outcome: 'acquired',
+      lockHandle: { taskId: taskIdText, lockPath: taskLockPath, pid: process.pid, ownerToken: token }
+    };
+  } catch (error) {
+    if (error.code !== 'EEXIST') {
+      throw error;
+    }
+  }
+
+  const existing = await readLockEventually(taskLockPath);
+  if (existing && isTaskLockHeldByActiveOwner(existing)) {
+    return { outcome: 'held_by_active', activeLock: safeActiveLockInfo(existing || {}, taskIdText) };
+  }
+
+  for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt += 1) {
+    const recovery = await replaceLockWithRecoveryClaim(
+      taskLockPath,
+      lock,
+      finalLock => finalLock && finalLock.ownerToken === token && finalLock.pid === process.pid
+    );
+    if (recovery.replaced) {
+      ownedTaskLockTokens.add(token);
+      return {
+        outcome: 'recovered_and_acquired',
+        lockHandle: { taskId: taskIdText, lockPath: taskLockPath, pid: process.pid, ownerToken: token }
+      };
+    }
+    if (recovery.activeLock && isTaskLockHeldByActiveOwner(recovery.activeLock)) {
+      return { outcome: 'held_by_active', activeLock: safeActiveLockInfo(recovery.activeLock, taskIdText) };
+    }
+    const waited = await waitForRecovery(taskLockPath, taskIdText);
+    if (waited) {
+      return waited;
+    }
+  }
+  const current = await readLockEventually(taskLockPath);
+  return { outcome: 'held_by_active', activeLock: safeActiveLockInfo(current || {}, taskIdText) };
+}
+
+export async function releaseTaskLock(lockHandle) {
+  if (!lockHandle || lockHandle.ownerToken == null || lockHandle.taskId == null) {
+    return false;
+  }
+  const taskLockPath = getTaskLockPath(lockHandle.taskId);
+  const existing = await readJsonFile(taskLockPath);
+  if (
+    existing &&
+    existing.pid === lockHandle.pid &&
+    existing.pid === process.pid &&
+    existing.ownerToken === lockHandle.ownerToken
+  ) {
+    await fs.rm(taskLockPath, { force: true });
+    ownedTaskLockTokens.delete(lockHandle.ownerToken);
+    return true;
+  }
+  return false;
+}

package/src/memory-log.mjs

@@ -0,0 +1,18 @@
+import path from 'path';
+import { CONFIG } from './config.mjs';
+import { pathExists } from './files.mjs';
+import { execFile } from './shell.mjs';
+
+export async function logMemory(message) {
+  const cliPath = path.join(CONFIG.memoryPath, 'tools', 'cli.mjs');
+  if (await pathExists(cliPath)) {
+    await execFile('node', [cliPath, 'log', message, '--agent', 'maestro-cli']);
+  }
+}
+
+export async function memoryDecision(message) {
+  const cliPath = path.join(CONFIG.memoryPath, 'tools', 'cli.mjs');
+  if (await pathExists(cliPath)) {
+    await execFile('node', [cliPath, 'decision', message, '--agent', 'maestro-cli']);
+  }
+}

package/src/memory.mjs

@@ -0,0 +1 @@
+console.log('Memory module');