@oracle-agent/oracle 0.24.5 → 0.24.7

package/README.md

@@ -46,12 +46,13 @@ 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 and 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`. Never paste a seed, key, passphrase, or signer
-token into Oracle chat or argv. The private `@oracle-agent/agent` admin package
-remains separate and is not included here.
+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.
 
 ---
 
@@ -97,14 +98,15 @@ decides what may even be asked.
 
 Three properties define it:
 
-1. **Self-custody by default.** The public package never accepts your private
-   key. It builds unsigned transactions and typed-data intents; your wallet
-   signs them.
+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.
 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 or smart account's job — this package never
-   signs, so it cannot be the thing that stops a transaction.
+   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.
 3. **Receipts or it didn't happen.** A claim without a transaction hash, a
    receipt, and a balance delta is not a result.
 
@@ -149,13 +151,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** (private, optional) — signing and broadcast live only in
-  separately operated owner infrastructure. It is not published on npm, not in
-  this artifact, and not available to holder installs.
+- **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.
 
-`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.
+`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.
 
 ## Coverage
 
@@ -301,13 +304,14 @@ npm test
 owner-local source lane.** The short version:
 
 - Reads and quotes need **no keys**.
-- The public package exposes no signer, key vault, or broadcast path.
-- User wallets authorize prepared actions outside the public data plane.
-- Owner-local signing exists only in separately operated private infrastructure;
-  it is not published on npm and is not a holder capability. When installed by
-  the owner, its generic signer exposes six policy-bounded surfaces: `hl`,
-  `poly`, `evm-swap`, `evm-bridge`, `btc`, and `sol`, with explicit caps and
-  fail-closed allowlists.
+- 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.
 
 ### Action vocabulary and execution planes
 
@@ -316,15 +320,17 @@ 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:** private owner-local infrastructure may sign on the same host with
-  the owner's key and policy. It is deployment-specific, unavailable to holder
-  installs, and must never expose a vault passphrase or signer credential to the
-  agent process.
+- **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 a trusted
-  owner-controlled direct-exec process is explicitly installed and armed.
+- Ordinary EVM preparation remains user-wallet signed unless the self-hoster has
+  initialized and unlocked their own local signer. No Oracle-hosted key exists.
 - `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.

package/SETUP.md

@@ -32,8 +32,29 @@ oracle sign lock
 Configure and HMAC-seal `~/.config/oracle/signer/signer-policy.json` with non-empty surface, action, chain,
 destination, selector, spender, and owner allowlists plus explicit value,
 approval, gas/fee, slippage, expiry, and RPC bounds. Empty allowlists fail
-closed. Exact one-use confirmation binds the final gas-populated artifact, which
-is checked again immediately before broadcast. Lock/disarm always wins.
+closed. Exact one-use confirmation binds the final gas-populated artifact. For
+reviewed EVM swap/bridge batches the TTY review is decoded from calldata and
+shows each approval's token/spender/amount, the reviewed provider, input/output
+tokens, amount in, minimum out, recipient, bridge destination chain/asset, and
+aggregate gas/value/maximum fee before asking for the digest. Caller summary
+metadata is never used for this review. The decoded minimum out must exactly
+match a fresh HMAC-authenticated auto-slippage quote bound to the full calldata;
+the caller's `slippageBps` label is not authority. Swap and allowance selectors
+known elsewhere in Oracle either use this strict decoded batch path or fail
+closed on generic/unversioned EVM surfaces. Generic approvals are refused rather
+than prompting without the exact token, spender, and amount. The artifact is checked again
+immediately before broadcast. Lock/disarm always wins.
+
+Autonomous mode additionally requires an Ed25519 trigger authority that is
+separate from the signer and its HMAC policy-integrity key. Provision only that
+authority's PEM public key as owner-only
+`~/.config/oracle/signer/trigger-attestation-authority.pub`; keep the private key
+outside the signer config and signer process. A trigger authority signs canonical
+JSON containing exactly `triggerId`, `issuedAtMs`, `expiresAtMs`, and the final
+`artifactDigest`, and sends `algorithm: "ed25519-canonical-json-v1"` plus the
+base64 signature. `ORACLE_AUTONOMOUS_TRADING=1` does not bypass this verification.
+The public `@oracle-agent/oracle/local-signer` export contains neither attestation
+minting nor filesystem key-reading helpers.
 
 Service templates ship under `public/service/` for Linux systemd, macOS
 launchd, and Windows Task Scheduler/PowerShell. Linux/macOS can retrieve the

package/dist/assets/profiles/protocol-builder/SOUL.md

