chainlesschain 0.163.4 → 0.163.6

package/src/lib/automation-center.js

@@ -0,0 +1,435 @@
+import { createHash } from "node:crypto";
+import {
+  automationExecutionAuthorityDigest,
+  automationExecutionAuthoritySnapshot,
+  inspectAutomationExecutionAuthority,
+  reserveAutomationExecutionAuthority,
+} from "./automation-execution-authority.js";
+import {
+  EXECUTION_STATUS,
+  FLOW_STATUS,
+  TRIGGER_TYPE,
+  deleteFlow,
+  executeFlow,
+  getExecution,
+  getFlow,
+  listExecutions,
+  listFlows,
+  listTriggers,
+  updateFlowStatus,
+} from "./automation-engine.js";
+import {
+  SchedulerKernelError,
+  canonicalJson,
+  normalizeIdentifier,
+} from "./scheduler-kernel/contract.js";
+import { RoutineStore } from "./routine-store.js";
+import { buildRoutineCenterProjection } from "./automation-center-routines.js";
+
+export const AUTOMATION_CENTER_SCHEMA = "chainlesschain.automation-center/v2";
+export const AUTOMATION_CENTER_SCHEMA_VERSION = 2;
+export const AUTOMATION_CENTER_ACTIONS = Object.freeze([
+  "run_now",
+  "retry_failed",
+  "pause",
+  "resume",
+  "disable",
+  "delete",
+]);
+
+function centerError(code, message, details = undefined) {
+  const error = new SchedulerKernelError(code, message, details);
+  error.retryable = false;
+  return error;
+}
+
+function digest(value) {
+  return `sha256:${createHash("sha256")
+    .update("chainlesschain.automation-center.v2\0", "utf8")
+    .update(canonicalJson(value, "automationCenter"), "utf8")
+    .digest("hex")}`;
+}
+
+function boundedText(value, maximum = 240) {
+  return String(value || "")
+    .replace(/[\r\n]+/g, " ")
+    .slice(0, maximum);
+}
+
+function safeTriggerScope(trigger) {
+  const config = trigger?.config || {};
+  if (trigger.type === TRIGGER_TYPE.EVENT) {
+    return {
+      event: boundedText(config.event, 80) || null,
+      origins: Array.isArray(config.scope?.origins)
+        ? config.scope.origins
+            .map((value) => boundedText(value, 64))
+            .slice(0, 16)
+        : [],
+      senders: Array.isArray(config.scope?.senders)
+        ? config.scope.senders
+            .map((value) => boundedText(value, 96))
+            .slice(0, 32)
+        : [],
+    };
+  }
+  if (trigger.type === TRIGGER_TYPE.SCHEDULE) {
+    return { cron: boundedText(config.cron, 120) || null };
+  }
+  if (trigger.type === TRIGGER_TYPE.WEBHOOK) {
+    // Webhook URLs often embed bearer material. The center reports that a
+    // route is configured without reflecting the URL into privileged IDE UI.
+    return {
+      endpointConfigured: typeof config.url === "string" && Boolean(config.url),
+    };
+  }
+  if (trigger.type === TRIGGER_TYPE.CONDITION) {
+    return { expression: boundedText(config.expression, 240) || null };
+  }
+  return {};
+}
+
+function projectTrigger(trigger) {
+  return {
+    id: trigger.id,
+    type: trigger.type,
+    enabled: trigger.enabled === true,
+    scope: safeTriggerScope(trigger),
+    triggerCount: Number(trigger.triggerCount) || 0,
+    lastTriggeredAt: trigger.lastTriggeredAt || null,
+  };
+}
+
+function projectExecution(execution) {
+  return {
+    id: execution.id,
+    status: execution.status,
+    triggerType: execution.triggerType || null,
+    durationMs: Number(execution.durationMs) || 0,
+    startedAt: execution.startedAt || null,
+    completedAt: execution.completedAt || null,
+    error: execution.error ? boundedText(execution.error, 400) : null,
+  };
+}
+
+function projectSecurity(db, flow, now) {
+  try {
+    const result = inspectAutomationExecutionAuthority(db, flow, { now });
+    return {
+      state: result.ready ? "ready" : "denied",
+      ready: result.ready,
+      principalId: result.snapshot.principalId,
+      connectors: result.snapshot.connectors,
+      permissions: result.permissions,
+      budget: {
+        revision: result.snapshot.budget.revision,
+        windowMs: result.snapshot.budget.windowMs,
+        maxRuns: result.snapshot.budget.maxRuns,
+        maxActionSteps: result.snapshot.budget.maxActionSteps,
+        ...result.window,
+      },
+      issue: null,
+    };
+  } catch (error) {
+    const code = boundedText(
+      error?.code || "AUTOMATION_EXECUTION_PREFLIGHT_FAILED",
+      96,
+    );
+    return {
+      state:
+        code === "AUTOMATION_EXECUTION_BUDGET_REQUIRED" ||
+        code === "AUTOMATION_EXECUTION_PRINCIPAL_REQUIRED"
+          ? "unconfigured"
+          : "invalid",
+      ready: false,
+      principalId:
+        typeof flow.createdBy === "string" && flow.createdBy
+          ? flow.createdBy
+          : null,
+      connectors: [],
+      permissions: [],
+      budget: null,
+      issue: { code, message: boundedText(error?.message || error, 400) },
+    };
+  }
+}
+
+function action(id, available, reason, flowId, itemRevision) {
+  return {
+    id,
+    available,
+    reason: available ? null : reason,
+    preview: available
+      ? {
+          executor: "cli",
+          argv: [
+            "automation",
+            "center-action",
+            flowId,
+            id,
+            "--expected-revision",
+            itemRevision,
+            "--json",
+          ],
+          mutates: true,
+        }
+      : null,
+  };
+}
+
+function projectFlow(db, flow, { historyLimit, now }) {
+  const triggers = listTriggers(db, flow.id).map(projectTrigger);
+  const history = listExecutions(db, {
+    flowId: flow.id,
+    limit: historyLimit,
+  }).map(projectExecution);
+  const security = projectSecurity(db, flow, now);
+  const content = {
+    kind: "flow",
+    id: flow.id,
+    name: boundedText(flow.name, 200),
+    description: boundedText(flow.description, 500),
+    status: flow.status,
+    schedule: flow.schedule || null,
+    updatedAt: flow.updatedAt || null,
+    triggers,
+    history,
+    security,
+  };
+  const revision = digest(content);
+  const active = flow.status === FLOW_STATUS.ACTIVE;
+  const paused = flow.status === FLOW_STATUS.PAUSED;
+  const archived = flow.status === FLOW_STATUS.ARCHIVED;
+  const latestFailed = history[0]?.status === EXECUTION_STATUS.FAILED;
+  return {
+    ...content,
+    revision,
+    actions: [
+      action(
+        "run_now",
+        active && security.ready,
+        !active
+          ? "flow is not active"
+          : "permission or budget preflight denied",
+        flow.id,
+        revision,
+      ),
+      action(
+        "retry_failed",
+        active && latestFailed && security.ready,
+        !active
+          ? "flow is not active"
+          : !latestFailed
+            ? "latest run did not fail"
+            : "permission or budget preflight denied",
+        flow.id,
+        revision,
+      ),
+      action(
+        "pause",
+        active,
+        "only an active flow can be paused",
+        flow.id,
+        revision,
+      ),
+      action(
+        "resume",
+        paused && security.ready,
+        !paused
+          ? "only a paused flow can be resumed"
+          : "permission or budget preflight denied",
+        flow.id,
+        revision,
+      ),
+      action(
+        "disable",
+        !archived,
+        "flow is already disabled",
+        flow.id,
+        revision,
+      ),
+      action(
+        "delete",
+        archived,
+        "disable the flow before deleting it",
+        flow.id,
+        revision,
+      ),
+    ],
+  };
+}
+
+export function buildAutomationCenterProjection(
+  db,
+  {
+    limit = 100,
+    historyLimit = 20,
+    now = Date.now,
+    routineStore = new RoutineStore(),
+  } = {},
+) {
+  if (typeof now !== "function") {
+    throw centerError(
+      "AUTOMATION_CENTER_CLOCK_REQUIRED",
+      "automation center requires a clock",
+    );
+  }
+  const boundedLimit = Math.max(1, Math.min(1000, Number(limit) || 100));
+  const boundedHistory = Math.max(1, Math.min(100, Number(historyLimit) || 20));
+  const flows = listFlows(db, { limit: boundedLimit }).map((flow) =>
+    projectFlow(db, flow, { historyLimit: boundedHistory, now }),
+  );
+  const routineProjection = buildRoutineCenterProjection(routineStore, {
+    limit: boundedLimit,
+    historyLimit: boundedHistory,
+  });
+  const items = [...flows, ...routineProjection.items];
+  const summary = {
+    total: items.length,
+    flows: flows.length,
+    routines: routineProjection.items.length,
+    active: items.filter((item) => item.status === FLOW_STATUS.ACTIVE).length,
+    paused: items.filter((item) => item.status === FLOW_STATUS.PAUSED).length,
+    needsAttention: items.filter(
+      (item) =>
+        item.security.ready !== true ||
+        item.history[0]?.status === EXECUTION_STATUS.FAILED ||
+        item.history[0]?.status === "failed",
+    ).length,
+  };
+  return {
+    schema: AUTOMATION_CENTER_SCHEMA,
+    schemaVersion: AUTOMATION_CENTER_SCHEMA_VERSION,
+    authority: "cli",
+    connected: true,
+    generatedAt: new Date(Number(now())).toISOString(),
+    routineCatalogRevision: routineProjection.catalogRevision,
+    revision: digest({
+      summary,
+      mutations: {
+        createRoutine: routineProjection.createRoutine.preview.argv,
+        routineCatalogRevision: routineProjection.catalogRevision,
+      },
+      items: items.map((item) => ({
+        kind: item.kind,
+        id: item.id,
+        revision: item.revision,
+      })),
+    }),
+    summary,
+    mutations: { createRoutine: routineProjection.createRoutine },
+    items,
+  };
+}
+
+function executionIdFor(flowId, requestedAction, revision) {
+  return `exec-center-${createHash("sha256")
+    .update(`${flowId}\0${requestedAction}\0${revision}`, "utf8")
+    .digest("hex")}`;
+}
+
+export function runAutomationCenterAction(
+  db,
+  { flowId, action: requestedAction, expectedRevision, now = Date.now } = {},
+) {
+  const id = normalizeIdentifier(flowId, "flowId");
+  if (!AUTOMATION_CENTER_ACTIONS.includes(requestedAction)) {
+    throw centerError(
+      "AUTOMATION_CENTER_ACTION_INVALID",
+      `unsupported automation center action: ${requestedAction}`,
+    );
+  }
+  const flow = getFlow(db, id);
+  if (!flow) {
+    throw centerError(
+      "AUTOMATION_CENTER_FLOW_NOT_FOUND",
+      `automation flow not found: ${id}`,
+    );
+  }
+  const item = projectFlow(db, flow, { historyLimit: 20, now });
+  if (expectedRevision !== item.revision) {
+    throw centerError(
+      "AUTOMATION_CENTER_STALE",
+      `automation flow changed before ${requestedAction}: ${id}`,
+      { expectedRevision, currentRevision: item.revision },
+    );
+  }
+  const capability = item.actions.find((entry) => entry.id === requestedAction);
+  if (!capability?.available) {
+    throw centerError(
+      "AUTOMATION_CENTER_ACTION_UNAVAILABLE",
+      capability?.reason ||
+        `automation action is unavailable: ${requestedAction}`,
+    );
+  }
+
+  let result;
+  let retryOf = null;
+  if (requestedAction === "pause") {
+    result = updateFlowStatus(db, id, FLOW_STATUS.PAUSED);
+  } else if (requestedAction === "resume") {
+    result = updateFlowStatus(db, id, FLOW_STATUS.ACTIVE);
+  } else if (requestedAction === "disable") {
+    result = updateFlowStatus(db, id, FLOW_STATUS.ARCHIVED);
+  } else if (requestedAction === "delete") {
+    if (typeof db.transaction !== "function") {
+      throw centerError(
+        "AUTOMATION_CENTER_TRANSACTION_REQUIRED",
+        "deleting an automation flow requires a transactional database",
+      );
+    }
+    result = db
+      .transaction(() => {
+        db.prepare(
+          "DELETE FROM auto_execution_budget_reservations WHERE flow_id = ?",
+        ).run(id);
+        db.prepare(
+          "DELETE FROM auto_execution_budget_usage WHERE flow_id = ?",
+        ).run(id);
+        db.prepare("DELETE FROM auto_execution_budgets WHERE flow_id = ?").run(
+          id,
+        );
+        deleteFlow(db, id);
+        return { deleted: true };
+      })
+      .immediate();
+  } else {
+    const authority = automationExecutionAuthoritySnapshot(db, flow);
+    const occurrenceId = `automation-center:${requestedAction}:${id}:${item.revision.slice("sha256:".length)}`;
+    reserveAutomationExecutionAuthority(
+      db,
+      flow,
+      occurrenceId,
+      authority,
+      automationExecutionAuthorityDigest(authority, flow),
+      { now },
+    );
+    let inputData = { source: "automation-center" };
+    if (requestedAction === "retry_failed") {
+      const failed = getExecution(db, item.history[0].id);
+      if (!failed || failed.status !== EXECUTION_STATUS.FAILED) {
+        throw centerError(
+          "AUTOMATION_CENTER_FAILED_RUN_CHANGED",
+          `failed automation run changed before retry: ${id}`,
+        );
+      }
+      retryOf = failed.id;
+      inputData = failed.inputData;
+    }
+    result = executeFlow(db, id, {
+      triggerType: TRIGGER_TYPE.MANUAL,
+      inputData,
+      executionId: executionIdFor(id, requestedAction, item.revision),
+    });
+  }
+  return {
+    schema: "chainlesschain.automation-center-action/v1",
+    schemaVersion: 1,
+    authority: "cli",
+    flowId: id,
+    action: requestedAction,
+    previousRevision: item.revision,
+    ...(retryOf ? { retryOf } : {}),
+    result,
+  };
+}

