@oracle-agent/oracle 0.24.7 → 0.24.9

package/README.md

@@ -23,7 +23,7 @@ The private operator configuration, approval flow, wire units, and holder waiver
 [Hyperliquid builder code](docs/hyperliquid-builder-code.md).
 
 
-**Prepare-only multichain agent control plane.** Policy-bounded intents; your wallet signs.
+**Oracle is a self-custody multichain agent control plane.** It reads, quotes, prepares, arms, signs, and broadcasts under owner policy.
 
 Specialist agent profiles, real protocol intents, self-custody by default,
 receipts or it didn't happen.
@@ -45,14 +45,12 @@ Oracle can run standalone model auth directly with API keys or Claude, Codex,
 and Grok OAuth. OAuth credentials use the OS keychain when available, with a
 private `0600` local fallback when keychain storage is unavailable.
 
-Oracle is **prepare-only by default and on hosted surfaces**. A self-hoster may
-explicitly initialize the optional encrypted local vault. The private `@oracle-agent/agent` admin package
-remains separate and is not included here. The public package can then run a
-short-lived, loopback-only signer. Every normal action requires exact one-use
-human confirmation and policy checks; autonomous trading additionally requires
-`ORACLE_AUTONOMOUS_TRADING=1` and a short-lived Ed25519 attestation from a
-separately provisioned trigger authority (the signer holds only its public key).
-Never paste a seed, key, passphrase, or signer token into Oracle chat or argv.
+Wallet-sign and the local `oracle signer` are both first-class. The signer
+stays off until the owner initializes an encrypted vault and sealed policy.
+Every sign needs one-use confirmation. Autonomous trading additionally requires
+`ORACLE_AUTONOMOUS_TRADING=1`. Never paste a seed, key, passphrase, or signer
+token into Oracle chat or argv. The private `@oracle-agent/agent` package is
+not included here.
 
 ---
 
@@ -98,17 +96,17 @@ decides what may even be asked.
 
 Three properties define it:
 
-1. **Self-custody by default.** Hosted/public-plane code never accepts your
-   private key. Oracle builds unsigned transactions and typed-data intents; your
-   wallet signs them. A self-hoster may separately import their key into the
-   encrypted local vault; it never reaches the model or public HTTP process.
+1. **Self-custody by default.** Hosted and default Oracle never accept your
+   private key. They build unsigned transactions and typed-data intents; your
+   wallet signs them. An explicit self-host setup may import a key into the
+   encrypted local vault and sign through `oracle signer`.
 2. **Bound grants.** A grant is a signed, scoped, expiring permission: max
    value, chain, venue, destination allowlist, TTL. Oracle canonicalizes it,
    renders it for review, and refuses to prepare anything outside it. Runtime
-   enforcement is the wallet's, smart account's, or self-hosted local signer's
-   job. Every local signer action still requires the exact policy-bound artifact.
+   enforcement is the wallet's or smart account's job, or the optional local
+   signer's sealed policy when that signer is explicitly enabled.
 3. **Receipts or it didn't happen.** A claim without a transaction hash, a
-   receipt, and a balance delta is not a result.
+   receipt is not a result. If a transport cannot verify a balance delta, the receipt must say `balanceDeltaVerified: false`.
 
 Default posture is `DISARMED`.
 
@@ -123,7 +121,7 @@ loop.
 | Authority | prompt-level "be careful" | signed grant: chain, spend, targets, TTL — enforced by your wallet, not by us |
 | Destinations | whatever the model emits | reviewed per-chain allowlist, fail-closed |
 | Slippage | fixed % | live guard recomputed per leg, hard 100 bps cap |
-| Proof | model says "done" | hash + verified successful on-chain receipt + expected balance delta or it failed |
+| Proof | model says "done" | hash + verified successful on-chain receipt, with `balanceDeltaVerified` true only when snapshots prove the expected delta |
 | Surface | swap only | swaps, bridges, perps, vaults, yield, NFTs, intents |
 
 ## Architecture
@@ -151,14 +149,14 @@ Three planes, and the boundary between them is mechanically enforced:
 - **Policy plane** (public) — destination allowlists, slippage guards, route and
   vault attestations, grant schema. Holds no keys; constrains what a signer may
   be asked to do.
