@lumenflow/cli 5.5.0 → 5.7.12

package/packs/software-delivery/tool-impl/lane-lock.ts

@@ -1,246 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-/* eslint-disable security/detect-non-literal-fs-filename */
-import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { UTF8_ENCODING } from '../constants.js';
-
-export interface LaneLockMetadata {
-  lane: string;
-  wuId: string;
-  owner: string;
-  timestamp: string;
-}
-
-export interface AcquireLaneLockInput {
-  lane: string;
-  wuId: string;
-  owner: string;
-  locksDir: string;
-  staleAfterMs?: number;
-}
-
-export interface AcquireLaneLockResult {
-  acquired: boolean;
-  is_stale: boolean;
-  lock_path: string;
-}
-
-export interface ReleaseLaneLockInput {
-  lane: string;
-  owner: string;
-  locksDir: string;
-}
-
-export interface ReleaseLaneLockResult {
-  released: boolean;
-  lock_path: string;
-}
-
-function laneToLockFileName(lane: string): string {
-  const chars: string[] = [];
-  for (const char of lane.toLowerCase()) {
-    if ((char >= 'a' && char <= 'z') || (char >= '0' && char <= '9')) {
-      chars.push(char);
-      continue;
-    }
-    if (chars[chars.length - 1] !== '-') {
-      chars.push('-');
-    }
-  }
-  let normalized = chars.join('');
-  while (normalized.startsWith('-')) {
-    normalized = normalized.slice(1);
-  }
-  while (normalized.endsWith('-')) {
-    normalized = normalized.slice(0, -1);
-  }
-  return `${normalized || 'lane'}.lock`;
-}
-
-function lockPathFor(input: { lane: string; locksDir: string }): string {
-  return path.join(input.locksDir, laneToLockFileName(input.lane));
-}
-
-function isStale(metadata: LaneLockMetadata, staleAfterMs: number): boolean {
-  const lockTime = new Date(metadata.timestamp).getTime();
-  return Number.isFinite(lockTime) && Date.now() - lockTime > staleAfterMs;
-}
-
-function staleTakeoverMarkerPath(lockPath: string): string {
-  return `${lockPath}.takeover`;
-}
-
-async function acquireTakeoverMarker(
-  markerPath: string,
-  metadata: LaneLockMetadata,
-): Promise<boolean> {
-  try {
-    await writeFile(markerPath, JSON.stringify(metadata), { encoding: UTF8_ENCODING, flag: 'wx' });
-    return true;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
-      return false;
-    }
-    throw error;
-  }
-}
-
-type LaneLockWarn = (message: string) => void;
-
-function writeWarning(message: string): void {
-  process.stderr.write(`${message}\n`);
-}
-
-export async function cleanupTakeoverMarker(
-  markerPath: string,
-  options: {
-    unlinkFile?: (targetPath: string) => Promise<void>;
-    warn?: LaneLockWarn;
-  } = {},
-): Promise<void> {
-  const unlinkFile = options.unlinkFile ?? unlink;
-  const warn: LaneLockWarn = options.warn ?? writeWarning;
-
-  try {
-    await unlinkFile(markerPath);
-  } catch (error) {
-    const nodeError = error as NodeJS.ErrnoException;
-    if (nodeError.code === 'ENOENT') {
-      return;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    warn(`[lane-lock] failed to cleanup takeover marker at ${markerPath}: ${message}`);
-  }
-}
-
-export async function readLaneLockMetadata(lockPath: string): Promise<LaneLockMetadata | null> {
-  try {
-    const raw = await readFile(lockPath, UTF8_ENCODING);
-    const parsed = JSON.parse(raw) as LaneLockMetadata;
-    if (
-      typeof parsed.lane !== 'string' ||
-      typeof parsed.wuId !== 'string' ||
-      typeof parsed.owner !== 'string' ||
-      typeof parsed.timestamp !== 'string'
-    ) {
-      return null;
-    }
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-export async function acquireLaneLockTool(
-  input: AcquireLaneLockInput,
-): Promise<AcquireLaneLockResult> {
-  await mkdir(input.locksDir, { recursive: true });
-  const lockPath = lockPathFor(input);
-  const staleAfterMs = input.staleAfterMs ?? 2 * 60 * 60 * 1000;
-  const nextMetadata: LaneLockMetadata = {
-    lane: input.lane,
-    wuId: input.wuId,
-    owner: input.owner,
-    timestamp: new Date().toISOString(),
-  };
-
-  try {
-    await writeFile(lockPath, JSON.stringify(nextMetadata), {
-      encoding: UTF8_ENCODING,
-      flag: 'wx',
-    });
-    return {
-      acquired: true,
-      is_stale: false,
-      lock_path: lockPath,
-    };
-  } catch (error) {
-    const isExists = (error as NodeJS.ErrnoException).code === 'EEXIST';
-    if (!isExists) {
-      throw error;
-    }
-
-    const existing = await readLaneLockMetadata(lockPath);
-    if (existing && isStale(existing, staleAfterMs)) {
-      const takeoverMarkerPath = staleTakeoverMarkerPath(lockPath);
-      const wonTakeoverRace = await acquireTakeoverMarker(takeoverMarkerPath, nextMetadata);
-      if (!wonTakeoverRace) {
-        return {
-          acquired: false,
-          is_stale: false,
-          lock_path: lockPath,
-        };
-      }
-
-      try {
-        const current = await readLaneLockMetadata(lockPath);
-        if (!current || !isStale(current, staleAfterMs)) {
-          return {
-            acquired: false,
-            is_stale: false,
-            lock_path: lockPath,
-          };
-        }
-
-        await unlink(lockPath).catch((unlinkError) => {
-          const nodeError = unlinkError as NodeJS.ErrnoException;
-          if (nodeError.code === 'ENOENT') {
-            return;
-          }
-          throw unlinkError;
-        });
-
-        try {
-          await writeFile(lockPath, JSON.stringify(nextMetadata), {
-            encoding: UTF8_ENCODING,
-            flag: 'wx',
-          });
-        } catch (writeError) {
-          if ((writeError as NodeJS.ErrnoException).code === 'EEXIST') {
-            return {
-              acquired: false,
-              is_stale: false,
-              lock_path: lockPath,
-            };
-          }
-          throw writeError;
-        }
-
-        return {
-          acquired: true,
-          is_stale: true,
-          lock_path: lockPath,
-        };
-      } finally {
-        await cleanupTakeoverMarker(takeoverMarkerPath);
-      }
-    }
-
-    return {
-      acquired: false,
-      is_stale: false,
-      lock_path: lockPath,
-    };
-  }
-}
-
-export async function releaseLaneLockTool(
-  input: ReleaseLaneLockInput,
-): Promise<ReleaseLaneLockResult> {
-  const lockPath = lockPathFor(input);
-  const metadata = await readLaneLockMetadata(lockPath);
-  if (!metadata || metadata.owner !== input.owner) {
-    return {
-      released: false,
-      lock_path: lockPath,
-    };
-  }
-
-  await unlink(lockPath);
-  return {
-    released: true,
-    lock_path: lockPath,
-  };
-}

package/packs/software-delivery/tool-impl/memory-tools.ts

@@ -1,470 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import type { ToolOutput } from '@lumenflow/kernel';
-import { RUNTIME_CLI_COMMANDS, runtimeCliAdapter } from './runtime-cli-adapter.js';
-
-const MEMORY_TOOLS = {
-  MEM_INIT: 'mem:init',
-  MEM_START: 'mem:start',
-  MEM_READY: 'mem:ready',
-  MEM_CHECKPOINT: 'mem:checkpoint',
-  MEM_CLEANUP: 'mem:cleanup',
-  MEM_CONTEXT: 'mem:context',
-  MEM_CREATE: 'mem:create',
-  MEM_DELETE: 'mem:delete',
-  MEM_EXPORT: 'mem:export',
-  MEM_INBOX: 'mem:inbox',
-  MEM_SIGNAL: 'mem:signal',
-  MEM_CONVERGED: 'mem:converged',
-  MEM_SUMMARIZE: 'mem:summarize',
-  MEM_TRIAGE: 'mem:triage',
-  MEM_RECOVER: 'mem:recover',
-} as const;
-
-type MemoryToolName = (typeof MEMORY_TOOLS)[keyof typeof MEMORY_TOOLS];
-
-const MEMORY_TOOL_ERROR_CODES: Record<MemoryToolName, string> = {
-  'mem:init': 'MEM_INIT_ERROR',
-  'mem:start': 'MEM_START_ERROR',
-  'mem:ready': 'MEM_READY_ERROR',
-  'mem:checkpoint': 'MEM_CHECKPOINT_ERROR',
-  'mem:cleanup': 'MEM_CLEANUP_ERROR',
-  'mem:context': 'MEM_CONTEXT_ERROR',
-  'mem:create': 'MEM_CREATE_ERROR',
-  'mem:delete': 'MEM_DELETE_ERROR',
-  'mem:export': 'MEM_EXPORT_ERROR',
-  'mem:inbox': 'MEM_INBOX_ERROR',
-  'mem:signal': 'MEM_SIGNAL_ERROR',
-  'mem:converged': 'MEM_CONVERGED_ERROR',
-  'mem:summarize': 'MEM_SUMMARIZE_ERROR',
-  'mem:triage': 'MEM_TRIAGE_ERROR',
-  'mem:recover': 'MEM_RECOVER_ERROR',
-};
-
-const MEMORY_TOOL_COMMANDS: Record<
-  MemoryToolName,
-  (typeof RUNTIME_CLI_COMMANDS)[keyof typeof RUNTIME_CLI_COMMANDS]
-> = {
-  'mem:init': RUNTIME_CLI_COMMANDS.MEM_INIT,
-  'mem:start': RUNTIME_CLI_COMMANDS.MEM_START,
-  'mem:ready': RUNTIME_CLI_COMMANDS.MEM_READY,
-  'mem:checkpoint': RUNTIME_CLI_COMMANDS.MEM_CHECKPOINT,
-  'mem:cleanup': RUNTIME_CLI_COMMANDS.MEM_CLEANUP,
-  'mem:context': RUNTIME_CLI_COMMANDS.MEM_CONTEXT,
-  'mem:create': RUNTIME_CLI_COMMANDS.MEM_CREATE,
-  'mem:delete': RUNTIME_CLI_COMMANDS.MEM_DELETE,
-  'mem:export': RUNTIME_CLI_COMMANDS.MEM_EXPORT,
-  'mem:inbox': RUNTIME_CLI_COMMANDS.MEM_INBOX,
-  'mem:signal': RUNTIME_CLI_COMMANDS.MEM_SIGNAL,
-  'mem:converged': RUNTIME_CLI_COMMANDS.MEM_CONVERGED,
-  'mem:summarize': RUNTIME_CLI_COMMANDS.MEM_SUMMARIZE,
-  'mem:triage': RUNTIME_CLI_COMMANDS.MEM_TRIAGE,
-  'mem:recover': RUNTIME_CLI_COMMANDS.MEM_RECOVER,
-};
-
-const MISSING_PARAMETER_MESSAGES = {
-  ID_REQUIRED: 'id is required',
-  WU_REQUIRED: 'wu is required',
-  MESSAGE_REQUIRED: 'message is required',
-} as const;
-
-interface CommandExecutionResult {
-  ok: boolean;
-  status: number;
-  stdout: string;
-  stderr: string;
-  executionError?: string;
-}
-
-function toRecord(input: unknown): Record<string, unknown> {
-  if (input && typeof input === 'object') {
-    return input as Record<string, unknown>;
-  }
-  return {};
-}
-
-function toStringValue(value: unknown): string | null {
-  if (typeof value !== 'string') {
-    return null;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-function toStringArray(value: unknown): string[] {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-  return value
-    .map((entry) => toStringValue(entry))
-    .filter((entry): entry is string => entry !== null);
-}
-
-function toIntegerString(value: unknown): string | null {
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    return String(Math.trunc(value));
-  }
-  if (typeof value === 'string') {
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : null;
-  }
-  return null;
-}
-
-async function runMemoryCommand(
-  toolName: MemoryToolName,
-  args: string[],
-): Promise<CommandExecutionResult> {
-  return runtimeCliAdapter.run(MEMORY_TOOL_COMMANDS[toolName], args);
-}
-
-function createMissingParameterOutput(message: string): ToolOutput {
-  return {
-    success: false,
-    error: {
-      code: 'MISSING_PARAMETER',
-      message,
-    },
-  };
-}
-
-function createFailureOutput(
-  toolName: MemoryToolName,
-  execution: CommandExecutionResult,
-): ToolOutput {
-  const stderrMessage = execution.stderr.trim();
-  const stdoutMessage = execution.stdout.trim();
-  const message =
-    execution.executionError ??
-    (stderrMessage.length > 0
-      ? stderrMessage
-      : stdoutMessage.length > 0
-        ? stdoutMessage
-        : `${toolName} failed`);
-  return {
-    success: false,
-    error: {
-      code: MEMORY_TOOL_ERROR_CODES[toolName],
-      message,
-      details: {
-        exit_code: execution.status,
-        stdout: execution.stdout,
-        stderr: execution.stderr,
-      },
-    },
-  };
-}
-
-function parseJsonOutput(stdout: string): unknown | null {
-  const trimmed = stdout.trim();
-  if (trimmed.length === 0) {
-    return null;
-  }
-  try {
-    return JSON.parse(trimmed) as unknown;
-  } catch {
-    return null;
-  }
-}
-
-function createSuccessOutput(
-  toolName: MemoryToolName,
-  execution: CommandExecutionResult,
-): ToolOutput {
-  const parsedJson = parseJsonOutput(execution.stdout);
-  if (parsedJson !== null) {
-    return {
-      success: true,
-      data: parsedJson,
-    };
-  }
-
-  const message = execution.stdout.trim().length > 0 ? execution.stdout.trim() : `${toolName} ran`;
-  return {
-    success: true,
-    data: {
-      message,
-    },
-  };
-}
-
-async function executeMemoryTool(toolName: MemoryToolName, args: string[]): Promise<ToolOutput> {
-  const execution = await runMemoryCommand(toolName, args);
-  if (!execution.ok) {
-    return createFailureOutput(toolName, execution);
-  }
-  return createSuccessOutput(toolName, execution);
-}
-
-export async function memInitTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_INIT, ['--wu', wu]);
-}
-
-export async function memStartTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const args = ['--wu', wu];
-  const lane = toStringValue(parsed.lane);
-  if (lane) {
-    args.push('--lane', lane);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_START, args);
-}
-
-export async function memReadyTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_READY, ['--wu', wu]);
-}
-
-export async function memCheckpointTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const args = ['--wu', wu];
-  const message = toStringValue(parsed.message);
-  if (message) {
-    args.push('--message', message);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_CHECKPOINT, args);
-}
-
-export async function memCleanupTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const args: string[] = [];
-  if (parsed.dry_run === true) {
-    args.push('--dry-run');
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_CLEANUP, args);
-}
-
-export async function memContextTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const args = ['--wu', wu];
-  const lane = toStringValue(parsed.lane);
-  if (lane) {
-    args.push('--lane', lane);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_CONTEXT, args);
-}
-
-export async function memCreateTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const message = toStringValue(parsed.message);
-  if (!message) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.MESSAGE_REQUIRED);
-  }
-
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const args = [message, '--wu', wu];
-  const type = toStringValue(parsed.type);
-  if (type) {
-    args.push('--type', type);
-  }
-  const tags = toStringArray(parsed.tags);
-  if (tags.length > 0) {
-    args.push('--tags', tags.join(','));
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_CREATE, args);
-}
-
-export async function memDeleteTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const id = toStringValue(parsed.id);
-  if (!id) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.ID_REQUIRED);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_DELETE, ['--id', id]);
-}
-
-export async function memExportTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const args = ['--wu', wu];
-  const format = toStringValue(parsed.format);
-  if (format) {
-    args.push('--format', format);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_EXPORT, args);
-}
-
-export async function memInboxTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const args: string[] = [];
-  const since = toStringValue(parsed.since);
-  if (since) {
-    args.push('--since', since);
-  }
-  const wu = toStringValue(parsed.wu);
-  if (wu) {
-    args.push('--wu', wu);
-  }
-  const lane = toStringValue(parsed.lane);
-  if (lane) {
-    args.push('--lane', lane);
-  }
-  const reader = toStringValue(parsed.for);
-  if (reader) {
-    args.push('--for', reader);
-  }
-  const thread = toStringValue(parsed.thread);
-  if (thread) {
-    args.push('--thread', thread);
-  }
-  const intent = toStringValue(parsed.intent);
-  if (intent) {
-    args.push('--intent', intent);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_INBOX, args);
-}
-
-export async function memSignalTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const message = toStringValue(parsed.message);
-  if (!message) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.MESSAGE_REQUIRED);
-  }
-
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const args = [message, '--wu', wu];
-  const to = toStringValue(parsed.to);
-  if (to) {
-    args.push('--to', to);
-  }
-  const thread = toStringValue(parsed.thread);
-  if (thread) {
-    args.push('--thread', thread);
-  }
-  const replyTo = toStringValue(parsed.reply_to);
-  if (replyTo) {
-    args.push('--reply-to', replyTo);
-  }
-  const intent = toStringValue(parsed.intent);
-  if (intent) {
-    args.push('--intent', intent);
-  }
-  const interrupt = toStringValue(parsed.interrupt);
-  if (interrupt) {
-    args.push('--interrupt', interrupt);
-  }
-  if (parsed.requires_ack === true) {
-    args.push('--requires-ack');
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_SIGNAL, args);
-}
-
-export async function memConvergedTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const thread = toStringValue(parsed.thread);
-  if (!thread) {
-    return createMissingParameterOutput('thread is required');
-  }
-
-  const args = ['--thread', thread];
-  if (parsed.quiet === true) {
-    args.push('--quiet');
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_CONVERGED, args);
-}
-
-export async function memSummarizeTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_SUMMARIZE, ['--wu', wu]);
-}
-
-export async function memTriageTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const args = ['--wu', wu];
-  const promote = toStringValue(parsed.promote);
-  if (promote) {
-    args.push('--promote', promote);
-  }
-  const lane = toStringValue(parsed.lane);
-  if (lane) {
-    args.push('--lane', lane);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_TRIAGE, args);
-}
-
-export async function memRecoverTool(input: unknown): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const wu = toStringValue(parsed.wu);
-  if (!wu) {
-    return createMissingParameterOutput(MISSING_PARAMETER_MESSAGES.WU_REQUIRED);
-  }
-
-  const args = ['--wu', wu];
-  const maxSize = toIntegerString(parsed.max_size);
-  if (maxSize) {
-    args.push('--max-size', maxSize);
-  }
-  const format = toStringValue(parsed.format);
-  if (format) {
-    args.push('--format', format);
-  }
-  if (parsed.quiet === true) {
-    args.push('--quiet');
-  }
-  const baseDir = toStringValue(parsed.base_dir);
-  if (baseDir) {
-    args.push('--base-dir', baseDir);
-  }
-
-  return executeMemoryTool(MEMORY_TOOLS.MEM_RECOVER, args);
-}