@oracle-agent/oracle 0.4.2 → 0.6.0

package/scripts/check-doc-drift.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Release gate: shipped prose must not contradict shipped behavior.
+//
+// Why this exists. The 2026-08-01 four-model audit found the same stale claim
+// in 20 places across both packages: docs said the unattended signer was
+// limited to `hl` and `poly` long after six bounded surfaces had shipped. The
+// worst instances were not READMEs — they were `profiles/oracle/SOUL.md` and
+// `skills/oracle-action-semantics/SKILL.md`, which are read by the MODEL. An
+// agent told that EVM daemon execution is impossible reasons incorrectly about
+// its own authority, and no test suite can see a false sentence.
+//
+// This scans every doc surface that ships in the tarball, including model-facing
+// SOUL and skill text, which is exactly where drift hides longest.
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+const failures = [];
+
+// Claims that shipped in a real release and are now false.
+const STALE_CLAIMS = [
+  { re: /limited\s+to\s+`?hl`?\s+and\s+`?poly`?/i, why: "says the unattended signer is limited to hl+poly" },
+  { re: /only\s+`?hl`?\s+and\s+`?poly`?\s+are\s+enabled/i, why: "says only hl+poly are daemon-enabled" },
+  { re: /daemon\s+surfaces\s+remain\s+`?hl`?\s+and\s+`?poly`?/i, why: "freezes the surface list at hl+poly" },
+  { re: /policy-bounded\s+`?hl`?\s+and\s+`?poly`?\s+only/i, why: "restricts the daemon to hl+poly" },
+  { re: /agent-facing\s+daemon\s+supports\s+only\s+policy-bounded\s+Hyperliquid\s+and\s+Polymarket\s+execution/i, why: "says the agent-facing daemon supports only Hyperliquid+Polymarket" },
+  { re: /`?evm`?,?\s+`?btc`?,?\s+and\s+`?sol`?\s+fail\s+closed\s+at\s+the\s+daemon/i, why: "claims evm/btc/sol are refused at the daemon" },
+  { re: /EVM,\s*BTC,?\s*and\s+Solana\s+are\s+not\s+daemon\s+surfaces/i, why: "denies evm/btc/sol are daemon surfaces" },
+  { re: /companion\s+daemon\s+is\s+`?hl`?\s*\/\s*`?poly`?[- ]only/i, why: "describes the companion daemon as hl/poly-only" },
+  { re: /daemon\s+supports\s+only\s+policy-bounded\s+Hyperliquid\s+and\s+Polymarket/i, why: "describes the daemon as Hyperliquid/Polymarket-only" },
+  { re: /unattended\s+signer\s+remains\s+`?hl`?\s*\/\s*`?poly`?/i, why: "freezes the generic signer at hl/poly" },
+  { re: /supports\s+autonomous\s+Hyperliquid\s+and\s+Polymarket\s+execution/i, why: "describes the daemon as Hyperliquid/Polymarket-only" },
+  { re: /\(HL\s*\+\s*Poly,\s*capped\)/i, why: "documents autosign as hl/poly-only" },
+  { re: /policy-bounded\s+HL\s*\/\s*Polymarket\s+exec/i, why: "documents the signer daemon as hl/poly-only" },
+  { re: /policy-bounded\s+daemon\s+surfaces:\s*hl\s*\|\s*poly\s*$/i, why: "documents only two of six daemon surfaces" },
+  { re: /ORACLE_SIGNER_SURFACES=hl,poly\s*$/i, why: "quickstart freezes ORACLE_SIGNER_SURFACES at hl,poly" },
+  { re: /ORACLE_AUTONOMOUS_TRADING=1.*(?:or\s+run\s+the\s+signer\s+daemon|same(?:-tier)?).*oracle-signer/i, why: "frames direct exec and oracle-signer as equivalent agent paths" },
+  { re: /(?:or\s+run\s+the\s+signer\s+daemon|same(?:-tier)?).*oracle-signer.*ORACLE_AUTONOMOUS_TRADING=1/i, why: "frames direct exec and oracle-signer as equivalent agent paths" },
+];
+
+// Version pins that go stale the moment a release ships. The audit found the
+// quickstart advertising 0.3.6/0.6.1 inside a 0.4.0 tarball, so a copy-paste
+// install handed users an older wall set.
+function checkVersionPins(rel, text) {
+  const lines = text.split("\n");
+  lines.forEach((line, i) => {
+    const pin = line.match(/@oracle-agent\/oracle@(\d+\.\d+\.\d+)/);
+    if (pin && pin[1] !== pkg.version) {
+      failures.push(
+        `${rel}:${i + 1} pins @oracle-agent/oracle@${pin[1]} but this package is ${pkg.version}\n    ${line.trim().slice(0, 120)}`,
+      );
+    }
+    const latest = line.match(/Latest:.*oracle\s+`(\d+\.\d+\.\d+)`/i);
+    if (latest && latest[1] !== pkg.version) {
+      failures.push(
+        `${rel}:${i + 1} advertises oracle ${latest[1]} as latest but this package is ${pkg.version}\n    ${line.trim().slice(0, 120)}`,
+      );
+    }
+  });
+}
+
+// Every markdown surface that ships to a user or a model.
+function docFiles() {
+  const out = [];
+  for (const rel of ["README.md", "SETUP.md", "SECURITY.md"]) {
+    if (existsSync(path.join(root, rel))) out.push(rel);
+  }
+  for (const dir of ["docs", "profiles", "skills"]) {
+    const abs = path.join(root, dir);
+    if (!existsSync(abs)) continue;
+    const walk = (d) => {
+      for (const entry of readdirSync(d)) {
+        const full = path.join(d, entry);
+        if (statSync(full).isDirectory()) walk(full);
+        else if (entry.endsWith(".md")) out.push(path.relative(root, full));
+      }
+    };
+    walk(abs);
+  }
+  return out;
+}
+
+const files = docFiles();
+for (const rel of files) {
+  const text = readFileSync(path.join(root, rel), "utf8");
+  text.split("\n").forEach((line, i) => {
+    for (const claim of STALE_CLAIMS) {
+      if (claim.re.test(line)) {
+        failures.push(`${rel}:${i + 1} ${claim.why}\n    ${line.trim().slice(0, 140)}`);
+      }
+    }
+  });
+  checkVersionPins(rel, text);
+}
+
+console.log(`package version: ${pkg.version}`);
+console.log(`doc surfaces scanned: ${files.length} (README/SETUP/SECURITY + docs/ + profiles/ + skills/)`);
+console.log("");
+
+if (failures.length) {
+  console.error(`FAIL — ${failures.length} doc/code drift finding(s):\n`);
+  for (const f of failures) console.error(`  ${f}\n`);
+  console.error("Shipped prose contradicts shipped behavior. Model-facing SOUL/skill text counts:");
+  console.error("an agent that reads a false capability claim reasons wrongly about its own authority.");
+  process.exit(1);
+}
+
+console.log("PASS — no stale capability claims or version pins in shipped docs");

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