kira-wallet 0.1.5 → 0.1.7

package/README.md

@@ -43,12 +43,11 @@ For a viewer without wallet or research actions, use `kira start --read-only`.
 Prefer an archive? [GitHub releases](https://github.com/realproject7/kira-wallet/releases/tag/v0.1.2)
 include the same package and its checksum.
 
-1. **Set up discovery.** In **Workspace settings**, connect an indexer for broad
-   ERC20 discovery. Public RPC alone has limited discovery; incomplete coverage
+1. **Review optional coverage.** Free research is enabled by default. In **Workspace settings**, connect Alchemy for broader
+   ERC20 discovery. Free token sources have limited coverage; incomplete coverage
    stays visible. An AI or browser wallet connection does not enable an indexer.
 2. **Add a watching wallet.** Paste a public address and give it a name. Add more
-   wallets whenever you need them. Without discovery, the form explicitly
-   offers limited research of native and Mint Club assets.
+   wallets whenever you need them. The form starts free research of native, common tokens and Mint Club assets, with keyless discovery on supported networks. First balances appear before detailed research finishes.
 3. **Connect your AI.** Install and sign in to the
    [Codex CLI](https://developers.openai.com/codex/cli) or
    [Claude Code](https://code.claude.com/docs/en/quickstart), then choose your
@@ -140,3 +139,14 @@ From source, use `node bin/kira.cjs` in place of `kira`.
 Original code and Kira character assets are available under the [MIT license](LICENSE).
 Third-party artwork and references retain their own terms; see
 [Third-party notices](THIRD_PARTY_NOTICES.md).
+
+### Token coverage and optional Alchemy setup
+
+Kira uses free public RPC with bounded fallback and checks a selected common-token
+list alongside native assets and Mint Club. Other ERC20 holdings can be missing.
+Incomplete results show recovery guidance on Home and the wallet page. Connect
+your own Alchemy account for broader discovery on supported networks, then
+refresh holdings. Public RPC remains the first choice for ordinary reads;
+Alchemy is a backup and supplies the dedicated token inventory API. See the
+[step-by-step Alchemy guide](docs/ALCHEMY_SETUP.md) and
+[RPC behavior](docs/FREE_RPC.md).

package/THIRD_PARTY_NOTICES.md

@@ -28,3 +28,9 @@ identifies the OWS wallet-creation integration without implying endorsement.
 Its retrieval date and source digest are in `site/assets/ows-artwork-source.json`.
 
 CASHCAT, BLAST and USDB artwork in the public reconstructed demo comes from lpTOKEN.fun token metadata, DEX Screener and CoinGecko. Token marks belong to their respective owners and identify the assets without implying affiliation or endorsement. The source URLs and chain-specific contract identities are recorded in `site/assets/token-artwork-sources.json`.
+
+The factual token inventory in `sources/known-tokens.json` includes selected
+chain/contract identities from Uniswap default-token-list at commit
+583cb696cc15778536fe0ddd416de5bd81be2023. The upstream references retain
+GPL-3.0 terms in `sources/TOKEN_LIST_LICENSE.txt`. Per-contract provenance is
+recorded in the catalog. No upstream executable code or artwork is included.

package/docs/AGENT_TOOLS.md

@@ -60,3 +60,16 @@ through the user's CLI; local storage does not imply an offline model.
 
 See [the conversation contract](ONBOARDING_CHAT_CONTRACT.md).
 The standalone stdio MCP adapter above remains read-only and separate.
+
+Native responses select the final Codex agent message. Older verified event
+streams without a phase use their last agent message. Commentary cannot become
+a tool request by concatenation. A mixed or malformed request gets one bounded
+correction; no tool executes from it and repeated malformed protocol fails
+without adding raw JSON to conversation history. Turn receipts expose only
+bounded tool names and completed/failed outcomes.
+
+Job reads include analysis phase, parent/continuation IDs and real progress
+events. Normalized chain discovery completeness is separate from a job's
+on-chain checkpoint status. Deferred candidates and pending networks are not
+failed reads or zero holdings. Historical observations cannot establish current
+execution, transfers or realized profit.

package/docs/ALCHEMY_SETUP.md

@@ -0,0 +1,95 @@
+# Connect Alchemy to Kira
+
+Kira works with free public RPC by default. It checks native assets, selected
+common token contracts and the Mint Club registry. Other ERC20 holdings may
+be missing. For broader token discovery, connect your own Alchemy account.
+Kira runs these requests locally and does not operate a hosted relay.
+
+## Create an Alchemy app
+
+1. Sign in to the [Alchemy dashboard](https://dashboard.alchemy.com/).
+   A new account may already have a default app. Use it, or open your team
+   menu, Team Overview, Apps, then Create new app.
+2. Name the app and select the mainnets you want to research. Check that the
+   app has Node API and Portfolio API access for those networks. Create it.
+3. Copy the app API key. The Endpoints tab shows its network URLs. Kira's
+   combined Alchemy setup needs the key, so you do not need to copy each URL.
+
+These steps follow Alchemy's [official API key guide](https://www.alchemy.com/docs/create-an-api-key),
+checked on October 9, 2026. Dashboard wording can change.
+
+## Connect the key locally
+
+Create a private directory and file in your terminal:
+
+```sh
+mkdir -p ~/.config/kira
+touch ~/.config/kira/alchemy.env
+chmod 600 ~/.config/kira/alchemy.env
+```
+
+Open the file in a local text editor. On macOS, you can use:
+
+```sh
+open -e ~/.config/kira/alchemy.env
+```
+
+Add this line, replacing `YOUR_KEY` inside the editor:
+
+```dotenv
+ALCHEMY_API_KEY=YOUR_KEY
+```
+
+Save the file, then run:
+
+```sh
+kira config import-env --file ~/.config/kira/alchemy.env
+```
+
+For a non-default workspace, supply its existing `--data-dir` before `config`.
+Kira stores the file reference. Credentials stay outside the browser, chat and
+published analysis. Do not commit this file to a repository. A process
+environment variable with the same name overrides the file value; check that
+if an old key remains active.
+
+## Check the connection and refresh
+
+Open Workspace settings, then Manage data connection. Select Alchemy and use
+"I added my key · check again". Save the connection. Finding the local key
+does not prove the account, API or network is working.
+
+For an existing wallet, choose Refresh this wallet's holdings or Refresh
+holdings on its page. A new analysis confirms access and coverage. Old saved
+analyses retain their original observations and warnings. Saving a connection
+does not register a wallet or start research automatically.
+
+## What uses the key
+
+Ordinary balances prefer public RPC. After two failed or unavailable public
+providers, Kira tries the configured custom backup within the read deadline.
+Advanced settings can choose custom first or require custom only. Existing
+explicit custom-only restrictions remain in force.
+
+Alchemy token discovery uses the key directly. Standard public RPC cannot
+enumerate arbitrary ERC20 holdings. Kira uses Alchemy's
+[Tokens By Wallet endpoint](https://www.alchemy.com/docs/data/portfolio-apis/portfolio-api-endpoints/portfolio-api-endpoints/get-tokens-by-address),
+then verifies discovered candidates with on-chain balance reads.
+
+## If tokens are still missing
+
+- **Local key unavailable:** confirm the file exists, its variable name matches
+  the connection settings, and you ran the import command in the right workspace.
+- **Discovery failed:** check the app's enabled APIs and networks and Alchemy's
+  usage dashboard. Correct access or limits, then retry holdings.
+- **Some balances could not be checked:** wait briefly and retry. Public and
+  custom providers both have outages and limits. Review Advanced read preferences
+  if a custom-only endpoint is unavailable.
+- **Unsupported network:** broader discovery is unavailable there. Connecting
+  Alchemy cannot cover every network or every token. Known-contract reads remain
+  useful, and missing holdings remain unknown.
+
+Alchemy has account allowances and throughput limits. Check the current
+[plans](https://www.alchemy.com/docs/reference/pricing-plans) and API availability
+before selecting a plan. Kira does not create an account, subscribe or upgrade
+it. Public-first balance reads reduce ordinary use of the key; discovery still
+consumes Alchemy allowance. No connection guarantees a complete token inventory.

package/docs/CLI.md

@@ -10,7 +10,7 @@ npm install -g kira-wallet
 kira setup
 ```
 
-The operator published npm version 0.1.4. Version 0.1.5 is a preparation candidate. GitHub v0.1.3 remains
+The operator published npm version 0.1.6. Version 0.1.7 is a preparation candidate. GitHub v0.1.3 remains
 a draft; the previous archive and checksum are available from the
 [0.1.2 GitHub release](https://github.com/realproject7/kira-wallet/releases/tag/v0.1.2).
 Registry publication remains an operator action. The code and original character assets use the MIT license.
@@ -46,9 +46,9 @@ Published 0.1.4 explains limited discovery before wallet registration and beside
 holdings. Missing coverage keeps the portfolio estimate partial. Existing snapshots require a holdings refresh after connecting
 an indexer; a price refresh does not discover missing tokens.
 
-Public RPC checks known assets and Mint Club. For broader ERC20 discovery,
-open Data provider connection, select Alchemy and follow its local key guide.
-The 0.1.5 candidate uses one save for Alchemy RPC and discovery; chain overrides
+Free research checks known assets, Mint Club and keyless token candidates on supported networks. Alchemy is optional. For broader ERC20 discovery,
+open Custom RPC & token coverage, select Alchemy and follow its local key guide.
+Published 0.1.5 uses one save for Alchemy RPC and discovery; chain overrides
 remain under Advanced. Never paste the key into the browser. `kira doctor`
 checks whether the configured key is available. Configuration alone does not
 prove complete coverage; inspect the recorded results and gaps.
@@ -68,7 +68,7 @@ authentication. Verified adapter versions are Codex 0.158.x and Claude Code
 verified. This is a native CLI connection, with no Kira account, API-key proxy or
 hosted portfolio backend.
 
-In the 0.1.5 candidate, setup opens the existing Account / Permissions / Ready
+From published 0.1.5, setup opens the existing Account / Permissions / Ready
 modal directly. Choose Codex or Claude, then Use default model or a readable
 model choice. Codex choices come from bounded native metadata; Claude offers
 Sonnet, Opus and Haiku aliases. A catalog is not proof of account access.
@@ -212,3 +212,12 @@ in session storage. It clears password fields immediately. Recovery keeps the
 original encryption passphrase. No signing, key export or account deletion
 endpoint is exposed. OWS absence does not block ordinary address or browser
 wallet onboarding.
+
+## Free reads and broader token coverage
+
+Public RPC is preferred for ordinary reads, including when a custom backup is
+configured. Advanced settings can select custom first or custom only. For CLI
+configuration, use `kira rpc set --chain 8453 --url-env KIRA_BASE_RPC --priority
+public_first`. Existing custom-only choices remain unchanged. Alchemy token
+discovery uses the configured key directly. See [free RPC behavior](FREE_RPC.md)
+and the [Alchemy setup guide](ALCHEMY_SETUP.md).

package/docs/FREE_RPC.md

@@ -0,0 +1,112 @@
+# Free RPC reads and token coverage
+
+Kira contacts public providers directly from the local research process. No
+Kira relay or shared credential is required. Free public services are best
+effort and can throttle requests or omit historical state.
+
+The reviewed default catalog adds alternatives on Ethereum, Base, BNB Chain,
+Polygon, Arbitrum and Optimism. PublicNode is the initial preference. Reserves
+are selected per chain rather than downloaded from an untrusted runtime list.
+The other supported networks retain their existing endpoints.
+
+## Request behavior
+
+- Chain identity is verified once per endpoint session and again after recovery.
+- One request runs per endpoint. Provider families share one queue and a
+  conservative two-second interval across chains. Two chain scans run at once.
+- A logical read has a twelve-second deadline including queues and verification.
+  The preferred HTTP attempt has four seconds, reserves at most two seconds.
+  Public attempts also have a total budget including verification and pacing,
+  leaving half the deadline for a configured personal backup.
+  Real fetches are aborted when a deadline expires. HTTP automatic retries are off.
+- At most four endpoint attempts run for a read. Public-first configurations
+  reserve an attempt for the personal backup after two public providers.
+- HTTP 429 and JSON-RPC backpressure cool an endpoint for at least sixty seconds.
+  Consecutive throttles increase this to at most thirty minutes. Retry-After
+  can extend the wait. Other transport failures have a short cooldown.
+- Unsupported methods have a method-specific penalty. Contract reverts do not
+  cool an otherwise healthy endpoint. Oversized Multicalls can split; outages and
+  throttling cannot create a burst of smaller calls.
+
+These are application limits, not promises about a provider's quota or uptime.
+Cooldown observations survive sequential research subprocesses in a bounded
+local cache. Custom endpoints and credentialed URLs are not written there.
+Status screens and onboarding checks do not probe RPC providers.
+
+## Snapshot consistency
+
+Each chain analysis records a block number and hash. Balance and contract reads
+keep that block. Before a fallback provider reads it, Kira verifies its header
+has the same hash. Every evidence read then uses an EIP-1898 block-hash selector
+with canonical checking. Providers that do not support it cannot supply that
+snapshot's evidence. Conflicting or unavailable evidence stays incomplete.
+No fallback silently substitutes `latest` for a fixed block.
+
+Identical concurrent reads share work. Successful fixed-block reads have a
+bounded cache keyed by chain, pinned hash, method and complete parameters,
+including the wallet address. Failed reads are evicted and never become zero.
+Wallet balances are not reused across wallets or new research processes.
+Registry identity caching remains separate from balances.
+
+## Default token inventory
+
+Native balances and the selected issuer/deployment-backed contracts in
+`sources/known-tokens.json` are checked before cold Mint Club enumeration.
+The catalog has 57 chain/contract identities on eight mainnets. Issuer references
+and selected Uniswap token-list records retain per-contract provenance. The
+upstream list commit and its license are bundled; no untrusted runtime list is
+loaded. Decimals and quantities come from on-chain reads. This remains a bounded
+inventory, not a claim to discover every wrapped or arbitrary token.
+
+Default research also uses Routescan without a key on individually verified
+Ethereum, Avalanche and Blast routes. Its documented free access is limited to
+two requests per second and 10,000 calls per day. Kira starts at most one call
+per second, reads at most 20 pages of 100 candidates per chain and spends at most
+25 seconds per enumeration. An isolated HTTP reader enforces a total deadline,
+including DNS and response bodies. Unsafe pagination, outages, malformed data
+and limits keep coverage partial. Provider quantities and prices never replace
+RPC-verified balances. Other Routescan chains are not presumed supported.
+Explicit keyless opt-outs and custom-only preferences remain respected.
+
+Initial reports check Base, Ethereum and Blast, up to 128 candidates per chain.
+Selected common contracts take priority. Remaining candidates and networks are
+explicitly pending. A durable background continuation scans every configured
+network, the full Mint Club registry and markets. Registry identity prefixes
+are saved incrementally; balances are never shared between wallets. Batches
+contain at most 128 reads, with splitting only for verified payload limits.
+New initial work takes priority over detailed research. Older same-wallet
+continuations cannot replace newer evidence.
+
+Public RPC cannot enumerate all arbitrary ERC20 contracts. Alchemy is an
+optional broader candidate source and backup RPC. Discovery calls made through
+the wallet engine have a 25-second initial or 60-second detailed per-chain
+budget. Native balances, free candidates and Mint Club research remain usable
+without it. Missing or deferred evidence stays unknown. Persistent coverage
+notices distinguish pending work from failed reads and offer retry or optional
+[Alchemy setup](ALCHEMY_SETUP.md).
+
+Keyless sources: [Routescan addresses](https://routescan.io/docs/api/addresses),
+[API access](https://routescan.io/docs/plans-and-limits/api-keys-and-pricing),
+[rate limits](https://routescan.io/docs/plans-and-limits/rate-limits).
+
+## Read preferences
+
+Public first is the default even when a custom connection is configured.
+Advanced settings provide custom first and custom only. Configurations without
+the new priority field use public first; an existing explicit custom-only choice
+continues to exclude public endpoints. RPC priority does not change the dedicated
+Alchemy discovery request.
+
+CLI example using an existing local endpoint variable:
+
+```sh
+kira rpc set --chain 8453 --url-env KIRA_BASE_RPC --priority public_first
+```
+
+Primary references: [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898),
+[PublicNode](https://www.publicnode.com/),
+[dRPC limits](https://drpc.org/docs/howitworks/ratelimiting),
+[1RPC networks](https://docs.1rpc.io/overview/supported-networks),
+[Circle contracts](https://developers.circle.com/stablecoins/usdc-contract-addresses),
+[Tether contracts](https://tether.to/en/supported-protocols/),
+[Uniswap Arbitrum deployments](https://developers.uniswap.org/docs/protocols/v3/deployments/v3-arbitrum-deployments).

package/docs/JOB_CONTRACT.md

@@ -121,3 +121,27 @@ its projection receipt without another provider request.
 
 The read-only stdio MCP adapter uses the same job and snapshot service. It has
 no mutation tools and requires separate operator-approved client setup.
+
+## Initial evidence and continuations in 0.1.7
+
+A valid wallet admission records its identity under a short registry lock.
+Idempotent replay repairs missing admission without undoing later name edits.
+New analysis jobs have `analysis_phase: baseline`. The first usable chain
+publishes an immutable `initial/` snapshot; the running job can reference it
+without claiming that the job is finished. The baseline publishes its own final
+partial snapshot and admits exactly one durable `enrichment` continuation with
+`parent_job_id`. The parent records `continuation_id`.
+
+Baseline work runs before enrichment. New baseline admission can preempt a
+running continuation. Saved chain evidence and verified registry identity
+prefixes survive; an interrupted registry batch is read again. A newer request
+for the same wallet supersedes older detailed work. Generation checks prevent
+an older result from replacing the latest pointer, while preserving historical
+evidence. Explicit cancellation of baseline prevents automatic continuation.
+
+`onchain_progress` events identify the actual operation, chain, checked count
+and known total. `chain.status: complete` concerns the on-chain checkpoint.
+Normalized wallet `complete` concerns general token discovery. Registry coverage,
+candidate failures, deferred candidates and pending RPC reads are separate facts.
+These flags do not prove exhaustive holdings. First results can be read while
+background work remains active.

package/docs/RELEASE.md

@@ -44,19 +44,20 @@ RPC failures show affected networks, retry guidance and a settings action.
 Failed candidate balance reads keep the saved result and valuation partial
 even when general token discovery succeeded.
 
-The next candidate is **0.1.5**. It opens the existing setup modal directly,
-adds readable Codex and Claude model choices, and exposes model and permission
-changes in Workspace settings. New setup recommends local history; upgrades
-preserve explicit opt-outs. Watching wallet methods use individual buttons.
-Data provider connection offers one atomic Alchemy RPC and discovery save,
-with custom overrides under Advanced. A missing key keeps prior settings.
-The wallet draft survives a connection detour. Connecting still requires an
-explicit holdings refresh before missing assets can appear in saved evidence.
-
-Version 0.1.5 requires independent review and operator registry publication.
-It is not yet available from the registry. Keep published 0.1.4 and earlier
-package bytes immutable. The showcase remains a separate deployment.
-See [discovery acceptance](KIRA_DISCOVERY_ACCEPTANCE.md).
+Published **0.1.5** opens the existing setup modal directly, adds Codex and
+Claude model choices, exposes model and permission changes in Workspace settings,
+and provides one Alchemy connection save. Its registry version was confirmed on
+2026-10-09. Published package bytes remain immutable.
+
+Published **0.1.6** adds a paced local RPC pool, core-chain public
+alternatives, public-first custom backup, fixed-block hash checks and a small
+known-token catalog. Home and wallet pages display incomplete coverage with an
+Alchemy setup action. The settings guide explains account setup, private local
+key import and an explicit holdings refresh. Missing or malformed discovery data
+cannot become a completed empty inventory.
+
+Version 0.1.6 is published and immutable. The showcase remains a separate deployment. See
+[free RPC behavior](FREE_RPC.md) and [Alchemy setup](ALCHEMY_SETUP.md).
 
 The operator published npm **0.1.2** on 2026-10-05. Its registry archive was
 downloaded and matched the reviewed GitHub archive above, including SHA-256,
@@ -78,7 +79,7 @@ The earlier unpublished 0.1.2 candidate is preserved in the ignored
 `dist/preserved-0.1.2-bad8f02/` directory. Use the current `dist/release.json`
 and its matching archive for publication; do not mix manifests from candidates.
 
-Keep GitHub v0.1.1, its tag and its released archive immutable. Versions 0.1.2, 0.1.3 and 0.1.4 are also published and immutable. Do not rebuild them from later documentation
+Keep GitHub v0.1.1, its tag and its released archive immutable. Versions 0.1.2, 0.1.3, 0.1.4, 0.1.5 and 0.1.6 are also published and immutable. Do not rebuild them from later documentation
 commits. Future package changes need a new version. Release preparation does not
 publish a GitHub release, merge PR 19, promote the website or publish to npm.
 Registry publication remains operator-only. The coding agent never publishes.
@@ -93,18 +94,38 @@ python3 scripts/prepare-release.py
 ```
 
 `prepare-release.py` scans the package boundary and creates
-`dist/kira-wallet-0.1.5.tgz`. The ignored `dist/release.json` records its source
+`dist/kira-wallet-0.1.7.tgz`. The ignored `dist/release.json` records its source
 commit, SHA-256 and member count. It never publishes. After reviewing that
 manifest, the operator's final command from the project root is:
 
 ```sh
-npm publish ./dist/kira-wallet-0.1.5.tgz --access public
+npm publish ./dist/kira-wallet-0.1.7.tgz --access public
 ```
 
 Use the operator's npm account and complete authentication or OTP personally.
 After publication, verify the registry archive and perform a fresh install
 before marking the new onboarding flow as available to npm users.
 
+## Proposed 0.1.7 behavior
+
+The candidate enables useful keyless research by default, expands the curated
+contract inventory and separates first recorded balances from exhaustive
+background research. Pending candidates, registry work and other networks stay
+visible. Current wallet evidence cannot roll back when an older continuation
+resumes. See [coverage and limits](FREE_RPC.md).
+
+Codex uses the final native message rather than joined commentary. Mixed tool
+protocol receives one bounded correction and is never rendered as a completed
+answer. Claude retains its restricted native adapter. Tool receipts contain
+names and outcomes, without raw arguments. Job checkpoints and normalized token
+discovery flags have separate meanings. Imported connection references reconcile
+with untouched settings fields while preserving edited drafts.
+
+The next archive is **0.1.7**, unpublished until the operator runs the command.
+Release readiness requires the repository suite, clean installation, source and
+history privacy scans, independent review and the frozen archive manifest.
+No live-extension or human passphrase acceptance is inferred from these checks.
+
 ## Verified 0.1.0 publication
 
 The operator published 0.1.0, verified on 2026-10-04. The registry archive has

package/kira_agent.py

@@ -42,7 +42,7 @@ SYSTEM = ('You are Kira, a careful wallet research partner. Answer in the langua
     'and full-balance output only when a validated quote exists. DEX pool TVL is not a sell quote. '
     'Missing execution quotes mean sale proceeds, fees, gas and price impact are unknown. '
     'For network questions, group by wallet and distinguish known assets from missing coverage. '
-    'A chain complete flag means general ERC20 discovery was checked; it does not prove native RPC reads succeeded. An indexer check and unavailable RPC are separate coverage facts, not conflicting records. '
+    'In normalized wallet facts, chain complete means general ERC20 discovery was checked. In job chains, status complete means an on-chain checkpoint finished. These are different stages. Neither flag alone proves all holdings are known. registry_complete and candidate_balance_errors describe separate read coverage. An indexer check and unavailable RPC are separate coverage facts, not conflicting records. '
     'An explicit chains.native_balance of zero is an observed native balance at its recorded time and block; null is unknown. Empty positive-holding inventories do not erase these observations. '
     'For saved-analysis comparisons, use snapshots_compare and read both snapshots. coverage_changed compares full evidence, including times and blocks, not just network status flags. price_references_changed may include changed reference values or times, not balances. '
     'Snapshot reads are normalized evidence. Compare chain observations and snapshot_price_references; never claim these are the only raw fields that changed. '
@@ -140,7 +140,7 @@ def wallet_facts(wallets, *, pool_budget=40_000):
     for wallet in wallets:
         row = pick(wallet,('address','tags','name','analysed_at','prices_at','balance_observed_at','known_value_usd','unpriced_count','status'))
         if not wallet.get('analysed_at'): row['known_value_usd']=None
-        row['chains'] = [pick(c,('id','name','environment','complete','rpc_available','native_symbol','native_balance','native_observed_at','native_block_number','registry_block_number')) for c in wallet['chains']]
+        row['chains'] = [pick(c,('id','name','environment','complete','rpc_available','native_symbol','native_balance','native_observed_at','native_block_number','registry_block_number','discovery_status','registry_complete','registry_phase','rpc_pending','candidate_balance_errors','candidate_deferred')) for c in wallet['chains']]
         row['snapshot_price_references'] = wallet.get('snapshot_price_references',{})
         row['assets'] = []
         for asset in wallet['assets']:
@@ -211,11 +211,14 @@ def run_native(config, prompt, cancel, *, timeout=180):
             else:
                 events = [json.loads(line) for line in output.splitlines() if line.strip()]
                 if not any(e.get('type') == 'turn.completed' for e in events): raise ValueError()
-                answer = '\n\n'.join(e['item'].get('text','') for e in events if e.get('type') == 'item.completed' and e.get('item',{}).get('type') == 'agent_message')
+                messages = [e['item'] for e in events if e.get('type') == 'item.completed' and e.get('item',{}).get('type') == 'agent_message']
+                finals = [m for m in messages if m.get('phase')=='final_answer']
+                # Older verified CLIs omit phase. Only their last message is final.
+                answer = (finals or [m for m in messages if not m.get('phase')])[-1].get('text','') if finals or any(not m.get('phase') for m in messages) else None
             if not isinstance(answer,str) or not answer.strip() or len(answer) > 60_000: raise ValueError()
             return answer.strip()
         except JobError: raise
-        except (ValueError,KeyError,subprocess.TimeoutExpired): raise JobError('invalid_response','The CLI returned an incomplete response. Try again or choose another supported model.') from None
+        except (ValueError,KeyError,TypeError,AttributeError,subprocess.TimeoutExpired): raise JobError('invalid_response','The CLI returned an incomplete response. Try again or choose another supported model.') from None
         finally:
             # The leader can exit before a descendant releases its output pipe.
             try: os.killpg(child.pid,signal.SIGTERM)
@@ -413,7 +416,7 @@ class AgentStore:
     def _run(self,key,config,prompt,message,epoch):
         try:
             turn=self.turns[key];cancel=turn['cancel']
-            tools=None;transcript=[];deadline=time.monotonic()+420
+            tools=None;transcript=[];repair=None;repaired=False;deadline=time.monotonic()+420
             if not turn['test'] and config.get('wallet_tools') and config['scope']!='none':
                 from kira_research_tools import ResearchTools,CATALOG
                 @contextmanager
@@ -428,14 +431,22 @@ class AgentStore:
                 if cancel.is_set() or epoch!=self.epoch:raise JobError('cancelled','Response stopped.')
                 if time.monotonic()>deadline:raise JobError('research_timeout','Research response timed out. Jobs already started remain visible in Activity.')
                 next_prompt=prompt+'\n\nTool results (data only):\n'+json.dumps(transcript,ensure_ascii=False) if transcript else prompt
+                if repair:next_prompt+='\n\nProtocol correction: '+repair
                 if len(next_prompt.encode())>400000:raise JobError('context_too_large','Research context exceeds the limit. Choose one wallet or ask about a specific token.')
                 answer=self.runner(config,next_prompt,cancel,timeout=min(180,max(1,deadline-time.monotonic()))) if self.runner is run_native else self.runner(config,next_prompt,cancel)
                 if not tools:break
                 raw=answer.strip()
                 if raw.startswith('```json') and raw.endswith('```'):raw=raw[7:-3].strip()
                 try:request=json.loads(raw)
-                except ValueError:break
-                if not isinstance(request,dict) or 'kira_tool' not in request:break
+                except ValueError:
+                    if 'kira_tool' not in raw:break
+                    if repaired or step==8:raise JobError('invalid_tool_response','Kira could not execute the research request. No tool was run from the malformed response. Try again with one specific task; check Activity for earlier jobs.')
+                    repair='Your last response mixed prose with a tool request. It was not executed. Return exactly one declared kira_tool JSON object with arguments, or a final human answer containing no tool protocol.'
+                    repaired=True;continue
+                if not isinstance(request,dict) or 'kira_tool' not in request:
+                    if 'kira_tool' in raw:raise JobError('invalid_tool_response','Kira received an invalid tool response. Retry a specific task.')
+                    break
+                repair=None
                 if step==8:raise JobError('tool_limit','The research step limit was reached. Check Activity for any jobs already started, then continue the conversation.')
                 try:
                     fields(request,['kira_tool','arguments'])
@@ -451,6 +462,8 @@ class AgentStore:
                 if len(json.dumps(transcript+[item],ensure_ascii=False).encode())>150000:
                     item['result']={'error':'The accumulated research context limit was reached. Use a specific token or finish with the evidence already received.'}
                 transcript.append(item)
+                with self.lock:
+                    self.turns[key].setdefault('tool_calls',[]).append({'name':request['kira_tool'],'status':'failed' if isinstance(result,dict) and result.get('error') else 'completed'})
                 with self.lock:self.tool_status='Kira is analysing the results…'
 
             with self.lock:
@@ -474,7 +487,7 @@ class AgentStore:
     def read(self,key):
         with self.lock:
             if key not in self.turns:raise JobError('not_found','This response is no longer available. Start a new conversation.')
-            return {**{k:self.turns[key][k] for k in ('id','state','error','answer','test','message','conversation_id')},'tool_status':self.tool_status if self.active==key else None}
+            return {**{k:self.turns[key][k] for k in ('id','state','error','answer','test','message','conversation_id')},'tool_calls':self.turns[key].get('tool_calls',[]),'tool_status':self.tool_status if self.active==key else None}
 
     def cancel(self,key):
         with self.lock:

package/kira_cli.py

@@ -172,7 +172,7 @@ def main():
     imp=configsub.add_parser('import-env');imp.add_argument('--file',required=True);imp.add_argument('--key-env',default='ALCHEMY_API_KEY')
     rpc=sub.add_parser('rpc');rpcsub=rpc.add_subparsers(dest='setting',required=True)
     rpcsub.add_parser('public')
-    custom=rpcsub.add_parser('set');custom.add_argument('--chain',type=int,required=True);custom.add_argument('--url-env',required=True);fallback=custom.add_mutually_exclusive_group();fallback.add_argument('--public-fallback',action='store_true',default=None);fallback.add_argument('--custom-only',dest='public_fallback',action='store_false')
+    custom=rpcsub.add_parser('set');custom.add_argument('--chain',type=int,required=True);custom.add_argument('--url-env',required=True);custom.add_argument('--priority',choices=['public_first','custom_first']);fallback=custom.add_mutually_exclusive_group();fallback.add_argument('--public-fallback',action='store_true',default=None);fallback.add_argument('--custom-only',dest='public_fallback',action='store_false')
     discovery=sub.add_parser('discovery');discovery.add_argument('provider',choices=['none','alchemy']);discovery.add_argument('--key-env',default='ALCHEMY_API_KEY');discovery.add_argument('--explorers',action='store_true')
     args=parser.parse_args();root=Path(args.data_dir).expanduser().resolve();os.environ['KIRA_DATA_DIR']=str(root)
     if sys.version_info<(3,11):raise ValueError('Python 3.11 or newer is required.')
@@ -235,10 +235,11 @@ def main():
                 from kira_config import provider_config
                 cfg=provider_config(cfg,'alchemy',args.key_env)
                 cfg['secret_env_file']=str(file);cfg['discovery']['explorers']=True
-            elif args.command=='discovery':cfg['discovery']={'provider':args.provider,'key_env':args.key_env,'explorers':args.explorers}
+            elif args.command=='discovery':cfg['discovery']={**cfg['discovery'],'provider':args.provider,'key_env':args.key_env,'explorers':args.explorers}
             elif args.setting=='public':cfg['rpc']['mode']='public'
             else:
                 cfg['rpc'].update(mode='custom')
+                if args.priority:cfg['rpc']['priority']=args.priority
                 if args.public_fallback is not None:cfg['rpc']['allow_public_fallback']=args.public_fallback
                 cfg['rpc']['chains'][str(args.chain)]={'url_env':args.url_env}
             # Validate before replacing the user's working configuration.

package/kira_config.py

@@ -16,8 +16,8 @@ def config_path():
     return Path(os.environ.get('KIRA_CONFIG', data_root()/'.kira.local.json')).expanduser()
 
 def default_config():
-    return {'schema_version':1,'rpc':{'mode':'public','allow_public_fallback':True,'chains':{}},
-            'discovery':{'provider':'none','key_env':'ALCHEMY_API_KEY','explorers':False}}
+    return {'schema_version':1,'rpc':{'mode':'public','allow_public_fallback':True,'priority':'public_first','chains':{}},
+            'discovery':{'provider':'none','key_env':'ALCHEMY_API_KEY','explorers':False,'public':True}}
 
 def provider_config(config, provider, key_env):
     """One settings transition. Preserve explicit fallback and custom overrides."""
@@ -44,7 +44,9 @@ def load_config():
         raise ValueError('Invalid RPC configuration.')
     if not isinstance(discovery,dict) or discovery.get('provider') not in ('none','alchemy') or type(discovery.get('explorers',False)) is not bool:
         raise ValueError('Invalid discovery configuration.')
-    if set(rpc)-{'mode','allow_public_fallback','chains'} or set(discovery)-{'provider','key_env','explorers'}:raise ValueError('Unknown provider configuration fields.')
+    if rpc.get('priority','public_first') not in ('public_first','custom_first'):raise ValueError('Invalid RPC priority.')
+    if type(discovery.get('public',True)) is not bool:raise ValueError('Invalid public discovery preference.')
+    if set(rpc)-{'mode','allow_public_fallback','priority','chains'} or set(discovery)-{'provider','key_env','explorers','public'}:raise ValueError('Unknown provider configuration fields.')
     if any(not isinstance(row,dict) or set(row)-{'url_env','alchemy_network'} for row in rpc['chains'].values()):raise ValueError('Unknown RPC endpoint fields.')
     for name in [discovery.get('key_env'),*[row.get('url_env') if isinstance(row,dict) else None for row in rpc['chains'].values()]]:
         if not isinstance(name,str) or not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*',name):raise ValueError('Credentials must use valid environment references.')
@@ -97,7 +99,8 @@ def endpoints(network,cfg=None):
         # New setups default to automatic fallback. Preserve an explicit existing
         # opt-out for operators who require custom providers only.
         if not rpc['allow_public_fallback']:return urls
-    urls.extend(network.get('public_rpc') or [])
+    public=network.get('public_rpc') or []
+    urls=public+urls if rpc.get('priority','public_first')=='public_first' else urls+public
     return list(dict.fromkeys(urls))
 
 def runtime():
@@ -105,7 +108,7 @@ def runtime():
     try: values=secret_values(cfg)
     except ValueError: values={}
     return {'endpoints':{str(n['chain_id']):endpoints(n,cfg) for n in networks},
-            'secrets':list(values.values()),'data_root':str(data_root())}
+            'secrets':list(values.values()),'data_root':str(data_root()),'health_file':str(data_root()/'cache/rpc-health.json')}
 
 if __name__=='__main__':
     # Internal child-process channel only. The user CLI never emits this payload.