@oracle-agent/oracle 0.3.6 → 0.4.0

package/bin/oracle-data-mcp.mjs

@@ -14,6 +14,7 @@ import fs from "node:fs";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { env } from "../src/oracle-env.mjs";
+import { listAddresses, lookupAddress, rememberAddress, forgetAddress } from "../src/address-book.mjs";
 
 const DATA_URL = (env("ORACLE_DATA_URL", "MAD_DESK_URL", "http://127.0.0.1:8787")).replace(/\/$/, "");
 
@@ -539,6 +540,57 @@ const tools = [
       required: ["chainId", "address"],
     },
   },
+  {
+    name: "address_book_remember",
+    description:
+      "Remember a wallet address with a label. Call this whenever someone states their address " +
+      "or an agent/counterparty wallet is discovered, so it survives the conversation. " +
+      "Stores labels only — never private keys, seeds, or passphrases.",
+    inputSchema: {
+      type: "object",
+      required: ["address", "label"],
+      properties: {
+        address: { type: "string", description: "0x address" },
+        label: { type: "string", description: "short name, e.g. carlo-agent" },
+        who: { type: "string", description: "person or entity the wallet belongs to" },
+        role: { type: "string", description: "agent | owner | person | counterparty | venue" },
+        chainIds: { type: "array", items: { type: "number" } },
+        notes: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "address_book_list",
+    description:
+      "List remembered wallets (owner, agent, people, counterparties). Read-only. " +
+      "Check this before sending or bridging to a person.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "search across label, who, address, notes" },
+        role: { type: "string" },
+        who: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "address_book_lookup",
+    description: "Look up one 0x address in the durable address book. Read-only.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" } },
+    },
+  },
+  {
+    name: "address_book_forget",
+    description: "Remove a remembered address, optionally only one label for it.",
+    inputSchema: {
+      type: "object",
+      required: ["address"],
+      properties: { address: { type: "string" }, label: { type: "string" } },
+    },
+  },
   {
     name: "best_swap_route",
     description:
@@ -817,6 +869,15 @@ async function callTool(name, args = {}) {
     const token = args.token ? await sc.tokenBalance(args.address, args.token).catch(() => null) : null;
     return { chainId: Number(args.chainId), address: args.address, native, token };
   }
+  if (name === "address_book_remember") {
+    return rememberAddress({
+      address: args.address, label: args.label, who: args.who,
+      role: args.role, chainIds: args.chainIds, notes: args.notes, source: "oracle-data-mcp",
+    });
+  }
+  if (name === "address_book_list") return listAddresses({ q: args.q, role: args.role, who: args.who });
+  if (name === "address_book_lookup") return lookupAddress(args.address);
+  if (name === "address_book_forget") return forgetAddress(args.address, args.label || null);
   if (name === "data_catalog") return httpJson(`${DATA_URL}/data/catalog`);
   if (name === "data_health") return httpJson(`${DATA_URL}/data/health`);
   if (name === "data_call") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Oracle: prepare-only multichain agent control plane. Policy-bounded intents for a user-signed wallet. Self-custody by default — the public package never takes your key. Built for Hermes; no model key required.",
   "license": "Apache-2.0",
   "type": "module",
@@ -42,6 +42,7 @@
     "./scanner": "./src/scanner/index.mjs",
     "./router": "./src/router/index.mjs",
     "./action-semantics": "./src/action-semantics.mjs",
+    "./address-book": "./src/address-book.mjs",
     "./nft-gas-war": "./src/nft-gas-war-guard.mjs",
     "./prepare-envelope": "./src/prepare-envelope.mjs"
   },

package/plugins/oracle-owner-gate/__init__.py

