nemoris 0.1.0

package/src/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+process.stdout.write = (chunk, ...args) => {
+  const text = typeof chunk === "string"
+    ? chunk
+    : Buffer.isBuffer(chunk)
+      ? chunk.toString("utf8")
+      : null;
+
+  if (text === null) {
+    return originalStdoutWrite(chunk, ...args);
+  }
+
+  const filtered = text
+    .split(/\r?\n/)
+    .filter((line) => !line.startsWith("[openclaw/patch]"))
+    .join("\n");
+
+  if (!filtered) {
+    return true;
+  }
+
+  const nextChunk = Buffer.isBuffer(chunk) ? Buffer.from(filtered, "utf8") : filtered;
+  return originalStdoutWrite(nextChunk, ...args);
+};
+
+const [{ default: path }, { default: fs }, { fileURLToPath }, { resolveEnvPath }] = await Promise.all([
+  import("node:path"),
+  import("node:fs"),
+  import("node:url"),
+  import("./utils/env-loader.js"),
+]);
+
+function printVersionAndExit() {
+  const arg = process.argv[2];
+  if (arg === "--version" || arg === "-v" || arg === "version") {
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const { version } = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    console.log(version);
+    process.exit(0);
+  }
+}
+
+const ENV_BLOCKLIST = new Set(["NODE_OPTIONS", "LD_PRELOAD", "LD_LIBRARY_PATH", "DYLD_INSERT_LIBRARIES"]);
+
+function loadParentEnv(envPath) {
+  try {
+    const content = fs.readFileSync(envPath, "utf8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIdx = trimmed.indexOf("=");
+      if (eqIdx < 1) continue;
+      const key = trimmed.slice(0, eqIdx).trim();
+      if (ENV_BLOCKLIST.has(key)) continue;
+      if (process.env[key] !== undefined) continue;
+      let value = trimmed.slice(eqIdx + 1).trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      process.env[key] = value;
+    }
+  } catch {
+    // .env file is optional
+  }
+}
+
+printVersionAndExit();
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const parentEnvPath = resolveEnvPath(__dirname);
+loadParentEnv(parentEnvPath);
+
+const { main } = await import("./cli-main.js");
+const exitCode = await main(process.argv);
+if (typeof exitCode === "number") {
+  process.exitCode = exitCode;
+}

package/src/config/loader.js

