@oracle-agent/oracle 0.3.6 → 0.4.1

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(/\/$/, "");
 
@@ -262,7 +263,7 @@ const tools = [
   {
     name: "nft_prepare_list",
     description:
-      "Prepare an NFT listing for OpenSea EVM, Magic Eden Solana, or Satflow Bitcoin after explicit user review. Requires userConfirmed=true plus asset, marketplace, price, currency where applicable, and future expiry. Returns approval/signing actions, an unsigned Solana transaction, or an unsigned Bitcoin PSBT. Never signs, submits, or broadcasts.",
+      "Prepare an NFT listing for OpenSea EVM, Magic Eden Solana, or Satflow Bitcoin after explicit user review. Requires userConfirmed=true plus asset, marketplace, price, currency where applicable, and future expiry. Magic Eden Solana also requires confirmation exactly: list <tokenMint> on magiceden-sol for <priceSol> SOL until <expiry>. Returns approval/signing actions, an unsigned Solana transaction, or an unsigned Bitcoin PSBT. Never signs, submits, or broadcasts.",
     inputSchema: {
       type: "object",
       required: ["marketplace", "userConfirmed"],
@@ -283,7 +284,8 @@ const tools = [
         tokenATA: { type: "string" },
         auctionHouse: { type: "string" },
         priceSol: { type: "string" },
-        expiry: { description: "Future ISO 8601 timestamp or Unix seconds." },
+        expiry: { description: "Future ISO 8601 timestamp or Unix seconds. Magic Eden Solana listings require finite future expiry; no-expiry is refused." },
+        confirmation: { type: "string", description: "Required for Magic Eden Solana listings. Exact phrase: list <tokenMint> on magiceden-sol for <priceSol> SOL until <expiry>." },
         inscriptionId: { type: "string" },
         runesOutput: { type: "string" },
         ordAddress: { type: "string" },
@@ -539,6 +541,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 +870,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.1",
   "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 };
+}

package/src/data/http.mjs

@@ -37,6 +37,35 @@ const IDENTITY_HEADERS = [
   "proxy-authorization",
 ];
 
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 3;
+
+function credentialHeaderName(name) {
+  const h = String(name || "").toLowerCase();
+  return IDENTITY_HEADERS.includes(h) || /(^|-)(api[-_]?key|key|token|secret|auth|authorization|session|cookie|signature|access)(-|$)/.test(h);
+}
+
+function stripCredentialHeaders(headers) {
+  const safe = {};
+  for (const [name, value] of Object.entries(headers || {})) {
+    if (!credentialHeaderName(name)) safe[name] = value;
+  }
+  return safe;
+}
+
+function redirectedUrl(location, currentUrl) {
+  if (!location) throw new Error(`HTTP redirect from ${currentUrl} missing Location`);
+  const next = new URL(String(location), String(currentUrl));
+  if (next.protocol !== "http:" && next.protocol !== "https:") {
+    throw new Error(`HTTP redirect from ${currentUrl} used unsupported protocol ${next.protocol}`);
+  }
+  return next.toString();
+}
+
+function sameOrigin(a, b) {
+  return new URL(String(a)).origin === new URL(String(b)).origin;
+}
+
 const inflight = new Map();
 
 /**
@@ -77,24 +106,48 @@ async function once(url, { fetchImpl, method, headers, body, timeoutMs }) {
   const ac = new AbortController();
   const t = setTimeout(() => ac.abort(), timeoutMs);
   try {
-    const res = await fetchImpl(url, { method, headers, body, signal: ac.signal });
-    const text = await res.text();
-    let json = null;
-    if (text) {
-      try {
-        json = JSON.parse(text);
-      } catch {
-        json = null;
+    let currentUrl = String(url);
+    let currentHeaders = { ...(headers || {}) };
+    for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1) {
+      const res = await fetchImpl(currentUrl, {
+        method,
+        headers: currentHeaders,
+        body,
+        signal: ac.signal,
+        redirect: "manual",
+      });
+      const text = await res.text();
+      let json = null;
+      if (text) {
+        try {
+          json = JSON.parse(text);
+        } catch {
+          json = null;
+        }
       }
+      if (REDIRECT_STATUS.has(res.status)) {
+        if (method !== "GET" && method !== "HEAD") {
+          const err = new Error(`HTTP ${res.status} ${method} ${currentUrl} redirected non-idempotent request`);
+          err.status = res.status;
+          err.body = json ?? text.slice(0, 300);
+          throw err;
+        }
+        if (redirects === MAX_REDIRECTS) throw new Error(`HTTP redirect loop for ${url}`);
+        const nextUrl = redirectedUrl(res.headers?.get?.("location"), currentUrl);
+        if (!sameOrigin(nextUrl, currentUrl)) currentHeaders = stripCredentialHeaders(currentHeaders);
+        currentUrl = nextUrl;
+        continue;
+      }
+      if (!res.ok) {
+        const err = new Error(`HTTP ${res.status} ${method} ${currentUrl}`);
+        err.status = res.status;
+        err.retryAfter = res.headers?.get?.("retry-after") ?? null;
+        err.body = json ?? text.slice(0, 300);
+        throw err;
+      }
+      return json ?? text;
     }
-    if (!res.ok) {
-      const err = new Error(`HTTP ${res.status} ${method} ${url}`);
-      err.status = res.status;
-      err.retryAfter = res.headers?.get?.("retry-after") ?? null;
-      err.body = json ?? text.slice(0, 300);
-      throw err;
-    }
-    return json ?? text;
+    throw new Error(`HTTP redirect loop for ${url}`);
   } finally {
     clearTimeout(t);
   }

package/src/data/providers/magiceden-sol.mjs

@@ -90,17 +90,33 @@ function lamports(sol) {
 }
 
 function listingExpiry(value) {
-  if (value == null || value === "") return null;
+  if (value == null || value === "") throw new Error("magiceden: listing expiry is required and must be in the future");
   const expiry = Number(value);
-  if (!Number.isSafeInteger(expiry) || expiry < 0) {
-    throw new Error("magiceden: expiry must be a whole Unix timestamp in seconds or 0");
+  if (!Number.isSafeInteger(expiry) || expiry <= 0) {
+    throw new Error("magiceden: expiry must be a future Unix timestamp in seconds");
   }
-  if (expiry !== 0 && expiry <= Math.floor(Date.now() / 1000)) {
-    throw new Error("magiceden: expiry must be in the future or 0 for no expiry");
+  if (expiry <= Math.floor(Date.now() / 1000)) {
+    throw new Error("magiceden: expiry must be in the future");
   }
   return expiry;
 }
 
+function listConfirmation({ tokenMint, priceSol, expiry }) {
+  return `list ${tokenMint} on magiceden-sol for ${priceSol} SOL until ${expiry}`;
+}
+
+function requireListingConfirmation(args, fields) {
+  if (args.userConfirmed !== true) {
+    throw new Error("magiceden: listing requires userConfirmed=true after reviewing tokenMint, priceSol, and expiry");
+  }
+  const expected = listConfirmation(fields);
+  const actual = String(args.confirmation || args.confirmationPhrase || "").trim();
+  if (actual !== expected) {
+    throw new Error(`magiceden: confirmation must equal ${JSON.stringify(expected)}`);
+  }
+  return expected;
+}
+
 export async function magicEdenSolHealth(opts = {}) {
   try {
     const stats = await magicEdenSolStats({ symbol: "mad_lads" }, opts);
@@ -269,6 +285,7 @@ export async function magicEdenSolPrepareList(args = {}, opts = {}) {
   const auctionHouse = solanaPubkey(args.auctionHouse, "auctionHouse");
   const priceSol = positiveNumber(args.priceSol ?? args.price, "priceSol");
   const expiry = listingExpiry(args.expiry);
+  const confirmation = requireListingConfirmation(args, { tokenMint, priceSol, expiry });
   const url = new URL(`${base(opts)}/instructions/sell`);
   url.searchParams.set("seller", seller);
   url.searchParams.set("auctionHouseAddress", auctionHouse);
@@ -301,6 +318,7 @@ export async function magicEdenSolPrepareList(args = {}, opts = {}) {
     tokenMint,
     priceSol,
     expiry,
+    confirmation,
     transaction,
     transactionEncoding: "base64",
     raw,