-- **Exec plane** (self-hosted, optional) — the public package can run an
-  encrypted, short-lived loopback signer for the user's own key. It is isolated
-  from the public HTTP/data plane and requires exact confirmation plus policy
-  checks. The broader Admin executor remains a separate private package.
+- **Exec plane** (self-hosted, optional) — signing and broadcast live only in an
+  explicitly initialized loopback local signer using the user's keys, or in
+  separately operated owner infrastructure. Hosted/default Oracle has no active
+  signer. The local-signer module ships inert and grants no holder privilege.
 
-`test/custody-boundary.test.mjs` walks the public-plane import graph and fails if
-it reaches local vault material, private Admin modules, or a house signer. The
-split is a test, not a promise.
+`test/custody-boundary.test.mjs` walks the import graph and fails if any public
+module reaches wallet key material or a house signer. The split is a test, not a
+promise.
 
 ## Coverage
 
@@ -304,14 +302,15 @@ npm test
 owner-local source lane.** The short version:
 
 - Reads and quotes need **no keys**.
-- Hosted public surfaces expose no signer, key vault, or house-key broadcast path.
-- The self-hosted public package includes an optional encrypted, loopback-only
-  local signer for the user's own key. Once its vault exists, user-initiated
-  swaps and bridges are armed equally; exact one-use confirmation, sealed policy
-  rails, caps, and non-empty allowlists still gate every broadcast.
-- User wallets may instead authorize prepared transaction sequences directly.
-- The separate private Admin package adds operator-only venue surfaces and is
-  not published on npm.
+- Hosted/default Oracle exposes no active signer, key vault, or broadcast path.
+- User wallets authorize prepared actions outside the public data plane.
+- The npm package includes an optional self-hosted loopback signer for the user's
+  own keys. It stays inert until local initialization and sealed policy setup.
+  Private Administrator modules remain separate and are not published on npm.
+- The documented `oracle signer` path permits built-in bounded native EVM
+  transfers, recognized approvals, decoded EVM swaps and bridges, EVM NFT mint
+  envelopes, Bitcoin PSBTs, and Solana messages under the user's encrypted local
+  vault and sealed policy. `hl` and `poly` are not public local-signer families.
 
 ### Action vocabulary and execution planes
 
@@ -320,17 +319,16 @@ Oracle keeps capability and authorization separate:
 - Public Oracle reads, quotes, simulates, and prepares unsigned artifacts.
 - **Path A:** owner/main, browser, smart-account, hardware, or protocol-native
   wallets sign the prepared artifact. This is the default self-custody path.
-- **Path B:** a self-hoster may initialize the public package's encrypted local
-  vault and short-lived loopback signer. Key presence arms both swaps and bridges;
-  policy decides what is allowed, and exact human confirmation remains mandatory.
-- **Path C:** the separate private Admin package may sign additional bounded
-  venue actions on the owner's machine. It must never expose a vault passphrase
-  or signer credential to the model process.
-- The generic unattended signer exposes six bounded surfaces: `hl`, `poly`,
-  `evm-swap`, `evm-bridge`, `btc`, `sol`. Each surface decodes its own
-  envelope, enforces its caps, and refuses while its allowlists are empty.
-- Ordinary EVM preparation remains user-wallet signed unless the self-hoster has
-  initialized and unlocked their own local signer. No Oracle-hosted key exists.
+- **Path B:** the optional public local signer may sign on the same host after
+  explicit init, sealed policy, and loopback start. Private Administrator
+  modules remain unpublished and are not a holder install.
+- The optional local signer decodes and binds bounded native EVM transfers,
+  recognized approvals, strict EVM swap/bridge calldata, EVM NFT mint envelopes,
+  Bitcoin PSBTs, and Solana messages. It refuses while required allowlists,
+  local keys, RPC URLs, simulation, signed-byte verification, receipt binding,
+  or ledger accounting are missing.
+- Ordinary EVM preparation remains user-wallet signed unless a trusted
+  owner-controlled direct-exec process is explicitly installed and armed.
 - `ORACLE_AUTONOMOUS_TRADING=1` is direct execution for trusted owner-controlled
   local code only. It is never model/agent authority and should not be framed as
   equivalent to the `oracle-signer` agent-process path.
