@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/onboarding/harness-configs.mjs

@@ -0,0 +1,102 @@
+const PACKAGE = "@oracle-agent/oracle";
+const COMMAND = "npx";
+const ARGS = ["-y", "--package", PACKAGE, "oracle-data-mcp"];
+const FORBIDDEN_NAME = /(?:^|_)(?:PRIVATE_KEY|SECRET|TOKEN|PASSWORD|PASSPHRASE|MNEMONIC|SEED)(?:_|$)/i;
+
+function requiredText(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
+  if (/\r|\n|\0/.test(value)) throw new TypeError(`${name} must be a single-line string`);
+  return value.trim();
+}
+
+function validateUrl(value) {
+  const text = requiredText(value, "url");
+  let parsed;
+  try { parsed = new URL(text); } catch { throw new TypeError("url must be a valid http(s) URL"); }
+  if (!/^https?:$/.test(parsed.protocol) || parsed.username || parsed.password) {
+    throw new TypeError("url must be a credential-free http(s) URL");
+  }
+  for (const name of parsed.searchParams.keys()) {
+    if (FORBIDDEN_NAME.test(name) || /^(?:key|api[_-]?key|auth)$/i.test(name)) {
+      throw new TypeError(`url must not contain secret-shaped query parameter: ${name}`);
+    }
+  }
+  return parsed.href;
+}
+
+function validateKey(value) {
+  const text = requiredText(value, "key");
+  if (/^[A-Z][A-Z0-9_]*\s*=/.test(text) || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(text)) {
+    throw new TypeError("key must be an Oracle agent key, not an environment assignment or private key");
+  }
+  if (/^(?:0x)?[0-9a-f]{64}$/i.test(text) || text.trim().split(/\s+/).length >= 12) {
+    throw new TypeError("key looks like private signing material");
+  }
+  return text;
+}
+
+function validateLabel(value) {
+  const label = requiredText(value, "label");
+  if (!/^[a-z0-9][a-z0-9_-]{0,62}$/i.test(label)) {
+    throw new TypeError("label must contain only letters, digits, underscores, and hyphens");
+  }
+  if (FORBIDDEN_NAME.test(label)) throw new TypeError("label must not be a secret-shaped environment name");
+  return label;
+}
+
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function yamlString(value) {
+  return JSON.stringify(value);
+}
+
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+/**
+ * Return deterministic, copy-pasteable MCP configuration snippets.
+ * This function performs no I/O and never reads from process.env.
+ */
+export function emitHarnessConfigs({ url, key, label = "oracle-data" } = {}) {
+  const endpoint = validateUrl(url);
+  const agentKey = validateKey(key);
+  const name = validateLabel(label);
+  const server = {
+    command: COMMAND,
+    args: [...ARGS],
+    env: { ORACLE_DATA_URL: endpoint, ORACLE_AGENT_KEY: agentKey },
+  };
+  const mcp = { mcpServers: { [name]: server } };
+
+  return {
+    hermes: [
+      "mcp_servers:",
+      `  ${name}:`,
+      `    command: ${yamlString(COMMAND)}`,
+      "    args:",
+      ...ARGS.map((arg) => `      - ${yamlString(arg)}`),
+      "    env:",
+      `      ORACLE_DATA_URL: ${yamlString(endpoint)}`,
+      `      ORACLE_AGENT_KEY: ${yamlString(agentKey)}`,
+      "",
+    ].join("\n"),
+    claudeCode: json(mcp),
+    codex: [
+      `[mcp_servers.${tomlString(name)}]`,
+      `command = ${tomlString(COMMAND)}`,
+      `args = [${ARGS.map(tomlString).join(", ")}]`,
+      "",
+      `[mcp_servers.${tomlString(name)}.env]`,
+      `ORACLE_DATA_URL = ${tomlString(endpoint)}`,
+      `ORACLE_AGENT_KEY = ${tomlString(agentKey)}`,
+      "",
+    ].join("\n"),
+    cursor: json(mcp),
+    genericMcp: json(mcp),
+  };
+}
+
+export const createHarnessConfigs = emitHarnessConfigs;

