@hasna/loops 0.4.0 → 0.4.1

package/dist/index.js

@@ -3962,6 +3962,257 @@ class Store {
     this.db.close();
   }
 }
+// package.json
+var package_default = {
+  name: "@hasna/loops",
+  version: "0.4.1",
+  description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  bin: {
+    loops: "dist/cli/index.js",
+    "loops-daemon": "dist/daemon/index.js",
+    "loops-api": "dist/api/index.js",
+    "loops-runner": "dist/runner/index.js",
+    "loops-mcp": "dist/mcp/index.js"
+  },
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./sdk": {
+      types: "./dist/sdk/index.d.ts",
+      import: "./dist/sdk/index.js"
+    },
+    "./mcp": {
+      types: "./dist/mcp/index.d.ts",
+      import: "./dist/mcp/index.js"
+    },
+    "./api": {
+      types: "./dist/api/index.d.ts",
+      import: "./dist/api/index.js"
+    },
+    "./runner": {
+      types: "./dist/runner/index.d.ts",
+      import: "./dist/runner/index.js"
+    },
+    "./mode": {
+      types: "./dist/lib/mode.d.ts",
+      import: "./dist/lib/mode.js"
+    },
+    "./storage": {
+      types: "./dist/lib/store.d.ts",
+      import: "./dist/lib/store.js"
+    }
+  },
+  files: [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    "LICENSE"
+  ],
+  scripts: {
+    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
+    typecheck: "tsc --noEmit",
+    test: "bun test",
+    "test:boundary": "bun run scripts/no-private-cloud-boundary.mjs",
+    prepare: "test -d dist || bun run build",
+    "dev:cli": "bun run src/cli/index.ts",
+    "dev:daemon": "bun run src/daemon/index.ts",
+    prepublishOnly: "bun run build && bun run test:boundary"
+  },
+  keywords: [
+    "loops",
+    "scheduler",
+    "daemon",
+    "agents",
+    "claude",
+    "cursor",
+    "codewith",
+    "opencode",
+    "cli"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/hasna/loops.git"
+  },
+  homepage: "https://github.com/hasna/loops#readme",
+  bugs: {
+    url: "https://github.com/hasna/loops/issues"
+  },
+  author: "Hasna <andrei@hasna.com>",
+  license: "Apache-2.0",
+  engines: {
+    bun: ">=1.0.0"
+  },
+  dependencies: {
+    "@hasna/events": "^0.1.9",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openrouter/ai-sdk-provider": "2.9.1",
+    ai: "6.0.204",
+    commander: "^13.1.0",
+    zod: "4.4.3"
+  },
+  optionalDependencies: {
+    "@hasna/machines": "0.0.49"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    typescript: "^5.7.3"
+  },
+  publishConfig: {
+    registry: "https://registry.npmjs.org",
+    access: "public"
+  }
+};
+
+// src/lib/version.ts
+function packageVersion() {
+  if (typeof package_default.version !== "string" || package_default.version.trim() === "")
+    throw new Error("package.json version is missing");
+  return package_default.version;
+}
+
+// src/lib/mode.ts
+var LOOP_DEPLOYMENT_MODES = ["local", "self_hosted", "cloud"];
+var MODE_ENV_KEYS = ["LOOPS_MODE", "HASNA_LOOPS_MODE"];
+var API_URL_ENV_KEYS = ["LOOPS_API_URL", "HASNA_LOOPS_API_URL"];
+var CLOUD_API_URL_ENV_KEYS = ["LOOPS_CLOUD_API_URL", "HASNA_LOOPS_CLOUD_API_URL"];
+var DATABASE_URL_ENV_KEYS = ["LOOPS_DATABASE_URL", "HASNA_LOOPS_DATABASE_URL"];
+var API_TOKEN_ENV_KEYS = ["LOOPS_API_TOKEN", "HASNA_LOOPS_API_TOKEN"];
+var CLOUD_TOKEN_ENV_KEYS = ["LOOPS_CLOUD_TOKEN", "HASNA_LOOPS_CLOUD_TOKEN"];
+var TOKEN_ENV_KEYS = [...API_TOKEN_ENV_KEYS, ...CLOUD_TOKEN_ENV_KEYS];
+function envValue(env, keys) {
+  for (const key of keys) {
+    const value = env[key]?.trim();
+    if (value)
+      return { key, value };
+  }
+  return;
+}
+function normalizeLoopDeploymentMode(value) {
+  const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+  if (normalized === "local")
+    return "local";
+  if (normalized === "self_hosted" || normalized === "selfhosted")
+    return "self_hosted";
+  if (normalized === "cloud" || normalized === "saas")
+    return "cloud";
+  throw new Error(`unsupported OpenLoops deployment mode "${value}"; expected local, self_hosted, or cloud`);
+}
+function resolveLoopDeploymentMode(env = process.env) {
+  const explicitMode = envValue(env, MODE_ENV_KEYS);
+  if (explicitMode) {
+    return {
+      deploymentMode: normalizeLoopDeploymentMode(explicitMode.value),
+      source: explicitMode.key
+    };
+  }
+  const cloudApiUrl = envValue(env, CLOUD_API_URL_ENV_KEYS);
+  if (cloudApiUrl)
+    return { deploymentMode: "cloud", source: cloudApiUrl.key };
+  const apiUrl = envValue(env, API_URL_ENV_KEYS);
+  if (apiUrl)
+    return { deploymentMode: "self_hosted", source: apiUrl.key };
+  const databaseUrl = envValue(env, DATABASE_URL_ENV_KEYS);
+  if (databaseUrl)
+    return { deploymentMode: "self_hosted", source: databaseUrl.key };
+  return { deploymentMode: "local", source: "default" };
+}
+function loopControlPlaneConfig(env = process.env) {
+  return {
+    apiUrl: envValue(env, API_URL_ENV_KEYS)?.value,
+    cloudApiUrl: envValue(env, CLOUD_API_URL_ENV_KEYS)?.value,
+    databaseUrlPresent: Boolean(envValue(env, DATABASE_URL_ENV_KEYS)),
+    apiAuthTokenPresent: Boolean(envValue(env, API_TOKEN_ENV_KEYS)),
+    cloudAuthTokenPresent: Boolean(envValue(env, CLOUD_TOKEN_ENV_KEYS)),
+    authTokenPresent: Boolean(envValue(env, TOKEN_ENV_KEYS))
+  };
+}
+function sourceOfTruthForMode(mode) {
+  if (mode === "local")
+    return "local_sqlite";
+  if (mode === "self_hosted")
+    return "self_hosted_control_plane";
+  return "cloud_control_plane";
+}
+function displayControlPlaneUrl(value) {
+  if (!value)
+    return;
+  try {
+    const url = new URL(value);
+    const path = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/g, "");
+    return `${url.origin}${path}`;
+  } catch {
+    return "[invalid-url]";
+  }
+}
+function buildDeploymentStatus(opts = {}) {
+  const env = opts.env ?? process.env;
+  const active = resolveLoopDeploymentMode(env);
+  const deploymentMode = opts.perspective ?? active.deploymentMode;
+  const config = loopControlPlaneConfig(env);
+  const rawApiUrl = deploymentMode === "cloud" ? config.cloudApiUrl : config.apiUrl;
+  const apiUrl = displayControlPlaneUrl(rawApiUrl);
+  const controlPlaneKind = deploymentMode === "local" ? "none" : deploymentMode;
+  const deploymentAuthTokenPresent = deploymentMode === "cloud" ? config.cloudAuthTokenPresent : deploymentMode === "self_hosted" ? config.apiAuthTokenPresent : false;
+  const controlPlaneConfigured = deploymentMode === "local" ? false : deploymentMode === "self_hosted" ? Boolean(config.apiUrl || config.databaseUrlPresent) : Boolean(config.cloudApiUrl && deploymentAuthTokenPresent);
+  const warnings = [];
+  if (deploymentMode === "self_hosted" && !controlPlaneConfigured) {
+    warnings.push("self_hosted mode needs LOOPS_API_URL or LOOPS_DATABASE_URL before it can become authoritative");
+  }
+  if (deploymentMode === "cloud" && config.apiUrl && !config.cloudApiUrl) {
+    warnings.push("LOOPS_API_URL selects self_hosted; cloud mode uses LOOPS_CLOUD_API_URL");
+  }
+  if (deploymentMode === "cloud" && !config.cloudApiUrl) {
+    warnings.push("cloud mode is a public contract until LOOPS_CLOUD_API_URL is configured");
+  }
+  if (deploymentMode === "cloud" && config.cloudApiUrl && !deploymentAuthTokenPresent) {
+    warnings.push("cloud mode needs LOOPS_CLOUD_TOKEN or HASNA_LOOPS_CLOUD_TOKEN before it can become ready");
+  }
+  if (opts.perspective && opts.perspective !== active.deploymentMode) {
+    warnings.push(`active deployment mode is ${active.deploymentMode}; this is the ${opts.perspective} perspective`);
+  }
+  return {
+    packageVersion: packageVersion(),
+    deploymentMode,
+    activeDeploymentMode: active.deploymentMode,
+    active: deploymentMode === active.deploymentMode,
+    deploymentModeSource: active.source,
+    sourceOfTruth: sourceOfTruthForMode(deploymentMode),
+    localStore: {
+      role: deploymentMode === "local" ? "authoritative" : "cache_and_spool"
+    },
+    controlPlane: {
+      kind: controlPlaneKind,
+      configured: controlPlaneConfigured,
+      apiUrl,
+      databaseUrlPresent: config.databaseUrlPresent,
+      authTokenPresent: deploymentAuthTokenPresent
+    },
+    runner: {
+      required: deploymentMode !== "local",
+      role: deploymentMode === "local" ? "daemon" : "control_plane_worker"
+    },
+    warnings
+  };
+}
+function deploymentStatusLine(status) {
+  const configured = status.controlPlane.kind === "none" ? "none" : String(status.controlPlane.configured);
+  const active = status.active ? "active" : `active=${status.activeDeploymentMode}`;
+  return [
+    `deploymentMode=${status.deploymentMode}`,
+    active,
+    `source=${status.deploymentModeSource}`,
+    `truth=${status.sourceOfTruth}`,
+    `local=${status.localStore.role}`,
+    `control_plane=${configured}`
+  ].join(" ");
+}
 
 // src/mcp/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -7323,105 +7574,6 @@ async function tick(deps) {
   }
   return { claimed, completed, skipped, recovered, expired };
 }