@@ -518,6 +516,10 @@ overall winner so a quote-only mid is never presented as actionable.
 
 ## Examples
 
+These run from a **repo clone**, not from the installed npm package: they import
+`../src/` directly, and the published tarball ships the bundled `dist/` instead of
+`src/`. Clone the repo, `npm install`, then:
+
 ```bash
 node examples/add-a-chain.mjs             # register an unseen chain, no code
 node examples/research-a-token.mjs        # honest token research on live data
@@ -535,9 +537,11 @@ oracle-data-mcp
 
 ## Security
 
-- Oracle never receives private keys.
+- Hosted/default Oracle never receives private keys. An explicit self-host
+  import writes only to the local encrypted vault.
 - The router can propose, simulate, explain, and draft. It cannot authorize.
-- Public modules may not import signer or executor code (enforced by test).
+- Public default modules may not import house-signer or executor code
+  (enforced by test). The optional `./local-signer` export is the self-host path.
 - Destination allowlists are per-chain and fail-closed: an empty allowlist
   refuses everything rather than allowing everything.
 - Report vulnerabilities per [SECURITY.md](SECURITY.md). Please do not open a

package/SECURITY.md

@@ -102,7 +102,7 @@ still apply after the public boundary hardening:
    caller-supplied public facts; `recordAudit()` is a process-local, best-effort
    file helper. Neither authorizes execution or proves settlement. Report
    success only after independently verifying the successful chain receipt,
-   expected destination/events, and expected balance delta.
+   expected destination/events, and `balanceDeltaVerified` when balance snapshots are available.
 7. **Repository-host controls are not the custody boundary.** Dependabot alerts
    may be enabled independently, while branch protection, CodeQL, and hosted
    secret scanning depend on repository visibility and account tier. Verify the

package/SETUP.md

@@ -1,10 +1,9 @@
 # Oracle setup
 
-Oracle's public CLI is prepare-only unless a user deliberately enables its
-self-hosted signer. The optional signer uses an AES-256-GCM/scrypt encrypted
-vault on the user's machine, listens only on loopback, and signs only exact
-confirmed artifacts within configured policy. Hosted Oracle remains
-prepare-only. The private `@oracle-agent/agent` admin package is not imported.
+Oracle's public CLI reads, prepares, arms, signs, and broadcasts under owner
+policy. Signing is the user wallet or `oracle signer` after an encrypted local
+vault and sealed policy exist. Hosted web stays keyless. The private
+`@oracle-agent/agent` package is not imported.
 
 ## Requirements
 
@@ -255,9 +254,11 @@ const prepared = await data.call("hl-perps", "prepareOrder", {
 ```
 
 Review the chain, destination, calldata or typed data, amount, minimum output,
-expiry, approvals, and fees in the user's wallet. Oracle's public package stops
-before signing. Report success only after a real transaction hash, successful
-receipt, and expected balance or state change.
+expiry, approvals, and fees. Hosted/default Oracle stops before signing and
+hands the artifact to a user-controlled wallet. A self-hoster who initialized
+`oracle signer` may sign that same reviewed artifact locally. Report success
+only after a real transaction hash, successful receipt, and expected balance or
+state change.
 
 ## Locals Only fee waiver
 
@@ -292,8 +293,9 @@ A clean standalone install can legitimately show warnings for:
 - `agent_runtime` when optional Hermes is not installed;
 - `hermes_lanes` before optional `oracle init --apply`.
 
-A Node-version failure is blocking. Signing warnings are irrelevant to the
-public package because signing is not installed there.
+A Node-version failure is blocking. Signing warnings from `oracle doctor`
+refer to signer setup, not hosted web. Hosted web never signs.
+`oracle sign doctor` and `oracle signer` are the local sign path.
 
 ## Upgrade
 
@@ -357,9 +359,10 @@ the API is live based on the static site or source code alone.
 
 ### A prepared action cannot be signed
 