@@ -26,6 +26,16 @@ _PROTECTED = {
     "oracle_operator_sign": "sign",
     "oracle_operator_send": "send",
     "oracle_operator_execute": "send",
+    "exec_arm": "execute",
+    "exec_disarm": "cancel",
+    "evm_sign": "sign",
+    "evm_send": "send",
+    # The address book is durable state a later send can be routed against, so
+    # writes are owner-only. Reads stay open to the owner's own sessions.
+    "address_book_remember": "owner_write",
+    "address_book_forget": "owner_write",
+    "address_book_list": "owner_read",
+    "address_book_lookup": "owner_read",
 }
 
 _LEADING_INTENT = re.compile(
@@ -181,6 +191,10 @@ def _on_pre_tool_call(tool_name: str = "", session_id: str = "", **_: Any) -> Op
         return _block(reason)
     if required == "owner_read":
         return None
+    if required == "owner_write":
+        # Owner-authenticated bookkeeping. It records a label; it does not move
+        # value and does not need a leading execution verb like `arm`.
+        return None
     intent = turn["intent"]
     if intent != required:
         labels = {

package/profiles/oracle/SOUL.md

@@ -47,6 +47,16 @@ the data plane). If it stays ambiguous, ask. Do not guess a chain.
    `watch`, `watch this`, and `ping me` always mean `actionMode: alert_only`.
    Only an explicit `arm` may mean `actionMode: execute`, and only for one exact,
    bounded owner-authorized action.
+
+   **Arming is a chat action, not a terminal chore.** When the owner says `arm`,
+   create the exact action and confirm it. Never tell them to edit an env file,
+   export a variable, or restart a service to enable a trade. A local operator
+   ships pre-armed for owner-confirmed actions; the walls that still apply are
+   owner identity, the venue/destination allowlist, and the exact-grant bind.
+
+   **Autonomous trading is the one opt-in.** A trigger that fires a trade with
+   nobody watching requires `ORACLE_AUTONOMOUS=1`. Until then such an action
+   alerts instead of executing. Say that plainly rather than pretending it fired.
 2. **RFQ is a route source, not a permission bypass.** Compare solver/RFQ
    quotes net of gas/spread where configured, enforce expiry, and keep exact
    artifact kinds separate.
@@ -69,6 +79,15 @@ the data plane). If it stays ambiguous, ask. Do not guess a chain.
    incomplete whenever a provider, address, price, token/NFT indexer, or chain
    adapter is missing. Never turn an unavailable historical value into zero.
 
+## Address memory
+
+Remember who an address belongs to. When someone states a wallet, or an agent /
+counterparty wallet turns up in a read, call `address_book_remember` with a label
+and who it belongs to. Before preparing a send or bridge to a person rather than a
+venue, check `address_book_lookup` / `address_book_list` instead of asking them to
+paste it again. Labels only — never private keys, seeds, or passphrases, and a
+remembered label is a convenience, not an authorization.
+
 ## Confidence
 
 State it explicitly: `high` / `moderate` / `low` / `unknown`. A confident wrong

package/src/address-book.mjs

