@oracle-agent/oracle 0.13.0 → 0.14.0

package/src/cli/messaging-platforms.mjs

@@ -0,0 +1,217 @@
+// Hermes messaging platforms Oracle can configure.
+// Values stay lowercase. Secrets stay in Hermes profile .env, never printed.
+
+export const MESSAGING_PLATFORMS = Object.freeze([
+  {
+    key: "telegram",
+    name: "telegram",
+    hermes: ["gateway", "setup"],
+    required: ["TELEGRAM_BOT_TOKEN"],
+    optional: ["TELEGRAM_ALLOWED_USERS", "TELEGRAM_PROXY"],
+    note: "dms · groups · topics",
+  },
+  {
+    key: "discord",
+    name: "discord",
+    hermes: ["gateway", "setup"],
+    required: ["DISCORD_BOT_TOKEN"],
+    optional: ["DISCORD_ALLOWED_USERS"],
+    note: "dms · channels · threads",
+  },
+  {
+    key: "slack",
+    name: "slack",
+    hermes: ["gateway", "setup"],
+    required: ["SLACK_BOT_TOKEN", "SLACK_APP_TOKEN"],
+    optional: ["SLACK_ALLOWED_USERS"],
+    note: "socket mode",
+  },
+  {
+    key: "whatsapp",
+    name: "whatsapp",
+    hermes: ["whatsapp"],
+    required: [],
+    optional: ["WHATSAPP_ALLOWED_USERS", "WHATSAPP_MODE"],
+    note: "qr bridge",
+  },
+  {
+    key: "whatsapp-cloud",
+    name: "whatsapp cloud",
+    hermes: ["whatsapp-cloud"],
+    required: [],
+    optional: [],
+    note: "business cloud api",
+  },
+  {
+    key: "signal",
+    name: "signal",
+    hermes: ["gateway", "setup"],
+    required: ["SIGNAL_HTTP_URL", "SIGNAL_ACCOUNT"],
+    optional: ["SIGNAL_ALLOWED_USERS"],
+    note: "signal-cli rest bridge",
+  },
+  {
+    key: "matrix",
+    name: "matrix",
+    hermes: ["gateway", "setup"],
+    required: ["MATRIX_HOMESERVER", "MATRIX_ACCESS_TOKEN", "MATRIX_USER_ID"],
+    optional: ["MATRIX_ALLOWED_USERS"],
+    note: "rooms · dms",
+  },
+  {
+    key: "mattermost",
+    name: "mattermost",
+    hermes: ["gateway", "setup"],
+    required: ["MATTERMOST_URL", "MATTERMOST_TOKEN"],
+    optional: ["MATTERMOST_ALLOWED_USERS"],
+    note: "channels · dms",
+  },
+  {
+    key: "email",
+    name: "email",
+    hermes: ["gateway", "setup"],
+    required: ["EMAIL_ADDRESS", "EMAIL_PASSWORD", "EMAIL_IMAP_HOST", "EMAIL_SMTP_HOST"],
+    optional: [],
+    note: "imap/smtp mailbox",
+  },
+  {
+    key: "bluebubbles",
+    name: "bluebubbles",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "imessage via bluebubbles",
+  },
+  {
+    key: "photon",
+    name: "photon",
+    hermes: ["photon"],
+    required: ["PHOTON_PROJECT_ID", "PHOTON_PROJECT_SECRET"],
+    optional: ["PHOTON_ALLOWED_USERS", "PHOTON_HOME_CHANNEL"],
+    note: "imessage via spectrum (no mac)",
+  },
+  {
+    key: "homeassistant",
+    name: "homeassistant",
+    hermes: ["gateway", "setup"],
+    required: ["HASS_URL", "HASS_TOKEN"],
+    optional: [],
+    note: "smart home",
+  },
+  {
+    key: "webhook",
+    name: "webhook",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "http ingress",
+  },
+  {
+    key: "api-server",
+    name: "api server",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "local http api",
+  },
+  {
+    key: "dingtalk",
+    name: "dingtalk",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "dingtalk bot",
+  },
+  {
+    key: "feishu",
+    name: "feishu",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "feishu / lark",
+  },
+  {
+    key: "wecom",
+    name: "wecom",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "wecom",
+  },
+  {
+    key: "weixin",
+    name: "weixin",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "weixin",
+  },
+  {
+    key: "qqbot",
+    name: "qqbot",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "qq bot",
+  },
+]);
+
+function normalize(raw) {
+  return String(raw || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\/+/, "")
+    .replace(/\s+/g, "-");
+}
+
+export function listMessagingPlatforms() {
+  return MESSAGING_PLATFORMS.slice();
+}
+
+export function findMessagingPlatform(query) {
+  const q = normalize(query);
+  if (!q) return null;
+  for (const p of MESSAGING_PLATFORMS) {
+    if (p.key === q) return p;
+    if (normalize(p.name) === q) return p;
+  }
+  return null;
+}
+
+export function renderSetupMenu({ profile = "oracle", statuses = {} } = {}) {
+  const lines = [
+    "oracle setup",
+    "",
+    "one oracle. many models. every connected channel.",
+    `profile: ${profile}`,
+    "",
+    "messaging platforms:",
+    "",
+  ];
+  for (const p of MESSAGING_PLATFORMS) {
+    const st = statuses[p.key] || "unset";
+    lines.push(`  ${p.key.padEnd(16)} ${String(st).padEnd(8)}  ${p.note}`);
+  }
+  lines.push("");
+  lines.push("commands:");
+  lines.push("  oracle setup                 this menu");
+  lines.push("  oracle setup messaging       open hermes gateway setup");
+  lines.push("  oracle setup telegram        configure telegram bot token");
+  lines.push("  oracle setup discord         configure discord bot token");
+  lines.push("  oracle setup status          show configured platforms (no secrets)");
+  lines.push("  oracle setup gateway         start/status hermes gateway");
+  lines.push("  /setup                       same menu inside chat");
+  lines.push("");
+  lines.push("notes:");
+  lines.push("  tokens stay in the hermes profile .env on this machine");
+  lines.push("  oracle never prints bot tokens or app secrets");
+  lines.push("  after setup: hermes -p oracle gateway restart");
+  return lines.join("\n") + "\n";
+}
+
+export default {
+  MESSAGING_PLATFORMS,
+  listMessagingPlatforms,
+  findMessagingPlatform,
+  renderSetupMenu,
+};