-That is expected in the public package. Hand the reviewed artifact to a
-user-controlled wallet. Do not install or request private owner infrastructure
-as a workaround.
+Hosted/default Oracle is prepare-only: hand the reviewed artifact to a
+user-controlled wallet. Do not install private Administrator infrastructure
+as a workaround. A self-hoster who already initialized `oracle sign` /
+`oracle signer` signs locally under that policy.
 
 ## References
 

package/dist/assets/profiles/_template/SOUL.md

@@ -22,8 +22,8 @@ Keep these. They are the desk's invariants, not suggestions:
 1. **You do not sign.** Transactions are prepared for the user's wallet.
 2. **A grant is authorization; your reasoning is not.** Outside the grant's chain,
    venue, destination, spend cap, or TTL → refuse, and say which bound broke.
-3. **Receipts or it didn't happen.** No hash, no receipt, no balance delta → it
-   did not succeed.
+3. **Receipts or it didn't happen.** No hash or receipt → it did not succeed.
+   Report balance delta only when verified.
 4. **Never invent chain facts.** Not from a live read → `unknown`.
 
 Then add rules specific to your venue.

package/dist/assets/profiles/oracle/SOUL.md

@@ -58,14 +58,12 @@ the data plane). If it stays ambiguous, ask. Do not guess a chain.
    margin call for different decisions. If `rankedOn` is `gross`, gas was NOT
    accounted for — say so. See the `oracle-best-execution` skill.
 
-1. **The public package never signs.** It reads, simulates, and prepares wallet-signable
-   artifacts. It does not import keys, expose a signer or vault, arm an executor, or
-   broadcast transactions. A separately provisioned owner-controlled executor may
-   consume a prepared artifact, but it is outside this package. Never describe one as
-   available without live verification and explicit owner authorization.
-   `watch`, `watch this`, and `ping me` always mean `actionMode: alert_only`.
-   An explicit `arm` requests one exact, bounded action for wallet or external-executor
-   confirmation. It does not arm anything inside this package.
+1. **Sign only through a confirmed path.** Reads and prepares are always
+   available. Signing and broadcast use the user wallet or `oracle signer`
+   after vault init, sealed policy, and one-use confirmation. Verify signer
+   status before claiming it is live. Never paste a key. `watch`, `watch this`,
+   and `ping me` always mean `actionMode: alert_only`. An explicit `arm`
+   requests one exact bounded action for confirmation. Lanes start DISARMED.
 
    **Autonomous trading is the one opt-in.** A trigger that fires a trade with
    nobody watching requires `ORACLE_AUTONOMOUS_TRADING=1`. Until then such an
@@ -80,11 +78,11 @@ the data plane). If it stays ambiguous, ask. Do not guess a chain.
    not. Resolve exact token/chain, sell-sim when possible, quote net of gas,
    cap spend/fees, and prepare a user-signed ticket.
 5. **Terminal and messaging are transports, not different authority models.**
-   Bare `oracle` launches this same prepare-only profile. Terminal, messaging, and
-   installed MCP targets can read, simulate, and prepare, but none can discover or
-   invoke a signer through this package. A separate executor keeps its own owner
-   authentication, grants, allowlists, caps, simulations, and receipt verification.
-   Changing `/model` never changes those walls.
+   Bare `oracle` launches this same default prepare-only profile. Terminal,
+   messaging, and installed MCP targets can read, simulate, and prepare.
+   Signing is a separate explicit `oracle signer` path, not something this
+   profile can discover or invoke on its own. Changing `/model` never changes
+   those walls.
 6. **A grant is authorization; your reasoning is not.** If an action falls
    outside the active grant — chain, venue, destination, spend cap, TTL — refuse
    and say which bound it broke.

package/dist/assets/profiles/profile.schema.json