@@ -0,0 +1,160 @@
+/**
+ * Durable labeled address book for owner/agent/counterparty wallets.
+ *
+ * On by default: remembering who an address belongs to is a read/annotate
+ * concern, not an execution one. Nothing here signs, and no private key,
+ * passphrase, or seed is ever accepted or stored.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ORACLE_CONFIG_DIR, env } from "./oracle-env.mjs";
+
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+const FORBIDDEN_KEYS = new Set([
+  "privatekey", "private_key", "secret", "seed", "mnemonic", "passphrase", "signature", "keystore",
+]);
+
+export function addressBookPath() {
+  const override = env("ORACLE_ADDRESS_BOOK", "MAD_ADDRESS_BOOK", "");
+  if (override) return path.resolve(override);
+  const dir = env("ORACLE_CONFIG_DIR", "MAD_CONFIG_DIR", ORACLE_CONFIG_DIR);
+  return path.join(dir, "address-book.json");
+}
+
+function assertNoSecrets(input) {
+  for (const key of Object.keys(input || {})) {
+    if (FORBIDDEN_KEYS.has(key.toLowerCase())) {
+      throw new Error(`address-book: ${key} is forbidden; the book stores labels, never key material`);
+    }
+  }
+}
+
+function normalizeAddress(value) {
+  const address = String(value || "").trim();
+  if (!ADDR_RE.test(address)) throw new Error("address-book: address must be 0x + 40 hex characters");
+  return address.toLowerCase();
+}
+
+function text(value, max) {
+  if (value == null || value === "") return null;
+  return String(value).slice(0, max);
+}
+
+function emptyBook() {
+  return { version: 1, updatedAt: null, entries: [] };
+}
+
+function normalizeEntry(entry) {
+  return {
+    address: String(entry.address).toLowerCase(),
+    label: text(entry.label, 80) || "unknown",
+    who: text(entry.who, 120),
+    role: text(entry.role, 40),
+    chainIds: Array.isArray(entry.chainIds) ? entry.chainIds.map(Number).filter(Number.isFinite) : [],
+    notes: text(entry.notes, 500),
+    source: text(entry.source, 80),
+    firstSeenAt: entry.firstSeenAt || null,
+    lastSeenAt: entry.lastSeenAt || null,
+  };
+}
+
+export function readAddressBook() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(addressBookPath(), "utf8"));
+    if (!raw || typeof raw !== "object") return emptyBook();
+    const entries = Array.isArray(raw.entries) ? raw.entries : [];
+    return {
+      version: 1,
+      updatedAt: raw.updatedAt || null,
+      entries: entries
+        .filter((entry) => entry && typeof entry === "object" && ADDR_RE.test(String(entry.address || "")))
+        .map(normalizeEntry),
+    };
+  } catch {
+    return emptyBook();
+  }
+}
+
+function writeBook(book) {
+  const file = addressBookPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const payload = { ...book, version: 1, updatedAt: new Date().toISOString() };
+  const tmp = path.join(path.dirname(file), `.address-book.${process.pid}.tmp`);
+  fs.writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    /* best effort on platforms without chmod semantics */
+  }
+  return payload;
+}
+
+export function listAddresses(filter = {}) {
+  const book = readAddressBook();
+  let entries = book.entries;
+  if (filter.role) entries = entries.filter((entry) => entry.role === String(filter.role));
+  if (filter.who) {
+    const query = String(filter.who).toLowerCase();
+    entries = entries.filter(
+      (entry) => (entry.who || "").toLowerCase().includes(query) || (entry.label || "").toLowerCase().includes(query),
+    );
+  }
+  if (filter.q) {
+    const query = String(filter.q).toLowerCase();
+    entries = entries.filter(
+      (entry) =>
+        entry.address.includes(query) ||
+        (entry.label || "").toLowerCase().includes(query) ||
+        (entry.who || "").toLowerCase().includes(query) ||
+        (entry.notes || "").toLowerCase().includes(query),
+    );
+  }
+  return { updatedAt: book.updatedAt, count: entries.length, entries };
+}
+
+export function lookupAddress(address) {
+  const normalized = normalizeAddress(address);
+  const entries = readAddressBook().entries.filter((entry) => entry.address === normalized);
+  return { address: normalized, found: entries.length > 0, entries };
+}
+
+export function rememberAddress(input = {}) {
+  assertNoSecrets(input);
+  const address = normalizeAddress(input.address);
+  const label = text(input.label ?? input.role, 80) || "wallet";
+  const now = new Date().toISOString();
+  const book = readAddressBook();
+  const index = book.entries.findIndex((entry) => entry.address === address && entry.label === label);
+  const entry = normalizeEntry({
+    address,
+    label,
+    who: input.who,
+    role: input.role,
+    chainIds: input.chainIds,
+    notes: input.notes,
+    source: input.source || "agent",
+    firstSeenAt: index >= 0 ? book.entries[index].firstSeenAt || now : now,
+    lastSeenAt: now,
+  });
+  if (index >= 0) book.entries[index] = entry;
+  else book.entries.push(entry);
+  const rank = (role) => (role === "agent" ? 0 : role === "owner" ? 1 : 2);
+  book.entries.sort(
+    (a, b) => rank(a.role) - rank(b.role) || a.label.localeCompare(b.label) || a.address.localeCompare(b.address),
+  );
+  const saved = writeBook(book);
+  return { ok: true, entry, count: saved.entries.length };
+}
+
+export function forgetAddress(address, label = null) {
+  const normalized = normalizeAddress(address);
+  const book = readAddressBook();
+  const before = book.entries.length;
+  book.entries = book.entries.filter((entry) => {
+    if (entry.address !== normalized) return true;
+    return label == null ? false : entry.label !== String(label);
+  });
+  writeBook(book);
+  return { ok: true, removed: before - book.entries.length, count: book.entries.length };
+}