-// package.json
-var package_default = {
-  name: "@hasna/loops",
-  version: "0.4.0",
-  description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
-  type: "module",
-  main: "dist/index.js",
-  types: "dist/index.d.ts",
-  bin: {
-    loops: "dist/cli/index.js",
-    "loops-daemon": "dist/daemon/index.js",
-    "loops-mcp": "dist/mcp/index.js"
-  },
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      import: "./dist/index.js"
-    },
-    "./sdk": {
-      types: "./dist/sdk/index.d.ts",
-      import: "./dist/sdk/index.js"
-    },
-    "./mcp": {
-      types: "./dist/mcp/index.d.ts",
-      import: "./dist/mcp/index.js"
-    },
-    "./storage": {
-      types: "./dist/lib/store.d.ts",
-      import: "./dist/lib/store.js"
-    }
-  },
-  files: [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "docs",
-    "LICENSE"
-  ],
-  scripts: {
-    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
-    "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
-    typecheck: "tsc --noEmit",
-    test: "bun test",
-    prepare: "test -d dist || bun run build",
-    "dev:cli": "bun run src/cli/index.ts",
-    "dev:daemon": "bun run src/daemon/index.ts",
-    prepublishOnly: "bun run build"
-  },
-  keywords: [
-    "loops",
-    "scheduler",
-    "daemon",
-    "agents",
-    "claude",
-    "cursor",
-    "codewith",
-    "opencode",
-    "cli"
-  ],
-  repository: {
-    type: "git",
-    url: "git+https://github.com/hasna/loops.git"
-  },
-  homepage: "https://github.com/hasna/loops#readme",
-  bugs: {
-    url: "https://github.com/hasna/loops/issues"
-  },
-  author: "Hasna <andrei@hasna.com>",
-  license: "Apache-2.0",
-  engines: {
-    bun: ">=1.0.0"
-  },
-  dependencies: {
-    "@hasna/events": "^0.1.9",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openrouter/ai-sdk-provider": "2.9.1",
-    ai: "6.0.204",
-    commander: "^13.1.0",
-    zod: "4.4.3"
-  },
-  optionalDependencies: {
-    "@hasna/machines": "0.0.49"
-  },
-  devDependencies: {
-    "@types/bun": "latest",
-    typescript: "^5.7.3"
-  },
-  publishConfig: {
-    registry: "https://registry.npmjs.org",
-    access: "public"
-  }
-};
-
-// src/lib/version.ts
-function packageVersion() {
-  if (typeof package_default.version !== "string" || package_default.version.trim() === "")
-    throw new Error("package.json version is missing");
-  return package_default.version;
-}
 
 // src/mcp/index.ts
 var LOOP_STATUSES = ["active", "paused", "stopped", "expired"];