@@ -77,7 +77,7 @@
         },
         "signing": {
           "enum": ["none", "user-wallet"],
-          "description": "Never 'house'. Oracle holds no keys."
+          "description": "Lane default is none or user-wallet. Local signing is oracle signer, not a lane house key."
         },
         "rationale": {
           "type": "string",

package/dist/assets/profiles/robinhood-agent/SOUL.md

@@ -103,11 +103,11 @@ marketplace sell are different paths with different approvals.
 2. **Never size against stale or virtual reserves.**
 3. **A fuzzy ticker match is not confirmation.** Surface the CA.
 4. **The public lane does not sign.** Ordinary swaps are prepared for the user's
-   wallet. The generic unattended signer exposes six bounded surfaces (`hl`, `poly`,
-   `evm-swap`, `evm-bridge`, `btc`, `sol`), each fail-closed on its own policy. A
-   separately installed, owner-gated EVM executor may handle one exact bounded
-   Robinhood Chain action after explicit `arm`. Verify that executor before claiming
-   it is available.
+   wallet. The optional self-hosted local signer accepts bounded native EVM
+   transfers and recognized approvals, but rejects swap and bridge calldata until
+   its economics are decoded. A separately installed, owner-gated EVM executor may
+   handle one exact bounded Robinhood Chain action after explicit `arm`. Verify that
+   executor before claiming it is available.
 5. **Watch is alert-only.** `watch`, `watch this`, and `ping me` persist as
    `active: true, actionMode: alert_only`. Only explicit `arm` can produce
    `actionMode: execute`; never infer execution from a watch or legacy `status: armed`.

package/dist/assets/skills/multi-venue-prepare-only-ranking/SKILL.md

@@ -8,11 +8,11 @@ description: Use when building prepare-only cross-venue rank surfaces.
 
 # Multi-venue prepare-only ranking
 
-Class of product: compare quotes across venues, rank honestly, prepare unsigned artifacts only. Worked repo: `/home/demi/work/oracle-equities` (298 offline tests as of 2026-08-04).
+Class of product: compare quotes across venues, rank honestly, prepare unsigned artifacts only. Reference implementation passed 298 offline tests as of 2026-08-04.
 
 ## Product law
 
-- Prepare-only. No keys, no sign, no broadcast in the public package.
+- This ranking workflow prepares only. Sign and broadcast with the user wallet or `oracle signer`.
 - Rank on **net received after fees/gas/impact** when costs are known; otherwise `rankedOn: "gross"` and say so.
 - **Unknown is not zero.** Missing gas/impact/funding => field `null` and `costAccounted: false`.
 - **Adapters report truth. Liveness filters.** Never "repair" crossed books or drop dormant venues inside an adapter.

package/dist/assets/skills/oracle-action-semantics/SKILL.md

@@ -7,10 +7,10 @@ description: Use for watch, ping, prepare, arm, sign, send, or execution-capabil
 
 Keep these planes distinct:
 
-1. **Public prepare plane**: reads, quotes, simulates, and prepares unsigned artifacts. It never signs or broadcasts.
-2. **Generic Oracle signer**: the unattended daemon exposes six *bounded* surfaces — `hl`, `poly`, `evm-swap`, `evm-bridge`, `btc`, `sol`. Bounded is not generic chain authority: each surface decodes and validates its own envelope shape and refuses while its allowlists are empty. Enablement is never authority; every signature still needs one exact owner-confirmed grant.
-3. **User-wallet EVM**: ordinary EVM preparations require the user's wallet signature.
-4. **Optional bounded EVM execution**: a deployment may expose a separate same-host, owner-gated EVM executor such as MAD. Verify its status and policy before saying it is available. Never infer it from the public package or the generic signer.
+1. **Public prepare plane**: reads, quotes, simulates, and prepares unsigned artifacts. Signing and broadcast happen through the wallet, `oracle signer`, or a verified execution lane.
+2. **Generic Oracle signer**: the documented unattended daemon exposes built-in public surfaces: `evm`, `evm-swap`, `evm-bridge`, `evm-nft`, `btc`, and `sol`. Bounded is not generic chain authority: each surface decodes and validates its envelope shape and refuses while allowlists, local keys, RPC URLs, simulation, signed-byte verification, receipt binding, or ledger accounting are missing. Enablement is never authority; every signature still needs one exact owner-confirmed grant.
+3. **User-wallet execution**: ordinary preparations can still be signed by the user's wallet instead of the local signer.
+4. **Optional extra execution**: a deployment may expose a separate same-host, owner-gated executor such as MAD. Verify its status and policy before saying it is available. Never infer extra `hl`/`poly` authority from the public package or the generic signer.
 
 Do not turn a deployment fact into a universal claim. If no bounded EVM executor is installed or healthy, say the current deployment cannot execute EVM. Do not say Oracle can never execute EVM.
 
@@ -35,6 +35,6 @@ Report each state separately:
 - `signingReady`
 - `broadcastReady`
 
-A quote is not a preparation. A preparation is not a signature. A signature is not a broadcast. A broadcast is not mined execution. Claim success only after a transaction hash, successful receipt, and expected balance delta.
+A quote is not a preparation. A preparation is not a signature. A signature is not a broadcast. A broadcast is not mined execution. Claim success only after a transaction hash, successful receipt. Report balance delta only when `balanceDeltaVerified` is true.
 
 ERC-20 approval is a separate transaction. Use an exact bounded amount unless the user explicitly authorizes another cap. Never silently create an unlimited approval.

package/dist/assets/skills/oracle-chat/SKILL.md

@@ -26,25 +26,25 @@ You are **oracle** — one lowercase persona. Models can change underneath via `
    - `ORACLE_ACTIVE_AGENT`
 2. If they name a chain ("build on hyperliquid"), run or instruct:
    `oracle chain use hyperliquid`
-3. Never claim signing or broadcast happened. This public package cannot perform either.
-4. Every model and transport remains read/prepare-only.
+3. Never claim signing or broadcast happened unless the owner used the explicit
+   self-host `oracle signer` path and you have a receipt.
+4. Default chat, MCP, and hosted transports stay read/prepare-only. Do not
+   invoke `oracle signer` from this profile.
 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.
+`oracle` in a TTY starts the native standalone Oracle runtime by default. Hermes is an explicit backend choice, not the automatic TTY path. Telegram can be wired to the same Oracle profile, but the terminal interface may use native model auth, local config, and the standalone loop unless `ORACLE_CHAT_BACKEND=hermes` is set.
 
 - Terminal and messaging can both read, simulate, and prepare unsigned actions.
 - For an explicit trade instruction, enforce the active-chain policy, prepare
   the exact unsigned artifact, and present it for wallet review.
-- Do not discover or invoke a signer, vault, control MCP, or broadcaster.
+- Default chat does not discover or invoke a signer, vault, control MCP, or broadcaster.
 - `arm` means prepare the exact bounded action for external wallet review. It
-  does not enable execution inside this package.
+  does not enable execution inside this default profile.
 - A tool refusal is a real policy wall. Report the exact refusal instead of
   bypassing it.
-- Never claim a trade executed from this package.
+- Never claim a trade executed from this default profile.
 
 ## shell helpers
 ```bash

package/dist/assets/skills/oracle-desk-product/SKILL.md

@@ -97,7 +97,7 @@ does not prove npm users receive it. A locally hosted model/data/policy loop doe
 a bundled signer. A merged feature is not public until the npm artifact containing it is
 published and inspected.
 
-**Candidate release in this source tree:** public package `@oracle-agent/oracle@0.24.7`
+**Candidate release in this source tree:** public package `@oracle-agent/oracle@0.24.9`
 ships the optional encrypted local vault + short-lived loopback signer. Hosted/default
 Oracle stays prepare-only. Self-host after `oracle sign init|import` is **auto-armed**
 for user-initiated actions. Public still charges the disclosed fee card; Administrator

package/dist/assets/skills/oracle-receipts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oracle-receipts
-description: Use whenever reporting the outcome of any on-chain action. Enforces that a claim of success carries a hash, a receipt, and a balance delta.
+description: Use whenever reporting the outcome of any on-chain action. Enforces that a claim of success carries a hash and a receipt, and reports balance delta only when verified.
 ---
 
 # Receipts or it didn't happen
@@ -16,7 +16,7 @@ A money-moving action is **complete** only when you can show:
 1. **transaction hash** — the real one, from the broadcast response
 2. **receipt status** — `1`. A receipt with status `0` is a *failed* transaction
    that still consumed gas; that is not success
-3. **balance delta** — the output token balance actually changed, read back after
+3. **balance delta when verified** — the output token balance actually changed, read back after
    the receipt
 4. **the log** proving the intended event fired (`Swap`, `Transfer` to the right
    recipient, `OrderFilled`)