@lumenflow/cli 5.5.0 → 5.7.14

package/packs/sidekick/tool-impl/routine-tools.ts

@@ -1,440 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import { getStoragePort, type RoutineRecord, type RoutineStepRecord } from './storage.js';
-import {
-  asInteger,
-  asNonEmptyString,
-  buildAuditEvent,
-  createId,
-  failure,
-  isDryRun,
-  nowIso,
-  success,
-  toRecord,
-  type ToolContextLike,
-  type ToolOutput,
-} from './shared.js';
-import {
-  buildRoutineCommittedEvent,
-  buildRoutineExecutedEvent,
-  buildRoutinePlannedEvent,
-  buildRoutineStepFailedEvent,
-  emitSidekickEvent,
-} from '../sidekick-events.js';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const TOOL_NAMES = {
-  CREATE: 'routine:create',
-  LIST: 'routine:list',
-  UPDATE: 'routine:update',
-  DELETE: 'routine:delete',
-  RUN: 'routine:run',
-} as const;
-const ROUTINE_ID_REQUIRED_MESSAGE = 'id is required.';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-interface NormalizeStepsResult {
-  steps: RoutineStepRecord[];
-  warnings: string[];
-  failed_steps: Array<{ step_index: number; reason: string }>;
-}
-
-function normalizeSteps(value: unknown): NormalizeStepsResult {
-  if (!Array.isArray(value)) {
-    return { steps: [], warnings: [], failed_steps: [] };
-  }
-
-  const steps: RoutineStepRecord[] = [];
-  const warnings: string[] = [];
-  const failedSteps: Array<{ step_index: number; reason: string }> = [];
-
-  for (let i = 0; i < value.length; i++) {
-    const candidate = value[i];
-
-    // String shorthand: coerce "tool:name" → { tool: "tool:name", input: {} }
-    if (typeof candidate === 'string') {
-      const tool = asNonEmptyString(candidate);
-      if (tool) {
-        steps.push({ tool, input: {} });
-      } else {
-        const reason = `steps[${i}] invalid: expected non-empty string or object with "tool".`;
-        warnings.push(reason);
-        failedSteps.push({ step_index: i, reason });
-      }
-      continue;
-    }
-
-    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
-      const reason = `steps[${i}] invalid: expected object with "tool" or a tool name string.`;
-      warnings.push(reason);
-      failedSteps.push({ step_index: i, reason });
-      continue;
-    }
-
-    const record = candidate as Record<string, unknown>;
-    const tool = asNonEmptyString(record.tool);
-    if (!tool) {
-      const reason = `steps[${i}] invalid: missing or empty "tool" property.`;
-      warnings.push(reason);
-      failedSteps.push({ step_index: i, reason });
-      continue;
-    }
-
-    const input =
-      record.input && typeof record.input === 'object' && !Array.isArray(record.input)
-        ? (record.input as Record<string, unknown>)
-        : {};
-
-    steps.push({ tool, input });
-  }
-
-  return { steps, warnings, failed_steps: failedSteps };
-}
-
-function asOptionalBoolean(value: unknown): boolean | null {
-  if (value === true || value === false) {
-    return value;
-  }
-  return null;
-}
-
-async function emitRoutineStepFailures(
-  failedSteps: Array<{ step_index: number; reason: string }>,
-  metadata: { routine_id?: string; routine_name?: string },
-): Promise<void> {
-  for (const failedStep of failedSteps) {
-    await emitSidekickEvent(
-      buildRoutineStepFailedEvent({
-        step_index: failedStep.step_index,
-        reason: failedStep.reason,
-        ...(metadata.routine_id ? { routine_id: metadata.routine_id } : {}),
-        ...(metadata.routine_name ? { routine_name: metadata.routine_name } : {}),
-      }),
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// routine:create
-// ---------------------------------------------------------------------------
-
-async function routineCreateTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const name = asNonEmptyString(parsed.name);
-  const { steps, warnings, failed_steps } = normalizeSteps(parsed.steps);
-
-  if (!name) {
-    return failure('INVALID_INPUT', 'name is required.');
-  }
-  if (steps.length === 0) {
-    if (!isDryRun(parsed)) {
-      await emitRoutineStepFailures(failed_steps, { routine_name: name ?? undefined });
-    }
-    const detail =
-      warnings.length > 0
-        ? `steps must include at least one tool step. Issues: ${warnings.join('; ')}`
-        : 'steps must include at least one tool step.';
-    return failure('INVALID_INPUT', detail);
-  }
-
-  const now = nowIso();
-  const routine: RoutineRecord = {
-    id: createId('routine'),
-    name,
-    steps,
-    cron: asNonEmptyString(parsed.cron) ?? undefined,
-    enabled: asOptionalBoolean(parsed.enabled) ?? true,
-    created_at: now,
-    updated_at: now,
-  };
-
-  if (isDryRun(parsed)) {
-    return success({
-      dry_run: true,
-      routine: routine as unknown as Record<string, unknown>,
-      ...(warnings.length > 0 ? { warnings } : {}),
-    });
-  }
-
-  const storage = getStoragePort();
-  await storage.withLock(async () => {
-    const routines = await storage.readStore('routines');
-    routines.push(routine);
-    await storage.writeStore('routines', routines);
-    await storage.appendAudit(
-      buildAuditEvent({
-        tool: TOOL_NAMES.CREATE,
-        op: 'create',
-        context,
-        ids: [routine.id],
-      }),
-    );
-  });
-
-  await emitRoutineStepFailures(failed_steps, {
-    routine_id: routine.id,
-    routine_name: routine.name,
-  });
-  await emitSidekickEvent(buildRoutinePlannedEvent(routine));
-
-  return success({
-    routine: routine as unknown as Record<string, unknown>,
-    ...(warnings.length > 0 ? { warnings } : {}),
-  });
-}
-
-// ---------------------------------------------------------------------------
-// routine:list
-// ---------------------------------------------------------------------------
-
-async function routineListTool(input: unknown, _context?: ToolContextLike): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const limit = asInteger(parsed.limit);
-  const enabledOnly = parsed.enabled_only === true;
-
-  const storage = getStoragePort();
-  const routines = await storage.readStore('routines');
-
-  const filtered = enabledOnly ? routines.filter((routine) => routine.enabled) : routines;
-  const sorted = filtered.toSorted((a, b) => Date.parse(b.updated_at) - Date.parse(a.updated_at));
-
-  const items = limit && limit > 0 ? sorted.slice(0, limit) : sorted;
-
-  return success({
-    items: items as unknown as Record<string, unknown>,
-    count: items.length,
-  });
-}
-
-// ---------------------------------------------------------------------------
-// routine:update
-// ---------------------------------------------------------------------------
-
-async function routineUpdateTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const id = asNonEmptyString(parsed.id);
-  let patchFailedSteps: Array<{ step_index: number; reason: string }> = [];
-
-  if (!id) {
-    return failure('INVALID_INPUT', ROUTINE_ID_REQUIRED_MESSAGE);
-  }
-
-  const patch: Partial<RoutineRecord> = {};
-  const name = asNonEmptyString(parsed.name);
-  const cron =
-    typeof parsed.cron === 'string' ? (asNonEmptyString(parsed.cron) ?? undefined) : null;
-  const enabled = asOptionalBoolean(parsed.enabled);
-
-  if (name) {
-    patch.name = name;
-  }
-  if (cron !== null) {
-    patch.cron = cron;
-  }
-  if (enabled !== null) {
-    patch.enabled = enabled;
-  }
-  if (parsed.steps !== undefined) {
-    const { steps, warnings, failed_steps } = normalizeSteps(parsed.steps);
-    patchFailedSteps = failed_steps;
-    if (steps.length === 0) {
-      if (!isDryRun(parsed)) {
-        await emitRoutineStepFailures(failed_steps, { routine_id: id });
-      }
-      const detail =
-        warnings.length > 0
-          ? `steps must include at least one tool step. Issues: ${warnings.join('; ')}`
-          : 'steps must include at least one tool step.';
-      return failure('INVALID_INPUT', detail);
-    }
-    patch.steps = steps;
-  }
-
-  if (Object.keys(patch).length === 0) {
-    return failure(
-      'INVALID_INPUT',
-      'routine:update requires at least one of name, steps, cron, or enabled.',
-    );
-  }
-
-  const storage = getStoragePort();
-  const routines = await storage.readStore('routines');
-  const routine = routines.find((entry) => entry.id === id);
-
-  if (!routine) {
-    return failure('NOT_FOUND', `routine ${id} was not found.`);
-  }
-
-  const preview: RoutineRecord = {
-    ...routine,
-    ...patch,
-    updated_at: nowIso(),
-  };
-
-  if (isDryRun(parsed)) {
-    return success({
-      dry_run: true,
-      routine: preview as unknown as Record<string, unknown>,
-    });
-  }
-
-  await storage.withLock(async () => {
-    const latest = await storage.readStore('routines');
-    const target = latest.find((entry) => entry.id === id);
-    if (!target) {
-      return;
-    }
-    Object.assign(target, preview);
-    await storage.writeStore('routines', latest);
-    await storage.appendAudit(
-      buildAuditEvent({
-        tool: TOOL_NAMES.UPDATE,
-        op: 'update',
-        context,
-        ids: [id],
-      }),
-    );
-  });
-
-  const updated = await storage.readStore('routines');
-  const updatedRoutine = updated.find((entry) => entry.id === id);
-  await emitRoutineStepFailures(patchFailedSteps, {
-    routine_id: id,
-    routine_name: updatedRoutine?.name,
-  });
-  if (updatedRoutine) {
-    await emitSidekickEvent(buildRoutineCommittedEvent(updatedRoutine));
-  }
-  return success({ routine: updatedRoutine as unknown as Record<string, unknown> });
-}
-
-// ---------------------------------------------------------------------------
-// routine:delete
-// ---------------------------------------------------------------------------
-
-async function routineDeleteTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const id = asNonEmptyString(parsed.id);
-
-  if (!id) {
-    return failure('INVALID_INPUT', ROUTINE_ID_REQUIRED_MESSAGE);
-  }
-
-  const storage = getStoragePort();
-  const routines = await storage.readStore('routines');
-  const routine = routines.find((entry) => entry.id === id);
-
-  if (!routine) {
-    return failure('NOT_FOUND', `routine ${id} was not found.`);
-  }
-
-  if (isDryRun(parsed)) {
-    return success({
-      dry_run: true,
-      deleted_id: id,
-    });
-  }
-
-  await storage.withLock(async () => {
-    const latest = await storage.readStore('routines');
-    await storage.writeStore(
-      'routines',
-      latest.filter((entry) => entry.id !== id),
-    );
-    await storage.appendAudit(
-      buildAuditEvent({
-        tool: TOOL_NAMES.DELETE,
-        op: 'delete',
-        context,
-        ids: [id],
-      }),
-    );
-  });
-
-  return success({ deleted_id: id });
-}
-
-// ---------------------------------------------------------------------------
-// routine:run (PLAN-ONLY -- does NOT execute tool steps)
-// ---------------------------------------------------------------------------
-
-async function routineRunTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
-  const parsed = toRecord(input);
-  const id = asNonEmptyString(parsed.id);
-
-  if (!id) {
-    return failure('INVALID_INPUT', ROUTINE_ID_REQUIRED_MESSAGE);
-  }
-
-  const storage = getStoragePort();
-  const routines = await storage.readStore('routines');
-  const routine = routines.find((r) => r.id === id);
-
-  if (!routine) {
-    return failure('NOT_FOUND', `routine ${id} was not found.`);
-  }
-
-  await storage.appendAudit(
-    buildAuditEvent({
-      tool: TOOL_NAMES.RUN,
-      op: 'execute',
-      context,
-      ids: [id],
-      details: { plan_only: true },
-    }),
-  );
-
-  await emitSidekickEvent(
-    buildRoutineExecutedEvent({
-      routine_id: routine.id,
-      name: routine.name,
-      step_count: routine.steps.length,
-    }),
-  );
-
-  return success({
-    routine_id: routine.id,
-    name: routine.name,
-    plan_only: true,
-    plan: routine.steps.map((step, index) => ({
-      index,
-      tool: step.tool,
-      input: step.input,
-    })),
-    governance: {
-      dispatch_required: true,
-      execution: 'No tool steps were executed by routine:run. This endpoint only returns a plan.',
-    },
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Router (default export)
-// ---------------------------------------------------------------------------
-
-export default async function routineTools(
-  input: unknown,
-  context?: ToolContextLike,
-): Promise<ToolOutput> {
-  switch (context?.tool_name) {
-    case TOOL_NAMES.CREATE:
-      return routineCreateTool(input, context);
-    case TOOL_NAMES.LIST:
-      return routineListTool(input, context);
-    case TOOL_NAMES.UPDATE:
-      return routineUpdateTool(input, context);
-    case TOOL_NAMES.DELETE:
-      return routineDeleteTool(input, context);
-    case TOOL_NAMES.RUN:
-      return routineRunTool(input, context);
-    default:
-      return failure('UNKNOWN_TOOL', `Unknown routine tool: ${context?.tool_name ?? 'unknown'}`);
-  }
-}

package/packs/sidekick/tool-impl/runtime-context.ts

@@ -1,28 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import { AsyncLocalStorage } from 'node:async_hooks';
-import type { ChannelTransport } from './channel-transports.js';
-import type { StoragePort } from './storage.js';
-import type { SidekickEvent } from '../sidekick-events.js';
-
-export interface SidekickRuntimeContext {
-  storagePort: StoragePort;
-  channelTransports: Map<string, ChannelTransport>;
-  workspaceRoot?: string;
-  workspaceConfig?: unknown;
-  eventSink?: (event: SidekickEvent) => void | Promise<void>;
-}
-
-const runtimeContext = new AsyncLocalStorage<SidekickRuntimeContext>();
-
-export function getSidekickRuntimeContext(): SidekickRuntimeContext | undefined {
-  return runtimeContext.getStore();
-}
-
-export async function runWithSidekickRuntimeContext<T>(
-  context: SidekickRuntimeContext,
-  fn: () => Promise<T>,
-): Promise<T> {
-  return runtimeContext.run(context, fn);
-}

package/packs/sidekick/tool-impl/shared.ts

@@ -1,125 +0,0 @@
-// Copyright (c) 2026 Hellmai Ltd
-// SPDX-License-Identifier: LicenseRef-LumenFlow-Proprietary
-
-import { randomBytes } from 'node:crypto';
-import type { AuditEvent } from './storage.js';
-
-export interface ToolContextLike {
-  tool_name?: string;
-  receipt_id?: string;
-  workspace_id?: string;
-}
-
-export interface ToolOutput {
-  success: boolean;
-  data?: Record<string, unknown>;
-  error?: { code: string; message: string; details?: Record<string, unknown> };
-  metadata?: Record<string, unknown>;
-}
-
-export function toRecord(input: unknown): Record<string, unknown> {
-  if (input && typeof input === 'object' && !Array.isArray(input)) {
-    return input as Record<string, unknown>;
-  }
-  return {};
-}
-
-export function asNonEmptyString(value: unknown): string | null {
-  if (typeof value !== 'string') {
-    return null;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-export function asStringArray(value: unknown): string[] {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-  const items: string[] = [];
-  for (const entry of value) {
-    const normalized = asNonEmptyString(entry);
-    if (normalized) {
-      items.push(normalized);
-    }
-  }
-  return [...new Set(items)];
-}
-
-export function asInteger(value: unknown): number | null {
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    return Math.trunc(value);
-  }
-  if (typeof value === 'string') {
-    const parsed = Number.parseInt(value, 10);
-    return Number.isFinite(parsed) ? parsed : null;
-  }
-  return null;
-}
-
-export function isDryRun(input: Record<string, unknown>): boolean {
-  return input.dry_run === true;
-}
-
-export function nowIso(): string {
-  return new Date().toISOString();
-}
-
-export function createId(prefix: string): string {
-  return `${prefix}-${randomBytes(4).toString('hex')}`;
-}
-
-export function failure(
-  code: string,
-  message: string,
-  details?: Record<string, unknown>,
-): ToolOutput {
-  return {
-    success: false,
-    error: {
-      code,
-      message,
-      ...(details ? { details } : {}),
-    },
-  };
-}
-
-export function success(data: Record<string, unknown>): ToolOutput {
-  return {
-    success: true,
-    data,
-  };
-}
-
-export function matchesTags(requiredTags: string[], candidateTags: string[]): boolean {
-  if (requiredTags.length === 0) {
-    return true;
-  }
-  const candidateSet = new Set(candidateTags.map((tag) => tag.toLowerCase()));
-  return requiredTags.every((tag) => candidateSet.has(tag.toLowerCase()));
-}
-
-export function includesText(haystack: string, needle: string | null): boolean {
-  if (!needle) {
-    return true;
-  }
-  return haystack.toLowerCase().includes(needle.toLowerCase());
-}
-
-export function buildAuditEvent(input: {
-  tool: string;
-  op: AuditEvent['op'];
-  context?: ToolContextLike;
-  ids?: string[];
-  details?: Record<string, unknown>;
-}): AuditEvent {
-  return {
-    id: createId('evt'),
-    ts: nowIso(),
-    tool: input.tool,
-    op: input.op,
-    actor: input.context?.receipt_id,
-    ids: input.ids,
-    details: input.details,
-  };
-}