@@ -7,7 +7,8 @@ adapters fail closed.
 
 ## What you own
 
-Chain-family token/NFT launch manifests, contract and program scaffolding,
+Chain-family token/NFT launch manifests, EVM contract scaffolding, Solana Rust/Anchor
+program bundles, Bitcoin Miniscript/Tapscript policy bundles,
 NFT/gacha mint mechanics, DEX/pool/launchpad design, security review, deploy and
 verify scripts, and **unsigned** deploy transactions. Research of existing
 protocols before cloning them.
@@ -50,6 +51,10 @@ what an attacker gains from each privileged function.
    `GUIDED_BUILD`, `RESEARCH_ONLY`, or `UNSUPPORTED`. RPC reachability is not deploy support.
 7. **One approval per side effect.** Deploy, metadata upload, mint, liquidity,
    authority transfer/revoke, reveal, and verification remain separate.
+8. **Bitcoin is not EVM.** Build UTXO policies, descriptors, scripts, and PSBT plans;
+   never call them contracts or imply arbitrary mutable state.
+9. **Solana identity stays public-only.** A program id and authority pubkey may enter
+   the builder; program keypairs, seeds, and private keys may not.
 
 ## Voice
 

package/dist/assets/profiles/protocol-builder/profile.json

@@ -4,7 +4,7 @@
   "label": "protocol builder",
   "role": "builder",
   "color": "#ff8c5a",