@@ -0,0 +1,332 @@
+import path from "node:path";
+import { homedir } from "node:os";
+import { listFilesRecursive, readText } from "../utils/fs.js";
+import { parseToml } from "./toml-lite.js";
+import { validateRuntimeConfig } from "../runtime/config-validator.js";
+import { validateOrThrow, SCHEMAS } from "./schema-validator.js";
+
+const PATH_KEYS = new Set(["workspaceRoot", "soulRef", "purposeRef", "userRef"]);
+
+async function loadDirectoryAsMap(dirPath, projectRoot, keyField = "id", { schema } = {}) {
+  const files = (await listFilesRecursive(dirPath)).filter((filePath) => filePath.endsWith(".toml"));
+  const entries = [];
+
+  for (const filePath of files) {
+    const parsed = resolveConfigPaths(normalizeKeys(parseToml(await readText(filePath, ""))), {
+      projectRoot
+    });
+    if (schema) {
+      validateOrThrow(parsed, schema, filePath);
+    }
+    const id = parsed[keyField] || path.basename(filePath, ".toml");
+    entries.push([id, { ...parsed, __filePath: filePath }]);
+  }
+
+  return Object.fromEntries(entries);
+}
+
+function normalizeKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeKeys(item));
+  }
+
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const normalized = {};
+  for (const [key, child] of Object.entries(value)) {
+    const normalizedKey = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+    normalized[normalizedKey] = normalizeKeys(child);
+  }
+  return normalized;
+}
+
+export function expandEnvRefs(value) {
+  return String(value || "").replace(/\$\{([^}]+)\}|\$([A-Z0-9_]+)/gi, (_match, braced, simple) => {
+    const envName = braced || simple;
+    return process.env[envName] || "";
+  });
+}
+
+function resolveEnvValue(value) {
+  if (typeof value === "string" && value.startsWith("env:")) {
+    return process.env[value.slice(4)] || "";
+  }
+  return value;
+}
+
+export function resolvePathLike(value) {
+  if (typeof value !== "string") return value;
+  const expanded = expandEnvRefs(value);
+  if (!expanded) return expanded;
+  if (expanded === "~") return homedir();
+  if (expanded.startsWith("~/") || expanded.startsWith("~\\")) {
+    return path.normalize(homedir() + expanded.slice(1));
+  }
+  if (path.isAbsolute(expanded)) return path.normalize(expanded);
+  return expanded;
+}
+
+function resolveConfigPaths(value, { projectRoot, parentKey = null } = {}) {
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveConfigPaths(item, { projectRoot, parentKey }));
+  }
+
+  if (typeof value === "string") {
+    if (PATH_KEYS.has(parentKey)) {
+      const resolvedPath = resolvePathLike(value);
+      if (!resolvedPath || path.isAbsolute(resolvedPath)) {
+        return resolvedPath;
+      }
+      return path.resolve(projectRoot, resolvedPath);
+    }
+    return expandEnvRefs(value);
+  }
+
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const resolved = {};
+  for (const [key, child] of Object.entries(value)) {
+    resolved[key] = resolveConfigPaths(child, { projectRoot, parentKey: key });
+  }
+  return resolved;
+}
+
+export class ConfigLoader {
+  constructor({ rootDir }) {
+    this.rootDir = rootDir;
+    this.projectRoot = path.dirname(rootDir);
+  }
+
+  async loadRouter() {
+    const filePath = path.join(this.rootDir, "router.toml");
+    const parsed = parseToml(await readText(filePath, ""));
+    const lanes = {};
+    for (const [laneName, rawValue] of Object.entries(parsed.lanes || {})) {
+      const value = normalizeKeys(rawValue);
+      lanes[laneName] = {
+        primary: value.primary,
+        fallbackModels: value.fallbackModels || [],
+        fallback: value.fallback,
+        manualBump: value.manualBump
+      };
+    }
+    validateOrThrow(lanes, SCHEMAS.router, filePath);
+    return lanes;
+  }
+
+  async loadProviders() {
+    return loadDirectoryAsMap(path.join(this.rootDir, "providers"), this.projectRoot, "id", { schema: SCHEMAS.provider });
+  }
+
+  async loadEmbeddings() {
+    return normalizeKeys(parseToml(await readText(path.join(this.rootDir, "embeddings.toml"), "")));
+  }
+
+  async loadRuntimeSettings() {
+    const filePath = path.join(this.rootDir, "runtime.toml");
+    const parsed = normalizeKeys(parseToml(await readText(filePath, "")));
+    validateOrThrow(parsed, SCHEMAS.runtime, filePath);
+    const configuredMaxJobsPerTick = parsed.concurrency?.maxJobsPerTick ?? parsed.concurrency?.maxConcurrentJobs;
+    return {
+      safety: parsed.safety || {},
+      concurrency: {
+        ...parsed.concurrency,
+        maxJobsPerTick: configuredMaxJobsPerTick ?? 2
+      },
+      retention: {
+        runs: parsed.retention?.runs || {},
+        notifications: parsed.retention?.notifications || {},
+        deliveries: parsed.retention?.deliveries || {},
+        transportInbox: parsed.retention?.transportInbox || {}
+      },
+      retrieval: {
+        lexicalWeight: parsed.retrieval?.lexicalWeight ?? 0.36,
+        embeddingWeight: parsed.retrieval?.embeddingWeight ?? 0.3,
+        recencyWeight: parsed.retrieval?.recencyWeight ?? 0.14,
+        salienceWeight: parsed.retrieval?.salienceWeight ?? 0.14,
+        typeWeight: parsed.retrieval?.typeWeight ?? 0.06,
+        semanticRescueBonus: parsed.retrieval?.semanticRescueBonus ?? 0.06,
+        shadowSnapshotPenalty: parsed.retrieval?.shadowSnapshotPenalty ?? 0.12
+      },
+      memoryLocks: {
+        ttlMs: parsed.memoryLocks?.ttlMs ?? 15000,
+        retryDelayMs: parsed.memoryLocks?.retryDelayMs ?? 25,
+        maxRetries: parsed.memoryLocks?.maxRetries ?? 40
+      },
+      handoffs: {
+        pendingTimeoutMinutes: parsed.handoffs?.pendingTimeoutMinutes ?? 120,
+        escalateOnExpiry: parsed.handoffs?.escalateOnExpiry ?? true,
+        escalationDeliveryProfile: parsed.handoffs?.escalationDeliveryProfile || null
+      },
+      followUps: {
+        pendingTimeoutMinutes: parsed.followUps?.pendingTimeoutMinutes ?? 120,
+        escalateOnExpiry: parsed.followUps?.escalateOnExpiry ?? true,
+        escalationDeliveryProfile: parsed.followUps?.escalationDeliveryProfile || null,
+        completionTtlMultiplier: parsed.followUps?.completionTtlMultiplier ?? 2
+      },
+      yields: {
+        enabled: parsed.yields?.enabled ?? true,
+        defaultTargetSurface: parsed.yields?.defaultTargetSurface || "operator_review"
+      },
+      delivery: {
+        preventResendOnUncertain: parsed.delivery?.preventResendOnUncertain ?? true,
+        retryOnFailure: parsed.delivery?.retryOnFailure ?? false
+      },
+      maintenance: {
+        walCheckpointThresholdBytes: parsed.maintenance?.walCheckpointThresholdBytes ?? 64 * 1024 * 1024,
+        pruneOnTick: parsed.maintenance?.pruneOnTick ?? true,
+        sweepPendingHandoffsOnTick: parsed.maintenance?.sweepPendingHandoffsOnTick ?? true,
+        sweepPendingFollowUpsOnTick: parsed.maintenance?.sweepPendingFollowUpsOnTick ?? true
+      },
+      network: {
+        dnsResultOrder: parsed.network?.dnsResultOrder || "system",
+        connectTimeoutMs: parsed.network?.connectTimeoutMs ?? 10000,
+        readTimeoutMs: parsed.network?.readTimeoutMs ?? 30000,
+        retryBudget: parsed.network?.retryBudget ?? 1,
+        circuitBreakerThreshold: parsed.network?.circuitBreakerThreshold ?? 3
+      },
+      bootstrapCache: {
+        enabled: parsed.bootstrapCache?.enabled ?? true,
+        identityTtlMs: parsed.bootstrapCache?.identityTtlMs ?? 300000
+      },
+      reportFallback: {
+        enabled: parsed.reportFallback?.enabled ?? false,
+        lane: parsed.reportFallback?.lane || "report_fallback_lowcost",
+        allowedJobIds: parsed.reportFallback?.allowedJobIds || ["workspace-health"],
+        allowedFailureClasses: parsed.reportFallback?.allowedFailureClasses || ["timeout", "provider_loading"]
+      },
+      shutdown: {
+        drainTimeoutMs: parsed.shutdown?.drainTimeoutMs ?? 15000,
+        transportShutdownTimeoutMs: parsed.shutdown?.transportShutdownTimeoutMs ?? 5000
+      },
+      circuitBreaker: {
+        failureThreshold: parsed.circuitBreaker?.failureThreshold ?? 5,
+        resetTimeoutSeconds: parsed.circuitBreaker?.resetTimeoutSeconds ?? 30,
+        halfOpenMaxProbes: parsed.circuitBreaker?.halfOpenMaxProbes ?? 1,
+        transientCodes: parsed.circuitBreaker?.transientCodes ?? [408, 429, 500, 502, 503, 504]
+      },
+      extensions: {
+        implicitWorkspaceAutoload: parsed.extensions?.implicitWorkspaceAutoload ?? false,
+        requireExplicitTrust: parsed.extensions?.requireExplicitTrust ?? true,
+        trustedRoots: parsed.extensions?.trustedRoots || []
+      },
+      telegram: {
+        botTokenEnv: parsed.telegram?.botTokenEnv || "NEMORIS_TELEGRAM_BOT_TOKEN",
+        pollingMode: parsed.telegram?.pollingMode ?? false,
+        webhookUrl: parsed.telegram?.webhookUrl || "",
+        operatorChatId: parsed.telegram?.operatorChatId || "",
+        authorizedChatIds: parsed.telegram?.authorizedChatIds || [],
+        defaultAgent: parsed.telegram?.defaultAgent || "nemo",
+      },
+      slack: {
+        enabled: parsed.slack?.enabled ?? false,
+        botToken: resolveEnvValue(parsed.slack?.botToken || ""),
+        signingSecret: resolveEnvValue(parsed.slack?.signingSecret || ""),
+        eventsPath: parsed.slack?.eventsPath || "/slack/events",
+        slashPath: parsed.slack?.slashPath || "/slack/slash",
+      },
+    };
+  }
+
+  async loadDelivery() {
+    return normalizeKeys(parseToml(await readText(path.join(this.rootDir, "delivery.toml"), "")));
+  }
+
+  async loadTaskRouter() {
+    return normalizeKeys(parseToml(await readText(path.join(this.rootDir, "task-router.toml"), "")));
+  }
+
+  async loadOutputContracts() {
+    return normalizeKeys(parseToml(await readText(path.join(this.rootDir, "output-contracts.toml"), "")));
+  }
+
+  async loadImprovementTargets() {
+    return normalizeKeys(parseToml(await readText(path.join(this.rootDir, "improvement-targets.toml"), "")));
+  }
+
+  async loadPeers() {
+    return normalizeKeys(parseToml(await readText(path.join(this.rootDir, "peers.toml"), "")));
+  }
+
+  async loadAgents() {
+    return loadDirectoryAsMap(path.join(this.rootDir, "agents"), this.projectRoot, "id", { schema: SCHEMAS.agent });
+  }
+
+  async loadJobs() {
+    return loadDirectoryAsMap(path.join(this.rootDir, "jobs"), this.projectRoot, "id", { schema: SCHEMAS.job });
+  }
+
+  async loadPolicies() {
+    return loadDirectoryAsMap(path.join(this.rootDir, "policies"), this.projectRoot);
+  }
+
+  async loadMcp() {
+    const filePath = path.join(this.rootDir, "mcp.toml");
+    try {
+      const raw = await readText(filePath, "");
+      if (!raw.trim()) return { servers: {} };
+      const parsed = normalizeKeys(parseToml(raw));
+      const servers = {};
+      for (const [id, serverConfig] of Object.entries(parsed.servers || {})) {
+        if (serverConfig.enabled === false) continue;
+        servers[id] = {
+          command: serverConfig.command,
+          args: serverConfig.args || [],
+          env: serverConfig.env || {},
+          timeout: serverConfig.timeout || 30000,
+        };
+      }
+      return { servers };
+    } catch (err) {
+      if (err.code === "ENOENT" || err.message?.includes("ENOENT")) return { servers: {} };
+      throw err;
+    }
+  }
+
+  async loadAll(options = {}) {
+    const [router, providers, agents, jobs, policies, runtime, taskRouter, delivery, peers, outputContracts, improvementTargets, mcp] = await Promise.all([
+      this.loadRouter(),
+      this.loadProviders(),
+      this.loadAgents(),
+      this.loadJobs(),
+      this.loadPolicies(),
+      this.loadRuntimeSettings(),
+      this.loadTaskRouter(),
+      this.loadDelivery(),
+      this.loadPeers(),
+      this.loadOutputContracts(),
+      this.loadImprovementTargets(),
+      this.loadMcp().catch((err) => {
+        if (err.code !== "ENOENT" && !err.message?.includes("ENOENT")) {
+          console.warn(`[config] mcp.toml parse error: ${err.message}`);
+        }
+        return { servers: {} };
+      })
+    ]);
+
+    const config = {
+      router,
+      providers,
+      agents,
+      jobs,
+      policies,
+      runtime,
+      taskRouter,
+      delivery,
+      peers,
+      outputContracts,
+      improvementTargets: improvementTargets.targets || {},
+      mcp,
+      embeddings: await this.loadEmbeddings()
+    };
+
+    if (!options?.skipValidation) {
+      await validateRuntimeConfig(config);
+    }
+    return config;
+  }
+}