@@ -8141,15 +8293,15 @@ function openAutomationsRuntimeBinding(overrides = {}) {
     failCommand: "automations queue fail",
     eventHandoff: {
       envelopeCommand: "automations webhooks event",
-      handlerCommand: "loops events handle generic",
-      pipeExample: "automations --json webhooks event <route> --body-json '<json>' | loops --json events handle generic",
+      handlerCommand: "loops routes create generic",
+      pipeExample: "automations --json webhooks event <route> --body-json '<json>' | loops --json routes create generic",
       boundary: "Use only for explicit event-envelope workflow handoff. OpenAutomations still owns deterministic automation materialization and queue state; OpenLoops owns workflow invocation."
     },
     requiredEnvironment: ["HASNA_AUTOMATIONS_DIR"],
     guarantees: [
       "OpenAutomations owns automation specs, run materialization, queue state, DLQ, replay, idempotency, and approvals.",
       "OpenLoops may execute claimed actions through explicit command or SDK handoff only.",
-      "OpenLoops may consume exported event envelopes only through explicit events handle commands.",
+      "OpenLoops may consume exported event envelopes only through explicit routes create commands.",
       "Workers must complete or fail actions by action id and runner id so OpenAutomations can enforce queue leases."
     ],
     nonGoals: [
@@ -9955,6 +10107,7 @@ function renderLoopTemplate(id, values, opts = {}) {
 }
 // src/lib/hygiene.ts
 import { basename as basename4 } from "path";
+import { homedir as homedir4 } from "os";
 var PROVIDER_TOKENS = new Set([
   "codewith",
   "claude",
@@ -9969,11 +10122,14 @@ var PROVIDER_TOKENS = new Set([
 var REPO_GENERIC_TOKENS = new Set(["repo", "repoops"]);
 var CADENCE_SUFFIX_TOKENS = new Set(["hourly", "daily", "weekly", "monthly"]);
 var CADENCE_SUFFIX_PATTERN = /^(?:every-?)?\d+(?:s|m|h|d|w)$/;
+function userHome() {
+  return process.env.HOME || homedir4();
+}
 function slugify(value) {
   return value.normalize("NFKD").replace(/[^\w\s.-]/g, "-").replace(/[_\s.:/]+/g, "-").replace(/[^a-zA-Z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
 }
 function repoSlugFromCwd(cwd) {
-  if (!cwd || cwd === process.env.HOME || cwd === "/home/hasna")
+  if (!cwd || cwd === userHome())
     return "";
   if (cwd.includes("/.hasna/loops/"))
     return "";
@@ -10156,7 +10312,7 @@ function commandText(loop) {
   return [loop.target.command, ...loop.target.args ?? []].join(" ");
 }
 function scriptNeedles(scriptsDir) {
-  const home = process.env.HOME ?? "/home/hasna";
+  const home = userHome();
   const normalized = scriptsDir.replace(/\/+$/g, "");
   const values = [
     normalized,
@@ -10174,7 +10330,7 @@ function scriptNeedles(scriptsDir) {
   return [...new Set(values)];
 }
 function buildScriptInventoryReport(store, opts = {}) {
-  const scriptsDir = opts.scriptsDir ?? `${process.env.HOME ?? "/home/hasna"}/.hasna/loops/scripts`;
+  const scriptsDir = opts.scriptsDir ?? `${userHome()}/.hasna/loops/scripts`;
   const needles = scriptNeedles(scriptsDir);
   const loops2 = managedLoops(store, { includeInactive: opts.includeInactive, includeStopped: true, limit: opts.limit });
   const scriptBacked = loops2.map((loop) => {
@@ -10210,6 +10366,7 @@ export {
   runDoctor,
   rollupSummary,
   resolveLoopMachine,
+  resolveLoopDeploymentMode,
   resolveGoalModel,
   renderTodosTaskWorkerVerifierWorkflow,
   renderLoopTemplate,
@@ -10222,8 +10379,10 @@ export {
   parseDuration,
   parseCron,
   openAutomationsRuntimeBinding,
+  normalizeLoopDeploymentMode,
   nextCronRun,
   loops,
+  loopControlPlaneConfig,
   listToolsForCli,
   listOpenMachines,
   listLoopTemplates,
@@ -10235,6 +10394,7 @@ export {
   executeTarget,
   executeLoopTarget,
   executeLoop,
+  deploymentStatusLine,
   createLoopsMcpServer,
   computeNextAfter,
   classifyRunFailure,
@@ -10242,12 +10402,14 @@ export {
   buildNameHygieneReport,
   buildHealthReport,
   buildDuplicateOverlapReport,
+  buildDeploymentStatus,
   ValidationError,
   TODOS_TASK_WORKER_VERIFIER_TEMPLATE_ID,
   Store,
   LoopsClient,
   LoopNotFoundError,
   LoopArchivedError,
+  LOOP_DEPLOYMENT_MODES,
   LOOPS_MCP_TOOLS,
   EVENT_WORKER_VERIFIER_TEMPLATE_ID,
   CodedError,

package/dist/lib/mode.d.ts

@@ -0,0 +1,48 @@
+export declare const LOOP_DEPLOYMENT_MODES: readonly ["local", "self_hosted", "cloud"];
+export type LoopDeploymentMode = (typeof LOOP_DEPLOYMENT_MODES)[number];
+export type LoopSourceOfTruth = "local_sqlite" | "self_hosted_control_plane" | "cloud_control_plane";
+export interface LoopModeResolution {
+    deploymentMode: LoopDeploymentMode;
+    source: string;
+}
+export interface LoopControlPlaneConfig {
+    apiUrl?: string;
+    cloudApiUrl?: string;
+    databaseUrlPresent: boolean;
+    apiAuthTokenPresent: boolean;
+    cloudAuthTokenPresent: boolean;
+    authTokenPresent: boolean;
+}
+export interface LoopDeploymentStatus {
+    packageVersion: string;
+    deploymentMode: LoopDeploymentMode;
+    activeDeploymentMode: LoopDeploymentMode;
+    active: boolean;
+    deploymentModeSource: string;
+    sourceOfTruth: LoopSourceOfTruth;
+    localStore: {
+        role: "authoritative" | "cache_and_spool";
+    };
+    controlPlane: {
+        kind: "none" | "self_hosted" | "cloud";
+        configured: boolean;
+        apiUrl?: string;
+        databaseUrlPresent: boolean;
+        authTokenPresent: boolean;
+    };
+    runner: {
+        required: boolean;
+        role: "daemon" | "control_plane_worker";
+    };
+    warnings: string[];
+}
+type Env = Record<string, string | undefined>;
+export declare function normalizeLoopDeploymentMode(value: string): LoopDeploymentMode;
+export declare function resolveLoopDeploymentMode(env?: Env): LoopModeResolution;
+export declare function loopControlPlaneConfig(env?: Env): LoopControlPlaneConfig;
+export declare function buildDeploymentStatus(opts?: {
+    env?: Env;
+    perspective?: LoopDeploymentMode;
+}): LoopDeploymentStatus;
+export declare function deploymentStatusLine(status: LoopDeploymentStatus): string;
+export {};