-  "description": "Builder lane for protocol, chain-family token/NFT collections, gacha, DEX, scanner, and mint-bot surfaces with unsigned deploy/mint preparation.",
+  "description": "Builder lane for EVM contracts, Solana programs, Bitcoin spending policies, chain-family token/NFT collections, gacha, DEX, scanner, and unsigned preparation.",
   "model": {
     "note": "Contract review is unforgiving and mistakes are permanent; wants the strongest reasoner available.",
     "suggested": "strong-reasoner"

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.
 
-**Current verified state as of 2026-08-13:** public npm `@oracle-agent/oracle@0.24.5`
+**Candidate release in this source tree:** public package `@oracle-agent/oracle@0.24.7`
 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-multichain-nft-launch/SKILL.md

@@ -47,8 +47,8 @@ three separate capabilities.
 | Family | Collection primitive | Default status | Required path |
 |---|---|---|---|
 | EVM | ERC-721, ERC-1155, ERC-2981 | `GUIDED_BUILD` until a gated Oracle collection template ships | Foundry tests, metadata/reveal tests, fork simulation, unsigned deploy |
-| Solana | Metaplex Core, Token Metadata collection, Candy Machine/drop programs | `GUIDED_BUILD` | Select one standard, validate authorities, simulate ordered unsigned transactions |
-| Bitcoin | Ordinals parent/child inscriptions and indexer collection manifests | `GUIDED_BUILD` for content and commit/reveal planning; adapter evidence required for `ADAPTER_READY` | Provenance manifest, parent link, UTXO/fee/reveal safety |
+| Solana | Metaplex Core, Token Metadata collection, Candy Machine/drop programs, custom Anchor programs | `GUIDED_BUILD` | Native Anchor scaffolds are available; select one standard, validate authorities, compile/test, and simulate ordered unsigned transactions |
+| Bitcoin | Ordinals parent/child inscriptions, indexer collection manifests, and Taproot policy components | `GUIDED_BUILD` for content, policy, and commit/reveal planning; adapter evidence required for `ADAPTER_READY` | Provenance manifest, parent link, descriptor/script review, UTXO/fee/reveal safety |
 | Cosmos | CW721 or chain-native NFT module | `RESEARCH_ONLY` by default | Verify chain-specific instantiate/execute messages and migration admin |
 | Sui | object-based collection and kiosk ecosystem | `RESEARCH_ONLY` by default | Move package, object capabilities, display metadata, testnet publish |
 | Aptos | Digital Asset standard or chain-native collection objects | `RESEARCH_ONLY` by default | Collection/mint refs, mutation permissions, testnet publish |

package/dist/assets/skills/oracle-multichain-token-launch/SKILL.md

@@ -43,8 +43,8 @@ simulation, fee estimate, and source/program verification path.
 | Family | Common standards | Default status | Required path |
 |---|---|---|---|
 | EVM | ERC-20 | `TEMPLATE_READY` only for Oracle `safe-erc20`; custom tax, mint, proxy, or hook designs are `GUIDED_BUILD` | Foundry gate, chain-id proof, unsigned deploy, source verification |
-| Solana | SPL Token, Token-2022 | `GUIDED_BUILD` | Select extensions explicitly, construct unsigned transactions, simulate, user wallet signs |
-| Bitcoin | Runes | `RESEARCH_ONLY` until an etch adapter is present | Commit/reveal plan, UTXO and fee model, exact terms review |
+| Solana | SPL Token, Token-2022, custom Anchor programs | `GUIDED_BUILD` | Native program scaffolds are available through `buildNative`; deployment still requires Anchor compile/test/simulation and unsigned transaction preparation |
+| Bitcoin | Runes and Taproot spending protocols | `GUIDED_BUILD` for `bitcoin-tapscript-vault`; Runes stay `RESEARCH_ONLY` until an etch adapter is present | Build reviewed policy/descriptor artifacts; compile and satisfy on regtest/signet; funding and PSBT preparation stay separate |
 | Cosmos | tokenfactory, CW20 | `RESEARCH_ONLY` by default | Resolve the chain's module or CosmWasm messages; EVM-enabled Cosmos chains use the EVM path only when verified |
 | Sui | Coin, regulated coin primitives | `RESEARCH_ONLY` by default | Move package, treasury capability model, devnet/testnet publish first |
 | Aptos | Coin, Fungible Asset | `RESEARCH_ONLY` by default | Move module/object model, upgrade policy, testnet publish first |

package/dist/assets/skills/oracle-protocol-builder/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: oracle-protocol-builder
-description: Use when the user wants Oracle to scaffold/deploy protocol templates. Gated Foundry templates; prepare-only deploy; not a firm audit.
+description: Use when the user wants Oracle to build EVM, Solana, or Bitcoin protocol artifacts. Chain-native gates; prepare-only; not a firm audit.
 ---
 
 # Protocol builder
 
-Oracle scaffolds and **prepares unsigned deploys**. The user signs. Custody boundary unchanged.
+Oracle scaffolds EVM contracts, Solana programs, and Bitcoin spending policies, then
+prepares unsigned side effects only after the matching chain gate is green. The user
+signs. Custody boundary unchanged.
 
 ## Security gate (v1)
 
@@ -30,6 +32,40 @@ data.call("protocol-templates", "prepareDeploy", {
 
 CLI: `npm run protocol:gate -- safe-erc20`
 
+## Native protocol builders
+
+```js
+// Native catalog
+data.call("protocol-templates", "listNative")
+
+// Solana Anchor program scaffold. programId is caller-generated public identity;
+// Oracle never accepts or emits its secret key.
+data.call("protocol-templates", "buildNative", {
+  templateId: "solana-safe-vault",
+  projectName: "treasury_vault",
+  network: "devnet",
+  programId,
+  authority,
+  unlockDelaySlots: 1200,
+})
+
+// Bitcoin Taproot policy scaffold. Returns descriptor/address/scripts, not a PSBT.
+data.call("protocol-templates", "buildNative", {
+  templateId: "bitcoin-tapscript-vault",
+  projectName: "cold_treasury",
+  network: "signet",
+  threshold: 2,
+  signerPubkeys,
+  recoveryPubkey,
+  recoveryDelayBlocks: 144,
+})
+```
+
+Both are `GUIDED_BUILD`, not `ADAPTER_READY`: the result is a hashed source/policy
+bundle. Solana still requires `anchor build`, `anchor test`, and cluster simulation.
+Bitcoin still requires descriptor compilation and spend-path tests on regtest or
+signet before funding. Neither operation deploys, funds, signs, or broadcasts.
+
 ## Shipped template: `safe-erc20`
 
 - Fixed supply, mint once in constructor (no hidden mint)
@@ -39,7 +75,7 @@ CLI: `npm run protocol:gate -- safe-erc20`
 
 ## Honesty
 
-**Reviewed templates + automated tests ≠ paid Solidity audit.**
+**Reviewed templates + automated tests ≠ a paid Solidity, Solana, or Bitcoin audit.**
 
 Docs and prepare envelopes always set `firmAudit: false` and carry the disclaimer.
 Mainnet TVL → independent firm audit.
@@ -48,11 +84,11 @@ Mainnet TVL → independent firm audit.
 
 1. Authority model  
 2. Threat model  
-3. Tests (Foundry)  
-4. Static analysis when available  
-5. Gate green  
-6. Prepare unsigned only  
-7. User signs + verify source  
+3. Chain-native tests (Foundry, Anchor, or regtest/signet policy vectors)
+4. Static analysis when available
+5. Gate green
+6. Prepare unsigned only
+7. User signs + verify source
 
 ## Refusal line