@oracle-agent/oracle 0.13.0 → 0.14.0

package/src/cli/chain-state.mjs

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findWorkingChain } from "./chain-catalog.mjs";
+import { homeDir, ensureDir, oracleConfigDir } from "./paths.mjs";
+
+export function activeChainPath() {
+  return path.join(oracleConfigDir(), "active-chain.json");
+}
+
+export function readActiveChain() {
+  const p = activeChainPath();
+  if (!fs.existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+    if (!raw || typeof raw !== "object" || !raw.key) return null;
+    const chain = findWorkingChain(raw.key);
+    if (!chain) return null;
+    return {
+      key: chain.key,
+      chainId: chain.chainId,
+      name: chain.name,
+      agent: chain.agent,
+      selectedAt: raw.selectedAt || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeActiveChain(query) {
+  const chain = findWorkingChain(query);
+  if (!chain) {
+    const err = new Error(`unknown chain '${query}'`);
+    err.code = "UNKNOWN_CHAIN";
+    throw err;
+  }
+  ensureDir(oracleConfigDir());
+  const payload = {
+    key: chain.key,
+    chainId: chain.chainId,
+    name: chain.name,
+    agent: chain.agent,
+    selectedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(activeChainPath(), JSON.stringify(payload, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  return payload;
+}
+
+export function clearActiveChain() {
+  const p = activeChainPath();
+  if (fs.existsSync(p)) fs.unlinkSync(p);
+  return true;
+}
+
+export function activeChainEnv(extra = {}) {
+  const active = readActiveChain();
+  const env = { ...process.env, ...extra };
+  if (!active) return env;
+  env.ORACLE_ACTIVE_CHAIN = active.key;
+  env.ORACLE_ACTIVE_CHAIN_ID = String(active.chainId);
+  env.ORACLE_ACTIVE_AGENT = active.agent || "oracle";
+  return env;
+}
+
+export default {
+  activeChainPath,
+  readActiveChain,
+  writeActiveChain,
+  clearActiveChain,
+  activeChainEnv,
+  homeDir,
+};

package/src/cli/commands/auth.mjs

@@ -0,0 +1,193 @@
+import { writeModelConfig } from "../model-config.mjs";
+import {
+  getOAuthStore,
+  loginOAuth,
+  oauthProviderConfig,
+  oauthProviderId,
+} from "../../auth/oauth.mjs";
+
+const API_PROVIDERS = Object.freeze({
+  openrouter: { model: "openrouter/auto" },
+  openai: { model: "gpt-4.1-mini" },
+  xai: { model: "grok-4.5" },
+  deepseek: { model: "deepseek-chat" },
+  gemini: { model: "gemini-2.5-flash" },
+  custom: { model: "" },
+});
+
+function option(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 && args[index + 1] ? args[index + 1] : "";
+}
+
+async function readAllStdin() {
+  let value = "";
+  for await (const chunk of process.stdin) value += chunk;
+  return value.trim();
+}
+
+function readHidden(prompt = "API key: ") {
+  if (!process.stdin.isTTY || !process.stdin.setRawMode) {
+    throw new Error("non-interactive API-key input requires --stdin");
+  }
+  process.stdout.write(prompt);
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const cleanup = () => {
+      process.stdin.off("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+    };
+    const onData = (chunk) => {
+      const text = String(chunk);
+      for (const character of text) {
+        if (character === "\r" || character === "\n") {
+          cleanup();
+          resolve(value.trim());
+          return;
+        }
+        if (character === "\u0003") {
+          cleanup();
+          reject(new Error("cancelled"));
+          return;
+        }
+        if (character === "\u007f" || character === "\b") value = value.slice(0, -1);
+        else value += character;
+      }
+    };
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+
+function selection(provider, model, { baseUrl = "" } = {}) {
+  if (!model) throw new Error(`${provider} provider requires --model`);
+  const config = { backend: "standalone", provider, model };
+  if (provider === "custom") {
+    if (!baseUrl) throw new Error("custom provider requires --base-url");
+    config.baseUrl = baseUrl;
+  }
+  return config;
+}
+
+function saveSelection(provider, model, options = {}) {
+  return writeModelConfig(selection(provider, model, options));
+}
+
+function printStatus(status) {
+  process.stdout.write(`storage: ${status.storage}\n`);
+  const oauth = Object.entries(status.providers || {});
+  const apiKeys = Object.entries(status.apiKeys || {});
+  if (!oauth.length && !apiKeys.length) {
+    process.stdout.write("no credentials configured\n");
+    return;
+  }
+  for (const [provider, value] of oauth) {
+    const expiry = value.expiresAt ? new Date(value.expiresAt).toISOString() : "unknown";
+    process.stdout.write(`${provider}: ${value.loggedIn ? "logged in" : "missing"}, expires ${expiry}\n`);
+  }
+  for (const [provider, value] of apiKeys) {
+    process.stdout.write(`${provider}: API key ${value.configured ? "configured" : "missing"}\n`);
+  }
+}
+
+function usage() {
+  return [
+    "oracle auth, configure OAuth or API-key authentication",
+    "",
+    "  oracle auth login claude|codex|grok [--model MODEL] [--no-browser]",
+    "  oracle auth api-key PROVIDER [--model MODEL] [--base-url URL]",
+    "  printf '%s\\n' \"$KEY\" | oracle auth api-key PROVIDER --stdin",
+    "  oracle auth status [--json]",
+    "  oracle auth logout PROVIDER",
+    "",
+    "OAuth and API keys are additive. Select any compatible model with oracle model --provider PROVIDER --model MODEL.",
+  ].join("\n");
+}
+
+export default {
+  name: "auth",
+  summary: "login with Claude, Codex, or Grok OAuth; store provider API keys",
+  group: "read",
+  usage: usage(),
+  async run(ctx) {
+    const args = [...ctx.argv];
+    const action = args.shift() || "status";
+    const store = getOAuthStore();
+    try {
+      if (action === "status") {
+        const status = store.status();
+        if (args.includes("--json")) process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+        else printStatus(status);
+        return 0;
+      }
+
+      if (action === "login") {
+        const requested = args.find((value) => !value.startsWith("-"));
+        if (!requested) throw new Error("usage: oracle auth login claude|codex|grok");
+        const config = oauthProviderConfig(requested);
+        const model = option(args, "--model") || config.model;
+        selection(config.id, model);
+        const credential = await loginOAuth(config.id, {
+          openFn: args.includes("--no-browser") ? () => false : undefined,
+        });
+        await store.withLock(async () => {
+          const previous = store.get(config.id);
+          store.set(config.id, credential);
+          try {
+            saveSelection(config.id, model);
+          } catch (error) {
+            if (previous) store.set(config.id, previous);
+            else store.remove(config.id);
+            throw error;
+          }
+        });
+        process.stdout.write(`${config.id}: logged in, stored in ${store.storage}\n`);
+        return 0;
+      }
+
+      if (action === "api-key") {
+        const provider = String(args.find((value) => !value.startsWith("-")) || "").trim().toLowerCase();
+        if (!provider) throw new Error("usage: oracle auth api-key PROVIDER [--stdin]");
+        if (!Object.hasOwn(API_PROVIDERS, provider)) throw new Error(`unsupported API-key provider: ${provider}`);
+        const model = option(args, "--model") || API_PROVIDERS[provider].model;
+        const baseUrl = option(args, "--base-url");
+        selection(provider, model, { baseUrl });
+        const apiKey = args.includes("--stdin") ? await readAllStdin() : await readHidden();
+        await store.withLock(async () => {
+          const previous = store.getApiKey(provider);
+          store.setApiKey(provider, apiKey);
+          try {
+            saveSelection(provider, model, { baseUrl });
+          } catch (error) {
+            if (previous) store.setApiKey(provider, previous);
+            else store.removeApiKey(provider);
+            throw error;
+          }
+        });
+        process.stdout.write(`${provider}: API key configured in ${store.storage}\n`);
+        return 0;
+      }
+
+      if (action === "logout") {
+        const requested = String(args.find((value) => !value.startsWith("-")) || "").trim().toLowerCase();
+        if (!requested) throw new Error("usage: oracle auth logout PROVIDER");
+        let removedOAuth = false;
+        try {
+          removedOAuth = store.remove(oauthProviderId(requested));
+        } catch {}
+        const removedApiKey = store.removeApiKey(requested);
+        if (!removedOAuth && !removedApiKey) throw new Error(`${requested}: no local credential found`);
+        process.stdout.write(`${requested}: local credential removed\n`);
+        return 0;
+      }
+
+      throw new Error(`unknown auth action: ${action}`);
+    } catch (error) {
+      process.stderr.write(`oracle auth: ${error.message}\n`);
+      return 1;
+    }
+  },
+};

package/src/cli/commands/bootstrap.mjs

@@ -0,0 +1,87 @@
+import {
+  HERMES_PYPI,
+  installManagedHermes,
+  runtimeStatus,
+  runtimeVenvDir,
+} from "../runtime.mjs";
+
+function usage() {
+  return [
+    "oracle bootstrap - optionally install an isolated Hermes compatibility runtime",
+    "",
+    "  oracle bootstrap            install into ~/.config/oracle/runtime/venv",
+    "  oracle bootstrap --upgrade  upgrade the managed runtime",
+    "  oracle bootstrap --status   show what runtime oracle would use",
+    "  oracle bootstrap --json     machine-readable status",
+    "",
+    "notes:",
+    "  a hermes on PATH always wins; bootstrap never touches system python",
+    "  read/prepare commands (chain, scan, route, data) never need this",
+  ].join("\n");
+}
+
+export default {
+  name: "bootstrap",
+  summary: "optionally install a Hermes compatibility runtime",
+  group: "read",
+  usage: usage(),
+  async run(ctx) {
+    const args = ctx.argv;
+    if (args.includes("-h") || args.includes("--help")) {
+      process.stdout.write(usage() + "\n");
+      return 0;
+    }
+
+    const json = args.includes("--json");
+    const status = runtimeStatus();
+
+    if (args.includes("--status") || json) {
+      if (json) {
+        process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+        return 0;
+      }
+      process.stdout.write(
+        [
+          `hermes:        ${status.hermes.ok ? `${status.hermes.bin} (${status.hermes.source})` : "not installed"}`,
+          `managed venv:  ${status.managedVenv}`,
+          `managed built: ${status.managedInstalled ? "yes" : "no"}`,
+          `host python:   ${status.hostPython ? `${status.hostPython.bin} (${status.hostPython.version})` : "none supported (need 3.11-3.13)"}`,
+          `uv:            ${status.uv || "not installed (oracle will install it locally)"}`,
+          "",
+        ].join("\n"),
+      );
+      return 0;
+    }
+
+    const upgrade = args.includes("--upgrade");
+
+    if (status.hermes.ok && status.hermes.source === "path" && !upgrade) {
+      process.stdout.write(
+        `hermes already on PATH: ${status.hermes.bin}\nnothing to do. run: oracle\n`,
+      );
+      return 0;
+    }
+
+    process.stdout.write(
+      `installing ${HERMES_PYPI} into ${runtimeVenvDir()}\n` +
+        (status.hostPython
+          ? `using python ${status.hostPython.version} (${status.hostPython.bin})\n`
+          : "provisioning an isolated python 3.13 with uv\n") +
+        "this takes a few minutes on first run\n\n",
+    );
+
+    const r = installManagedHermes({ upgrade });
+    if (!r.ok) {
+      process.stderr.write(`oracle bootstrap failed: ${r.reason}\n`);
+      if (r.stderr) process.stderr.write(`${r.stderr}\n`);
+      return 1;
+    }
+
+    process.stdout.write(
+      r.reused
+        ? `runtime already present: ${r.bin}\n`
+        : `\nruntime ready: ${r.bin}\nrun: oracle\n`,
+    );
+    return 0;
+  },
+};

package/src/cli/commands/chain.mjs

@@ -0,0 +1,143 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import {
+  findWorkingChain,
+  listWorkingChains,
+  renderChainList,
+} from "../chain-catalog.mjs";
+import {
+  clearActiveChain,
+  readActiveChain,
+  writeActiveChain,
+} from "../chain-state.mjs";
+
+function usage() {
+  return [
+    "oracle chain — pick the build/trade surface",
+    "",
+    "  oracle chain                 list working chains",
+    "  oracle chain list            same",
+    "  oracle chain show            show active chain",
+    "  oracle chain use <name>      select (hyperliquid, base, solana, ...)",
+    "  oracle chain clear           unset",
+    "  oracle chain --json          machine output",
+    "",
+    "chat:",
+    "  /chain",
+    "  /chain hyperliquid",
+    "  /chain show",
+  ].join("\n");
+}
+
+function printList(json) {
+  const active = readActiveChain();
+  if (json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          active,
+          chains: listWorkingChains(),
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return 0;
+  }
+  process.stdout.write(
+    renderChainList({ selectedKey: active?.key || null }),
+  );
+  return 0;
+}
+
+function printShow(json) {
+  const active = readActiveChain();
+  if (json) {
+    process.stdout.write(JSON.stringify({ active }, null, 2) + "\n");
+    return active ? 0 : 1;
+  }
+  if (!active) {
+    process.stdout.write("active: none\nrun: oracle chain use hyperliquid\n");
+    return 1;
+  }
+  process.stdout.write(
+    `active: ${active.key}  id=${active.chainId}  agent=${active.agent}\n`,
+  );
+  return 0;
+}
+
+function useChain(query, json) {
+  try {
+    const active = writeActiveChain(query);
+    if (json) {
+      process.stdout.write(JSON.stringify({ ok: true, active }, null, 2) + "\n");
+    } else {
+      process.stdout.write(
+        `selected ${active.key} (${active.chainId}) · agent ${active.agent}\n` +
+          `build/trade context pinned for this machine\n`,
+      );
+    }
+    return 0;
+  } catch (err) {
+    if (err?.code === "UNKNOWN_CHAIN") {
+      process.stderr.write(`oracle chain: unknown '${query}'\n`);
+      process.stderr.write("try: oracle chain list\n");
+      return 1;
+    }
+    throw err;
+  }
+}
+
+export default {
+  name: "chain",
+  summary: "list/select working chains (hyperliquid, base, solana, ...)",
+  group: "read",
+  usage: usage(),
+  async run(ctx) {
+    const args = [...ctx.argv];
+    const json = args.includes("--json");
+    const clean = args.filter((a) => a !== "--json");
+    const verb = (clean[0] || "list").toLowerCase();
+    const rest = clean.slice(1);
+
+    if (["-h", "--help", "help"].includes(verb)) {
+      process.stdout.write(usage() + "\n");
+      return 0;
+    }
+    if (["list", "ls"].includes(verb)) return printList(json);
+    if (["show", "status", "current"].includes(verb)) return printShow(json);
+    if (["clear", "unset", "none"].includes(verb)) {
+      clearActiveChain();
+      process.stdout.write(json ? "{\"ok\":true,\"active\":null}\n" : "active chain cleared\n");
+      return 0;
+    }
+    if (["use", "set", "select", "pick"].includes(verb)) {
+      const q = rest.join(" ").trim();
+      if (!q) {
+        process.stderr.write("usage: oracle chain use <name>\n");
+        return 1;
+      }
+      return useChain(q, json);
+    }
+
+    // bare token: oracle chain hyperliquid
+    if (findWorkingChain(verb)) return useChain(verb, json);
+
+    // interactive pick when tty and no args beyond list default already handled
+    if (!clean.length && process.stdin.isTTY) {
+      const chains = listWorkingChains();
+      process.stdout.write(renderChainList({ selectedKey: readActiveChain()?.key }));
+      const rl = readline.createInterface({ input, output });
+      try {
+        const answer = (await rl.question("chain> ")).trim();
+        if (!answer) return 0;
+        return useChain(answer, false);
+      } finally {
+        rl.close();
+      }
+    }
+
+    process.stderr.write(`oracle chain: unknown verb '${verb}'\n${usage()}\n`);
+    return 1;
+  },
+};