@oracle-agent/oracle 0.14.0 → 0.15.0

package/src/onboarding/harness-configs.mjs

@@ -1,102 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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

@@ -1,139 +0,0 @@
-// 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

@@ -1,55 +0,0 @@
-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

@@ -1,42 +0,0 @@
-// 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

@@ -1,225 +0,0 @@
-// 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;
-}