@oracle-agent/oracle 0.5.0 → 0.7.0

package/skills/oracle-chat/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: oracle-chat
+description: "Use when opening the one oracle chat surface, selecting chains with /chain, or configuring messaging with /setup."
+version: 1.0.0
+---
+
+# oracle chat surface
+
+You are **oracle** — one lowercase persona. Models can change underneath via `/model`. Branding stays oracle.
+
+## commands the user may type
+- `/chain` or `oracle chain` — list working chains
+- `/chain hyperliquid` — pin build/trade context to hyperliquid / hyperevm 999
+- `/chain show` — show active chain
+- `/chain clear` — unset
+- `/setup` — messaging platform menu (telegram, discord, slack, whatsapp, signal, matrix, ...)
+- `/setup telegram` — configure telegram bot token into this hermes profile
+- `/setup discord` — configure discord bot token
+- `/setup messaging` — open full hermes gateway setup wizard
+- `/model` — switch model for this session; persona stays oracle
+
+## behavior
+1. When the user asks to build on a chain, prefer the active chain from env:
+   - `ORACLE_ACTIVE_CHAIN`
+   - `ORACLE_ACTIVE_CHAIN_ID`
+   - `ORACLE_ACTIVE_AGENT`
+2. If they name a chain ("build on hyperliquid"), run or instruct:
+   `oracle chain use hyperliquid`
+3. Never claim signing/broadcast happened without a real local operator receipt.
+4. Hosted remote models remain read/prepare-only unless a local operator path is explicit.
+5. Keep replies lowercase-friendly and terse. No glaze.
+
+## terminal and telegram are the same oracle
+
+`oracle` in a TTY launches Hermes with `-p oracle`. Telegram is wired to that
+same profile. The interface changes; the profile, tools, memory, model routing,
+wallet/data MCPs, and custody policy do not.
+
+- Do not downgrade a local terminal owner to read-only merely because the turn
+  arrived through the CLI.
+- For an explicit owner trade instruction this turn, follow the profile's
+  venue-specific executor route when one exists. Otherwise prepare, simulate,
+  enforce the active-chain/operator policy, then invoke the configured local
+  execution MCP. The signer/operator remains authoritative.
+- If confirmation is not explicit, show the exact action and wait for it.
+- `arm` is a chat action for one exact intent and TTL. Never tell the owner to
+  flip an execution environment variable.
+- A tool refusal is a real policy wall. Report the exact refusal instead of
+  bypassing it.
+- Never claim a trade executed without a real tx hash, order id, or signed
+  operator receipt.
+
+## shell helpers
+```bash
+oracle chain list
+oracle chain use hyperliquid
+oracle setup status
+oracle setup telegram --token <BOT_TOKEN>
+oracle setup gateway restart
+oracle chat
+```

package/skills/oracle-chat/chain.SKILL.md

@@ -0,0 +1,31 @@
+---
+name: chain
+description: "Use when the user types /chain or wants to list/select oracle working chains (hyperliquid, base, solana, bitcoin, ...)."
+version: 1.0.0
+disable-model-invocation: true
+---
+
+# /chain
+
+Run the local oracle chain selector. Do not invent chains.
+
+```bash
+# list
+oracle chain list
+
+# select build surface
+oracle chain use {{arg1}}
+
+# show / clear
+oracle chain show
+oracle chain clear
+```
+
+If `{{arg1}}` is empty, run `oracle chain list`.
+If `{{arg1}}` is `show`, `status`, `clear`, `list`, or a chain key, pass it through:
+
+```bash
+oracle chain {{arg1}} {{arg2}}
+```
+
+After selection, confirm active chain key + id + agent in lowercase.

package/skills/oracle-chat/setup.SKILL.md

@@ -0,0 +1,37 @@
+---
+name: setup
+description: "Use when the user types /setup or wants to connect telegram, discord, slack, or other hermes messaging platforms to oracle."
+version: 1.0.0
+disable-model-invocation: true
+---
+
+# /setup
+
+Configure hermes messaging for the oracle profile. Secrets stay local.
+
+```bash
+# menu + status (never prints tokens)
+oracle setup status
+
+# open full hermes wizard
+oracle setup messaging
+
+# platform shortcuts
+oracle setup telegram
+oracle setup discord
+oracle setup slack
+oracle setup whatsapp
+
+# gateway control
+oracle setup gateway status
+oracle setup gateway restart
+```
+
+If the user passed args after `/setup`, forward them:
+
+```bash
+oracle setup {{arg1}} {{arg2}} {{arg3}}
+```
+
+If no args, show `oracle setup status`.
+Never echo bot tokens, app tokens, or passwords back into chat.