package/src/config/schema-validator.js

@@ -0,0 +1,214 @@
+/**
+ * TOML config schema validation — validates parsed config objects against
+ * expected schemas at load time so that missing/malformed fields fail loudly
+ * instead of silently degrading at runtime.
+ */
+
+import { formatRuntimeError, RuntimeError } from "../utils/errors.js";
+
+// ── Schema definitions ──────────────────────────────────────────────
+
+const AGENT_SCHEMA = {
+  label: "agent",
+  required: {
+    id: "string",
+    primaryLane: "string",
+    memoryPolicy: "string",
+    toolPolicy: "string"
+  }
+};
+
+const JOB_SCHEMA = {
+  label: "job",
+  required: {
+    id: "string",
+    modelLane: "string"
+  },
+  atLeastOne: [["schedule", "trigger"]]
+};
+
+const PROVIDER_SCHEMA = {
+  label: "provider",
+  required: {
+    id: "string"
+  },
+  atLeastOne: [["adapter", "type"]]
+};
+
+const RUNTIME_SCHEMA = {
+  label: "runtime",
+  requiredSections: {
+    safety: {
+      contextTokens: "number"
+    }
+  }
+};
+
+const ROUTER_SCHEMA = {
+  label: "router",
+  minLanes: 1
+};
+
+export const SCHEMAS = {
+  agent: AGENT_SCHEMA,
+  job: JOB_SCHEMA,
+  provider: PROVIDER_SCHEMA,
+  runtime: RUNTIME_SCHEMA,
+  router: ROUTER_SCHEMA
+};
+
+// ── Validation engine ───────────────────────────────────────────────
+
+export class ConfigSchemaError extends Error {
+  constructor(message, errors) {
+    super(message);
+    this.name = "ConfigSchemaError";
+    this.validationErrors = errors;
+  }
+}
+
+function typeLabel(value) {
+  if (value === null || value === undefined) return "missing";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function checkType(value, expectedType) {
+  if (value === null || value === undefined) return false;
+  if (expectedType === "array") return Array.isArray(value);
+  return typeof value === expectedType;
+}
+
+/**
+ * Validate a parsed config object against a schema definition.
+ *
+ * @param {object} config  – the parsed (and key-normalised) config object
+ * @param {object} schema  – one of the SCHEMAS entries
+ * @param {string} filePath – file path for error messages
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateConfig(config, schema, filePath) {
+  const errors = [];
+  const ctx = filePath || schema.label || "config";
+
+  if (!config || typeof config !== "object") {
+    errors.push(`${ctx}: config is ${typeLabel(config)}, expected an object`);
+    return { ok: false, errors };
+  }
+
+  // Check required fields
+  if (schema.required) {
+    for (const [field, expectedType] of Object.entries(schema.required)) {
+      if (!(field in config) || config[field] === undefined || config[field] === null || config[field] === "") {
+        errors.push(`${ctx}: missing required field "${field}"`);
+      } else if (!checkType(config[field], expectedType)) {
+        errors.push(
+          `${ctx}: field "${field}" should be ${expectedType}, got ${typeLabel(config[field])}`
+        );
+      }
+    }
+  }
+
+  // Check at-least-one groups (e.g. schedule OR trigger)
+  if (schema.atLeastOne) {
+    for (const group of schema.atLeastOne) {
+      const present = group.filter((field) => field in config && config[field] !== undefined && config[field] !== null && config[field] !== "");
+      if (present.length === 0) {
+        errors.push(`${ctx}: must have at least one of: ${group.join(", ")}`);
+      }
+    }
+  }
+
+  // Check required sections (nested objects with typed sub-fields)
+  if (schema.requiredSections) {
+    for (const [section, subFields] of Object.entries(schema.requiredSections)) {
+      if (!(section in config) || !config[section] || typeof config[section] !== "object") {
+        errors.push(`${ctx}: missing required section [${section}]`);
+      } else {
+        for (const [subField, expectedType] of Object.entries(subFields)) {
+          const value = config[section][subField];
+          if (value === undefined || value === null) {
+            errors.push(`${ctx}: missing required field "${section}.${subField}"`);
+          } else if (!checkType(value, expectedType)) {
+            errors.push(
+              `${ctx}: field "${section}.${subField}" should be ${expectedType}, got ${typeLabel(value)}`
+            );
+          }
+        }
+      }
+    }
+  }
+
+  // Router-specific: must have at least N lane definitions
+  if (schema.minLanes !== undefined) {
+    const laneCount = Object.keys(config).length;
+    if (laneCount < schema.minLanes) {
+      errors.push(`${ctx}: must define at least ${schema.minLanes} lane(s), found ${laneCount}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Validate and throw if invalid — convenience wrapper used by the config loader.
+ */
+export function validateOrThrow(config, schema, filePath) {
+  const result = validateConfig(config, schema, filePath);
+  if (!result.ok) {
+    const runtimeError = new RuntimeError(
+      `Config schema validation failed for ${filePath || schema.label}`,
+      { category: "config", context: { filePath, schema: schema.label, errorCount: result.errors.length }, recoverable: false }
+    );
+    const formatted = formatRuntimeError(runtimeError, { details: result.errors.join("; ") });
+    throw new ConfigSchemaError(formatted, result.errors);
+  }
+  return config;
+}
+
+/**
+ * Validate all config sections in a full loadAll() result.
+ * Returns { ok, errors[] } for CLI / test consumption.
+ */
+export function validateAllConfigs(config, rootDir) {
+  const allErrors = [];
+
+  // Agents
+  for (const [id, agent] of Object.entries(config.agents || {})) {
+    const filePath = agent.__filePath || `${rootDir}/agents/${id}.toml`;
+    const result = validateConfig(agent, AGENT_SCHEMA, filePath);
+    allErrors.push(...result.errors);
+  }
+
+  // Jobs
+  for (const [id, job] of Object.entries(config.jobs || {})) {
+    const filePath = job.__filePath || `${rootDir}/jobs/${id}.toml`;
+    const result = validateConfig(job, JOB_SCHEMA, filePath);
+    allErrors.push(...result.errors);
+  }
+
+  // Providers
+  for (const [id, provider] of Object.entries(config.providers || {})) {
+    const filePath = provider.__filePath || `${rootDir}/providers/${id}.toml`;
+    const result = validateConfig(provider, PROVIDER_SCHEMA, filePath);
+    allErrors.push(...result.errors);
+  }
+
+  // Runtime
+  if (config.runtime) {
+    const result = validateConfig(config.runtime, RUNTIME_SCHEMA, `${rootDir}/runtime.toml`);
+    allErrors.push(...result.errors);
+  } else {
+    allErrors.push(`${rootDir}/runtime.toml: runtime config is missing entirely`);
+  }
+
+  // Router
+  if (config.router) {
+    const result = validateConfig(config.router, ROUTER_SCHEMA, `${rootDir}/router.toml`);
+    allErrors.push(...result.errors);
+  } else {
+    allErrors.push(`${rootDir}/router.toml: router config is missing entirely`);
+  }
+
+  return { ok: allErrors.length === 0, errors: allErrors };
+}

package/src/config/toml-lite.js

@@ -0,0 +1,8 @@
+import { parse } from "smol-toml";
+
+export function parseToml(source) {
+  if (!source || !String(source).trim()) {
+    return {};
+  }
+  return parse(String(source));
+}

package/src/daemon/action-handlers.js

@@ -0,0 +1,71 @@
+/**
+ * Factory that creates an action executor wired to real system components.
+ * Returns an async function: (actionName, context) => boolean (success).
+ */
+export function createActionHandler({ getBreaker, mcpConsumer, stateStore, telegramSendFn, lastFailedMessage }) {
+  const handlers = {
+    async circuit_break(ctx) {
+      const breaker = getBreaker(ctx.provider);
+      if (breaker) breaker.recordFailure(ctx.code || 500);
+      return true;
+    },
+    async retry_then_break(ctx) {
+      // Retry once, then circuit break
+      const breaker = getBreaker(ctx.provider);
+      if (breaker) breaker.recordFailure(ctx.code || 408);
+      return true;
+    },
+    async restart(ctx) {
+      if (!mcpConsumer) return false;
+      await mcpConsumer.ensureRunning(ctx.server);
+      return true;
+    },
+    async kill_restart(ctx) {
+      if (!mcpConsumer) return false;
+      await mcpConsumer.shutdown(ctx.server);
+      await mcpConsumer.ensureRunning(ctx.server);
+      return true;
+    },
+    async compact() {
+      // Trigger is handled by existing maintenance cycle — just return true
+      return true;
+    },
+    async rebuild_index() {
+      return true; // Existing embedding rebuild runs in maintenance
+    },
+    async reap() {
+      try {
+        const { reapOrphanedJobs } = await import("../runtime/orphan-reaper.js");
+        reapOrphanedJobs(stateStore);
+      } catch {
+        // stateStore may be a stub in tests or unavailable — best-effort
+      }
+      return true;
+    },
+    async retry_backoff(ctx) {
+      if (!telegramSendFn) return false;
+      const delays = [1000, 2000, 4000]; // 3 retries with exponential backoff
+      for (const delay of delays) {
+        await new Promise(r => setTimeout(r, delay));
+        const result = await telegramSendFn(lastFailedMessage || "Retry");
+        if (result?.ok) return true;
+      }
+      return false;
+    },
+    async resend(ctx) {
+      if (!telegramSendFn || !lastFailedMessage) return false;
+      const result = await telegramSendFn(lastFailedMessage);
+      return !!result?.ok;
+    }
+  };
+
+  return async (actionName, context) => {
+    const handler = handlers[actionName];
+    if (!handler) return false;
+    try {
+      return await handler(context || {});
+    } catch {
+      return false;
+    }
+  };
+}