package/src/cli/model-config.mjs

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { ensureDir, oracleConfigDir } from "./paths.mjs";
+
+const BACKENDS = new Set(["auto", "standalone", "hermes", "remote", "arch"]);
+const PROVIDERS = new Set([
+  "openrouter", "openai", "xai", "deepseek", "gemini", "custom",
+  "anthropic-oauth", "openai-codex", "xai-oauth",
+]);
+
+export function modelConfigPath() {
+  return path.join(oracleConfigDir(), "model.json");
+}
+
+function optionalString(value) {
+  const text = String(value || "").trim();
+  return text || undefined;
+}
+
+function normalize(config = {}) {
+  const backend = optionalString(config.backend)?.toLowerCase() || "auto";
+  const provider = optionalString(config.provider)?.toLowerCase();
+  const model = optionalString(config.model);
+  const baseUrl = optionalString(config.baseUrl)?.replace(/\/+$/, "");
+  const apiKeyEnv = optionalString(config.apiKeyEnv);
+  const contextLength = Number.parseInt(String(config.contextLength || ""), 10);
+  const reasoningEffort = optionalString(config.reasoningEffort);
+  const computeHost = optionalString(config.computeHost || config.remoteHost);
+  const computeUser = optionalString(config.computeUser || config.remoteUser);
+  const computePath = optionalString(config.computePath || config.remotePath);
+
+  if (!BACKENDS.has(backend)) throw new Error(`unsupported backend: ${backend}`);
+  if (process.env.ORACLE_PUBLIC_DESKTOP === "1" && ["remote", "arch"].includes(backend)) throw new Error("remote compute backends are disabled in the public desktop");
+  if (provider && !PROVIDERS.has(provider)) throw new Error(`unsupported provider: ${provider}`);
+  if (baseUrl && provider !== "custom") throw new Error("baseUrl is only supported for the custom provider");
+  if (apiKeyEnv && !/^[A-Z][A-Z0-9_]*$/.test(apiKeyEnv)) throw new Error("api key env must be an uppercase environment variable name");
+  if (provider === "custom" && !baseUrl) throw new Error("custom provider requires baseUrl");
+  if (backend === "standalone" && !model) throw new Error("standalone backend requires a model");
+  if (backend === "remote" && !computeHost) throw new Error("remote backend requires computeHost");
+
+  return {
+    backend,
+    ...(provider ? { provider } : {}),
+    ...(model ? { model } : {}),
+    ...(baseUrl ? { baseUrl } : {}),
+    ...(apiKeyEnv ? { apiKeyEnv } : {}),
+    ...(Number.isFinite(contextLength) && contextLength > 0 ? { contextLength } : {}),
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+    ...(computeHost ? { computeHost } : {}),
+    ...(computeUser ? { computeUser } : {}),
+    ...(computePath ? { computePath } : {}),
+  };
+}
+
+export function readModelConfig() {
+  const file = modelConfigPath();
+  if (!fs.existsSync(file)) return null;
+  try {
+    return normalize(JSON.parse(fs.readFileSync(file, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+export function writeModelConfig(config) {
+  const normalized = normalize(config);
+  const file = modelConfigPath();
+  ensureDir(path.dirname(file));
+  if (process.platform !== "win32") fs.chmodSync(path.dirname(file), 0o700);
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temp, file);
+  if (process.platform !== "win32") fs.chmodSync(file, 0o600);
+  return normalized;
+}
+
+export default { modelConfigPath, readModelConfig, writeModelConfig };

package/src/cli/operator-dispatch.mjs

@@ -0,0 +1,257 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(HERE, "../..");
+
+export const OPERATOR_BIN_NAMES = Object.freeze([
+  "oracle-vault",
+  "oracle-credential",
+  "oracle-signer",
+  "oracle-runner",
+  "oracle-agentic-init",
+  "oracle-agentic-doctor",
+  "oracle-control-mcp",
+  "oracle-operator-caps",
+]);
+
+export const SIGN_NOUNS = Object.freeze([
+  "vault",
+  "credential",
+  "signer",
+  "runner",
+  "sign",
+]);
+
+export const OPERATOR_NOT_INSTALLED_MESSAGE = `oracle: signing is unavailable in the public package.
+
+  The public 'oracle' package is prepare-only and never handles keys.
+  Owner-operated signing is private infrastructure and has no public npm install.
+  Review and sign prepared artifacts in your own wallet instead.
+
+  Nothing about your read/research/prepare setup is affected.
+`;
+
+export const SIGN_HINT =
+  "hint: run 'oracle sign init' to provision keys, or 'oracle sign doctor --json' for detail.";
+
+function whichOnPath(binName) {
+  const pathEnv = process.env.PATH || "";
+  const parts = pathEnv.split(path.delimiter).filter(Boolean);
+  const exts = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+  for (const dir of parts) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, binName + ext);
+      try {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+          return candidate;
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return null;
+}
+
+function binsFromDir(binDir) {
+  const bins = {};
+  for (const name of OPERATOR_BIN_NAMES) {
+    const candidates = [
+      path.join(binDir, name),
+      path.join(binDir, `${name}.mjs`),
+      path.join(binDir, `${name}.js`),
+    ];
+    for (const c of candidates) {
+      if (fs.existsSync(c) && fs.statSync(c).isFile()) {
+        bins[name] = c;
+        break;
+      }
+    }
+  }
+  return bins;
+}
+
+function findPackageRoot(entryPath) {
+  let dir = path.dirname(entryPath);
+  while (dir !== path.dirname(dir)) {
+    const pkgJson = path.join(dir, "package.json");
+    if (fs.existsSync(pkgJson)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf8"));
+        if (pkg.name === "@oracle-agent/operator") return { root: dir, pkg };
+      } catch {
+        // continue upward
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function tryResolvePackage(fromPaths) {
+  for (const from of fromPaths) {
+    try {
+      const req = createRequire(path.join(from, "package.json"));
+      let found;
+      try {
+        const pkgJson = req.resolve("@oracle-agent/operator/package.json");
+        found = {
+          root: path.dirname(pkgJson),
+          pkg: JSON.parse(fs.readFileSync(pkgJson, "utf8")),
+        };
+      } catch {
+        const entry = req.resolve("@oracle-agent/operator");
+        found = findPackageRoot(entry);
+      }
+      if (!found) continue;
+      const { root, pkg } = found;
+      const binField = pkg.bin || {};
+      const bins = {};
+      for (const [name, rel] of Object.entries(binField)) {
+        bins[name] = path.resolve(root, rel);
+      }
+      const extra = binsFromDir(path.join(root, "bin"));
+      for (const [k, v] of Object.entries(extra)) {
+        if (!bins[k]) bins[k] = v;
+      }
+      return {
+        ok: true,
+        binDir: path.join(root, "bin"),
+        version: pkg.version || "unknown",
+        bins,
+        source: `require:${from}`,
+      };
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}
+
+function tryCapsOnPath() {
+  const capsBin = whichOnPath("oracle-operator-caps");
+  if (!capsBin) return null;
+  const r = spawnSync(capsBin, [], {
+    encoding: "utf8",
+    timeout: 5000,
+    env: process.env,
+  });
+  if (r.status !== 0 || !r.stdout) return null;
+  try {
+    const report = JSON.parse(r.stdout);
+    if (!report || typeof report !== "object" || !report.bins) return null;
+    return {
+      ok: true,
+      binDir: path.dirname(Object.values(report.bins)[0] || capsBin),
+      version: report.version || "unknown",
+      bins: report.bins,
+      source: "caps-path",
+      controlMcp: report.controlMcp,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function tryPathProbe() {
+  const bins = {};
+  for (const name of OPERATOR_BIN_NAMES) {
+    const hit = whichOnPath(name);
+    if (hit) bins[name] = hit;
+  }
+  if (!Object.keys(bins).length) return null;
+  return {
+    ok: true,
+    binDir: path.dirname(Object.values(bins)[0]),
+    version: "unknown",
+    bins,
+    source: "path-probe",
+  };
+}
+
+export function resolveOperator() {
+  if (process.env.ORACLE_PUBLIC_DESKTOP === "1") return { ok: false, source: "public-desktop" };
+  const envDir = process.env.ORACLE_OPERATOR_BIN_DIR;
+  if (envDir) {
+    const abs = path.resolve(envDir);
+    if (!fs.existsSync(abs)) return { ok: false };
+    const bins = binsFromDir(abs);
+    if (!Object.keys(bins).length) return { ok: false };
+    let version = "unknown";
+    const pkgCandidate = path.resolve(abs, "../package.json");
+    if (fs.existsSync(pkgCandidate)) {
+      try {
+        version = JSON.parse(fs.readFileSync(pkgCandidate, "utf8")).version || version;
+      } catch {
+        // ignore
+      }
+    }
+    return { ok: true, binDir: abs, version, bins, source: "env:ORACLE_OPERATOR_BIN_DIR" };
+  }
+
+  const fromPkg =
+    tryResolvePackage([process.cwd(), PACKAGE_ROOT]) ||
+    tryCapsOnPath() ||
+    tryPathProbe();
+  return fromPkg || { ok: false };
+}
+
+export function printOperatorNotInstalled(stream = process.stderr) {
+  stream.write(OPERATOR_NOT_INSTALLED_MESSAGE);
+  if (!OPERATOR_NOT_INSTALLED_MESSAGE.endsWith("\n")) stream.write("\n");
+}
+
+export function dispatchOperator(binName, argv = [], opts = {}) {
+  const resolved = resolveOperator();
+  if (!resolved.ok) {
+    printOperatorNotInstalled(opts.stderr || process.stderr);
+    return 3;
+  }
+  const binPath = resolved.bins[binName];
+  if (!binPath) {
+    const err = opts.stderr || process.stderr;
+    err.write(`oracle: operator bin '${binName}' not found in resolved operator (${resolved.source})\n`);
+    return 3;
+  }
+
+  const stdio = opts.stdio || "inherit";
+  const isJs = /\.(mjs|cjs|js)$/.test(binPath);
+  const command = isJs ? process.execPath : binPath;
+  const args = isJs ? [binPath, ...argv] : [...argv];
+  const r = spawnSync(command, args, {
+    stdio,
+    env: opts.env || process.env,
+    cwd: opts.cwd || process.cwd(),
+    encoding: stdio === "pipe" ? "utf8" : undefined,
+  });
+
+  if (r.error) {
+    const err = opts.stderr || process.stderr;
+    err.write(`oracle: failed to spawn ${binName}: ${r.error.message}\n`);
+    return 1;
+  }
+
+  const code = typeof r.status === "number" ? r.status : 1;
+  if (code !== 0 && opts.appendHintOnError) {
+    const err = opts.stderr || process.stderr;
+    err.write(SIGN_HINT + "\n");
+  }
+  if (stdio === "pipe") {
+    return { code, stdout: r.stdout || "", stderr: r.stderr || "" };
+  }
+  return code;
+}
+
+export default {
+  resolveOperator,
+  dispatchOperator,
+  printOperatorNotInstalled,
+  OPERATOR_NOT_INSTALLED_MESSAGE,
+  SIGN_HINT,
+  SIGN_NOUNS,
+  OPERATOR_BIN_NAMES,
+};