package/skins/oracle.yaml

@@ -0,0 +1,52 @@
+name: oracle
+description: plain lowercase ascii oracle
+colors:
+  banner_border: "#30363d"
+  banner_title: "#e6edf3"
+  banner_accent: "#e6edf3"
+  banner_dim: "#7d8590"
+  banner_text: "#b1bac4"
+  ui_accent: "#e6edf3"
+  ui_label: "#b1bac4"
+  ui_ok: "#7ee787"
+  ui_error: "#ff7b72"
+  ui_warn: "#d29922"
+  prompt: "#e6edf3"
+  input_rule: "#30363d"
+  response_border: "#30363d"
+  status_bar_bg: "#0d1117"
+  status_bar_text: "#b1bac4"
+  status_bar_strong: "#e6edf3"
+  status_bar_dim: "#7d8590"
+  status_bar_good: "#7ee787"
+  status_bar_warn: "#d29922"
+  status_bar_bad: "#ff7b72"
+  status_bar_critical: "#ff7b72"
+  session_label: "#b1bac4"
+  session_border: "#30363d"
+  voice_status_bg: "#0d1117"
+  selection_bg: "#21262d"
+  completion_menu_bg: "#0d1117"
+  completion_menu_current_bg: "#21262d"
+  completion_menu_meta_bg: "#0d1117"
+  completion_menu_meta_current_bg: "#21262d"
+spinner:
+  waiting_faces: [".", "..", "..."]
+  thinking_faces: [".", "..", "..."]
+  thinking_verbs: ["working", "reading", "checking", "routing"]
+  wings: [["", ""]]
+branding:
+  agent_name: "oracle"
+  welcome: ""
+  goodbye: "exit"
+  response_label: "oracle"
+  prompt_symbol: ">"
+  help_header: "oracle"
+tool_prefix: ">"
+banner_logo: |
+  [#e6edf3]                 _[/]
+  [#e6edf3] ___ _ _ __ _ __| |___[/]
+  [#e6edf3]/ _ \ '_/ _` / _| / -_)[/]
+  [#e6edf3]\___/_| \__,_\__|_\___|[/]
+banner_hero: |
+  [#e6edf3]oracle[/]

package/src/cli/chain-catalog.mjs

@@ -0,0 +1,215 @@
+// Working chain surface for the oracle chat/CLI selector.
+// Keys stay lowercase. Hyperliquid is the product name; HyperEVM is chain 999.
+
+export const WORKING_CHAINS = Object.freeze([
+  {
+    key: "hyperliquid",
+    aliases: ["hl", "hyperevm", "hype", "999"],
+    chainId: 999,
+    name: "hyperliquid",
+    kind: "evm",
+    family: "hyperliquid",
+    agent: "hyperliquid-agent",
+    note: "perps · hip-3/4 · hyperevm 999",
+    build: true,
+  },
+  {
+    key: "ethereum",
+    aliases: ["eth", "mainnet", "1"],
+    chainId: 1,
+    name: "ethereum",
+    kind: "evm",
+    family: "evm",
+    agent: "oracle",
+    note: "l1 · bridge hub",
+    build: true,
+  },
+  {
+    key: "base",
+    aliases: ["8453"],
+    chainId: 8453,
+    name: "base",
+    kind: "evm",
+    family: "evm",
+    agent: "oracle",
+    note: "evm l2",
+    build: true,
+  },
+  {
+    key: "arbitrum",
+    aliases: ["arb", "42161"],
+    chainId: 42161,
+    name: "arbitrum",
+    kind: "evm",
+    family: "evm",
+    agent: "oracle",
+    note: "evm l2",
+    build: true,
+  },
+  {
+    key: "optimism",
+    aliases: ["op", "10"],
+    chainId: 10,
+    name: "optimism",
+    kind: "evm",
+    family: "evm",
+    agent: "oracle",
+    note: "op mainnet",
+    build: true,
+  },
+  {
+    key: "polygon",
+    aliases: ["matic", "137"],
+    chainId: 137,
+    name: "polygon",
+    kind: "evm",
+    family: "evm",
+    agent: "oracle",
+    note: "evm l2",
+    build: true,
+  },
+  {
+    key: "bsc",
+    aliases: ["bnb", "56"],
+    chainId: 56,
+    name: "bnb chain",
+    kind: "evm",
+    family: "evm",
+    agent: "oracle",
+    note: "bsc",
+    build: true,
+  },
+  {
+    key: "avalanche",
+    aliases: ["avax", "43114"],
+    chainId: 43114,
+    name: "avalanche",
+    kind: "evm",
+    family: "evm",
+    agent: "oracle",
+    note: "c-chain",
+    build: true,
+  },
+  {
+    key: "abstract",
+    aliases: ["abs", "2741"],
+    chainId: 2741,
+    name: "abstract",
+    kind: "evm",
+    family: "evm",
+    agent: "oracle",
+    note: "open / add agent",
+    build: true,
+  },
+  {
+    key: "stable",
+    aliases: ["988"],
+    chainId: 988,
+    name: "stable",
+    kind: "evm",
+    family: "stable",
+    agent: "stable-agent",
+    note: "usdt0 gas · stable agent",
+    build: true,
+  },
+  {
+    key: "robinhood",
+    aliases: ["rh", "4663"],
+    chainId: 4663,
+    name: "robinhood",
+    kind: "evm",
+    family: "robinhood",
+    agent: "robinhood-agent",
+    note: "rh chain 4663",
+    build: true,
+  },
+  {
+    key: "solana",
+    aliases: ["sol"],
+    chainId: "SOL",
+    name: "solana",
+    kind: "svm",
+    family: "solana",
+    agent: "solana-agent",
+    note: "jup · nfts · dexs",
+    build: true,
+  },
+  {
+    key: "bitcoin",
+    aliases: ["btc"],
+    chainId: "BTC",
+    name: "bitcoin",
+    kind: "utxo",
+    family: "bitcoin",
+    agent: "bitcoin-agent",
+    note: "ord · runes · l1",
+    build: true,
+  },
+  {
+    key: "polymarket",
+    aliases: ["poly", "polygon-poly"],
+    chainId: 137,
+    name: "polymarket",
+    kind: "venue",
+    family: "polymarket",
+    agent: "polymarket-agent",
+    note: "prediction markets (polygon venue)",
+    build: false,
+  },
+]);
+
+function normalize(raw) {
+  return String(raw || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\/+/, "")
+    .replace(/\s+/g, "-");
+}
+
+export function listWorkingChains({ buildOnly = false } = {}) {
+  return WORKING_CHAINS.filter((c) => (buildOnly ? c.build : true));
+}
+
+export function findWorkingChain(query) {
+  const q = normalize(query);
+  if (!q) return null;
+  for (const chain of WORKING_CHAINS) {
+    if (chain.key === q) return chain;
+    if (String(chain.chainId).toLowerCase() === q) return chain;
+    if ((chain.aliases || []).map(normalize).includes(q)) return chain;
+    if (normalize(chain.name) === q) return chain;
+  }
+  return null;
+}
+
+export function renderChainList({ selectedKey = null, buildOnly = false } = {}) {
+  const rows = listWorkingChains({ buildOnly });
+  const lines = [
+    "oracle chains",
+    "",
+    "pick a build/trade surface:",
+    "",
+  ];
+  for (const c of rows) {
+    const mark = selectedKey && selectedKey === c.key ? "*" : " ";
+    const id = String(c.chainId).padEnd(6);
+    const key = c.key.padEnd(12);
+    lines.push(`${mark} ${key} ${id}  ${c.note}`);
+  }
+  lines.push("");
+  lines.push("usage:");
+  lines.push("  /chain                 list");
+  lines.push("  /chain hyperliquid     select");
+  lines.push("  /chain show            current");
+  lines.push("  /chain clear           unset");
+  lines.push("  oracle chain use base  same from shell");
+  if (selectedKey) lines.push("", `active: ${selectedKey}`);
+  return lines.join("\n") + "\n";
+}
+
+export default {
+  WORKING_CHAINS,
+  listWorkingChains,
+  findWorkingChain,
+  renderChainList,
+};

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/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;
+  },
+};