package/src/onboarding/index.mjs

@@ -0,0 +1,18 @@
+export {
+  createAgentKey,
+  listAgentKeys,
+  revokeAgentKey,
+  authenticateAgentKey,
+  defaultStorePath,
+  __resetAgentKeysForTest,
+} from "./agent-keys.mjs";
+
+export {
+  TIERS,
+  listTiers,
+  getTier,
+  onboardUser,
+  onboardAuthenticate,
+  onboardListKeys,
+  onboardRevoke,
+} from "./tiers.mjs";

package/src/onboarding/tiers.mjs

@@ -0,0 +1,139 @@
+// Product onboarding tiers — multi-user, non-custodial.
+// Tier chooses default scopes. Higher tiers never put user private keys on our box.
+
+import { DEFAULT_SCOPES, EXECUTE_SCOPE } from "../scopes.mjs";
+import { createAgentKey, listAgentKeys, revokeAgentKey, authenticateAgentKey } from "./agent-keys.mjs";
+
+/**
+ * Tier catalog (product story):
+ * - observer:   read-only market/position data
+ * - preparer:   can prepare trades/mints (unsigned / advisory)
+ * - shadow:     paper/shadow agent loops
+ * - executor:   live agent:execute — ONLY if owner is on controller allowlist
+ * - local_signer: no API key needed for signing; user signs off-infra (docs only)
+ */
+export const TIERS = {
+  observer: {
+    id: "observer",
+    label: "Observer",
+    description: "Read markets, NFTs, positions. No prepare/execute.",
+    scopes: ["read:markets", "read:nfts", "read:positions"],
+    custody: "none",
+    canExecute: false,
+  },
+  preparer: {
+    id: "preparer",
+    label: "Preparer",
+    description: "Prepare trades/mints; user or operator co-signs. No live execute scope.",
+    scopes: [...DEFAULT_SCOPES].filter((s) => s !== "agent:shadow"),
+    custody: "none",
+    canExecute: false,
+  },
+  shadow: {
+    id: "shadow",
+    label: "Shadow agent",
+    description: "Full prepare + agent:shadow paper loops. Still no live execute.",
+    scopes: [...DEFAULT_SCOPES],
+    custody: "none",
+    canExecute: false,
+  },
+  executor: {
+    id: "executor",
+    label: "Executor (controller)",
+    description:
+      "Live agent:execute on the owner's own wallet only. Owner must be an executor controller. Key is NOT a wallet key.",
+    scopes: [...DEFAULT_SCOPES, EXECUTE_SCOPE],
+    custody: "none — scoped API key only; user wallet key never stored",
+    canExecute: true,
+  },
+  local_signer: {
+    id: "local_signer",
+    label: "Local signer",
+    description:
+      "User keeps keys on their device. Desk issues prepare-only key; signing happens off our infra.",
+    scopes: ["read:markets", "read:positions", "prepare:trade", "prepare:mint"],
+    custody: "none — signing off-box",
+    canExecute: false,
+    mintKey: true,
+  },
+};
+
+export function listTiers() {
+  return Object.values(TIERS).map((t) => ({
+    id: t.id,
+    label: t.label,
+    description: t.description,
+    scopes: t.scopes,
+    custody: t.custody,
+    canExecute: t.canExecute,
+  }));
+}
+
+export function getTier(id) {
+  const t = TIERS[id];
+  if (!t) throw new Error(`Unknown tier: ${id}`);
+  return t;
+}
+
+/**
+ * Onboard a user wallet onto a tier. Returns one-time raw API key (except pure docs).
+ * NEVER accepts or stores a private key.
+ */
+export function onboardUser({
+  owner,
+  tier = "observer",
+  name,
+  controllerAllowlist = [],
+  storePath,
+  scopes, // optional override
+} = {}) {
+  if (owner && typeof owner === "object" && owner.privateKey) {
+    throw new Error("Refusing privateKey — non-custodial onboarding accepts owner address only");
+  }
+  const t = getTier(tier);
+  const finalScopes = scopes || t.scopes;
+  const result = createAgentKey({
+    owner,
+    name: name || `${t.label} key`,
+    scopes: finalScopes,
+    tier: t.id,
+    controllerAllowlist,
+    storePath,
+  });
+  return {
+    tier: t.id,
+    custody: t.custody,
+    canExecute: t.canExecute && finalScopes.includes(EXECUTE_SCOPE),
+    key: result.key, // show once
+    record: result.record,
+    nextSteps:
+      t.id === "local_signer"
+        ? [
+            "Store the API key for prepare/read calls only",
+            "Keep your wallet key on your device / hardware signer",
+            "Submit prepared payloads to your local signer — never upload the key here",
+          ]
+        : t.canExecute
+          ? [
+              "Store the API key securely",
+              "Live execute stays disabled until the separately installed operator enables it",
+              "This key can only act on YOUR owner wallet (custody firewall)",
+            ]
+          : [
+              "Store the API key securely",
+              "Use with getSigner({ identity: auth.identity, venue }) after authenticateAgentKey",
+            ],
+  };
+}
+
+export function onboardAuthenticate(rawKey, opts) {
+  return authenticateAgentKey(rawKey, opts);
+}
+
+export function onboardListKeys(owner, opts) {
+  return listAgentKeys(owner, opts);
+}
+
+export function onboardRevoke(opts) {
+  return revokeAgentKey(opts);
+}