package/src/lib/automation-engine.js

@@ -11,6 +11,7 @@
  */
 
 import crypto from "crypto";
+import { nextCronTime } from "./agent-schedule-store.js";
 
 /* ── Constants ─────────────────────────────────────────────── */
 
@@ -519,6 +520,12 @@ export function scheduleFlow(db, flowId, cron) {
   if (!cron || typeof cron !== "string") {
     throw new Error("cron expression required");
   }
+  // Validate at write time so an invalid schedule cannot poison a resident
+  // scheduler loop later. nextCronTime() parses the existing five-field cron
+  // dialect and returns the first matching minute.
+  if (nextCronTime(cron, Date.now()) === null) {
+    throw new Error("cron expression has no occurrence in the next 366 days");
+  }
   _requireFlow(db, flowId);
   db.prepare(
     `UPDATE auto_flows SET schedule = ?, updated_at = ? WHERE id = ?`,
@@ -732,29 +739,45 @@ export function executeFlow(db, flowId, options = {}) {
     inputData = {},
     triggerType = TRIGGER_TYPE.MANUAL,
     testMode = false,
+    executionId,
   } = options;
-  const execId = _genId("exec");
+  const execId =
+    executionId === undefined
+      ? _genId("exec")
+      : _normalizeExecutionId(executionId);
+  const existing = getExecution(db, execId);
+  if (existing) {
+    return _resolveExistingExecution(existing, { flowId, triggerType });
+  }
   const startedAt = _now();
   const startMs = Date.now();
 
-  db.prepare(
-    `INSERT INTO auto_executions
-     (id, flow_id, trigger_type, input_data, output_data, status, steps_log, duration_ms, error, test_mode, started_at, completed_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-  ).run(
-    execId,
-    flowId,
-    triggerType,
-    JSON.stringify(inputData),
-    null,
-    EXECUTION_STATUS.RUNNING,
-    JSON.stringify([]),
-    0,
-    null,
-    testMode ? 1 : 0,
-    startedAt,
-    null,
-  );
+  try {
+    db.prepare(
+      `INSERT INTO auto_executions
+       (id, flow_id, trigger_type, input_data, output_data, status, steps_log, duration_ms, error, test_mode, started_at, completed_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      execId,
+      flowId,
+      triggerType,
+      JSON.stringify(inputData),
+      null,
+      EXECUTION_STATUS.RUNNING,
+      JSON.stringify([]),
+      0,
+      null,
+      testMode ? 1 : 0,
+      startedAt,
+      null,
+    );
+  } catch (error) {
+    // A deterministic scheduler execution id may race another process. Resolve
+    // the winner from durable evidence instead of running the flow twice.
+    const concurrent = getExecution(db, execId);
+    if (!concurrent) throw error;
+    return _resolveExistingExecution(concurrent, { flowId, triggerType });
+  }
 
   const stepsLog = [];
   let finalStatus = EXECUTION_STATUS.SUCCESS;
@@ -817,6 +840,38 @@ export function executeFlow(db, flowId, options = {}) {
   );
 }
 
+function _normalizeExecutionId(value) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > 256 ||
+    !/^[A-Za-z0-9._:-]+$/.test(value)
+  ) {
+    const error = new Error("executionId must be a safe non-empty identifier");
+    error.code = "AUTOMATION_EXECUTION_ID_INVALID";
+    throw error;
+  }
+  return value;
+}
+
+function _resolveExistingExecution(existing, { flowId, triggerType }) {
+  if (existing.flowId !== flowId || existing.triggerType !== triggerType) {
+    const error = new Error(
+      `Execution id is already bound to another automation request: ${existing.id}`,
+    );
+    error.code = "AUTOMATION_EXECUTION_BINDING_MISMATCH";
+    throw error;
+  }
+  if (existing.status === EXECUTION_STATUS.RUNNING) {
+    const error = new Error(
+      `Automation execution outcome is unknown; refusing duplicate execution: ${existing.id}`,
+    );
+    error.code = "AUTOMATION_EXECUTION_OUTCOME_UNKNOWN";
+    throw error;
+  }
+  return existing;
+}
+
 export function fireTrigger(db, triggerId, inputData = {}) {
   const trig = getTrigger(db, triggerId);
   if (!trig) throw new Error(`Trigger not found: ${triggerId}`);