package/src/oracle-env.mjs

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PUBLIC_DESKTOP = process.env.ORACLE_PUBLIC_DESKTOP === "1";
+
+export const ORACLE_CONFIG_DIR = PUBLIC_DESKTOP
+  ? (process.env.ORACLE_CONFIG_DIR || join(homedir(), ".config", "oracle"))
+  : join(homedir(), ".config", "oracle");
+// Legacy config dir from before the rename. Kept so existing installs keep
+// working; new installs only ever see ~/.config/oracle. The packaged public
+// desktop never consults it — it owns its own config root, so an operator/desk
+// install on the same machine cannot be inherited.
+export const LEGACY_CONFIG_DIR = PUBLIC_DESKTOP
+  ? ORACLE_CONFIG_DIR
+  : join(homedir(), ".config", "mad-desk");
+
+export function env(primary, legacy, fallback = "") {
+  const pv = process.env[primary];
+  if (pv != null && String(pv).trim() !== "") return pv;
+  const lv = legacy ? process.env[legacy] : undefined;
+  if (lv != null && String(lv).trim() !== "") return lv;
+  return fallback;
+}
+
+export function envFlag(primary, legacy, defaultValue = false) {
+  const fallback = defaultValue ? "1" : "";
+  return String(env(primary, legacy, fallback)).trim() === "1";
+}
+
+const DISABLE_WORDS = ["0", "false", "off", "no"];
+
+// Reading a flag that may default ON. Only an explicit disable word turns it
+// off, and an unset value keeps `defaultValue`.
+//
+// The old shape (`!== "0"`) inverted with a false default: ORACLE_ONBOARD_HTTP
+// defaults off, so a user writing `false` to keep it off actually ENABLED it,
+// because "false" is not "0". A disable word must never enable a surface.
+export function envEnabled(primary, legacy, defaultValue = true) {
+  const raw = String(env(primary, legacy, "")).trim().toLowerCase();
+  if (raw === "") return defaultValue;
+  return !DISABLE_WORDS.includes(raw);
+}
+
+export function csvEnv(primary, legacy) {
+  return String(env(primary, legacy, ""));
+}
+
+export function configPath(file, primary, legacy) {
+  const explicit = env(primary, legacy, "");
+  if (explicit) return explicit;
+  const oraclePath = join(ORACLE_CONFIG_DIR, file);
+  if (existsSync(oraclePath)) return oraclePath;
+  return join(LEGACY_CONFIG_DIR, file);
+}

package/src/package-manifest.mjs

@@ -0,0 +1,42 @@
+// Resolve this package's own root without assuming how deep the caller sits.
+//
+// Bin entry points run from `bin/` in the source tree and from `dist/bin/` in
+// the published bundle, so a hard-coded `path.join(__dirname, "..")` is correct
+// in exactly one layout. That is what broke 0.12.0: `oracle-data` and
+// `oracle init` both crashed at startup with ENOENT because they resolved
+// dist/package.json and dist/profiles/ instead of the real package root.
+//
+// Runtime assets (profiles/, skills/) live at the root in the source tree and
+// under dist/assets/ in the bundle, so asset lookup checks both.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function packageRoot(fromUrl) {
+  let dir = dirname(fileURLToPath(fromUrl));
+  for (let depth = 0; depth < 8; depth += 1) {
+    const manifest = join(dir, "package.json");
+    if (existsSync(manifest)) {
+      try {
+        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+        if (parsed && typeof parsed.version === "string") return dir;
+      } catch {
+        // an unreadable manifest is not the root we want; keep walking
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`oracle: could not resolve package root from ${fromUrl}`);
+}
+
+export function readPackageManifest(fromUrl) {
+  return JSON.parse(readFileSync(join(packageRoot(fromUrl), "package.json"), "utf8"));
+}
+
+export function packageAssetDir(name, fromUrl) {
+  const root = packageRoot(fromUrl);
+  const bundled = join(root, "dist", "assets", name);
+  return existsSync(bundled) ? bundled : join(root, name);
+}

package/src/plugins/agent-plugin-loader.mjs

@@ -0,0 +1,225 @@
+// Agent Plugins loader — implements the open standard at https://agent-plugins.org/.
+//
+// Oracle can load any conformant Agent Plugin from a directory, validate its
+// manifest against the canonical schema, and discover skills and MCP servers.
+// This makes Oracle an Agent Plugins-compatible client.
+//
+// Spec: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
+//
+// Custody: read-only. This module never signs, never broadcasts, never
+// touches key material. Skills and MCP servers are inert until invoked.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+
+const NAME_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\.[a-z0-9]+(?:[._-][a-z0-9]+)*)*$/;
+
+/**
+ * Validate a plugin.json manifest against the canonical schema.
+ * Returns { valid, errors[], warnings[] }.
+ * Non-fatal violations are warnings; fatal violations are errors.
+ */
+export function validateManifest(raw) {
+  const errors = [];
+  const warnings = [];
+
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push("plugin.json must be a JSON object");
+    return { valid: false, errors, warnings };
+  }
+
+  // $schema — required, must match canonical
+  if (raw.$schema !== SCHEMA_ID) {
+    if (!raw.$schema) {
+      errors.push("$schema is required — must be " + SCHEMA_ID);
+    } else {
+      errors.push(`unsupported $schema: ${raw.$schema} (expected ${SCHEMA_ID})`);
+    }
+  }
+
+  // name — required, kebab-case dot-separated
+  if (!raw.name || typeof raw.name !== "string") {
+    errors.push("name is required (string)");
+  } else if (!NAME_RE.test(raw.name)) {
+    errors.push(`name "${raw.name}" must be kebab-case dot-separated (e.g. deployment.tools)`);
+  }
+
+  // version — optional, warn if missing
+  if (raw.version === undefined || raw.version === null || raw.version === "") {
+    warnings.push("version is missing — semantic versioning recommended");
+  }
+
+  // description — optional
+  if (raw.description !== undefined && typeof raw.description !== "string") {
+    warnings.push("description must be a string");
+  }
+
+  // author — optional object
+  if (raw.author !== undefined) {
+    if (typeof raw.author !== "object" || Array.isArray(raw.author)) {
+      warnings.push("author must be an object with optional name, email, url");
+    }
+  }
+
+  // keywords — optional array
+  if (raw.keywords !== undefined) {
+    if (!Array.isArray(raw.keywords)) {
+      warnings.push("keywords must be an array");
+    }
+  }
+
+  // license — optional string
+  if (raw.license !== undefined && typeof raw.license !== "string") {
+    warnings.push("license must be a string");
+  }
+
+  // Extension fields (unknown top-level) — warn, don't error
+  const known = new Set(["$schema", "name", "version", "description", "author", "homepage", "repository", "license", "keywords", "extensions"]);
+  for (const key of Object.keys(raw)) {
+    if (!known.has(key)) {
+      warnings.push(`unknown field "${key}" — will be ignored (use extensions.<namespace> for client data)`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Discover skills in a plugin's skills/ directory.
+ * Each .md file is a skill. Subdirectories are supported for organization.
+ * Returns [{ name, path, content? }]
+ */
+export function discoverSkills(pluginRoot) {
+  const skillsDir = path.join(pluginRoot, "skills");
+  const skills = [];
+
+  if (!fs.existsSync(skillsDir) || !fs.statSync(skillsDir).isDirectory()) {
+    return skills;
+  }
+
+  function walk(dir, prefix = "") {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full, prefix ? `${prefix}/${entry.name}` : entry.name);
+      } else if (entry.name.endsWith(".md")) {
+        const skillName = prefix ? `${prefix}/${entry.name.replace(/\.md$/, "")}` : entry.name.replace(/\.md$/, "");
+        skills.push({
+          name: skillName,
+          path: full,
+          relativePath: path.relative(skillsDir, full),
+        });
+      }
+    }
+  }
+
+  walk(skillsDir);
+  return skills;
+}
+
+/**
+ * Discover MCP server configs in a plugin's mcp/ directory.
+ * Each .json file is an MCP server definition.
+ * Returns [{ name, path, config }]
+ */
+export function discoverMcpServers(pluginRoot) {
+  const mcpDir = path.join(pluginRoot, "mcp");
+  const servers = [];
+
+  if (!fs.existsSync(mcpDir) || !fs.statSync(mcpDir).isDirectory()) {
+    return servers;
+  }
+
+  for (const entry of fs.readdirSync(mcpDir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const full = path.join(mcpDir, entry.name);
+    try {
+      const config = JSON.parse(fs.readFileSync(full, "utf8"));
+      servers.push({
+        name: entry.name.replace(/\.json$/, ""),
+        path: full,
+        config,
+      });
+    } catch (e) {
+      // Invalid JSON in an MCP config — skip this server, don't fail the plugin
+      servers.push({
+        name: entry.name.replace(/\.json$/, ""),
+        path: full,
+        error: `invalid JSON: ${e.message}`,
+      });
+    }
+  }
+
+  return servers;
+}
+
+/**
+ * Load a complete Agent Plugin from a directory.
+ * Validates the manifest, discovers skills and MCP servers.
+ *
+ * Returns:
+ *   { ok: true, plugin: { name, version, root, manifest, skills[], mcpServers[], warnings[] } }
+ *   { ok: false, error, errors[] }
+ */
+export function loadPlugin(pluginRoot) {
+  const root = path.resolve(pluginRoot);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    return { ok: false, error: `plugin directory not found: ${root}` };
+  }
+
+  const manifestPath = path.join(root, "plugin.json");
+  if (!fs.existsSync(manifestPath)) {
+    return { ok: false, error: `missing plugin.json in ${root}` };
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (e) {
+    return { ok: false, error: `invalid plugin.json: ${e.message}` };
+  }
+
+  const validation = validateManifest(manifest);
+  if (!validation.valid) {
+    return { ok: false, error: "manifest validation failed", errors: validation.errors };
+  }
+
+  const skills = discoverSkills(root);
+  const mcpServers = discoverMcpServers(root);
+
+  return {
+    ok: true,
+    plugin: {
+      name: manifest.name,
+      version: manifest.version || "0.0.0",
+      description: manifest.description || "",
+      author: manifest.author || {},
+      license: manifest.license || "UNLICENSED",
+      root,
+      manifest,
+      skills,
+      mcpServers,
+      warnings: [...validation.warnings],
+    },
+  };
+}
+
+/**
+ * Scan a directory for installed plugins (directories containing plugin.json).
+ * Returns an array of loaded plugin descriptors.
+ */
+export function scanInstalledPlugins(pluginsDir) {
+  const plugins = [];
+  if (!fs.existsSync(pluginsDir)) return plugins;
+
+  for (const entry of fs.readdirSync(pluginsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const pluginRoot = path.join(pluginsDir, entry.name);
+    const result = loadPlugin(pluginRoot);
+    if (result.ok) plugins.push(result.plugin);
+  }
+
+  return plugins;
+}